首页
博客
隆重推出图谱 API v25.0 和市场营销 API v25.0

2026年2月18日

隆重推出图谱 API v25.0 和市场营销 API v25.0

发布者 Manjari Jain

下文介绍 v25 版本中全新图谱 API/市场营销 API 变更的亮点。请访问我们的更新日志，获取完整的变更列表和详细信息。

常规更新

图谱 API：隆重推出“公共主页浏览人数”指标

截至 2026 年 6 月底，我们计划在图谱 API 中引入“公共主页浏览人数”指标。“浏览人数”指标旨在替代旧的“覆盖人数”指标，为跨平台成效衡量（Facebook 和 Instagram）提供一致的标准，以统计看过某内容的用户数量。开发者应着手规划向“浏览人数”指标的迁移，以确保继续获取受众分析。

变更内容

公共主页成效分析和快拍成效分析中将提供“浏览人数”指标

帖子/公共主页成效分析

  • GET {page-id}/insights/page_total_media_view_unique*
  • GET {post-id}/insights/post_total_media_view_unique*

快拍成效分析

  • 系统将添加新指标
  • GET {stories-id}/insights/metric
    • PAGE_STORY_TOTAL_MEDIA_VIEW_UNIQUE

上述图谱 API 将在 v25 版本发布后可用，我们建议开发者查看图谱 API 更新日志以获取最新信息。

Webhook mTLS 证书更新

自 2026 年 3 月 31 日起，Meta 将开始使用归 Meta 所有的另一家认证机构 (CA) 来签署 Webhook mTLS 证书。

这对开发者而言意味着什么？

如果将您的服务器配置为要求并验证 Webhook mTLS 证书，则您必须信任这家新的 Meta 认证机构。若未在截止日期之前更新信任库，会导致 TLS 握手失败，并且您的服务器会停止接收所有 Webhook 事件。

需要采取操作：更新信任库

为确保不中断地接收 Webhook，您必须

  1. 下载 Meta 根 CA 证书：前往开始使用 Webhook 并下载名为 meta-outbound-api-ca-2025-12.pem 的文件。
    根 CA 将对叶证书进行签名，该证书将在 Webhook 请求中展示。
  2. 将证书添加到信任库：将此证书添加到所有接收 Webhook 的服务器的信任库中。
  3. 保留当前证书：您应该在当前证书仍有效时，将新的证书添加至信任库中。

重要提示：切勿等到截止日期才来进行操作。您应立即将新证书添加到信任库，确保在 3 月 31 日实现无缝切换。

截止日期：2026 年 3 月 31 日之前。

变更原因

当前的 Webhook mTLS 证书由 DigiCert 根 CA 签名。由于 DigiCert 将弃用客户身份验证 EKU，因此无法使用此根 CA 续期证书，该证书已于 2025 年 4 月 15 日过期。

因此，新的 Webhook mTLS 证书将由 Meta 内部根 CA 签名。该证书将与当前证书保持相同的通用名称 (client.webhooks.fbclientcerts.com)。

Webhook mTLS 的公开文档已更新，并附有关于此变更的通知。完整技术细节将在 2026 年 4 月过渡完成后永久更新至文档中。

停用及重大变更

针对广告成效分析异步 API 提供的增强版错误消息

我们始终致力于通过 API 改善开发者体验。为了提高透明度，帮助开发者构建更稳定的应用程序，我们针对广告成效分析异步 API GET {AD_REPORT_RUN_ID} 端点的错误报告进行了升级。

自 2026 年 2 月 18 日发布的图谱 API v25.0 版本起，当异步报告失败时，开发者将可获取详细错误信息，从而更轻松地诊断故障并提升其 API 集成效率。对于当前有权访问 error_code 字段的任何开发者，该类型将从 uint 更改为 int。

变更内容

我们将在所有应用程序的广告成效分析异步 API GET {AD_REPORT_RUN_ID} 端点的响应中引入以下新的默认字段：

  • error_code：错误代码。注意：对于当前有权访问此字段的任何开发者，字段将从 uint 更改为 int
  • error_message：与 error_code 对应的消息。
  • error_subcode：错误的具体子代码。
  • error_user_title：易于用户理解的错误子代码标题。
  • error_user_msg：详细说明错误子代码的易读消息。

这些字段将在报告运行失败时被填充。建议您检查自己的 API 集成，确保其与响应中新的默认字段兼容。

此更新计划与新版图谱 API 一同发布。建议开发者查看图谱 API 更新日志，获取最新信息。开发者文档已同步更新以反映这些变更。

图谱 API：元数据查询参数已停用

