Postman API Client (SalesforceのモジュールPostman API Clienの解説) *


Postman Advent Calendar 2023 シリーズ2　2日目の記事として投稿

[Postman API Client:これを日本語化しています](https://trailhead.salesforce.com/ja/content/learn/modules/postman-api-client)

**参考**

[Postman Learning Center](https://learning.postman.com/)
[Welcome to the Postman community!](https://community.postman.com/)

日本語のモジュールがないんですよね。自分の覚え的に日本語で整理したいと思います。
1日目の記事としてPostmanワークショップ: テスト自動化を受講して理解が深まりました。この記事を先に使ったので、ワークショップを受けた後が良かったかもしれません。

# Get Started with Postman

このモジュールでは、Postman を API クライアントとして使用する手順を示します。このモジュールには実践的な課題はありませんが、手順に沿って試してみたい場合は、Postman アカウントの設定、Postman Web API クライアントの使用、ワークスペースの作成などについて説明します。


# Send API Calls

**パブリックワークスペースをセットアップする**
Postman での作業を整理するためのワークスペースを、さまざまなレベルのプライバシーで設定できます。個人用ワークスペースは自分だけが表示されます。チーム ワークスペースは、プロジェクトで他のユーザーと共同作業するために使用できます。 

**コードの生成**

https://learning.postman.com/docs/sending-requests/generate-code-snippets/

Postman は API リクエストをコード スニペットに変換でき、プログラミング言語またはフレームワークを選択できます。この生成されたコード スニペットをフロントエンド アプリケーションで使用できます。

1. コード スニペットに使用するリクエストを開き、 コードアイコン 右側のペインでコード アイコンを選択します。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/328136/2faa0a99-4a04-dd28-81a1-45c40aa753ca.png)

2\. ドロップダウン リストから言語またはフレームワークを選択します。
3\. コピー アイコンを選択して コピーアイコン 、コード スニペットをクリップボードにコピーします。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/328136/7ee2605b-08ee-ed03-39dd-af28a3b7abdc.png)

インデントのタイプや数など、その他の構成オプションを使用するには、 設定アイコン ドロップダウン リストの横にある設定アイコンを選択します。設定は、選択した言語またはフレームワークによって異なります。

生成されたコードが希望どおりにフォーマットされていない場合は、追加の設定を <img width="30" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/328136/4bd93527-740e-4bd5-3109-41de1107a432.png">
で調整できます装備。コード スニペットをインライン編集することもできます。準備ができたら、このコードをコピーして独自のアプリケーションに貼り付けることができます。

# Test Responses

**テスト スニペットを挿入する**

JavaScript で Postman テストを作成して、API が期待どおりに機能していることを確認できます。リクエストの[テスト]タブで、JavaScript を手動で入力するか、コード エディターの右側にある SNIPPETS リストを使用できます。これらの一般的な使用例のいずれかをクリックすると、編集用のコードがエディターに自動的に挿入されます。

1. リクエストを開いた状態で、「テスト」をクリックします。
2. スニペット リストで、[ステータス コード: コードは 200] を見つけてクリックし、コード エディターにスニペットを挿入します。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/328136/4e5ba588-cc28-e297-d5bd-f269d3de2b43.png)


Postman テストは、以下を受け入れるpm.test()関数で構成されます。

+ テスト結果出力で識別するために使用されるテストの名前
+ テストが成功したか失敗したかを示すブール値 (true または false) を返す関数

この例では、テストの名前は「ステータス コードは 200」です。この関数には、 Chai BDD構文を使用してフォーマットされた HTTP ステータス コード 200 を受け取るという、応答に関するアサーションが含まれています。

```
pm.test("Status code is 200", function () {
    pm.response.to.have.status(200);
});
```

**テストを実行する**

テストはサーバーの応答に関するアサーションであるため、テストはリクエストを実行し、API からの応答を受信した後に実行されます。 

+ テストをリクエストに追加したら、「送信」をクリックしてリクエストを実行します。
+ 下部の応答セクションでテスト結果を開きます。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/328136/2dbb0e85-761f-44f6-89e9-c4214b2ab10b.png)

