Panoramica

L'API Graph è il modo principale per inserire ed estrarre dati dalla Piattaforma Facebook. È un'API basata su HTTP che le app possono utilizzare per eseguire query sui dati a livello di programmazione, pubblicare nuove storie, gestire inserzioni, caricare foto ed eseguire un'ampia varietà di altre attività.

L'API Graph prende il nome dall'idea di un "social graph", una rappresentazione delle informazioni su Facebook. Si compone di nodi, segmenti e campi. 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. All'interno della nostra documentazione, con "endpoint" potremmo fare riferimento sia a un nodo che a un segmento. Ad esempio, "invia una richiesta GET all'endpoint User".

HTTP

Tutti i trasferimenti dati conformi al protocollo HTTP/1.1 e tutti gli endpoint richiedono il protocollo HTTPS. Essendo basata su HTTP, l'API Graph 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

... è equivalente all'esecuzione di questa richiesta cURL:

curl -i -X GET "https://graph.facebook.com/facebook/picture?redirect=false"

Abbiamo anche abilitato la direttiva HSTS includeSubdomains in facebook.com, tuttavia non dovrebbe avere conseguenze negative sulle tue chiamate 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. Quasi tutti gli endpoint dell'API Graph richiedono un token d'accesso, quindi ogni volta che accedi a un endpoint, la richiesta potrebbe richiederne uno. Di solito, sono responsabili di due funzioni:

• Consentono alla tua app di accedere alle informazioni sull'utente senza la richiesta della relativa password. Ad esempio, la tua app ha bisogno dell'e-mail dell'utente per eseguire una funzione. Se autorizza la tua app a recuperare il suo indirizzo e-mail da Facebook, l'utente non dovrà immettere la password di Facebook per consentire all'app di ottenere il suo indirizzo e-mail.
• 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.

Consulta la nostra documentazione sui token d'accesso per saperne di più.

Nodi

I nodi sono singoli oggetti con ID unici. Ad esempio, esistono diversi oggetti dei nodi User, ognuno con un ID unico che rappresenta una persona su Facebook. Pagine, gruppi, post, foto e commenti sono solo alcuni dei nodi del social graph di Facebook.

Il seguente cURL di esempio rappresenta una chiamata al nodo User.

curl -i -X GET \
  "https://graph.facebook.com/USER-ID?access_token=ACCESS-TOKEN"

Questa richiesta restituisce i seguenti dati per impostazione predefinita, in formato JSON:

{
  "name": "Your Name",
  "id": "YOUR-USER-ID"
}

Metadati del nodo

Puoi ottenere una lista di tutti i campi, inclusi il nome del campo, la descrizione e il tipo di dati, di un oggetto nodo come un utente, una pagina o una foto. Invia una richiesta GET a un ID oggetto e includi il parametro metadata=1:

curl -i -X GET \
  "https://graph.facebook.com/USER-ID?
    metadata=1&access_token=ACCESS-TOKEN"

La risposta JSON risultante includerà la proprietà metadata, che indica tutti i campi supportati da un determinato nodo:

{
  "name": "Jane Smith",
  "metadata": {
    "fields": [
      {
        "name": "id",
        "description": "The app user's App-Scoped User ID. This ID is unique to the app and cannot be used by other apps.",
        "type": "numeric string"
      },
      {
        "name": "age_range",
        "description": "The age segment for this person expressed as a minimum and maximum age. For example, more than 18, less than 21.",
        "type": "agerange"
      },
      {
        "name": "birthday",
        "description": "The person's birthday.  This is a fixed format string, like `MM/DD/YYYY`.  However, people can control who can see the year they were born separately from the month and day so this string can be only the year (YYYY) or the month + day (MM/DD)",
        "type": "string"
      },
...

/me

Il nodo /me è un endpoint speciale che si traduce nell'ID oggetto della persona o della pagina il cui token d'accesso è attualmente in uso per effettuare le chiamate API. Se avessi un token d'accesso per l'utente potresti recuperare il nome e l'ID dell'utente usando:

curl -i -X GET \
  "https://graph.facebook.com/me?access_token=ACCESS-TOKEN"

Segmenti

Un segmento è un collegamento tra due nodi. Ad esempio, un nodo User può avere delle foto associate, mentre un nodo Photo può avere dei commenti associati. Il seguente cURL di esempio restituirà una lista di foto pubblicate da una persona su Facebook.

curl -i -X GET \
  "https://graph.facebook.com/USER-ID/photos?access_token=ACCESS-TOKEN"

Ogni ID restituito rappresenta un nodo Photo e il momento del relativo caricamento su Facebook.

    {
  "data": [
    {
      "created_time": "2017-06-06T18:04:10+0000",
      "id": "1353272134728652"
    },
    {
      "created_time": "2017-06-06T18:01:13+0000",
      "id": "1353269908062208"
    }
  ],
}

Campi

I campi sono proprietà dei nodi. Quando effettui una query per un nodo o un segmento, 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.

La seguente richiesta cURL include il parametro fields e il nome, l'e-mail e l'immagine di profilo dell'utente.

curl -i -X GET \
  "https://graph.facebook.com/USER-ID?fields=id,name,email,picture&access_token=ACCESS-TOKEN"

Dati restituiti

{
  "id": "USER-ID",
  "name": "EXAMPLE NAME",
  "email": "EXAMPLE@EMAIL.COM",
  "picture": {
    "data": {
      "height": 50,
      "is_silhouette": false,
      "url": "URL-FOR-USER-PROFILE-PICTURE",
      "width": 50
    }
  }
}

Parametri complessi

La maggior parte dei tipi di parametri è rappresentata da primitive semplici, come bool, string e int, ma esistono anche tipi list e object che possono essere specificati nella richiesta.

Il tipo list è specificato nella sintassi JSON, ad esempio: ["firstitem", "seconditem", "thirditem"]

Anche il tipo object è specificato nella sintassi JSON, ad esempio: {"firstkey": "firstvalue", "secondKey": 123}

Pubblicazione, aggiornamento ed eliminazione

Consulta la nostra guida alla condivisione su Facebook per scoprire come pubblicare sul profilo Facebook di un utente o la documentazione sull'API Pages per pubblicare nel feed di Facebook di una pagina.

Alcuni nodi ti consentono di aggiornare i campi con operazioni POST. Ad esempio, puoi aggiornare il campo email nel modo seguente:

curl -i -X POST \
  "https://graph.facebook.com/USER-ID?email=YOURNEW@EMAILADDRESS.COM&access_token=ACCESS-TOKEN"

RAW

Per la creazione e l'aggiornamento degli endpoint, l'API Graph può leggere subito un oggetto pubblicato o aggiornato correttamente e restituire i campi supportati dall'endpoint di lettura corrispondente.

Per impostazione predefinita, sarà restituito un ID dell'oggetto creato o aggiornato. Per includere maggiori informazioni nella risposta, includi il parametro fields nella richiesta e indica i campi da restituire. Ad esempio, per pubblicare il messaggio "Hello" nel feed di una pagina, potresti effettuare la richiesta seguente:

curl -i - X POST "https://graph.facebook.com/PAGE-ID/feed?message=Hello&
  fields=created_time,from,id,message&access_token=ACCESS-TOKEN"

La richiesta restituirebbe i campi specificati come risposta in formato JSON, in questo modo:

{
  "created_time": "2017-04-06T22:04:21+0000",
  "from": {
    "name": "My Facebook Page",
    "id": "PAGE-ID"
  },
  "id": "POST_ID",
  "message": "Hello",
}

Consulta la documentazione di riferimento di ogni endpoint per sapere se supporta la modalità RAW e quali sono i campi disponibili.

Errori

Se la lettura non va a buon fine per qualsiasi motivo (ad esempio per aver richiesto un campo inesistente), l'API Graph restituirà una risposta di errore standard. Consulta la nostra guida alla gestione degli errori per maggiori informazioni.

Di solito puoi eliminare un nodo, ad esempio un nodo Post o Photo, eseguendo un'operazione DELETE sull'ID oggetto:

curl -i -X DELETE \
  "https://graph.facebook.com/PHOTO-ID?access_token=ACCESSS-TOKEN"

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

Webhook

Puoi ricevere notifiche di modifiche ai nodi o interazioni con i nodi attivando l'iscrizione ai webhook. Consulta Webhooks.

Versioni

L'API Graph prevede diverse versioni a rilascio trimestrale. Puoi specificare la versione nelle chiamate aggiungendo "v" e il numero di versione all'inizio del percorso della richiesta. Ad esempio, ecco una chiamata alla versione 4.0:

curl -i -X GET \
  "https://graph.facebook.com/v4.0/USER-ID/photos
    ?access_token=ACCESS-TOKEN"

Se non includi un numero di versione, per impostazione predefinita verrà utilizzata la versione meno recente disponibile, quindi è consigliabile includere il numero di versione nelle tue richieste.

Puoi avere maggiori informazioni sulle versioni consultando la nostra guida alle versioni e scoprire di più su tutte le versioni disponibili nel registro modifiche dell'API Graph.

API, SDK e piattaforme Facebook

Collega le interfacce e inizia a sviluppare attraverso le piattaforme usando API, SDK e piattaforme Facebook.

Passaggi successivi

Primi passi con l'API Graph: esploriamo insieme il social graph di Facebook usando il tool di esplorazione per la API Graph ed effettuiamo un paio di richieste di dati.