Documentazione Forum Modello Blog Le mie applicazioni

Graph API

Concetti di base › Graph API

Al centro di Facebook c'è il social graph: le persone e le connessioni con qualunque cosa interessi loro. Le Graph API presentano in modo semplice e consistente una vista sul grafo sociale di Facebook, rappresentando in modo uniforme gli oggetti nel grafo (p.e., i profili, le foto, gli eventi, e le pagine) e le connessioni tra questi (p.e., le relazioni di amicizia, i contenuti condivisi, e i tag nelle foto).

Ogni oggetto nel grafo sociale ha un identificativo univoco. Si può accedere alle proprietà di un oggetto richiedendole a https://graph.facebook.com/ID . Per esempio, la pagina ufficiale Facebook Platform ha come ID 19292868552, quindi si possono recuperare le proprietà dell'oggetto all'indirizzo https://graph.facebook.com/19292868552:

{ "name": "Facebook Platform", "type": "page", "website": "http://developers.facebook.com", "username": "platform", "founded": "May 2007", "company_overview": "Facebook Platform enables anyone to build...", "mission": "To make the web more open and social.", "products": "Facebook Application Programming Interface (API)...", "fan_count": 449921, "id": 19292868552, "category": "Technology"}

In alternativa, per i profili e le pagine con uno username possono accessibili usando lo username come ID. Essendo "platform" lo username della pagina precedente, all'indirizzo https://graph.facebook.com/platform si otterrà il risultato precedente. Tutte le risposte sono oggetti JSON.

Tutti gli oggetti in Facebook sono accessibili coerentemente allo stesso modo:

• Profili utente: https://graph.facebook.com/btaylor (Bret Taylor)

• Pagine: https://graph.facebook.com/cocacola (Coca-Cola page)

• Eventi: https://graph.facebook.com/251906384206 (Facebook Developer Garage Austin)

• Gruppi: https://graph.facebook.com/195466193802264 (Facebook Developers group)

• Applicazioni: https://graph.facebook.com/2439131959 (the Graffiti app)

• Messaggi di Status: https://graph.facebook.com/367501354973 (A status message from Bret)

• Foto: https://graph.facebook.com/98423808305 (A photo from the Coca-Cola page)

• Album di foto: https://graph.facebook.com/99394368305 (Coca-Cola's wall photos)

• Immagini del profilo: http://graph.facebook.com/100001823511400/picture (your profile picture)

• Video: https://graph.facebook.com/614004947048 (A Facebook tech talk on Tornado)

• Note: https://graph.facebook.com/122788341354 (Note announcing Facebook for iPhone 3.0)

• Checkin: https://graph.facebook.com/414866888308 (Check-in at a pizzeria)

Tutti gli oggetti del grafo sociale in Facebook sono connessi agli altri via relationi. Bret Taylor è un fan della pagina Coca-Cola page, e Bret Taylor e Arjun Banker sono amici. Possiamo chiamare queste relationi connessioni nell'API. Si possono esaminare le connessioni tra oggetti usando la struttura dell'URL https://graph.facebook.com/ID/CONNECTION_TYPE . Le connessioni accessibili dal proprio profilo includono:

• Amici: https://graph.facebook.com/me/friends?access_token=...

• News feed: https://graph.facebook.com/me/home?access_token=...

• Feed del profilo (Wall): https://graph.facebook.com/me/feed?access_token=...

• Mi piace: https://graph.facebook.com/me/likes?access_token=...

• Film che mi piacciono: https://graph.facebook.com/me/movies?access_token=...

• Musica che mi piace: https://graph.facebook.com/me/music?access_token=...

• Libri che mi piacciono: https://graph.facebook.com/me/books?access_token=...

• Note: https://graph.facebook.com/me/notes?access_token=...

• Tag nelle foto: https://graph.facebook.com/me/photos?access_token=...

• Album di foto: https://graph.facebook.com/me/albums?access_token=...

• Tag nei video: https://graph.facebook.com/me/videos?access_token=...

• Video caricati: https://graph.facebook.com/me/videos/uploaded?access_token=...

• Eventi: https://graph.facebook.com/me/events?access_token=...

• Grouppi: https://graph.facebook.com/me/groups?access_token=...

• Checkin: https://graph.facebook.com/me/checkins?access_token=...

