Graph APIの概要

グラフAPIは、Facebookプラットフォームにデータを取り込んだり、Facebookプラットフォームからデータを取り出したりするための主要な手段です。プログラムを使用したデータのクエリ、新しい記事の投稿、広告の管理、写真のアップロード、アプリで行うその他のさまざまなタスクに利用できるローレベルのHTTPベースのAPIです。

基本情報

Graph APIは、Facebookを構成する情報表現である「ソーシャルグラフ」の概念にちなんで名前が付けられました。

  • ノード - 基本的には、利用者、写真、Facebookページ、コメントなどの「もの」を指します。
  • エッジ - Facebookページの写真や写真のコメントなど、これらの「もの」のつながりを指します。
  • フィールド - 利用者の誕生日やFacebookページ名など、これらの「もの」に関する情報を指します。

Graph APIはHTTPベースのため、cURL、urllibのようなHTTPライブラリのあるすべての言語で機能します。Graph APIを使って実行できる内容については、以下のセクションでもう少し詳しく説明しますが、HTTPベースということはGraph APIをブラウザで直接、利用することも可能になります。Graph APIリクエストは、以下と同じになります。

GET graph.facebook.com
  /facebook/picture?
    redirect=false

ほとんどのGraph APIリクエストでは、アプリでFacebookログインを実装して生成できるアクセストークンを使う必要があります。

この概要では、Graph APIでのデータの読み取り方法と、ソーシャルグラフへのデータの公開方法について紹介します。

Graph APIの構造

詳しくは「Graph APIの使用」ガイドで説明していますが、一般的には、ノードやこれらのノードのエッジにHTTP GETリクエストを行ってAPIを読み込めます。

ほぼすべてのリクエストは、graph.facebook.comでGraph APIに渡されます。ただし、動画をアップロードする場合のみgraph-video.facebook.comを使います。

オブジェクトID

各ノードには、一意のIDが付いています。これを使って、Graph APIからノードにアクセスします。ノードIDとオブジェクトIDの構造やフォーマットは、時間とともに変更される可能性が非常に高く、アプリでは現在の構造に基づいて想定しない方がよいため、具体的な説明は省きます。

IDを使ってノードのリクエストを行う場合、以下のようになります。

GET graph.facebook.com
  /{node-id}

エッジの場合は、以下のようになります。

GET graph.facebook.com
  /{node-id}/{edge-name}

通常、APIに公開するには、パラメータを使ってノードにHTTP POSTリクエストを行います。

POST graph.facebook.com
  /{node-id}

エッジの場合は、以下のようになります。

POST graph.facebook.com
  /{node-id}/{edge-name}

APIを使って削除するには、同じエンドポイントに対してHTTP DELETEリクエストを使います(POSTリクエストで更新)。

APIのバージョン

Graph APIには、いつでも利用できる複数のバージョンがあります。各バージョンには、コアフィールドとエッジ操作のセットが含まれています。リリースから少なくとも2年間はこれらのコアAPIを利用でき、そのバージョンでは変更が行われないことが保証されています。現在利用できるバージョンについては、プラットフォームの更新履歴で確認できます。

エッジ内での公開やノード内の特定フィールドでの公開のような特定の操作は、エッジ全体や、コアになっているノードがない場合でもコアである可能性があります。「Graph APIリファレンス」ドキュメントでは、この 記号を使って、これらのコアAPIに注釈を付けています。

これらのコアAPI以外は、すべて拡張APIと呼ばれます。これらのAPIは、バージョン指定されたパスからアクセスできますが、Facebookのプラットフォームロードマップで発表される90日間の移行期間の対象となっているため、いつでも修正または削除される可能性があります。または、次回の利用可能なAPIバージョンに含まれる可能性があります。

バージョン管理の目的について詳しくはFacebookのガイドに記載されていますが、ここでは特定バージョンのGraph APIに呼び出しを実行する方法について説明します。

方法はとても簡単で、リクエストパスの先頭に、バージョン識別子を付加するだけです。たとえば、v2.2への呼び出しは次のようになります。

GET graph.facebook.com
  /v2.2/me

これは、次の一般的なフォームで、すべてのバージョンに対して機能します。

GET graph.facebook.com
  /vX.Y/{request-path}

