市场营销 API

版本管理

市场营销 API 的当前版本是 v19.0。

Facebook 开放平台拥有核心和扩展版本管理模式。通过市场营销 API 版本管理，所有重要更改都将纳入新版本中。市场营销 API 或 SDK 可同时存在多个版本，每个版本的功能有所不同。

开发者应提前了解市场营销 API 或 SDK 的更改时间。虽然我们为您提供 90 天的窗口期来采用更改，但转移到新版本的方式和时间仍由您自行选择。

版本计划

发布市场营销 API 新版本后，我们会继续支持市场营销 API 的上一个版本，支持时间至少为 90 天。您有至少 90 天的宽限期来逐步向新版本过渡。在 90 天宽限期内，您既可以调用当前版本的 API，也可以调用已停用的上一个版本 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/v19.0/me/adaccounts"

以下一般格式适用于所有版本：

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

其中 n 是所需的版本号。您可以访问我们的更新日志，查看可用版本的完整列表。所有市场营销 API 参考文档都会提供对应版本的信息。

迁移

迁移仅适用于某些特殊情况，如需要作出的更改无法进入版本管理流程。通常是在基础数据模型有所变更的情况下。迁移适用于所有版本。

如需了解目前正在执行的迁移，请参阅我们的迁移页面。迁移至少会提供 90 天的窗口期，您必须在这段时间内完成应用迁移。窗口期启动后，迁移后的行为将成为新应用的默认行为。迁移窗口期结束后，迁移前的行为将不再可用。

通过图谱 API 管理迁移

您可以通过 /app 节点中的 migrations 字段管理迁移：

您可以对连线发出更新调用，以启用或停用迁移。

通过应用面板管理迁移

您可以在应用面板的设置 > 迁移下启用和停用可用的迁移。请注意，您实际看到的迁移列表可能与下图不同，因为可用迁移视应用和时间而异。如果您看见 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 日，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 的版本执行调用，在 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''
固定链接