非同期リクエストとバッチリクエスト

非同期リクエストを使用すると、広告を作成して、ブロックすることなく複数の広告リクエストを送信できます。リクエスト完了後に呼び出すURLを指定するか、またはリクエストのステータスを確認します。「広告、リファレンス」をご覧ください。

バッチリクエストは、広告を管理するための最も効率的な方法です。いくつかの一般的なリクエストを実行するために使用します。

非同期リクエスト

例えば、非同期リクエストセットのステータスを取得するには次のようにします。

curl -G \
  -d 'fields=name,success_count,error_count,is_completed' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v19.0/<REQUEST_SET_ID>

これにより、非同期リクエストセット全体のステータスがJSONオブジェクトとして返されます。デフォルトでは、すべてのフィールドが表示されるわけではありません。デフォルト以外のフィールドをクエリに含めるには、fieldsで指定します。例: fields=id,owner_id,name,total_count,success_count,error_count,is_completed。

次のように、非同期リクエストセットの全体的なステータスを取得した後、各リクエストの詳細を取得できます。

curl -G \
  -d 'fields=id,status' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v19.0/<REQUEST_SET_ID>/requests   

これにより、非同期リクエストセット内の各リクエストのステータスと詳細が返されます。非同期広告を作成する場合は、1つの広告の作成ごとに1つのリクエストを実行します。ステータスパラメータは、リクエストのステータスでリクエストをフィルタリングするために使用します。以下の値の任意の組み合わせを使用できます。

• initial – リクエストがまだ処理されていない
• in_progress – リクエストが処理中
• success – リクエストが正常に終了した。
• error – リクエストがエラーで終了した
• canceled – リクエストがユーザーによってキャンセルされた

応答は、デフォルトのフィールドを含むJSON配列です。デフォルト以外のフィールドを含めるには、fieldsで指定します。例: fields=id,scope_object_id,status,result,input,async_request_set。

リクエストの詳細を取得する

特定の非同期リクエストの詳細を取得するには、次の呼び出しを実行します。

curl -G \
  -d 'fields=id,status' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v19.0/<REQUEST_SET_ID>/requests   

これにより、上記のリストに示されているフィールドを含むJSONオブジェクトが返されます。

アカウントのリクエストセットのリストを取得する

非同期広告リクエストセットは複数作成できます。1つの広告アカウントについて、そのすべての非同期広告リクエストセットをクエリするには次のようにします。

curl -G \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v19.0/act_<AD_ACCOUNT_ID>/asyncadrequestsets  

これにより、非同期リクエストセットオブジェクトのJSON配列が返されます。各オブジェクトは、非同期リクエストセットのセクションに示されているものと同じです。is_completedで結果をフィルターできます。is_completed=trueを使用すると、完了した非同期リクエストセットのみが表示されます。

広告セットのリクエストのリストを取得する

1つの非同期呼び出しで、複数の異なる広告セット内に広告を作成できます。各広告セットのステータスを取得するには、1つの広告セットのすべての広告作成リクエストを取得します。

curl -G \
  -d 'fields=id,status' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v19.0/<AD_SET_ID>/asyncadrequests

これにより、非同期リクエストオブジェクトのJSON配列が返されます。ステータス、フィールドフィルター、および非同期リクエストフィールドは、https://graph.facebook.com/<API_VERSION>/<REQUEST_SET_ID>/requests APIと同じです。

リクエストセットを更新する

非同期リクエストセットのname、notification_uri、notification_modeを変更できます。

curl \
  -F 'name=New Name' \
  -F 'notification_mode=OFF' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v19.0/<REQUEST_SET_ID>

更新が成功すると、trueが返されます。notification_uriとnotification_modeは、通知が送信される前にしか変更できません。

リクエストをキャンセルする

非同期リクエストをキャンセルすることは可能ですが、キャンセルできるのはリクエストがまだ処理されていないときだけです。

curl -X DELETE \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v19.0/<REQUEST_ID>

キャンセルが成功すると、trueが返されます。非同期リクエストセットの未処理のリクエストをキャンセルすることもできます。

curl -X DELETE \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v19.0/<REQUEST_SET_ID>

キャンセルが成功すると、trueが返されます。

非同期の例

特定の非同期リクエストのステータスを取得するには次のようにします。

