Référence concernant l’API Graph

Présentation

L’API Graph pour Workplace permet d’insérer et de récupérer des données dans Workplace de manière automatisée. Il s’agit d’une API HTTP de bas niveau qui vous permet d’interroger des données relatives aux objets dans un graphe Workplace.

Le nom de l’API Graph est dérivé de l’idée d’un modèle de données dans lequel les objets sont représentés par des nœuds associés à des arêtes dans un graphique. Au niveau de l’API, c’est ainsi que les apps accèdent aux informations sur Workplace. L’API Graph pour Workplace reprend un sous-ensemble des fonctionnalités de l’API Graph pour Facebook. Ces fonctionnalités sont limitées aux interactions avec une communauté Workplace et peuvent se comporter différemment selon les situations, afin d’améliorer les performances ou la convivialité.

Objets de l’API Graph pour Workplace

L’accès aux nœuds suivants est possible via l’API Graph pour Workplace à l’aide d’un token d’accès d’une intégration personnalisée ou d’une app tierce.

Community

Une communauté Workplace. Il s’agit du groupe racine de tous vos appels de l’API Graph pour Workplace.

Groups

Un groupe Workplace.

Posts

Une publication dans un groupe ou sur le profil d’un membre.

Members

Un compte d’un utilisateur spécifique de Workplace. Ce nœud sert également à afficher et à modifier les messages envoyés et reçus par cet utilisateur.

Skills

Une compétence ajoutée au profil d’un membre.

Event

Un évènement d’un groupe ou d’une communauté Workplace.

Category

Catégorie de la bibliothèque de connaissances permettant de stocker les contenus importants de l’entreprise.

Ensemble de personnes

Collection de personnes définie à l’aide de critères ou de listes.

Contenu signalé

Contenu sur Workplace qui a été signalé pour examen par un ou une admin.

Remplacements

Données relatives aux horaires de remplacement pour les travailleurs et travailleuses rémunéré·es à l’heure sur Workplace.

Sondage

Sondages créés sur Workplace.

Exportation de données

Tâches d’exportation de données pour l’exportation de données groupées depuis Workplace.

Pour voir des exemples d’appels combinés de l’API Graph afin de résoudre des problèmes spécifiques, consultez la liste des échantillons d’applications.

Utilisation de l’API Graph

Objets de l’API Graph

L’API Graph est une représentation graphique des informations de Workplace, qui se compose des éléments suivants :

• Nœuds : objets tels qu’un utilisateur, une photo, une publication ou un commentaire
• Arêtes : connexions entre ces objets, comme entre un fichier et une publication ou un commentaire et une photo
• Champs : métadonnées relatives aux objets, telles que le nom d’une personne ou la confidentialité d’un groupe

Chaque élément du graphe de Workplace est représenté par un ID unique. Les groupes, les membres, les publications et même les commentaires ont leur propre identifiant, ce qui permet de collecter des informations à leur sujet avec l’API Graph.

Gestion de la communauté

Chaque communauté de Workplace évolue indépendamment des autres communautés. Ainsi, l’API Graph vous permet d’accéder uniquement au contenu de votre communauté et des groupes inter-entreprises auxquels les membres de votre communauté ont été ajoutés.

En termes d’accès à l’API Graph, votre communauté est traitée comme un groupe. Votre communauté fonctionne comme un groupe racine auquel vous ajoutez tous vos groupes, qui sont alors ses enfants. Pour collecter des informations sur votre communauté avec l’API Graph, vous devez vous munir de l’ID de votre communauté, que vous pouvez obtenir en envoyant une requête HTTP GET à graph.facebook.com/community avec un token d’accès d’app valide.

Gestion des versions de l’API Graph

L’API Graph pour Workplace est issue de l’API Graph pour la plate-forme Facebook. Elle hérite donc de la même gestion des versions que Facebook.

Les versions de l’API Graph sont publiées environ tous les trois mois, et les changements entre toutes les API pour Workplace et Facebook sont publiés dans le changelog de l’API Graph.

Lorsque vous envoyez un appel d’API à l’API Graph, vous pouvez spécifier une version dans le chemin de l’API, comme ceci :

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

Toutefois, des restrictions s’appliquent pour les versions disponibles :

• Quand une nouvelle version est publiée, elle devient la version actuelle de l’API et son fonctionnement est garanti pendant deux ans après sa sortie.
• Quand vous créez une app, la version par défaut de l’API est la version actuelle au moment de sa création. Celle-ci devient la version minimale de l’API pour cette app.
• Quand les applications envoient des appels d’API, elles sont libres de préciser n’importe quelle version de l’API. Toutefois, la version indiquée ne doit pas être obsolète ou inférieure à la version minimale de l’API.
• En l’absence de version dans les appels d’API, la version utilisée est la version minimale de l’API pour cette application.

Quand une nouvelle intégration personnalisée est créée, la version minimale de l’API disponible pour cette intégration est la version actuelle de l’API au moment de sa création. La version minimale affecte autant les appels de l’API Graph que les abonnements webhook.

Vérifier la version de l’API Graph

Si vous n’êtes pas sûr de la version que vous utilisez, plusieurs méthodes vous permettent de la vérifier. Vous pouvez ajouter le paramètre debug à votre appel d’API pour connaître la version de l’API Graph que vous pouvez utiliser avec votre app.

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

Vous recevrez des informations de débogage supplémentaires vous confirmant la version utilisée.

      {
         "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"
               }
            ]
         }
      }
    

Si vous essayez d’utiliser une version inférieure à la version minimale de l’API pour votre app, vous en serez averti dans le message debug.

      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"
               }
            ]
         }
      }
    

Vérifier la version des webhooks

Les abonnements webhook utilisent la version minimale de l’API si l’abonnement a été souscrit via la boîte de dialogue contextuelle Intégration personnalisée, ou la version de l’API spécifiée si l’abonnement a été souscrit via le point de terminaison /app/subscriptions de l’API Graph.

Vous pouvez utiliser ce point de terminaison des abonnements pour vérifier la version appliquée pour chaque champ et sujet des webhooks. Ce point de terminaison nécessite un token d’accès d’app.

      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"
              },
      ...
    

Utilisation des tokens d’accès

Obtenir un token d’accès d’app

Pour envoyer des appels d’API à votre communauté, vous devez créer une app et obtenir un token d’accès. Pour ce faire, vous devez créer une nouvelle intégration personnalisée afin d’accorder les autorisations nécessaires à la fonctionnalité que vous souhaitez créer.

Pour en savoir plus sur la création d’app et le modèle d’autorisation, consultez le guide relatif aux autorisations.

Obtenir un token d’accès de membre

Alors qu’un token d’accès d’app autorise une app à accéder aux objets d’une communauté, ainsi qu’à interagir avec ces derniers, un token d’accès de membre autorise un service à envoyer des appels pour le compte d’un utilisateur spécifique.

Pour obtenir un token d’accès de membre, envoyez une requête GET au point de terminaison /member_id pour un membre donné, en utilisant un token d’accès d’administrateur et en ajoutant le champ impersonate_token dans la requête.

L’app à l’origine de l’appel doit obtenir l’autorisation d’usurper l’identité du compte pour utiliser cette fonctionnalité.