版本说明

本页提供了 AdSense Management API 的版本说明。

版本 2

此版本引入了以下变更，旨在移除已弃用的功能，并使 AdSense Management API 符合当前的 Google API 标准。根据 Google API 版本控制方案，此版本会随着时间的推移而更新，以包含更多（向后兼容的）功能，而不是在新次要版本中发布新功能。

2025-10-02

报告

• 添加了 TRAFFIC_SOURCE 维度，可按流量来源（例如“Google”“Bing”“Facebook”“其他”）细分指标。如需了解详情，请参阅流量来源细分。

2025-05-06

PolicyIssues

• 已弃用的 policyTopics[].must_fix 字段（请参阅之前的更新）现在将始终设置为 false。

2025-02-24

PolicyIssues

• 添加了 policyTopics[].type 字段，用于标识政策主题是政策问题、监管问题还是广告客户偏好设置问题。 这会替换 policyTopics[].must_fix，后者现已标记为已弃用的字段。

2024-04-03

PolicyIssues

• 添加了一个新集合，用于报告账号当前存在的违规和警告情况。

2023-06-19

支付

• payments.list 现在会返回有关优质发布商付款的详细信息。

2023-06-13

报告

• 添加了 FUNNEL_REQUESTS、FUNNEL_IMPRESSIONS、FUNNEL_CLICKS 和 FUNNEL_RPM 指标，这些指标可提供有关非广告单元（例如相关搜索单元）效果的信息。

2023-03-30

报告

• 添加了 PAGE_URL 维度，可按网页网址细分指标（但有一些注意事项，请参阅网页网址细分）。

2022-09-21

AdUnits

• 添加了创建和修补方法。请注意，这些方法只能由已启用 AdSense for Platforms 产品的项目使用。

CustomChannels

• 添加了 create、patch 和 update 方法。请注意，这些方法只能由已启用 AdSense for Platforms 产品的项目使用。
• 向资源添加了 active 字段。

账号

• 添加了 getAdBlockingRecoveryTag 方法。

2022-08-25

报告

• 添加了 HOSTED_AD_CLIENT_ID 维度，以便主发布商和平台发布商按其发布商账号（主发布商）和子账号（平台发布商）细分指标。

2022-05-03

AdClient

• 添加了 get 方法。

报告

• 添加了 getSaved 方法。

UrlChannels

• 添加了 get 方法。

2022-03-31

账号

• API 现在会返回非活跃账号，并使用 state 字段指明账号的状态。

AdClient

• 与账号变更类似，API 现在会返回不活跃的广告客户，并使用 state 字段指明广告客户的状态。

2022-02-24

付款

• 资源名称格式已扩展，可支持 YouTube 收入的单独资源。此变更是在面向 YouTube 创作者逐步推出改进版 AdSense 体验之前进行的，届时 YouTube 收入将单独存入其自己的收款账号。如果您有专门用于接收 YouTube 收入的收款账号，那么付款列表方法也会返回 YouTube 付款信息。 YouTube 收入将采用以下资源名称格式：
  • accounts/{account}/payments/youtube-unpaid，用于未付（当前）YouTube 收入。
  • accounts/{account}/payments/youtube-yyyy-MM-dd，用于支付 YouTube 收入。
  
  注意：AdSense 收入的资源名称保持不变：
  • accounts/{account}/payments/unpaid，用于获取未付（当前）AdSense 收入。
  • accounts/{account}/payments/yyyy-MM-dd，用于已支付的 AdSense 收入。

2021-06-30

举报

• 添加了维度 AD_FORMAT_NAME 和 AD_FORMAT_CODE，用于指明在您的网站上向用户展示广告的方式（网页内广告、穿插广告等）。请注意，v1.4 具有（已弃用）名称相同但成员不同的维度；v2 中添加的两个维度与 v1.4 中存在的维度不同。

2021-04-19（初始版本）

常规

• 移除了 v1.4 中的所有已弃用的方法。这包括不需要 accountId 的资源方法。在 v2 中，accountId 在 parent 字段中指定。
• 根据 Google API 标准，资源现在由 name 字段标识。例如，AdClient 的名称将类似于 accounts/{accountId}/adclients/{adClientId}。此外，在 v1.4 中，资源 ID 用作报告维度，但在 v2 中，该值现在可通过多个资源上的 reporting_dimension_id 字段获得。
• kind 字段已从所有资源中移除。

账号

• name 字段已更改为 display_name。
• timezone 字段已从字符串更改为 google.type.TimeZone。
• creation_time 字段（类型为 int64）已更改为 create_time（类型为 google.protobuf.Timestamp）。
• 添加了 pending_tasks 字段，该字段是一个未完成任务的列表，这些任务需要在新账号的注册过程中完成。例如，任务可能与您的结算资料或电话号码验证有关。
• sub_accounts 字段已移除。在 v2 中，可以使用 listChildAccounts 自定义方法实现类似的功能。通过以递归方式调用 listChildAccounts，可以在 v2 中生成完整的子账号树。

AdClient

• 移除了 arc_opt_in 字段，因为该字段已从 AdSense 界面中移除。
• supports_reporting 字段替换为 reporting_dimension_id 字段，后者表示广告客户的唯一 ID，与 AD_CLIENT_ID 报告维度中使用的 ID 相同。如果 reporting_dimension_id 为空，则表示 AdClient 不支持报告。

