圖形 API

第 2.11 版

圖形 API | 行銷 API

變更紀錄項目分為以下類別：

  • 新功能 — 新產品或服務，包括新的節點、關係連線和欄位。
  • 變更項目 — 對既有產品或服務的變更（不包括淘汰項目）。
  • 淘汰項目 — 要移除的既有產品或服務。
  • 90 天期限重大變更 — 版本發佈日期 90 天之後會生效的變更和淘汰項目。

新功能、變更項目和淘汰項目只會影響這個版本。90 天期限重大變更會影響所有版本。

此處並未包括重大變更，因為重大變更並非與特定版本相關聯。

圖形 API

發佈日期：2017 年 11 月 7 日 | 有效期限：2020 年 1 月 28 日 | 部落格文章

新功能

粉絲專頁

  • @Mentions — 在粉絲專頁使用 POST /comment_id/comments?message=hello @[userid]，即可公開提及（@mention）曾與貼文互動的用戶。粉絲專頁僅可提及（@mention）曾撰寫貼文或在貼文留言的用戶。

  • /page/feed — 如果連結是由發佈貼文的粉絲專頁所擁有，便不再淘汰以下 link 子欄位。若要驗證連結擁有權，請利用 url 節點上的 ownership_permissions{can_customize_link_posts} 欄位。這項動作必須使用有效的粉絲專頁存取權杖。caption 仍維持全面停用狀態。

    • description
    • name
    • picture
    • thumbnail

變更

活動

  • /event/videos — 此關係連線已移除。

一般

  • HTTPS — 我們已在 facebook.com 啟用 includeSubdomains HSTS 指令。這項指令會強制網路瀏覽器在向 facebook.com 或其任何子網域發出要求時，都必須使用 HTTPS，但不會對您應用程式所發出的圖形 API 要求造成不利影響。

粉絲專頁

  • /page — 以下關係連線現在執行特定作業時，會要求粉絲專頁存取權杖：

    • GET /page/agencies
    • GET /page/canvases
    • GET /page/instagram_accounts
    • GET /page/leadgen_forms
    • GET /page/page_backed_instagram_accounts
    • GET /page/promotable_posts
    • GET /page/userpermissions

    • POST /page/agencies
    • POST /page/page_backed_instagram_accounts
    • POST /page/userpermissions

Webhooks

  • 粉絲專頁主題 — sender_name 和 sender_id 已由 feed 訂閱中的單一 from 屬性取代。

淘汰項目

粉絲專頁

  • Conversations API — 我們已針對 /page/conversations 關係連線的 GET 作業和 Webhooks 粉絲專頁主題的 messages 欄位，淘汰 thread_key 和 thread_id 欄位。

Webhooks

  • 用戶主題 — 以下欄位已淘汰，請改為使用其 _https 同等欄位。

    • pic
    • pic_big
    • pic_small
    • pic_square
    • picture

90 天期限重大變更

  • Mobile Hosting API — /app/app_link_hosts 關係連線的 POST 作業將遭到淘汰，網頁型應用程式連結工具也將遭到移除，不過既有應用程式連結的 GET 作業將繼續正常運作。

社團

  • /group/videos — 此關係連線現在會要求具備 user_managed_groups 或 user_groups 權限的用戶存取權杖才能傳回影片資訊。

Messenger 開放平台

  • 內建自然語言處理 — 如果您已啟用內建自然語言處理並使用 API 為應用程式訂閱粉絲專頁，現在起必須利用 /page/nlp_configs 關係連線，針對每個新訂閱的粉絲專頁手動啟用自然語言處理。

