Uso dell'API Graph

La panoramica sull'API Graph include nozioni principali sulla terminologia e sulla struttura dell'API. Questo documento approfondisce le varie operazioni che puoi eseguire tramite l'API Graph.

HTTP/1.1

Tutti i trasferimenti dati conformi al protocollo HTTP/1.1 e tutti gli endpoint richiedono il protocollo HTTPS. Abbiamo anche abilitato la direttiva HSTS includeSubdomains in facebook.com, tuttavia non dovrebbe avere conseguenze negative sulle tue chiamate all'API Graph.

URL host

Quasi tutte le richieste vengono trasmesse all'URL host graph.facebook.com. L'unica eccezione è costituita dal caricamento di video, che prevede l'uso di graph-video.facebook.com.

Token d'accesso

I token d'accesso consentono alla tua app di accedere all'API Graph. Di solito, sono responsabili di due funzioni:

  • Consentono alla tua app di accedere alle informazioni sull'utente senza la richiesta della relativa password.
  • Ci permettono di identificare la tua app, l'utente che la usa e il tipo di dati per cui l'utente ha concesso l'autorizzazione di accesso alla tua app.

Tutti gli endpoint dell'API Graph richiedono un token d'accesso, pertanto ogni volta che accedi a un endpoint, la richiesta deve includerne uno.

Funzionamento dei token

I token d'accesso sono conformi al protocollo OAuth 2.0. OAuth 2.0 consente alle entità come utenti o Pagine di autorizzare i token. Di solito, ciò avviene attraverso un'interfaccia web. Dopo l'autorizzazione, le app possono usare tali token per accedere a specifiche informazioni.

Ad esempio, questa app richiede all'utente l'autorizzazione per l'accesso alle sue foto, ai suoi video e al suo indirizzo e-mail:

Come puoi vedere, si tratta di un'interfaccia di Facebook. L'utente ha appena usato l'interfaccia per accedere al proprio account e, in questo modo, abbiamo potuto autenticarlo. Se l'utente decide di continuare, sostituiremo il token precedente (uno dell'app) con uno nuovo (un token dell'utente). A questo punto, l'app può usare il nuovo token dell'utente per effettuare le richieste all'API Graph, ma può accedere solo alle foto, ai video e all'indirizzo e-mail di quello specifico utente.

Questo attributo dei token d'accesso è molto importante. L'ID app e l'ID utente sono entrambi codificati nel token stesso (insieme ad altri elementi) e usiamo questi ID per tenere traccia dei dati a cui l'utente ha concesso l'autorizzazione di accesso all'app. Ad esempio, analizzando il token dopo che l'utente concede l'autorizzazione, accederesti a queste informazioni:

I token sono estremamente preziosi, poiché autorizzano l'accesso ai dati di un utente e possono essere usati da chiunque, pertanto prendi le dovute precauzioni quando li usi nelle tue query. Il modo più semplice per farlo consiste nell'usare Facebook Login per le gestione dei token.

Facebook Login

OAuth 2.0 prevede numerosi reindirizzamenti, richieste di accesso e sostituzioni di token, pertanto abbiamo creato il prodotto Facebook Login per semplificare il tutto. Facebook Login offre funzioni e metodi facili da usare per tutti i nostri SDK, che semplificano l'uso dei token d'accesso rispetto alla creazione di soluzioni personalizzate.

Per scoprire di più sui token d'accesso e su Facebook Login o per scoprire come creare la tua soluzione personalizzata, consulta la nostra documentazione su Facebook Login.

Lettura

Nodi

Le operazioni di lettura iniziano quasi sempre con un nodo. I nodi sono singoli oggetti con ID univoci. Ad esempio, esistono diversi oggetti dei nodi delle Pagine, ognuno con un ID univoco. La Pagina Coca-Cola è l'unica con ID 820882001277849. Per leggere un nodo, devi effettuare una query rispetto allo specifico ID dell'oggetto. Pertanto, per leggere il nodo della Pagina Coca-Cola, devi effettuare una query rispetto al relativo ID:

GET https://graph.facebook.com/820882001277849

