Impaginazione e coda

Questa pagina spiega come utilizzare l'impaginazione e il tailing quando chiami gli endpoint dell'API Manager.

Impaginazione

L'impaginazione è supportata per la maggior parte degli endpoint dell'API Manager. Per le eccezioni, vedi Eseguire il tailing di un endpoint per i record aggiornati.

Impostare le dimensioni della pagina

Per impostazione predefinita, gli endpoint dell'API Manager restituiscono pagine contenenti 100 record. Puoi modificare questo numero utilizzando il parametro di query per.

Per impostare le dimensioni delle pagine, utilizza il seguente endpoint:

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

In questo modo, le dimensioni della pagina vengono impostate su 50 record.

Richiedere una pagina specifica

Puoi richiedere una pagina specifica di record utilizzando il parametro di query page.

Per richiedere una pagina specifica, utilizza il seguente endpoint:

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

Viene restituita la seconda pagina di record.

Ottenere tutti i record disponibili

Per impostazione predefinita, l'API Manager restituisce 100 record in una pagina di risposta, anche se puoi modificare il numero di record in una pagina impostando le dimensioni della pagina. Per gli endpoint che supportano l'impaginazione, l'intestazione della risposta include il numero totale di record disponibili. Se questo numero supera le dimensioni della pagina, devi chiamare l'API più volte per ottenere tutti i record. L'API Manager non indica esplicitamente che sono presenti altri record da restituire.

Per ottenere tutti i record disponibili:

1. Chiama un endpoint API Manager che supporta l'impaginazione. Per ulteriori informazioni, vedi Impaginazione. L'intestazione della risposta indica il numero di record da restituire.

2. Confronta il numero di record da restituire con le dimensioni della pagina. Se il numero di record da restituire è inferiore alle dimensioni della pagina, tutti i record sono stati restituiti. In caso contrario, continua con il passaggio successivo.

3. Chiama di nuovo l'endpoint, specificando la pagina successiva di record. Per ulteriori informazioni, vedi Richiedere una pagina specifica. Ripeti questo passaggio finché non vengono restituiti tutti i record.

Eseguire il tailing di un endpoint per i record aggiornati

Google sconsiglia di utilizzare l'impaginazione per gli endpoint API delle attività di chiamata, chat, e agente perché non possiamo garantire risultati ottimali. Ti consigliamo invece di eseguire il tailing di questi endpoint API per i record aggiornati. Eseguire il tailing di un endpoint API significa chiamarlo continuamente per ottenere i record nuovi o aggiornati dall'ultima richiesta.

Eseguire il tailing dell'endpoint API Calls

Ogni volta che un record di chiamata viene modificato, il timestamp updated_at viene aggiornato. Puoi utilizzare il timestamp per specificare i record di chiamata che vuoi recuperare quando chiami l'endpoint API Calls.

Per eseguire il tailing dell'endpoint API Calls ogni 60 minuti:

1. Invia una richiesta all'endpoint API Calls (/manager/api/v1/calls), specificando i seguenti parametri di ricerca:

   • updated_at[from]. Specifica che vuoi i record aggiornati a partire da questa ora.

   • sort_column. Specifica il campo in base al quale ordinare i record.

   • sort_direction. Specifica la direzione di ordinamento dei record nella risposta.

   Di seguito è riportato un esempio di script Bash che utilizza il comando 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
   

   L'API Calls restituisce una risposta simile alla seguente:

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

   Gli oggetti di risposta aggiornati a partire dal timestamp specificato vengono restituiti, ordinati per data, in ordine crescente. Utilizza il timestamp updated_at dell'ultimo oggetto in questa risposta per il timestamp nella chiamata successiva all'endpoint.

2. Chiama l'endpoint API Calls 60 minuti dopo. Vengono restituiti i record di chiamata aggiornati dall'ultima richiesta.

3. Ripeti il passaggio precedente per continuare a eseguire il tailing dell'endpoint.

Eseguire il tailing dell'endpoint API Chats

Ogni volta che un record di chat viene modificato, il timestamp updated_at viene aggiornato. Puoi utilizzare il timestamp per specificare i record di chat che vuoi recuperare quando chiami l'endpoint API Chats.

Per eseguire il tailing dell'endpoint API Chats ogni 60 minuti:

1. Invia una richiesta all'endpoint API Chats (/manager/api/v1/chats), specificando i seguenti parametri di ricerca:

   • updated_at[from]. Specifica che vuoi i record aggiornati a partire da questa ora.

   • sort_column. Specifica il campo in base al quale ordinare i record.

   • sort_direction. Specifica la direzione di ordinamento dei record nella risposta.

   Di seguito è riportato un esempio di script Bash che utilizza il comando 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
   

   L'API Chats restituisce una risposta simile alla seguente:

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

   Gli oggetti di risposta aggiornati a partire dal timestamp specificato vengono restituiti, ordinati per data, in ordine crescente. Utilizza il timestamp updated_at dell'ultimo oggetto in questa risposta per il timestamp nella chiamata successiva all'endpoint.

2. Chiama di nuovo l'endpoint API 60 minuti dopo. Vengono restituiti i record di chat aggiornati dall'ultima richiesta.

3. Ripeti il passaggio precedente per continuare a eseguire il tailing dell'endpoint.

Eseguire il tailing dell'endpoint API Agent Activity

A differenza dei record di chat e chiamata, i log delle attività degli agenti non vengono aggiornati e, di conseguenza, non hanno un timestamp updated_at. Puoi utilizzare il timestamp started_at per specificare i record di attività che vuoi recuperare quando chiami l'endpoint API Agent Activity.

Per eseguire il tailing dell'endpoint API Agent Activity ogni 60 minuti:

1. Invia una richiesta all'endpoint API Agent Activity (/manager/api/v1/agent_activity_logs), specificando i seguenti parametri di query:

   • started_at[from]. Specifica che vuoi i log delle attività avviati a partire da questa ora.

   • sort_column. Specifica il campo in base al quale ordinare i record.

   • sort_direction. Specifica la direzione di ordinamento dei record nella risposta.

   Di seguito è riportato un esempio di script Bash che utilizza il comando 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
   

   L'API Agent Activity restituisce una risposta simile alla seguente:

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

   Gli oggetti di risposta avviati a partire dal timestamp specificato vengono restituiti, ordinati per data, in ordine crescente. Utilizza il timestamp started_at dell'ultimo oggetto in questa risposta per il timestamp nella chiamata successiva all'endpoint.

2. Chiama di nuovo l'endpoint API Agent Activity 60 minuti dopo. Vengono restituiti i record dei log delle attività degli agenti aggiornati dall'ultima richiesta.

3. Ripeti il passaggio precedente per continuare a eseguire il tailing dell'endpoint.