粉絲專頁

  • /page/* — 除非是利用粉絲專頁存取權杖發出的要求，否則針對粉絲專頁所擁有的任何物件（或粉絲專頁上的任何物件）的 GET 回應將不會包含用戶資訊。只要節點和關係連線會傳回粉絲專頁所擁有物件的資料，就會受到這項變更的影響。

  • /page/insights — 此關係連線將會針對所有衡量指標要求提供所查詢粉絲專頁的粉絲專頁存取權杖。

  • /page/tabs — 只有擁有超過 2000 名粉絲的粉絲專頁，或由列入許可清單的應用程式所管理的粉絲專頁，才可使用 POST 作業建立自訂頁籤，但既有自訂頁籤不受影響。
  • /page/tagged — 此關係連線將會要求粉絲專頁存取權杖。

行銷 API

發佈日期：2017 年 11 月 7 日 | 部落格文章

新功能

企業管理平台 API 重新設計

現在有代表客戶和代理商的新關係。之前也沒有 user，所以透過 bid/userpermissions 處理對企業及其資產的所有存取和邀請，因而造成效能問題。新 API 的重點整理如下：

  • 企業範圍用戶 — 新用戶會與特定企業連結，並且具備的權限會在該企業範圍內。用戶可管理其個人檔案、權限以及與該企業相關聯的資產存取權。
  • 邀請 — 透過新端點，邀請用戶存取企業。您可在這些端點查看與更新用戶邀請的狀態。
  • 資產類別 — 將不同類型的資產分為各種類別，並為各類別提供個別端點。這會使得在讀取資產時，將結果分頁更加簡單。如果所管理的企業資產龐大，這也會減少效能問題。我們在重新設計時新增多個端點。

若要存取企業的用戶：

  • BUSINESS_ID/business_users
  • BUSINESS_ID/system_users
  • BUSINESS_ID/pending_users

若要存取已指派給用戶的資產：

  • BUSINESS_USER_ID/assigned_pages
  • BUSINESS_USER_ID/assigned_ad_accounts
  • BUSINESS_USER_ID/assigned_product_catalogs
  • SYSTEM_USER_ID/assigned_pages
  • SYSTEM_USER_ID/assigned_ad_accounts
  • SYSTEM_USER_ID/assigned_product_catalogs
  • PENDING_USER_ID/assigned_pages
  • PENDING_USER_ID/assigned_ad_accounts
  • PENDING_USER_ID/assigned_product_catalogs

若要存取企業粉絲專頁：

  • BUSINESS_ID/owned_pages — 取得企業擁有的粉絲專頁清單
  • BUSINESS_ID/client_pages — 取得企業客戶的粉絲專頁清單
  • BUSINESS_ID/pending_owned_pages — 取得企業所擁有、但等待批准的粉絲專頁清單
  • BUSINESS_ID/pending_client_pages — 取得屬於企業客戶、但等待批准的粉絲專頁清單

若要存取企業廣告帳號：

  • BUSINESS_ID/owned_ad_accounts — 取得企業擁有的廣告帳號清單
  • BUSINESS_ID/client_ad_accounts — 取得企業客戶的廣告帳號清單
  • BUSINESS_ID/pending_owned_ad_accounts — 取得企業所擁有、但等待批准的廣告帳號清單
  • BUSINESS_ID/pending_client_ad_accounts — 取得屬於企業客戶、但等待批准的廣告帳號清單

若要存取企業產品目錄：

  • BUSINESS_ID/owned_product_catalogs — 取得企業擁有的產品目錄清單
  • BUSINESS_ID/client_product_catalogs — 取得屬於企業客戶的產品目錄清單

若要存取企業應用程式：

  • BUSINESS_ID/owned_apps — 取得企業擁有的應用程式清單
  • BUSINESS_ID/client_apps — 取得企業客戶的應用程式清單
  • BUSINESS_ID/pending_client_apps — 取得屬於企業客戶、但等待批准的應用程式清單

如需更多資訊，請參閱企業管理平台 API、企業管理平台系統用戶、企業資產管理 API 及企業管理平台 API 最佳作法。

您現在可在建立輪播廣告時，附加會顯示即時位置的附件。請在 AD_CREATIVE_ID/object_story_spec 的 place_data 中新增選項 type=REALTIME 和 location_source_id = PAGE_ID。 這適用於以下項目的 object_story_spec 欄位：

  • POST /AD_ACCOUNT_ID/adcreatives
  • GET CREATIVE_ID

來店客流量的地理位置目標設定

您現在可將目標設定在超出商家地點特定半徑範圍的地理位置。建立廣告組合時，如果以來店客流量為目標，我們在 targeting_specs 欄位中新增 geo_locations 參數。這項功能僅供部分地區廣告商使用，請聯絡 Facebook 代表取得使用權。 請參閱來店客流量目標。

  • POST AD_ACCOUNT_ID/adsets 有新選項。
  • 支援目標設定規格：位置中的所有地理區域，但 country_groups 和 travel_in 地點類型目標設定除外。
  • 建立以 STORE_VISITS 為目標的廣告僅供部分廣告商使用，請參閱來店客流量。

廣告組合的目的地類型

這代表廣告連結的目的地類型；也就是當用戶點擊廣告或廣告中的行動呼籲時，所前往的位置。這可為廣告組合中的所有廣告提供一致的目的地類型，讓廣告僅包含不同類型的廣告創意。請參閱廣告組合：目的地類型。

  • 針對廣告組合新增 destination_type
  • 適用於 /ADSET_ID

關鍵績效指標

在 AD_ACCOUNT_ID/CAMPAIGN_ID 新增欄位 kpi_type，以說明要在行銷活動或行銷活動的廣告物件中追蹤的關鍵績效指標類型。若要按照 kpi_results 中的 kpi_type 查看洞察報告資料，請發出以下呼叫：

  • GET CAMPAIGN_ID/insights
  • GET ADSET_ID/insights
  • GET AD_ID/insights

如需更多資訊，請參閱廣告行銷活動參考資料。

重大變更

廣告管理

  • 作廢廣告目標設定right_hand_column — 如果 AD_ACCOUNT_ID/adsets 的 right_hand_column 包含無效廣告創意，廣告目標設定在這個位置會傳回錯誤。我們不允許影片、精選集或全螢幕互動廣告格式僅使用 right_hand_column 版位。只有單一圖像和輪播格式可僅使用 right_hand_column 版位。

  • 變更GET VERSION/RF_PREDICTION_ID/pause_periods — 現在會傳回 Array，而不是 String，讓處理更加簡單。

企業管理平台 API

  • 重新命名欄位 — admin_system_user 欄位已重新命名為 admin，system_user 欄位已重新命名為 employee。這會影響以下關係連線：

    • /{business-id}/userpermissions
    • /{business-id}/system_users

淘汰項目

廣告管理

已淘汰 VIDEO_VIEWS 最佳化 — 目標為 VIDEO_VIEWS 的行銷活動無法再使用 CLICKS、IMPRESSIONS、PAGE_ENGAGEMENT、POST_ENGAGEMENT 或 REACH 為最佳化目標：

  • 建立廣告組合時，如果指定這些為最佳化目標，會傳回錯誤。
  • 複製以 REACH 為最佳化目標的廣告組合時，最佳化目標會自動轉換為 VIDEO_VIEWS。
  • 複製以 CLICKS、IMPRESSIONS、PAGE_ENGAGEMENT 或 POST_ENGAGEMENT 為最佳化目標的廣告組合時，會傳回錯誤。這是因為建立或複製既有廣告組合中的廣告時，會嘗試重複使用這些最佳化目標。

這項變更會影響以下關係連線：

  • POST ACCOUNT_ID/adsets
  • POST AD_ACCOUNT_ID/ads
  • POST CAMPAIGN_ID/copies
  • POST ADSET_ID/copies
  • POST AD_ID/copies

已淘汰reach — 做為品牌知名度目標的 optimization_goal。已從 /adset 移除，僅適用於廣告回想最佳化。這樣可避免用戶在使用觸及人數為專屬目標時產生疑惑。

已淘汰最佳化BRAND_AWARENESS — 已由 AD_RECALL_LIFT 取代。用於反映更有效率的新廣告投遞模式。新的最佳化目標支援混合廣告創意，例如靜態和影片廣告在同一廣告組合中，也支援手動出價。BRAND_AWARENESS 不再適用於以下項目：

  • POST /ADSET_ID
  • GET /ADSET_ID
  • POST /AD_ACCOUNT_ID/adsets

已淘汰frequency_cap — 包括以下項目的 lifetime_frequency_cap 和 frequency_cap_reset_period 欄位：

  • POST AD_ACCOUNT_ID/adsets
  • GET /ADSET_ID
  • POST /ADSET_ID

請改用 frequency_control_specs。

已淘汰每次動作成本的POST_ENGAGEMENT — 對於這個目標，您無法再使用 POST_ENGAGEMENT 做為 billing_event。如此會使得廣告投遞和成效衡量更為契合。影響的端點為：/AD_SET_ID。

廣告洞察報告與成效衡量

已淘汰以下項目的 video_15_sec_watched_actions：

  • GET AD_ACCOUNT_ID/insights
  • GET CAMPAIGN_ID/insights
  • GET ADSET_ID/insights
  • GET AD_ID/insights
  • POST AD_ACCOUNT_ID/insights
  • POST CAMPAIGN_ID/insights
  • POST ADSET_ID/insights
  • POST AD_ID/insights

已淘汰recurrence_value — 從進階成效衡量 API 中淘汰。這個欄位過去在 Atlas API 中稱為分析報告排程。已由 recurrence_values 取代。請參閱進階成效衡量：分析報告排程。

企業管理平台

因重新設計企業管理平台 API 所淘汰的端點：

  • BUSINESS_ID/userpermissions
  • BUSINESS_ID/business_persona
  • business_persona_id

已淘汰用於管理資產相關端點：

  • BUSINESS_ID/pages
  • BUSINESS_ID/adaccounts
  • BUSINESS_ID/product_catalogs
  • BUSINESS_ID/apps

若要存取資產，請使用 BUSINESS_ID/owned_ASSET 或 BUSINESS_ID/client_ASSET

已淘汰用於管理屬於其他企業的資產相關端點：

  • BUSINESS_ID/assigned_ad_accounts
  • BUSINESS_ID/assigned_pages
  • BUSINESS_ID/assigned_product_catalogs

改用 BUSINESS_USER_ID/assigned_ASSET

即刻淘汰項目

這些淘汰項目會影響所有 API 版本，並於 2017 年 11 月 14 日生效。

活動廣告和連結廣告

已淘汰：建立與編輯未與有效粉絲專頁連結的活動廣告或連結廣告。以下格式不再有效，會傳回錯誤。

要淘汰的簽章：

  • 活動廣告
    • 目標：EVENT_RESPONSES
    • 廣告創意欄位：body、object_id
  • 連結廣告
    • 目標：LINK_CLICKS
    • 廣告創意欄位：title、body、object_url（image_file 或 image_hash）

支援的簽章

  • 活動廣告
    • 目標：EVENT_RESPONSES
    • 廣告創意欄位：object_story_id 或 object_story_spec
  • 連結廣告
    • 目標：LINK_CLICKS
    • 廣告創意欄位：object_story_id 或 object_story_spec

先前建立的既有活動廣告和連結廣告可繼續刊登，但這項變更一旦生效，您便無法修改這些廣告的廣告創意或建立新廣告，否則將會傳回錯誤。請參閱活動廣告和本地廣告及廣告參考資料。