Referenzen zur Graph API

Übersicht

Die Graph API für Workplace ist eine programmgesteuerte Methode, mit der du Daten in Workplace einlesen und daraus abrufen kannst. Es handelt sich dabei um eine einfache HTTP-basierte API, die du dazu verwenden kannst, Daten zu Objekten in einem Workplace-Graphen abzufragen.

Die Graph API ist nach der Idee eines Graph-Datenmodells benannt, in dem Objekte von Nodes dargestellt und anhand von Edges zusammengeführt werden. Auf API-Ebene greifen Apps so auf die Informationen in Workplace zu. Die Graph API for Workplace bietet eine Teilmenge der Funktionalität der Graph API. Diese Funktionalität ist auf Interaktionen mit einer Workplace-Community beschränkt und unterscheidet sich in einigen Fällen zu Gunsten einer verbesserten Leistungsfähigkeit oder Verwendbarkeit.

Weitere Informationen über die Verwendung der Graph API für Workplace findest du weiter unten:

Workplace Graph API-Objekte

Die folgenden Nodes sind über die Workplace Graph API zugänglich. Für den Zugriff auf alle Nodes sollte ein benutzerdefinierter Zugriffsschlüssel für Integration verwendet werden.

Community

Eine Workplace-Community. Die Stammgruppe deiner Workplace Graph API-Aufrufe.

Gruppen

Eine Workplace-Gruppe.

Beiträge

Ein Beitrag, der in einer Gruppe oder im Profil eines Mitglieds veröffentlicht wurde.

Mitglieder

Ein Konto für eine*n bestimmte*n Workplace-Nutzer*in.

Beispiele für das Kombinieren von Graph API-Aufrufen zum Lösen bestimmter Probleme findest du in der Liste mit Beispiel-Apps.

Verwenden der Graph API

Graph API-Objekte

Die Graph API stellt die in Workplace enthaltenen Informationen dar, die wie folgt zusammengesetzt sind:

• Nodes: Objekte wie ein Nutzer, ein Foto, ein Beitrag oder ein Kommentar
• Edges: Verbindungen zwischen diesen „Dingen“ wie die Datei eines Beitrags oder ein Kommentar zu einem Fotos
• Felder: Metadaten zu Objekten wie der Name einer Person oder die Privatsphäre einer Gruppe

Jedes Element im Workplace-Graph wird durch eine eindeutige ID dargestellt. Gruppen, Mitglieder, Beiträge und sogar Kommentare verfügen über ihre eigenen IDs, anhand derer Informationen über sie aus der Graph API abgerufen werden können.

Verwalten deiner Community

Jede Workplace-Community existiert separat von anderen Communitys. Daher kannst du auf Inhalte deiner eigenen Community und von unternehmensübergreifenden Gruppen, zu denen Mitglieder deiner Community hinzugefügt wurden, nur über die Graph API zugreifen.

Für den Zugriff auf die Graph API wird deine Community wie eine Gruppe behandelt. Du kannst deine Community als eine übergeordnete Gruppe verstehen, zu der alle deine Gruppen als untergeordnete Gruppen hinzugefügt werden. Um Informationen zu deiner Community aus der Graph API abzurufen, benötigst du deine Community-ID, die programmgesteuert aus der Graph API abgerufen wird. Hierzu erfolgt eine HTTP GET-Abfrage an graph.facebook.com/community mit einem gültigen App-Zugriffsschlüssel.

Versionierung der Graph API

Die Graph API for Workplace baut auf der Plattform der Graph API auf. Das heißt, sie übernimmt dasselbe API-Versionierungsverhalten.

Neue Versionen der Graph API erscheinen ungefähr alle drei Monate und Änderungen an allen Workplace und Graph APIs werden im Graph API-Änderungsprotokoll veröffentlicht.

Wenn du einen API-Aufruf an die Graph API durchführst, kannst du im API-Pfad wie folgt die Version angeben:

      https://graph.facebook.com/v2.11/community/groups
    