呼び出しが200HTTP ステータス コードを返した場合、テストは成功します。それ以外の場合、テストは失敗します。テスト スクリプト内の予期されるステータス コードを に変更して404、リクエストを再度実行してみてください。テスト結果に失敗とエラー メッセージが表示されることがわかります。

**リクエストをコレクションに保存する**

左側のサイドバーの「履歴」タブには、Postman から送信した最新のリクエストの記録が保持されます。履歴を調べてリクエストを見つけて再利用するのは時間がかかる場合があります。代わりに、リクエストのコレクションを保存して作業を整理できます。コレクションは、生産性を向上させるだけでなく、自動化、監視、模擬サーバーなど、Postman のより高度な機能の基盤でもあります。

1. <img width="30" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/328136/594e152b-4117-d339-8855-cfb07b67afe6.png">をクリック
2. 最初に作成したリクエストの上にマウスを置き、「Add request to Collection」 ( + ) をクリックします。これは、日付パラメータを追加する前に行ったリクエストである必要があります。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/328136/d747aee3-d5fd-733c-1680-f81741a6d257.png)

3\. [New Collection]をクリックします。
4\. コレクションに名前を付けますTrailhead module
5\. 「Create」をクリックします。
6\. 「Save」をクリックします。リクエストは新しいコレクションに保存されます。
7\. 2 番目の通話の上にマウスを置き、「Add request to Collection」 ( + ) をクリックします。
8\. 宛先はすでに Trailhead モジュールになっているはずです。[Save]をクリックしてください。

2020 年 11 月以降、最初の呼び出しの名前を Picture of the Day に更新し、2 回目の呼び出しの名前を Pictures に更新します。

1. <img width="30" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/328136/0ac1eba1-e1ef-69dd-83c9-32c90f634823.png">をクリックします。
2. Trailhead モジュール コレクションを展開します。
3. 上部のリクエストにカーソルを合わせてクリックします3 つの点で示されたその他のアクションのアイコン
4. [Rename]をクリックします。 
5. Picture of the Day と入力します
6. コレクション内の 2 番目のリクエストの名前を変更します　Pictures from November 2020。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/328136/25af9646-e743-a618-dab8-9adb90e04140.png)

ここで、実際に 2020 年 11 月のすべての写真をリクエストしていることを確認してみましょう。 

1. [Pictures from November 2020]をクリックします。
2. 作成した日付キーの上にマウスを置き、[X]をクリックして削除します。
3. 新しいキーを入力して、11 月 1 日に検索配列を開始します。
Key：start_date
Value ：2020-11-01
4. 別のキーを入力して最終日の検索配列を終了します。
Key：end_date
Value ：2020-11-30
5. 作業内容を保存します。
6. 「送信」をクリックしてリクエストを実行します。

**DRYな状態に保ちます**

DRY は「同じことを繰り返さない」の略です。すべてのエンドポイントから JSON オブジェクトが返されることを常に期待していると想像してください。すべてのリクエストに同じテストを個別に追加する代わりに、コレクション レベルでテスト アサーションを追加して、コレクション内のすべてのリクエストの後に実行できます。Postman を使用すると、個々のリクエスト、フォルダー、またはコレクションにテストを追加できます。

1. [Trailhead module]をクリックします。
2. 「Test」タブをクリックします。
3. [SNIPPETS] で、[Status Code: Code is 200]を選択して、コレクション レベルでテストを追加します。
4. 「Save」をクリックします。
5. 次に、「Run」<img width="30" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/328136/dc745749-1382-216a-a084-e9105c21c0d4.png">をクリックします
6\.  次に、「Run Trailhead module」をクリックします。収集が実行されると、各リクエストが [All Test]タブで合格したことが確認できます。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/328136/b93b046e-12a9-2a6b-87ae-77cec0b79c13.png)

# Get and Set Variables

**変数のスコープを調べる**

Postman には、さまざまなタスクに適したさまざまな変数スコープがあります。

