Verwenden der Graph API

Die Graph API ist die Hauptmethode, mit der du Daten in den Social Graph von Facebook einliest und daraus abrufst. Dabei handelt es sich um eine einfache HTTP-basierte API, mit der du Daten abfragen, neue Meldungen posten, Fotos hochladen und zahlreiche andere Aufgaben ausführen kannst, die eventuell für eine App erforderlich sind. In diesem Leitfaden erfährst du, wie du all dies in der Graph API durchführen kannst.

Grundlagen

Wir behandeln die Grundlagen der Graph API-Terminologie und -Struktur in unserer Graph API-Übersicht. In den folgenden Abschnitten erfährst du mehr über die verschiedenen Vorgänge, die du mit der API ausführen kannst.

Lesen

Alle Nodes und Edges in der Graph API können einfach mit einer HTTP-GET-Anfrage an den jeweiligen Endpunkt gelesen werden. Wenn du beispielsweise Informationen zum aktuellen Nutzer abrufen möchtest, tätigst du wie folgt eine HTTP-GET-Anfrage:

GET /v2.5/me HTTP/1.1
Host: graph.facebook.com

Die meisten API-Aufrufe müssen mit einem Zugriffsschlüssel signiert sein. In der Graph API-Referenz für den gewünschten Node oder die gewünschte Edge kannst du ermitteln, welche Berechtigungen in diesem Zugriffsschlüssel erforderlich sind. Du kannst auch den Graph API Explorer verwenden, um schnell Schlüssel zu erstellen und die Funktionsweise der API auszuprobieren.

Der Node /me ist ein spezieller Endpunkt, der für die user_id der Person (oder die page_id der Facebook-Seite) steht, mit deren Zugriffsschlüssel die API-Aufrufe derzeit ausgeführt werden. Mit einem Nutzerzugriffsschlüssel könntest du wie folgt alle Fotos eines Nutzers abrufen:

GET graph.facebook.com
  /me/photos

Die zurückgegebene Antwort ist von den gelesenen Nodes oder Edges abhängig, hat aber im Allgemeinen das folgende Format:

{
   "fieldname": {field-value},
   ....
}

Auswählen von Feldern

Standardmäßig werden nicht alle Felder in einem Node oder einer Edge bei einer Abfrage zurückgegeben. Du kannst die gewünschten Felder oder Edges mit dem Abfrageparameter fields auswählen. Dieser eignet sich besonders, um deine API-Aufrufe effizienter und schneller zu machen.

Beispiel: Der folgende Graph API-Aufruf, der deinen Nutzerzugriffsschlüssel https://graph.facebook.com/me?fields=id,name,picture verwendet, gibt nur die ID, den Namen und das Bild in deinem Profil zurück:

GET graph.facebook.com/me?fields=id,name,picture

Anordnen

Du kannst bestimmte Datensätze chronologisch anordnen. So könntest du beispielsweise die Kommentare eines Fotos mit dem Schlüssel reverse_chronological in umgekehrter chronologischer Reihenfolge sortieren:

GET graph.facebook.com
  /{photo-id}?
    fields=comments.order(reverse_chronological)

order muss einen der folgenden Werte aufweisen:

  • chronological
  • reverse_chronological

URL-Lookup

Die meisten Objekte können anhand ihrer IDs gefunden werden. Manchmal ist dies aber nicht möglich und du kannst ein Objekt nur anhand einer URL identifizieren.

Mit dem URL-Node, der in Version 2.1 eingeführt wurde, kannst du die IDs von Open Graph-Objekt-URLs zurückgeben oder mit einer App-Link-URL verknüpfte Daten finden.

Mehr über das Auffinden von App-Link-Daten mit der Index API findest du in unserer Dokumentation für App-Links.

Ändern von API-Anfragen

Bei einigen API-Endpunkten kannst du zusätzliche Parameter verwenden, um die Anfrage zu ändern. Die Funktionen dieser Modifikatoren variieren. Deshalb haben wir sie einzeln in der jeweiligen API-Referenzdokumentation beschrieben. Im Folgenden findest du eine Liste der gängigen Modifikatoren, die mit den meisten Endpunkten verwendet werden können.

Name Beschreibung Typ

return_ssl_resources

Wird verwendet, wenn ein Bild über eine sichere Verbindung (HTTPS) zurückgegeben werden soll, um Warnungen zu gemischten Inhalten in Browsern zu vermeiden.

bool

locale

Wird verwendet, wenn deine App in der Lage sein soll, lokalisierten Inhalt in der Sprache einer bestimmten Ländereinstellung abzurufen (sofern verfügbar).

Locale

Andere Modifikatoren für Paginierung und Introspektion werden weiter unten gezeigt.

