Zendesk API Cursor-Paginierung: Eine vollständige Entwickleranleitung

Wenn Sie Integrationen mit Zendesk erstellen, werden Sie schnell feststellen, dass die API nicht Ihre gesamte Ticket-Datenbank auf einmal übergibt. Stattdessen werden Daten in mundgerechten Portionen über einen Mechanismus namens Paginierung bereitgestellt. Dies ist so konzipiert. Die Paginierung hält die API reaktionsschnell und verhindert Timeouts, wenn Sie es mit Tausenden (oder Millionen) von Support-Tickets zu tun haben.

Aber hier wird es interessant. Zendesk bietet zwei verschiedene Möglichkeiten, durch Ihre Daten zu paginieren: Cursor-Paginierung und Offset-Paginierung. Die eine ist schnell, modern und nahezu unbegrenzt. Die andere ist auf 10.000 Datensätze begrenzt und bringt einige Altlasten aus älteren API-Designs mit sich. Seit August 2023 drängt Zendesk Entwickler in Richtung Cursor-Paginierung, indem strenge Beschränkungen für die Offset-Methode durchgesetzt werden.

In dieser Anleitung werden wir beide Paginierungsansätze mit funktionierenden Codebeispielen durchgehen. Sie erfahren, wann Sie welche Methode verwenden sollten, wie Sie mit Sonderfällen umgehen und welche Fallstricke Sie vermeiden sollten. Und wenn Sie denken, dass es einen einfacheren Weg geben muss, mit Zendesk-Daten zu arbeiten, ohne selbst Paginierungslogik zu schreiben, werden wir auch das behandeln.

Für mehr Kontext zu den Zendesk-Paginierungsansätzen könnte Ihnen auch unser vollständiger Leitfaden zur Paginierung durch Zendesk-Tickets hilfreich sein.

Die Paginierung in der Zendesk API verstehen

Bevor wir in den Code eintauchen, wollen wir klären, warum es die Paginierung gibt und wie sie auf hoher Ebene funktioniert.

Die Zendesk API unterteilt große Ergebnismengen aus Performancegründen in kleinere Seiten. Das Anfordern von 100.000 Tickets in einem einzigen API-Aufruf würde bei den meisten Systemen zu einem Timeout führen oder sie zum Absturz bringen. Stattdessen fordern Sie Seite 1 an, verarbeiten diese Ergebnisse, fordern dann Seite 2 an und so weiter, bis Sie alles abgerufen haben.

Verschiedene Endpunkte haben unterschiedliche Standardseitengrößen:

• Tickets und Benutzer: 100 Elemente pro Seite
• Help Center-Artikel: 30 Elemente pro Seite
• Suchergebnisse: maximal 100 Elemente pro Seite

Sie können die Seitengröße in der Regel innerhalb von Grenzen anpassen, aber Sie können das Maximum für einen bestimmten Endpunkt nicht überschreiten.

Alle API-Anfragen werden auf Ihr Ratenlimit angerechnet. Zendesk erlaubt eine bestimmte Anzahl von Anfragen pro Minute, abhängig von Ihrem Plan, und die Paginierung kann diese Quote schnell aufbrauchen, wenn Sie große Datensätze abrufen. Die gute Nachricht ist, dass die Cursor-Paginierung effizienter ist als die Offset-Paginierung, sodass der Methodenwechsel Ihre API-Nutzung tatsächlich reduzieren kann.

Eine wichtige Änderung, die Sie kennen sollten: Ab dem 15. August 2023 geben Offset-basierte Paginierungsanfragen über die ersten 10.000 Datensätze (100 Seiten) hinaus einen 400 Bad Request-Fehler zurück. Wenn Sie mehr als 10.000 Datensätze benötigen, ist die Cursor-Paginierung jetzt Ihre einzige Option. Erfahren Sie mehr über diese Änderung in der Zendesk-Ankündigung zur Offset-Paginierung.

Cursor-Paginierung vs. Offset-Paginierung

Lassen Sie uns die Unterschiede zwischen diesen beiden Ansätzen aufschlüsseln, damit Sie den richtigen für Ihren Anwendungsfall auswählen können.

Verwenden Sie die Cursor-Paginierung, wenn:

• Sie mehr als 10.000 Datensätze benötigen
• Performance wichtig ist (besonders bei großen Datensätzen)
• Sie Daten sequenziell verarbeiten, ohne herumspringen zu müssen

Verwenden Sie die Offset-Paginierung, wenn:

