推廣 API

版本控制

推廣 API 的目前版本是 v21.0。

Facebook 的平台設有核心和延展版本控制模式。透過推廣 API 版本控制，所有重大變更都將納入新版本中。多個版本的推廣 API 或 SDK 可同時存在，而每個版本的功能均有所不同。

開發人員應事先了解推廣 API 或 SDK 的變更時間。雖然您只有 90 天的期限來採用變更，但您可以自行決定轉移至新版本的方式與時間。

版本時間表

新版本的推廣 API 發佈後，我們會繼續支援舊版推廣 API 最少 90 天。您有最少 90 天寬限期轉移至新版本。在 90 天的寬限期內，您可以呼叫目前版本或已停用版本的 API，並有 90 天寬限期轉移至新版本。90 天寬限期之後，已停用版本會停止運作。一旦某個版本變為不可用，對該版本號碼執行的任何呼叫都可能會失敗，或者由系統升級為對下一個可用版本執行。

舉例來說，推廣 API v17.0 在 2023 年 5 月 23 日發佈，而推廣 API v16.0 在 2024 年 2 月 6 日過期，中間有最少 90 天時間可轉移至新版本。

以下是時間線範例。請注意，我們未必會在上一個版本停用 90 天寬限期後推出新版本。在範例中，v16.0 是在 v18.0 推出前不久才停用：

由於 SDK 是可下載的套件，因此各版本隨時適用。不過，在過了失效日期後，SDK 所依賴的推廣 API 或方法就可能無法正常運作，所以您只能假設到期的 SDK 也無法正常運作。

發出指定版本的要求

您可以透過指定版本路徑使用所有推廣 API 端點，只需在要求路徑開頭加上版本編號即可。例如：

curl -G \
-d "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/v21.0/me/adaccounts"

所有版本都適用，一般形式如下：

https://graph.facebook.com/v{n}/{request-path}

其中 n 是所需版本。請參閱變更記錄，查看可用版本的完整清單。所有推廣 API 參考資料均就每個版本提供相關資訊。

轉移

轉移只適用於某些特殊情況：需要作出的變更無法進入版本控制流程。一般而言，這通常是在基礎數據模式變更時才會用到。轉移適用於所有版本。

轉移頁面列有目前仍在進行中的轉移項目。轉移至少會提供 90 天的期限，您必須在此期間完成應用程式轉移。期間起算後，遷移後的行為模式將成為新應用程式的預設設定。轉移期限結束後，轉移前的行為將無法再用。

透過 Graph API 管理轉移

您可透過 /app 節點中的轉移欄位管理轉移：

您可以在關係連線節點執行更新呼叫來啟用和註銷轉移。

透過應用程式管理中心管理轉移

您可以在應用程式管理中心的設定 > 轉移下啟用和停用可用的轉移。請注意，您實際看到的轉移清單可能與下圖不同，因為可用轉移會因應不同應用程式和時間而異。如果看到轉移項目 Use Graph API v2.0 by default，這適用於 Graph API 而非推廣 API。

在用戶端臨時啟用轉移

除了在應用程式管理中心或透過推廣 API 啟用轉移，您也可以改為在推廣 API 呼叫中新增一個特殊標示，以便啟用轉移。這個標示稱為 migrations_override，當中要求您指定一個 JSON blob，來描述您要開啟或關閉的轉移項目。舉例來說，如果您想執行原始呼叫，則可以傳送：

http://graph.facebook.com/path?
  migrations_override={"migration1":true, "migration2":false}

有了這種方法，您便可以透過用戶端更新來呼叫新的推廣 API，而不必讓所有呼叫方同時更新以呼叫新的推廣 API。這種方法也非常適用於除錯。

這些轉移項目的名稱可在上述提及的 /app 節點找到。

版本自動升級功能

由於推廣 API 版本快速輪換，大約每四個月輪換一次，我們正在簡化升級流程。自 2024 年 5 月起，我們會為不受版本變更影響的推廣 API 端點啟用自動版本升級功能。這就代表，在要停用的版本與下一個可用版本之間，如果某個端點不受影響，平台會升級呼叫，改為對下一個可用版本執行呼叫，而不是直接表示要求失敗。這項變更旨在確保提供更順暢、更有效率的 API 體驗。

