API Graph

Richieste di gruppo

Invia una singola richiesta HTTP che contenga più chiamate all'API Graph di Facebook. Le operazioni indipendenti vengono elaborate in parallelo, mentre quelle dipendenti vengono elaborate in sequenza. Dopo aver completato tutte le operazioni, viene restituita una risposta consolidata e la connessione HTTP viene chiusa.

L'ordine delle risposte corrisponde a quello delle operazioni nella richiesta. Devi elaborare le risposte di conseguenza per stabilire quali operazioni sono state eseguite correttamente e quali invece devono essere ritentate in un'operazione successiva.

Limitazioni

  • Per le richieste di gruppo, il limite è 50 richieste per gruppo. Ogni chiamata all'interno del gruppo viene conteggiata separatamente ai fini del calcolo dei limiti delle chiamate all'API e delle risorse. Ad esempio, in un gruppo di 10 chiamate all'API, ognuna sarà calcolata e contribuirà allo stesso modo al calcolo dei limiti delle risorse della CPU. Per ulteriori informazioni, consulta la nostra Guida al rate limiting.
  • Le richieste di gruppo non possono includere più Adsets sotto la stessa Campagna. Scopri di più sulle richieste di gruppo all'API Marketing.

Richiesta di gruppo

Una richiesta di gruppo accetta un oggetto JSON che consiste in un array delle richieste. Restituisce un array di risposte HTTP logiche rappresentate come array JSON. Ogni risposta ha un codice di stato, un array di intestazioni facoltativo e un corpo facoltativo (che è una stringa codificata JSON).

Per effettuare una richiesta in gruppo, invia una richiesta POST a un endpoint in cui il parametro batch sia il tuo oggetto JSON.

POST /ENDPOINT?batch=[JSON-OBJECT]

Esempio di richiesta di gruppo

In questo esempio, richiediamo informazioni su due pagine gestite dalla nostra app.

Formattato per una maggiore leggibilità.
curl -i -X POST 'https://graph.facebook.com/me?batch=  
  [
    {
      "method":"GET",
      "relative_url":"PAGE-A-ID"
    },  
    {
      "method":"GET",
      "relative_url":"PAGE-B-ID"
    }
  ]
  &include_headers=false             // Included to remove header information
  &access_token=ACCESS-TOKEN'

Una volta completate tutte le operazioni, viene inviata una risposta con il risultato di ciascuna operazione. A volte, le intestazioni restituite possono avere dimensioni notevolmente superiori rispetto alla risposta dell'API effettiva, pertanto per una maggiore efficienza puoi rimuoverle. Per includere le informazioni dell'intestazione, rimuovi il parametro include_headers o impostalo su true.

Esempio di risposta

Il campo body contiene un oggetto JSON codificato in formato stringa:

[
  {
    "code": 200,
    "body": "{
      \"name\": \"Page A Name\",
      \"id\": \"PAGE-A-ID\"
      }"
  },
  {
    "code": 200,
    "body": "{
      \"name\": \"Page B Name\",
      \"id\": \"PAGE-B-ID\"
      }"
  }
]

Richieste di gruppo complesse

È possibile combinare operazioni che di solito utilizzano diversi metodi HTTP in un'unica richiesta di gruppo. Mentre le operazioni GET e DELETE possono avere solo un relative_url e un campo method, le operazioni POST e PUT possono contenere un campo body facoltativo. Il body deve essere formattato come stringa POST HTTP non elaborata, simile a una stringa di query URL.

Esempio di richiesta

Nell'esempio seguente viene pubblicato un post su una Pagina che gestiamo e di cui disponiamo delle autorizzazioni di pubblicazione e quindi il feed della Pagina in un'unica operazione:

curl "https://graph.facebook.com/PAGE-ID?batch=
  [
    { 
      "method":"POST",
      "relative_url":"PAGE-ID/feed",
      "body":"message=Test status update"
    },
    { 
      "method":"GET",
      "relative_url":"PAGE-ID/feed"
    }
  ]
  &access_token=ACCESS-TOKEN"

L'output della chiamata sarà:

[
    { "code": 200,
      "headers": [
          { "name":"Content-Type", 
            "value":"text/javascript; charset=UTF-8"}
       ],
      "body":"{\"id\":\"…\"}"
    },
    { "code": 200,
      "headers": [
          { "name":"Content-Type", 
            "value":"text/javascript; charset=UTF-8"
          },
          { "name":"ETag", 
            "value": "…"
          }
      ],
      "body": "{\"data\": [{…}]}
    }
]

