授权和 HTTP 标头

调用 Search Ads 360 Reporting API 时,您需要 OAuth 2.0 应用凭据。如果您以 Search Ads 360 经理账号的身份发出 API 调用,还需要在每个请求中指定 login-customer-id 标头。本页介绍了如何设置这些值,并记录了在使用 REST 接口时发送和接收的几个额外的特定于 API 的 HTTP 标头。

OAuth 2.0 凭据

Search Ads 360 Reporting API 使用应用凭据来识别和授权 API 请求。可以配置 OAuth 2.0 客户端。所有 Search Ads 360 Reporting API 调用都必须通过 OAuth2 进行授权。借助 OAuth2,您的 Search Ads 360 Reporting API 客户端应用就能够访问用户的 Search Ads 360 账号,而无需处理或存储用户的登录信息。

如果您是 Google API 的新用户,可以使用 oauth2lOAuth 2.0 Playground 来试用应用凭据和 Search Ads 360 Reporting API,然后再为应用编写代码。您还可以运行提供的用户凭据生成脚本来生成 OAuth 刷新令牌。

生成新的访问令牌

获得客户端 ID客户端密钥刷新令牌后,您可以使用 curl 命令行工具生成新的访问令牌,以便在 API 调用中使用:

curl \
  --data "grant_type=refresh_token" \
  --data "client_id=CLIENT_ID" \
  --data "client_secret=CLIENT_SECRET" \
  --data "refresh_token=REFRESH_TOKEN" \
  https://www.googleapis.com/oauth2/v3/token

然后,您可以在每次调用 Search Ads 360 Reporting API 时,使用 curl 请求返回的访问令牌作为 Authorization HTTP 标头:

GET /v0/customers:listAccessibleCustomers HTTP/1.1
Host: searchads360.googleapis.com
Authorization: Bearer ACCESS_TOKEN

请求标头

登录客户 ID

对于经理账号向客户账号发出的 Search Ads 360 Reporting API 调用(即以经理账号身份登录,向其某个客户账号发出 API 调用),您还需要提供 login-customer-id HTTP 标头。此值表示发出 API 调用的经理账号的 Search Ads 360 客户 ID。

包含此 HTTP 标头的效果就相当于在登录或点击页面右上角的个人资料图片后选择 Search Ads 360 界面中的账号。指定客户 ID 时,请务必移除所有连字符 (—),例如:1234567890,而不是 123-456-7890

GET /v0/customers:listAccessibleCustomers HTTP/1.1
Host: searchads360.googleapis.com
Authorization: Bearer ACCESS_TOKEN
login-customer-id: MANAGER_CUSTOMER_ID

响应标头

以下标头会在 API 的 HTTP 响应中返回。

请求 ID

request-id 是唯一标识 API 请求的字符串。在调试或排查特定 API 调用方面的问题时,request-id 是一个重要的标识符,在与 Google 开发者支持团队联系时,请务必提供此标识符。

request-id: 2a5Cj89VV7CNhya1DZjjrC