Asynchrone und Batch-Anfragen

Verwende asynchrone Anfragen, um Anzeigen zu erstellen und eine größere Anzahl von Anzeigenanfragen ohne Blockierung zu senden. Gib entweder eine URL an, die nach Abschluss der Anfragen aufgerufen wird, oder überprüfe den Status der Anfrage. Siehe Anzeige – Referenz.

Du kannst Werbeanzeigen am effektivsten durch Batch-Anfragen verwalten. Nutze diese für einige der häufigeren Anfragen.

Asynchrone Anfragen

Du kannst beispielsweise den Status einer asynchronen Anfragengruppe abrufen:

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

Dadurch wird der Gesamtstatus der asynchronen Anfragengruppe als JSON-Objekt zurückgegeben. Nicht alle Felder werden standardmäßig angezeigt. Wenn deine Anfrage nicht-standardmäßige Felder enthalten soll, gib diese in fields an, z. B. fields=id,owner_id,name,total_count,success_count,error_count,is_completed.

Rufe nach dem Gesamtstatus der asynchronen Anfragengruppe Details zu jeder Anfrage ab:

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

Dabei werden Status und Details zu jeder asynchronen Anfrage in der Gruppe zurückgegeben. Sende bei der asynchronen Anzeigenerstellung eine Anfrage zum Erstellen einer Werbeanzeige. Mit dem Status-Parameter kannst du Anfragen nach ihrem Status filtern. Er kann eine beliebige Kombination der folgenden Werte aufweisen:

• initial: noch nicht verarbeitet.
• In_progress: Anfrage wird verarbeitet.
• success: Anfrage wurde erfolgreich abgeschlossen.
• error: Anfrage wurde nicht erfolgreich abgeschlossen.
• Canceled: Anfrage wurde von dem*der Nutzer*in abgebrochen.

Die Antwort ist ein JSON-Array mit Standardfeldern. Wenn du nicht-standardmäßige Felder abfragen möchtest, gib diese in fields an, wie beispielsweise fields=id,scope_object_id,status,result,input,async_request_set.

Abrufen der Anfragedetails

Mit dem folgenden Aufruf erhältst du die Details einer bestimmten asynchronen Anfrage:

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

Der Aufruf gibt ein JSON-Objekt mit den oben genannten Feldern zurück.

Auflisten der Anfragengruppen für ein Konto

Du kannst mehrere asynchrone Anzeigenanfragengruppen erstellen. So fragst du alle asynchronen Anzeigenanfragengruppen für ein Werbekonto ab:

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

Damit erhältst du ein JSON-Array von asynchronen Anfragengruppenobjekten. Die Objekte sind dieselben wie im Abschnitt mit den asynchronen Anfragengruppen. Du kannst die Ergebnisse mit dem Parameter is_completed filtern. Wenn is_completed=true, werden dir nur abgeschlossene asynchrone Anfragengruppen angezeigt.

Auflisten von Anfragen für eine Anzeigengruppe

Du kannst einen asynchronen Aufruf tätigen, um Anzeigen in verschiedenen Anzeigengruppen zu erstellen. Um den Status für die einzelnen Anzeigengruppen abzurufen, frage alle Anzeigenerstellungsanfragen für eine Anzeigengruppe ab:

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

Dadurch wird ein JSON-Array mit asynchronen Anfragengruppen-Objekten zurückgegeben. Die Felder für Status, Feldfilter und asynchrone Anfragen sind mit denen der https://graph.facebook.com/<API_VERSION>/<REQUEST_SET_ID>/requests API identisch.

Aktualisieren von Anfragengruppen

Du kannst name, notification_uri und notification_mode bei einer asynchronen Anfragengruppe ändern.

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

Bei einer erfolgreichen Aktualisierung wird true zurückgegeben. notification_uri und notification_mode kannst du nur vor dem Senden der Benachrichtigung ändern.

Abbrechen einer Anfrage

Du kannst eine asynchrone Anfrage abbrechen, solange sie noch nicht verarbeitet wurde.

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

Bei einem erfolgreichen Abbruch wird true zurückgegeben. Außerdem kannst du nicht verarbeitete Anfragen in der asynchronen Anfragengruppe abbrechen:

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

Bei einem erfolgreichen Abbruch wird true zurückgegeben.

Asynchrone Beispiele

Abrufen des Status einer bestimmten asynchronen Anfrage:

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

Zurückgegebene Werte:

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

