Richieste batch e asincrone

Usa le richieste asincrone per creare inserzioni e inviare numerose richieste di inserzioni senza alcun blocco. Specifica un URL da chiamare dopo il completamento delle richieste o controlla lo stato della richiesta. Consulta il riferimento alle inserzioni.

Il modo più efficiente per gestire le inserzioni è attraverso le richieste batch. Usalo per eseguire alcune delle richieste più comuni.

Richieste asincrone

Ad esempio, ottieni lo stato del gruppo di richieste asincrone:

curl -G \
  -d 'fields=name,success_count,error_count,is_completed' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v19.0/<REQUEST_SET_ID>

Restituisce lo stato complessivo del gruppo di richieste asincrone come oggetto JSON. Non tutti i campi sono visualizzati per impostazione predefinita. Se desideri che la tua query includa campi non predefiniti, specificali in fields, ad esempio fields=id,owner_id,name,total_count,success_count,error_count,is_completed.

Dopo aver ottenuto lo stato complessivo del gruppo di richieste asincrone, ottieni i dettagli di ogni richiesta:

curl -G \
  -d 'fields=id,status' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v19.0/<REQUEST_SET_ID>/requests   

Questo restituisce lo stato e i dettagli di ogni richiesta del gruppo di richieste asincrone. Per la creazione delle inserzioni asincrone, effettua una richiesta per creare un'inserzione. Il parametro dello stato consente di filtrare le richieste per stato; può essere una combinazione dei seguenti valori:

• initial: non ancora elaborata
• in_progress: richiesta in elaborazione
• success: richiesta terminata e andata a buon fine
• error: richiesta terminata e non andata a buon fine
• canceled: richiesta annullata dall'utente

La risposta è un array JSON con campi predefiniti. Per includere in qualsiasi campo non predefinito, specificalo in fields, ad esempio fields=id,scope_object_id,status,result,input,async_request_set.

Acquisizione dei dettagli delle richieste

Per ottenere i dettagli di una specifica richiesta asincrona, effettua questa chiamata:

curl -G \
  -d 'fields=id,status' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v19.0/<REQUEST_SET_ID>/requests   

Questo restituisce un oggetto JSON con i campi elencati in alto.

Elenco di gruppi di richieste per un account

Puoi creare più gruppi di richieste di inserzioni asincrone. Per interrogare tutti i gruppi di inserzioni di richieste asincrone per un account pubblicitario:

curl -G \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v19.0/act_<AD_ACCOUNT_ID>/asyncadrequestsets  

Questo restituisce un array JSON di oggetti gruppo di richieste asincrone. Ogni oggetto è lo stesso che è specificato nella sezione sui gruppi di richieste asincrone. Puoi filtrare i risultati con is_completed. Se is_completed=true, visualizzerai solo gruppi di richieste asincrone completate.

Elenco di richieste per un gruppo di inserzioni

Puoi effettuare una chiamata asincrona per creare inserzioni in diversi gruppi di inserzioni. Per ottenere lo stato di ciascun gruppo di inserzioni, ottieni tutte le richieste di creazione delle inserzioni per un gruppo di inserzioni:

curl -G \
  -d 'fields=id,status' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v19.0/<AD_SET_ID>/asyncadrequests

Restituisce un array JSON di oggetti richiesta asincrona. Lo stato, il filtro dei campi e i campi delle richieste asincrone sono gli stessi dell'API https://graph.facebook.com/<API_VERSION>/<REQUEST_SET_ID>/requests.

Aggiornamento dei gruppi di richieste

Puoi modificare name, notification_uri e notification_mode per un gruppo di richieste asincrone.

curl \
  -F 'name=New Name' \
  -F 'notification_mode=OFF' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v19.0/<REQUEST_SET_ID>

Questo restituisce true se l'aggiornamento è andato a buon fine. Puoi modificare notification_uri e notification_mode solo prima che la notifica venga inviata.

Annullamento delle richieste

Puoi annullare una richiesta asincrona solo se non è stata ancora elaborata.

curl -X DELETE \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v19.0/<REQUEST_ID>

Restituisce true se l'annullamento è andato a buon fine. Puoi annullare anche le richieste non elaborate appartenenti a un gruppo di richieste asincrone:

curl -X DELETE \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v19.0/<REQUEST_SET_ID>

Restituisce true se l'annullamento è andato a buon fine.

Esempi asincroni

Acquisizione dello stato di una specifica richiesta asincrona:

//pretty=true for command line readable output
curl -G \
-d "id=6012384857989" \
-d "pretty=true" \
-d "access_token=_____" \
"https://graph.facebook.com/v19.0/"

Valori restituiti:

{
   "id": "6012384857989",
   "owner_id": 12345,
   "name": "testasyncset",
   "is_completed": true
}

Acquisizione dei risultati delle richieste:

curl -G \
-d "id=6012384857989" \
-d "pretty=true" \
-d "fields=result" \
-d "access_token=_____" \
"https://graph.facebook.com/v19.0/requests"

Restituisce:

{
   "data": [
      {
         "result": {
            "id": "6012384860989"
         },
         "id": "6012384858389"
      },
      {
         "result": {
            "id": "6012384858789"
         },
         "id": "6012384858189"
      }
   ],
   "paging": {
      "cursors": {
         "after": "___",
         "before": "___"
      }
   }
}

Acquisizione di una lista di gruppi di richieste per un account pubblicitario:

curl -G \
-d "is_completed=1" \
-d "pretty=true" \
-d "access_token=___" \
"https://graph.facebook.com/v19.0/act_71597454/asyncadrequestsets"

Restituisce:

{
   "data": [
      {
         "id": "6012384253789",
         "owner_id": 71597454,
         "name": "testasyncset",
         "is_completed": true
      },
   ],
   "paging": {
      "cursors": {
         "after": "___",
         "before": "___"
      }
   }
}

Acquisizione di una lista di richieste per una campagna:

curl -G \
-d "status=SUCCESS,ERROR" \
-d "pretty=true" \
-d "access_token=___" \
"https://graph.facebook.com/v19.0/6008248529789/asyncadrequests"
    

Valori restituiti:

{
   "data": [
      {
         "id": "6012384951789",
         "scope_object_id": 6008248529789,
         "status": "SUCCESS"
      },
   ],
   "paging": {
      "cursors": {
         "after": "___",
         "before": "___"
      }
   }
}

Richieste batch

Con le richieste batch, puoi combinare una serie di chiamate all'API Graph in un'unica richiesta HTTP. L'API Marketing suddivide questa richiesta nelle sue richieste costituenti. Questo rende le richieste batch il modo più efficiente di interagire con l'API Marketing. Per un'efficienza ancora maggiore, puoi effettuare richieste batch parallele usando thread di elaborazione separati.

Le richieste batch per inserzioni, creatività dell'inserzione e gruppi di inserzioni sono molto simili, per cui le tratteremo complessivamente qui. Per maggiori informazioni, vedi Richieste batch dell'API Graph ed ETag.

Creazione delle inserzioni

Puoi fornire creatività dell'inserzione e altri oggetti pubblicitari in una richiesta batch. Ad esempio, puoi creare tre inserzioni usando una sola creatività dell'inserzione e tre diverse specifiche di targetizzazione. Come prima cosa definisci la tua creatività dell'inserzione, quindi fai riferimento ad essa quando crei ciascuna inserzione:

curl -F 'access_token=______' 
  -F 'test1=@./test1.jpg'  
  -F 'batch=[
             {
              "method": "POST",
              "name": "create_adimage",
              "relative_url": "<API_VERSION>/act_187687683/adimages",
              "attached_files": "test1"
             },
             {
              "method": "POST",
              "name": "create_creative",
              "relative_url": "<API_VERSION>/act_187687683/adcreatives",
              "attached_files": "test1",
              "body": "name=sample creative&object_story_spec={\"link_data\": {\"image_hash\": \"{result=create_adimage:$.images.*.hash}\", \"link\": \"https://www.test12345.com\", \"message\": \"this is a sample message\"}, \"page_id\":\"12345678\"}&degrees_of_freedom_spec={\"creative_features_spec\": {\"standard_enhancements\": {\"enroll_status\": \"OPT_OUT\"}}}"
             },
             {
              "method": "POST",
              "relative_url": "<API_VERSION>/act_187687683/ads",
              "body": "adset_id=6004163746239&redownload=1&status=PAUSED&optimization_goal=REACH&billing_event=IMPRESSIONS&&creative={\"creative_id\":\"{result=create_creative:$.id}\"}&targeting={\"countries\":[\"US\"]}&name=test1"
             },
             {
              "method": "POST",
              "relative_url": "<API_VERSION>/act_187687683/ads",
              "body": "adset_id=6004163746239&redownload=1&status=PAUSED&optimization_goal=REACH&billing_event=IMPRESSIONS&&creative={\"creative_id\":\"{result=create_creative:$.id}\"}&targeting={\"countries\":[\"US\"]}&name=test2"
             },
             {
              "method": "POST",
              "relative_url": "<API_VERSION>/act_187687683/ads",
              "body": "adset_id=6004163746239&redownload=1&status=PAUSED&optimization_goal=REACH&billing_event=IMPRESSIONS&&creative={\"creative_id\":\"{result=create_creative:$.id}\"}&targeting={\"countries\":[\"US\"]}&name=test3"
             }
            ]' https://graph.facebook.com/

