グラフAPI

概要

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

グラフAPIは、Facebook上の情報を表す「ソーシャルグラフ」という概念にちなんで名付けられました。グラフAPIは、ノード、エッジ、フィールドで構成されています。一般的に、ノードは特定のオブジェクトに関するデータを取得するために使用し、エッジは単一のオブジェクトに接続されたオブジェクトのコレクションを取得するために使用し、フィールドは単一のオブジェクトまたはコレクション内の各オブジェクトに関するデータを取得するために使用します。ドキュメントの中では、ノードとエッジの両方を「エンドポイント」と呼ぶことがあります。例えば、「UserエンドポイントにGETリクエストを送信する」といった具合です。

HTTP

すべてのデータ転送はHTTP/1.1に準拠しており、すべてのエンドポイントはHTTPSを必要とします。グラフAPIはHTTPベースなので、cURLやurllibといったHTTPライブラリを持つすべての言語で機能します。つまり、グラフAPIはブラウザー内で直接利用できます。たとえば、ブラウザー内で次のURLをリクエストするとします:

https://graph.facebook.com/facebook/picture?redirect=false

これは、次のcURLリクエストを実行するのと同じです。

curl -i -X GET "https://graph.facebook.com/facebook/picture?redirect=false"

facebook.comのincludeSubdomains HSTSディレクティブも有効化されていますが、グラフAPIの呼び出しに悪影響が出ないようにする必要があります。

ホストURL

ほとんどすべてのリクエストは、graph.facebook.comホストURLに渡されます。ただし、動画をアップロードする場合に限り、graph-video.facebook.comが使用されます。

アクセストークン

アクセストークンは、アプリがグラフAPIにアクセスする際に必要とするものです。ほとんどすべてのグラフAPIエンドポイントには、何らかのアクセストークンが必要であるため、エンドポイントにアクセスするたびに、リクエストにアクセストークンが必要になる可能性があります。アクセストークンは通常、次のような2つの働きをします。

  • ユーザーのパスワードがなくても、アプリがユーザーの情報にアクセスできるようにする。例えば、ある機能を実行するためにユーザーのメールが必要になったとします。アプリがFacebookからメールアドレスを取得することにユーザーが同意している場合、ユーザーはアプリがメールアドレスを取得するためにFacebookのパスワードを入力する必要がありません。
  • アプリ、アプリを使用しているユーザー、ユーザーが、アプリにアクセスを許可したデータの種類を特定できるようにする。

詳しくは、アクセストークンのドキュメントをご覧ください。

ノード

ノードとは、一意のIDを持つ個別のオブジェクトです。例えば、ユーザーノードオブジェクトは多数存在しますが、それぞれにFacebookの利用者を表す一意のIDが付いています。ページ、グループ、投稿、写真、コメントは、Facebookソーシャルグラフのノードの一部です。

次のcURLの例は、ユーザーノードへの呼び出しを表しています。

curl -i -X GET \
  "https://graph.facebook.com/USER-ID?access_token=ACCESS-TOKEN"

このリクエストは、デフォルトでは以下のデータをJSON形式で返します。

{
  "name": "Your Name",
  "id": "YOUR-USER-ID"
}

ノードのメタデータ

ユーザー、ページ、写真などのノードオブジェクトの、フィールド名、説明、データタイプを含むすべてのフィールドのリストを取得できます。オブジェクトIDに対してGETリクエストを送信し、metadata=1パラメーターを指定します。

curl -i -X GET \
  "https://graph.facebook.com/USER-ID?
    metadata=1&access_token=ACCESS-TOKEN"

返されるJSONには、特定のノードでサポートされているすべてのフィールドのリストを示すmetadataプロパティが含まれます。