Senden verschachtelter Anfragen

Mit der Felderweiterungsfunktion der Graph API kannst du mehrere Graph-Abfragen effektiv in einem einzelnen Aufruf verschachteln. Bestimmte Ressourcen, wie der Großteil der Ads API, können bei einigen oder allen Verbindungen keine Felderweiterung nutzen.

Du kannst beispielsweise in einem Aufruf nach den ersten N Fotos der ersten K Alben fragen. Die Datenhierarchie wird in der Antwort beibehalten, damit Entwickler die Daten am Client nicht zusammenführen müssen.

Darin besteht der Unterschied zur Batch-Anfrage, einer Funktion, mit der du mehrere, potenziell nicht zusammengehörige Graph API-Aufrufe in einer einzelnen Anfrage tätigen kannst.

Die Felderweiterung hat im Allgemeinen das folgende Format:

GET graph.facebook.com
  /{node-id}?
    fields=<first-level>{<second-level>}

<first-level> besteht in diesem Fall aus einem oder mehreren (durch Komma getrennten) Feldern oder Edges aus dem übergeordneten Node. <second-level> besteht aus einem oder mehreren (durch Komma getrennten) Feldern oder Edges aus dem Node der ersten Ebene.

Du kannst hier beliebig viele Ebenen verschachteln. Du kannst auch anhand des Arguments .limit(n) für jedes Feld oder jede Edge einschränken, wie viele Objekte du abrufen möchtest.

Das lässt sich einfacher mit einem praktischen Beispiel veranschaulichen. Hier siehst du also eine Beispielabfrage, die bis zu fünf Alben abruft, die von einer Person erstellt wurden, sowie die letzten fünf Beiträge im News Feed der Person.

GET graph.facebook.com
  /me?
    fields=albums.limit(5),posts.limit(5)

Dann können wir das noch etwas erweitern und für jedes Albumobjekt auch die ersten zwei Fotos und die in jedem Foto markierten Personen abrufen:

GET graph.facebook.com
  /me?
    fields=albums.limit(5){name, photos.limit(2)},posts.limit(5)

Und das können wir erneut erweitern, indem wir den Namen jedes Fotos, die Bild-URL und die markierten Personen abrufen:

GET graph.facebook.com
  /me?
    fields=albums.limit(5){name, photos.limit(2){name, picture, tags.limit(2)}},posts.limit(5)

Sehen wir uns ein Beispiel mit der Cursor-basierten Paginierung an:

GET graph.facebook.com
  /me?fields=albums.limit(5){name,photos.limit(2).after(MTAyMTE1OTQwNDc2MDAxNDkZD){name,picture,tags.limit(2)}},posts.limit(5)

Du siehst also, wie die Felderweiterung über Nodes, Edges und Felder hinweg funktioniert, sodass du richtig komplexe Daten mit nur einer Anfrage zurückgeben kannst.

Durchlaufen paginierter Ergebnisse

Wenn du eine API-Anfrage für einen Node oder eine Edge ausführst, erhältst du normalerweise nicht alle Ergebnisse dieser Anfrage in einer einzelnen Antwort. Dies liegt daran, dass einige Antworten Tausende Objekte beinhalten könnten. Daher sind die meisten Antworten standardmäßig paginiert.

Cursor-basierte Paginierung

Die Cursor-basierte Paginierung stellt die effizienteste Paginierungsmethode dar und sollte nach Möglichkeit immer verwendet werden. Ein Cursor bezieht sich auf einen zufälligen String für ein bestimmtes Element in einer Datenliste. Solange dieses Element nicht gelöscht wird, zeigt der Cursor immer auf denselben Teil der Liste. Er wird aber ungültig, wenn ein Element entfernt wird. Daher sollte deine App keine Cursor speichern oder davon ausgehen, dass diese in Zukunft gültig sind.

Beim Lesen einer Edge, die Cursor-Paginierung unterstützt, siehst du die folgende JSON-Antwort:

{
  "data": [
     ... Endpoint data is here
  ],
  "paging": {
    "cursors": {
      "after": "MTAxNTExOTQ1MjAwNzI5NDE=",
      "before": "NDMyNzQyODI3OTQw"
    },
    "previous": "https://graph.facebook.com/me/albums?limit=25&before=NDMyNzQyODI3OTQw"
    "next": "https://graph.facebook.com/me/albums?limit=25&after=MTAxNTExOTQ1MjAwNzI5NDE="
  }
}

