发出已验证请求

进入 Twitter 广告 API 端点，要求你的应用程序使用 TLS 登录 https://ads-api.twitter.com，安全地发出已验证网页请求。

以下章节j将要介绍如何发出已验证 API 请求、设置 Twurl 与 API 互动，以及扩展你的应用程序以支持 OAuth 1.0a。同时，对你的广告账号发出请求。

要求

在向 Twitter 广告 API 发出已验证请求之前，你需要：

一个已批准的开发者账号
已获批准访问广告 API 的应用程序
通过应用程序管理用户界面获取的 API 密钥和机密，以及
供用户进入 Twitter 广告账号的访问令牌

使用 API

可通过 https://ads-api.twitter.com 找到广告 API。标准 REST API 和广告 API 可一起用于相同的客户端应用。广告 API 强制实施 HTTPS，因此，尝试通过 HTTP 访问端点会导致错误消息出现。

广告 API 输出 JSON。所有标识符均为字符串，且所有字符串均为 UTF-8。广告 API 已进行版本控制，版本被指定为任何资源 URL 的第一路径元素。

https://ads-api.twitter.com/<version>/accounts

HTTP 动词和常见响应代码

广告 API 中使用四种 HTTP 动词：

GET 检索数据
POST 创建新数据，如广告活动
PUT 更新现有数据，如行项目
DELETE 删除数据。

虽然删除是永久性的，但已删除的数据仍可使用多数基于 GET 的方法查看，方法是在请求资源时纳入显式 with_deleted=true 参数。否则，删除的记录将返回 HTTP 404。

创建、删除或更新资源时，成功请求将返回 HTTP 200 系列响应以及表示对象的 JSON 响应。

使用 HTTP PUT 更新数据时，将仅更新指定字段。你可以使用空字符串指定参数，以此取消设置可选值。例如，如下参数组将取消设置任何已指定的 end_time：&end_time=&paused=false。

参阅错误代码和响应，获取有关错误响应的更多详细信息。

内嵌参数

大多数资源 URL 具有一个或多个内嵌参数。许多 URL 在查询字串上或针对正文中的 POST 或 PUT 请求采用显式声明的参数。

内嵌参数在每个资源的资源路径部分中由前面预置的冒号 (“:”) 来表示。例如，如果你正在处理的账号标识为 "abc1"，且你正在检索与账号关联的广告活动，则你可使用 URL https://ads-api.twitter.com/6/accounts/abc1/campaigns 访问该列表。通过指定资源 URL (https://ads-api.twitter.com/6/accounts/:account_id/campaigns) 中描述的内嵌 account_id 参数，你可以将请求的范围限定为仅与该账号关联的对象。

使用访问令牌

Twitter 广告 API 使用已签署的 HTTPS 请求验证应用程序的身份，并获取授予终端用户（即应用程序代为发出 API 请求的终端用户）的许可，以用户的访问令牌表示。广告 API 的全部 HTTP 调用必须包括一个在 HTTPS 协议上的授权请求标题（使用 OAuth 1.0a）。

你需要添加支持，以向你的应用程序生成 OAuth 1.0a 授权请求标题，并与 Twitter 广告 API 结合。但是，鉴于生成签署请求的复杂性，我们强烈建议合作伙伴使用可以支持 Twitter API 或实施 OAuth 1.0a 请求处理的现有库——以下为建议的 OAuth 库和身份验证代码示例。

注意，当合作伙伴使用已知库却不能支持实施自定义 OAuth 时，我们可以为遇到身份验证出错的合作伙伴提供协助。

HTTP 和 OAuth

和 Twitter REST API v1.1 一样，广告 API 要求同时使用 OAuth 1.0A 和 HTTPS。API 密钥可通过应用管理控制台获取。访问令牌还必须用于表示“当前用户”。当前用户是具有广告功能的 Twitter 账号。

我们强烈建议合作伙伴使用 OAuth 库，而不是自己编写。使用已知库时，我们可提供调试支持，但是，如果使用自己的 OAuth 实现，我们便无法提供调试支持。参阅你可使用的库。

该 API 严格遵循 HTTP 1.1 和 OAuth。确保你在准备 OAuth 签名基础字符串前，在 URL 和 POST 正文中正确地编码保留字符。较为特别的是，广告 API 在指定时间时使用“:”字符，在提供选项集合时使用“,”字符。这两个字符都属于如下保留集：

‘

(

)

：

;

[

]

%21

%23

%24

%26

%27

%28

%29

%2A

%2B

%2C

%2F

%3A

%3B

%3D

%3F

%40

%5B

%5D

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

Twitter 帮助维持一个命令行工具，即 Twurl。它可支持 OAuth 1.0a 授权标题作为 cURL 的替代。Twurl 提供了一种简便的方法，可在向你的应用程序添加身份验证之前发出已验证 API 请求和开发广告 API。

在安装和授权 Twurl 之后，你可以迅速生成访问令牌，并向广告 API 发出已验证请求。

twurl -H "ads-api.twitter.com" "/5/accounts/"

请按照本详细步骤的教程，熟悉 Twurl 和 API，并通过 API 创建广告活动。

使用 Postman 进行测试

对于不熟悉命令行工具的用户，我们还提供了一个针对 Twitter 广告 API 端点的 Postman 集合。

Postman 是当今业界最常用的 API 开发工具之一。它是一种 HTTP 客户端，提供友好的用户界面，让你可更轻松发出复杂的 API 请求并提高工作效率。

要安装 Postman 并开始使用广告 API Postman 集合，请查看我们的设置指南。

在 Postman 中运行

扩展你的应用程序，以发出已验证请求。

在熟悉如何使用 Twurl 向广告 API 发出请求后，可添加支持，以向你的应用程序创建 OAuth 1.0a 身份验证标头。

OAuth 1.0a身份验证标头包括验证应用程序和用户身份的信息，以及防止窜改请求的信息。你的应用程序需要为每个 API 请求创建一个新的授权标题。许多语言都有支持创建此授权标题的开源库，以向 Twitter 发出 API 请求。

以下为使用 C#、PHP、Ruby 和 Python 的一些示例 - 代码示例。

自定义实施

有一些情景要求实施 OAuth 1.0a 身份验证，而无需开源库的支持。授权一个请求可为实施支持创建授权标题提供详细的指示。我们强烈建议使用社区支持的库。

概要：

为标题收集 7 个键/值对——以 oauth_ 开头
使用这些键/值对生成 OAuth 1.0a HMAC-SHA1 签名
使用上述值建立授权标题

后续步骤

在为授权标题添加支持后，你应当有一个能够成功向 Twitter 广告 API 发出已验证请求的简单应用程序。

为访问其他用户的 Twitter 广告账号，你的应用程序需要通过三方 OAuth 流获取访问令牌。

如果你的应用程序只访问你的 Twitter 广告账号，则转至《上传视频与推广推文指南》，以上传可在广告活动中使用的素材。

资源

开发工具

Twurl - 用于与 Twitter API 互动的命令行工具
Postman - 用于人工检查第三方 API 的开发工具

Twitter 库支持广告 API

Python - Twitter 支持
Ruby - Twitter 支持
Java - Twitter 建议

支持 OAuth 1.0a 的请求标题授权库