自图谱 API v25 版本起，我们将停用 metadata=1 查询参数。此参数之前用于在 API 响应中返回有关节点字段和连接的元数据。由于此功能使用率较低，因此我们将其停用以简化平台架构。停用后，API 请求中将忽略 metadata 参数。

目前依赖 metadata=1 的开发者应改为使用我们的官方 API 文档来了解每种节点类型的可用字段和连接。

变更内容

更改

时间表

metadata=1 查询参数已停用

v25（2026 年 2 月）

metadata=1 查询参数已移除

2026 年 5 月

变更前（v24 及更低版本）：

在图谱 API 请求中添加 ?metadata=1 后，系统将返回有关该节点的更多元数据，包括可用字段和连接。

变更后（v25 及更高版本）：

metadata=1 参数将被忽略。包含此参数的请求将继续返回不含元数据的标准响应。不会发生任何故障或重大变更 - 如果请求中包含 metadata=1，则不会出错或中断；该参数只会不起作用。

图谱 API：“公共主页覆盖人数/展示次数”指标停用信息

2026 年 6 月，我们计划停用图谱 API 中的“帖子/公共主页覆盖人数”、“视频展示次数”和“快拍展示次数”指标。这些旧指标不再显示在我们的成效分析工具中，但在此之前仍可通过 API 获取。

为使产品与 API 统一采用一致的指标体系并提升系统整体可靠性，我们将停用这些旧版指标。停用后，开发者应迁移至新版“影音内容浏览量”和“影音内容浏览人数”指标，这些指标将取代旧版的“展示次数”、“覆盖人数”和“视频观看人数”概念。

变更内容

以下指标将于 2026 年 6 月在所有 API 版本中停用。建议开发者查看图谱 API 更新日志，获取最新信息。

帖子/公共主页覆盖人数

  • GET {page-id}/insights/page_impressions_unique*
  • GET {page-id}/insights/page_impressions_paid_unique*
  • GET {page-id}/insights/page_impressions_viral_unique*
  • GET {page-id}/insights/page_impressions_nonviral_unique*
  • GET {page-id}/insights/page_posts_impressions*
  • GET {page-id}/insights/page_posts_impressions_unique*
  • GET {page-id}/insights/page_posts_impressions_paid*
  • GET {page-id}/insights/page_posts_impressions_paid_unique*
  • GET {page-id}/insights/page_posts_impressions_organic_unique*
  • GET {page-id}/insights/page_posts_served_impressions_organic_unique*
  • GET {page-id}/insights/page_posts_impressions_viral*
  • GET {page-id}/insights/page_posts_impressions_viral_unique*
  • GET {page-id}/insights/page_posts_impressions_nonviral*
  • GET {page-id}/insights/page_posts_impressions_nonviral_unique*
  • GET {post-id}/insights/post_impressions_unique*
  • GET {post-id}/insights/post_impressions_paid_unique*
  • GET {post-id}/insights/post_impressions_fan_unique*
  • GET {post-id}/insights/post_impressions_organic_unique*
  • GET {post-id}/insights/post_impressions_viral_unique*
  • GET {post-id}/insights/post_impressions_nonviral_unique*
  • GET {post-id}/insights/post_impressions_nonviral_unique*

视频展示次数

  • GET {video-id}/video_insights/post_impressions_unique
  • GET {video-id}/video_insights/total_video_impressions
  • GET {video-id}/video_insights/total_video_impressions_unique
  • GET {video-id}/video_insights/total_video_impressions_paid_unique
  • GET {video-id}/video_insights/total_video_impressions_paid
  • GET {video-id}/video_insights/total_video_impressions_organic_unique
  • GET {video-id}/video_insights/total_video_impressions_organic
  • GET {video-id}/video_insights/total_video_impressions_viral_unique
  • GET {video-id}/video_insights/total_video_impressions_viral
  • GET {video-id}/video_insights/total_video_impressions_fan_unique
  • GET {video-id}/video_insights/total_video_impressions_fan
  • GET {video-id}/video_insights/total_video_impressions_fan_paid_unique
  • GET {video-id}/video_insights/total_video_impressions_fan_paid

快拍展示次数

  • 两个指标将被替换
  • GET {stories-id}/insights/metric
    • PAGE_STORY_IMPRESSIONS_BY_STORY_ID
    • PAGE_STORY_IMPRESSIONS_BY_STORY_ID_UNIQUE

建议使用以下替代指标：

  • GET {page-id}/insights/page_total_media_view_unique
  • GET {post-id}/insights/post_total_media_view_unique