//pretty=true for command line readable output
curl -G \
-d "id=6012384857989" \
-d "pretty=true" \
-d "access_token=_____" \
"https://graph.facebook.com/v19.0/"

返り値は、次のようになります。

{
   "id": "6012384857989",
   "owner_id": 12345,
   "name": "testasyncset",
   "is_completed": true
}

リクエストの結果を取得するには次のようにします。

curl -G \
-d "id=6012384857989" \
-d "pretty=true" \
-d "fields=result" \
-d "access_token=_____" \
"https://graph.facebook.com/v19.0/requests"

返り値:

{
   "data": [
      {
         "result": {
            "id": "6012384860989"
         },
         "id": "6012384858389"
      },
      {
         "result": {
            "id": "6012384858789"
         },
         "id": "6012384858189"
      }
   ],
   "paging": {
      "cursors": {
         "after": "___",
         "before": "___"
      }
   }
}

広告アカウントのリクエストセットのリストを取得するには次のようにします。

curl -G \
-d "is_completed=1" \
-d "pretty=true" \
-d "access_token=___" \
"https://graph.facebook.com/v19.0/act_71597454/asyncadrequestsets"

返り値:

{
   "data": [
      {
         "id": "6012384253789",
         "owner_id": 71597454,
         "name": "testasyncset",
         "is_completed": true
      },
   ],
   "paging": {
      "cursors": {
         "after": "___",
         "before": "___"
      }
   }
}

キャンペーンのリクエストのリストを取得するには次のようにします。

curl -G \
-d "status=SUCCESS,ERROR" \
-d "pretty=true" \
-d "access_token=___" \
"https://graph.facebook.com/v19.0/6008248529789/asyncadrequests"
    

返り値は、次のようになります。

{
   "data": [
      {
         "id": "6012384951789",
         "scope_object_id": 6008248529789,
         "status": "SUCCESS"
      },
   ],
   "paging": {
      "cursors": {
         "after": "___",
         "before": "___"
      }
   }
}

バッチリクエスト

バッチリクエストでは、複数のグラフAPI呼び出しを組み合わせて、1つのHTTPリクエストにします。バッチリクエストは、マーケティングAPIにより、構成要素である個々のリクエストに分割されます。このため、バッチリクエストは、マーケティングAPIとやり取りする最も効率的な方法です。さらに効率を高めるには、別々の処理スレッドを使用して、複数の並列バッチリクエストを実行します。

広告、広告クリエイティブ、広告セットのバッチリクエストはよく似ているため、ここでは個別の説明は省きます。詳しくは、「グラフAPIのバッチリクエスト」と「ETag」をご覧ください。

広告を作成する

広告クリエイティブと他の広告オブジェクトをバッチリクエストで指定できます。例えば、1つの広告クリエイティブと3つの異なるターゲット設定スペックを使用して、3つの広告を作成できます。最初に広告クリエイティブを定義した後、個々の広告を作成する際に、その広告クリエイティブを参照します。

curl -F 'access_token=______' 
  -F 'test1=@./test1.jpg'  
  -F 'batch=[
             {
              "method": "POST",
              "name": "create_adimage",
              "relative_url": "<API_VERSION>/act_187687683/adimages",
              "attached_files": "test1"
             },
             {
              "method": "POST",
              "name": "create_creative",
              "relative_url": "<API_VERSION>/act_187687683/adcreatives",
              "attached_files": "test1",
              "body": "name=sample creative&object_story_spec={\"link_data\": {\"image_hash\": \"{result=create_adimage:$.images.*.hash}\", \"link\": \"https://www.test12345.com\", \"message\": \"this is a sample message\"}, \"page_id\":\"12345678\"}&degrees_of_freedom_spec={\"creative_features_spec\": {\"standard_enhancements\": {\"enroll_status\": \"OPT_OUT\"}}}"
             },
             {
              "method": "POST",
              "relative_url": "<API_VERSION>/act_187687683/ads",
              "body": "adset_id=6004163746239&redownload=1&status=PAUSED&optimization_goal=REACH&billing_event=IMPRESSIONS&&creative={\"creative_id\":\"{result=create_creative:$.id}\"}&targeting={\"countries\":[\"US\"]}&name=test1"
             },
             {
              "method": "POST",
              "relative_url": "<API_VERSION>/act_187687683/ads",
              "body": "adset_id=6004163746239&redownload=1&status=PAUSED&optimization_goal=REACH&billing_event=IMPRESSIONS&&creative={\"creative_id\":\"{result=create_creative:$.id}\"}&targeting={\"countries\":[\"US\"]}&name=test2"
             },
             {
              "method": "POST",
              "relative_url": "<API_VERSION>/act_187687683/ads",
              "body": "adset_id=6004163746239&redownload=1&status=PAUSED&optimization_goal=REACH&billing_event=IMPRESSIONS&&creative={\"creative_id\":\"{result=create_creative:$.id}\"}&targeting={\"countries\":[\"US\"]}&name=test3"
             }
            ]' https://graph.facebook.com/