例如，在 2024 年 5 月 14 日，v17.0 會停用。根據 v18.0 變更記錄，以下端點會受影響：

  • POST /act_{ad-account-id}/reachfrequencypredictions
  • GET /act_{ad-account-id}/reachestimate
  • GET /act_{ad-account-id}/delivery_estimate
  • POST /act_{ad-account-id}/adsets
  • POST /{adset-id}
  • POST /act_{ad-account-id}/saved_audiences
  • POST /{saved-audience-id}
  • POST /act_{ad-account-id}/credit_cards

如果您的應用程式在 2024 年 5 月 14 日 v17.0 停用後向 v17.0 執行 POST /{adset-id} 呼叫，此 API 要求會失敗，因為自動升級功能不適用於受下一個可用版本（v18.0）影響的端點。

如果在 v17.0 停用後，應用程式向 v17.0 執行 GET /{ad-account-id}/insights 呼叫，平台會升級呼叫，改為對下一個可用版本（v18.0）執行呼叫。

請注意：如果應用程式已有向高於 v17.0 的版本執行呼叫，則在版本停用當天應不會有任何變更。

如要查看在各版本中受影響的端點，請參閱推廣 API 變更記錄。

常見問題

版本時間表

We refer to this as an unversioned call. Unversioned calls are invalid and will fail when made against Marketing API endpoints.

固定連結

You can call the version of the Marketing API that was the latest available when the app was created, as long as it has not been deprecated. It can also make calls to any newer, undeprecated versions launched after the app is created.

Starting May 14, 2024, if a deprecated version is provided, the platform may upgrade selected endpoints to the next available version instead of failing the request. To learn more about the behavior, refer to Marketing API Auto-version upgrade.

For example:

  • If your app was created before the launch of v17.0, while v16.0 was available, then it will be able to make calls to v16.0 until the expiration date of that version. After v16.0 has been deprecated, calls to v16.0 will fail.
  • If your app was created after v17.0 was released, it will be able to make calls to v17.0 until the expiration date of that version, and any subsequent versions (v18.0, etc) until their expiration dates. After v17.0 has been deprecated, calls to v17.0 will fail.
  • Your app will not be able to make calls to v16.0, since 1) that was before your app was created and 2) that version is deprecated and calls to v16.0 may fail or be upgraded to the next available version.

If an app was not used - to make any Marketing API calls or requests - after being created, it will not have the ability to use those versions if any newer version is launched. Here's another example to explain this:

  • If your app was created while v16.0 was the latest version available, but not used until after v17.0 had launched, it will only be to use v17.0, and not v16.0.
  • If your app was created while v16.0 was the latest version available, and then used before v17.0 had launched, it will still be able to use v16.0 even after the launch of v17.0.
固定連結

There are a few differences between how Marketing API and the rest of Graph API. For the details on Platform API versioning, see Graph API, Versioning.

  1. Marketing API is versioned on a 90-day deprecation schedule, whereas Platform API has core and extended APIs with a 2 year guarantee for core APIs.
  2. Marketing API does not support unversioned calls. If you do not specify a working version in your call, it fails.
固定連結

發出指定版本的要求

With migrations, you set migration on or off in App Dashboard, as described in the Migrations section. With versioning, we are making Marketing API functionality more transparent by moving the setting into the endpoint:

https://graph.facebook.com/v{n}/{request-path}

You can know what behavior to expect out without having to manually visit your app's migration panel.

固定連結

版本自動升級功能

The upgrade will apply on any deprecated version to the next available version. This means hypothetically if your app is making calls to v15.0 after v16.0 is deprecated, the call will also be upgraded to v17.0 if the endpoint is not listed as affected endpoint on both v16.0 and v17.0.

固定連結

No. We highly encourage developers to perform version upgrades before a version gets deprecated for the following reasons

  • You may still need to manually upgrade endpoints being impacted by next version.
  • You might want to upgrade to newer versions to benefit from new features instead of the lowest available version.
固定連結

You can look up affected endpoints from Marketing API Changelog.

固定連結

You can disable the version auto-upgrade via the Marketing API Version setting under Marketing API App Product Page > Settings.

固定連結

If an API call targets a version that has been deprecated and has been automatically upgraded, an API response header is included for any call that has been auto-upgraded.

Example notification header

X-Ad-Api-Version-Warning: 'X-Ad-Api-Version-Warning: 'The call has been auto-upgraded to vXXX as vXXX has been deprecated''
固定連結