グラフAPIのリファレンス

概要

WorkplaceのグラフAPIにより、プログラムを使用してWorkplaceのデータを出し入れできます。グラフAPIは低レベルのHTTPベースのAPIで、Workplaceグラフのオブジェクトに関するデータをクエリできます。

グラフAPIは、オブジェクトをノードで表現し、エッジに沿って結合するグラフデータモデルの概念にちなんで名付けられました。APIレベルでは、アプリはこの方法によってWorkplaceの情報にアクセスします。Workplace用のグラフAPIでは、Facebook用グラフAPIの機能のサブセットを利用できます。この機能は、Workplaceコミュニティとのやり取りに限定されており、パフォーマンスやユーザビリティを向上させるために、変更されている場合もあります。

WorkplaceグラフAPIオブジェクト

次のノードは、カスタム統合またはサードパーティアプリのアクセストークンを使用して、WorkplaceグラフAPIからアクセスできます。

コミュニティ

Workplaceコミュニティ。WorkplaceグラフAPI呼び出しのルートグループ。

グループ

Workplaceグループ。

投稿

グループやメンバーのプロフィールでの投稿。

メンバー

特定のWorkplaceユーザーのアカウント。このノードは、このユーザーが送受信したメッセージを表示したり、編集したりするためにも使用されます。

スキル

メンバーのプロフィールに追加されたスキル。

イベント

Workplaceコミュニティやグループのイベント。

カテゴリ

会社の重要なコンテンツを保存するための情報ライブラリのカテゴリ。

ユーザーセット

基準またはリストを使って定義された、ユーザーのコレクション。

報告されたコンテンツ

管理者によって審査に報告されたWorkplaceのコンテンツ。

シフト

Workplace上の時給制社員のシフトスケジュールデータ。

アンケート

Workplaceで作成されたアンケート。

データエクスポート

Workplaceからのデータ一括エクスポートのデータエクスポートジョブ。

特定の問題を解決するためのグラフAPI呼び出しの組み合わせ例については、サンプルアプリのリストをご覧ください。

グラフAPIの利用

グラフAPIオブジェクト

グラフAPIは、Workplace上の情報を表現したもので、次の項目で構成されます。

ノード - ユーザー、写真、投稿、コメントなどのオブジェクト
エッジ - 投稿のファイルや写真のコメントなど、これらの「もの」のつながり
フィールド - 人の名前やグループのプライバシーなど、オブジェクトに関するメタデータ

Workplaceグラフの各項目は、固有のIDで表されます。グループ、メンバー、投稿、さらにはコメントにもそれぞれIDがあり、それらを使用してグラフAPIから情報を取得できます。

コミュニティの管理

各Workplaceコミュニティは他のコミュニティから独立しているため、グラフAPIを使用してアクセスできるのは、自分のコミュニティ内のコンテンツと、自分のコミュニティのメンバーが追加された会社間グループ内のコンテンツのみです。

グラフAPIによるアクセスにおいては、コミュニティはグループとして扱われます。コミュニティはルートグループと考えることができ、その下にすべてのグループが子として追加されます。グラフAPIでコミュニティに関する情報を取得するには、コミュニティIDが必要になります。このIDは、有効なアプリアクセストークンを使ってgraph.facebook.com/communityに対するHTTP GETリクエストをすることによって、グラフAPIからプログラムにより取得されます。

グラフAPIのバージョン管理

Workplace用のグラフAPIは、Facebookのプラットフォーム用のグラフAPIの上に構築されます。これは、Facebookで使われているものと同じAPIのバージョン管理動作を継承していることを意味します。

グラフAPIのバージョンはだいたい3か月ごとにリリースされ、WorkplaceとFacebook APIの変更点はすべてグラフAPI更新履歴で公開されます。

グラフAPIに対するAPI呼び出しを行う際には、次のようにAPIパスでバージョンを指定できます。

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

ただし、利用可能なバージョンにはいくつか制限があります。

新しいバージョンがリリースされると、そのバージョンが現在のAPIバージョンとなり、リリース後2年間の動作が保証されます。
アプリが作成される場合、作成時の現在のAPIバージョンがデフォルトとなり、そのバージョンがそのアプリで利用可能な最小APIバージョンとなります。
アプリではAPI呼び出しの際に任意のAPIバージョンを自由に指定できますが、廃止されたAPIバージョンや、アプリの最小APIバージョン未満のバージョンへの呼び出しを行うことはできません。
バージョンが指定されていないAPI呼び出しでは、デフォルトでそのアプリの最小APIバージョンが呼び出されます。

新しいカスタム統合を作成すると、その利用可能な最小APIバージョンは、作成時の現在のAPIバージョンになります。この最小バージョンは、グラフAPI呼び出しとWebhookサブスクリプションの両方に影響します。

プラットフォームのバージョン管理グラフAPI更新履歴

グラフAPIのバージョンの確認

どのバージョンを使っているのかわからない場合は、いくつかの方法で確認できます。アプリで使用できるグラフAPIのバージョンを確認するには、API呼び出しにdebugパラメーターを追加します。

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

そうすると、使用されているバージョンを確認するための追加のデバッグ情報が返されます。

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

アプリの最小APIバージョン未満のバージョンを使用しようとすると、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"
               }
            ]
         }
      }

Webhookバージョンの確認

Webhookサブスクリプションでは、[カスタム統合]ポップアップダイアログでサブスクリプションを作成した場合は最小APIバージョンが使用され、サブスクリプションのグラフAPIエンドポイント/app/subscriptionsでサブスクリプションを作成した場合には指定されたAPIバージョンが使用されます。

サブスクリプションのエンドポイントを使用すると、各Webhookフィールドとトピックに適用されたWebhookのバージョンを確認することができます。このエンドポイントにはアプリアクセストークンが必要です。

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

Webhookサブスクリプションを有効化した方法に応じて、1つのWebhookオブジェクト内のさまざまなフィールドが異なるバージョン番号を使用したペイロードを返す場合があります。

ペイロードが期待した形式ではない場合は、バージョン番号を再確認し、必要に応じて新しいバージョンを使用して再度サブスクリプション登録します。

アクセストークンの利用

アプリアクセストークンを取得する

コミュニティのグラフAPIを呼び出すには、アプリを作成してアクセストークンを取得する必要があります。その場合、新しいカスタム統合を作成し、作成する機能に必要なアクセス許可を付与する必要があります。

アプリの作成とアクセス許可モデルについて、詳しくはアクセス許可に関するガイドをご覧ください。

メンバーアクセストークンを取得する

アプリアクセストークンを使用すると、アプリがコミュニティ全体のオブジェクトにアクセスしてやり取りできるようになります。一方、メンバーアクセストークンを使用すると、特定のアカウントに代わってサービスから呼び出しを実行できるようになります。

メンバーアクセストークンを取得するには、特定のメンバーの/member_idエンドポイントにGETリクエストを行います。その際、管理者アクセストークンを使用して、追加フィールドimpersonate_tokenをリクエストします。

この機能を使用するには、呼び出しをするアプリのなりすましのアクセス許可が必要です。

なりすましは廃止されたアクセス許可です。このアクセス許可を使用して新しい機能を作成しないでください。このアクセス許可は、カスタム統合に追加できなくなりました。

なりすましトークンは、取得済みのアカウントに対してのみ取得できます。