Comment parcourir les tickets Zendesk avec pagination : Un guide complet pour les développeurs

Si vous créez des intégrations avec Zendesk, vous découvrirez rapidement que l'API ne vous remet pas l'intégralité de votre base de données de tickets en une seule fois. Au lieu de cela, elle sert les données en morceaux gérables grâce à un mécanisme appelé pagination. Ceci est intentionnel. La pagination maintient l'API réactive et empêche les délais d'attente lorsque vous traitez des milliers (ou des millions) de tickets de support.

Mais voici où cela devient intéressant. Zendesk offre deux manières différentes de paginer vos données : la pagination par curseur et la pagination par décalage. L'une est rapide, moderne et pratiquement illimitée. L'autre est limitée à 10 000 enregistrements et traîne des bagages des anciennes conceptions d'API. Depuis août 2023, Zendesk pousse les développeurs vers la pagination par curseur en appliquant des limites strictes à la méthode de décalage.

Dans ce guide, nous allons passer en revue les deux approches de pagination avec des exemples de code fonctionnels. Vous apprendrez quand utiliser chaque méthode, comment gérer les cas extrêmes et quels pièges éviter. Et si vous pensez qu'il doit y avoir un moyen plus simple d'automatiser les flux de travail Zendesk sans écrire vous-même la logique de pagination, nous aborderons également ce point.

Comprendre la pagination de l'API Zendesk

Avant de plonger dans le code, clarifions pourquoi la pagination existe et comment elle fonctionne à un niveau élevé.

L'API Zendesk divise les grands ensembles de résultats en pages plus petites pour des raisons de performance. Demander 100 000 tickets en un seul appel API entraînerait un délai d'attente ou un plantage de la plupart des systèmes. Au lieu de cela, vous demandez la page 1, traitez ces résultats, puis demandez la page 2, et ainsi de suite jusqu'à ce que vous ayez tout récupéré.

Différents points de terminaison ont des tailles de page par défaut différentes :

• Tickets et utilisateurs : 100 éléments par page
• Articles du centre d'aide : 30 éléments par page
• Résultats de recherche : 100 éléments par page maximum

Vous pouvez généralement ajuster la taille de la page dans certaines limites, mais vous ne pouvez pas dépasser le maximum pour un point de terminaison donné.

Toutes les requêtes API sont comptabilisées dans votre limite de débit. Zendesk autorise un certain nombre de requêtes par minute en fonction de votre plan, et la pagination peut rapidement épuiser ce quota si vous récupérez de grands ensembles de données. La bonne nouvelle est que la pagination par curseur est plus efficace que la pagination par décalage, donc changer de méthode peut en fait réduire votre utilisation de l'API.

Un changement essentiel à connaître : à partir du 15 août 2023, les requêtes de pagination basées sur le décalage au-delà des 10 000 premiers enregistrements (100 pages) renvoient une erreur 400 Bad Request. Si vous avez besoin de plus de 10 000 enregistrements, la pagination par curseur est désormais votre seule option. Apprenez-en davantage sur ce changement dans l'annonce de la pagination par décalage de Zendesk.

Pagination par curseur : la méthode recommandée

La pagination par curseur est l'approche préférée de Zendesk pour la plupart des points de terminaison de liste. Elle utilise un pointeur (le curseur) qui suit votre position dans l'ensemble de données plutôt que de compter les enregistrements depuis le début à chaque fois. Cela la rend considérablement plus rapide pour les grands ensembles de données, car l'API n'a pas besoin de compter et de sauter des enregistrements pour trouver votre page.

Comment fonctionne la pagination par curseur

Pour activer la pagination par curseur, ajoutez un paramètre page[size] à votre requête. Cela indique à Zendesk que vous souhaitez utiliser le mode curseur et spécifie le nombre d'éléments à renvoyer par page (jusqu'à 100 pour la plupart des points de terminaison).

La réponse inclut deux objets clés :

• meta : Contient has_more (booléen), after_cursor et before_cursor
• links : Contient les URL next et prev pour les pages adjacentes

Voici à quoi ressemble une réponse typique :