具体来说，对于付费覆盖人数和自然覆盖人数的细分数据，建议使用以下指标，这些指标可以提供大致相似的成效分析：

  • GET {page-id}/insights/page_media_view
  • GET {post-id}/insights/post_media_view

图谱 API：“观看视频达 3 秒的观众人数”指标停用信息

我们计划于 2026 年 6 月停用“观看视频达 3 秒的观众人数”指标。这些旧指标不再显示在我们的成效分析工具中，但在此之前仍可通过图谱 API 获取。

为使产品与 API 统一采用一致的指标体系并提升系统整体可靠性，我们将停用这些旧版指标。停用后，开发者应迁移至新版“影音内容浏览量”和“影音内容浏览人数”指标，这些指标将取代旧版的“展示次数”、“覆盖人数”和“视频观看人数”概念。

变更内容

以下指标将于 2026 年 6 月在所有 API 版本中停用。建议开发者查看图谱 API 更新日志，获取最新信息。

  • GET {page-id}/insights/page_video_views_unique
  • GET {post-id}/insights/post_video_views_organic_unique
  • GET {post-id}/insights/post_video_views_paid_unique
  • GET {post-id}/insights/post_video_views_unique
  • GET {video-id}/video_insights/total_video_views_organic_unique
  • GET {video-id}/video_insights/total_video_views_paid_unique
  • GET {video-id}/video_insights/total_video_views_unique

建议使用以下替代指标：

  • GET {page-id}/insights/page_total_media_view_unique
  • GET {post-id}/insights/post_total_media_view_unique

具体来说，对于付费观看视频达 3 秒的观众人数和自然观看视频达 3 秒的观众人数的细分数据，建议使用以下指标，这些指标可以提供大致相似的成效分析：

  • GET {page-id}/insights/page_media_view
  • GET {post-id}/insights/post_media_view

市场营销 API：ASC 和 AAC 停用信息

自动化统一方案将推动应用、销量和潜在客户类广告系列默认采用最佳的自动化优先进阶赋能型设置，帮助广告主与合作伙伴更便捷地使用 Meta 最新、效果最优的自动化产品。我们正在逐步停用旧版 API，并引导市场营销 API 开发者迁移至新版自动化的统一进阶赋能型设置。

自 v25.0 版本起（2026 年 2 月 18 日），进阶赋能型智能购物广告 (ASC) 和进阶赋能型应用广告 (AAC) 将无法再通过市场营销 API 创建或更新。此变更将于 90 天后（2026 年 5 月 19 日）扩展至所有市场营销 API 版本。

在 v26.0 版本中（预计 2026 年 9 月发布），所有剩余的 ASC 和 AAC 广告将暂停投放。

使用“现有客户预算限额 (ECBC)”的 ASC 或 AAC 广告在 v26.0 版本之前将保持可编辑状态，此功能不适用于进阶赋能型广告系列。在 v26.0 版本发布之前，拥有 ECBC 广告的开发者应使用以下方法之一来复制 ECBC 广告：

  • 手动复制：在广告管理工具中打开使用 ECBC 的现有 ASC/AAC 广告，系统将提示您“复制广告”。只需单击一下，即可创建新的广告，其设置与现有广告完全相同。
  • 使用 API 复制 ECBC 广告，按照开发者文档中提供的指导，使用 API 复制广告，文档可点击此处获取。
  • 在广告账户层级申请批量迁移，对于有专人服务的合作伙伴，我们可以提供一次性操作，以便在约定的日期复制所有 ECBC 广告。请联系您的 Meta 联系人，并提供账户编号和首选迁移日期。

注意：所有 ECBC 广告复制操作都将生成新的广告编号。

此更改会影响以下端点：

  • POST /{campaign-id}
  • POST /{campaign-id}/copies

请查看更新版开发者文档和常见问题，了解此项变更的所有详情。

开发者文档链接

功能帮助文章链接

API 版本停用信息：

作为 Facebook 图谱 API 和市场营销 API 版本计划的一部分，请注意近期的停用信息：

图谱 API

  • 2026 年 5 月 21 日：图谱 API v.19 将被停用并从平台中移除。
  • 2026 年 9 月 24 日：图谱 API v.20 将被停用并从平台中移除。

为避免业务出现中断，我们建议您将所有调用迁移到今天发布的最新 API 版本。


标签

业务工具开发者工具图谱 API市场营销 API

探索更多

2025年5月29日

Introducing Graph API v23.0 and Marketing API v23.0

2025年1月21日

Introducing Graph API v22.0 and Marketing API v22.0

2024年5月21日

Introducing Graph API v20.0 and Marketing API v20.0

获取电子简报

订阅以接收 Meta 开发者每月动态。

立即订阅