Questa richiesta restituisce i campi seguenti (proprietà del nodo) per impostazione predefinita, in formato JSON:

{
  "name": "Coca-Cola",
  "id": "820882001277849"
}

Segmenti

I nodi presentano segmenti che, di solito, restituiscono raccolte di altri nodi a essi collegati. Per leggere un segmento, devi includere l'ID nodo e il nome del segmento nel percorso. Ad esempio, i nodi /page presentano un segmento /feed in grado di restituire tutti i nodi dei post di una Pagina. Ecco come puoi usare il segmento per ottenere tutti i post della Pagina Coca-Cola.

GET https://graph.facebook.com/820882001277849/feed

La risposta JSON si presenta in questo modo:

{
  "data": [
    {
      "created_time": "2017-12-08T01:08:57+0000",
      "message": "Love this puzzle. One of my four coke puzzles",
      "id": "820882001277849_1805191182846921"
    },
    {
      "created_time": "2017-12-07T20:06:14+0000",
      "message": "You need to add grape as a flavor for Coke in your freestyle machines.",
      "id": "820882001277849_1804966026202770"
    },
    {
      "created_time": "2017-12-07T01:29:12+0000",
      "message": "Plz play the old commercial’s with the polar bears. Would be nice to see them this holiday",
      "id": "820882001277849_1804168469615859"
    }
  ]
}

Tieni presente che, oltre agli ID dei nodi dei post nella raccolta, la risposta contiene anche i campi created_time e message. Si tratta di una situazione comune. La maggior parte dei segmenti include uno o più campi per impostazione predefinita.

Campi

I campi sono proprietà dei nodi. Quando effettui una query per un nodo, viene restituito un insieme di campi per impostazione predefinita, come negli esempi precedenti. Tuttavia, puoi specificare i campi da restituire usando il parametro fields ed elencando ogni campo. In questo modo, ignori i valori predefiniti e ti vengono restituiti solo i campi specificati, insieme all'ID dell'oggetto, che viene restituito in ogni caso.

Ad esempio, il riferimento per il nodo della Pagina indica quali campi puoi richiedere quando leggi un nodo della Pagina. Per ottenere i campi about, fan_count, website della Pagina Coca-Cola, puoi eseguire questa operazione:

GET https://graph.facebook.com/820882001277849
    ?fields=about,fan_count,website

In questo modo, viene restituita la risposta seguente:

{
  "about": "Welcome to the happiest Facebook page on, um, Facebook.",
  "fan_count": 106714402,
  "website": "http://coca-cola.com",
  "id": "820882001277849"
}

I segmenti, che di solito restituiscono raccolte di oggetti, restituiscono anche i campi relativi a ogni oggetto della raccolta. Immaginiamo che tu abbia usato il segmento /photos per ottenere tutti i nodi delle foto della Pagina Coca-Cola:

GET https://graph.facebook.com/820882001277849/photos

In questo modo, viene generata una risposta che si presenta così:

{
  "data": [
    {
      "created_time": "2016-08-23T13:12:10+0000",
      "id": "1308573619175349"
    },
    {
      "created_time": "2016-08-05T22:34:19+0000",
      "id": "1294456907253687"
    },
    {
      "created_time": "2016-04-29T16:17:02+0000",
      "id": "1228552183844160"
    }
  ]
}

Come puoi vedere, il segmento /photos restituisce per impostazione predefinita una raccolta di ID dei nodi delle foto, nonché la proprietà created_time di ogni foto. Proprio come con i nodi, puoi usare il parametro fields per specificare i campi da restituire per ogni oggetto restituito nella raccolta.

Immaginiamo di voler ottenere i campi height, width e link (URL) per ogni nodo delle foto restituito dal segmento /photos:

GET https://graph.facebook.com/820882001277849/photos
      ?fields=height,width,link

La risposta si presenterà in questo modo:

{
  "data": [
    {
      "height": 720,
      "width": 720,
      "link": "https://www.facebook.com/CocaColaUnitedStates/photos/a.820887414610641.1073741825.820882001277849/1308573619175349/?type=3",
      "id": "1308573619175349"
    },
    {
      "height": 720,
      "width": 720,
      "link": "https://www.facebook.com/CocaColaUnitedStates/photos/a.820887414610641.1073741825.820882001277849/1294456907253687/?type=3",
      "id": "1294456907253687"
    },
    {
      "height": 180,
      "width": 180,
      "link": "https://www.facebook.com/CocaColaUnitedStates/photos/a.820887414610641.1073741825.820882001277849/1228552183844160/?type=3",
      "id": "1228552183844160"
    }
  ]
}

Tieni presente che puoi anche specificare un segmento con il parametro fields, utile quando usi l'espansione dei campi.

Espansione dei campi

Se hai testato la query GET /page/photos precedente nel tool di esplorazione per la API Graph, probabilmente hai notato che la richiesta ha restituito più di tre oggetti, oltre ad aver paginato i risultati. Si tratta di una situazione comune per quasi tutti i segmenti. Affronteremo presto i risultati trasversali, per adesso osserviamo l'espansione dei campi, che ti consente non solo di effettuare query nidificate ma anche di limitare e ordinare i risultati.

Limitazione dei risultati

La limitazione ti consente di controllare il numero degli oggetti restituiti in ogni insieme di risultati paginati. Per limitare i risultati, aggiungi un argomento .limit() a qualsiasi campo o segmento.

Ad esempio, una richiesta GET sul segmento /feed della Pagina Coca-Cola potrebbe restituire centinaia di post. Puoi limitare il numero dei post restituiti per ogni pagina dei risultati tramite questa operazione:

GET https://graph.facebook.com/820882001277849
    ?fields=feed.limit(3)

In questo modo, vengono restituiti tutti i post della Pagina Coca-Cola, limitando però il numero di oggetti di ogni pagina dei risultati a tre. Tieni presente che, anziché specificare il segmento del feed nell'URL del percorso (/page/feed), devi specificarlo nel parametro fields (?fields=feed), che ti consente di aggiungere l'argomento .limit(3).

Ecco i risultati della query:

{
  "feed": {
    "data": [
      {
        "created_time": "2017-12-12T01:24:21+0000",
        "message": "This picture of my grandson with Santa screams Coca Cola",
        "id": "820882001277849_1809387339093972"
      },
      {
        "created_time": "2017-12-11T23:40:17+0000",
        "message": ":)",
        "id": "820882001277849_1809316002434439"
      },
      {
        "created_time": "2017-12-11T23:31:38+0000",
        "message": "Thought you might enjoy this.  My horse loves Coke!",
        "id": "820882001277849_1809310929101613"
      }
    ],
    "paging": {
      "cursors": {
        "before": "Q2c4U1pXNTBYM0YxWlhKNVgzTjBiM0o1WDJsa0R5UTRNakE0T0RJd01ERXlOemM0TkRrNkxUVXdPRE16TXpVM01EQXpNVFUwTkRRME5Ua1BER0ZA3YVY5emRHOXllVjlwWkE4ZA09ESXdPRGd5TURBeE1qYzNPRFE1WHpFNE1Ea3pPRGN6TXprd09UTTVOeklQQkhScGJXVUdXaTh2eFFFPQZDZD",
        "after": "Q2c4U1pXNTBYM0YxWlhKNVgzTjBiM0o1WDJsa0R5TTRNakE0T0RJd01ERXlOemM0TkRrNk1UTTJORE01T0RVNU1UZAzVPRGMyTnpFNE1BOE1ZAWEJwWDNOMGIzSjVYMmxrRHlBNE1qQTRPREl3TURFeU56YzRORGxmTVRnd09USXdOamsxTlRjM09EWTNOdzhFZAEdsdFpRWmFMdk9HQVE9PQZDZD"
      },
      "next": "https://graph.facebook.com/820882001277849/feed?access_token=valid_token_goes_here"
    }
  },
  "id": "820882001277849"
}

Come puoi vedere, solo tre oggetti vengono visualizzati nella pagina dei risultati paginati, ma la risposta include un campo next e un URL che puoi usare per il recupero della pagina successiva.

Ordinamento dei risultati

