Paginierung und Tailing

Auf dieser Seite wird erläutert, wie Sie die Paginierung und das Tailing beim Aufrufen der Endpunkte der Manager API verwenden.

Seitenumbruch

Die Paginierung wird für die meisten Endpunkte der Manager API unterstützt. Ausnahmen finden Sie unter Endpunkt auf aktualisierte Datensätze prüfen.

Seitengröße festlegen

Standardmäßig geben Manager-API-Endpunkte Seiten mit 100 Einträgen zurück. Sie können diese Anzahl mit dem Suchparameter per auf maximal 100 ändern. Ein größerer Wert wird auf 100 reduziert.

Verwenden Sie den folgenden Endpunkt, um die Seitengröße festzulegen:

/manager/api/v1/agents?per=50

Dadurch wird die Seitengröße auf 50 Einträge festgelegt.

Bestimmte Seite anfordern

Mit dem Suchparameter page können Sie eine bestimmte Seite mit Datensätzen anfordern.

Verwenden Sie den folgenden Endpunkt, um eine bestimmte Seite anzufordern:

/manager/api/v1/agents?page=2

Dadurch wird die zweite Seite mit Datensätzen zurückgegeben.

Alle verfügbaren Datensätze abrufen

Standardmäßig gibt die Manager API 100 Einträge auf einer Antwortseite zurück. Sie können die Anzahl der Einträge auf einer Seite jedoch ändern, indem Sie die Seitengröße festlegen. Bei Endpunkten, die die Paginierung unterstützen, enthält der Antwortheader die Gesamtzahl der verfügbaren Datensätze. Wenn diese Zahl die Seitengröße überschreitet, müssen Sie die API mehrmals aufrufen, um alle Einträge abzurufen. Bei Endpunkten, die die Paginierung unterstützen, enthält die Antwort einen Link-Header gemäß RFC 5988. Ein rel="next"-Link ist vorhanden, wenn weitere Datensätze verfügbar sind. Ein rel="last"-Link gibt die Nummer der letzten Seite an. Die Antwort enthält auch die Header Total und Per-Page.

So rufen Sie alle verfügbaren Einträge ab:

  1. Rufen Sie einen Manager-API-Endpunkt auf, der die Paginierung unterstützt. Weitere Informationen finden Sie unter Paginierung. Der Antwortheader gibt an, wie viele Datensätze zurückgegeben werden sollen.

  2. Vergleichen Sie die Anzahl der zurückzugebenden Datensätze mit der Seitengröße. Wenn die Anzahl der zurückzugebenden Datensätze kleiner als die Seitengröße ist, wurden alle Datensätze zurückgegeben. Fahren Sie andernfalls mit dem nächsten Schritt fort.

  3. Rufen Sie den Endpunkt noch einmal auf und geben Sie die nächste Seite mit Datensätzen an. Weitere Informationen finden Sie unter Bestimmte Seite anfordern. Wiederholen Sie diesen Schritt, bis alle Datensätze zurückgegeben wurden.

Endpunkt auf aktualisierte Datensätze überwachen

Google rät davon ab, die Paginierung für die API-Endpunkte call, chat und agent activity zu verwenden, da wir keine optimalen Ergebnisse garantieren können. Stattdessen empfehlen wir, diese API-Endpunkte auf aktualisierte Einträge zu prüfen. Das Tailing eines API-Endpunkt bedeutet, dass er kontinuierlich aufgerufen wird, um Datensätze abzurufen, die seit Ihrer letzten Anfrage neu oder aktualisiert wurden.

Calls API-Endpunkt beobachten

Wenn ein Anrufdatensatz geändert wird, wird der Zeitstempel updated_at aktualisiert. Mit dem Zeitstempel können Sie die Anrufaufzeichnungen angeben, die Sie beim Aufrufen des Calls API-Endpunkt abrufen möchten.

