All rights reserved by Postman Inc やさしい Postman API 入門 草薙 昭彦 テクノロジーエバンジェリスト #PostmanMeetup

テクノロジーエバンジェリスト Postman 株式会社 草薙 昭彦 @postman_japan @nagix

はじめての Postman - 何に使うと便利なの？ @postman_japan API のトラブルを 調査して解決 API 認証を スマートに行う API リクエスト送信と レスポンスの確認 よく使うリクエストを 整理しておく

Postman のはじめ方 - サインアップ @postman_japan https://identity.getpostman.com/signup まずは Postman アカウントを作成 ● Postman アプリで作成したデータは Postman クラウドに保存されます ● 同じ Postman アカウントを使えばどこ からでもデータにアクセスできます 必要な情報 ● メールアドレス ● ユーザー名（英数字とハイフン） ● パスワード（7文字以上） 日本語を選べます

デスクトップアプリと Web アプリ @postman_japan サーバー API エンドポイント Postman デスクトップアプリ （要インストール） Postman Web アプリ （インストール不要） クライアント クライアント ブラウザー Postman クラウド ユーザーデータ リクエスト レスポンス リクエスト レスポンス

Postman アプリ画面 @postman_japan ヘッダー サイドバー 右サイドバー フッター ワークベンチ

日本語化してみましょう ヘッダー右側の ⚙ をクリック > Settings > General > Application > Languageで日本語選択 @postman_japan

API リクエストの作成 @postman_japan まずはサイドバーで「新しいコレクションを作成」→ コレクションに「リクエストを追加」

API リクエストの作成 - GET リクエスト @postman_japan わかりやすいリクエストの名前をつける GET メソッドを選択 エンドポイントの URL を入力 保存を忘れずに リクエストはタブとして切り替えられる パラメーターなし

API リクエストの作成 - GET リクエスト @postman_japan クエリパラメーターあり キーと値のペアを入力 チェックを外せば無効にできる 説明はリクエストの送信には使われない キーと値は URL に反映される パラメータータブを選択

API リクエストの作成 - GET リクエスト @postman_japan パス変数あり 値を入力 「/:<キー名>」を URL に付けるとパス変数テーブルに反映される

API リクエストの作成 - POST リクエスト @postman_japan x-www-form-urlencoded 形式 ボディタブを選択 POST メソッドを選択 x-www-form-urlencoded 形式を選択 キーと値のペアを入力

API リクエストの作成 - POST リクエスト @postman_japan JSON 文字列形式 Raw 形式を選択 JSON を入力 「整形」はインデントや改行を整えてくれる JSON 文字列を入力

API リクエストの作成 - ヘッダーのカスタマイズ @postman_japan ヘッダータブを選択 キーと値のペアを入力

レスポンスの確認 @postman_japan 送信をクリック ボディを選択 整形を選択 レスポンスボディを見る ステータスコードを確認 レスポンスボディを見る 表示形式を指定できる レスポンスボディ内を検索

レスポンスの確認 @postman_japan レスポンスの詳細情報を見る ネットワーク情報 ステータスコード レスポンス時間 レスポンスサイズ

レスポンスの確認 @postman_japan ヘッダーを選択 レスポンスヘッダーを見る キーと値を見る ｉにマウスを合わせると説明が見られる

コレクションを使ってリクエストを整理する @postman_japan ワークスペース コレクション - API v2 コレクション - API v1 フォルダー - 在庫管理 フォルダー - ユーザー管理 GET リクエスト - 在庫一覧 POST リクエスト - 在庫追加 プロジェクトやバージョン毎にコレ クションを作成 フォルダーを使って階層構造を作 りリクエストを整理する

API 認証 @postman_japan セキュリティや利用量の追跡のために、通常は API を使うには認証が行われます。 API 認証は、API ドキュメントに書かれている方法に従って設定します。 代表的な認証の方法 Bearer トークン OAuth 2.0（Bearer トークンを利用） クライアント サービス提供者 アクセストークン API コール サービス提供者 アイデンティティプロ バイダー クライアント 連携 認証・アクセス トークン発行 サービス 情報 API コール *Bearer トークンでの認証で、どのようにアクセストークンを入手するかは様々。 OAuth 2.0 は代表例だが、JWT など他の方法もある

API 認証 @postman_japan API 認証については、2024年2月22日にオンラインワークショップを開催予定🚀 Bearer トークン アクセストークンを入力 Bearer トークンを選択 認証タブを選択

API 認証 @postman_japan OAuth 2.0 OAuth 2.0 を選択 トークンの設定を設定後、トークンを取得すると取得し たトークンが自動的に入力される

API のトラブルシューティングの基本 @postman_japan ● ステータスコードは返ってきているか？ ● ステータスコードの内容は？ 例: 認証が失敗 ステータスコードが 401。レスポンスボディにも認証されなかった旨が表示されている

API のトラブルシューティングの基本 @postman_japan ● リクエストヘッダー、ボディ、レスポンスヘッダー、ボディを確認 例: レート制限に引っかかった ステータスコードが 403。レスポンスヘッダーの Rate-Remaining が 0 になっている。レート制限に関 するヘッダーやステータスコードは API によって異なる場合があるので注意

API のトラブルシューティングの基本 @postman_japan ● デフォルトで非表示のリクエストヘッダーを、表示して確認 例: JSON で送るべきところをプレーンテキストで送ってしまった ステータスコードが 415。本来は Content-Type: application/json でリクエストすべきところを、Text 形式を選んでしまったので text/plain になってしまった ここが Text なので Content-Type が text/plain になった クリックすると表示に切り替わる

API のトラブルシューティングの基本 @postman_japan ● API 履歴を確認 ● 正常に動作した時のリクエストの詳細をチェックする 履歴を選択 過去に実行したリクエストを選択

API のトラブルシューティングの基本 @postman_japan ● デフォルトでは履歴にはレスポンスヘッダーとボディは残らないが、保存するように設定することは 可能 レスポンスに保存をオンにする

Postman よくあるハマりポイント @postman_japan リクエストでデータが送れない → POST メソッドのボディが正しく設定されていない → API が受け付ける Content-Type をよく確認する ● application/json の場合: Raw 形式で JSON を選択 ● application/x-www-form-urlencoded の場合: x-www-form-urlencoded 形式を選択 ● multipart/form-data の場合: form-data を選択

Postman よくあるハマりポイント Web アプリ利用時にリクエストが送信できない → フッターでブラウザーエージェントが選ばれていない か確認 → クラウドエージェントやデスクトップエージェント（または自動）を選択 @postman_japan エージェントって？ Web アプリでは、CORS（ドメインをまたいでリソースにアク セスできない）ポリシーのためにブラウザから直接通信がで きない場合があるため、クラウドエージェントやデスクトップ エージェントを経由した通信を行うオプションがある ブラウザーエージェント デスクトップエージェント クラウドエージェント API エンドポイント

ダウンロードして無料でスタート！ https://www.postman.com/downloads/ デスクトップアプリ ● Windows ● Mac ● Linux Web アプリ ● アカウント登録で同 じ機能をブラウザで も利用できる @postman_japan

@postman_japan ご清聴いただき、ありがとうございました