バッチリクエスト
複数のFacebookグラフAPI呼び出しを含む、単一のHTTPリクエストを送信します。独立した操作は並列で処理され、依存関係を持つ操作は順番に処理されます。すべての操作が完了すると、集約された応答が返され、HTTP接続が閉じられます。
応答の順序は、リクエスト内の操作の順序に対応します。それに応じて応答を処理し、成功した操作と、その後の操作で再試行する必要があるものを判別する必要があります。
制限
- バッチに含めるリクエストは、1つのバッチにつき50個に制限されています。API呼び出し制限とリソース制限を計算するため、バッチ内の各呼び出しは個別にカウントされます。たとえば、1つのバッチに10個のAPI呼び出しが含まれる場合、呼び出しは10回としてカウントされます。また、バッチ内の個々の呼び出しは、CPUリソース制限でも同様にカウントされます。詳しくは、「レート制限ガイド」をご覧ください。
バッチリクエスト
バッチリクエストは、リクエストの配列で構成されるJSONオブジェクトを受け取ります。そして、JSON配列で表現された論理HTTP応答の配列を返します。それぞれの応答には、ステータスコード、ヘッダー配列(オプション)、本文(JSONでエンコードされた文字列、オプション)が含まれます。
バッチリクエストを実行するには、batchパラメーターにJSONオブジェクトを指定して、POSTリクエストをエンドポイントに送信します。
POST /ENDPOINT?batch=[JSON-OBJECT]
単純なバッチリクエスト
次の例では、アプリが管理する2つのページに関する情報を取得します。
読みやすくするためにフォーマットしています。curl -i -X POST 'https://graph.facebook.com/me?batch=
[
{
"method":"GET",
"relative_url":"PAGE-A-ID"
},
{
"method":"GET",
"relative_url":"PAGE-B-ID"
}
]
&include_headers=false // Included to remove header information
&access_token=ACCESS-TOKEN'すべての操作が完了すると、各操作の結果を含む応答が返されます。返されるヘッダーが実際のAPI応答よりかなり大きい場合があるので、ヘッダーを削除することで効率を高められます。ヘッダー情報を含める場合は、include_headersパラメーターを削除するか、またはtrueに設定します。
応答の例
本文フィールドには、文字列がエンコードされたJSONオブジェクトが含まれます:
[
{
"code": 200,
"body": "{
\"name\": \"Page A Name\",
\"id\": \"PAGE-A-ID\"
}"
},
{
"code": 200,
"body": "{
\"name\": \"Page B Name\",
\"id\": \"PAGE-B-ID\"
}"
}
]複雑なバッチリクエスト
一般的にさまざまなHTTPメソッドを使用する操作を1つのバッチリクエストに結合できます。GET操作とDELETE操作ではrelative_urlフィールドとmethodフィールドのみを指定できますが、POST操作とPUT操作ではオプションとしてbodyフィールドを指定できます。本文は、URLクエリ文字列に似た未加工のHTTP POST文字列の形式にしてください。
リクエストの例
次の例では、1つの操作の中で、管理対象であり公開アクセス許可を持っているページに投稿を公開した後、ページのフィードを公開します:
curl "https://graph.facebook.com/PAGE-ID?batch=
[
{
"method":"POST",
"relative_url":"PAGE-ID/feed",
"body":"message=Test status update"
},
{
"method":"GET",
"relative_url":"PAGE-ID/feed"
}
]
&access_token=ACCESS-TOKEN"この呼び出しの出力は次のようになります:
[
{ "code": 200,
"headers": [
{ "name":"Content-Type",
"value":"text/javascript; charset=UTF-8"}
],
"body":"{\"id\":\"…\"}"
},
{ "code": 200,
"headers": [
{ "name":"Content-Type",
"value":"text/javascript; charset=UTF-8"
},
{ "name":"ETag",
"value": "…"
}
],
"body": "{\"data\": [{…}]}
}
]次の例では、キャンペーンのために新しい広告を作成した後、新しく作成されたオブジェクトの詳細を取得します。本文パラメーターのURLEncodingに注意してください。
curl \
-F 'access_token=...' \
-F 'batch=[
{
"method":"POST",
"name":"create-ad",
"relative_url":"11077200629332/ads",
"body":"ads=%5B%7B%22name%22%3A%22test_ad%22%2C%22billing_entity_id%22%3A111200774273%7D%5D"
},
{
"method":"GET",
"relative_url":"?ids={result=create-ad:$.data.*.id}"
}
]' \
https://graph.facebook.com次の例では、ビジネスマネージャに複数のページを追加します。
curl \
-F 'access_token=<ACCESS_TOKEN>' \
-F 'batch=[
{
"method":"POST",
"name":"test1",
"relative_url":"<BUSINESS_ID>/owned_pages",
"body":"page_id=<PAGE_ID_1>"
},
{
"method":"POST",
"name":"test2",
"relative_url":"<BUSINESS_ID>/owned_pages",
"body":"page_id=<PAGE_ID_2>"
},
{
"method":"POST",
"name":"test3",
"relative_url":"<BUSINESS_ID>/owned_pages",
"body":"page_id=<PAGE_ID_3>"
},
]' \
"https://graph.facebook.com/v12.0"説明:
<ACCESS_TOKEN>は、business_managementアクセス許可を持つアクセストークンです。<BUSINESS_ID>は、ページを申請しているビジネスマネージャのIDです。<PAGE_ID_n>は、申請対象のページIDです。
エラー
リクエストした操作の一部がエラーを返す場合があります。原因としては、たとえば、リクエストした操作を実行するアクセス許可がないことが考えられます。応答は標準のグラフAPIと似たものになりますが、バッチ応答構文でカプセル化されます:
[
{ "code": 403,
"headers": [
{"name":"WWW-Authenticate", "value":"OAuth…"},
{"name":"Content-Type", "value":"text/javascript; charset=UTF-8"} ],
"body": "{\"error\":{\"type\":\"OAuthException\", … }}"
}
]バッチ内の他のリクエストは正常に完了し、正常なステータスコード200を返します。
タイムアウト
大規模なバッチや複雑なバッチは、バッチ内のすべてのリクエストの完了に時間がかかりすぎると、タイムアウトすることがあります。この場合、結果としてバッチは部分的に完了します。部分的に完了したバッチでは、正常に完了したリクエストはステータスコード200の正常出力を返します。正常に完了しなかったリクエストの応答はnullになります。成功しなかったリクエストは再試行できます。
JSONPによるバッチ呼び出し
バッチAPIは、他のグラフAPIと同様に、JSONPをサポートしています。JSONPコールバック関数は、callbackクエリ文字列またはフォームポストパラメーターを使って指定します。
複数のアクセストークンを使用する
1つのバッチリクエストに含まれる個々のリクエストでは、独自のアクセストークンをクエリ文字列またはフォームポストパラメーターとして指定できます。その場合、トップレベルのアクセストークンはフォールバックトークンと見なされ、個々のリクエストでアクセストークンが明示的に指定されていない場合に使用されます。
これは、複数の異なるユーザーアクセストークンまたはページアクセストークンを使用してAPIをクエリする場合や、アプリアクセストークンを使用して一部の呼び出しを実行する必要がある場合に役立ちます。
個々のリクエストすべてに独自のトークンを指定する場合でも、1つのアクセストークンをトップレベルパラメーターとして含める必要があります。
バイナリデータをアップロードする
バッチ呼び出しの一環として、複数のバイナリアイテムをアップロードできます。これを行うには、すべてのバイナリアイテムをmultipart/mimeの添付としてリクエストに追加し、それぞれの操作でattached_filesプロパティを使用してバイナリアイテムを参照する必要があります。attached_filesプロパティの値には、添付の名前のコンマ区切りリストを指定できます。
次の例は、1つのバッチ呼び出しで2枚の写真をアップロードする方法を示しています:
curl
-F 'access_token=…' \
-F 'batch=[{"method":"POST","relative_url":"me/photos","body":"message=My cat photo","attached_files":"file1"},{"method":"POST","relative_url":"me/photos","body":"message=My dog photo","attached_files":"file2"},]' \
-F 'file1=@cat.gif' \
-F 'file2=@dog.jpg' \
https://graph.facebook.com