Sono supportate diverse tipi di connessioni per oggetti diversi. Per esempio, è possibile otterene la lista delle persone che parteciperanno all'evento “the Facebook Developer Garage at SXSW” (ID #331218348435) recuperando l'elenco all'indirizzo https://graph.facebook.com/331218348435/attending?access_token=....

Tutti i tipi di oggetti e di connessioni supportate sono incluse nella Graph API reference documentation.

Autorizzazione

La Graph API consente di accedere facilmente a tutte le informazioni pubbliche di un oggetto. Per esempio, https://graph.facebook.com/btaylor (Bret Taylor) ritorna tutte le informazioni pubbliche circa Bret. Per esempio a il nome dell'utente, il cognome e l'immagine del profilo sono disponibili pubblicamente.

Per ottenere ulteriori informazioni sull'utente, è necessario prima ottenerne i permessi. È necessario ottenere un access token per l'utente Facebook. Una volta ottenuto l'access token per l'utente, è possibile effettuare le richieste autorizzate come se si fosse quell'utente includendo l'access token nella richiesta alla Graph API:

https://graph.facebook.com/220439?access_token=...

Per esempio https://graph.facebook.com/btaylor?access_token=... (Bret Taylor) ritorna informazioni addizionali su Bret Taylor.

Le Graph API usano il protocollo OAuth 2.0 per le autorizzazioni. È possibile leggere la guida all'autenticazione che fornisce dettagli sull'implementazione di OAuth 2.0 di Facebook, come richiedere i permessi per l'utente e ottenere un access token.

Ottenuto un access token per un utente senza permissi estesi consente l'accesso alle informazioni che l'utente ha reso disponibili a tutti su Facebook. Se sono necessarie informazioni specifiche dell'utente, come l'indirizzo email o lo storico degli impieghi, è necessario richiedere i permessi estesi specifici. I permessi necessari per accedere ad ogni proprietà e connessione di un oggetto sono documentate in Graph API reference documentation.

Page Login

È possibile impersonare una pagina amministrata da un utente richiedendo i manage_pages permission.

Una volta che l'utente ha garantito alla tua applicazione i permessi per gestire le pagine, è possibile ottenere le connessioni "accounts" che contengono gli access_token necessari per accedere ad ogni pagina amministrata dall'utente. Questi access_token possono essere usati per effettuare chiamate per conto della pagina. I permessi garantiti dall'utente alla tua applicazione saranno ora applicabili alle sue pagine.

App Login

Per effettuare chiamate amministrative che non richiedono un utente attivo (per esempio, recuperare i dati analytics o i test users) è necessario ottenere un access token per la tua applicazione. Maggiori informazioni su come ottenere una access token per una applicazione qui.

Lettura

Le Graph API consentono la lettura delle proprietà e le connessioni del Facebook social graph. È possibile usare le API per leggere campi specifici, ottenere l'immagine di ogni oggetto, leggere i metadati di un oggetto e ottenere gli update in tempo reale di ogni cambiamento.

Selezione

Per default, la maggior parte delle proprietà di un oggetto sono ritornate quando si effettua una query. È possibile definire come parametri della query quali campi o connessioni interessano. Per esempio, il seguente URL ritornerà solo l'id, il nome, e l'immagine di Ben: https://graph.facebook.com/bgolub?fields=id,name,picture

È possibile richiedere in una singola query informazioni di più oggetti indicando più ID come parametro "ids". Per esempio, l'URL https://graph.facebook.com?ids=arjun,vernal ritornerò entrambe i profili nella stessa risposta.

Il parametro “ids” della query accetta anche URL. Questo è utile per trovare gli ID associati agli URL nel Open Graph. Per esempio: https://graph.facebook.com/?ids=http://www.imdb.com/title/tt0117500/

Inoltre è possibile utilizzare lo speciale identificatore me per riferirsi all'utente corrente. Pertanto l'URL https://graph.facebook.com/me ritorna il profilo dell'utente attivo.

Immagini

È possibile renderizzare la foto per profilo corrente di ogni oggetto aggiungendo il suffisso /picture all'URL dell'oggetto. Per esempio, il seguente codice visualizzerà la tua foto del profilo pubblica:

<img src="https://graph.facebook.com/100001823511400/picture"/>

Lo stesso pattern per l'URL funziona per tutti gli oggetti del grafo:

• Profili utente: http://graph.facebook.com/100001823511400/picture

• Eventi: http://graph.facebook.com/331218348435/picture

