Sei sulla pagina 1di 5

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

message, picture, link, name, caption,


/PROFILE_ID/feed Pubblica un nuovo post nel dato profilo feed/wall
description, source

Commenta il dato oggetto (se presenta la


/OBJECT_ID/comments message
connessione /comments)

Mi piace per il dato oggetto (se presenta la


/OBJECT_ID/likes none
connessione /likes)

/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)

Crea un checkin nella posizione presente in una


/PROFILE_ID/checkins coordinates, place, message, tags
Pagina

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.