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

​
要求

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

​
使用 API

X Ads API 的访问地址为 https://ads-api.x.com。[标准 REST API](https://developer.x.com/en/docs/x-api/v1/tweets/post-and-engage/overview) 与 X Ads API 可在同一个客户端 App 中配合使用。X Ads API 强制使用 HTTPS，因此尝试通过 HTTP 访问某个 endpoint 将会返回错误。 X Ads API 输出 JSON。所有标识符均为字符串，且所有字符串均为 UTF-8。X Ads API 采用版本管理，版本号作为任何资源 URL 的第一个路径元素进行指定。 https://ads-api.x.com/<version>/accounts

​
HTTP 动词与典型响应代码

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

​
内联参数

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

​
使用 Access Tokens

X Ads API 使用带签名的 HTTPS 请求来验证应用的身份，并获取该应用代表终端用户发起 API 请求时所获授的权限，这些权限由用户的 access token 表示。对 Ads API 的所有 HTTP 调用都必须通过 HTTPS 协议携带 Authorization 请求头（使用 OAuth 1.0a）。 要集成 X Ads API，您需要在应用中支持生成 OAuth 1.0a 的 Authorization 请求头。但鉴于生成签名请求的复杂性，我们强烈建议合作伙伴使用已支持 X API 或已实现 OAuth 1.0a 请求处理的现有库——这里提供了推荐的 OAuth 库和身份验证代码示例。 请注意，当合作伙伴使用已知库且遇到身份验证错误时，我们可以提供协助，但无法支持自定义的 OAuth 实现。

​
HTTP 与 OAuth

与 X REST API v1.1 类似，Advertising API 需要同时使用 OAuth 1.0a 和 HTTPS。可通过 App 管理控制台 获取 API Key。还必须使用 Access Tokens 来表示“current user”。current user 指具备投放广告能力的 X 账号。 强烈建议合作伙伴使用现成的 OAuth 库，而非自行编写。使用知名库时我们可以协助调试，但如果你自研 OAuth 实现，我们将无法提供支持。请参阅可用的 libraries。 该 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 请求，并在将身份验证集成到你的应用之前探索 X Ads API。 在安装并授权 Twurl 后，你可以快速生成 access token，并向 X Ads API 发起已认证的请求。 
twurl -H "ads-api.x.com" "/5/accounts/"
花点时间通过这个关于使用 API 创建广告活动的分步教程来熟悉 Twurl 和 API。

​
使用 Postman 进行测试

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

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

在熟悉使用 Twurl 向 X 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 标头
⌘I