応答には、リクエストごとの応答コードと、グラフAPIの標準応答が含まれます。詳しくは、複数のAPIリクエストの実行をご覧ください。

バッチリクエスト処理では、それ以前のリクエストを参照するために、JSONPath式の形式が使用されます。

広告を更新する

バッチリクエストで広告を更新できます。3つの広告の入札を更新するには、次のようにします。

curl -F 'access_token=____' 
  -F 'batch=[
             {
              "method": "POST",
              "relative_url": "<API_VERSION>/6004251715639",
              "body": "redownload=1&name=new name"
             },
             {
              "method": "POST",
              "relative_url": <API_VERSION>/v6004251716039",
              "body": "redownload=1&name=new name"
             },
             {
              "method": "POST",
              "relative_url": "<API_VERSION>/6004251715839",
              "body": "redownload=1&name=new name"
             }
            ]' https://graph.facebook.com

相対URLにredownload=1を含めると、広告IDを含む完全な広告の詳細を取得できます。これは、どの広告を更新したかを識別するのに役立ちます。

広告クリエイティブを更新するには、クリエイティブ全体を指定するか、新しいクリエイティブIDを指定します。これは、広告クリエイティブが作成された後は、名前と実行ステータス以外の編集ができなくなるためです。

広告を読み取る

多数の広告がある場合は、1つのバッチリクエスト内でリクエストを複数のリクエストに分割します。

curl -F 'access_token=____' 
  -F 'batch=[
             {
              "method": "GET",
              "relative_url": "<API_VERSION>/?ids=6003356308839,6004164369439&fields=<comma separated list of fields>"
             },
             {
              "method": "GET",
              "relative_url": "<API_VERSION>/6003356307839/ads&fields=<comma separated list of fields>"
             },
             {
              "method": "GET",
              "relative_url": "<API_VERSION>/act_187687683/ads?adset_ids=[6003356307839, 6004164259439]&fields=<comma separated list of fields>"
             }
            ]' https://graph.facebook.com

6003356308839と6004164369439は広告IDであり、6003356307839と6004164259439は広告セットIDです。

広告インサイト

多数の広告インサイトがある場合は、1つのバッチリクエスト内でリクエストを複数のリクエストに分割します。

curl -F 'access_token=____' 
  -F 'batch=[
             {
              "method": "GET",
              "relative_url": "<API_VERSION>/act_19643108/insights?filtering=[{field:'ad.id',operator:'IN',value:[6003356308839,6004164369439]}]"
             },
             {
              "method": "GET",
              "relative_url": "<API_VERSION>/6003356308839/insights"
             },
             {
              "method": "GET",
              "relative_url": "<API_VERSION>/act_187687683/insights?filtering=[{field:'adset.id',operator:'IN',value:[6003356307839, 6004164259439]}]"
             }
            ]' https://graph.facebook.com

この例で、6003356308839と6004164369439は広告IDであり、6003356307839と6004164259439は広告セットIDです。

広告アカウントに広告が大量にある場合、act_<account_ID>/adgroupstatsの使用は、リクエストがタイムアウトする可能性があるため、おすすめしません。

リーチ推定のバッチリクエスト

単一のバッチリクエストで、最大50の推定リーチをリクエストできます。次の例では、2つの異なるターゲット設定スペックについて推定リーチをリクエストしています。

curl -F 'access_token=____' 
  -F 'batch=[
             {
              "method": "GET",
              "relative_url": "<API_VERSION>/act_600335/reachestimate?targeting_spec={'geo_locations': {'countries':['US']}}"
             },
             {
              "method": "GET",
              "relative_url": "<API_VERSION>/act_600335/reachestimate?targeting_spec={'geo_locations': {'countries':['FR']}}"
             }
            ]' https://graph.facebook.com

