Risultati paginati

La panoramica sull'API Graph include le nozioni di base sulla terminologia e sulla struttura dell'API Graph. Questo documento approfondisce i risultati provenienti dalle richieste API.

Risultati paginati trasversali

Se invii una richiesta API a un nodo o a un segmento, di solito non ricevi tutti i risultati in un'unica risposta, perché alcune risposte potrebbero contenere migliaia di oggetti e quindi la maggior parte di esse viene paginata per impostazione predefinita.

Paginazione basata sul cursore

La paginazione basata sul cursore rappresenta il metodo più efficace per la paginazione e deve essere usata quando possibile. Un cursore è una stringa casuale di caratteri che contrassegna un determinato elemento in una lista di dati. Il cursore punterà sempre a quell'elemento, ma sarà reso non valido se l'elemento viene eliminato o rimosso. La tua app non deve quindi archiviare i cursori o ritenere che saranno validi in futuro.

Quando leggi un segmento che supporta la paginazione basata sul cursore, viene visualizzata la seguente risposta JSON:

{
  "data": [
     ... Endpoint data is here
  ],
  "paging": {
    "cursors": {
      "after": "MTAxNTExOTQ1MjAwNzI5NDE=",
      "before": "NDMyNzQyODI3OTQw"
    },
    "previous": "https://graph.facebook.com/{your-user-id}/albums?limit=25&before=NDMyNzQyODI3OTQw"
    "next": "https://graph.facebook.com/{your-user-id}/albums?limit=25&after=MTAxNTExOTQ1MjAwNzI5NDE="
  }
}

Un segmento paginato in base al cursore supporta i seguenti parametri:

• before: il cursore che punta all'inizio della pagina di dati restituita.
• after: il cursore che punta alla fine della pagina di dati restituita.
• limit: il numero massimo di oggetti che potrebbero essere restituiti. Una query potrebbe restituire un numero di oggetti inferiore rispetto al valore di limit a causa dell'applicazione di filtri. Per indicare che la tua query ha raggiunto la fine della lista di dati, non ti basare sul numero di risultati inferiore rispetto al valore di limit. Usa invece l'assenza di next come descritto di seguito. Ad esempio, se imposti limit su 10 e vengono restituiti 9 risultati, potrebbero essere disponibili altri dati, ma un elemento potrebbe essere stato rimosso a causa dell'applicazione di filtri per la privacy. Per motivi legati alle prestazioni, per alcuni segmenti potrebbe anche essere definito un massimo per il valore di limit. In tutti i casi, l'API restituisce i link di paginazione corretti.
• next: l'endpoint API Graph che restituisce la pagina di dati successiva. Se non è incluso, la pagina corrente è l'ultima pagina di dati. Date le modalità con cui funziona la paginazione con visibilità e privacy, è possibile che una pagina sia vuota, ma contenga un link di paginazione next. Interrompi la paginazione quando il link next non viene più visualizzato.
• previous: l'endpoint API Graph che restituisce la pagina di dati precedente. Se non è incluso, la pagina corrente è la prima pagina di dati.

Paginazione basata sul tempo

La paginazione basata sul tempo è usata per navigare nei dati dei risultati utilizzando le marche temporali Unix, che puntano a determinati parametri temporali in una lista di dati.

Quando utilizzi un endpoint che usa la paginazione basata sul tempo, viene visualizzata la seguente risposta JSON:

{
  "data": [
     ... Endpoint data is here
  ],
  "paging": {
    "previous": "https://graph.facebook.com/{your-user-id}/feed?limit=25&since=1364849754",
    "next": "https://graph.facebook.com/{your-user-id}/feed?limit=25&until=1364587774"
  }
}

Un segmento paginato in base al tempo supporta i seguenti parametri:

• until: una marca temporale Unix o un valore di dati strtotime che punta alla fine di una serie di dati basati sul tempo.
• since: una marca temporale Unix o un valore di dati strtotime che punta all'inizio di una serie di dati basati sul tempo.
• limit: il numero massimo di oggetti che potrebbero essere restituiti. Una query potrebbe restituire un numero di oggetti inferiore rispetto al valore di limit a causa dell'applicazione di filtri. Per indicare che la tua query ha raggiunto la fine della lista di dati, non ti basare sul numero di risultati inferiore rispetto al valore di limit. Usa invece l'assenza di next come descritto di seguito. Ad esempio, se imposti limit su 10 e vengono restituiti 9 risultati, potrebbero essere disponibili altri dati, ma un elemento potrebbe essere stato rimosso a causa dell'applicazione di filtri per la privacy. Per motivi legati alle prestazioni, per alcuni segmenti potrebbe anche essere definito un massimo per il valore di limit. In tutti i casi, l'API restituisce i link di paginazione corretti.
• next: l'endpoint API Graph che restituisce la pagina di dati successiva.
• previous: l'endpoint API Graph che restituisce la pagina di dati precedente.

Paginazione basata sull'offset

La paginazione basata sull'offset può essere usata quando la cronologia non è importante e desideri solo che ti sia restituito un determinato numero di oggetti. Usala solo se il segmento non supporta la paginazione basata sul cursore o sul tempo.

Un segmento paginato in base all'offset supporta i seguenti parametri:

• offset: determina l'inizio di ogni pagina secondo il numero specificato.
• limit: il numero massimo di oggetti che potrebbero essere restituiti. Una query potrebbe restituire un numero di oggetti inferiore rispetto al valore di limit a causa dell'applicazione di filtri. Per indicare che la tua query ha raggiunto la fine della lista di dati, non ti basare sul numero di risultati inferiore rispetto al valore di limit. Usa invece l'assenza di next come descritto di seguito. Ad esempio, se imposti limit su 10 e vengono restituiti 9 risultati, potrebbero essere disponibili altri dati, ma un elemento potrebbe essere stato rimosso a causa dell'applicazione di filtri per la privacy. Per motivi legati alle prestazioni, per alcuni segmenti potrebbe anche essere definito un massimo per il valore di limit. In tutti i casi, l'API restituisce i link di paginazione corretti.
• next: l'endpoint API Graph che restituisce la pagina di dati successiva. Se non è incluso, la pagina corrente è l'ultima pagina di dati. Date le modalità con cui funziona la paginazione con visibilità e privacy, è possibile che una pagina sia vuota, ma contenga un link di paginazione next. Interrompi la paginazione quando il link next non viene più visualizzato.
• previous: l'endpoint API Graph che restituisce la pagina di dati precedente. Se non è incluso, la pagina corrente è la prima pagina di dati.

Tieni presente che, se alla lista di elementi sottoposta a paginazione vengono aggiunti nuovi oggetti, i contenuti di ogni pagina basata sull'offset cambieranno.

Per oggetti con molti elementi restituiti, ad esempio commenti che possono essere nell'ordine di decine di migliaia, potresti riscontrare dei limiti durante la paginazione. L'API restituirà un errore quando la tua app avrà raggiunto il limite del cursore:

{
  "error": {
    "message": "(#100) The After Cursor specified exceeds the max limit supported by this endpoint",
    "type": "OAuthException",
    "code": 100
  }
}

Passaggi successivi

Ora che hai maggiore familiarità con l'API Graph, visita la nostra Guida al tool di esplorazione per la API Graph per esplorare l'API Graph senza scrivere codice, gli usi comuni per visualizzare le attività più comuni eseguite e gli SDK disponibili.