{
  "tickets": [
    { "id": 1, "subject": "Sample ticket" },
    { "id": 2, "subject": "Another ticket" }
  ],
  "meta": {
    "has_more": true,
    "after_cursor": "eyJvIjoibmljZV9pZCIsInYiOiJhV2tCQUFBQUFBQUEifQ==",
    "before_cursor": "eyJvIjoibmljZV9pZCIsInYiOiJhUzRCQUFBQUFBQUEifQ=="
  },
  "links": {
    "next": "https://example.zendesk.com/api/v2/tickets.json?page[size]=100&page[after]=eyJvIjoibmljZV9pZCIsInYiOiJhV2tCQUFBQUFBQUEifQ==",
    "prev": "https://example.zendesk.com/api/v2/tickets.json?page[size]=100&page[before]=eyJvIjoibmljZV9pZCIsInYiOiJhUzRCQUFBQUFBQUEifQ=="
  }
}

Vous continuez à paginer jusqu'à ce que meta.has_more soit faux. À ce stade, vous avez récupéré tous les enregistrements.

Exemple Python avec pagination par curseur

Voici un exemple de travail complet utilisant Python et la bibliothèque requests :

import requests
import time

ZENDESK_SUBDOMAIN = 'your-subdomain'
ZENDESK_EMAIL = 'your-email@example.com'
ZENDESK_API_TOKEN = 'your-api-token'

BASE_URL = f'https://{ZENDESK_SUBDOMAIN}.zendesk.com/api/v2/tickets.json'
auth = (f'{ZENDESK_EMAIL}/token', ZENDESK_API_TOKEN)

def fetch_all_tickets():
    tickets = []
    url = BASE_URL
    params = {'page[size]': 100}  # Use cursor pagination with 100 items per page

    while url:
        response = requests.get(url, auth=auth, params=params)

        # Handle rate limiting
        if response.status_code == 429:
            retry_after = int(response.headers.get('Retry-After', 60))
            print(f'Rate limited. Waiting {retry_after} seconds...')
            time.sleep(retry_after)
            continue

        response.raise_for_status()
        data = response.json()

        # Process tickets from this page
        for ticket in data['tickets']:
            tickets.append(ticket)
            print(f"Fetched ticket {ticket['id']}: {ticket['subject']}")

        # Check if there are more pages
        if data['meta']['has_more']:
            url = data['links']['next']
            params = None  # Next URL already includes all parameters
        else:
            url = None

    return tickets

if __name__ == '__main__':
    all_tickets = fetch_all_tickets()
    print(f'\nTotal tickets fetched: {len(all_tickets)}')

Éléments clés à remarquer dans cet exemple :

• Nous commençons par page[size]=100 pour activer la pagination par curseur
• Nous vérifions la limitation de débit (HTTP 429) et respectons l'en-tête Retry-After
• Après la première requête, nous utilisons directement l'URL links.next pour les pages suivantes
• La boucle continue jusqu'à ce que has_more soit faux

Exemple Node.js avec pagination par curseur

Voici la même logique en Node.js en utilisant axios :

const axios = require('axios');

const ZENDESK_SUBDOMAIN = 'your-subdomain';
const ZENDESK_EMAIL = 'your-email@example.com';
const ZENDESK_API_TOKEN = 'your-api-token';

const BASE_URL = `https://${ZENDESK_SUBDOMAIN}.zendesk.com/api/v2/tickets.json`;
const auth = Buffer.from(`${ZENDESK_EMAIL}/token:${ZENDESK_API_TOKEN}`).toString('base64');

async function fetchAllTickets() {
  const tickets = [];
  let url = BASE_URL;
  let params = { 'page[size]': 100 };

  try {
    do {
      const response = await axios.get(url, {
        headers: { Authorization: `Basic ${auth}` },
        params: params
      });

      const data = response.data;

      // Process tickets from this page
      for (const ticket of data.tickets) {
        tickets.push(ticket);
        console.log(`Fetched ticket ${ticket.id}: ${ticket.subject}`);
      }

      // Prepare for next page
      if (data.meta.has_more) {
        url = data.links.next;
        params = null; // Next URL includes all parameters
      } else {
        url = null;
      }

    } while (url);

    console.log(`\nTotal tickets fetched: ${tickets.length}`);
    return tickets;

  } catch (error) {
    if (error.response && error.response.status === 429) {
      const retryAfter = error.response.headers['retry-after'] || 60;
      console.log(`Rate limited. Retry after ${retryAfter} seconds`);
    } else {
      console.error('Error fetching tickets:', error.message);
    }
    throw error;
  }
}

fetchAllTickets();

Pagination par décalage : la méthode héritée