Eine Cursor-paginierte Edge unterstützt die folgenden Parameter:

  • before: Dies ist der Cursor, der auf den Anfang der Seite mit den zurückgegebenen Daten verweist.
  • after: Dies ist der Cursor, der auf das Ende der Seite mit den zurückgegebenen Daten verweist.
  • limit: Das ist die maximale Anzahl an Objekten, die zurückgegeben werden kann. Aufgrund der Filterung wird bei einer Abfrage möglicherweise ein geringerer limit-Wert zurückgegeben. Die Anzahl der Ergebnisse darf nicht zwingend geringer sein als der limit-Wert, um anzugeben, dass für deine Abfrage das Ende der Datenliste erreicht wurde. Verwende in diesem Fall stattdessen eine Abfrage ohne den nachfolgend erläuterten Parameter next. Wenn du beispielsweise limit auf „20“ festlegst, werden 20 Objekte gefunden, aufgrund der Privatsphärefilterung werden jedoch nur neun angezeigt. Wenn du limit auf „40“ zurücksetzt, werden 40 Objekte gefunden, aber durch die Filterung wieder nur 12 zurückgegeben. Wenn die Suche kein Ergebnis liefert, gibt es keine Paginierung und keinen Hinweis darauf, dass weitere Elemente verfügbar sind. Es können jedoch mehr Elemente verfügbar sein, wenn du limit erhöhst. Einige Edges weisen möglicherweise aus Gründen der Performance einen Höchstwert für den Wert limit auf.
  • next: Der Graph API-Endpunkt, der die nächste Datenseite zurückgibt. Wenn nicht vorhanden, handelt es sich hierbei um die letzte Datenseite. Aufgrund des Zusammenhangs zwischen Paginierung und Sichtbarkeit/Datenschutz kann es vorkommen, dass eine Seite leer ist, aber den Paginierungslink „next“ enthält. Du solltest die Paginierung beenden, wenn der Link „next“ nicht mehr auftaucht.
  • previous: Der Graph API-Endpunkt, der die vorherige Datenseite zurückgibt. Wenn nicht vorhanden, handelt es sich hierbei um die erste Datenseite.

Speichere keine Cursor. Durch das Hinzufügen oder Entfernen von Elementen können Cursor schnell ungültig werden.

Zeitbasierte Paginierung

Anhand der Zeitpaginierung kannst du mit UNIX-Zeitstempeln, die auf bestimmte Zeiten in einer Datenliste verweisen, durch Ergebnisdaten navigieren.

Beim Verwenden eines Endpunkts, der die zeitbasierte Paginierung verwendet, siehst du die folgende JSON-Antwort:

{
  "data": [
     ... Endpoint data is here
  ],
  "paging": {
    "previous": "https://graph.facebook.com/me/feed?limit=25&since=1364849754",
    "next": "https://graph.facebook.com/me/feed?limit=25&until=1364587774"
  }
}

Eine zeitpaginierte Edge unterstützt die folgenden Parameter:

  • until: Ein UNIX-Zeitstempel oder strtotime-Datenwert, der auf das Ende des Bereichs mit den zeitbasierten Daten verweist.
  • since: Ein UNIX-Zeitstempel oder strtotime-Datenwert, der auf den Anfang des Bereichs mit den zeitbasierten Daten verweist.
  • limit: Dies ist die maximale Anzahl an Objekten, die zurückgegeben werden kann. Aufgrund der Filterung wird bei einer Abfrage möglicherweise ein geringerer Wert als limit zurückgegeben. Die Anzahl der Ergebnisse darf nicht zwingend geringer sein als der limit-Wert, um anzugeben, dass für deine Abfrage das Ende der Datenliste erreicht wurde. Verwende in diesem Fall stattdessen eine Abfrage ohne den nachfolgend erläuterten Parameter next. Wenn du beispielsweise limit auf den Wert „10“ festlegst und 9 Ergebnisse zurückgegeben werden, sind möglicherweise weitere Daten verfügbar, es wurde jedoch ein Element aufgrund des Privatsphäre-Filters entfernt. Einige Edges weisen möglicherweise aus Gründen der Performance einen Höchstwert für den Wert limit auf. In jedem Fall gibt die API die richtigen Paginierungslinks zurück.
  • next: Der Graph API-Endpunkt, der die nächste Datenseite zurückgibt.
  • previous: Der Graph API-Endpunkt, der die vorherige Datenseite zurückgibt.

Gib sowohl den Parameter since als auch den Parameter until an, um konsistente Ergebnisse zu erhalten. Außerdem empfehlen wir, einen Zeitabstand von höchstens 6 Monaten zu verwenden.

Offset-basierte Paginierung

Du kannst die Offset-Paginierung verwenden, wenn die chronologische Anordnung keine Rolle spielt und du einfach eine bestimmte Anzahl an Objekten zurückgeben möchtest. Dies solltest du nur verwenden, wenn die Edge keine Cursor- oder zeitbasierte Paginierung unterstützt.

