跳转到主要内容
要访问 X Ads API 的端点，你的应用必须通过 TLS 安全地向 https://ads-api.x.com 发送经认证的网络请求。 以下部分将概述如何发起认证的 API 请求、如何设置 Twurl 与 API 交互，以及如何扩展你的应用以支持 OAuth 1.0a 并向你的 Ads 帐户发起请求。

​
要求

在向 X Ads API 发起已认证请求之前，您需要：

​
使用 API

Advertising API 可通过 https://ads-api.x.com 访问。标准 REST API 与 Advertising API 可以在同一个客户端应用中配合使用。Advertising API 强制使用 HTTPS，因此尝试以 HTTP 访问任何端点都会返回错误信息。 Ads API 输出 JSON。所有标识符均为字符串，且所有字符串均为 UTF-8。Advertising API 采用版本化，版本作为任何资源 URL 的第一个路径元素进行指定。 https://ads-api.x.com/<version>/accounts

​
HTTP 动词与典型响应代码

Ads API 使用四种 HTTP 动词：
  • GET 获取数据
  • POST 创建新数据，例如广告系列（campaigns）
  • PUT 更新现有数据，例如广告单元（line items）
  • DELETE 删除数据
删除操作是永久性的，但在请求资源时显式添加参数 with_deleted=true，仍可通过大多数基于 GET 的方法查看已删除的数据。否则，已删除的记录将返回 HTTP 404。 成功的请求在创建、删除或更新资源时会返回 HTTP 200 系列响应，并附带表示该对象的 JSON 响应体。 使用 HTTP PUT 更新数据时，仅会更新指定的 fields。你可以通过将参数设置为空字符串来清除一个可选值。例如，以下参数组合将清除已设置的 end_time：&end_time=&paused=false。 有关错误响应的更多详细信息，请参阅 错误代码与响应。

​
内联参数

大多数资源 URL 包含一个或多个内联参数。许多 URL 也会在查询字符串中显式声明参数，或在 POST 或 PUT 请求的请求体中传递参数。 内联参数在每个资源的资源路径部分以前置冒号（“:”）标示。例如，如果你正在处理的账户的标识为 "abc1"，并且你在检索与某个账户关联的广告系列，则可以通过 URL https://ads-api.x.com/6/accounts/abc1/campaigns 访问该列表。通过在资源 URL（https://ads-api.x.com/6/accounts/:account_id/campaigns）中指定内联的 account_id 参数，你已将请求限定为仅与该账户关联的对象。

​
使用访问令牌

X Ads API 使用带签名的 HTTPS 请求来验证应用的身份，同时获取该应用代表终端用户发起 API 请求时所授予的权限，这些权限由用户的访问令牌表示。对 Ads API 的所有 HTTP 调用都必须在 HTTPS 协议下包含 Authorization 请求头（使用 OAuth 1.0a）。 你需要在应用中实现生成 OAuth 1.0a Authorization 请求头的能力，以便集成 X Ads API。鉴于生成签名请求较为复杂，我们强烈建议合作伙伴使用现有库，这些库要么原生支持 X API，要么实现了 OAuth 1.0a 请求处理—这里提供了推荐的 OAuth 库和认证代码示例。 请注意，当合作伙伴在使用已知库时遇到认证 errors 时，我们可以提供协助，但无法支持自定义的 OAuth 实现。

​
HTTP 与 OAuth

与 X REST API v1.1 相同，Advertising API 需要同时使用 OAuth 1.0A 和 HTTPS。可通过 应用管理控制台 获取 API 密钥。还必须使用访问令牌来表示“当前用户”。“当前用户”指具备投放广告权限的 X 账户。 强烈建议合作伙伴使用现成的 OAuth 库，而非自行实现。使用已知库时我们可以协助排查问题，但如果你自行实现 OAuth，我们将无法提供支持。请参阅可用的 库。 API 对 HTTP/1.1 和 OAuth 的要求非常严格。请确保在准备 OAuth 签名基字符串之前，已在 URL 和 POST 正文中适当对保留字符进行编码。特别是，Advertising API 在指定时间时使用“:”字符，在提供选项集合时使用“,”字符。二者均属于以下保留字符集：
符号URL 编码
!%21
#%23
$%24
&%26
’%27
(%28
)%29
*%2A
+%2B
,%2C
/%2F
:%3A
;%3B
=%3D
?%3F
@%40
[%5B
]%5D

​
使用 Twurl 发起你的第一个 API 请求

X 维护了一个命令行工具 Twurl，它支持 OAuth 1.0a 授权标头，可作为 cURL 的替代方案。Twurl 提供了一种简单方式，用于发起已认证的 API 请求，并在将认证集成到你的应用之前探索 Ads API。 在安装并授权 Twurl后，你可以快速生成访问令牌，并向 Ads API 发起已认证的请求。 
twurl -H "ads-api.x.com" "/5/accounts/"
花些时间，通过本分步教程（通过 API 创建广告系列），熟悉 Twurl 和 API。

​
使用 Postman 进行测试

对于不熟悉命令行工具的用户，我们也提供了适用于 X Ads API 端点的 Postman 集合。 Postman 是当今业内最受欢迎的 API 开发工具之一。它是一个 HTTP 客户端，拥有出色的图形界面，可让你更轻松地发起复杂的 API 请求并提升效率。 要安装 Postman 并开始使用 Ads API 的 Postman 集合，请参阅我们的安装指南。

​
将你的应用扩展为可发起认证请求

在使用 Twurl 熟悉了向 Ads API 发起请求之后，现在是时候为你的应用添加对创建 OAuth 1.0a 认证请求头的支持了。 OAuth 1.0a 认证请求头包含用于同时验证应用与用户身份的信息，并可防止请求被篡改。你的应用需要为每个 API 请求创建一个新的 Authorization 请求头。许多编程语言都有开源库可用于创建该授权请求头，以便向 X 发起 API 请求。 以下是使用 C#、PHP、Ruby 和 Python 的一些示例——代码示例。

​
自定义实现

在某些场景下，可能需要在没有开源库支持的情况下实现 OAuth 1.0a 认证。授权请求提供了关于如何构建 Authorization 头的详细实现指南。我们强烈建议使用社区维护的库。 总体流程：
  1. 收集 7 个以 oauth_ 开头的键值对用于构建头部
  2. 使用这些键值对生成 OAuth 1.0a HMAC-SHA1 签名
  3. 使用上述值构建 Authorization 头