La risposta include i singoli codici di risposta per ogni richiesta e la risposta dell'API Graph standard. Per i dettagli, vedi Invio di più richieste API.

Il processo delle richieste batch utilizza il formato JSONPath per fare riferimento alle richieste precedenti.

Aggiornamento delle inserzioni

Puoi aggiornare le inserzioni con richieste batch. Per aggiornare le offerte per tre inserzioni:

curl -F 'access_token=____' 
  -F 'batch=[
             {
              "method": "POST",
              "relative_url": "<API_VERSION>/6004251715639",
              "body": "redownload=1&name=new name"
             },
             {
              "method": "POST",
              "relative_url": <API_VERSION>/v6004251716039",
              "body": "redownload=1&name=new name"
             },
             {
              "method": "POST",
              "relative_url": "<API_VERSION>/6004251715839",
              "body": "redownload=1&name=new name"
             }
            ]' https://graph.facebook.com

Se includi redownload=1 nel relativo URL, ottieni i dettagli completi delle inserzioni, incluso l'ID dell'inserzione. Questo aiuta a identificare le inserzioni che hai aggiornato.

Per aggiornare le creatività dell'inserzione, specifica l'intera creatività oppure indica un nuovo ID della creatività. Questo è necessario perché le creatività dell'inserzione non possono essere modificate dopo la loro creazione, tranne per il nome e lo stato di pubblicazione.

Lettura delle inserzioni

Se hai un numero elevato di inserzioni, suddividi la richiesta in una serie di richieste contenute in una richiesta batch:

curl -F 'access_token=____' 
  -F 'batch=[
             {
              "method": "GET",
              "relative_url": "<API_VERSION>/?ids=6003356308839,6004164369439&fields=<comma separated list of fields>"
             },
             {
              "method": "GET",
              "relative_url": "<API_VERSION>/6003356307839/ads&fields=<comma separated list of fields>"
             },
             {
              "method": "GET",
              "relative_url": "<API_VERSION>/act_187687683/ads?adset_ids=[6003356307839, 6004164259439]&fields=<comma separated list of fields>"
             }
            ]' https://graph.facebook.com

6003356308839 e 6004164369439 sono ID dell'inserzione, mentre 6003356307839 e 6004164259439 sono ID del gruppo di inserzioni.

Insight sulle inserzioni

Se hai un numero elevato di insight sulle inserzioni, suddividi la richiesta in una serie di richieste contenute in una richiesta batch:

curl -F 'access_token=____' 
  -F 'batch=[
             {
              "method": "GET",
              "relative_url": "<API_VERSION>/act_19643108/insights?filtering=[{field:'ad.id',operator:'IN',value:[6003356308839,6004164369439]}]"
             },
             {
              "method": "GET",
              "relative_url": "<API_VERSION>/6003356308839/insights"
             },
             {
              "method": "GET",
              "relative_url": "<API_VERSION>/act_187687683/insights?filtering=[{field:'adset.id',operator:'IN',value:[6003356307839, 6004164259439]}]"
             }
            ]' https://graph.facebook.com

In questo esempio, 6003356308839 e 6004164369439 sono ID dell'inserzione, mentre 6003356307839 e 6004164259439 sono ID del gruppo di inserzioni.

Per gli account pubblicitari con un numero elevato di inserzioni, non è consigliabile usare act_<account_ID>/adgroupstats in quanto potrebbe causare il timeout della richiesta.

Richieste batch per una stima della copertura

Puoi richiedere fino a 50 stime della copertura in un'unica richiesta batch. L'esempio seguente mostra la stima della copertura richiesta per due diverse specifiche di targetizzazione:

curl -F 'access_token=____' 
  -F 'batch=[
             {
              "method": "GET",
              "relative_url": "<API_VERSION>/act_600335/reachestimate?targeting_spec={'geo_locations': {'countries':['US']}}"
             },
             {
              "method": "GET",
              "relative_url": "<API_VERSION>/act_600335/reachestimate?targeting_spec={'geo_locations': {'countries':['FR']}}"
             }
            ]' https://graph.facebook.com

