Graph API – Übersicht

Die Graph API ist die gängigste Methode, mit der du Daten aus der Facebook-Plattform abrufst und darin einliest. Dabei handelt es sich um eine einfache HTTP-basierte API, mit der du programmatisch Daten abfragen, neue Meldungen posten, Werbeanzeigen verwalten, Fotos hochladen und zahlreiche andere Aufgaben ausführen kannst, die eventuell für eine App erforderlich sind.

Die Grundlagen

Die Graph API erhält ihren Namen vom Konzept eines „Social Graphs“, einer Darstellung der Informationen auf Facebook, die aus Folgendem besteht:

  • Nodes: kurz gesagt, die Dinge, die auf Facebook angezeigt werden, wie Nutzer, Fotos, Seiten, Kommentare
  • Edges: die Verbindungen zwischen diesen Dingen, wie die Fotos oder Kommentare auf einer bestimmten Seite
  • Felder: Informationen zu diesen Dingen, wie Geburtstage von Personen oder Namen von Seiten

Die Graph API ist HTTP-basiert und funktioniert daher mit jeder Sprache, die eine HTTP-Bibliothek aufweist, beispielsweise cURL und urllib. Im folgenden Abschnitt stellen wir die Einsatzmöglichkeiten etwas genauer vor. Es bedeutet aber vor allem, dass du die Graph API direkt im Browser verwenden kannst. Eine Graph API-Anfrage entspricht beispielsweise:

GET graph.facebook.com
  /facebook/picture?
    redirect=false

Bei den meisten Graph API-Anfragen musst du Zugriffsschlüssel verwenden, die deine App generieren kann, wenn du Facebook Login implementiert hast.

In dieser Übersicht erfährst du, wie die Graph API Daten im Social Graph liest und veröffentlicht.

Struktur

Wir stellen die Struktur in unserem Leitfaden Verwenden der Graph API ausführlich vor. Im Allgemeinen kannst du APIs aber lesen, indem du HTTP-GET-Anfragen an Nodes oder Edges auf diesen Nodes sendest.

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

Objekt-IDs

Jeder Node weist eine eindeutige ID auf, mit der über die Graph API darauf zugegriffen wird. Wir bieten keine Dokumentation für Node/Objekt-ID-Struktur oder -Format an, da diese sich mit größter Wahrscheinlichkeit im Laufe der Zeit ändern und Apps keine Annahmen aufgrund der aktuellen Struktur treffen sollten.

So stellst du eine Anfrage für einen Node anhand der ID:

GET graph.facebook.com
  /{node-id}

Bzw. für die Edge:

GET graph.facebook.com
  /{node-id}/{edge-name}

Du kannst Daten im Allgemeinen in APIs veröffentlichen, indem du HTTP-POST-Anfragen mit Parametern für den Node sendest:

POST graph.facebook.com
  /{node-id}

Bzw. für die Edge:

POST graph.facebook.com
  /{node-id}/{edge-name}

Das Löschen über APIs erfolgt anhand von HTTP-DELETE-Anfragen (und das Aktualisieren über POST-Anfragen) an dieselben Endpunkte.

API-Versionen

Du kannst jeweils immer auf mehrere Versionen der Graph API zugreifen. Jede Version umfasst einen Satz aus Kern-Feldern und Edge-Vorgängen. Wir garantieren, dass diese Kern-APIs in der jeweiligen Version mindestens zwei Jahre ab Veröffentlichung unverändert verfügbar sind. Im Änderungsprotokoll der Plattform erfährst du, welche Versionen derzeit verfügbar sind.

Bestimmte Vorgänge, wie das Veröffentlichen in einer Edge oder in bestimmten Feldern in einem Node, können Kernvorgänge sein, ohne dass die gesamte Edge oder der Node ein Kernelement ist. Wir kennzeichnen diese Kern-APIs mit diesem Symbol in unserer Graph API-Referenzdokumentation.

Alle Elemente außerhalb dieser Kern-APIs sind erweiterte APIs. Der Zugriff auf diese APIs erfolgt weiterhin über versionierte Pfade, sie können aber jederzeit geändert oder entfernt werden (nach einem Migrationszeitraum von 90 Tagen, der auf unserer Plattform-Roadmap angekündigt wird). Alternativ dazu können sie auch einfach in die nächste verfügbare API-Version aufgenommen werden.

In unserem Leitfaden erfährst du mehr über den Zweck der Versionierung, aber hier erläutern wir, wie du eine bestimmte Version der Graph API aufrufst.

Ganz einfach: Du stellst lediglich die Versions-ID vor den Anfang des Anfragepfads. Hier siehst du einen Beispielaufruf an v2.2:

GET graph.facebook.com
  /v2.2/me

Das funktioniert in dieser allgemeinen Form für alle Versionen:

GET graph.facebook.com
  /vX.Y/{request-path}