|変数	|範囲	|値の種類|
|:----------|:----------|:----------|
|Global variables|Postman リクエスト、コレクション、スクリプト、環境間のデータにすべて単一のワークスペース内でアクセスします。|一般的に使用されるが、頻繁には変更されない値 (ausernameや など)country|
|Collection variables|コレクション内のリクエスト全体でデータにアクセスします。|特定のコレクションに限定された値|
|Environment variables|一度に 1 つのコレクションで使用されるデータにアクセスしますが、他のコレクションでも移植可能に使用できます。 |一度に 1 つのコレクションで使用されるデータにアクセスしますが、他のコレクションでも移植可能に使用できます。 |
|Local variables|単一のリクエストまたはコレクションの実行内でアクセスします。|実行が終了すると保持されない一時的な値|
|Data variables|NewmanまたはCollection Runnerを介したコレクションの実行中に、外部 CSV または JSON ファイルからアクセスします。|何百ものテストシナリオをループする値|

同じ名前の変数が 2 つの異なるスコープで宣言されている場合、最も狭いスコープの変数に格納されている値が使用されます。たとえば、両方とも という名前のグローバル変数とローカル変数がある場合username、リクエストの実行時にローカル値が使用されます。

**テキストフィールドで変数を使用する**

Postman リクエスト ビルダーのテキスト領域では、リクエスト URL やパラメータと同様に、二重中括弧を使用して変数を参照できます。任意のスコープで新しい変数を作成するためのショートカットを学びましょう。 

1. Pictures from November 2020を選択します。
2. リクエスト URL フィールドで、変数にしたいデータを強調表示します。この例では、 ですDEMO_KEY。
3. これにより、対話型のツールチップが開きます。[Set as variable]をクリックします。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/328136/23d3c340-0adc-6a4f-f0f9-175e1ada96ed.png)

4\. [Set as a new variable]をクリックします。
5\. 変数に名前を付けますnasa_api_key
6\. ドロップダウンリストからコレクションスコープを選択します ( Collection: Trailhead module )。
7\. [Set variable]をクリックします。
8\. 新しい変数の上にマウスを移動して、変数の詳細を確認します。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/328136/ef8d29ab-2eb1-2a12-3472-cfb89785c7fd.png)

9\. 次に、他のリクエストに対しても同じことを行います。新しい変数を使用すると、いくつかの手順を省略できることに注意してください。

**コードエディタで変数を使用する**

変数を手動で編集する代わりに、[Pre-request Script ]タブと[Tests]タブのリクエスト スクリプトで JavaScript を使用して、プログラムで変数を定義および参照することもできます。 

1. Trailhead モジュール コレクション内で、[ Pre-request Script]タブをクリックします。
2. [Get a collection variable]を選択します。
3. 次に、「Set a collection variable」を選択します。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/328136/d3d006cb-24fd-1a31-0f67-499f7ec37ee6.png)

Postman は変数を文字列として保存します。オブジェクトまたは配列を保存する場合は、JSON.stringify()保存する前と取得するときに値を覚えておいてくださいJSON.parse()。

**チェーンリクエスト**

Postman で変数をプログラム的に定義および参照する方法がわかったので、リクエストを連鎖させることができます。つまり、変数を使用して、1 つの応答からデータを抽出し、他の要求で使用します。

「Retrieve image」という 3 番目のリクエストをコレクションに追加して、リクエスト URL に対して GET リクエストを実行します{{nasa_image_url}}。 

1. Trailhead モジュール コレクションの上にマウスを置き、![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/328136/2bf4786f-d5cc-f403-d980-8de6e5459b94.png)をクリックします。3 つの点で示されたその他のアクションのアイコン
2. [Add request]をクリックします。
3. 新しいリクエストの名前を変更しますRetrieve image
4. リクエスト URL フィールドに「 」と入力します{{nasa_image_url}}。この変数は現時点では何も意味を持ちません。いくつかの手順で変更します。
5. 「Save」をクリックします。
6. ここで、 「Pictures from November 2020」に戻るをクリックしてください。
7. 「Tests」タブをクリックします。
8. pm.collectionVariables.set("nasa_image_url", pm.response.json()[0].url)エディターに入力します。nasa_image_urlNASA サーバーから応答を受け取ると、このスクリプトは変数を定義します。
9.  「Save」をクリックします。
10. 次に、[Send]をクリックします。

pm.collectionVariables.set()関数を使用してコレクション変数を設定しています。この関数は 2 つのパラメータを受け取ります。最初のパラメータは、 のような文字列としての変数 key ですnasa_image_url。2 番目のパラメータは変数値です。この例では、 pm.responseオブジェクトを使用して応答データにアクセスしています。

