市场营销 API

异步和批量请求

使用异步请求来创建广告，无需限制即可发送大量广告请求。您需要指定完成请求后要调用的网址，或检查请求的状态。请参阅“参考资料”>“广告”。

批量请求是管理广告的最高效方法。此方法用于执行一些更常见的请求。

异步请求

例如，获取异步请求集的状态：

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

系统会以 JSON 对象形式返回异步请求集的整体状态。默认情况下，有些字段不会显示。如果您希望查询包含非默字段，请在 fields 中指定这些字段，例如 fields=id,owner_id,name,total_count,success_count,error_count,is_completed。

名称 描述

id

类型：整数

默认情况下显示。

当前异步请求集的 id。

owner_id

类型：整数

默认情况下显示。

拥有此异步请求集的对象。对于广告异步请求，owner_id 为相应账户编号。

name

类型：字符串

默认情况下显示。

此异步请求集的名称。

is_completed

类型：布尔值

默认情况下显示。

此请求集中的异步请求已完成

total_count

类型：整数

默认情况下不显示。

此请求集的请求总数

initial_count

类型：整数

默认情况下不显示。

尚未处理的请求数。

in_progress_count

类型：整数

默认情况下不显示。

正在处理的请求数。

success_count

类型：整数

默认情况下不显示。

已完成并成功的请求数。

error_count

类型：整数

默认情况下不显示。

已完成但失败的请求数。

canceled_count

类型：整数

默认情况下不显示。

用户取消的请求数

notification_uri

类型：字符串

默认情况下不显示。

此异步请求集的通知 URI。

notification_mode

类型：字符串

默认情况下不显示。

接收通知的方式。有效值包括：

  • OFF – 不发送通知
  • ON_COMPLETE – 整个请求集完成时发送通知。

获取异步请求集的整体状态后，获取每个请求的详细信息：

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

系统会返回异步请求集中每个请求的状态和详细信息。对于异步广告创建，发出一个请求即可创建一个广告。status 参数用于根据请求自身状态来筛选请求，可以是以下值的任意组合：

  • initial – 尚未处理。
  • in_progress – 正在处理请求
  • success – 请求已完成并成功。
  • error – 请求已完成但失败
  • canceled – 用户已取消请求

响应为包含默认字段的 JSON 数组。如果希望响应中包含任何非默认字段，请在 fields 中指定这些字段，例如 fields=id,scope_object_id,status,result,input,async_request_set。

名称 描述

id

类型：整数

默认情况下显示。

每个异步请求的编号

scope_object_id

类型：整数

默认情况下显示。

此请求创建的对象的父编号。如果您创建广告，则这是新广告的广告组编号。

status

类型：字符串

默认情况下显示。

此异步请求的状态。选项：

  • Initial – 尚未处理
  • In_progress – 正在处理请求
  • Success – 请求已完成并成功
  • Error – 请求已完成但失败
  • Canceled – 用户已取消请求

result

类型：数组

默认情况下不显示。

如果请求已完成，则此字段会显示请求的结果。
如果请求成功，result 字段与非异步请求的结果相同。例如，如果您创建广告，每个请求的 result 字段就是新广告的编号。如果出错，result 字段将是包含以下项的数组：

  • error_code – 返回的错误代码
  • error_message – 错误消息

input

类型：对象

默认情况下不显示。

此异步请求的原始输入。如果创建广告，则输入为 adgroup_spec。

async_request_set

类型：对象

默认情况下不显示。

包含此单个请求的异步请求集

获取请求详情

如要获取特定异步请求的详情，请执行以下调用：

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

系统会返回包含上述字段的 JSON 对象。

列出账户的请求集

您可以创建多个异步广告请求集。如要查询特定广告账户的所有异步广告请求集，请执行以下调用：

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

系统会返回包含异步请求集对象的 JSON 数组。每个对象都与异步请求集部分中说明的对象相同。您可以使用 is_completed 筛选结果。如果将其设为 is_completed=true，则您仅会看到完成的异步请求集。

列出广告组的请求

您可发出异步调用，在不同的广告组中创建广告。如要获取每个广告组的状态，可获取一个广告组的所有广告创建请求：

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

系统会返回包含异步请求对象的 JSON 数组。状态、字段筛选条件和异步请求字段与 https://graph.facebook.com/&lt;API_VERSION>/&lt;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/v21.0/<REQUEST_SET_ID>

如果更新成功，系统会返回 true。您仅可在发送通知前更改 notification_uri 和 notification_mode。

取消请求

您可以取消异步请求，但只能取消尚未处理的异步请求。

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

如果取消成功，系统会返回 true。您还可以取消异步请求集中未处理的请求：

curl -X DELETE \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v21.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/v21.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/v21.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/v21.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/v21.0/6008248529789/asyncadrequests"

系统会返回以下值：

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

批量请求

通过批量请求，可将多个图谱 API 调用合并到一个 HTTP 请求中。市场营销 API 会将此类请求拆分为其组成请求。这使得批量请求成为与市场营销 API 互动的最高效方式。为了进一步提升效率，您可以使用单独的处理线程发出并行批量请求。

每个批量请求最多可包含 50 个请求。对于广告创建流程，每个批次只能包含最多 10 个广告。

针对广告、广告创意和广告组的批量请求十分相似，所以我们不在这里单独讨论。详情请参阅图谱 API 批量请求和 ETag。

创建广告