wobei X.Y für die gewünschte Version steht. Wir veröffentlichen eine vollständige Liste der verfügbaren Versionen in unserem Änderungsprotokoll. Unsere gesamte Graph API-Referenzdokumentation enthält versionsspezifische Informationen. Achte also darauf, dass du die richtige Version prüfst. Bei einigen Versionen werden Nodes und Edges entfernt, bei anderen Versionen werden sie hinzugefügt.

Jetzt zeigen wir dir, wie einfach eine API-Anfrage ist.

Graph API Explorer laden

Die einfachste Nutzung der Graph API erreichst du mit dem Graph API Explorer, einem benutzerfreundlichen Tool, mit dem du Daten abfragen, hinzufügen und entfernen kannst. Diese Ressource ist bei der Integration in Facebook ganz besonders nützlich. Du gehst also als Nächstes zum Graph API Explorer.

Graph API Explorer

Einfachen Nutzerzugriffsschlüssel generieren

Wenn du deine eigene App erstellst, musst du dich mit Zugriffsschlüsseln und deren Erstellung mit Facebook Login vertraut machen. Für unsere Zwecke können wir einfach schnell einen Schlüssel über den Graph API Explorer abrufen:

  1. Klicke auf den Button Get Token oben rechts im Explorer.
  2. Wähle die Option Get User Access Token.
  3. Aktiviere im nächsten Dialog keine Kontrollkästchen, sondern klicke einfach auf den blauen Button Get Access Token.
  4. Klicke im daraufhin angezeigten Facebook Login-Dialog auf OK, um fortzufahren.

Erste Anfrage stellen

Jetzt kannst du deine erste Graph API-Anfrage senden. Wir beginnen dabei mit einer „read“-Anfrage. Lösche den vorhandenen Text neben dem Dropdown-Button „GET“ (wir bezeichnen dies als Pfadfeld) und gib „me“ ein:

Klicke dann auf den Button „Submit“. Die Verarbeitung dauert einige Sekunden. Dann solltest du eine Reihe von Informationen im Antwortbereich sehen. Die hier angezeigten Informationen sind von den Privatsphäre-Einstellungen deines Profils abhängig, sollten jedoch mindestens einige grundlegende Felder umfassen:

Diese Aktion, die du gerade im Graph API Explorer ausgeführt hast, entspricht der folgenden Graph API-„read“-Anfrage:

GET graph.facebook.com
  /me

/me ist ein spezieller Endpunkt, der für die Nutzer-ID der Person steht, mit deren Zugriffsschlüssel die Anfrage ausgeführt wird.

Herzlichen Glückwunsch, du hast gerade deine erste Graph API-Anfrage getätigt.

Veröffentlichungsberechtigungen erhalten

Als Nächstes veröffentlichen wir etwas mit der Graph API auf Facebook. Das würdest du nur dann in deiner App machen, wenn du deinen eigenen Composer erstellst und keinen der Dialoge „Teilen“ für das Web, iOS oder Android verwendest. Dank der Dialoge „Teilen“ von Facebook musst du nicht Facebook Login implementieren oder deine eigene Benutzeroberfläche erstellen, in der Personen Meldungen teilen können.

Um die Veröffentlichung mit der Graph API auszuprobieren, klicke erneut auf den Button „Get Access Token“ und wähle dieses Mal die Berechtigung publish_actions:

Wenn du jetzt auf den blauen Button „Get Access Token“ klickst, siehst du wieder den Login-Dialog. Hier musst du dem Graph API Explorer die Berechtigung erteilen, in deinem Namen zu posten. Bei Bedarf kannst du die Zielgruppe hier in „Nur ich“ ändern, sodass nur du den Beitrag sehen kannst. Du solltest diesen Dialog aber akzeptieren und mit dem nächsten Schritt weitermachen.

Beitrag veröffentlichen

Wenn du die Berechtigung publish_actions angefragt hast, klicke jetzt auf den Button „GET“ und wähle im daraufhin angezeigten Dropdown-Menü die Option „POST“. Gib me/feed in das Pfadfeld ein und klicke auf „Add a Field“.

Gib in die neu angezeigten Felder message als „name“ und Hello, World als „value“ ein. Hierdurch sollte ein Bildschirm wie der Folgende angezeigt werden:

Klicke jetzt auf den blauen Button „Submit“. Nach einigen Sekunden sollte der Antwortbereich in etwa wie folgt aussehen:

{
  "id": "{new-post-id}"
}

Das bedeutet, dass du gerade deinen ersten Beitrag über die Graph API veröffentlicht hast. Du kannst jetzt zu deinem Profil gehen und solltest den Beitrag dort sehen können:

Diese Aktion, die du gerade im Graph API Explorer ausgeführt hast, entspricht der folgenden Graph API-„publish“-Anfrage:

POST graph.facebook.com
  /me/feed?
    message="Hello, World."&
    access_token={your-access-token}

Nächste Schritte

Nachdem du die Grundlagen kennen gelernt hast, solltest du dich noch intensiver mit der Verwendung der Graph API vertraut machen. Wir empfehlen, zunächst mehr über Facebook Login und vor allem über das Generieren von Zugriffsschlüsseln zu erfahren, damit du komplexere Graph API-Anfragen tätigen kannst.