Eine Offset-paginierte Edge unterstützt die folgenden Parameter:

  • offset: Damit wird der Anfang jeder Seite um die angegebene Zahl versetzt.
  • limit: Dies ist die maximale Anzahl an Objekten, die zurückgegeben werden kann. Aufgrund der Filterung wird bei einer Abfrage möglicherweise ein geringerer Wert als limit zurückgegeben. Die Anzahl der Ergebnisse darf nicht zwingend geringer sein als der limit-Wert, um anzugeben, dass für deine Abfrage das Ende der Datenliste erreicht wurde. Verwende in diesem Fall stattdessen eine Abfrage ohne den nachfolgend erläuterten Parameter next. Wenn du beispielsweise limit auf den Wert „10“ festlegst und 9 Ergebnisse zurückgegeben werden, sind möglicherweise weitere Daten verfügbar, es wurde jedoch ein Element aufgrund des Privatsphäre-Filters entfernt. Einige Edges weisen möglicherweise aus Gründen der Performance einen Höchstwert für den Wert limit auf. In jedem Fall gibt die API die richtigen Paginierungslinks zurück.
  • next: Der Graph API-Endpunkt, der die nächste Datenseite zurückgibt. Wenn nicht vorhanden, handelt es sich hierbei um die letzte Datenseite. Aufgrund des Zusammenhangs zwischen Paginierung und Sichtbarkeit/Datenschutz kann es vorkommen, dass eine Seite leer ist, aber den Paginierungslink „next“ enthält. Du solltest die Paginierung beenden, wenn der Link „next“ nicht mehr auftaucht.
  • previous: Der Graph API-Endpunkt, der die vorherige Datenseite zurückgibt. Wenn nicht vorhanden, handelt es sich hierbei um die erste Datenseite.

Hinweis: Wenn neue Objekte der Liste mit den zu durchblätternden Elementen hinzugefügt werden, ändert sich der Inhalt jeder Offset-basierten Seite.

Die Offset-basierte Paginierung wird nicht bei allen API-Aufrufen unterstützt. Um konsistente Ergebnisse zu erreichen, solltest du über die in der Antwort zurückgegebenen Links „previous/next“ paginieren.

Senden großer Anfragen

Einige Graph API-Endpunkte können sehr große Parameter akzeptieren. Wenn deine Anfragen mehr als einige Tausend Zeichen enthalten, können Serverfehler auftreten, da unsere Server sehr große GET-Anfragen ablehnen.

Als Best Practice solltest du bei großen Anfragen eine POST-Anfrage anstelle einer GET-Anfrage verwenden und einen method=GET-Parameter hinzufügen. Dadurch wird der POST-Vorgang als GET-Vorgang interpretiert.

Senden mehrerer Anfragen

Die Standardversion der Graph API dient dazu, das Abrufen von Daten für ein einzelnes Objekt und das Durchsuchen von Verbindungen zwischen Objekten zu vereinfachen. Du kannst damit auch eingeschränkt Daten für mehrere Objekte gleichzeitig abrufen.

Wenn deine App gleichzeitig auf erhebliche Datenmengen zugreifen muss oder du mehrere Objekte gleichzeitig ändern musst, bietet es sich häufig an, Batch-Anfragen anstatt mehrerer individueller HTTP-Anfragen zu tätigen.

Dazu unterstützt die Graph API mehrere Funktionen, wie das Lookup mehrerer IDs und Batching. Batch-Anfragen werden in einem eigenen Leitfaden erläutert, aber weiter unten erfährst du mehr über das Lookup mehrerer IDs.

Leseanfragen mit mehreren IDs

Du kannst eine einzelne GET-Anfrage senden, die mehrere Nodes abruft, indem du den Endpunkt ?ids mit den Objekt-IDs dieser Nodes verwendest. Beispiel: Mit dem folgenden Graph API-Aufruf könntest du die Facebook-Entwicklerseite und den aktuellen Sitzungsnutzer in nur einer Anfrage abrufen:

GET graph.facebook.com
  /?ids=platform,me

Dies entspricht den folgenden individuellen API-Anfragen:

GET graph.facebook.com
  /platform
  
GET graph.facebook.com
  /me

Die zurückgegebenen Daten sehen in etwa wie folgt aus:

{
  "me": {
    "id": "1234567890"
    ... // Other fields
  }, 
  "platform": {
    "id": "19292868552"
    ... // Other fields
  }
}

Dies kann auch mit Edges funktionieren, solange alle angeforderten IDs die angeforderte Edge aufweisen. Beispiel:

GET graph.facebook.com
  /photos?ids={user-id-a},{user-id-b}