• Gruppi: http://graph.facebook.com/69048030774/picture

• Pagine: http://graph.facebook.com/DoloresPark/picture

• Applicazioni: http://graph.facebook.com/2318966938/picture

• Photo Album: http://graph.facebook.com/platform/picture

È possibile specificare la dimensione dell'immagine richiesta con il parametro type, che può avere come valore square (50x50), small (50 pixel in larghezza, altezza variabile), e large (circa 200 pixel in larghezza, altezza variabile): http://graph.facebook.com/100001823511400/picture?type=large.

Se è necessario ottenere l'immagine su una connessione sicura, è possibile indicare il parametro return_ssl_resources = 1: http://graph.facebook.com/100001823511400/picture?return_ssl_resources=1.

Paginazione

Ci sono diversi parametri che è possibile indicare nelle query delle connessioni per filtrare e paginare i dati ritornati:

• limit, offset: https://graph.facebook.com/me/likes?limit=3

• until, since (un timestamp unix o una data accettata da strtotime): https://graph.facebook.com/search?until=yesterday&q=orange

Date

Tutti i campi di tipo data sono ritornati come stringhe formattate nello standard ISO-8601. È possibile ottenere le date in un formato diverso specificando il parametro "date_format" nella query. Le stringhe di formato accettate sono identiche a quelle accettate dalla funzione php date. Per esempio, http://graph.facebook.com/platform/feed?date_format=U ritorna il feed della pagina Platform, con le date nel formato unix.

Introspezione

Le Graph API supportano l'introspezione degli oggetti, che consente di accedere a tutte le connessioni di un oggetto senza conoscere il suo tipo in anticipo. Per ottenere queste informazioni, è necessario aggiungere il parametro metadata=1 alla query URL, e il risultato JSON includerà i metadati contenente la lista di tutte le connessioni supportate dal dato oggetto. Per esempio, è possibile accedere a tutte le connessioni dell'evento Developer Garage recuperandole all'indirizzo https://graph.facebook.com/331218348435?metadata=1 il cui output è:

{ "name": "Facebook Developer Garage Austin - SXSW Edition", "metadata": { "connections": { "feed": "http://graph.facebook.com/331218348435/feed", "picture": "https://graph.facebook.com/331218348435/picture", "invited": "https://graph.facebook.com/331218348435/invited", "attending": "https://graph.facebook.com/331218348435/attending", "maybe": "https://graph.facebook.com/331218348435/maybe", "noreply": "https://graph.facebook.com/331218348435/noreply", "declined": "https://graph.facebook.com/331218348435/declined" } }}

La funzione di introspezione è un modo utile ed estensibile per trovare ogni cosa alla quale gli utenti sono connessi.

Aggiornamenti Real-Time

Gli update Real-time danno alla tua applicazione la possibilità di ricevere gli aggiornamenti degli utenti, non appena cambiano i dati dell'utente. Con tale sottoscrizione, ci si può assicurare che i propri dati siano aggiornati senza richiederli continuamente ai server di Facebook, incrementando l'attendibilità della tua applicazione, e fornendo una user-experience più rapida.

Ricerche

È possibile effettuare ricerche di tutti gli oggetti pubblici nel grafo sociale all'indirizzo https://graph.facebook.com/search . Il formato è:

https://graph.facebook.com/search?q=QUERY&type=OBJECT_TYPE

Le ricerche sono supportate per i seguenti tipi di oggetti:

• Post pubblici: https://graph.facebook.com/search?q=watermelon&type=post

• Profili utente: https://graph.facebook.com/search?q=mark&type=user

• Pagine: https://graph.facebook.com/search?q=platform&type=page

• Eventi: https://graph.facebook.com/search?q=conference&type=event

• Gruppi: https://graph.facebook.com/search?q=programming&type=group

• Places: https://graph.facebook.com/search?q=coffee&type=place&center=37.76,122.427&distance=1000

• Checkin: https://graph.facebook.com/search?type=checkin

È possibile cercare nei wall degli utenti, restringendo la ricerca agli amici dell'utente, aggiungendo l'argomento q all'URL di connessione alla home:

• News Feed: https://graph.facebook.com/me/home?q=facebook

Pubblicazione

È possibile pubblicare nel grafo di Facebook lanciando una richiesta di HTTP POST agli appropriati URL di connessioni, usando un access token. Per esempio, è possibile aggiungere un post sul wall di Arjun lanciando una richiesta POST a https://graph.facebook.com/arjun/feed :