AdUnit

• status 字段已重命名为 state。 此外，ACTIVE 状态不再表示相应广告单元在过去 7 天内是否有活动。在 v2 中，表示广告单元已由用户激活，可以投放广告。
• code 字段已移除。此值仍可在 name 字段的末尾（最后一个正斜杠之后）找到。
• 已移除 contentAdsSettings.backupOption 字段。
• type 字段已限制为值 TYPE_UNSPECIFIED、DISPLAY、FEED、ARTICLE、MATCHED_CONTENT 和 LINK。
• AdSense 界面中已移除的其他字段也会被移除：custom_style、saved_style_id、 mobile_content_ads_settings、feed_ads_settings。

提醒

• 移除了 delete 方法。
• is_dismissible 字段已移除。
• locale 字段已重命名为 language_code。

CustomChannel

• code 字段已移除。此值仍可在 name 字段的末尾（最后一个正斜杠之后）找到。
• targeting_info 字段已被移除，因为它已从 AdSense 界面中移除。

付款

• payment_date 字段已重命名为 date，并从字符串类型更改为 google.type.Date 类型。
• payment_amount 字段和 payment_amount_currency_code 字段已合并为单个 payment 字段（例如，“1,235 日元”“1,234.57 美元”“87.65 英镑”）。

举报

• 在 v2 中，AdSense Management API 报告数据现在与 AdSense 界面保持一致。这意味着，AdMob 和 YouTube 媒体资源不再受支持。此外，该 API 仅支持追溯到 3 年前的报告数据。
• Metadata.dimensions 资源和 Metadata.metrics 资源已被移除。
• 我们添加了新方法来生成报告的 CSV 版本，取代了 v1.4 中的查询参数。注意：对于压缩，您仍然可以使用 HTTP 标头“Accept-Encoding: gzip”。
• 临时报告生成功能中的部分字段已发生变化。
  • account_id 字段已重命名为 account。
  • dimension 字段已重命名为 dimensions。
  • metric 字段已重命名为 metrics。
  • filter 字段已重命名为 filters。
  • sort 字段已重命名为 order_by。
  • locale 字段已重命名为 language_code。
  • currency 字段已重命名为 currency_code。
  • 您现在可以使用 date_range 指定多个常见范围（例如，TODAY、YESTERDAY、MONTH_TO_DATE、YEAR_TO_DATE、LAST_7_DAYS 和 LAST_30_DAYS），也可以通过将 date_range 设置为 CUSTOM 来指定 start_date 和 end_date。
  • start_date 和 end_date 字段已从字符串类型更改为 google.type.Date 类型。注意：因此，相对日期关键字（例如，“today-6d”）不再受支持。
  • 布尔值字段 use_timezone_reporting 已替换为 reporting_time_zone，后者可使用以下两个值之一：ACCOUNT_TIME_ZONE 或 GOOGLE_TIME_ZONE（表示 PST/PDT）。v2 中的默认值为 ACCOUNT_TIME_ZONE，这与 v1.4 中的默认值不同。
  • start_index 字段已移除。
  • max_results 字段已重命名为 limit。
• 已更改保存的报告生成中的某些字段。
  • 添加了日期字段（date_range、start_date、end_date、reporting_time_zone）。
  • 添加了 currency_code 字段。
  • locale 字段已重命名为 language_code。
  • start_index 字段已移除。
  • max_results 字段已移除。

SavedAdStyle

• SavedAdStyle 已被移除，因为它已从 AdSense 界面中移除。

网站

• Sites 已添加，用于提取有关您已添加到 AdSense 账号中的网站的数据。
• state 字段表示网站是否处于以下任一状态：REQUIRES_REVIEW、GETTING_READY、READY、NEEDS_ATTENTION。
• auto_ads_enabled 字段是一个布尔值，用于表示特定网站上是否已启用自动广告。

版本 1.4

此版本引入了以下功能：

• 您现在可以列出 AdSense 账号中以相应币种进行的付款。
• 您现在可以通过调用 delete 方法来关闭提醒，该方法会在 API 和 AdSense 网页界面中隐藏提醒。
• 报告响应现在包含开始日期和结束日期。如果您在生成报告时使用相对日期（例如 today、yesterday、firstDayOfMonth-1m），这一点非常重要，因为响应现在会包含您请求的日期范围。

已知问题

此版本不支持报告中的 currency 字段。

版本 1.3

此版本引入了以下功能：

• 能够检索提醒。
• 能够检索指标和维度元数据。
• 能够以账号的本地时区运行报告。

已知问题

此版本不支持报告中的 currency 字段。

版本 1.2

此版本引入了以下功能：

• 能够检索广告样式。
• 能够检索和执行前端中定义的已保存报告。

已知问题

此版本不支持报告中的 currency 字段。

版本 1.1

此版本引入了以下功能：

• 能够列出用户有权访问的账号
• 能够对特定账号进行 GET 调用
• 能够对广告单元和自定义渠道进行 GET 调用
• 能够确定广告单元与自定义渠道之间的关联
• 自定义渠道包含有关定位信息的更多数据

此外，您现在可以访问默认账号或特定账号下的数据。

已知问题

此版本不支持报告中的 currency 字段。

版本 1

这是该 API 的第一个版本。它支持检索广告客户、广告单元、自定义渠道、网址渠道，以及生成报告。

已知问题

此版本不支持报告中的 currency 字段。