Entspricht den folgenden individuellen API-Anfragen:

GET graph.facebook.com
  /{user-id-a}/photos
  
GET graph.facebook.com
  /{user-id-b}/photos

Die zurückgegebenen Daten sehen in etwa wie folgt aus:

{
  "{user-id-a}": {
    "data": [
      {
        "id": "12345", 
        "picture": "{photo-url}", 
        "created_time": "2014-07-15T15:11:25+0000"
      }
      ... // More photos
    ]
  },
  "{user-id-b}": {
    "data": [
      {
        "id": "56789", 
        "picture": "{photo-url}", 
        "created_time": "2014-01-15T12:24:47+0000"
      }
      ... // More photos
    ]
  }, 
}

Beachte, dass Feldfilterung, Felderweiterung und Feldeinschränkung zwar mit diesen Lookups mehrerer IDs funktionieren, aber ein Fehler auftritt, wenn eines der angeforderten Felder in einem der Objekte nicht vorhanden ist. Wenn du beispielsweise eine Seite und einen Nutzer anhand dieser Methode suchst und dann nach fields=id,picture,gender filterst, wird die Anfrage fehlschlagen, da Seiten kein gender-Feld aufweisen.

Introspektion

Die Graph API unterstützt die Introspektion von Nodes. Damit kannst du alle Edges eines Nodes anzeigen, ohne zuvor dessen Typ zu kennen. Füge metadata=1 zur Graph API-Anfrage hinzu, um diese Informationen abzurufen:

GET graph.facebook.com
  /{node-id}?
    metadata=1

Die resultierende JSON-Antwort umfasst eine metadata-Eigenschaft, die alle unterstützten Edges für den jeweiligen Node auflistet:

{
   "name": {node-name},
   "metadata": {
      "connections": {
         "feed": "http://graph.facebook.com/me/feed",
         "picture": "https://graph.facebook.com/me/picture",
         ....
      }
      "fields": [
        {
          "name": "id",
          "description": "The user's Facebook ID. No `access_token` required. `string`."
        },
        ....
      ],
      "type": "user"
   }
}

Veröffentlichung

Die meisten Nodes in der Graph API weisen Edges auf, die als Veröffentlichungsziele verwendet werden können (wie /{user-id}/feed oder /{album-id}/photos). Jede Graph API-Veröffentlichung erfolgt mit einer HTTP-POST-Anfrage an die jeweilige Edge mit allen erforderlichen Parametern. Wenn du beispielsweise einen Beitrag im Namen einer Person veröffentlichen möchtest, tätigst du wie folgt eine HTTP-POST-Anfrage:

POST graph.facebook.com
  /{user-id}/feed?
    message={message}&
    access_token={access-token}

Alle Veröffentlichungsaufrufe müssen mit einem Zugriffsschlüssel signiert sein. In der Graph API-Referenz für den gewünschten Veröffentlichungs-Node kannst du ermitteln, welche Berechtigungen in diesem Zugriffsschlüssel erforderlich sind.

Es gibt zahlreiche Edges, in denen du Daten veröffentlichen kannst. Details hierzu findest du in der Referenzdokumentation für den jeweiligen Node.

In unserem Leitfaden mit gängigen Szenarien für die Graph API findest du weitere Informationen zu einigen gängigen Veröffentlichungssituationen.

Senden mehrerer Anfragen

Du kannst Veröffentlichungsaufrufe anhand von Batch-Anfragen mit Leseaufrufen verketten. Weitere Informationen findest du unter Tätigen mehrerer API-Anfragen.

Read-After-Write (Lesen nach Schreiben)

Viele Edges unterstützen read-after-write. In der Referenzdokumentation für die einzelnen Endpunkte kannst du herausfinden, ob ein Endpunkt read-after-write unterstützt und welche Felder verfügbar sind.

Aktualisieren

Jedes Graph API-Update erfolgt mit einer HTTP-POST-Anfrage an den jeweiligen Node mit allen aktualisierten Parametern:

POST graph.facebook.com
  /{node-id}?
    {updated-field}={new-value}&
    access_token={access-token}

Alle Update-Aufrufe müssen mit einem Zugriffsschlüssel mit den Berechtigungen signiert sein, die für die Veröffentlichung in diesem Endpunkt erforderlich sind. Informationen dazu findest du in der Graph API-Referenz für den zu aktualisierenden Node.

Read-After-Write (Lesen nach Schreiben)

Viele Edges unterstützen read-after-write. In der Referenzdokumentation für die einzelnen Endpunkte kannst du herausfinden, ob ein Endpunkt read-after-write unterstützt und welche Felder verfügbar sind.

Löschen

Du kannst Nodes mit HTTP-DELETE-Anfragen aus dem Graph löschen:

DELETE graph.facebook.com
  /{node-id}?
    access_token=...

Im Allgemeinen können nur Inhalte von einer App gelöscht werden, die auch ursprünglich von dieser App erstellt wurden. Im Referenzleitfaden für den betreffenden Node oder die betreffende Edge erhältst du weitere Informationen hierzu.

Für Clients, die nicht alle HTTP-Methoden unterstützen, kannst du alternativ auch eine POST-Anfrage an einen Endpunkt mit dem zusätzlichen Argument method=delete senden, um die HTTP-Methode außer Kraft zu setzen. Du kannst beispielsweise einen Kommentar löschen, indem du die folgende Anfrage ausgibst:

POST graph.facebook.com
  /{comment-id}?
    method=delete

Read-After-Write (Lesen nach Schreiben)

Für Erstellungs- und Aktualisierungsendpunkte kann die Graph API ein erfolgreich veröffentlichtes oder aktualisiertes Objekt sofort lesen und alle Felder zurückgeben, die vom jeweiligen Leseendpunkt unterstützt werden.

Um dieses Feature zu verwenden, musst du einen fields-Parameter in deine Anfrage aufnehmen und die gewünschten Felder auflisten. Um beispielsweise die Nachricht „Hello“ im Feed eines Nutzers zu veröffentlichen, könntest du die folgende Anfrage senden:

POST graph.facebook.com
  /126577551217199/feed?
    message=Hello&
    fields=created_time,from,id,message,permalink_url

Dabei werden die angegebenen Felder als Antwort im JSON-Format zurückgegeben. Dies sieht wie folgt aus:

{
  "created_time": "2017-04-06T22:04:21+0000",
  "from": {
    "name": "Jay P Jeanne",
    "id": "126577551217199"
  },
  "id": "126577551217199_122842541590700",
  "message": "Hello",
  "permalink_url": "https://www.facebook.com/126577551217199/posts/122842541590700",
}

In der Referenzdokumentation für die einzelnen Endpunkte kannst du herausfinden, ob ein Endpunkt read-after-write unterstützt und welche Felder verfügbar sind.

Fehler

Wenn der Lesevorgang aus irgendeinem Grund fehlschlägt (z. B. bei der Anfrage eines nicht vorhandenen Feldes), sendet die Graph API eine Standard-Fehlerantwort. Die Antwort enthält außerdem eine original_response-Eigenschaft mit dem Wert, der normalerweise bei einem erfolgreichen Vorgang vom Endpunkt zurückgegeben wird.

Diese Anfrage enthält beispielsweise ein ungültiges Feld:

POST graph.facebook.com
  /126577551217199/feed?
    message=Hello&
    fields=permalink_urls

Die Antwort würde hier wie folgt lauten:

{
  "error": {
    "message": "(#100) Tried accessing nonexisting field (permalink_urls) on node type (Post)",
    "type": "FacebookApiException",
    "code": 100,
    "fbtrace_id": "AzMnKh6NRKY",
    "original_response": {
      "id": "126577551217199_122842541590700"
    }
  }
}

Mit dem Endpunkt /search kannst du zahlreiche öffentliche Objekte im Social Graph durchsuchen. Die Suchsyntax lautet wie folgt:

GET graph.facebook.com
  /search?
    q={your-query}&
    type={object-type}

Bei allen Graph API-Suchanfragen ist ein Zugriffsschlüssel in der Anfrage erforderlich. Du brauchst einen Nutzerzugriffsschlüssel, um eine Suche auszuführen.

Verfügbare Suchtypen

Wir unterstützen die Suche nach den folgenden Typen:

Typ Beschreibung „q“-Wert

user

Suche nach einer Person (wenn diese Person die Suche nach ihrem Namen zulässt).

Name

page

Suche nach einer Seite.

Name

event

Suche nach einer Veranstaltung.

Name

group

Suche nach einer Gruppe.

Name

place

Suche nach einem Ort. Du kannst deine Suche auf einen bestimmten Standort und eine Entfernung eingrenzen, indem du den Parameter center (mit Längengrad und Breitengrad) und einen optionalen distance-Parameter (in Metern) hinzufügst:

Name

placetopic

Gibt eine Liste der möglichen Seitenthemen und deren IDs zurück. Mit dem Parameter topic_filter=all rufst du die vollständige Liste ab.

Keine

ad_*

Eine Sammlung verschiedener Suchoptionen, mit denen du Targeting-Optionen finden kannst.

Siehe Targeting-Optionen

Beispiel:

GET graph.facebook.com
  /search?
    q=coffee&
    type=place&
    center=37.76,-122.427&
    distance=1000

Umgang mit Fehlern