Abrufen der Ergebnisse von Anfragen:

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

Rückgabe:

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

Abrufen einer Liste von Anfragengruppen eines Werbekontos:

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

Rückgabe:

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

Abrufen einer Liste von Anfragengruppen einer Kampagne:

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

Zurückgegebene Werte:

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

Batch-Anfragen

Mit Batch-Anfragen kannst du mehrere Graph API-Anfragen zu einer HTTP-Anfrage kombinieren. Die Marketing API teilt diese Anfrage in die einzelnen Anfragen auf. Damit sind Batch-Anfragen die effizienteste Methode, mit der Marketing API zu interagieren. Du kannst auch parallele Batch-Anfragen mit separaten Verarbeitungs-Threads stellen, um noch effizienter zu arbeiten.

Batch-Anfragen für Werbeanzeigen, Anzeigeninhalte und Anzeigengruppen sind sehr ähnlich. Wir werden sie deshalb hier nicht einzeln behandeln. Weitere Informationen findest du unter Graph API, Batch-Anfragen und ETags.

Werbeanzeigen erstellen

Du kannst den Inhalt einer Werbeanzeige und andere Objekte in einer Batch-Anfrage bereitstellen. Du kannst z.  B. drei Anzeigen mit einem Inhalt und drei verschiedenen Targeting-Spezifikationen erstellen. Definiere zuerst den Inhalt der Werbeanzeige und gib anschließend beim Erstellen jeder Anzeige einen Verweis darauf an:

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/

Die Antwort enthält die einzelnen Antwortcodes für jede Anfrage sowie die normale Graph API-Antwort. Weitere Details findest du unter Senden mehrerer API-Anfragen.

Der Vorgang für Batch-Anfragen verwendet das JSONPath-Ausdrucksformat für Referenzen auf frühere Anfragen.

Werbeanzeigen aktualisieren

Du kannst Werbeanzeigen mit Batch-Anfragen aktualisieren. So aktualisierst du Gebote für drei Anzeigen:

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

Wenn du redownload=1 in die relative URL aufnimmst, erhältst du die vollständigen Anzeigendetails einschließlich Anzeigen-ID. So ermittelst du, welche Werbeanzeigen du aktualisiert hast.

Um den Inhalt einer Werbeanzeige zu aktualisieren, gib den kompletten Inhalt oder eine neue Inhalts-ID an. Dies ist notwendig, da Anzeigeninhalte mit Ausnahme des Namens und des Status nach der Erstellung nicht bearbeitet werden können.

Werbeanzeigen lesen

Wenn du eine große Anzahl an Werbeanzeigen verwaltest, kannst du die Anfrage auf mehrere Anfragen innerhalb einer Batch-Anfrage aufteilen:

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 und 6004164369439 sind Werbeanzeigen-IDs. 6003356307839 und 6004164259439 sind Anzeigengruppen-IDs.

Werbeanzeigen-Insights

Wenn du eine große Anzahl an Werbeanzeigen-Insights verwaltest, kannst du die Anfrage auf mehrere Anfragen innerhalb einer Batch-Anfrage aufteilen:

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 diesem Beispiel sind 6003356308839 und 6004164369439Werbeanzeigen-IDs. 6003356307839 und 6004164259439 sind Anzeigengruppen-IDs.

Wenn dein Werbekonto besonders viele Werbeanzeigen enthält, solltest du act_<account_ID>/adgroupstats nicht verwenden, da es sonst zu einer Zeitüberschreitung bei der Anfrage kommen kann.

Batch-Anfragen für geschätzte Reichweite

Du kannst bis zu 50 Reichweitenschätzungen in einer Batch-Anfrage anfordern. Das folgende Beispiel zeigt die Anforderung einer Reichweitenschätzung für zwei verschiedene Targeting-Spezifikationen:

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

Batch API

Mit der Batch API kannst du Anfragen gruppieren und asynchron senden. Gruppiere verschiedene Graph API-Aufrufe in eine HTTP-Anfrage und führe sie asynchron ohne Blockieren aus. Außerdem kannst du Abhängigkeiten zwischen verwandten Vorgängen angeben.

Facebook verarbeitet die einzelnen unabhängigen Vorgänge parallel und deine abhängigen Vorgänge der Reihe nach. Jeder API-Aufruf kann bis zu 1.000 Anfragen enthalten.

Senden eines Batch API-Aufrufs

