访问 Ads 帐户

​

用户账户 vs 广告账户

在使用 X Ads API 时涉及两类账户：广告账户和 X 用户账户。在 Ads API 文档中，“account”通常指广告账户。

• 广告账户在 business.x.com 注册，并在 API 中由 account_id 标识。广告账户直接关联资金来源，并可利用一个或多个 X 用户账户的内容作为“promotable users”。每个广告账户可以向一个或多个 X 用户账户授予权限。广告账户（即“current account”）在几乎所有执行的 URL 中都以内联参数 :account_id 表示。
• X 用户账户（例如 @AdsAPI）在 Ads API 中由 user_id 标识。一个或多个此类账户可以关联到某个广告账户。通过 API 发起请求的已认证 X 用户账户称为“current user”。当前用户可访问的广告账户列表可通过 GET accounts 获取。“Promotable users” 指可由特定广告账户进行推广的 X 账号。更多详情，参见 Obtaining Ads Account Access。

​

广告账户访问的方法

您可以通过以下两种方式为广告主的账户发起 X Ads API 请求：

1. 代表广告主发起请求（推荐）
2. 使用您自己的账户（已获授对某广告主账户的访问权限）发起请求，例如支持多个账户的代理商。

本文档简要概述了这些选项之间的差异，应与我们的其他资源（例如多用户登录常见问题）结合阅读。

如授权请求所述，对 X Ads API 的所有请求都需要在 Authorization 头中使用OAuth 1.0a，并通过三方OAuth流程获得的 access token。您的应用需要实现基于 Web 的 OAuth 流程以获取访问令牌。Ads API 开发者绝不应要求 X 广告主共享其登录凭据。

默认情况下，每个 X developer application 都包含一个静态 access token，可用于为拥有该应用的账户发起 X Ads API 请求。对于不需要三方或基于 PIN 的 OAuth流程的单账户用例，这些凭据是理想选择。如果您不需要访问其他 X Ads 账户，请使用这些单用户凭据，而不是以下步骤。

​

访问权限级别

​

App 级权限

每位用户的访问级别将依据其在申请 X Ads API时所请求的权限而定：

• 仅转化（Conversion Only）：用户可在读写权限下访问 Mobile 和 Web Conversion endpoint。
• 标准访问（Standard Access）：用户可在读写权限下访问 Analytics、Campaign Management、Creatives、Custom Audiences 和 Conversion endpoint。

注意： 在 2023 年 7 月之前申请访问的 Ads API 开发者，可能具有不同的访问级别与权限，并且可能仅限于 5 个 OAuth 令牌。请参阅我们的提升访问级别指南，以获取更多 endpoint 的访问权限，或为现有 App 解除令牌限制。

​

广告账户级别权限

每个能够访问广告账户的用户都具有特定的账户级别权限：Account administrator、Ad manager、Campaign analyst、Organic analyst 和 Creative Manager。有关账户级别权限的最新文档，请参见 business.x.com。应用应通过 Authenticated User Access API endpoint 获取当前已认证用户的权限，以确定其可访问的 API endpoints 和 Ads 功能。

注意： 与 Conversion API 搭配使用的任何用户令牌，必须属于具备 Account administrator 或 Ad manager 账户级别权限的用户。                                                                                                                                              

​

获取 access token 的方式

​

1. 获取广告主（用户）的 access token

获取广告主的access token有两种方法。最常见的是在你的 Web UI 中直接通过三方 OAuth 授权流程。对于没有向广告主公开可访问 UI 的应用，可以实现基于 PIN 的 OAuth 流程。用户完成三方流程后，你的应用将获得凭证，可通过 API 代表其 Ads 账户发起请求。

通过 OAuth 流程获取用户凭证是我们对大多数 X Ads API 开发者获取广告主账户访问权限的强烈建议。这使你能够代表用户调用 API，并以该用户身份执行操作。这些令牌不会过期，但可由用户随时撤销。

​

2. 获取你的（开发者）access token

此选项要求广告主通过 business.x.com 的 X 界面授予你的 @username（或多个 @username）对其 X Ads 账户的访问权限。通过你的账户使用三方 OAuth 授权流程获取的 Access Tokens 将能够访问该广告主的 X Ads 账户。

这样，你可以使用自己 @username 的 OAuth 令牌调用 API，而无需使用广告主的 OAuth 令牌。该选项的关键区别在于，只有当你的 @username 被授予 Post 委派/创作权限时，你才能创建“仅推广”Post。

要代表账户中的 FULL 可推广用户获得创建“仅推广”Post 的权限，你还必须在此流程中被授予创建 Post 的权限。随后即可通过 GET accounts/:account_id/authenticated_user_access endpoint 上的 TWEET_COMPOSER 权限获得访问。

​

这些方法之间的差异

	广告主（用户）OAuth 令牌	（开发者）OAuth 令牌 （添加 @username 以区分账户）
访问广告账户	✔	✔
代表用户创建 Post	✔	✔*
管理广告活动	✔	✔
访问分析数据	✔	✔
代表用户创建卡片	✔	✔
开发者通过 X Ads UI 的访问能力		✔
请求速率限制	按广告主区分	按广告主账户区分

注意： 详情参见上文 获取你的（开发者）access token 部分。

​

示例用法

​

通过 OAuth 三方网页流程获取广告主的 access token

标准流程基于网页，并使用 三方授权 OAuth 流程。此处展示的屏幕截图来自一个示例，您可以在 https://github.com/xdevplatform/twauth-web 查看其源代码。

在应用的某个阶段，您需要重定向到 X 以请求用户为您的应用授权

当您携带请求令牌重定向到 X 时，系统会提示用户为您的应用授权

用户完成授权后，会被重定向到您在生成请求令牌时提供的回调 URL。您将使用该信息为该用户获取永久的 access token，并将其本地存储。