行銷 API

版本控制

目前的行銷 API 版本是 v19.0。

Facebook 的平台具備核心與延伸版本控制模式。透過行銷 API 版本控制，所有重大變更都會是新版本。多個版本的行銷 API 或 SDK 可同時存在，並保留各版本中的不同功能。

開發人員應事先瞭解行銷 API 或 SDK 何時會變更。您有 90 天期間來採納變更，而改用新版本的方式和時機則由您決定。

版本時程

行銷 API 推出新版本後，我們會繼續支援前一版的行銷 API 至少 90 天。您有至少 90 天的寛限期轉移到新版本。在這 90 天的寛限期，目前版本和淘汰版本皆可供您呼叫，而且您有 90 天的寛限期轉移到新版本。90 天的寛限期結束後，淘汰版本將停止運作。版本一旦停止運作，對該版本號碼發出的任何呼叫可能會失敗，或自動升級到下一個可用版本。

例如，行銷 API 17.0 版於 2023 年 5 月 23 日發行，行銷 API 16.0 版於 2024 年 2 月 6 日到期，這提供了至少 90 天的時間可以轉移到新版本。

以下舉例說明時間表。請注意，我們不一定會在舊版淘汰的 90 天寛限期結束時推出新版本。在此範例中，16.0 版在 18.0 版發行前的某個時間淘汰：

至於 SDK，因為是可下載的套件，所以會維持提供一個可用版本。不過，SDK 在生命週期結束後，運作時可能須依賴已停用的行銷 API 或方法，因此您應假設生命週期結束的 SDK 無法運作。

發出版本控制要求

所有行銷 API 端點都可透過指定版本路徑使用，在要求路徑的開頭前面加上版本即可。例如：

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

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

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

其中 n 是所需版本。請參閱變更紀錄中可用版本的完整清單。我們所有的行銷 API 參考資料都提供每個版本的資訊。

移轉

無法透過版本控制進行必要變更時，只能使用移轉來處理這種特殊情況，通常發生在基礎資料模型有所變更時。移轉會套用至所有版本。

我們的移轉頁面會列出目前仍在進行中的所有移轉。移轉會提供至少 90 天的期間，您必須在此期間移轉您的應用程式。這個期間開始後，新的應用程式就會預設採用移轉後行為。當移轉期間結束後，移轉前行為就完全不可用。

透過圖形 API 管理移轉

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

您可對關係連線發出更新呼叫，藉此啟用及停用移轉。

透過應用程式主控板管理移轉

您可在應用程式主控板的設定 > 移轉下方，啟用及停用可用的移轉。請注意，移轉清單可能與下圖不同，因為不同的應用程式在不同時間會有不同的可用移轉。如果您看到 Use Graph API v2.0 by default 移轉，這僅適用於圖形 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 日，系統將停用 17.0 版。根據 18.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 日 17.0 版停用後，使用它呼叫 POST /{adset-id}，此 API 要求將失敗，因為自動升級不適用於受下一個可用版本（18.0 版）影響的端點。

如果您的應用程式在 17.0 版停用後，使用它呼叫 GET /{ad-account-id}/insights，平台會將您的呼叫升級到下一個可用版本（18.0 版）。

注意：如果您的應用程式已使用 17.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''
永久連結