Panoramica sull'API Graph

L'API Graph è il metodo principale per estrarre e inserire dati nella Piattaforma Facebook. Si tratta di un'API di basso livello basata su HTTP che puoi usare per richiedere dati, pubblicare notizie, gestire inserzioni, caricare foto ed effettuare altre operazioni implementabili in un'app in modo programmatico.

Informazioni di base

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

  • Nodi - elementi come un utente, una foto, una Pagina o un commento.
  • Segmenti - le connessioni tra gli elementi sopra descritti, come le foto di una Pagina o i commenti a una foto.
  • Campi - informazioni sugli elementi, come il compleanno dell'utente o il nome di una Pagina.

L'API Graph è basata su HTTP, pertanto funziona con qualsiasi linguaggio dotato di una libreria HTTP, come cURL e urllib. La sezione successiva spiega in modo più approfondito cosa puoi fare con tale API, implicando che è possibile usarla direttamente nel browser, ad esempio una richiesta API Graph equivale a:

GET graph.facebook.com
  /facebook/picture?
    redirect=false

Nella maggior parte delle richieste API Graph, è necessario usare i token d'accesso, che l'app può generare implementando Facebook Login.

Questa panoramica spiega come l'API Graph è in grado di leggere e pubblicare dati nel social graph.

Struttura

L'argomento è spiegato in modo approfondito nella guida su come usare l'API Graph, ma in generale è possibile leggere le API eseguendo richieste HTTP GET ai nodi o ai relativi segmenti.

Quasi tutte le richieste vengono passate all'API su graph.facebook.com, a eccezione dei caricamenti video, che usano graph-video.facebook.com.

ID oggetto

A ogni nodo corrisponde un singolo ID, usato per accedere tramite l'API Graph. Non offriamo una documentazione specifica sulla struttura o sul formato degli ID oggetto/nodo, che con molta probabilità può cambiare nel tempo e le app non devono basarsi su quella attuale.

In questo esempio, l'ID viene usato per eseguire una richiesta a un nodo:

GET graph.facebook.com
  /{node-id}

o a un segmento:

GET graph.facebook.com
  /{node-id}/{edge-name}

In generale, puoi pubblicare nelle API eseguendo richieste HTTP POST con parametri al nodo:

POST graph.facebook.com
  /{node-id}

o a un segmento:

POST graph.facebook.com
  /{node-id}/{edge-name}

Per eliminare un elemento tramite le API, esegui richieste HTTP DELETE (e per aggiornarlo richieste POST) agli stessi endpoint.

Versioni dell'API

Sono disponibili diverse versioni dell'API Graph, accessibili in qualsiasi momento. Ognuna contiene una serie di campi e operazioni relative ai segmenti fondamentali. Garantiamo che, in ogni versione, le API fondamentali rimarranno disponibili e invariate per 2 anni dalla distribuzione. Il registro modifiche della piattaforma elenca le versioni attualmente disponibili.

Alcune operazioni, come la pubblicazione all'interno di un segmento o di determinati campi in un nodo, possono essere fondamentali senza che l'intero segmento o nodo lo siano. Nella documentazione di riferimento per l'API Graph, le API fondamentali sono contraddistinte dal simbolo .

Le API non fondamentali sono denominate API estese. L'accesso avviene attraverso percorsi con versione, ma è possibile che siano modificate o rimosse in qualsiasi momento, in quanto potenzialmente soggette alle migrazioni di 90 giorni annunciate nella roadmap della piattaforma. In alternativa, potrebbero essere incluse nella nuova versione dell'API.

Scopri di più sull'uso del controllo delle versioni nella nostra guida, in questo documento spiegheremo come effettuare una chiamata a una versione specifica dell'API Graph.

È semplice, inserisci l'identificatore della versione all'inizio del percorso della richiesta. Ad esempio, in una chiamata alla versione v2.2:

GET graph.facebook.com
  /v2.2/me

Questa forma generica funziona con tutte le versioni:

GET graph.facebook.com
  /vX.Y/{request-path}

X.Y è la versione richiesta. Nel registro modifiche è presente una lista completa delle versioni disponibili. La documentazione di riferimento per l'API Graph offre informazioni specifiche per ogni versione, pertanto assicurati di aver consultato la versione corretta (in alcune versioni nodi e segmenti sono stati rimossi, in altre sono stati aggiunti).

Ora ti mostreremo come sia semplice eseguire una richiesta API.