バッチAPI

バッチAPIを使用すると、バッチリクエストを非同期で送信できます。複数のグラフAPI呼び出しを1つのHTTPリクエストにまとめて、ブロックすることなく非同期で実行します。関連する操作の間の依存関係を指定することもできます。

Facebookは、依存関係のない操作はそれぞれ並列で処理し、依存関係のある操作は順番に処理します。個々のAPI呼び出しには、最大1,000のリクエストを含めることができます。

バッチAPI呼び出しを実行する

バッチAPI呼び出しを行うには、次のようにします。

curl \
-F "access_token=___" \
-F "name=asyncbatchreqs" \
-F "adbatch=<an array of requests>"\
"https://graph.facebook.com/v19.0/act_<AD_ACCOUNT_ID>/async_batch_requests"

HTTP POSTリクエストの配列をJSON配列として指定します。各リクエストには以下が含まれます。

• name
• relative_url - URLのgraph.facebook.comより後の部分
• body

このAPIは、リクエストの進行状況のクエリに使用できるIDを返します。

例えば、以前のリクエストを参照するためにJSONPath形式を使用した広告セットを指定してキャンペーンを作成するには、次のようにします。

curl \
-F "access_token=___" \
-F "name=batchapiexample" \
-F "adbatch=[
  {
    'name': 'create-campaign',
    'relative_url': 'act_123456/campaigns',
    'body': 'name%3DTest+Campaign%26objective%3DLINK_CLICKS%26status%3DPAUSED%26buying_type%3DAUCTION',
  },
  {
    'name': 'create-adset',
    'relative_url': 'act_123456/adsets',
    'body': 'targeting%3D%7B%22geo_locations%22%3A%7B%22countries%22%3A%5B%22US%22%5D%7D%7D%26daily_budget%3D5000%26campaign_id%3D%7Bresult%3Dcreate-campaign%3A%24.id%7D%26bid_amount%3D2%26name%3DFirst%2BAd%2BSet%20Test%26billing_event%3DLINK_CLICKS',
  },
]" \
https://graph.facebook.com/<API_VERSION>/act_123456/async_batch_requests

リクエストセットステータスを取得するには、次のようにします。

curl –G \
-d "access_token=___" \
-d "fields=<comma separated list of fields>" \
"https://graph.facebook.com/v19.0/<REQUEST_SET_ID>"

これにより、非同期リクエストセット全体のステータスがJSONオブジェクトとして返されます。デフォルトでは、すべてのフィールドが返されるわけではありません。デフォルト以外のフィールドを含めるには、fieldsで指定します。例: fields=id,owner_id,name,total_count,success_count,error_count,is_completed

全体のステータスを取得した後、各リクエストの詳細を取得できます。

curl –G \   
-d "access_token=___" \
-d "fields=<comma separated list of fields>" \
"https://graph.facebook.com/v19.0/<REQUEST_SET_ID>/requests"

これにより、詳細がJSON配列として返されます。デフォルト以外のフィールドを含めるには、fieldsで指定します。例: fields=id,scope_object_id,status,result,input,async_request_set。

広告アカウントのバッチAPIリクエストのリストを取得する

複数のバッチAPIリクエストセットを作成できます。1つの広告アカウントの下のすべてのリクエストセットをクエリするには、次のようにします。

curl –G \ 
-d "access_token=___" \
"https://graph.facebook.com/v19.0/act_<AD_ACCOUNT_ID>/async_requests"

ETags

マーケティングAPIでは、Etagsがサポートされています。これは、クエリ対象データが前回の確認時から変更されたかどうかを知るのに役立ちます。動作のしくみは次のとおりです。

1. 呼び出しを実行すると、応答ヘッダーに、API呼び出しで返されたデータのハッシュ値を持つETagが含められます。このETag値を、次のステップで使用するために保存します。
2. 同じAPI呼び出しを次に実行するときに、保存したETag値を指定したIf-None-Matchリクエストヘッダーを含めます。
3. データが変更されていない場合、応答ステータスコードは304 – Not Modifiedになり、データは返されません。
4. 前回のクエリ以降にデータが変更されている場合、通常どおりデータが返されるとともに、新しいETagが返されます。新しいETag値を保存し、その後の呼び出しでそれを使用します。

ETagはデータトラフィックの削減に役立ちますが、アプリのレート制限ではIf-None-Match GETもカウントされます。