• Sie die Gesamtzahl der Datensätze benötigen
• Sie eine Benutzeroberfläche erstellen, mit der Benutzer zu bestimmten Seiten springen können
• Sie mit einem kleinen Datensatz (unter 10.000 Datensätze) arbeiten und Einfachheit wichtig ist

Wenn Sie derzeit die Offset-Paginierung verwenden und an das Limit von 10.000 Datensätzen stoßen, ist die Migration zur Cursor-Paginierung unkompliziert. Die wichtigsten Änderungen sind:

1. Ersetzen Sie den Parameter page durch page[size]
2. Überprüfen Sie meta.has_more anstelle von next_page ist null
3. Verwenden Sie links.next für die URL der nächsten Seite anstelle von next_page

Bei eesel AI integrieren wir uns direkt in Zendesk und handhaben die gesamte Paginierungskomplexität automatisch. Aber wenn Sie benutzerdefinierte Integrationen erstellen, ist das Verständnis dieser Unterschiede unerlässlich.

Wie die Cursor-Paginierung funktioniert

Die Cursor-Paginierung verwendet einen Zeiger (den Cursor), der Ihre Position im Datensatz verfolgt, anstatt jedes Mal Datensätze vom Anfang an zu zählen. Dies macht sie für große Datensätze deutlich schneller, da die API keine Datensätze zählen und überspringen muss, um Ihre Seite zu finden.

Um die Cursor-Paginierung zu aktivieren, fügen Sie Ihrer Anfrage einen page[size]-Parameter hinzu. Dies teilt Zendesk mit, dass Sie den Cursor-Modus verwenden möchten, und gibt an, wie viele Elemente pro Seite zurückgegeben werden sollen (bis zu 100 für die meisten Endpunkte). Weitere Informationen finden Sie in der Zendesk-Dokumentation zur Cursor-Paginierung.

Die Antwort enthält zwei wichtige Objekte:

• meta: Enthält has_more (boolesch), after_cursor und before_cursor
• links: Enthält next- und prev-URLs für die benachbarten Seiten

So sieht eine typische Antwort aus:

{
  "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=="
  }
}

Sie paginieren so lange, bis meta.has_more falsch ist. An diesem Punkt haben Sie alle Datensätze abgerufen.

Implementierung der Cursor-Paginierung in Python

Hier ist ein vollständiges, funktionierendes Beispiel mit Python und der Requests-Bibliothek:

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)}')

Wichtige Dinge, die in diesem Beispiel zu beachten sind:

• Wir beginnen mit page[size]=100, um die Cursor-Paginierung zu aktivieren
• Wir prüfen auf Ratenbegrenzung (HTTP 429) und beachten den Retry-After-Header
• Nach der ersten Anfrage verwenden wir die links.next-URL direkt für nachfolgende Seiten
• Die Schleife wird fortgesetzt, bis has_more falsch ist

Implementierung der Cursor-Paginierung in Node.js

Hier ist die gleiche Logik in Node.js mit 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();

Häufige Fallstricke und wie man sie vermeidet

Auch mit funktionierendem Code werden Sie in der Produktion auf Sonderfälle stoßen. Hier erfahren Sie, wie Sie mit den häufigsten Problemen umgehen.

Umgang mit Ratenbegrenzungen

Zendesk gibt HTTP 429 zurück, wenn Sie Ihr Ratenlimit überschreiten. Die Antwort enthält einen Retry-After-Header, der Ihnen mitteilt, wie viele Sekunden Sie warten müssen. Implementieren Sie immer einen exponentiellen Backoff, anstatt die API zu hämmern:

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')

Umgang mit leeren Seiten

Gelegentlich kann es vorkommen, dass Sie auf eine leere Seite stoßen, auf der has_more wahr war, aber die nächste Anfrage keine Datensätze zurückgibt. Dies kann vorkommen, wenn der letzte Datensatz von der vorherigen Seite der letzte Datensatz im gesamten Datensatz war. Speichern Sie in diesem Fall den vorherigen after_cursor-Wert zur späteren Verwendung.

Cursor-Ablauf

Für den Endpunkt Export Search Results laufen Cursor nach einer Stunde ab. Wenn Ihre Verarbeitung länger dauert, müssen Sie den Export neu starten oder Daten schneller verarbeiten.

Einschränkungen der Such-API

Die Such-API hat ihre eigenen Paginierungs-Eigenheiten:

• Maximal 1.000 Ergebnisse pro Abfrage insgesamt
• Maximal 100 Ergebnisse pro Seite
• Verwendet nur Offset-Paginierung
• Das Anfordern von Seite 11 (bei 100 Ergebnissen pro Seite) gibt einen 422-Fehler zurück