API-Anfragen können zu mehreren verschiedenen Fehlerantworten führen. Das folgende Thema behandelt die Fehlerbehebungsverfahren und enthält eine Liste der Fehlerwerte mit einer Angabe der jeweils gängigsten Behebungsmaßnahme.

Empfangen von Fehlercodes

Das folgende Beispiel stellt eine gängige Fehlerantwort bei einer fehlgeschlagenen API-Anfrage dar:

{
  "error": {
    "message": "Message describing the error", 
    "type": "OAuthException", 
    "code": 190,
    "error_subcode": 460,
    "error_user_title": "A title",
    "error_user_msg": "A message",
    "fbtrace_id": "EJplcsCHuLu"
  }
}
  • message: Eine für Menschen lesbare Beschreibung des Fehlers.
  • code: Ein Fehlercode. Hierzu werden weiter unten einige häufige Werte aufgeführt, zusammen mit den jeweils gängigen Behebungsverfahren.
  • error_subcode: Zusätzliche Informationen zu diesem Fehler. Weiter unten werden einige gängige Werte aufgeführt.
  • error_user_msg: Die Meldung, die dem Nutzer angezeigt wird. Die Sprache der Meldung richtet sich nach der Ländereinstellung der API-Anfrage.
  • error_user_title: Der Titel des Dialogs, sofern er angezeigt wird. Die Sprache der Meldung richtet sich nach der Ländereinstellung der API-Anfrage.
  • fbtrace_id: Interne Support-ID. Wenn du einen Fehler mit einem Graph API-Aufruf meldest, gib die fbtrace_id an, damit wir leichter Logdaten für das Debuggen finden können.

Fehlercodes

Code oder Typ Name Vorgehensweise

OAuthException

Wenn kein Untercode vorhanden ist, bedeutet dies, dass der Login-Status oder Zugriffsschlüssel abgelaufen ist, entzogen wurde oder auf andere Weise ungültig ist. Rufe einen neuen Zugriffsschlüssel ab.

Wenn ein Untercode vorhanden ist, findest du darin weitere Informationen.

102

API-Sitzung

Wenn kein Untercode vorhanden ist, bedeutet dies, dass der Login-Status oder Zugriffsschlüssel abgelaufen ist, entzogen wurde oder auf andere Weise ungültig ist. Rufe einen neuen Zugriffsschlüssel ab.

Wenn ein Untercode vorhanden ist, findest du darin weitere Informationen.

1

API unbekannt

Möglicherweise ein vorübergehendes Problem wegen eines Ausfalls. Warte einen Moment und wiederhole den Vorgang später. Wenn der Fehler erneut auftritt, stelle sicher, dass die angefragte API vorhanden ist.

2

API-Dienst

Vorübergehendes Problem wegen eines Ausfalls. Warte einen Moment und wiederhole den Vorgang später.

4

Zu viele API-Aufrufe

Vorübergehendes Problem wegen Throttling. Warte einen Moment und wiederhole den Vorgang später oder prüfe die Anzahl deiner API-Anfragen.

17

Zu viele API-Nutzeraufrufe

Vorübergehendes Problem wegen Throttling. Warte einen Moment und wiederhole den Vorgang später oder prüfe die Anzahl deiner API-Anfragen.

10

API-Berechtigung abgelehnt

Die Berechtigung wurde entweder entzogen oder nicht erteilt. Verarbeite die fehlenden Berechtigungen.

190

Zugriffsschlüssel ist abgelaufen

Rufe einen neuen Zugriffsschlüssel ab.

200-299

API-Berechtigung (mehrere Werte je nach Berechtigung)

Die Berechtigung wurde entweder entzogen oder nicht erteilt. Verarbeite die fehlenden Berechtigungen.

341

App-Limit erreicht

Vorübergehendes Problem wegen eines Ausfalls oder wegen Throttling. Warte einen Moment und wiederhole den Vorgang später oder prüfe die Anzahl deiner API-Anfragen.

368

Aufgrund von Richtlinienverstößen vorübergehend gesperrt

Warte einen Moment und wiederhole den Vorgang später.

506

Doppelter Beitrag

Identische Beiträge können nicht direkt nacheinander veröffentlicht werden. Ändere den Inhalt des Beitrags und versuche es erneut.

1609005

Fehler beim Posten des Links

Beim Auslesen von Daten aus dem angegebenen Link ist ein Problem aufgetreten. Prüfe die URL und versuche es erneut.

Untercodes für Authentifizierungsfehler

Code Name Vorgehensweise

458

App nicht installiert

Der Nutzer hat sich nicht bei deiner App angemeldet. Versuche erneut, den Nutzer zu authentifizieren.

459

