Business Management APIs

入門指南

學習如何實作廣告創意素材管理。

廣告創意素材管理僅提供給特定合作夥伴使用。請聯絡您的 Meta 合作夥伴以瞭解詳情。

需求

若要使用此 API，您需要：

權限

登入應用程式時，您需要向您的用戶請求以下權限：

  • business_creative_management - 管理商用廣告創意資料夾和商用廣告創意。這是所有商用廣告創意素材管理平台 API 端點的必要條件。
  • business_creative_insights - 存取商用廣告創意素材洞察報告。
  • business_management - 管理企業用戶與接受合夥協議要求。

限制

  • 應用程式用戶（廣告商）必須是企業管理平台編號所代表之商家的管理員

步驟 1：建立商用廣告創意資料夾

發出 POST 要求至 {business-id}/creative_folders 端點，將可代表廣告商企業建立商用廣告創意資料夾。在此情況下，{business-id} 為廣告商的企業編號。

需要有 business_creative_management 權限才能執行此動作。

要求範例

curl -X POST \
  -F 'name={folder-name}' \
  -F 'access_token={access-token}' \
  https://graph.facebook.com/<API_VERSION>/<BUSINESS_ID>/creative_folders

回應範例

{ “id”: “{business-creative-folder-id}” }

您也可以建立子資料夾。

步驟 2：將廣告創意新增至資料夾

發出 POST 要求至 {business-id}/images 或 {business-id}/videos，可將現有廣告創意素材新增至資料夾。您需要有 business_creative_management 權限才能執行此動作。

新增圖像

範例 — 新增圖像的方法：

curl -X POST \
  -F 'bytes={image-content-in-bytes-format}' \
  -F 'name={image-name}' \
  -F 'access_token={access-token}' \
  -F 'creative_folder_id={business-creative-folder-id}' \
  https://graph.facebook.com/{version}/{business-id}/images

回應

{
  "images":{
    "{image-name}":{
      "id":"{business-image-id}",
      "hash":"{hash}",
      "url":"{image-url}"
    }
  }
}

上傳影片

若影片大小不超過數 MB，請使用單一要求上傳影片，否則請由 chunks 上傳。請在 graph-video.facebook.com 發出上傳影片的 API 呼叫，而不要在 graph.facebook.com 發出。

範例 — 傳送 POST 到 {business-id}/video，並且註明影片的名稱、出處以及商用廣告創意資料夾編號。

curl -X POST \
  -F 'name={video-name}' \
  -F 'source='@{video-path}'' \
  -F 'access_token={access-token}' \
  -F 'creative_folder_id={business-creative-folder-id}' \
  https://graph-video.facebook.com/{version}/{business-id}/videos

回應

{ 
    "success": true, 
    "business_video_id": "{business-video-id}" 
}

上傳區塊影片

對於較大的影片，請傳送一項 start 要求、一或多項 transfer 要求，以及一項 finish 要求。

如要發出 start 要求並建立一個影片上傳連線階段，請傳送一項 POST 要求到 /{business-id}/videos、將 upload_phase 欄位設為 start，再以位元組為單位指定 file_size。

curl -X POST \
  -F 'title={video-name}' \
  -F 'creative_folder_id={business-creative-folder-id}' \
  -F 'access_token={access-token}' \
  -F 'upload_phase=start' \
  -F 'file_size={video_file_size_in_bytes}' \
  https://graph-video.facebook.com/<API_VERSION>/<BUSINESS_ID>/videos

回應範例

{
  "upload_session_id": "{session-id}",
  "business_video_id": "{business-video-id}",
  "video_id": "{video-id}",
  "start_offset": "0",
  "end_offset": "52428800"
}

如要上傳影片的 [0, 52428800]，請按照開始和結束位移點將檔案分段，然後使用 transfer 要求傳送這些片段。每一個片段，我們會分別傳送一個新的位移點給您。請使用這些新位移點上傳每個片段。

範例：傳送第一個片段

curl -X POST \
  -F 'title={video-name}' \
  -F 'access_token={access-token}' \
  -F 'creative_folder_id={business-creative-folder-id}' \
  -F 'upload_phase=transfer' \
  -F 'upload_session_id={session-id}' \
  -F 'start_offset=0' \
  -F 'video_file_chunk=@{binary-chunk-filename}' \
  https://graph-video.facebook.com/<API_VERSION>/<BUSINESS_ID>/videos

成功之後，我們會發出回應，也就是下一個片段的位移點：

{
 "start_offset": "52428800",    //Start byte position of the next file chunk.
 "end_offset": "104857601"      //End byte position of the next file chunk.
}

按照 [52428800, 104857601] 這個範圍，從檔案中剪出並上傳第二個片段，並且傳送片段：

curl -X POST \
  -F 'title={video-name}' \
  -F 'access_token={access-token}' \
  -F 'creative_folder_id={business-creative-folder-id}' \
  -F 'upload_phase=transfer' \
  -F 'start_offset=52428801' \
  -F 'upload_session_id={your-upload-sesson-id}' \
  -F 'video_file_chunk={binary-chunk-filename}' \
  https://graph-video.facebook.com/<API_VERSION>/<BUSINESS_ID>/videos

傳送所有其他片段，一直到 start_offset 等於 end_offset 為止：

{
  "start_offset": "152043520",
  "end_offset": "152043520"
}

這表示您已經上傳了整個檔案。現在您需要發佈這個影片，並且關閉上傳連線階段。

curl -X POST \
  -F 'title={video-name}' \
  -F 'access_token={access-token}' \
  -F 'creative_folder_id={business-creative-folder-id}' \
  -F 'upload_phase=finish' \
  -F 'upload_session_id={session-id}' \
  https://graph-video.facebook.com/<API_VERSION>/<BUSINESS_ID>/videos

如果上傳過程中出現錯誤，您可以重試上傳該片段。錯誤通常是回應問題所造成。請試著重新上傳無法上傳的片段。如要查看更多有關錯誤的資訊，請參閱：

當您將廣告創意上傳到資料夾後，有權存取資料夾的廣告商即可在廣告管理員建立廣告，或是用 行銷 API 建立廣告。

所有上傳的廣告創意將會顯示於廣告管理員 > 影音素材選項用戶介面。您可以在廣告建立流程和廣告編輯流程使用這些素材。此外，也可前往企業管理平台 > 影音資料庫，在企業管理平台的「影音資料庫」工具中使用這些資料夾和廣告創意素材。

步驟 3：提供素材的深層連結網址，並建立廣告或貼文

如要取得特定素材的深層連結網址，請查詢所上傳圖像或影片素材的 media_library_url 欄位：

curl -X GET \  
  -F 'access_token={partner-access-token}' \
https://graph.facebook.com/v<API_VERSION>/<asset_id>?fields=media_library_url

如要使用深層連結來建立廣告或是粉絲專頁貼文，請在連結末尾附加 &action=CREATE_AD 或 &action=CREATE_POST：

https://business.facebook.com/asset_library/business_creatives/?object_id=<OBJECT_ID>&action=CREATE_AD