Es gelten jedoch einige Einschränkungen für verfügbare Versionen:

• Sobald eine neue Version veröffentlicht wird, wird diese zur aktuellen API-Version. Nach der Veröffentlichung funktioniert diese Version garantiert für mindestens zwei Jahre.
• Wenn eine App erstellt wird, verwendet diese standardmäßig die zum Zeitpunkt der Erstellung aktuelle API-Verion, die dann für diese App zur mindestens angeforderten API-Version wird.
• Apps können bei API-Aufrufen jede API-Version frei wählen. Es können jedoch keine Aufrufe an veraltete Versionen durchgeführt werden oder an Versionen die älter sind als die mindestens angeforderte API-Version der App.
• API-Aufrufe, bei denen keine Version angegeben ist, verwenden standardmäßig die mindestens angeforderte API-Version der App.

Wenn eine neue benutzerdefinierte Integration erstellt wird, ist deren mindestens verfügbare API-Version die zum Zeitpunkt der Erstellung aktuelle API-Version. Diese mindestens erforderliche Version betrifft sowohl Aufrufe an die Graph API als auch Webhook-Abonnements.

Überprüfen der Graph API-Version

Wenn du dir nicht sicher bist, welche Version du verwendest, gibt es verschiedene Methoden, dies herauszufinden. Um zu ermitteln, welche Versionen der Graph API mit deiner App verwendet werden können, füge den Parameter debug zu deine API-Aufruf hinzu.

      https://graph.facebook.com/community?debug=all
    

Dadurch werden zusätzliche Debug-Informationen zurückgegeben, anhand derer du die Verwendete Version überprüfen kannst.

      {
         "name": "Example Community",
         "privacy": "CLOSED",
         "id": "855210357923606",
         "__debug__": {
            "messages": [
               {
                  "link": "https://developers.facebook.com/docs/apps/versions/",
                  "message": "No API version was specified. This request defaulted to version v2.8.",
                  "type": "warning"
               }
            ]
         }
      }
    

Falls du versuchst, eine Version zu verwenden, die älter ist als die mindestens angeforderte API-Version deiner App, wird dir dies in der debug-Nachricht mitgeteilt.

      https://graph.facebook.com/v2.6/community?debug=all
      
      {
         "name": "Example Community",
         "privacy": "CLOSED",
         "id": "855210357923606",
         "__debug__": {
            "messages": [
               {
                  "link": "https://developers.facebook.com/docs/apps/versions/",
                  "message": "The app tried to call version v2.6. This app can only call versions v2.8 and higher, so the request defaulted to version v2.8.",
                  "type": "warning"
               }
            ]
         }
      }
    

Überprüfen der Webhook-Version

Webhook-Abonnements verwenden die mindestens erforderliche API-Version, sofern das Abonnement über den Pop-up-Dialog in der benutzerdefinierten Integration erfolgt ist, oder die angegebene API-Verion, falls das Abonnement über den Abonnement-Endpunkt der Graph API /app/subscriptions abgeschlossen wurde.

Du kannst den Abonnement-Endpunkt verwenden um die angewendete Webhook-Version für jedes Webhook-Feld und -Thema zu prüfen. Dieser Endpunkt erfordert einen App-Zugriffsschlüssel.

      https://graph.facebook.com/v2.11/app/subscriptions
      
      {
        "data": [
          {
            "object": "group",
            "callback_url": "https://www.example.com/callback",
            "active": true,
            "fields": [
              {
                "name": "comments",
                "version": "v2.8"
              },
      ...
    

Zugriffsschlüssel verwenden

Einen App-Zugriffsschlüssel anfordern

Um Graph API-Aufrufe für deine Community durchzuführen, musst du eine App erstellen und einen Zugriffsschlüssel abrufen. Dies umfasst das Erstellen einer neuen App, der du die erforderlichen Berechtigungen für die Funktionen erteilst, die du schaffen möchtest.

Weitere Informationen über das Erstellen von Apps und das Berechtigungsmodell findest du im Berechtigungsleitfaden.