{
  "name": "Jane Smith",
  "metadata": {
    "fields": [
      {
        "name": "id",
        "description": "The app user's App-Scoped User ID. This ID is unique to the app and cannot be used by other apps.",
        "type": "numeric string"
      },
      {
        "name": "age_range",
        "description": "The age segment for this person expressed as a minimum and maximum age. For example, more than 18, less than 21.",
        "type": "agerange"
      },
      {
        "name": "birthday",
        "description": "The person's birthday.  This is a fixed format string, like `MM/DD/YYYY`.  However, people can control who can see the year they were born separately from the month and day so this string can be only the year (YYYY) or the month + day (MM/DD)",
        "type": "string"
      },
...

/me

/meノードは、API呼び出しにアクセストークンが使用されている人またはページのオブジェクトIDに変換される、特別なエンドポイントです。ユーザーアクセストークンを持っていれば、次のコードでユーザーの名前とIDを取得することができます。

curl -i -X GET \
  "https://graph.facebook.com/me?access_token=ACCESS-TOKEN"

エッジ

エッジとは、2つのノード間のつながりのことです。例えば、ユーザーノードには写真が、写真ノードにはコメントがそれぞれつながっています。次のcURLの例は、ある人物がFacebookに公開した写真のリストを返します。

curl -i -X GET \
  "https://graph.facebook.com/USER-ID/photos?access_token=ACCESS-TOKEN"

返される各IDは、写真ノードとその写真がいつFacebookにアップロードされたかを表しています。

    {
  "data": [
    {
      "created_time": "2017-06-06T18:04:10+0000",
      "id": "1353272134728652"
    },
    {
      "created_time": "2017-06-06T18:01:13+0000",
      "id": "1353269908062208"
    }
  ],
}

フィールド

フィールドはノードプロパティです。ノードやエッジにクエリを実行すると、上述の例のように、デフォルトでフィールドのセットが返されます。ただし、fieldsパラメーターを使用して各フィールドをリスティングすれば、どのフィールドを返すかを指定することもできます。これによりデフォルトが無効化され、返されるのは指定したフィールドとオブジェクトのIDのみとなります(IDは常に返されます)。

以下のcURLリクエストには、fieldsパラメーターとユーザーの名前、メール、プロフィール写真が含まれています。

curl -i -X GET \
  "https://graph.facebook.com/USER-ID?fields=id,name,email,picture&access_token=ACCESS-TOKEN"

返されるデータ

{
  "id": "USER-ID",
  "name": "EXAMPLE NAME",
  "email": "EXAMPLE@EMAIL.COM",
  "picture": {
    "data": {
      "height": 50,
      "is_silhouette": false,
      "url": "URL-FOR-USER-PROFILE-PICTURE",
      "width": 50
    }
  }
}

複合パラメーター

ほとんどのパラメータータイプはbool、string、intのような単純なプリミティブですが、リクエストで指定できるlistタイプとobjectタイプもあります。

listタイプはJSON構文で指定します。例: ["firstitem", "seconditem", "thirditem"]

objectタイプもJSON構文で指定します。例: {"firstkey": "firstvalue", "secondKey": 123}

公開、更新、削除

ユーザーのFacebookに公開する方法についてはFacebook共有ガイドを、ページのFacebookフィードに公開する方法についてはページAPIドキュメントをご覧ください。

ノードによっては、POST操作でフィールドを更新できます。例えば、次のようにしてemailフィールドを更新できます。

curl -i -X POST \
  "https://graph.facebook.com/USER-ID?email=YOURNEW@EMAILADDRESS.COM&access_token=ACCESS-TOKEN"

リードアフターライト

作成と更新のエンドポイントでは、グラフAPIが公開または更新に成功したオブジェクトを即座に読み取り、対応する読み取りエンドポイントでサポートしているフィールドを返します。

デフォルトでは、作成または更新されたオブジェクトのIDが返されます。応答にさらに多くの情報を含めるには、リクエストにfieldsパラメーターを含め、返したいフィールドをリストアップします。例えば、ページのフィードに「Hello」というメッセージを公開するには、次のリクエストを送信します。

curl -i - X POST "https://graph.facebook.com/PAGE-ID/feed?message=Hello&
  fields=created_time,from,id,message&access_token=ACCESS-TOKEN"
上記のコード例は、読みやすいようにフォーマットされています。

次のように、指定したフィールドがJSON形式で返されます。

{
  "created_time": "2017-04-06T22:04:21+0000",
  "from": {
    "name": "My Facebook Page",
    "id": "PAGE-ID"
  },
  "id": "POST_ID",
  "message": "Hello",
}

各エンドポイントのリファレンスドキュメントを参照し、リードアフターライトをサポートしているかどうか、どのフィールドを利用できるかをご確認ください。

エラー

何らかの理由で読み取りに失敗した場合(存在しないフィールドをリクエストした場合など)、グラフAPIは標準的なエラー応答を返します。詳しくは、エラーの処理ガイドをご覧ください。

投稿ノードや写真ノードなどのノードを削除するには、通常、オブジェクトIDに対してDELETE操作を行います。

curl -i -X DELETE \
  "https://graph.facebook.com/PHOTO-ID?access_token=ACCESSS-TOKEN"

通常、削除できるのは自分が作成したノードのみですが、削除操作に関する要件については、各ノードのリファレンスガイドをご覧ください。

Webhooks

Webhooksをサブスクリプション登録することで、ノードの変更やノードとのやり取りに関する通知を受け取ることができます。Webhooksをご覧ください。

バージョン

グラフAPIには、四半期ごとにリリースされる複数のバージョンがあります。呼び出しの際には、リクエストパスの先頭に「v」とバージョン番号を追加することで、バージョンを指定することができます。例えば、バージョン4.0への呼び出しは次のようになります。

curl -i -X GET \
  "https://graph.facebook.com/v4.0/USER-ID/photos
    ?access_token=ACCESS-TOKEN"

バージョン番号を含めないと、利用できる最も古いバージョンがデフォルトとして使用されるため、リクエストにはバージョン番号を含めることをおすすめします。

バージョンについての詳細は、「バージョン管理ガイド」をご覧ください。また、「グラフAPI更新履歴」では、利用可能なすべてのバージョンが紹介されています。

Facebook API、SDK、プラットフォーム

FacebookのさまざまなAPI、SDK、プラットフォームを使用することで、複数のプラットフォームをまたいでインターフェイスをつなぎ、開発を進めることができます。

次のステップ

グラフAPIの利用を始める – グラフエクスプローラーツールを使ってFacebookのソーシャルグラフを探索し、リクエストをいくつか実行してデータを取得してみましょう。