推廣 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

此操作會傳回非同步要求組合中各個要求的狀態和詳細資訊。如果是非同步廣告建立流程，請發出一個要求以建立一個廣告。此狀態參數用於按要求狀態篩選要求，此參數可為以下任何值的組合：

  • 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

類型：陣列

預設為隱藏。

如果要求已完成，則顯示要求結果。
如果要求成功，則結果與不是非同步要求的結果相同。例如，如果您建立了一個廣告，則各個要求的結果均為新廣告的編號。如果出現錯誤，則此項為以下項目的陣列：

  • 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": "___"
      }
   }
}

批量要求

透過批量要求，您可以將多個 Graph API 呼叫合併為一個 HTTP 要求。推廣 API 可將此要求分割為多個子要求，因此批量要求可謂與推廣 API 互動的最高效方式。如需進一步提升效率，您可以使用獨立的處理執行緒發出並行批量要求。

每個批量要求最多可包含 50 項要求。如果是廣告建立流程，每個批次所包含的廣告不得超過 10 個。

廣告、廣告創意和廣告組合的批量要求非常相似，因此不在此作個別探討。詳情請參閱 Graph 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/

相關回應包含各個要求的個別回應代碼以及標準 Graph 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 可讓您發出批量要求，並以非同步形式傳送這些要求。將數個 Graph API 呼叫組合為單一 HTTP 要求，在無需封鎖的情況下以非同步方式執行這些呼叫。您也可以指定相關操作之間的相依項目。

Facebook 會並行處理各個獨立操作，並按順序處理您的相依操作。每個 API 呼叫最多包含 1,000 項要求。

發出批量 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

類型：陣列

預設為隱藏。

如果要求完成，系統會顯示結果。如果要求成功，則結果與不是非同步的 API 結果相同。例如，如果您建立了廣告建立流程，則結果為新廣告的編號。如果要求出錯，則結果為：

  • 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。這有助確定您查詢的資料自上次查詢後有否變更。以下是 ETag 的運作方式：

  1. 發出呼叫時，回應標題會包含 ETag，其值為 API 呼叫傳回的資料雜湊值。儲存此 ETag 值，以供後續步驟使用。
  2. 當您下次發出同一個 API 呼叫時，加入 If-None-Match 要求標題及已儲存的 ETag 值。
  3. 如果資料未有變更，回應狀態碼為 304 – Not Modified，系統不會傳回任何資料。
  4. 如果資料自上次查詢後有所變更，系統將照常傳回資料，並包含新的 ETag。儲存新的 ETag 值，以便在後續呼叫中使用。

雖然 ETag 有助減少資料流量，但 If-None-Match GET 仍然會計入應用程式的限速限制。

ETag 使用 API 呼叫的整個回應以作計算，當中包含其格式。回應的格式可能受用戶代理字串影響。因此，您應該確保同一個用戶端發出的呼叫之間的用戶代理相符。

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 回應。