Postman 入門

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

はじめに

Postman は、グラフィカルユーザーインターフェイスから API にリクエストを送信できるデスクトップ版および Web 版のアプリケーションです。API の機能を確認・検証したり、アプリケーションの問題をトラブルシューティングしたりする際には、X API、X Ads API、および Labs エンドポイントとあわせて Postman を使用することをおすすめします。 

現在、次の 2 つの Postman コレクションを利用できます。

X API v2 コレクション

X Ads API コレクション

前提条件

X の Postman コレクションを使い始める前に、利用したい X の開発者プラットフォーム向けツールで、適切なアクセス権と認証情報が付与されていることを確認する必要があります。アクセスの取得については、「はじめに」ページで詳しく確認できます。 

開発者アカウントを取得し、developer App を設定し、認証用のキーとトークン一式を用意し、利用を予定している特定の API にリクエストを送信できるよう環境を正しく設定できたら、以下の手順に従って作業を開始できます。  

X の Postman コレクションを使い始める

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

Postman 内で使用したい特定のエンドポイントを一つひとつ作成することもできますが、その作業はあらかじめこちらで行い、関連する API をまとめたすぐに使えるコレクションを用意しています。前の「Postman collections」セクションにあるリンクのいずれかをクリックすると、選択した API に関連付けられたすべてのエンドポイントを含むコレクションが Postman App に追加されます。これらのコレクションは Postman API network からも利用できます。各エンドポイントには、利用可能なパラメータ、レスポンス例、認証方式があらかじめ設定されているため、あとは認証情報とパラメータ値を追加するだけで機能を試し始めることができます。

この例では、X の API v2 collection を使って進めます。   

Step two: 環境変数としてキーとトークンを追加する

コレクションをお使いの 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 コレクションへのリクエストを送る準備は完了です。これは、各エンドポイントの Authorization タブが、この環境から変数を自動的に継承するように設定されているためです。 

User Access Tokens と共に Postman を使用する方法については、XXXX までスキップして追加の詳細説明を参照してください。

ステップ3：エンドポイントを選択する

次は、コレクションからエンドポイントを選択し、リクエストの作成を始めます。右側のナビゲーションからエンドポイントを選択できます。表示は次のようになります。

この例では、X API v2 > Post Lookup > Single Post エンドポイントを使用します。 

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

次の手順では、Paramsタブに移動します。ここには、無効になっている複数のパラメータが表示されており、それぞれについてパラメータの役割を説明する文章と、リクエストで指定できるすべての候補値の一覧が付いています。 

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

Key	Value
tweet.fields	created_at,attachments
expansions	author_id

クエリパラメータを追加するだけでなく、必須の Path Variable である id も追加する必要があります。このエンドポイントはポストを返すため、値として有効なポストIDを指定する必要があります。

ポストIDは、x.com にアクセスしてポストをクリックし、URL を確認することで取得できます。たとえば、次の URL のポストIDは 1228393702244134912 です。

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

Paramsタブで、すべてのクエリパラメータをスクロールして「Path Variables」セクションを表示します。ここで、使用したいポスト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": "Developers",
                "id": "2244994945"
            }
        ]
    }
}

Postman を使用したユーザーアクセス・トークンの生成:

OAuth 1.0a を使用してユーザーアクセス・トークンを生成する

OAuth 1.0a フローテストコレクション で説明されている 3 ステップのプロセスを確認します。

OAuth 2.0 を使用してユーザーアクセス・トークンを生成する

Postman で OAuth 2.0 のユーザーアクセス・トークンを生成したい場合は、X の API v2 Postman collection で使用できる OAuth 2.0 アクセストークンを生成できます。 

ワークスペース内のコレクションをクリックし、「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 - confidential client を使用している場合
• Update Scope - 接続したいエンドポイントに対応する scopes。例: “tweet.read users.read” 
• Callback URL (redirect URL とも呼ばれます) 。これは App の認証設定で設定している値と一致している必要があります。
• State - state

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

アプリを承認すると、Postman にリダイレクトされ、そこでトークンを確認し、「Use Token」ボタンを選択して、認可されたユーザーに代わってリクエストの送信を開始できます。

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

次のステップ

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