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

批次要求

透過批次要求，您可將多個圖形 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"

提供 HTTP POST 要求的陣列作為 JSON 陣列。每個要求包含：

  • 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，可協助您判斷自上次檢查以來查詢的資料是否已變更。運作方式：

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