Wie man durch Zendesk-Tickets paginiert: Eine vollständige Entwickleranleitung

Wenn Sie Integrationen mit Zendesk entwickeln, werden Sie schnell feststellen, dass die API Ihnen 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 reaktionsfähig 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, Zendesk-Workflows zu automatisieren, ohne selbst Paginierungslogik zu schreiben, werden wir auch das behandeln.

Die Zendesk API-Paginierung 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 diese 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: die empfohlene Methode

Die Cursor-Paginierung ist der von Zendesk bevorzugte Ansatz für die meisten Listen-Endpunkte. Sie 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 Datensätze nicht zählen und überspringen muss, um Ihre Seite zu finden.

Wie die Cursor-Paginierung funktioniert

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

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.

Python-Beispiel mit Cursor-Paginierung

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 respektieren 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

Node.js-Beispiel mit Cursor-Paginierung

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();

Offset-Paginierung: die Legacy-Methode

Die Offset-Paginierung ist der ältere Ansatz, den Zendesk immer noch unterstützt, aber nicht mehr empfiehlt. Sie funktioniert, indem eine Seitenzahl angegeben wird und die API basierend auf diesem Offset vom Anfang des Datensatzes berechnet, welche Datensätze zurückgegeben werden sollen.

Wie die Offset-Paginierung funktioniert

Bei der Offset-Paginierung verwenden Sie den Parameter page, um eine bestimmte Seitenzahl anzufordern, und optional per_page, um die Anzahl der Elemente pro Seite festzulegen (bis zu 100).

Die Antwort enthält:

• next_page: URL für die nächste Seite oder null, wenn Sie sich auf der letzten Seite befinden
• previous_page: URL für die vorherige Seite oder null, wenn Sie sich auf der ersten Seite befinden
• count: Gesamtzahl der Datensätze im Datensatz

Hier ist eine typische Antwort:

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

Python-Beispiel mit Offset-Paginierung

So paginieren Sie mit der Offset-Methode:

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

Einschränkungen, die Sie beachten sollten

Die Offset-Paginierung hat mehrere Nachteile, die erklären, warum Zendesk sie auslaufen lässt:

• Die harte Grenze von 10.000 Datensätzen: Sie können mit der Offset-Paginierung nicht mehr als 10.000 Datensätze abrufen. Der Versuch, Seite 101 oder höher anzufordern, gibt einen 400-Fehler zurück.

• Performance-Einbußen: Wenn Sie tiefere Seiten anfordern (Seite 50, Seite 90), dauert es länger, bis die API antwortet, da sie alle vorhergehenden Datensätze zählen und überspringen muss.

• Dateninkonsistenz: Wenn Datensätze hinzugefügt oder entfernt werden, während Sie paginieren, können doppelte Datensätze angezeigt werden oder Datensätze fehlen. Dies geschieht, weil der Offset für jede Anfrage basierend auf dem aktuellen Datensatzstatus neu berechnet wird.

• Keine Gesamtzahl mit Cursor-Paginierung: Ein Vorteil der Offset-Paginierung ist, dass sie eine count der Gesamtzahl der Datensätze zurückgibt. Die Cursor-Paginierung bietet dies nicht, sodass Sie einen separaten API-Aufruf benötigen, wenn Sie die Gesamtzahl benötigen.

Cursor vs. Offset: Welche sollten Sie verwenden?

Die Wahl ist für die meisten Anwendungsfälle einfach:

Verwenden Sie die Cursor-Paginierung, wenn:

• Sie mehr als 10.000 Datensätze benötigen
• Performance wichtig ist (insbesondere 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ätzen) arbeiten und Einfachheit wichtig ist

Wenn Sie derzeit die Offset-Paginierung verwenden und an die Grenze 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, anstatt zu prüfen, ob next_page null ist
3. Verwenden Sie links.next für die nächste Seiten-URL anstelle von next_page

Häufige Paginierungs-Fallstricke und Lösungen

Auch mit funktionierendem Code werden Sie in der Produktion auf Sonderfälle stoßen. So gehen Sie mit den häufigsten Problemen um.

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 exponentielles Backoff, anstatt die API zu überlasten:

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, die nächste Anfrage aber 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 Export-Suchergebnisse-Endpunkt 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 (mit 100 Ergebnissen pro Seite) gibt einen 422-Fehler zurück

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

Automatisierung von Zendesk-Workflows ohne die API

Das Erstellen benutzerdefinierter API-Integrationen mit ordnungsgemäßer Paginierung, Fehlerbehandlung und Ratenbegrenzung erfordert einen erheblichen Entwicklungsaufwand. 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 die gesamte Datenabfrage 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 Ticket-Weiterleitung automatisieren, Antworten für Ihre Agenten entwerfen, eingehende Tickets taggen 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. Wenn es Ihr Ziel ist, Workflows zu automatisieren und die Effizienz zu verbessern, können Tools wie eesel AI Sie jedoch schneller dorthin bringen.

Beginnen Sie noch heute mit der Automatisierung Ihrer Zendesk-Workflows

Die Paginierung ist ein grundlegendes Konzept bei der Arbeit mit der Zendesk API. Die Cursor-Paginierung bietet eine bessere Performance und keine Datensatzbeschränkungen, was sie zur klaren Wahl für die meisten modernen Integrationen macht. Die Offset-Paginierung hat immer noch ihren Platz für kleinere Datensätze und wenn Sie die Gesamtzahl der Datensätze benötigen, aber die Beschränkung auf 10.000 Datensätze bedeutet, dass sie für die groß angelegte Datenabfrage nicht geeignet ist.

Die Codebeispiele in dieser Anleitung sollten Ihnen eine solide Grundlage für die Implementierung der Paginierung in Ihren eigenen Projekten geben. Denken Sie daran, Ratenbegrenzungen elegant zu behandeln, auf Sonderfälle wie leere Seiten zu achten und die Paginierungsmethode zu wählen, die zu Ihrem spezifischen Anwendungsfall passt.

Wenn Sie die API-Entwicklung lieber ganz überspringen und noch heute mit der Automatisierung Ihrer Zendesk-Workflows beginnen möchten, probieren Sie eesel AI aus. Es übernimmt die technische Komplexität, sodass Sie sich auf die Bereitstellung eines besseren Kundensupports konzentrieren können.