API Batch

L'API Batch ti consente di effettuare richieste batch e inviarle in modo asincrono. Raggruppa più chiamate all'API Graph in un'unica richiesta HTTP ed eseguile in modo asincrono senza interrompere le operazioni. Inoltre, puoi specificare le dipendenze tra operazioni correlate.

Facebook elabora ogni operazione indipendente in parallelo, mentre quelle dipendenti in modo sequenziale. Ogni chiamata API può avere un massimo di 1000 richieste.

Chiamate all'API Batch

Per effettuare una chiamata all'API Batch:

curl \
-F "access_token=___" \
-F "name=asyncbatchreqs" \
-F "adbatch=<an array of requests>"\
"https://graph.facebook.com/v19.0/act_<AD_ACCOUNT_ID>/async_batch_requests"

Fornisci un array di richieste HTTP POST come array JSON. Ogni richiesta include:

• name
• relative_url: porzione di URL dopo graph.facebook.com
• body

L'API restituisce un ID che dovrai usare per interrogare il progresso delle richieste.

Ad esempio, crea una campagna in un gruppo di inserzioni con il formato JSONPath per fare riferimento alle richieste precedenti:

curl \
-F "access_token=___" \
-F "name=batchapiexample" \
-F "adbatch=[
  {
    'name': 'create-campaign',
    'relative_url': 'act_123456/campaigns',
    'body': 'name%3DTest+Campaign%26objective%3DLINK_CLICKS%26status%3DPAUSED%26buying_type%3DAUCTION',
  },
  {
    'name': 'create-adset',
    'relative_url': 'act_123456/adsets',
    'body': 'targeting%3D%7B%22geo_locations%22%3A%7B%22countries%22%3A%5B%22US%22%5D%7D%7D%26daily_budget%3D5000%26campaign_id%3D%7Bresult%3Dcreate-campaign%3A%24.id%7D%26bid_amount%3D2%26name%3DFirst%2BAd%2BSet%20Test%26billing_event%3DLINK_CLICKS',
  },
]" \
https://graph.facebook.com/<API_VERSION>/act_123456/async_batch_requests

Per ottenere lo stato di un gruppo di richieste:

curl –G \
-d "access_token=___" \
-d "fields=<comma separated list of fields>" \
"https://graph.facebook.com/v19.0/<REQUEST_SET_ID>"

Restituisce lo stato complessivo dei gruppi di richieste asincrone come oggetti JSON. Non tutti i campi sono restituiti per impostazione predefinita. Per includerli, specifica l'elemento fields, ad esempio fields=id,owner_id,name,total_count,success_count,error_count,is_completed.

Dopo aver ottenuto lo stato complessivo, puoi ottenere i dettagli per ogni richiesta:

curl –G \   
-d "access_token=___" \
-d "fields=<comma separated list of fields>" \
"https://graph.facebook.com/v19.0/<REQUEST_SET_ID>/requests"

Restituisce i dettagli come array JSON. Per includere campi non predefiniti, specificali in fields, ad esempio fields=id,scope_object_id,status,result,input,async_request_set.

Elenco di richieste API Batch per account pubblicitario

Puoi creare diversi gruppi di richieste API Batch. Per interrogare tutti i gruppi di richieste per un account pubblicitario:

curl –G \ 
-d "access_token=___" \
"https://graph.facebook.com/v19.0/act_<AD_ACCOUNT_ID>/async_requests"

ETag

L'API Marketing supporta gli ETag. Questo ti aiuta a capire se i dati che hai interrogato hanno subito modifiche dall'ultimo controllo. Come funziona:

1. Quando effettui una chiamata, l'intestazione della risposta include un ETag con un valore che corrisponde all'hash dei dati restituiti nella chiamata API. Prendi nota del valore di questo ETag, ti servirà nel passaggio successivo.
2. Quando effettuerai nuovamente la stessa chiamata API, includi l'intestazione della richiesta If-None-Match con il valore dell'ETag che hai annotato.
3. Se i dati non hanno subito modifiche, il codice dello stato della risposta è 304 – Not Modified e non viene restituito alcun dato.
4. Se i dati hanno subito modifiche dall'ultima query, vengono restituiti come di consueto con un nuovo ETag. Prendi nota del valore del nuovo ETag e usalo per le successive chiamate.