L'esempio seguente mostra come creare una nuova inserzione per una campagna e ottenere i dettagli dell'oggetto appena creato. Nota l'URLEncoding per il parametro body:

curl \
-F 'access_token=...' \
-F 'batch=[
  {
    "method":"POST",
    "name":"create-ad",
    "relative_url":"11077200629332/ads",
    "body":"ads=%5B%7B%22name%22%3A%22test_ad%22%2C%22billing_entity_id%22%3A111200774273%7D%5D"
  }, 
  {
    "method":"GET",
    "relative_url":"?ids={result=create-ad:$.data.*.id}"
  }
]' \
https://graph.facebook.com

L'esempio seguente aggiunge più Pagine a un Business Manager:

curl \
-F 'access_token=<ACCESS_TOKEN>' \
-F 'batch=[
  {
    "method":"POST",
    "name":"test1",
    "relative_url":"<BUSINESS_ID>/owned_pages",
    "body":"page_id=<PAGE_ID_1>"
  }, 
  {
    "method":"POST",
    "name":"test2",
    "relative_url":"<BUSINESS_ID>/owned_pages",
    "body":"page_id=<PAGE_ID_2>"
  }, 
  {
    "method":"POST",
    "name":"test3",
    "relative_url":"<BUSINESS_ID>/owned_pages",
    "body":"page_id=<PAGE_ID_3>"
  }, 
]' \
"https://graph.facebook.com/v12.0"

Dove:

  • <ACCESS_TOKEN> è un token d'accesso con l'autorizzazione business_management.
  • <BUSINESS_ID> è l'ID del Business Manager al quale devono essere assegnate le Pagine reclamate.
  • <PAGE_ID_n> sono gli ID delle Pagine da reclamare.

Errori

È possibile che una delle operazioni richieste possa restituire un errore. Questa situazione si può verificare perché, ad esempio, non disponi dell'autorizzazione per eseguire l'operazione. La risposta è simile all'API Graph standard, ma inclusa nella sintassi della risposta di gruppo:

[
    { "code": 403,
      "headers": [
          {"name":"WWW-Authenticate", "value":"OAuth…"},
          {"name":"Content-Type", "value":"text/javascript; charset=UTF-8"} ],
      "body": "{\"error\":{\"type\":\"OAuthException\", … }}"
    }
]

Le altre richieste presenti nel gruppo vengono comunque completate e, come di norma, restituite con il codice di stato 200.

Timeout

I gruppi più ampi o complessi possono scadere se il completamento di tutte le richieste contenute all'interno del gruppo richiede troppo tempo. In questo caso, il gruppo viene completato parzialmente. In un gruppo completato parzialmente, le richieste completate correttamente restituiscono l'output normale con il codice di stato 200. Le risposte per le richieste che non sono state eseguite correttamente sono null. Puoi riprovare a eseguire tutte le richieste non riuscite.

Chiamate di gruppo con JSONP

Come il resto dell'API Graph, l'API Batch supporta JSONP; la funzione di callback viene specificata utilizzando il parametro della stringa di query callback o form post.

Utilizzo di più token d'accesso

Nelle singole richieste di un'unica richiesta di gruppo può essere specificato il token d'accesso come parametro della stringa della query o form post. In questo caso, il token d'accesso di livello superiore è considerato un token fallback e viene utilizzato se una richiesta non ne ha specificato uno in modo esplicito.

Si tratta di un'opzione utile per inviare query all'API utilizzando i token d'accesso di diversi utenti o Pagine oppure per effettuare una chiamata con un token d'accesso dell'app.

È necessario includere un token d'accesso come parametro di livello superiore, anche quando le singole richieste contengono i propri token.

Caricamento di dati binari

Puoi caricare più elementi binari come parte di una chiamata di gruppo. Puoi farlo aggiungendoli come allegati multipart/mime alla richiesta e utilizzando la proprietà attached_files per permettere alle operazioni di farvi riferimento. Il valore della proprietà attached_files accetta una lista separata da virgole dei nomi attribuiti agli allegati.

Il seguente esempio mostra come caricare 2 foto con un'unica chiamata di gruppo:

curl 
     -F 'access_token=…' \
     -F 'batch=[{"method":"POST","relative_url":"me/photos","body":"message=My cat photo","attached_files":"file1"},{"method":"POST","relative_url":"me/photos","body":"message=My dog photo","attached_files":"file2"},]' \
     -F 'file1=@cat.gif' \
     -F 'file2=@dog.jpg' \
    https://graph.facebook.com
-->