Puoi ordinare i risultati in base all'ora di creazione dell'oggetto. A tale scopo, usa un argomento .order() con uno dei valori seguenti su un campo o un segmento.

  • chronological: ordina i risultati a partire dagli oggetti meno recenti.
  • reverse_chronological: ordina i risultati a partire dagli oggetti più recenti.

Ad esempio, acquisiamo tutti i commenti di uno dei post con video della Pagina Coca-Cola (1809938745705498), ordiniamo i risultati in modo cronologico (prima i meno recenti) e limitiamo il numero di oggetti per risultato paginato a tre:

GET https://graph.facebook.com/1809938745705498
    ?fields=comments.order(chronological).limit(3)

Ancora una volta, tieni presente che per usare un argomento su un segmento, devi specificare quest'ultimo nel parametro fields. Come puoi vedere, puoi unire gli argomenti .limit() e .order() in un unico campo o segmento.

Ecco i risultati:

{
  "comments": {
    "data": [
      {
        "created_time": "2017-12-12T14:12:20+0000",
        "message": ":) :) :)",
        "id": "1809938745705498_1809939942372045"
      },
      {
        "created_time": "2017-12-12T14:14:03+0000",
        "message": "seasons greetings!",
        "id": "1809938745705498_1809941802371859"
      },
      {
        "created_time": "2017-12-12T14:14:11+0000",
        "message": "My bestie <3",
        "id": "1809938745705498_1809941879038518"
      }
    ],
    "paging": {
      "cursors": {
        "before": "WTI5dGJXVnVkRjlqZAFhKemIzSTZANVGd3T1Rrek9UZAzROVGN3TlRNNE5Eb3hOVEV6TURnM09UTTIZD",
        "after": "WTI5dGJXVnVkRjlqZAFhKemIzSTZANVGd4TURBd09UazROVFk1T0RNM05Eb3hOVEV6TURreU5qQXoZD"
      },
      "next": "https://graph.facebook.com/1809938745705498/comments?access_token=valid_token_goes_here"
    }
  },
  "id": "1809938745705498"
}

Pubblicazione

La maggior parte dei segmenti ti consente di pubblicare oggetti in una raccolta su un nodo. A tale scopo, puoi usare una richiesta POST sul segmento del nodo. Ad esempio, puoi pubblicare un commento su una foto tramite il segmento /comments del nodo della foto:

POST https://graph.facebook.com
  /1809938745705498
    /comments
      ?message=Awesome!

In caso di operazione eseguita correttamente, la maggior parte dei segmenti restituisce l'ID dell'oggetto che hai appena pubblicato, spesso una combinazione dell'ID dell'oggetto pubblicato e di una nuova stringa ID:

{
  "id": "1809938745705498_1810399758992730"
}

Di solito, la pubblicazione richiede autorizzazioni aggiuntive, pertanto consulta la documentazione di riferimento di ogni segmento per conoscere le autorizzazioni richieste caso per caso.

Il token d'accesso usato per la pubblicazione dell'oggetto potrebbe influire sull'aspetto di quest'ultimo. Se viene usato un token d'accesso della Pagina, si presenterà come se fosse la Pagina a pubblicare l'oggetto, mentre il token d'accesso dell'utente renderà l'oggetto come se fosse pubblicato da una persona.

Diversi segmenti, inoltre, supportano funzioni avanzate, come la lettura dopo la scrittura, che ti consente di leggere immediatamente un oggetto appena pubblicato e la pubblicazione in batch

Aggiornamento

Puoi eseguire operazioni di aggiornamento su un nodo esistente tramite le richieste POST. Ad esempio, per aggiornare il campo message in un commento esistente, puoi eseguire questa operazione:

POST https://graph.facebook.com
  /1809938745705498_1810399758992730
    ?message=Happy%20Holidays!

In caso di operazione eseguita correttamente, il nodo restituisce un campo success e un valore di true:

{
  "success": true
}

Come per le operazioni di pubblicazione, quelle di aggiornamento richiedono autorizzazioni aggiuntive, indicate nella documentazione di riferimento di ogni nodo. E, come per la maggior parte dei segmenti, diversi nodi supportano la lettura dopo la scrittura.

Eliminazione

Di solito, puoi eliminare un nodo tramite un'operazione DELETE:

DELETE https://graph.facebook.com
  /1809938745705498_1810399758992730

In caso di operazione eseguita correttamente, il nodo restituisce un campo success e un valore di true:

{
  "success": true
}

Di solito, puoi eliminare solo i nodi creati da te, tuttavia ti consigliamo di consultare le guide di riferimento di ogni nodo per vedere i requisiti per le operazioni di eliminazione.

Per il supporto dei client non compatibili con tutti i metodi HTTP, puoi inviare una richiesta POST al nodo e includere il parametro method=delete, nonché il valore per sovrascrivere il metodo HTTP:

POST https://graph.facebook.com
  /1809938745705498_1810399758992730
    ?method=delete

Risultati paginati

Se esegui una richiesta API a un nodo o a un segmento, di solito non ricevi tutti i risultati in un'unica risposta. Questo poiché alcune risposte potrebbero contenere migliaia di oggetti, pertanto la maggior parte 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 ogni volta che è possibile. Un cursore si riferisce a una stringa casuale di caratteri che contrassegna un determinato elemento in un elenco di dati. A meno che l'elemento non venga eliminato, il cursore punterà sempre alla stessa parte dell'elenco e diventerà non valido una volta rimosso l'elemento. Per questo motivo, la tua app non deve memorizzare i cursori e ritenere che siano validi in futuro.

Leggendo un segmento che supporta la paginazione basata sul cursore, visualizzerai la seguente risposta JSON:

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

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

  • before: si tratta del cursore che punta all'inizio della pagina di dati restituita.
  • after: si tratta del cursore che punta alla fine della pagina di dati restituita.
  • limit: questo è 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 dei 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 è stato rimosso a causa dei filtri per la privacy. Per motivi legati alle prestazioni, alcuni segmenti possono fissare anche 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, sarà l'ultima pagina di dati. Date le modalità con cui la paginazione usa la visibilità e la privacy, è possibile che una pagina sia vuota ma contenga un link per proseguire a quella successiva. Interrompi la paginazione se il link non viene visualizzato.
  • previous: l'endpoint API Graph che restituisce la pagina di dati precedente. Se non è incluso sarà la prima pagina di dati.

Non memorizzare i cursori, poiché diventano subito non validi in caso di elementi aggiunti o eliminati.

Paginazione basata sul tempo

La paginazione basata sul tempo è usata per navigare mediante i dati restituiti usando il tempo Unix, che punta a determinati parametri temporali in un elenco di dati.

Usando un endpoint che sfrutta la paginazione basata sul tempo, visualizzerai la seguente risposta JSON:

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

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

  • until: un parametro temporale Unix o un valore strtotime che punta alla fine di una serie di dati basati sul tempo.
  • since: un parametro temporale Unix o un valore strtotime che punta all'inizio di una serie di dati basati sul tempo.
  • limit: questo è 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 dei 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 è stato rimosso a causa dei filtri per la privacy. Per motivi legati alle prestazioni, alcuni segmenti possono fissare anche 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.

Per risultati coerenti, specifica entrambi i parametri since e until. Inoltre, è consigliabile che la differenza massima di tempo sia di 6 mesi.

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: questo è 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 dei 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 è stato rimosso a causa dei filtri per la privacy. Per motivi legati alle prestazioni, alcuni segmenti possono fissare anche 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, sarà l'ultima pagina di dati. Date le modalità con cui la paginazione usa la visibilità e la privacy, è possibile che una pagina sia vuota ma contenga un link per proseguire a quella successiva. Interrompi la paginazione se il link non viene visualizzato.
  • previous: l'endpoint API Graph che restituisce la pagina di dati precedente. Se non è incluso sarà la prima pagina di dati.

Tieni presente che, se all'elenco di oggetti sottoposto a paginazione ne vengono aggiunti di nuovi, i contenuti di ogni pagina basata sull'offset cambieranno.

La paginazione basata sull'offset non è supportata per tutte le chiamate API. Per ottenere risultati coerenti, ti consigliamo di eseguire la paginazione sfruttando i link per proseguire alla pagina successiva o tornare a quella precedente, restituiti nella risposta.