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 for Facebook. 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.

Workplace Graph API-Objekte

Folgende Nodes sind in der Workplace Graph API über eine benutzerdefinierte Integration oder einen Zugriffsschlüssel für eine Drittanbieter-App zugänglich.

Community

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

Gruppen

Eine Workplace-Gruppe.

Beiträge

Ein in einer Gruppe oder auf der Seite eines Mitglieds verfasster Beitrag.

Mitglieder

Ein Konto für eine*n bestimmte*n Workplace-Nutzer*in. Dieser Node wird auch verwendet, um Nachrichten anzuzeigen und zu bearbeiten, die von diesem*dieser Nutzer*in gesendet oder empfangen wurden.

Fähigkeiten

Eine zum Profil eines Mitglieds hinzugefügte Fähigkeit.

Event

Ein Event einer Workplace Community oder -Gruppe.

Kategorie

Eine Kategorie in der Wissensdatenbank, in der wichtige Unternehmensinhalte gespeichert werden.

Personen-Set

Eine Sammlung an Personen, die anhand von Kriterien oder Listen erstellt wurde.

Gemeldeter Inhalt

Inhalt in Workplace, der von einem*einer Administrator*in zur Überprüfung gemeldet wurde.

Schicht

Schichtplandaten für Stundenlohnempfänger*innen in Workplace.

Umfrage

Umfragen, die in Workplace erstellt wurden.

Datenexport

Datenexportaufträge für Massendatenexporte aus Workplace.

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*e Nutzer*in, ein Foto, ein Beitrag oder ein Kommentar
• Edges: Verbindungen zwischen diesen „Dingen“ wie die Datei eines Beitrags oder ein Kommentar zu einem Foto
• 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 for Facebook auf. Das heißt, sie übernimmt dasselbe API-Versionierungsverhalten wie Facebook.

Neue Versionen der Graph API erscheinen ungefähr alle drei Monate und Änderungen an allen Workplace und Facebook 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 personalisierte 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 deinem 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 personalisierten Integration erfolgt ist, oder die angegebene API-Version, 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 personalisierten Integration, der du die erforderlichen Berechtigungen für die gewünschten Funktionen erteilst.

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

Mitglieds-Zugriffsschlüssel abrufen

Während ein App-Zugriffsschlüssel es einer App ermöglicht, auf Objekte in der gesamten Community zuzugreifen und mit ihnen zu interagieren, ermöglicht ein Mitglieds-Zugriffsschlüssel es einem Dienst, Aufrufe im Namen eines bestimmten Kontos auszuführen.

Du kannst ein Mitglieds-Zugriffsschlüssel abrufen, indem du für ein bestimmtes Mitglied eine GET-Abfrage an den /member_id-Endpunkt durchführst. Verwende dabei einen Admin-Zugriffsschlüssel und frage das zusätzliche Feld impersonate_token ab.

Für diese Funktion muss die App, die den Aufruf durchführt, über die Nachahmungsberechtigung verfügen.