Graph API

Batch-Anfragen

Sende eine einzelne HTTP-Anfrage, die mehrere Facebook Graph API-Aufrufe enthält. Unabhängige Vorgänge werden parallel verarbeitet, abhängige Vorgänge nacheinander. Nach Abschluss aller Vorgänge wird eine konsolidierte Antwort an dich zurückgegeben und die HTTP-Verbindung wird geschlossen.

Die Reihenfolge der Antworten entspricht der Reihenfolge der Vorgänge in einer Anfrage. Verarbeite Antworten dementsprechend, um zu ermitteln, welche Vorgänge erfolgreich waren und welche erneut in einem Folgevorgang wiederholt werden müssen.

Einschränkungen

  • Batch-Anfragen sind auf 50 Anfragen pro Batch beschränkt. Jeder Aufruf im Batch wird aber separat gezählt, um die API-Aufruflimits und Ressourcenlimits zu berechnen. Ein Batch mit zehn API-Aufrufen wird beispielsweise als zehn Aufrufe erfasst und jeder Aufruf im Batch trägt gleichermaßen zum Erreichen der CPU-Ressourcenlimits bei. Weitere Informationen findest du in unserem Leitfaden zur Durchsatzratenbegrenzung.
  • Batch-Anfragen dürfen nicht mehrere Anzeigengruppen unter derselben Kampagne enthalten. Erfahre mehr über das Batching von Marketing API-Anfragen.

Batch-Anfragen

Eine Batch-Anfrage verwendet ein JSON-Objekt, das aus einem Array deiner Anfragen besteht. Sie gibt ein Array logischer HTTP-Antworten in Form von JSON-Arrays zurück. Jede Antwort umfasst einen Statuscode, ein optionales Header-Array und einen optionalen Body (einen JSON-kodierten String).

Senden zum Durchführen einer Batch-Anfrage eine POST-Anfrage an einen Endpunkt, an dem der batch-Parameter dein JSON-Objekt ist.

POST /ENDPOINT?batch=[JSON-OBJECT]

Beispiel-Batch-Anfrage

In diesem Beispiel rufst du Informationen zu zwei Seiten ab, die von deiner App verwaltet werden.

Für Lesbarkeit formatiert.
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'

Nach Abschluss aller Vorgänge wird eine Antwort mit dem Ergebnis der einzelnen Vorgänge gesendet. Da die zurückgegebenen Header manchmal sehr viel größer als die eigentliche API-Antwort sein können, kann es sich aus Effizienzgründen anbieten, diese zu entfernen. Um Header-Informationen einzuschließen, entferne den Parameter include_headers oder lege ihn auf true fest.

Beispielantwort

Das Body-Feld enthält ein String-kodiertes JSON-Objekt:

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

Komplexe Batch-Anfragen

Du kannst Vorgänge, die normalerweise unterschiedliche HTTP-Methoden verwenden würden, in einer einzelnen Batch-Anfrage kombinieren. Während GET- und DELETE-Vorgänge nur die Felder relative_url und method aufweisen dürfen, können POST- und PUT-Vorgänge das optionale Feld body enthalten. Der Body sollte als roher HTTP-POST-String formatiert werden, ähnlich einem URL-Abfrage-String.

Beispielanfrage

Im folgenden Beispiel wird ein Beitrag auf einer Seite veröffentlicht, die von uns verwaltet wird und für die wir über Veröffentlichungsberechtigungen verfügen. Anschließend wird im gleichen Vorgang der Feed der Seite geschrieben:

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"

Die Ausgabe dieses Aufrufs lautet:

[
    { "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\": [{…}]}
    }
]

Im folgenden Beispiel wird eine neue Werbeanzeige für eine Kampagne erstellt und dann werden die Details des neu erstellten Objekts abgerufen. Beachte die URL-Kodierung für den „body“-Parameter:

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

Das nachfolgende Beispiel fügt einem Business Manager mehrere Seiten hinzu:

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"

Hierbei gilt:

  • <ACCESS_TOKEN> ist ein Zugriffsschlüssel mit der Berechtigung business_management.
  • <BUSINESS_ID> ist die ID des Business Managers, für den die Seiten beansprucht werden sollen.
  • <PAGE_ID_n> sind die Seiten-IDs für die Beanspruchung.

Fehler

Es kann passieren, dass einer deiner angeforderten Vorgänge einen Fehler auslöst. Ein Grund dafür könnte z. B. sein, dass du nicht zur Ausführung des angeforderten Vorgangs berechtigt bist. Die Antwort ist der Standard-Graph API ähnlich, fasst diese aber in der Syntax der Batch-Antwort zusammen:

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

Andere Anfragen im Batch sollten dennoch erfolgreich abgeschlossen werden und werden wie gewöhnlich mit dem Statuscode 200 zurückgegeben.

Zeitüberschreitungen

Große oder komplexe Batches können zu einer Zeitüberschreitung führen, wenn die Ausführung aller Anfragen im Batch zu lange dauert. In diesem Fall ist das Ergebnis ein teilweise abgeschlossener Batch. In einem teilweise abgeschlossenen Batch geben Anfragen, die erfolgreich abgeschlossen wurden, die normale Ausgabe mit dem Statuscode 200 zurück. Antworten für nicht erfolgreiche Anfragen lauten null. Du kannst eine nicht erfolgreiche Anfrage erneut durchführen.

Batch-Aufrufe mit JSONP

Die Batch API unterstützt JSONP, genauso wie der Rest der Graph API. Die JSONP-Rückruffunktion wird über den Abfrage-String- oder Form-POST-Parameter callback angegeben.

Verwenden mehrerer Zugriffsschlüssel

Einzelne Anfragen einer einzigen Batch-Anfrage können ihre eigenen Zugriffsschlüssel als Abfragezeichenfolge oder Post-Parameter angeben. In diesem Fall wird der Zugriffsschlüssel der obersten Ebene als Fallback-Schlüssel behandelt und verwendet, wenn eine individuelle Anfrage nicht explizit einen Zugriffsschlüssel angibt.

Dies kann sich als nützlich erweisen, wenn du die API mit den verschiedenen Zugriffsschlüsseln mehrerer Nutzer oder Seiten abfragen möchtest oder wenn einige deiner Aufrufe mit einem App-Zugriffsschlüssel getätigt werden müssen.

Du musst aber selbst dann einen Zugriffsschlüssel als Parameter der obersten Ebene miteinbeziehen, wenn alle individuellen Anfragen eigene Schlüssel enthalten.

Hochladen von Binärdaten

Du kannst mehrere Binärelemente als Teil eines Batch-Anrufs hochladen. Dazu musst du alle Binärelemente als Multipart-/Mime-Anhänge zu deiner Anfrage hinzufügen. Außerdem muss jeder Vorgang die zugehörigen Binärelemente über die Eigenschaft attached_files im Vorgang referenzieren. Die Eigenschaft attached_files akzeptiert auch eine durch Komma getrennte Liste mit Anhangsnamen als Wert.

Das folgende Beispiel zeigt, wie du zwei Fotos mit einem einzelnen Batch-Aufruf hochlädst:

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