Graph API

Übersicht

Die Graph API ist die gängigste Methode, mit der du Daten in die Facebook-Plattform einliest und daraus abrufst. Dabei handelt es sich um eine HTTP-basierte API, mit der du programmgesteuert Daten abfragen, neue Stories posten, Werbeanzeigen verwalten, Fotos hochladen und zahlreiche andere Aufgaben ausführen kannst.

Die Graph API erhält ihren Namen vom Konzept eines „Social Graphs“, einer Darstellung der Informationen auf Facebook. Sie besteht aus Nodes, Edges und Feldern. Normalerweise verwendest du Nodes, um Daten über ein spezifisches Objekt abzurufen; du verwendest Edges, um Sammlungen von Objekten zu einem einzelnen Objekt abzurufen; und du nutzt Felder, um Daten zu einem einzelnen Objekt oder einzelnen Objekten in einer Sammlung abzurufen. Im Rahmen dieser Dokumentation werden sowohl Nodes als auch Edges als „Endpunkte“ bezeichnet. Beispielsweise könnte eine Anweisung lauten: „Eine GET-Abfrage an den Benutzerendpunkt senden“.

HTTP

Alle Datenübertragungen entsprechen HTTP/1.1; für alle Endpunkte ist HTTPS erforderlich. Da die Graph API HTTP-basiert ist, funktioniert sie mit jeder Sprache, die eine HTTP-Bibliothek aufweist, beispielsweise cURL und urllib. Das heißt, du kannst die Graph API direkt in deinem Browser verwenden. Wenn du beispielsweise die folgende URL in deinem Browser abrufst ...

https://graph.facebook.com/facebook/picture?redirect=false

... entspricht dies dieser cURL-Abfrage:

curl -i -X GET "https://graph.facebook.com/facebook/picture?redirect=false"

Wir haben außerdem die includeSubdomains-HSTS-Direktive auf facebook.com aktiviert. Hierdurch sollten Graph API-Anfragen nicht beeinträchtigt werden.

Host-URL

Fast alle Anfragen werden an die Host-URL graph.facebook.com übergeben. Die einzige Ausnahme sind Video-Uploads, die graph-video.facebook.com verwenden.

Zugriffsschlüssel

Deine App kann über Zugriffsschlüssel auf die Graph API zugreifen. Nahezu alle Graph API-Endpunkte erfordern einen bestimmten Zugriffsschlüssel. Daher muss deine Anfrage bei jedem Zugriff auf einen Endpunkt einen Zugriffsschlüssel enthalten. Zugriffsschlüssel führen in der Regel zwei Funktionen aus:

  • Deine App kann auf die Informationen eines Users zugreifen, ohne dass das Passwort des Users erforderlich ist. Beispielsweise benötigt deine App die E-Mail-Adresse eines Users, um eine Funktion auszuführen. Wenn der User deiner App gestattet, seine E-Mail-Adresse von Facebook abzurufen, muss er sein Facebook-Passwort in deiner App nicht mehr eingeben.
  • Sie ermöglichen es, deine App, den User, der deine App verwendet, und die Art der Daten zu identifizieren, auf die der User deiner App Zugriff gewährt.

Weitere Informationen hierzu findest du in der Dokumentation zu Zugriffsschlüsseln.

Nodes

Ein Node ist ein einzelnes Objekt mit einer eindeutigen ID. Es gibt beispielsweise viele User-Node-Objekte, wobei jedes eine eindeutige ID einer Person auf Facebook aufweist. Seiten, Gruppen, Posts, Fotos und Kommentare sind nur einige Beispiele für Nodes im Facebook Social Graph.

Das folgende cURL-Beispiel stellt einen Aufruf des User-Nodes dar.

curl -i -X GET \
  "https://graph.facebook.com/USER-ID?access_token=ACCESS-TOKEN"

Bei der Abfrage werden standardmäßig die folgenden Daten zurückgegeben, die in JSON formatiert sind:

{
  "name": "Your Name",
  "id": "YOUR-USER-ID"
}

Node-Metadaten

Du kannst für ein Node-Objekt wie User, Seite oder Foto eine Liste aller Felder abrufen, einschließlich Feldname, Beschreibung und Datentyp. Sende dazu eine GET-Abfrage an eine Objekt-ID und nimm darin den metadata=1-Parameter auf:

curl -i -X GET \
  "https://graph.facebook.com/USER-ID?
    metadata=1&access_token=ACCESS-TOKEN"

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

