Panoramica

L'API Graph è il metodo principale per permettere ai dati di entrare e uscire dalla Piattaforma Facebook. Si tratta di un'API di basso livello basata su HTTP che le app possono usare per effettuare query sui dati, pubblicare notizie, gestire inserzioni, caricare foto ed effettuare altre operazioni in modo programmatico.

Informazioni di base

Il nome API Graph deriva dal concetto di "social graph", ovvero una rappresentazione delle informazioni presenti su Facebook. Questa è composta da:

  • nodi, ovvero oggetti singoli, come utenti, foto, Pagine o commenti.
  • segmenti, connessioni tra una raccolta di oggetti e un singolo oggetto, ad es. le foto di una Pagina o i commenti su una foto.
  • campi, dati relativi a un oggetto, ad es. il compleanno dell'utente o il nome di una Pagina.

Di solito, usi i nodi per ottenere dati circa un oggetto specifico, usi i segmenti per ottenere raccolte di oggetti su un singolo oggetto e usi i campi per ottenere dati su un singolo oggetto o su ogni oggetto di una raccolta.

HTTP

L'API Graph è basata su HTTP, pertanto funziona con qualsiasi linguaggio dotato di una libreria HTTP, come cURL e urllib. Di conseguenza, puoi usare l'API Graph direttamente nel browser. Ad esempio, richiedere questo URL nel tuo browser:

https://graph.facebook.com/facebook/picture?redirect=false

equivale a eseguire questa richiesta cURL:

curl -i -X GET \
 "https://graph.facebook.com/facebook/picture?redirect=false&access_token={valid-access-token-goes-here}"

Token d'accesso

Avrai notato il parametro access_token e il valore del placeholder nella richiesta cURL precedente. La maggior parte delle richieste all'API Graph richiede un token d'accesso. In definitiva, devi conoscere il funzionamento dei token d'accesso. A tale scopo, consulta la nostra documentazione sui token d'accesso. Tuttavia, al momento, tutto ciò che devi sapere è questo:

  • quasi tutte le richieste all'API Graph richiedono un token d'accesso.
  • Inoltre, il modo più semplice per ottenere i token d'accesso è attraverso l'implementazione di Facebook Login.

Gli esempi di richieste/risposte in pseudo codice contenuti in tutta la nostra documentazione sull'API Graph non presentano riferimenti espliciti ai token d'accesso, tuttavia devi presupporre che un token d'accesso sia stato incluso nella richiesta, dato che è stata ottenuta una risposta.

Struttura

Trattiamo questo argomento in modo completo nella nostra guida all'uso dell'API Graph, tuttavia, in generale:

  • Usa i nodi per ottenere dati su singoli oggetti.
  • Usa i segmenti per ottenere raccolte di oggetti connessi a un nodo o per pubblicare oggetti in tali raccolte.
  • Usa i campi per specificare i dati da includere nelle risposte.

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.

ID oggetto

I nodi sono singoli oggetti, ognuno dei quali è dotato di un ID univoco, pertanto, per ottenere informazioni su un nodo, devi effettuare una query diretta al relativo ID. Ad esempio, la Pagina Facebook ufficiale presenta l'ID 20531316728. Puoi effettuare una query usando direttamente tale ID:

GET graph.facebook.com
  /20531316728

Per ottenere dati specifici (noti come campi) su un nodo, puoi includere il parametro fields e specificare i campi che la risposta deve restituire. Consultando rapidamente il riferimento per il nodo della Pagina, puoi notare che uno dei campi che è possibile ottenere durante la lettura di un oggetto della Pagina è il campo cover, ovvero l'immagine di copertina della Pagina. Ecco come si presenta la relativa query:

GET graph.facebook.com
  /20531316728?fields=cover

La maggior parte dei nodi presenta segmenti, in grado di restituire raccolte di oggetti connessi a tale nodo. Per effettuare una query rispetto a un segmento, usa l'ID nodo e il nome del segmento. Uno dei segmenti elencati nel riferimento per il nodo della Pagina è il segmento photos, che restituisce tutti gli oggetti delle foto appartenenti alla Pagina. Pertanto, per acquisire tutte le foto appartenenti alla Pagina Facebook, devi effettuare una query rispetto al segmento photos del nodo:

GET graph.facebook.com
  /20531316728/photos

Alcuni nodi ti consentono di aggiornare i campi con operazioni POST. Ad esempio, se tu fossi un amministratore della Pagina Facebook, potresti aggiornarne il campo description in questo modo:

POST graph.facebook.com
  /20531316728?description=The%20OFFICIAL%20Facebook%20Page

Spesso, i segmenti ti consentono di pubblicare nuovi oggetti nelle raccolte del nodo, tramite operazioni POST. Ecco come pubblicare una foto nella raccolta di foto appartenente alla Pagina Facebook:

POST graph.facebook.com
  /20531316728/photos

Naturalmente, la pubblicazione di un oggetto in una raccolta, di solito richiede campi aggiuntivi relativamente a tale oggetto, ad esempio l'URL di una foto o un titolo o, ancora, una descrizione. La documentazione di riferimento relativa ai segmenti indica i campi obbligatori e quelli facoltativi.

Infine, di solito puoi eliminare un nodo tramite un'operazione DELETE sull'ID oggetto:

DELETE graph.facebook.com
  /20531316728

Versioni

L'API Graph è disponibile in varie versioni. Scopri di più sul controllo delle versioni nella nostra guida alle versioni dell'app, in questo documento spiegheremo come effettuare una chiamata a una versione specifica.

È semplicissimo: ti basta aggiungere la lettera v seguita dal numero di versione all'inizio del percorso richiesto. Ad esempio, in una chiamata alla versione 2.9:

GET graph.facebook.com
  /v2.9/20531316728/photos

Se non includi un numero di versione, l'impostazione predefinita prevede la versione meno recente disponibile, pertanto è consigliabile includere sempre il numero di versione nelle tue richieste.

Il registro modifiche dell'API Graph indica tutte le versioni disponibili, mentre la nostra documentazione di riferimento ti consente i filtrare i contenuti in base alla versione.

Passaggi successivi

A questo punto, consulta Uso dell'API Graph per osservare richieste più elaborate e le relative risposte, nonché per vedere le altre azioni che puoi eseguire grazie all'API Graph.