リファレンス

グラフAPIのリファレンス

概要

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

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

Workplace用グラフAPIの使い方について詳しくは、下記をご覧ください。

アプリの作成ボットの構築アクセス許可サンプル

WorkplaceグラフAPIオブジェクト

WorkplaceグラフAPIオブジェクトで、以下のノードにアクセスできます。どのノードにアクセスする場合も、カスタム統合アクセストークンを使う必要があります。

コミュニティ

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

グループ

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は、グラフAPIの上に構築されます。これは、同じAPIのバージョン管理動作を継承していることを意味します。

グラフAPIのバージョンはだいたい3か月ごとにリリースされ、Workplaceとグラフ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を呼び出すには、アプリを作成してアクセストークンを取得する必要があります。その場合、新しいアプリを作成し、作成する機能に必要なアクセス許可を付与する必要があります。

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