So rufen Sie den Calls API-Endpunkt alle 60 Minuten ab:

  1. Senden Sie eine Anfrage an den Calls API-Endpunkt (/manager/api/v1/calls) und geben Sie die folgenden Suchparameter an:

    • updated_at[from]: Geben Sie an, dass Sie Datensätze abrufen möchten, die zu oder nach diesem Zeitpunkt aktualisiert wurden.

    • sort_column: Geben Sie das Feld an, nach dem die Datensätze sortiert werden sollen.

    • sort_direction. Geben Sie die Sortierrichtung der Datensätze in der Antwort an.

    Das folgende Bash-Beispielskript verwendet den Befehl curl:

    # 1. Define your environment variables (usually set in your shell or .env file)
    export API_HOSTNAME="ccaip-host.uc1.ccaiplatform.com/"
    export API_USER="ccaip-host"
    export API_PASS="CCAI Platform API Key"
    
    # 2. Calculate the timestamp for 60 minutes ago in ISO 8601 format (UTC)
    # For macOS (BSD date):
    # TIMESTAMP=$(date -v-60M -u +"%Y-%m-%dT%H:%M:%SZ")
    # For Linux (GNU date):
    TIMESTAMP=$(date --date='60 minutes ago' -u +"%Y-%m-%dT%H:%M:%SZ")
    
    # 3. Execute the curl command
    # -u handles the Base64 encoding for Basic Auth automatically
    curl -g -u "${API_USER}:${API_PASS}" \
    "https://${API_HOSTNAME}/manager/api/v1/calls?updated_at[from]=${TIMESTAMP}&sort_column=updated_at&sort_direction=asc" | jq
    

    Die Calls API gibt in etwa folgende Antwort zurück:

      [
        {
          "id": 100,
          ...
          "updated_at": "2025-01-01T00:00:00Z"
        },
        {
          "id": 98,
          ...
          "updated_at": "2025-01-02T00:00:00Z"
        },
        {
          "id": 150,
          ...
          "updated_at": "2025-01-03T00:00:00Z"
        }
      ]
    

    Es werden Antwortobjekte zurückgegeben, die am oder nach dem von Ihnen angegebenen Zeitstempel aktualisiert wurden, sortiert nach Datum in aufsteigender Reihenfolge. Verwenden Sie den Zeitstempel updated_at des letzten Objekts in dieser Antwort für den Zeitstempel im nächsten Aufruf des Endpunkts. Der Filter from ist inklusiv, sodass die nächste Antwort den Eintrag mit diesem Zeitstempel wiederholt. Deduplizieren Sie anhand der Datensatz-ID oder erfassen Sie die IDs, die bereits zu diesem Zeitstempel verarbeitet wurden, und überspringen Sie sie.

  2. Rufen Sie den Call API-Endpunkt 60 Minuten später auf. Die aktualisierten Anrufdatensätze seit Ihrer letzten Anfrage werden zurückgegeben.

  3. Wiederholen Sie den vorherigen Schritt, um das Monitoring des Endpunkts fortzusetzen.

Chats API-Endpunkt beobachten

Verwenden Sie den Zeitstempel updated_at aus dem letzten Objekt in dieser Antwort für den Zeitstempel im nächsten Aufruf des Endpunkts. Der Filter updated_at[from] ist inklusiv, sodass die nächste Antwort den Eintrag mit diesem Zeitstempel wiederholt. Führen Sie eine Deduplizierung anhand der Datensatz-ID durch oder erfassen Sie die IDs, die bereits zu diesem Zeitstempel verarbeitet wurden, und überspringen Sie sie.

Wenn ein Chat-Datensatz geändert wird, wird der Zeitstempel updated_at aktualisiert. Mit dem Zeitstempel können Sie die Chatprotokolle angeben, die Sie beim Aufrufen des Chats API-Endpunkt abrufen möchten.

So rufen Sie den Chats API-Endpunkt alle 60 Minuten ab:

  1. Senden Sie eine Anfrage an den Chats API-Endpunkt (/manager/api/v1/chats) und geben Sie die folgenden Abfrageparameter an:

    • updated_at[from]: Geben Sie an, dass Sie Datensätze abrufen möchten, die zu oder nach diesem Zeitpunkt aktualisiert wurden.

    • sort_column: Geben Sie das Feld an, nach dem die Datensätze sortiert werden sollen.

    • sort_direction. Geben Sie die Sortierrichtung der Datensätze in der Antwort an.

    Das folgende Bash-Beispielskript verwendet den Befehl curl:

    # 1. Define your environment variables (usually set in your shell or .env file)
    export API_HOSTNAME="ccaip-host.uc1.ccaiplatform.com/"
    export API_USER="ccaip-host"
    export API_PASS="CCAI Platform API Key"
    
    # 2. Calculate the timestamp for 60 minutes ago in ISO 8601 format (UTC)
    # For macOS (BSD date):
    # TIMESTAMP=$(date -v-60M -u +"%Y-%m-%dT%H:%M:%SZ")
    # For Linux (GNU date):
    TIMESTAMP=$(date --date='60 minutes ago' -u +"%Y-%m-%dT%H:%M:%SZ")
    
    # 3.. Execute the curl command
    # -u handles the Base64 encoding for Basic Auth automatically
    curl -g -u "${API_USER}:${API_PASS}" \
    "https://${API_HOSTNAME}/manager/api/v1/chats?updated_at[from]=${TIMESTAMP}&sort_column=updated_at&sort_direction=asc" | jq
    

    Die Chats API gibt in etwa folgende Antwort zurück:

    [
      {
        "id": 100,
        ...
        "updated_at": "2025-01-01T00:00:00Z"
      },
      {
        "id": 98,
        ...
        "updated_at": "2025-01-02T00:00:00Z"
      },
      {
        "id": 150,
        ...
        "updated_at": "2025-01-03T00:00:00Z"
      }
    ]
    

    Antwortobjekte, die am oder nach dem angegebenen Zeitstempel aktualisiert wurden, werden zurückgegeben und nach Datum in aufsteigender Reihenfolge sortiert. Verwenden Sie den Zeitstempel updated_at des letzten Objekts in dieser Antwort für den Zeitstempel im nächsten Aufruf des Endpunkts.

  2. Rufen Sie den API-Endpunkt 60 Minuten später noch einmal auf. Die aktualisierten Chateinträge seit Ihrer letzten Anfrage werden zurückgegeben.

  3. Wiederholen Sie den vorherigen Schritt, um das Monitoring des Endpunkts fortzusetzen.