curl -F 'access_token=...' \ -F 'message=Hello, Arjun. I like this new API.' \ https://graph.facebook.com/arjun/feed

Le Graph API reference forniscono informazioni più dettagliate sugli argomenti supportati e i corrispondenti valori.

È possibile lasciare un commento o un mi piace su ogni oggetto che ha connessioni /comments o /likes postando https://graph.facebook.com/OBJECT_ID/comments e https://graph.facebook.com/OBJECT_ID/likes , rispettivamente:

curl -F 'access_token=...' \ https://graph.facebook.com/313449204401/likes

Le operazioni di POST richiedono permessi estesi dell'utente attivo. Nella guida all'autenticazione sono disponibili i dettagli su come ottenere i permessi estesi dall'utente durante la fase di autenticazione.

Sono supportati i seguenti tipi di accesso in scrittura per gli oggetti:

Metodo Descrizione Argomenti

/PROFILE_ID/feed Pubblica un nuovo post nel dato profilo feed/wall message, picture, link, name, caption, description, source

/OBJECT_ID/commentsCommenta il dato oggetto (se presenta la connessione /comments)

message

/OBJECT_ID/likes Mi piace per il dato oggetto (se presenta la connessione /likes)

none

/PROFILE_ID/notes Pubblica una nota sul dato profilo message, subject

/PROFILE_ID/links Pubblica un link sul dato profilo link, message, picture, name, caption,

description

/PROFILE_ID/events Crea un evento name, start_time, end_time

/EVENT_ID/attending RSVP "parteciperò" al dato evento none

/EVENT_ID/maybe RSVP "forse parteciperò" al dato evento none

/EVENT_ID/declined RSVP "non parteciperò" al dato evento none

/PROFILE_ID/albums Crea un album name, message

/ALBUM_ID/photos Carica una foto nell'album message, source (multipart/form-data)

/PROFILE_ID/checkins Crea un checkin nella posizione presente in una Pagina

coordinates, place, message, tags

Cancellazione

È possibile cancellare oggetti nel grafo lanciando una richiesta HTTP DELETE all'indirizzo dell'oggetto, p.e,

DELETE https://graph.facebook.com/ID?access_token=... HTTP/1.1

Per i client che non supportano tutti i metodi HTTP (come i client JavaScript), è possibile lanciare alternativamente una richiesta POST all'URL dell'oggetto con l'argomento method=delete per indicare il metodo HTTP. Per esempio, è possibile cancellare un commento lanciando una richiesta di POST a https://graph.facebook.com/COMMENT_ID?method=delete .

È possibile eliminare un mi piace lanciando una richiesta di DELETE al /OBJECT_ID/likes (perché i mi piace non hanno un ID).

Analytics

Quando si registra una applicazione, è possibile ottenere dettagliati analytics demografici degli utenti disponibili come Insights dell'applicazione.

Le Graph API consentono di accedere programmaticamente a tutti questi dati rendendo possibile integrare i dati della piattaforma Facebook nei propri sistemi di analytics.

Per scaricare i dati Insights, è necessario ottenere l'app access token.

Ottenuto l'access token dell'applicazione, è possibile scaricare i dati analitici dell'applicazione all'indirizzo:

https://graph.facebook.com/app_id/insights?access_token=...

Tale URL fornisce tutti i dati analitici disponibili con le API, inclusi il numero totale degli utenti, il numero degli utenti attivi, e un certo numero di altre metriche dettagliate. Per esempio, è possibile sapere il numero delle impressioni della tua canvas dell'applicazione:

https://graph.facebook.com/app_id/insights/application_canvas_views/day?access_token=...

Si possono utilizzare gli attributi since e until per specificare l'intervallo di tempo dei dati desiderati. Entrambe gli argomenti accettano le indicazioni temporali nei formati di data usualmente utilizzati:

https://graph.facebook.com/app_id/insights?access_token=...&since=yesterday

Per ulteriori informazioni è possibile approfondire il prodotto Insights, l'URL di base /insights, e la documentazione Insights.

Richieste Batch

In caso sia necessario per l'applicazione accedere ad un ammontare significativo di dati o effettuare modifiche a diversi oggetti contemporaneamente, è più efficiente combinare questa operazioni piuttosto che effettuare richieste HTTP multiple.

Per effettuare richieste batch fare riferimento alla documentazione.