So tätigst du einen Batch API-Aufruf:

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

Gib ein Array von HTTP POST-Anfragen als JSON-Arrays an. Jede Anfrage enthält Folgendes:

• name
• relative_url – Teil der URL nach graph.facebook.com
• body

Die API gibt eine ID zurück, mit der du den Fortschritt von Anfragen abfragen kannst.

Du kannst z. B. eine Kampagne mit einer Anzeigengruppe mit dem JSONPath-Format erstellen, um auf die früheren Anfragen zu verweisen:

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

So rufst du den Status einer Anfragengruppe ab:

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

Dadurch wird der Gesamtstatus der asynchronen Anfragengruppen als JSON-Objekte zurückgegeben. Standardmäßig werden nicht alle Felder zurückgegeben. Um sie abzurufen, musst du die fields-Werte angeben, beispielsweise fields=id,owner_id,name,total_count,success_count,error_count,is_completed.

Nachdem du den Gesamtstatus abgerufen hast, kannst du Details zu jeder Anfrage abrufen:

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

Damit erhältst du Details als JSON-Array. Wenn du nicht-standardmäßige Felder abfragen möchtest, gib diese in fields an, wie beispielsweise fields=id,scope_object_id,status,result,input,async_request_set.

Auflisten von Batch API-Anfragen für ein Werbekonto

Du kannst mehrere Batch API-Anfragengruppen erstellen. So fragst du alle Anfragengruppen für ein Werbekonto ab:

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

ETags

Die Marketing API unterstützt ETags. Damit kannst du bestimmen, ob die abgefragten Daten seit der letzten Prüfung geändert wurden. So geht‘s:

1. Wenn du einen Aufruf sendest, enthält der Antwort-Header ein ETag mit dem Hash der Daten, die im API-Aufruf zurückgegeben werden. Speichere diesen ETag-Wert, damit du ihn im nächsten Schritt verwenden kannst.
2. Wenn du denselben API-Aufruf erneut sendest, nimm den If-None-Match-Anfrage-Header mit dem gespeicherten ETag-Wert auf.
3. Wenn die Daten unverändert sind, lautet der Antwortstatuscode 304 – Not Modified. Dann werden keine Daten zurückgegeben.
4. Wenn die Daten seit der letzten Abfrage geändert wurden, werden sie wie gewöhnlich mit einem neuen ETag zurückgegeben. Speichere den neuen ETag-Wert für zukünftige Aufrufe.

Auch wenn ETags den Daten-Traffic verringern, wird If-None-Match GET weiterhin auf die Durchsatzratenbegrenzung für deine App angerechnet.

Das ETag wird anhand der ganzen Antwort vom API-Aufruf, einschließlich Formatierung, berechnet. Der Nutzer-Agent-String kann sich auf die Formatierung der Antwort auswirken. Bewahre daher die Konsistenz des Nutzer-Agents zwischen Aufrufen von demselben Client.

Beispiele für ETags

So prüfst du, ob sich die Werbekonten des*der Nutzer*in geändert haben.

Schritt 1: Bestimme das ETag für die aktuellen Daten.

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

Du erhältst folgende Antwort:

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 diesem Beispiel lautet das ETag "7776cdb01f44354af8bfa4db0c56eebcb1378975". Beachte, dass das ETag Anführungszeichen (") enthält.

Schritt 2: Stelle fest, ob die Daten geändert wurden.

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

Wenn keine Daten geändert wurden, erhältst du folgende Antwort:

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

Beachte die 304 Not Modified-Antwort. Wenn die Daten sich geändert hätten, würde eine normale API-Antwort zurückgegeben.

Ein Batch-Beispiel zum Prüfen, ob sich die Werbeanzeigen des*der Nutzer*in geändert haben.

Schritt 1: Bestimme das ETag für die aktuellen Daten.

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"

Die Antwort enthält die folgenden ETag-Werte:

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

In diesem Beispiel lauten die ETags "21d371640127490b2ed0387e8af3f0f8c9eff012" und "410e53bb257f116e8716e4ebcc76df1c567b87f4". Beachte, dass das ETag Anführungszeichen (") enthält.

Schritt 2: Stelle fest, ob die Daten geändert wurden:

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

Wenn keine Daten geändert wurden, erhältst du folgende Antwort:

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

Beachte die 304 Not Modified-Antwort. Wenn sich die Daten geändert haben, wird eine normale API-Antwort zurückgegeben.