{
  "name": "Jane Smith",
  "metadata": {
    "fields": [
      {
        "name": "id",
        "description": "The app user's App-Scoped User ID. This ID is unique to the app and cannot be used by other apps.",
        "type": "numeric string"
      },
      {
        "name": "age_range",
        "description": "The age segment for this person expressed as a minimum and maximum age. For example, more than 18, less than 21.",
        "type": "agerange"
      },
      {
        "name": "birthday",
        "description": "The person's birthday.  This is a fixed format string, like `MM/DD/YYYY`.  However, people can control who can see the year they were born separately from the month and day so this string can be only the year (YYYY) or the month + day (MM/DD)",
        "type": "string"
      },
...

/me

Der /me-Node ist ein besonderer Endpunkt, der der Objekt-ID der Person oder Seite entspricht, deren Zugriffsschlüssel gerade für die API-Aufrufe verwendet wird. Mit einem Userzugriffsschlüssel könntest du wie folgt den Namen und die ID des Users abrufen:

curl -i -X GET \
  "https://graph.facebook.com/me?access_token=ACCESS-TOKEN"

Edges

Eine Edge ist eine Verbindung zwischen zwei Nodes. Beispielsweise können mit einem User-Node Fotos und mit einem Foto-Node Kommentare verknüpft sein. Mit dem folgenden cURL-Beispiel wird eine Liste von Fotos zurückgegeben, die eine Person auf Facebook veröffentlicht hat.

curl -i -X GET \
  "https://graph.facebook.com/USER-ID/photos?access_token=ACCESS-TOKEN"

Jede zurückgegebene ID stellt einen Foto-Node mit der entsprechenden Upload-Zeit auf Facebook dar.

    {
  "data": [
    {
      "created_time": "2017-06-06T18:04:10+0000",
      "id": "1353272134728652"
    },
    {
      "created_time": "2017-06-06T18:01:13+0000",
      "id": "1353269908062208"
    }
  ],
}

Felder

Felder sind Node-Eigenschaften. Wenn du eine Abfrage an einen Node oder eine Edge sendest, gibt diese(r) standardmäßig verschiedene Felder zurück – wie in den Beispielen oben gezeigt. Du kannst jedoch angeben, welche Felder zurückgegeben werden sollen, indem du für jedes Feld den fields-Parameter und Listen verwendest. Damit wird die Standardeinstellung überschrieben und es werden nur die von dir definierten Felder zurückgegeben. Darüber hinaus wird die ID des Objekts zurückgegeben (diese wird immer zurückgegeben).

Die folgende cURL-Abfrage enthält den fields-Parameter sowie den Namen, die E-Mail-Adresse und das Profilbild des Users.

curl -i -X GET \
  "https://graph.facebook.com/USER-ID?fields=id,name,email,picture&access_token=ACCESS-TOKEN"

Zurückgegebene Daten

{
  "id": "USER-ID",
  "name": "EXAMPLE NAME",
  "email": "EXAMPLE@EMAIL.COM",
  "picture": {
    "data": {
      "height": 50,
      "is_silhouette": false,
      "url": "URL-FOR-USER-PROFILE-PICTURE",
      "width": 50
    }
  }
}

Komplexe Parameter

Die meisten Parametertypen sind ganz normale Primitive, wie bool, 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}

Veröffentlichung, Aktualisierung und Löschung

In unserem Facebook-Leitfaden zum Teilen erfährst du, wie du Inhalte im Facebook-Bereich eines Users veröffentlichst. In der Pages API-Dokumentation hingegen erfährst du, wie du Inhalte im Facebook-Feed einer Seite veröffentlichst.

In einigen Nodes kannst du Felder über POST-Vorgänge aktualisieren. So könntest du beispielsweise dein email-Feld folgendermaßen aktualisieren:

curl -i -X POST \
  "https://graph.facebook.com/USER-ID?email=YOURNEW@EMAILADDRESS.COM&access_token=ACCESS-TOKEN"

Read-After-Write

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.

Standardmäßig wird eine ID des erstellten oder aktualisierten Objekts zurückgegeben. Um weitere Informationen in die Antwort aufzunehmen, musst du den fields-Parameter in deine Anfrage aufnehmen und die Felder auflisten, die zurückgegeben werden sollen. Um beispielsweise die Nachricht „Hello“ im Feed einer Seite zu veröffentlichen, könntest du die folgende Anfrage senden:

curl -i - X POST "https://graph.facebook.com/PAGE-ID/feed?message=Hello&
  fields=created_time,from,id,message&access_token=ACCESS-TOKEN"
Wir haben das obige Code-Beispiel für eine bessere Lesbarkeit formatiert.

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": "My Facebook Page",
    "id": "PAGE-ID"
  },
  "id": "POST_ID",
  "message": "Hello",
}

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 (wenn beispielsweise ein nicht vorhandenes Feld angefragt wird), gibt die Graph API eine standardmäßige Fehlermeldung zurück. In unserem Leitfaden zum Umgang mit Fehlern erfährst du mehr dazu.

Ein Node wie beispielsweise ein Post- oder Foto-Node lässt sich normalerweise löschen, indem du für die Objekt-ID einen DELETE-Vorgang ausführst:

curl -i -X DELETE \
  "https://graph.facebook.com/PHOTO-ID?access_token=ACCESSS-TOKEN"

In der Regel kannst du nur Nodes löschen, die du selbst erstellt hast. Eine ausführliche Erläuterung zu den Anforderungen für Löschvorgänge findest du in der Referenz der einzelnen Nodes.

Webhooks

Du kannst Benachrichtigungen über Änderungen an Nodes oder Interaktionen mit Nodes erhalten, indem du Webhooks abonnierst. Siehe Webhooks.

Versionen

Die Graph API hat mehrere Versionen, die vierteljährlich veröffentlicht werden. Du kannst in deinen Aufrufen die Version angeben, indem du dem Pfad der Anfrage ein "v" und die gewünschte Versionsnummer voranstellst. Hier siehst du einen Beispielaufruf für Version 4.0:

curl -i -X GET \
  "https://graph.facebook.com/v4.0/USER-ID/photos
    ?access_token=ACCESS-TOKEN"

Wenn du keine Versionsnummer einbindest, wird standardmäßig die älteste verfügbare Version verwendet. Aus diesem Grund empfiehlt es sich, eine Versionsnummer in deinen Anfragen anzugeben.

Mehr zu unseren Versionen erfährst du in unserem Leitfaden zur Versionierung. Informationen zu allen verfügbaren Versionen sind im Graph API-Änderungsprotokoll zu finden.

Facebook-APIs, -SDKs und -Plattformen

Mithilfe der verschiedenen APIs, SDKs und Plattformen von Facebook kannst du Schnittstellen einbinden und plattformübergreifend entwickeln.

Nächste Schritte

Erste Schritte mit Graph API – Schauen wir uns einmal den Facebook Social Graph mit dem Graph Explorer-Tool näher an und führen einige Datenanfragen aus.