Wenn Sie mehr als 1.000 Suchergebnisse benötigen, verwenden Sie stattdessen den Endpunkt Export Search Results, der die Cursor-Paginierung unterstützt und bis zu 1.000 Datensätze pro Seite zurückgibt. Weitere Informationen finden Sie in der Zendesk-Dokumentation zur Such-API.

Datenkonsistenz während der Paginierung

Paginierte Daten können aufgrund der Echtzeitnatur der Daten ungenau sein. Ein oder mehrere Elemente können zwischen den Anfragen zu Ihrer Datenbankinstanz hinzugefügt oder daraus entfernt werden. Eine Möglichkeit, Paginierungsungenauigkeiten zu reduzieren (wenn auch nicht vollständig zu beseitigen), besteht darin, die Datensätze nach einem Attribut zu sortieren, das nicht geändert werden kann, z. B. die ID oder das Erstellungsdatum, falls dies von der Ressource unterstützt wird.

Bei eesel AI handhabt unser KI-Agent diese Komplexitäten automatisch. Wir verwalten Ratenbegrenzungen, Cursor-Ablauf und Datenkonsistenzprobleme, sodass Sie diese Logik nicht selbst schreiben müssen.

Migration von Offset- zu Cursor-Paginierung

Wenn Sie derzeit die Offset-Paginierung verwenden, finden Sie hier eine kurze Migrationsanleitung, die die wichtigsten Änderungen zeigt:

Vorher (Offset-Paginierung):

url = f'https://{subdomain}.zendesk.com/api/v2/tickets.json'
while url:
    response = requests.get(url, auth=auth)
    data = response.json()
    # Process tickets...
    url = data['next_page']  # null when done

Nachher (Cursor-Paginierung):

url = f'https://{subdomain}.zendesk.com/api/v2/tickets.json?page[size]=100'
params = {'page[size]': 100}
while url:
    response = requests.get(url, auth=auth, params=params)
    data = response.json()
    # Process tickets...
    if data['meta']['has_more']:
        url = data['links']['next']
        params = None
    else:
        url = None

Die wichtigsten Änderungen sind:

1. Fügen Sie den Parameter page[size] hinzu, um den Cursor-Modus zu aktivieren
2. Überprüfen Sie meta.has_more anstelle von next_page ist null
3. Verwenden Sie links.next für die URL der nächsten Seite anstelle von next_page
4. Entfernen Sie die Abhängigkeit von der count-Eigenschaft (nicht verfügbar in der Cursor-Paginierung)

Überspringen Sie die Paginierungskomplexität mit eesel AI

Das Erstellen benutzerdefinierter API-Integrationen mit ordnungsgemäßer Paginierung, Fehlerbehandlung und Ratenbegrenzung erfordert erhebliche Entwicklungsarbeit. Sie müssen den Code schreiben, ihn pflegen, wenn Zendesk seine API aktualisiert, und alle Sonderfälle behandeln, die wir besprochen haben.

Für viele Teams gibt es einen einfacheren Weg. eesel AI verbindet sich direkt mit Ihrem Zendesk-Konto und übernimmt den gesamten Datenabruf automatisch. Anstatt Paginierungslogik zu schreiben, konfigurieren Sie über eine visuelle Oberfläche, was Sie erreichen möchten.

So funktioniert es:

• Verbinden Sie eesel AI in wenigen Minuten mit Ihrem Zendesk-Konto
• Die KI lernt aus Ihren vergangenen Tickets, Help Center-Artikeln und Makros
• Sie definieren Automatisierungsregeln in einfachem Deutsch (kein Code erforderlich)
• eesel AI übernimmt alle API-Aufrufe, die Paginierung und die Datenverarbeitung

Sie können die Ticketweiterleitung automatisieren, Antworten für Ihre Agenten entwerfen, eingehende Tickets kennzeichnen und priorisieren sowie Berichte erstellen. Alles ohne eine einzige Zeile Paginierungscode zu schreiben.

Für Teams, die benutzerdefinierte Integrationen benötigen, bleibt die Zendesk API die richtige Wahl. Aber wenn Ihr Ziel darin besteht, Arbeitsabläufe zu automatisieren und die Effizienz zu verbessern, können Tools wie eesel AI Sie schneller dorthin bringen. Sehen Sie sich unsere Preise an, um zu sehen, wie wir im Vergleich zum Erstellen und Warten benutzerdefinierter Lösungen abschneiden.