Postman のはじめ方

このチュートリアルでは、Postman の概要と、すばやくセットアップする方法を説明します。

​

はじめに

Postman は、グラフィカルユーザーインターフェイスから API にリクエストを送信できるデスクトップおよびウェブアプリケーションです。API の機能を試したり、アプリケーションの不具合を調査したりする際には、X API、X Ads API、Labs の endpoint とあわせて Postman の利用を推奨します。 

現在、利用可能な Postman コレクションは 2 件あります。

X API v2 Collection

X Ads API Collection

​

前提条件

X の Postman コレクションを使い始める前に、選択した X デベロッパープラットフォームのツールで必要なアクセス権と認証情報を用意してください。アクセス方法の詳細は Getting started ページをご覧ください。

デベロッパーアカウントを取得し、開発者用 Appを設定し、認証のキーおよびトークン一式を用意し、使用予定の特定の API にリクエストを送信できるよう環境を正しく構成したら、以下の手順に従って開始できます。  

​

X の Postman コレクションをはじめる

​

ステップ1: X の Postman コレクションのいずれかをアカウントに追加する

Postman 内で使いたい特定の endpoint を一から用意することもできますが、必要な作業は当方で済ませ、関連する API をすぐに使えるコレクションとして用意しています。前述の「Postman collections」セクションのリンクのいずれかをクリックすると、選択した API に対応するすべての endpoint を含むコレクションがあなたの Postman アプリに追加されます。これらのコレクションは Postman API network でも入手できます。各 endpoint には、利用可能なパラメータ、レスポンス例、認証の type があらかじめ設定されているため、あなたは認証情報とパラメータ値を追加するだけで機能の検証を開始できます。

この例では、X の API v2 collection を使用します。   

​

ステップ2：環境変数としてキーおよびトークンを追加する

コレクションを 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 をスキップしてください。

​

ステップ3：endpoint を選択する 

次のステップは、コレクションから endpoint を選び、リクエストの作成を開始することです。右側のナビゲーションから endpoint を選択できます。表示は以下のとおりです。

この例では、X API v2 > Post Lookup > Single Post の endpoint を使用します。 

​

ステップ4：Params タブに値を追加する

次のステップでは、Params タブに移動します。各パラメータの役割を説明する記述とともに、非アクティブなパラメータの一覧と、リクエストで指定可能な値のリストが表示されます。

この例では、expansions と tweet.fields の query パラメータを有効にし、次の値を追加します。

Key	Value
tweet.fields	created_at,attachments
expansions	author_id

query パラメータに加えて、必須の Path Variable である id も追加する必要があります。この endpoint は Posts を返すため、値として有効な Post ID を指定します。

Post ID は、x.com で目的の Post をクリックし、URL を確認することで取得できます。例えば、次の URL の Post ID は 1228393702244134912 です。

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

Params タブで、すべての query パラメータの一覧を下にスクロールし、「Path Variables」セクションを表示します。使用したい Post ID を、id キーの値として追加します。

このステップの入力が正しければ、Params タブは次のように表示されます。

​

ステップ5：リクエストを送信し、レスポンスを確認する

リクエストの設定が完了したら、「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 を使用してユーザー Access Token を生成する：

​

OAuth 1.0a を使用してユーザー access token を生成する

OAuth 1.0a flow test collection で用いられている3段階の手順を確認してください。

​

OAuth 2.0 を使用してユーザー access token を生成する

Postman で OAuth 2.0 のユーザー access token を生成する場合、X API v2 Postman collection と併用するための OAuth 2.0 access tokens を作成できます。 

ワークスペース内のコレクションをクリックし、「Auth」タブを開いて、type を「OAuth 2.0」に選択します。続いて、「Configure New Token」見出しの下にある「Configuration Options」に進みます。「Grant Type」を「Authorization Code (With PKCE)」に更新できます。

Callback URL を、あなたのアプリケーションに紐づく callback 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 - 機密クライアントを使用している場合
• Scope の更新 - 接続したい endpoint に対応する scopes。例: “tweet.read users.read”
• あなたの callback URL（redirect URL とも呼ばれます）。これは App の authentication 設定と一致している必要があります。
• State - state

準備ができたら「Get New Access Token」をクリックして Access Token を生成します。「問題が発生しました」といったダイアログが表示された場合は、ログインのために戻るボタンを押す必要があることがあります。ダイアログで「Authorize app」と表示されている箇所をクリックして、App にアカウントへのアクセスを許可してください。

App を承認すると Postman に戻り、トークンを確認して「Use Token」ボタンを選択し、承認済みユーザーとしてリクエストを送信できるようになります。

これで Postman collection を使用する準備が整いました。

​

次のステップ

Postman の「Code」ボタンをクリックすると、先ほど作成したリクエストを Python、Node、Ruby などお好みの言語に変換して、すぐに始められます。Postman には参考になる優れたドキュメントがあります。さらに、endpoint との統合をより迅速に進めるのに役立つGitHub 上のサンプルコードも用意しています。