Sebbene gli ETag contribuiscano a ridurre il traffico dei dati, If-None-Match GET continua a conteggiare il rate limiting per la tua app.

L'ETag è calcolato utilizzando l'intera risposta ricevuta dalla chiamata API, inclusa la formattazione. La formattazione della risposta potrebbe essere influenzata dalla stringa user agent. Pertanto, lo user agent deve rimanere costante tra le chiamate effettuate dallo stesso client.

Esempi di ETag

Ecco come controllare se gli account pubblicitari dell'utente hanno subito modifiche.

Passaggio 1: determinare l'ETag per i dati correnti

curl -i "https://graph.beta.facebook.com/me/adaccounts?access_token=___"

La risposta sarà la seguente:

HTTP/1.1 200 OK
Access-Control-Allow-Origin: *
Cache-Control: private, no-cache, no-store, must-revalidate
Content-Type: text/javascript; charset=UTF-8
ETag: "7776cdb01f44354af8bfa4db0c56eebcb1378975"
Expires: Sat, 01 Jan 2000 00:00:00 GMT
Pragma: no-cache
X-FB-Rev: 495685
X-FB-Server: 10.30.149.204
X-FB-Debug: CWbHcogdwUE8saMv6ML+8FacXFrE8ufhjjwxU2dQWaA=
X-Cnection: close
Date: Mon, 16 Jan 2012 12:07:44 GMT
Content-Length: 3273

{"data":[{"id":"act.......

In questo esempio, l'ETag è "7776cdb01f44354af8bfa4db0c56eebcb1378975" (l'ETag include le virgolette ").

Passaggio 2: determinare se i dati hanno subito delle modifiche

curl -i -H "If-None-Match: \"7776cdb01f44354af8bfa4db0c56eebcb1378975\"" "https://graph.beta.facebook.com/me/adaccounts?access_token=___"

In assenza di modifiche, la risposta sarà la seguente:

HTTP/1.1 304 Not Modified
Access-Control-Allow-Origin: *
Cache-Control: private, no-cache, no-store, must-revalidate
Content-Type: text/javascript; charset=UTF-8
Expires: Sat, 01 Jan 2000 00:00:00 GMT
Pragma: no-cache
X-FB-Rev: 495685
X-FB-Server: 10.30.177.190
X-FB-Debug: ImBhat3k07Nez5FvuS2lPWU0U2xxmxD4B3k9ua4Sk7Q=
X-Cnection: close
Date: Mon, 16 Jan 2012 12:09:17 GMT
Content-Length: 0

Come vedi, la risposta è 304 Not Modified. Se i dati avessero subito delle modifiche, sarebbe stata restituita una risposta API normale.

Ecco un batch di esempio per controllare se le inserzioni dell'utente hanno subito modifiche.

Passaggio 1: determinare l'ETag per i dati correnti

curl -i "curl -F 'access_token=___' -F 'batch=[ 
  {"method":"GET", "relative_url": "?ids=6003356308839,6004164369439" }, 
  {"method":"GET", "relative_url": "act_12345678/ads?campaign_ids=[6003356307839, 6004164259439]"}]'
 https://graph.facebook.com"

La risposta conterrà valori di ETag come mostrato di seguito:

...{"name":"ETag","value":"\"21d371640127490b2ed0387e8af3f0f8c9eff012\""}...      
...{"name":"ETag","value":"\"410e53bb257f116e8716e4ebcc76df1c567b87f4\""}...

In questo esempio, gli ETag sono "21d371640127490b2ed0387e8af3f0f8c9eff012" e "410e53bb257f116e8716e4ebcc76df1c567b87f4" (l'ETag include le virgolette ").

Passaggio 2: determinare se i dati hanno subito delle modifiche:

curl -F 'access_token=___' -F 'batch=[
  {"method":"GET", "headers":["If-None-Match: \"21d371640127490b2ed0387e8af3f0f8c9eff012\""], "relative_url": "?ids=6003356308839,6004164369439" },
  {"method":"GET",  "headers":["If-None-Match: \"410e53bb257f116e8716e4ebcc76df1c567b87f4\""], "relative_url": "act_12345678/ads?campaign_ids=[6003356307839, 6004164259439]"}]' 
https://graph.facebook.com

In assenza di modifiche, la risposta è la seguente:

[{
    "code": 304,
    .
    .
    .
    "body": null
},
{
    "code": 304,
    .
    .
    .
    "body": null
}]

Come vedi, la risposta è 304 Not Modified. Se i dati hanno subito modifiche, restituiamo una risposta API normale.