ETagの計算では、API呼び出しからの応答全体(書式設定も含む)が使用されます。応答の書式設定は、ユーザーエージェント文字列の影響を受ける場合があります。従って、同じクライアントから実行する呼び出しでは、一貫したユーザーエージェントを使用してください。

Etagsの例

ユーザーの広告アカウントが変更されたかどうかをチェックする例を次に示します。

ステップ1: 現在のデータのETagを確認する

curl -i "https://graph.beta.facebook.com/me/adaccounts?access_token=___"

応答は次のようになります。

HTTP/1.1 200 OK
Access-Control-Allow-Origin: *
Cache-Control: private, no-cache, no-store, must-revalidate
Content-Type: text/javascript; charset=UTF-8
ETag: "7776cdb01f44354af8bfa4db0c56eebcb1378975"
Expires: Sat, 01 Jan 2000 00:00:00 GMT
Pragma: no-cache
X-FB-Rev: 495685
X-FB-Server: 10.30.149.204
X-FB-Debug: CWbHcogdwUE8saMv6ML+8FacXFrE8ufhjjwxU2dQWaA=
X-Cnection: close
Date: Mon, 16 Jan 2012 12:07:44 GMT
Content-Length: 3273

{"data":[{"id":"act.......

この例のETagは、"7776cdb01f44354af8bfa4db0c56eebcb1378975"です。ETagに引用符(")が含まれていることに注意してください。

ステップ2: データに何らかの変更が加えられているかどうかを判定する

curl -i -H "If-None-Match: \"7776cdb01f44354af8bfa4db0c56eebcb1378975\"" "https://graph.beta.facebook.com/me/adaccounts?access_token=___"

何も変更されていない場合、応答は次のようになります。

HTTP/1.1 304 Not Modified
Access-Control-Allow-Origin: *
Cache-Control: private, no-cache, no-store, must-revalidate
Content-Type: text/javascript; charset=UTF-8
Expires: Sat, 01 Jan 2000 00:00:00 GMT
Pragma: no-cache
X-FB-Rev: 495685
X-FB-Server: 10.30.177.190
X-FB-Debug: ImBhat3k07Nez5FvuS2lPWU0U2xxmxD4B3k9ua4Sk7Q=
X-Cnection: close
Date: Mon, 16 Jan 2012 12:09:17 GMT
Content-Length: 0

応答が304 Not Modifiedであることに注意してください。データが変更されている場合は、通常のAPI応答が返されます。

ユーザーの広告が変更されているかどうかをチェックするバッチの例を次に示します。

ステップ1: 現在のデータのETagを確認する

curl -i "curl -F 'access_token=___' -F 'batch=[ 
  {"method":"GET", "relative_url": "?ids=6003356308839,6004164369439" }, 
  {"method":"GET", "relative_url": "act_12345678/ads?campaign_ids=[6003356307839, 6004164259439]"}]'
 https://graph.facebook.com"

応答には、次のようなETag値が含まれます。

...{"name":"ETag","value":"\"21d371640127490b2ed0387e8af3f0f8c9eff012\""}...      
...{"name":"ETag","value":"\"410e53bb257f116e8716e4ebcc76df1c567b87f4\""}...

この例のETagは、"21d371640127490b2ed0387e8af3f0f8c9eff012"と"410e53bb257f116e8716e4ebcc76df1c567b87f4"です。ETagに引用符(")が含まれていることに注意してください。

ステップ2: データに何らかの変更が加えられているかどうかを判定する。

curl -F 'access_token=___' -F 'batch=[
  {"method":"GET", "headers":["If-None-Match: \"21d371640127490b2ed0387e8af3f0f8c9eff012\""], "relative_url": "?ids=6003356308839,6004164369439" },
  {"method":"GET",  "headers":["If-None-Match: \"410e53bb257f116e8716e4ebcc76df1c567b87f4\""], "relative_url": "act_12345678/ads?campaign_ids=[6003356307839, 6004164259439]"}]' 
https://graph.facebook.com

何も変更されていない場合、応答は次のようになります。

[{
    "code": 304,
    .
    .
    .
    "body": null
},
{
    "code": 304,
    .
    .
    .
    "body": null
}]

応答が304 Not Modifiedであることに注意してください。データが変更されている場合は、通常のAPI応答が返されます。