La pagination par décalage est l'ancienne approche que Zendesk prend toujours en charge, mais ne recommande plus. Elle fonctionne en spécifiant un numéro de page et l'API calcule quels enregistrements renvoyer en fonction de ce décalage par rapport au début de l'ensemble de données.

Comment fonctionne la pagination par décalage

Avec la pagination par décalage, vous utilisez le paramètre page pour demander un numéro de page spécifique, et éventuellement per_page pour définir le nombre d'éléments par page (jusqu'à 100).

La réponse inclut :

• next_page : URL de la page suivante, ou null si vous êtes sur la dernière page
• previous_page : URL de la page précédente, ou null si vous êtes sur la première page
• count : Nombre total d'enregistrements dans l'ensemble de données

Voici une réponse typique :

{
  "tickets": [
    { "id": 1, "subject": "Sample ticket" },
    { "id": 2, "subject": "Another ticket" }
  ],
  "count": 15420,
  "next_page": "https://example.zendesk.com/api/v2/tickets.json?page=2",
  "previous_page": null
}

Exemple Python avec pagination par décalage

Voici comment paginer en utilisant la méthode de décalage :

import requests
import time

ZENDESK_SUBDOMAIN = 'your-subdomain'
ZENDESK_EMAIL = 'your-email@example.com'
ZENDESK_API_TOKEN = 'your-api-token'

BASE_URL = f'https://{ZENDESK_SUBDOMAIN}.zendesk.com/api/v2/tickets.json'
auth = (f'{ZENDESK_EMAIL}/token', ZENDESK_API_TOKEN)

def fetch_tickets_offset():
    tickets = []
    url = BASE_URL

    while url:
        response = requests.get(url, auth=auth)

        if response.status_code == 429:
            retry_after = int(response.headers.get('Retry-After', 60))
            time.sleep(retry_after)
            continue

        if response.status_code == 400:
            # You've hit the 10,000 record limit
            print('Error: Cannot paginate beyond 10,000 records with offset pagination')
            break

        response.raise_for_status()
        data = response.json()

        for ticket in data['tickets']:
            tickets.append(ticket)

        # Move to next page
        url = data['next_page']

    return tickets

Limites à connaître

La pagination par décalage présente plusieurs inconvénients qui expliquent pourquoi Zendesk l'abandonne progressivement :

• La limite stricte de 10 000 enregistrements : Vous ne pouvez pas récupérer plus de 10 000 enregistrements en utilisant la pagination par décalage. Tenter de demander la page 101 ou au-delà renvoie une erreur 400.

• Dégradation des performances : Lorsque vous demandez des pages plus profondes (page 50, page 90), l'API met plus de temps à répondre, car elle doit compter et sauter tous les enregistrements précédents.

• Incohérence des données : Si des enregistrements sont ajoutés ou supprimés pendant que vous paginez, vous pouvez voir des doublons ou manquer des enregistrements. Cela se produit parce que le décalage est calculé à nouveau pour chaque requête en fonction de l'état actuel de l'ensemble de données.

• Pas de nombre total avec la pagination par curseur : Un avantage de la pagination par décalage est qu'elle renvoie un count du nombre total d'enregistrements. La pagination par curseur ne fournit pas cela, vous aurez donc besoin d'un appel API séparé si vous avez besoin du total.

Curseur vs décalage : lequel devriez-vous utiliser ?

Le choix est simple pour la plupart des cas d'utilisation :

Utilisez la pagination par curseur lorsque :

• Vous avez besoin de plus de 10 000 enregistrements
• La performance est importante (en particulier pour les grands ensembles de données)
• Vous traitez les données séquentiellement sans avoir besoin de sauter

Utilisez la pagination par décalage lorsque :

• Vous avez besoin du nombre total d'enregistrements
• Vous créez une interface utilisateur qui permet aux utilisateurs d'aller à des pages spécifiques
• Vous travaillez avec un petit ensemble de données (moins de 10 000 enregistrements) et la simplicité est importante

Si vous utilisez actuellement la pagination par décalage et que vous atteignez la limite de 10 000 enregistrements, la migration vers la pagination par curseur est simple. Les principaux changements sont :

1. Remplacez le paramètre page par page[size]
2. Vérifiez meta.has_more au lieu de vérifier si next_page est nul
3. Utilisez links.next pour l'URL de la page suivante au lieu de next_page

Pièges courants de la pagination et solutions

Même avec du code fonctionnel, vous rencontrerez des cas extrêmes en production. Voici comment gérer les problèmes les plus courants.