Caricamento del tool di esplorazione per la API Graph

Il metodo più semplice per comprendere l'API Graph è usarla con il tool di esplorazione per la API Graph, strumento di basso livello che permette di richiedere, aggiungere e rimuovere dati. Si tratta di una risorsa molto utile da avere a disposizione durante l'integrazione con Facebook. Nel prossimo passaggio dovrai quindi accedere al tool di esplorazione per la API Graph.

Tool di esplorazione per la API Graph

Creazione di un token d'accesso base per l'utente

Nella creazione della tua app, sarà necessario capire cosa sono i token d'accesso e come generarli usando Facebook Login, ma per il momento possiamo crearne velocemente uno attraverso il tool di esplorazione per la API Graph:

  1. Clicca sul pulsante Get Token in alto a destra.
  2. Seleziona l'opzione Get User Access Token.
  3. Nella finestra di dialogo che seguirà, non selezionare alcuna casella, clicca semplicemente sul pulsante blu Get Access Token.
  4. Visualizzerai la finestra di dialogo Accedi di Facebook, clicca su OK per proseguire.

Invio della prima richiesta

Ora puoi eseguire la tua prima richiesta API Graph, cominceremo con una di lettura. Cancella il testo nel campo accanto al pulsante a discesa "GET" (che chiameremo campo del percorso) e digita "me":

Successivamente, clicca sul pulsante "Invia". Dopo qualche secondo di elaborazione dovresti visualizzare una serie di informazioni nel pannello di risposta. Ciò che visualizzerai è determinato dalle impostazioni sulla privacy del tuo profilo, ma dovrebbero essere presenti almeno i campi fondamentali:

Le operazioni che hai eseguito nel tool di esplorazione per la API Graph equivalgono alla seguente richiesta di lettura alla stessa API:

GET graph.facebook.com
  /me

/me è un particolare endpoint che si traduce nell'ID utente della persona il cui token d'accesso è usato per eseguire la richiesta.

Congratulazioni, hai appena eseguito la tua prima richiesta API Graph!

Autorizzazioni di pubblicazione

Ora proveremo a pubblicare contenuti su Facebook mediante l'API Graph. Svolgi l'operazione all'interno dell'app solo se stai creando un composer personalizzato e non usi finestre di condivisione su Web, iOS o Android. Con le finestre di condivisione di Facebook non è necessario implementare Facebook Login o creare un'interfaccia personalizzata per permettere agli utenti di condividere contenuti.

Per sperimentare la pubblicazione con l'API Graph, clicca di nuovo sul pulsante "Ricevi token d'accesso" e seleziona l'autorizzazione publish_actions:

Successivamente, clicca sul pulsante blu "Ricevi token d'accesso" per visualizzare nuovamente la finestra di dialogo Accedi. Ti verrà chiesto di concedere al tool di esplorazione per la API Graph l'autorizzazione a pubblicare contenuti per tuo conto. Puoi modificare il pubblico in "Solo io" così da impedire che gli altri visualizzino il post, in ogni caso accetta la finestra per passare al passaggio successivo.

Pubblicazione di un post

Se hai richiesto l'autorizzazione publish_actions, clicca sul pulsante "GET" e scegli "POST" nello strumento di selezione a discesa che visualizzerai. Successivamente, inserisci me/feed nel campo del percorso e clicca su "Aggiungi un campo".

Nei nuovi campi, inserisci message come "name" e Hello, World come "value". Dovresti visualizzare un risultato simile a questo:

Clicca sul pulsante blu "Invia", dopo qualche secondo il pannello di risposta dovrebbe mostrare un risultato simile:

{
  "id": "{new-post-id}"
}

Hai appena pubblicato il tuo primo post tramite l'API Graph! Accedendo al tuo profilo dovresti essere in grado di visualizzarlo:

Le operazioni che hai svolto nel tool di esplorazione per la API Graph equivalgono alla seguente richiesta di pubblicazione alla stessa API:

POST graph.facebook.com
  /me/feed?
    message="Hello, World."&
    access_token={your-access-token}

Passaggi successivi

Una volta compresi gli elementi fondamentali, perché non scoprire di più sull'uso dell'API Graph? Se non l'hai già fatto, ti consigliamo di leggere la documentazione su Facebook Login e, in particolare, su come generare i token d'accesso, che ti permetteranno di eseguire richieste API Graph più complesse.