Postman Flowsの基本 / Postman Flows Basics

Slides for:
- Event Drinven Architecture Multi Vendor ワークショップ at https://serverless.connpass.com/event/342157/

概要
これはPostman Flowsの基本をカバーする資料です。Postman Flows は、画面上でAPIのブロックをつなげることでワークフローの作成やアプリ連携、作業の自動化を行うことができる、APIプラットフォーム Postman で利用できるビジュアルツールです。

https://www.postman.com/product/flows/

Transcript

1. All rights reserved by Postman Inc Postman Flowsの基本 川崎庸市 テクノロジーエバンジェリスト
2. テクノロジーエバンジェリスト Postman株式会社 川崎 庸市 / Yoichi Kawasaki @yokawasa @postman_japan
3. Postman ツール利用オプション Postman Desktop App Postman Web Postman VS Code Extension Postman CLI
4. 日本語化してみましょう アプリ画面右上の⚙をクリック > Settings > General > Application > Languageで日本語選択 @postman_japan
5. 自動保存の設定をしてみましょう アプリ画面右上の⚙をクリック > 設定 > 一般> アプリケーション> 自動保存をチェック @postman_japan
6. Postman Flowsの基本 @postman_japan
7. Postman Flowsとは？ API中心のアプリ(ワークフロー) を構築するためのビジュアルエディターです • 複数のAPIの連携、データの加工、出力結果の可視化など一連のアクションの自動化 ◦ サービス連携処理、自然言語処理、DevOps処理、など • 既存のコレクションにある APIリクエスト設定や環境 Environment)を活用可能 • フロー用のWebhookエンドポイントを公開して、外部からフローをトリガー可能 • 公開済みフローを自分のワークスペースにフォークやコピーして利用できる ベータリリース 2025.02時点)
8. Postman FlowsとフローFlow • Postman Flows : ワークフロー構築のためのビジュアルエディター • フロー（Flow）: Postman Flowsで構築するワークフローのこと フロー フロー一覧 Postman Flows
9. Postman Flows ユーザーインターフェース https://learning.postman.com/docs/postman-flows/gs/the-flows-interface/ グループ化 その他ブロック Startブロック 注釈(annotation) コンソール Webhook ツールバー Runボタン 注釈追加 ミニマップ @postman_japan
10. Postman Flows カタログ Flowsカタログでは様々なカテゴリーの便利なフローを探索しテンプレートとして活用できます。ニーズに 合ったフローを見つけて自身のワークスペースにコピーして利用できます https://learning.postman.com/docs/postman-flows/gs/flows-catalog/ フロー探索方法 • サイドバーメニューのフローを選択 • 「＋」をクリックして「Discover Flows Catalog」 を選択 • カタログのカテゴリや検索フォームなどを通じて フローを探索 • 目的のフローで「Use this Flow」をクリックして 自分のワークスペースにコピー
11. Flows 2大コンセプト: ブロックとコネクション ブロック Blocks ブロックでは情報作成、決断、アクション実行などができ る。各ブロックには入力・出力口（いづれか or 両方）があ りコネクションで複数ブロックを連携させることができる コネクション Connections) コネクションはブロック同士を相互作用させる方法。あるブ ロックの出力から別のブロックの入力にコネクションをドラッ グすることで、結合先ブロックに情報を渡したり実行させた りすることができる @postman_japan
12. ブロックの種類 Postman Flows Block https://learning.postman.com/docs/postman-flows/reference/blocks-list/ アクション SendRequest リクエスト送信 Create with AI BETA AIモデルを活用して出力 を生成 Delay 指定した時間待つ トリガー Start フローを開始 意思決定 If FQL/TypeScriptを使用して データを true/false別の出 力に分岐 Evaluate FQL/TypeScriptを使用して データ取得・操作を行う 繰り返し Collect ループの結果を収集 For 要素リストをループ Repeat 指定した回数ループ 出力 Output 受信データを表示し、後続 ブロックに転送 Log Postmanコンソールにロ グ出力 その他 Group ブロックをグループ化 情報 String テキスト文字列を出力 Bool true/falseを出力 Number 数値を出力 Null null値を出力 Regex 正規表現文字列を出力 Select 入力の特定部分を選択 Now 現在日時を出力 Date 指定日付を出力 Date & Time 指定日時を出力 List 順序付きリストを出力 Record 名前付きデータ出力 Create Variable 新しい変数作成 Get Variable 変数の値を出力 Template テンプレート出力 @postman_japan
13. リクエストと変数 Postman FlowsでのAPIリクエスト送信設定と関連する変数の追加について https://learning.postman.com/docs/postman-flows/concepts/requests-and-variables/ SendRequestブロックでコレクションにあ るAPIリクエストを選択 APIリクエスト例 ここでは変数 value1,value2を設定 もしワークスペースにコレクションがない場 合は６つのよく使われるプリセットされたリク エストが表示される リクエストに関連する変数が 自動検知される SendRequestブロック 変数やスクリプトの設定が可能 @postman_japan
14. Selectブロックで特定データの取得 Selectブロックにより、あるデータの中から特定部分を取得できます https://learning.postman.com/docs/postman-flows/concepts/selecting-information/ SendRequestブロックで取得した結果からSelectブロックで特定のデータを取得 Selectブロック @postman_japan
15. 複数リクエスト間のデータ連携 あるブロックの出力を他ブロックの入力として活用して複数リクエスト間のデータ連携を実現します https://learning.postman.com/docs/postman-flows/concepts/passing-information-between-blocks/ https://learning.postman.com/docs/postman-flows/tutorials/send-information-from-one-system-to-another/ 中間のselectブロックで値を抽出して他ブロックに送信 するパターン ブロックの中で直接 selectブロックを活用して値を抽出 するパターン @postman_japan
16. フローのローカル実行テスト • クラウド公開前のフローはRunボタン押下でStartブロックからローカル実行できます • 一度フローを公開したら、WebhookメニューのPreviewよりローカル実行できます。この場合、 Webhookをシュミレートできます @postman_japan
17. フローの公開 Publish)と実行 1/2 フローをクラウド公開 Publish)すると、そのフローをWebhook から実行できるようになります https://learning.postman.com/docs/postman-flows/concepts/automatic-runs/ Webhookリクエスト簡易情報 エンドポイント Webhookのプレビュー実行 @postman_japan
18. フローの公開 Publish)と実行 2/2 フロー公開後、そのフローのライブログを確認することができます 「･･･」メニュー > [view published version] > View Live log] フロー公開後の注意点 • 公開後にフローに変更を加えたら、再公開Publish]しない限りクラウドに反映されません • 関連するコレクションと環境に変更を加えた場合も再公開が必要になります（フロー公開毎に Postmanは関連コレクションと環境変数・コレクション変数情報をセットで保存します。なお、グローバ ル変数はセットで保存されないので注意）
19. フローの整理: 色、注釈、グループ化 色、注釈、グループ化を活用してすることでフローを整理し、見通しやすくできます https://learning.postman.com/docs/postman-flows/concepts/organizing-a-flow/ ブロック左上隅のペイントアイコンから 設定 色 注釈 グループ化 ツールバーの「テキストの追 加」ボタンを押して追加 Shift キーを押しながらカーソルをブロックの セットの周囲にドラッグするか、 ⌘またはCtrl を押したまま追加するブロックを選択。ファイル アイコンを選択するとグループが作成される @postman_japan
20. フローの定期的な実行 公開後のフローはWebhookから実行できるため、様々な方法でスケジュール実行がきるようになります。 ここではPostmanモニターを活用したスケジュール実行の設定方法を紹介します https://learning.postman.com/docs/postman-flows/tutorials/make-your-own-automatically-scheduled-tasks/ @postman_japan 2.コレクション作成 発行されたWebhookへ のリクエスト設定とコレク ション作成 3.モニターの作成 - コレクション関連付け - 実行頻度設定 1.フローの公開 これでWebhookが 発行される Webhook URL コレクション 定期実行頻度
21. Postmanモニターについて Postmanモニターを使うと、関連付けられたコレクションのリクエストを定期的に実行して、APIの健全性と パフォーマンスを継続的にチェックできます 参考情報 https://learning.postman.com/docs/monitoring-your-api/setting-up-monitor/ Postmanモニターでできること • コレクションごとにモニターを設定 • テスト実行頻度 ◦ 5分毎〜設定可能。ただし無料プランは一時間毎〜 • テスト実行リージョン選択 ◦ 複数リージョンからの APIテスト実行が可能 • スタティックIPを持つモニター指定 ◦ 要Professional / Enterpriseプラン • アラート通知設定 ◦ メール通知、or インテグレーション設定 でslack、 PagerDutyなど他チャンネルへの通知も可能 • リトライ、タイムアウトなど設定可能 @postman_japan
22. フローのデバッグ 1/2 SendRequestブロックでSuccessポートもしくはFailureポートをみてAPIリクエスト送信結果を確認 https://learning.postman.com/docs/postman-flows/reference/debugging/ @postman_japan
23. フローのデバッグ 2/2 OutputブロックやLogブロックを活用してフロー中の特定情報を出力する https://learning.postman.com/docs/postman-flows/reference/debugging/ Outputブロック Logブロック • すべての送信されたリクエストとレスポンス情報は Postman コンソールに 出力される • Logブロックに送信された内容はコンソールに出力される @postman_japan
24. 意思決定ブロックにおけるFQLとTypeScriptの活用 意思決定の役割を担うEvaluationとIfの2つのブロックにおいて、そのロジックの記述にFQL Flows Query Language)またはTypeScriptのいづれかの言語を選択できます 言語選択 Evaluationブロック Ifブロック @postman_japan
25. Postman FlowsでのPostbotの活用 AIアシスタントPostbotがフローの構築とデバッグをサポート。 Postbotにプロンプトで指示を与えると、必要なブロックを追加 したり、FQLやTypeScriptを書いてくれる。また、フローのエラーを修正することもできる。 https://learning.postman.com/docs/postman-flows/gs/postbot-in-flows/ Postbotでフローの構築（ブロック追加） エラーの修正 @postman_japan
26. Flows Query Language FQLの概要 FQLはAPIリクエストや他のブロックから取得したデータをパースして必要なフィールドを取得したり、操作、 集約するために使用できる式言語 Expression Language) https://learning.postman.com/docs/postman-flows/flows-query-language/introduction-to-fql/ EvaluateとIfブロックの中で使用可能 FQLでできること • 基本値の取得 • 条件付きデータ選択 • 構造化データの返却 • データ操作 @postman_japan
27. FQL - 値の取得 FQLでは、ロケーションパス構文を使用してJSON構造から値を抽出する Get basic values in FQL https://learning.postman.com/docs/postman-flows/flows-query-language/getting-basic-values/ トップレベル フィールドの値 name ネストされたフィールドの値 address.city 配列の特定インデックスの値 phone[0.number 配列内の全オブジェクトの特定フィールドの値 phone.number ["1234567890","0987654321"] "1234567890" "John Smith" "Atlanta" ⇒ ⇒ ⇒ ⇒ @postman_japan
28. FQL - 条件付きデータの取得 FQL を使用して、特定のデータをフィルターできます。該当データが複数ある場合は配列で、単一の場合 はは単一のレコードとして返却されます 特定キー・値ペアのオブジェクトをフィルター payments[description="recurring subscription"] フィルターされたオブジェクトの特定フィールド値取得 payments[description="recurring subscription"].invoice_number [ { "invoice_number": "101301", "date": "20220911T161234.494Z", "description": "recurring subscription", "amount": 110.48 }, { "invoice_number": "101303", "date": "20221011T161234.683Z", "description": "recurring subscription", "amount": 110.48 } ] ⇒ ["101301","101303"] ⇒ Select conditional data in FQL https://learning.postman.com/docs/postman-flows/flows-query-language/conditional-data-selection/
29. FQL - データ操作のための豊富な関数 文字列関連 文字列の長さを取得 文字列の一部を返す 文字列を数値に変換する パターンが最初に出現する前の文字列を取得 パターンが最初に出現した後の文字列を取得 文字列をすべて大文字に変換します 文字列をすべて小文字に変換します 文字列をトリムする 文字列をパディングする 文字列をコンポーネントの配列に分割する 文字列の配列を単一の文字列に結合します ある文字列を別の文字列に置き換えます Base64で文字列をエンコードする Base64で文字列をデコードする 文字列をJSONに変換する 数値関連 数値を合計する 2 つの数値の差の絶対値を取得します 数値を切り上げます 数値を切り捨てる 数値の累乗 数値の平方根を取得します 数値を 16 進数または 2 進数に変換する 新しいランダムな請求書番号を生成します 数値を文字列に変換 URL関連 URLコンポーネントをエンコードする URLコンポーネントをデコードする URL全体をエンコードする URL全体をデコードする 日付・時間関連 現在時刻を ISO 8601 形式で取得します エポックからの現在時刻を Unix ミリ秒単位で取得 特定の日付形式から Unix エポック時間に変換 Unix エポック時刻から特定の日付形式に変換 日付から日 /月/年を取得する 日付から時間を取得する 日付から曜日を取得する 2 つの日付を比較する 日付を 1 日増やす 2 つの日付の差を取得する 時刻と日付の形式 ロジック・配列操作関連 配列に追加する If-then-else 配列を分割する 配列内の各値に対してアクションを実行 値のフィルター 配列を単一の値に折りたたむ 配列をソートする オブジェクト操作 オブジェクト内の各値に対してアクションを実行 Manipulate data in FQL https://learning.postman.com/docs/postman-flo ws/flows-query-language/data-manipulation/ FQL function reference https://learning.postman.com/docs/postman-flo ws/flows-query-language/function-reference/
30. FQL - 日本語資料 • Postman Flows FQLサンプル https://qiita.com/nagix/items/adb1b7f484fc8167c046 • Postman Flows FQL関数 https://qiita.com/nagix/items/2a79a0899c4765f0af97
31. TypeScriptの活用 意思決定の役割を担う EvaluationとIfの2つのブロックにおけるロジック記述言語として TypeScriptも活用 できます。FQLで実現できないロジック（例 : 暗号化）を必要とする関数を直接実装できます https://learning.postman.com/docs/postman-flows/concepts/flows-typescript-support/ @postman_japan TypeScript記述における制約 • ライブラリのimport/requireができない • ファイルシステムアクセスができない • スクリプトからAPI呼び出しができない その他ポイント • Web Crypto API、SHA256ハッシュ、AES暗号化、 セキュアな乱数生成など、様々な暗号化機能が用意さ れている • 次の関数でコンソールへのログ出力が可能 : console.log, console.error, console.warn, console.info
32. Postman Flowsの Tips ＆ ハマりどころ @postman_japan
33. 変数の初期値・現在値の保存先 Postmanクラウド ブラウザアプリ デスクトップアプリ 同期 同 期 初期値 現在値 現在値 初期値 初期値 変数 変数 ローカル ローカル 変数 現在値 コピー(*) (*) - 初期値更新時に同じ値を現在値にコピー
34. フローの実行場所・実行バージョンと保存先 未公開 フロー 未公開 フロー 未公開 フロー 公開済 フロー ブラウザアプリ デスクトップアプリ Webhook 公 開 (*) ローカル ローカル Postmanクラウド 同期 同 期 フロー コレクション 環境・コレクション変数 (*) - その時点のフローと関連コレクション、変数 (環境 / コレクション変数)がセットで保存される
35. Postman Flowsでの変数活用の注意点 公開済フローの実行時 Postmanクラウドで実行) • 環境変数・コレクション変数は定数 Read-only)としてのみ活用可能であり、フロー実行時に変更できない ◦ フロー実行時にAPIリクエストのスクリプト (pre-request|post-response)で変更できない • フロー実行時にグローバル変数を活用できない（公開済みフローの一部として保持されない） 未公開フローの実行時 (ローカルクライアント側で実行) • 環境変数・コレクション変数・グローバル変数、いづれもフロー実行時に変更可能な変数として活用できる
36. Postman Flowsにおける秘匿情報の扱い方 秘匿情報を活用するフローを公開して実行（クラウドで実行）する場合は、秘匿情報を次のように格納す ることを推奨する • 秘匿情報は環境変数として格納し、変数タイプはシークレットで、初期値にも現在値と同じ値を設定する ◦ 公開済みフローをクラウドで実行するときは、変数の初期値に設定した値が活用される。一方、ローカル実行時には現在値 が活用される ◦ 公開済みフロー実行時にはグローバル変数を活用できない（公開済フローの一部として保持されないため） ◦ なお、フローを公開して実行しない（ローカルのみで実行する）場合は、初期値に秘匿情報を設定する必要はなく、また環境 変数以外にもグローバル変数や Postman Vaultの活用が可能 • パーソナルワークスペース、or 最低限のアクセス共有レベルのワークスペースを活用する ◦ 上述の通り、秘匿情報を環境変数の初期値にも設定する必要がある。初期値はクラウド同期され、従ってそのワークスペー スにアクセス可能なメンバーにも共有されることになる。 ◦ もしパーソナルワークスペース以外を活用する場合は、初期値がクラウド同期されることを意識し、プライベートやチームワー クスペースなど最低限のアクセス共有レベルを持つワークスペースを選択ください
37. 複数リクエスト間のデータ連携におけるTips 複数リクエスト間のデータ連携には、コレクション変数や環境変数を使うのではなく、実行時のフローのブ ロック間で直接渡すことを推奨 1. フローの中で直接あるSendRequestブロックのOutputを別のSendRequestブロックのInputとして渡す 2. データの加工が必要ならば、SelectやEvaluate ブロックを活用する 環境変数・コレクション変数 は定数 Read-only)として のみ活用可能であり、フロー実行時に変更可能な変数 として活用できない 「Postman Flowsでの変数活用の注意点 」
38. Webhookに送信するBodyデータ形式における注意点 公開済みフローのWebhookに送信するBodyデータはJSON形式である必要がある • 公開済みフローのWebhookに対してJSON以外の形式でBodyデータを送信するとフロー実行時に下記のようなエラーが Consoleに出力されフロー内で送信されたBodyデータが取得できない • Webhook Previewを通じたローカルフローの実行においては、JSON以外の形式であっても問題なく送信されたBodyデー タを取得できる
39. Postman Flows 学習リソース @postman_japan
40. Postman Flows 参考情報 • Postman Flows ラーニングセンター https://learning.postman.com/docs/postman-flows/gs/flows-overview/ • Postman Flowsブロック https://qiita.com/nagix/items/2ebedd0273e7eb13c2cf • Postman Flows FQLサンプル https://qiita.com/nagix/items/adb1b7f484fc8167c046 • Postman Flows FQL関数 https://qiita.com/nagix/items/2a79a0899c4765f0af97 • Postman Flows スニペット https://www.postman.com/postman/postman-flows/flow/663b2f59c5d21c003d361465
41. 学習リソース @postman_japan
42. Postman Flows • Postman Flowsオンラインワークショップ資料 2024年9月実施) ◦ Postman Flows オンラインワークショップ (スライド) • Postman Flows ハッカソン資料 2024年5月実施) ◦ Postman Flows オンラインハッカソンセミナー (スライド) ◦ Postman Flows オンラインハッカソンセミナー YouTube) • Postman Flowsブロック https://qiita.com/nagix/items/2ebedd0273e7eb13c2cf • Postman Flows FQLサンプル https://qiita.com/nagix/items/adb1b7f484fc8167c046 • Postman Flows FQL関数 https://qiita.com/nagix/items/2a79a0899c4765f0af97
43. 変数 参考情報 • Postman Learning Center - 変数 https://learning.postman.com/docs/sending-requests/variables/variables/ • 徹底解説 Postman 変数 https://qiita.com/yokawasa/items/05913df60aea07395903
44. Postman AI Agent Builder https://www.postman.com/product/ai-agent-builder/
45. Postman AI Agent Stack
46. Postman Connpassページ https://postman.connpass.com @postman_japan
47. Postman Japan コミュニティ Discord Discord サーバーを開設しました！ 今後 Postman のプロダクトアップデートやイベン ト情報の配信や、みなさんとの交流の場として活 用していきたいと思います。 https://discord.gg/G4SQWDDqVa @postman_japan
48. ありがとうございました @postman_japan
49. All rights reserved by Postman Inc APPENDIX
50. ワークスペース @postman_japan
51. ワークスペースとは？ ワークスペース内のコレクション、API 定義、環境、モック、モニターなどへの共有アクセスをチームや世界 に提供し、組織や世界をまたいだシームレスなコラボレーションを支援します コラボレーションハブ ワークスペース（パブリック） ワークスペース内の コレクション群 ワークスペース コレクション API API ビルダー) 環境 フロー @postman_japan
52. ワークスペースとは？ 5 種類のワークスペースがあり、それぞれ異なる共有アクセスレベルを提供します パーソナル 自分だけがアクセス可能 プライベート ワークスペース作成ユーザーとそのワークスペースに招待されたチー ムメンバーのみアクセス可能。要 Professional プラン チーム 全てのチームメンバーだけがアクセス可能。設定可能なチームメン バー数はプランによって変わる（無料は 3 名まで） パートナー ワークスペース作成ユーザーとそのワークスペースに招待されたチー ムメンバー、およびパートナーとして招待した外部ユーザーのみアクセ ス可能。要 Professionalプラン パブリック 世界中の誰もがアクセス可能。パブリック API ネットワークに API を公 開するにはワークスペースをパブリックする必要がある ワークスペースの種類 @postman_japan
53. コレクション @postman_japan
54. コレクションとは？ コレクションは、実行可能な関連APIリクエスト（群）の集合です。コレクション単位で（もしくはコレクションに 関連付けて）モックサーバー、モニター、テストスイートなど主要なPostman機能が利用できます コレクション APIリクエスト テスト サンプル APIリクエスト テスト サンプル APIリクエスト テスト サンプル コレクションでできる主なこと • 複数APIリクエスト、関連レスポンス、テストの定義 • ワークフロー定義（リクエスト呼び出しのシーケンス） • リクエスト・テスト実行の自動化（コレクションランナー活用） • コレクション単位の文書化 • モックサーバー利用（コレクション単位） • モニター利用（コレクション単位） • チームメイトや利用者とのコラボレーション ◦ フォーク（Fork） ◦ プルリクエスト ◦ コメント 他にもいろんなことができます
55. コレクションとは？ コレクション フォルダー APIリクエスト
56. 変数 @postman_japan
57. 変数 変数として保存された値はPostman内で {{変数名}}表記で再利用できます • 変数の種類 ◦ グローバル変数 ◦ コレクション変数 ◦ 環境変数（Environment） • 変数スコープ ◦ 変数の種類ごとに異なる • 変数タイプ ◦ default ◦ secret (グローバルと環境変数のみ) • 動的変数 ◦ {{$guid}}, {{$timestamp}}, {{$randomInt}}, etc. 変数スコープ 変数関連参考資料 - Store and reuse values using variables - Group sets of variables in Postman using environments - 徹底解説 - Postman 変数 Variables) 同じ名前の変数が2つの異なるスコープで宣言されている場合、狭 い方のスコープの変数に格納されている値が使用される 変数 @postman_japan
58. 変数 使用例 （１）リクエストURLの一部に対しての変数使用例 （３）クエリーパラメータの変数使用例 （２）ヘッダーでの変数使用例 （４）リクエストボディでの変数使用例 変数
59. 初期値と現在値 • 初期値：サーバーに保存され、そのコレクションまたは環境にアクセス可能なユー ザー（メンバー）に共有される • 現在値：API リクエストで利用される値。ローカルにのみ保存され、誰にも共有され ない 初期値 現在値
60. 秘匿情報の扱い方 - 変数の活用 変数を活用した秘匿情報に扱いについてのポイント • 環境変数、もしくはグローバル変数として設定する • 各変数の初期値に秘匿情報を入力しない • 変数タイプをシークレットにする ◦ シークレットタイプは表示上マスクされるだけであることに注意 @postman_japan
61. 秘匿情報の扱い方 - Postman Vaultの活用 Postman Vaultを活用した秘匿情報に扱いについてのポイント • Postman Vaultと呼ばれるPostmanローカルインスタンスに格納する ◦ 機密データをPostmanのローカルインスタンスにのみ保存して再利用できる仕組み。データは Postman Vault 内で暗号化され保存される ◦ Postmanクラウドには同期されない（共同作業者が Vaultにシークレットの使用を防ぐ） ◦ デフォルトでVault シークレットはマスクされている ◦ [注意] スクリプトからVaultシークレットを設定したりアクセスはできない @postman_japan [補足] Enterpriseプランかつ Advanced Security Administration アドオンを購入することで外部Vaultインテ グレーションの活用も可能。外部 Vaultインテグレーションにより外部キー管理サービスに格納されたシークレット 情報を Postman 変数として利用可能。サポートされている外部キー管理サービスに、 1Password、AWS Secrets Manager、Azure Key Vault、HashiCorp Vaultなどがある。 参考情報