Postman 入门

本教程将介绍 Postman 的基本概念，并说明如何快速完成设置。

​

介绍

Postman 是一款桌面端和网页版应用，可通过图形界面向 API 发起请求。我们建议在探索 X API、X Ads API 和 Labs endpoint 的功能，以及排查应用问题时使用 Postman。

我们目前提供两套 Postman 集合：

X API v2 集合

X Ads API 集合

​

先决条件

在开始使用 X 的 Postman 集合之前，您需要确保为所选的 X 开发者平台工具准备好相应的访问权限和凭据。您可以在我们的“入门”页面了解如何获取访问权限的更多信息。

当您已拥有开发者账户、完成开发者 App设置、获取一组身份验证密钥和令牌，并正确配置环境以便向计划使用的特定 API 发出请求后，即可按照以下步骤开始。  

​

开始使用 X 的 Postman 集合

​

第一步：将一套 X 的 Postman 集合添加到你的账户

虽然你可以在 Postman 中自行搭建想用的特定 endpoint，但我们已经替你做好了大部分工作，提供了一套可即用的相关 API 集合。只需点击前文“Postman collections”部分中的任一链接，所选 API 关联的所有 endpoint 的集合就会添加到你的 Postman App 中。这些集合也可在 Postman API network 获取。每个 endpoint 都会自动包含可用的参数、示例响应和已配置的认证 type，你只需添加凭证和参数值即可开始探索其功能。

在本示例中，我们将使用 X 的 API v2 collection。   

​

步骤二：将你的密钥和令牌添加为环境变量

当你将集合添加到 Postman 实例时，会自动创建一个名为“X API v2”的环境，你需要将密钥和令牌添加到其中。此步骤将引导你把开发者 App 中的密钥和令牌添加到“X API v2”环境。

要将密钥和令牌添加到“X API v2”环境，请点击 Postman 右上角的“manage environments”按钮；如未看到该按钮，请点击右上角的设置按钮。

在环境列表中，点击“X API v2”。

接着，将你通过 Apps 控制台生成的各类密钥和令牌以变量形式添加到表格中。如下是表格示例：

VARIABLE	INITIAL VALUE	CURRENT VALUE
consumer_key	QAktM6W6DF6F7XXXXXX	QAktM6W6DF6F7XXXXXX
consumer_secret	AJX560A2Omgwyjr6Mml2esedujnZLHXXXXXX	AJX560A2Omgwyjr6Mml2esedujnZLHXXXXXX
access_token	1995XXXXX-0NGqVhk3s96IX6SgT3H2bbjOPjcyQXXXXXXX	1995XXXXX-0NGqVhk3s96IX6SgT3H2bbjOPjcyQXXXXXXX
token_secret	rHVuh7dgDuJCOGeoe4tndtjKwWiDjBZHLaZXXXXXX	rHVuh7dgDuJCOGeoe4tndtjKwWiDjBZHLaZXXXXXX
bearer_token	AAAAAAAAAAAAAAAAAAAAAL9v6AAAAAAA99t03huuqRYg0mpYAAFRbPR3XXXXXXX	AAAAAAAAAAAAAAAAAAAAAL9v6AAAAAAA99t03huuqRYg0mpYAAFRbPR3XXXXXXX

请注意，上表中的密钥和令牌仅为示例，无法用于实际请求。

在将凭据添加为变量并确认已选择 X API v2 环境后，你即可对 X API v2 集合发起请求。原因是各 endpoint 的授权选项卡已配置为自动继承该环境中的变量。

如需在 Postman 中使用 User Access Tokens，请跳转至 XXXX 查看详细说明。

​

第三步：选择一个 endpoint 

接下来，从集合中选择一个 endpoint 并开始构建请求。你可以在右侧导航中选择一个 endpoint。如下所示：

在本示例中，我们将使用 X API v2 > Post Lookup > Single Post endpoint。 

​

步骤四：在 Params 选项卡中添加值

接下来，请前往 Params 选项卡。你会看到一组未启用的参数及其说明，解释各参数的作用，并列出可随请求传递的所有潜在取值。

在本示例中，我们将启用 expansions 和 tweet.fields 查询参数，并添加以下值：

Key	Value
tweet.fields	created_at,attachments
expansions	author_id

除了添加查询参数外，我们还需要添加必填的 Path Variable：id。由于此 endpoint 返回 Posts，我们需要提供一个有效的 Post ID 作为其值。

你可以通过访问 x.com，点击任一 Post，然后查看其 URL 来找到该 Post ID。例如，以下 URL 的 Post ID 为 1228393702244134912：

https://x.com/XDevelopers/status/1228393702244134912

在 Params 选项卡中，向下滚动，越过所有查询参数，找到“Path Variables”部分。我们将把你要使用的 Post ID 作为值添加到 id 键中。

如果你已正确完成本步骤的所有输入，Params 选项卡应如下所示：

​

第五步：发送请求并查看响应

现在你的请求已全部配置完成，可以点击“Send”按钮。

如果一切配置正确，你将会收到如下有效负载：

{
    "data": {
        "author_id": "2244994945",
        "text": "开发者在情人节卡片上写了什么？\n  \nwhile(true) {\n    I = Love(You);  \n}",
        "id": "1228393702244134912",
        "created_at": "2020-02-14T19:00:55.000Z"
    },
    "includes": {
        "users": [
            {
                "username": "XDevelopers",
                "name": "开发者",
                "id": "2244994945"
            }
        ]
    }
}

​

使用 Postman 生成用户访问令牌：

​

使用 OAuth 1.0a 生成用户访问令牌

查看 OAuth 1.0a 流程测试集合 中采用的三步流程。

​

使用 OAuth 2.0 生成用户 access token

如果你想在 Postman 中生成 OAuth 2.0 用户 access token，可以生成 OAuth 2.0 access tokens，并与 X API v2 Postman collection 配合使用。 

在工作区中点击该集合，进入名为“Auth”的选项卡，并将 type 设为“OAuth 2.0”。然后在“Configure New Token”下的“Configuration Options”中，将“Grant Type”更新为“Authorization Code (With PKCE)”。

请将 Callback URL 更新为与你的应用关联的回调 URL。此外，还需要更新以下参数：

• Auth URL -  https://x.com/i/oauth2/authorize
• Access Token URL -  https://api.x.com/2/oauth2/token
• Client ID - 来自 Dev Portal 的 OAuth 2.0 client ID
• Client Secret - 如果你使用的是机密客户端
• Update Scope - 作用域需与要连接的 endpoints 匹配。例如：“tweet.read users.read” 
• 你的 callback URL（也称为 redirect URL）。必须与 App 身份验证设置中的配置一致。
• State - state

准备就绪后，点击“Get New Access Token”生成一个 Access Token。若弹出对话框提示出现问题，可能需要点击返回按钮以登录。你需要在对话框中点击“Authorize app”，为你的应用授权访问你的账户。

授权完成后，你会被重定向回 Postman，在那里可以看到你的 token，并点击“Use Token”按钮，以代表已授权用户开始发起请求。

你现在可以开始使用 Postman collection 了。

​

后续步骤

在 Postman 中点击“Code”按钮，可以将我们刚创建的请求转换为你选择的语言，例如 Python、Node 或 Ruby，帮助你快速上手。Postman 提供了优质的文档，可能对你有所帮助。我们在 GitHub 上也提供了示例代码，可帮助你更快地集成这些 endpoint。