ここでは、X.Yが必要なバージョンです。更新履歴では利用できるバージョンの全リストが公開されています。すべての「Graph APIリファレンス」ドキュメントではバージョンごとの情報が提供されているため、そこで正しいバージョンをご覧ください。バージョンによっては、ノードやエッジが削除されていたり、追加されていたりするものもあります。

次に、APIリクエストが簡単に実行できることをご覧いただくために、実際に試してみましょう。

Graph APIエクスプローラの読み込み

Graph APIについて理解する最も簡単な方法は、Graph APIエクスプローラと一緒に使うことです。Graph APIエクスプローラはローレベルのツールで、データのクエリ、追加、削除に使用できます。アプリをFacebookと統合する際に簡単に利用できる、非常に便利なリソースです。では、Graph APIエクスプローラに移動します。

Graph APIエクスプローラ

基本的なユーザーアクセストークンの生成

独自のアプリを作成する際、アクセストークンの概要と、Facebookログインを使ってそれらを作成する方法について知っておく必要がありますが、ここではGraph APIエクスプローラから簡単に紹介します。

  1. Graph APIエクスプローラの右上にある[Get Token]ボタンをクリックします。
  2. [Get User Access Token]オプションを選択します。
  3. 次のダイアログではすべてのボックスのチェックを外して、[Get Access Token]ボタンのみをクリックします。
  4. Facebookログインダイアログが表示されたら、[OK]をクリックして進みます。

最初のリクエストの実行

これで、最初のGraph APIリクエストを実行する準備が整いました。'read'リクエストから試してみましょう。[取得]ドロップダウンボタンの横にあるテキストフィールド(パスフィールドと呼ばれる)で、既存のテキストを削除して「me」と入力します。

[送信]ボタンを押します。処理に数秒かかりますが、完了すると、応答パネルに多くの情報が表示されます。ここに表示される内容は、プロフィールのプライバシー設定によって決まりますが、少なくともいくつかの基本フィールドが含まれています。

さきほどGraph APIエクスプローラで実行した内容は、以下のGraph APIの'read'リクエストと同じものです。

GET graph.facebook.com
  /me

/meは特別なエンドポイントで、アクセストークンでリクエストの呼び出しに使われている利用者のユーザーIDに変わります。

これで、最初のGraph APIリクエストを実行できました。

公開許可の取得

次に、Graph APIを使って、Facebookに何かを公開してみましょう。アプリでこれを行うのは、独自のカスタム投稿ツールを作成している場合で、なおかつwebiOSAndroidでシェアダイアログを使っていない場合のみです。Facebookシェアダイアログでは、Facebookログインを実装したり、利用者がシェアするための独自のインターフェイスを作成したりする必要はありません。

Graph APIを使って公開を試すには、もう一度[アクセストークンを取得]ボタンをクリックし、今回は[publish_actions]アクセス許可を選択します。

その後、青色の[アクセストークンを取得]ボタンをクリックすると、ログインダイアログが再表示されます。ここでは、Graph APIエクスプローラが代理で投稿するためのアクセス許可を求めるメッセージが表示されます。ここで対象者を[自分のみ]に変更して、自分だけに投稿が表示されるようにすることもできますが、このダイアログの内容を受け入れて次の手順に進みます。

投稿の公開

publish_actionsアクセス許可を求めた場合は、そこにある[取得]ボタンをクリックして、表示されるドロップダウンセレクタから[投稿]を選択します。パスフィールドに「me/feed」を入力した後、[フィールドを追加]をクリックします。

表示される新しいフィールドで、"name"に「message」、"value"に「Hello, World」と入力します。次のようになります。

青色の[送信]ボタンをクリックします。数秒後、以下のような応答パネルが表示されます。

{
  "id": "{new-post-id}"
}

これで、Graph APIから最初の投稿が公開されました。 プロフィールに移動すると、そこで投稿が表示されていることを確認できます。

さきほどGraph APIエクスプローラで実行した内容は、以下のGraph APIの'publish'リクエストと同じものです。

POST graph.facebook.com
  /me/feed?
    message="Hello, World."&
    access_token={your-access-token}

次のステップ

ここでは基本情報について説明しました。引き続きGraph APIの使用について詳しくご覧ください。 まずFacebookログインについてお読みください。特に、さらに複雑なGraph APIリクエストを実行する際に必要となる、アクセストークンの作成方法をご覧ください。