概要

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

基本情報

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

  • ノード - 基本的には、ユーザー、写真、Facebookページ、コメントなどといった個々のオブジェクトを指します。
  • エッジ - 1つのページ上の複数の写真または1つの写真上の複数のコメントといった、単一のオブジェクトとオブジェクトのコレクションとの間の接続を指します。
  • フィールド - ユーザーの誕生日やページの名前といった、オブジェクトに関するデータを指します。

通常、ノードは特定のオブジェクトに関するデータを取得するため、エッジは単一のオブジェクト上にあるオブジェクトのコレクションを取得するため、フィールドは単一のオブジェクトまたはコレクション内の各オブジェクトに関するデータを取得するために使用されます。

HTTP

Graph 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&access_token={valid-access-token-goes-here}"

アクセストークン

上記のcURLリクエストにはaccess_tokenパラメーターとプレースホルダー値があります。ほとんどのグラフAPIリクエストには、アクセストークンが必要です。いずれは、Facebookが提供しているアクセストークンに関するドキュメントを読んで、アクセストークンの仕組みを理解する必要がありますが、今のところは次のことを知っておけば十分です。

  • ほぼすべてのグラフAPIリクエストには、何らかの種類のアクセストークンが必要である
  • アクセストークンを取得する一番簡単な方法は、Facebookログインを実行することである

グラフAPIドキュメント全体に記載されている擬似コードリクエスト/応答例ではアクセストークンについてはっきり触れていませんが、リクエストには応答を取得するためのアクセストークンが含まれていると想定してください。

構造

構造についての詳細は「グラフAPIの利用ガイド」に記載されていますが、大まかに言うと次のとおりです。

  • ノードを使用して、個々のオブジェクトについてのデータを取得する
  • エッジを使用して、ノードに接続されたオブジェクトのコレクションを取得したり、オブジェクトをこれらのコレクションに向けて公開したりする
  • フィールドを使用して、どのデータを応答に含めるか指定する

ホストURL

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

オブジェクトID

ノードは個別のオブジェクトであり、それぞれ固有のIDを持つため、ノードに関する情報を取得するには、このIDを直接クエリします。たとえばFacebook公式ページのIDは、20531316728です。このIDを使用して直接クエリします。

GET graph.facebook.com
  /20531316728

ノードに関する特定のデータ(フィールドと呼ばれる)を取得するには、fieldsパラメーターを含めて、応答で返されるフィールドを指定します。ページノードリファレンスを見ると、ページオブジェクトを読み込んだ時に取得できるフィールドの1つに、coverフィールドがあることがわかります。これはページのカバー写真です。クエリは、次のようになります。

GET graph.facebook.com
  /20531316728?fields=cover

ほとんどのノードはエッジを持ち、そのノードに接続されたオブジェクトのコレクションを返します。エッジをクエリする際には、ノードIDとエッジ名のどちらも使用できます。 ページノードリファレンスに記載されたエッジの1つにphotosエッジがあります。これは、ページが所有するすべての写真オブジェクトを返します。そのため、Facebookページによって所有される写真のすべてを取得するには、ノードのphotosエッジをクエリします。

GET graph.facebook.com
  /20531316728/photos

一部のノードでは、POST操作により、フィールドを更新できます。例えば、Facebookページの管理者であれば、そのdescriptionフィールドを次のように更新できます。

POST graph.facebook.com
  /20531316728?description=The%20OFFICIAL%20Facebook%20Page

エッジを使用してPOST操作を実行すれば、ノードのコレクションに対して新しいオブジェクトを公開できます。Facebookページによって所有されている写真のコレクションに写真を公開する方法を次に示します。

POST graph.facebook.com
  /20531316728/photos

もちろん、コレクションにオブジェクトを公開するには通常、写真のURL、タイトル、説明など、そのオブジェクトに関する追加のフィールドが必要になります。エッジリファレンスドキュメントを見れば、どのフィールドが必須でどれが任意かがわかります。

通常、オブジェクトIDに対してDELETE操作を実行すると、ノードを削除できます。

DELETE graph.facebook.com
  /20531316728

バージョン

グラフAPIは複数のバージョンから成ります。バージョン管理の詳細は「アプリバージョンガイド」に記載されていますが、ここでは特定のバージョンに対して呼び出しを実行する方法について説明します。

方法はとても簡単で、リクエストパスの先頭に、文字vとバージョン番号を追加するだけです。たとえば、バージョン2.9への呼び出しは次のようになります。

GET graph.facebook.com
  /v2.9/20531316728/photos

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

グラフAPI変更履歴」には、利用可能なすべてのバージョンが一覧表示されています。リファレンスドキュメントを使用すれば、コンテンツをバージョンごとにフィルターできます。

次のステップ

次は、「グラフAPIの利用」を読み、リクエストやその応答の詳細について、またグラフAPIを使用して実行できるその他のアクションについてご確認ください。