您可以在批量请求中提供广告创意和其他广告对象。例如，您可以使用一个广告创意和三个不同的定位参数创建三个广告。先定义您的广告创意，然后在创建各个广告时引用该创意：

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 表达式格式引用之前的请求。

更新广告

您可以使用批量请求更新广告。如要更新三个广告的竞价，可执行以下调用：

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

如果您在相关网址中加入 redownload=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 是广告编号，6003356307839 和 6004164259439 是广告组编号。

广告成效分析

如果您有大量广告成效分析，请在批量请求中将请求拆分成多个请求：

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 是广告编号，6003356307839 和 6004164259439 是广告组编号。

对于包含大量广告的广告账户，不建议使用 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 调用组合成一个 HTTP 请求，并以异步方式执行这些调用，而不必中止进程。您也可以指定相关操作之间的依赖关系。

Facebook 在并行进程中处理每个独立操作，并按顺序执行依赖操作。每个 API 调用最多可包含 1000 个请求。

发出批处理 API 调用

如要执行批处理 API 调用，可使用以下代码：

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

以 JSON 数组形式提供由 HTTP POST 请求组成的数组。每个请求都拥有以下字段：

  • name
  • relative_url - graph.facebook.com 之后的网址部分
  • body

批处理 API 会返回一个编号，您将使用该编号来查询请求的进度。

例如，使用 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/v21.0/<REQUEST_SET_ID>"

系统会以 JSON 对象的形式返回异步请求集的整体状态。默认情况下，系统不会返回所有字段。要包含这些字段，请指定 fields，例如，fields=id,owner_id,name,total_count,success_count,error_count,is_completed

名称 描述

id

类型：整数

默认情况下显示。

当前异步请求集的 id。

owner_id

类型：整数

默认情况下显示。

拥有此异步请求集的对象。如果创建广告，则 owner_id 为广告账户编号。

name

类型：字符串

默认情况下显示。

此异步请求集的名称

is_completed

类型：布尔值

默认情况下显示。

此请求集中的所有异步请求已完成

total_count

类型：整数

默认情况下不显示。

此请求集的请求总数

initial_count

类型：整数

默认情况下不显示。

尚未处理的请求数

in_progress_count

类型：整数

默认情况下不显示。

正在处理的请求数

success_count

类型：整数

默认情况下不显示。

已完成并成功的请求数

error_count

类型：整数

默认情况下不显示。

已完成但失败的请求数

canceled_count

类型：整数

默认情况下不显示。

用户取消的请求数

notification_uri

类型：字符串

默认情况下不显示。

此异步请求集的通知 URI。

notification_mode

类型：字符串

默认情况下不显示。

接收通知的方式。有效值：

  • OFF – 不发送通知
  • ON_COMPLETE – 整个请求集完成时发送通知。

notification_result

类型：字符串

默认情况下不显示。

发送通知的结果。

notification_status

类型：字符串

默认情况下不显示。

通知状态：not_sent、sending 或 sent

获取整体状态后，可获取每个请求的详细信息：

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

系统会以 JSON 数组的形式返回详细信息。如果希望响应中包含非默认字段，请在 fields 中指定这些字段，例如 fields=id,scope_object_id,status,result,input,async_request_set。

名称 描述

id

类型：整数

默认情况下显示。

每个异步请求的编号

scope_object_id

类型：整数

默认情况下显示。

此请求创建的对象的父编号。如果创建广告，则这是新广告的广告组编号。

status

类型：字符串

默认情况下显示。

此异步请求的状态：

  • Initial – 尚未处理
  • In_progress – 正在处理请求
  • Success – 请求已完成并成功
  • Error – 请求已完成但失败
  • Canceled – 用户已取消请求

result

类型：数组

默认情况下不显示。

如果请求已完成，此数组会显示结果。如果请求成功，则 result 与非异步 API 的结果相同。例如，如果您创建广告，result 为新广告编号。如果请求出错：

  • error_code – 返回的错误代码
  • error_message – 错误消息

input

类型：对象

默认情况下不显示。

此请求的原始输入。如果创建广告，则输入为 adgroup_spec。

async_request_set

类型：对象

默认情况下不显示。

包含此请求的异步请求集。

列出广告账户的批处理 API 请求

您可以创建多个批处理 API 请求集。如要查询特定广告账户下的所有请求集，请执行以下调用：

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

ETag

市场营销 API 支持 Etag。这可以帮助您判断自上次检查以来，查询的数据是否已发生更改。运作方式：

  1. 在您执行调用时，响应标头将包含一个 ETag，其中的值是 API 调用所返回数据的哈希值。您应该保存此 ETag 值，将其用于后续步骤。
  2. 下一次调用同一个 API 时，添加 If-None-Match 请求标头和保存的 ETag 值。
  3. 如果对应的数据没有发生更改，响应状态代码将为 304 – Not Modified，且不会返回任何数据。
  4. 如果自上次查询后数据已发生更改，则系统将照常返回该数据，并附带新的 ETag。请保存新的 ETag 值，并将其用于后续调用。

虽然 Etag 有助于减少数据流量，但 If-None-Match GET 仍会计入您应用的流量限制。

系统会使用 API 调用的整个响应（包括其格式）计算 ETag。响应的格式可能会受用户代理字符串影响。因此，您应该确保通过同一客户端执行的调用之间的用户代理一致。

Etag 示例

检查用户的广告账户是否有变化。

第 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 响应。