Gérer les limites de débit

Zendesk renvoie HTTP 429 lorsque vous dépassez votre limite de débit. La réponse inclut un en-tête Retry-After vous indiquant combien de secondes attendre. Implémentez toujours un repli exponentiel plutôt que de marteler l'API :

import time

def make_request_with_backoff(url, auth, max_retries=5):
    for attempt in range(max_retries):
        response = requests.get(url, auth=auth)

        if response.status_code == 429:
            retry_after = int(response.headers.get('Retry-After', 60))
            # Exponential backoff: wait longer with each retry
            wait_time = retry_after * (2 ** attempt)
            time.sleep(wait_time)
            continue

        return response

    raise Exception('Max retries exceeded')

Gérer les pages vides

Parfois, vous pouvez rencontrer une page vide où has_more était vrai, mais la requête suivante ne renvoie aucun enregistrement. Cela peut se produire lorsque le dernier enregistrement de la page précédente était le dernier enregistrement de l'ensemble de données entier. Enregistrez la valeur after_cursor précédente pour une utilisation future dans ce cas.

Expiration du curseur

Pour le point de terminaison Export Search Results, les curseurs expirent après une heure. Si votre traitement prend plus de temps que cela, vous devrez redémarrer l'exportation ou traiter les données plus rapidement.

Limitations de l'API de recherche

L'API de recherche a ses propres particularités de pagination :

• Maximum 1 000 résultats par requête au total
• Maximum 100 résultats par page
• Utilise uniquement la pagination par décalage
• Demander la page 11 (à 100 résultats par page) renvoie une erreur 422

Si vous avez besoin de plus de 1 000 résultats de recherche, utilisez plutôt le point de terminaison Export Search Results, qui prend en charge la pagination par curseur et renvoie jusqu'à 1 000 enregistrements par page. Consultez la documentation de l'API de recherche Zendesk pour plus de détails.

Automatiser les flux de travail Zendesk sans l'API

La création d'intégrations API personnalisées avec une pagination, une gestion des erreurs et une limitation de débit appropriées demande un effort de développement important. Vous devez écrire le code, le maintenir à mesure que Zendesk met à jour son API et gérer tous les cas extrêmes dont nous avons parlé.

Pour de nombreuses équipes, il existe un chemin plus simple. eesel AI se connecte directement à votre compte Zendesk et gère automatiquement toute la récupération de données. Au lieu d'écrire la logique de pagination, vous configurez ce que vous voulez accomplir via une interface visuelle.

Voici comment cela fonctionne :

• Connectez eesel AI à votre compte Zendesk en quelques minutes
• L'IA apprend de vos tickets passés, des articles du centre d'aide et des macros
• Vous définissez des règles d'automatisation en langage clair (aucun code requis)
• eesel AI gère tous les appels API, la pagination et le traitement des données

Vous pouvez automatiser le routage des tickets, rédiger des réponses pour vos agents, étiqueter et prioriser les tickets entrants et générer des rapports. Le tout sans écrire une seule ligne de code de pagination.

Pour les équipes qui ont besoin d'intégrations personnalisées, l'API Zendesk reste le bon choix. Mais si votre objectif est d'automatiser les flux de travail et d'améliorer l'efficacité, des outils comme eesel AI peuvent vous y amener plus rapidement.

Commencez à automatiser vos flux de travail Zendesk dès aujourd'hui

La pagination est un concept fondamental lorsque vous travaillez avec l'API Zendesk. La pagination par curseur offre de meilleures performances et aucune limite d'enregistrements, ce qui en fait le choix évident pour la plupart des intégrations modernes. La pagination par décalage a toujours sa place pour les ensembles de données plus petits et lorsque vous avez besoin du nombre total d'enregistrements, mais la limite de 10 000 enregistrements signifie qu'elle ne convient pas à la récupération de données à grande échelle.

Les exemples de code dans ce guide devraient vous donner une base solide pour implémenter la pagination dans vos propres projets. N'oubliez pas de gérer les limites de débit avec élégance, de surveiller les cas extrêmes comme les pages vides et de choisir la méthode de pagination qui correspond à votre cas d'utilisation spécifique.

Si vous préférez éviter complètement le développement de l'API et commencer à automatiser vos flux de travail Zendesk dès aujourd'hui, essayez eesel AI. Il gère la complexité technique afin que vous puissiez vous concentrer sur la fourniture d'un meilleur support client.