Agent Activity API-Endpunkt beobachten

Im Gegensatz zu den Chat- und Anrufaufzeichnungen werden die Aktivitätsprotokolle des KI-Agenten nicht aktualisiert und haben daher keinen updated_at-Zeitstempel. Mit dem Zeitstempel started_at können Sie die Aktivitätsdatensätze angeben, die Sie beim Aufrufen des API-Endpunkt für Agentenaktivitäten abrufen möchten. Der Filter started_at[from] ist inklusiv, sodass in der nächsten Antwort der Datensatz mit diesem Zeitstempel wiederholt wird. Führen Sie eine Deduplizierung anhand der Datensatz-ID durch oder erfassen Sie die bereits zu diesem Zeitstempel verarbeiteten IDs und überspringen Sie sie.

So rufen Sie den Agent Activity API-Endpunkt alle 60 Minuten ab:

  1. Senden Sie eine Anfrage an den Agent Activity API-Endpunkt (/manager/api/v1/agent_activity_logs) und geben Sie die folgenden Abfrageparameter an:

    • started_at[from]: Geben Sie an, dass Sie Aktivitätsprotokolle möchten, die zu oder nach diesem Zeitpunkt gestartet wurden.

    • ended_at[from]: Geben Sie an, dass Sie Aktivitätsprotokolle abrufen möchten, die zu oder nach diesem Zeitpunkt beendet wurden. Verwenden Sie diese Option anstelle von started_at[from], um Sitzungen zu erfassen, die vor dem Fenster begonnen, aber innerhalb des Fensters beendet wurden.

    • page. Fügen Sie diesen Parameter hinzu, damit die Antwort Paginierungsheader zurückgibt. Ohne page wird die Antwort auf die Standardseitengröße von 100 Einträgen begrenzt, ohne dass die Header Link, Total oder Per-Page zurückgegeben werden.

    • sort_column: Geben Sie das Feld an, nach dem die Datensätze sortiert werden sollen.

    • sort_direction. Geben Sie die Sortierrichtung der Datensätze in der Antwort an.

    Das folgende Bash-Beispielskript verwendet den Befehl curl:

    # 1. Define your environment variables (usually set in your shell or .env file)
    export API_HOSTNAME="ccaip-host.uc1.ccaiplatform.com"
    export API_USER="ccaip-host"
    export API_PASS="CCAI Platform API Key"
    
    # 2. Calculate the timestamp for 60 minutes ago in ISO 8601 format (UTC)
    # For macOS (BSD date):
    # TIMESTAMP=$(date -v-60M -u +"%Y-%m-%dT%H:%M:%SZ")
    # For Linux (GNU date):
    TIMESTAMP=$(date --date='60 minutes ago' -u +"%Y-%m-%dT%H:%M:%SZ")
    
    # 3. Execute the curl command
    # -u handles the Base64 encoding for Basic Auth automatically
    curl -g -u "${API_USER}:${API_PASS}" \
    "https://${API_HOSTNAME}/manager/api/v1/agent_activity_logs?started_at[from]=${TIMESTAMP}&sort_column=started_at&sort_direction=asc" | jq
    

    Die Agent Activity API gibt eine Antwort ähnlich der folgenden zurück:

    [
      {
        "id": 100,
        ...
        "started_at": "2025-01-01T00:00:00Z"
      },
      {
        "id": 98,
        ...
        "started_at": "2025-01-02T00:00:00Z"
      },
      {
        "id": 150,
        ...
        "started_at": "2025-01-03T00:00:00Z"
      }
    ]
    

    Es werden Antwortobjekte zurückgegeben, die am oder nach dem angegebenen Zeitstempel gestartet wurden, sortiert nach Datum in aufsteigender Reihenfolge. Verwenden Sie den Zeitstempel started_at des letzten Objekts in dieser Antwort für den Zeitstempel im nächsten Aufruf des Endpunkts.

  2. Rufen Sie den API-Endpunkt für Agentenaktivitäten 60 Minuten später noch einmal auf. Die aktualisierten Einträge im Aktivitätsprotokoll des KI-Agenten seit Ihrer letzten Anfrage werden zurückgegeben.

  3. Wiederholen Sie den vorherigen Schritt, um das Monitoring des Endpunkts fortzusetzen.