Référence concernant l’API Graph

Vue d’ensemble

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 applications accèdent aux informations sur Workplace. L’API Graph pour Workplace reprend un sous-ensemble des fonctionnalités de l’API Graph. 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é.

Plus d’informations sur l’utilisation de l’API Graph pour Workplace sont disponibles ci-dessous :

Création d’applications Création de bots Autorisations Exemples

Objets de l’API Graph pour Workplace

Les nœuds suivants sont accessibles via l'API Graph pour Workplace. Un token d’accès pour les intégrations personnalisées doit être utilisé pour accéder à tous les nœuds.

Communauté

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

Groupes

Un groupe Workplace.

Publications

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

Membres

Un compte d’un·e utilisateur·ice spécifique de 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 exemples 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. Elle hérite donc de la même gestion des versions.

Les versions de l’API Graph sont publiées environ tous les trois mois, et les changements entre toutes les API pour Workplace et Graph 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 apps 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 absence de version dans les appels d’API, la version utilisée est la version minimale de l’API pour cette app.

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.

Gestion des versions de la plate-forme Changelog de l’API Graph

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

En fonction de la procédure suivie pour activer l’abonnement webhook, différents champs d’un même objet webhook peuvent renvoyer des charges utiles avec des numéros de version différents.

Si le format de la charge utile ne correspond pas au format attendu, vérifiez à nouveau le numéro de version et renouvelez l’abonnement avec une version plus récente, si nécessaire.

Utilisation des tokens d’accès

Obtenir un token d’accès d’app

Pour envoyer des appels d’API Graph à votre communauté, vous devez créer une application et obtenir un token d’accès. Pour ce faire, vous devez créer une application, puis lui accorder les autorisations nécessaires à la fonctionnalité que vous souhaitez créer.

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