Nutzer bei Checkpoint abgefangen

Der Nutzer muss sich bei https://www.facebook.com oder https://m.facebook.com anmelden, um dieses Problem zu beheben.

460

Passwort geändert

Wenn die Person sich bei iOS 6 und höher über den betriebssystemintegrierten Ablauf angemeldet hat, sollte sie zu den Betriebssystemeinstellungen für Facebook auf dem Gerät umgeleitet werden, um ihr Passwort zu aktualisieren. Andernfalls muss sie sich erneut bei der App anmelden.

463

Abgelaufen

Login-Status oder Zugriffsschlüssel ist abgelaufen, wurde entzogen oder ist ungültig. Verarbeite abgelaufene Zugriffsschlüssel.

464

Nicht bestätigter Nutzer

Der Nutzer muss sich bei https://www.facebook.com oder https://m.facebook.com anmelden, um dieses Problem zu beheben.

467

Ungültiger Zugriffsschlüssel

Zugriffsschlüssel ist abgelaufen, wurde entzogen oder ist ungültig. Verarbeite abgelaufene Zugriffsschlüssel.

Komplexe Parameter

Die meisten Parametertypen sind ganz normale Primitive, wie string und int. Es gibt aber auch list- und object-Typen, die in der Anfrage angegeben werden können.

Der list-Typ wird in JSON-Syntax angegeben, wie: ["firstitem", "seconditem", "thirditem"]

Der object-Typ wird ebenfalls in JSON-Syntax angegeben, wie: {"firstkey": "firstvalue", "secondKey": 123}

Debuggen von API-Anfragen

Graph API-Debug-Modus

Wenn der Debug-Modus aktiviert ist, kann die Graph API-Antwort zusätzliche Felder enthalten, die mögliche Probleme mit der Anfrage erläutern.

Du aktivierst den Debug-Modus mit dem Abfrage-String-Parameter debug. Beispiel:

GET graph.facebook.com
  /v2.3/me/friends
    access_token=...&
    debug=all

Wenn die Berechtigung user_friends nicht erteilt wurde, ergibt dies die folgende Antwort:

{
  "data": [
  ], 
  "__debug__": {
    "messages": [
      {
        "message": "Field friends is only accessible on User object, if user_friends permission is granted by the user", 
        "type": "warning"
      }, 
      {
        "link": "https://developers.facebook.com/docs/apps/changelog#v2_0", 
        "message": "Only friends who have installed the app are returned in versions greater or equal to v2.0.", 
        "type": "info"
      }
    ]
  }
}

Der Wert des debug-Parameters kann auf „all“ oder auf den mindestens angeforderten Schweregrad gesetzt werden, der dem type der Meldung entspricht:

Debug-Parameterwert Rückgabewert

all

Alle verfügbaren Debug-Meldungen

info

Debug-Meldungen mit den Typen info und warning

warning

Nur Debug-Meldungen mit dem Typ warning

Debug-Informationen werden (sofern verfügbar) als JSON-Objekt unter dem Schlüssel __debug__ im Array messages zurückgegeben. Jedes Element dieses Arrays ist ein JSON-Objekt mit den folgenden Feldern:

Feld Datentyp Beschreibung

message

String

Die Meldung.

type

String

Der Schweregrad der Meldung.

link

String

[Optional] Eine URL, die auf zugehörige Informationen verweist.

Du kannst den Debug-Modus auch mit Graph API Explorer verwenden.

Bestimmen der von API-Anfragen verwendeten Version

Beim Erstellen einer App und Tätigen von Graph API-Anfragen kann es sich als nützlich erweisen, zu bestimmen, von welcher API-Version du eine Antwort erhältst. Wenn du beispielsweise Aufrufe ohne angegebene Version tätigst, ist dir die antwortende API-Version möglicherweise nicht bekannt.

Die Graph API bietet in jeder Antwort einen Anfrage-Header mit dem Namen facebook-api-version, der die genaue Version der API angibt, die die Antwort erstellt hat. Beispiel: Ein Graph API-Aufruf, der eine Anfrage mit Version 2.0 erstellt, hat den folgenden HTTP-Header:

facebook-api-version:v2.0

Mit diesem facebook-api-version-Header kannst du bestimmen, ob API-Aufrufe von der erwarteten Version zurückgegeben werden.

Debug-Info zum Melden von Fehlern

Wenn du einen Fehler in der Graph API melden musst, fügen wir einige zusätzliche Anfrage-Header hinzu, die du mit dem Fehlerbericht senden solltest, damit wir dein Problem besser diagnostizieren und reproduzieren können. Diese Anfrage-Überschriften lauten X-FB-Debug, x-fb-rev und X-FB-Trace-ID.