コレクション変数エディターを見て、Postman が新しい変数を設定したことを確認します。この場合、2020 年 11 月の画像の配列の最初の画像 URL です

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/328136/50e37381-4439-5c14-ccbb-d5dbd086a12a.png)

1. 「Retrieve image」に戻ります。
2. 上にマウスを移動する{{nasa_image_url}}と、新しい変数が機能するようになったことを確認します。
3. 新しいリクエストで[Send]をクリックして画像を取得します。

# Provide Authorization Credentials

**認証の詳細を構成する**

Postman から送信するリクエストと一緒に認証の詳細を渡すことができます。認証データは、リクエストのヘッダー、本文、またはリクエストのパラメーターとして含めることができます。

各リクエストにクエリ パラメーターとして API キーを含める必要があります。これを実際に見てみましょう。

1. 「Picture of the Day」を選択します。
2. クエリパラメータの選択を解除しますapi_key。
3. 更新を保存します。
4. 次に、「Send」をクリックします。エラー応答が表示されます。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/328136/b9517861-a19a-c259-daf3-a160c39d95b1.png)

api_key Pictures from November 2020もクエリ パラメーターの選択を解除してください。

アップデートを 必ずSaveしてください。

**認可ヘルパーを使用する**

リクエスト ビルダーの「認証」タブで、Postman がリクエストの関連部分に自動的に入力するように認証の詳細を入力および構成できます。リクエスト、フォルダー、またはコレクションに対して承認ヘルパーを使用できます。

Trailhead モジュール コレクション内のすべてのリクエストは同じ認証タイプを必要とするため、コレクションに認証ヘルパーを追加しましょう。 

1. Trailhead moduleを選択します。
2. 「Authorization」タブをクリックします。
3. 「Type」ドロップダウンから「API Key」を選択します。
キーと値のペアを入力します。
Key：api_key
Value：{{nasa_api_key}}
5. [追加先] ドロップダウンから[ Query Params]を選択します。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/328136/04e887a3-c6b9-19a3-6fc3-fd42392af337.png)

6\. 変更をSaveします。
7\. 保存したリクエストをクリックします。Postman が[Params]タブに適切な資格情報を自動的に追加していることがわかります。

変数とコレクションを使用して承認の詳細をより安全かつ効率的に定義することを忘れないでください。これにより、同じ情報を複数の場所で再利用できるようになります。リクエストをコレクションとフォルダーにグループ化すると、グループ全体で再利用する認証の詳細を指定できます。

# Debug and Troubleshoot Unexpected Behavior

予期しない動作をデバッグする
API が期待どおりに動作しない場合は、Postman コンソールを使用してデバッグを支援します。 

Postman の左下のアイコンからコンソールを開きますコンソール。<img width="90" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/328136/2352aa50-b699-15ed-2441-172761ff4140.png">Postman は、すべてのリクエストを生の形式と美しい形式の両方で記録します。これらのネットワーク呼び出しからのヘッダー、証明書、要求、および応答を検査できます。実際に見てみましょう。

コレクション内の 2 番目のリクエストを送信し、コンソール出力を検査します。

1. Pictures from November 2020を開きます。
2. [Send]をクリックします。
3. 次に、コンソール Postman の左下をクリックします。
4. 最新のリクエストを展開してログを調べます。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/328136/ef352ad4-32ca-0301-56b3-22757873d529.png)

次のリクエストを実行する前にコンソールをクリアするには、「Clear」 をクリックします。<img width="60" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/328136/4270c848-e318-bf90-15bd-c029f959a72e.png">

**コンソールステートメントの挿入**

スクリプト内の適切な場所でログ ステートメントを使用すると、問題の原因を特定するのに役立ちます。コードが正しい順序で実行されていることを確認し、特定の時点での変数の値を検査できます。

2020 年 11 月の画像がまだ開いている状態で、 [Tests]タブの最初の行に次のコードを挿入します。console.log(`From the Tests tab, number of pictures is: ${pm.response.json().length}`)
リクエストを送信し、コンソール出力を検査します。ステートメントの応答が表示されます。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/328136/4226bef5-5d00-3b53-9bd3-916df4c02c9b.png)