OpenAPI 仕様をオープンソース化 により、開発者が API を探索して統合することがこれまで以上に簡単になっています。今回は、これらの仕様を活用するための実用的な方法、特に Postman でそれらを使用する方法をフォローアップしてみたいと思います。
過去に Postmanで REST API のテストした経験をお持ち場合には、エンドポイント毎に Postman コレクションを作成する手作業が必要であることをご存じと思います。ただし、API が進化して連続して複数のエンドポイントを使するようになると、コレクションの作成に時間がかかり、エラーを招きやすくなる傾向があります。
OpenAPI 仕様が公開されるようになったことで、そのような苦労はもう必要ありません。Postman に直接インポートして、（ほぼ)）即座に使用できるリクエストの完全なコレクションを即座に生成できます。エンドポイントのテスト、ワークフローの構築、利用可能な運用の探索など、Postmanはプラットフォームの機能へのワンクリック ゲートウェイになります。
利用方法（Postman がインストールされている前提）
- Postmanを開き、[Collections] セクションに移動して、上部にある [Import] ボタンをクリックします。
- インポートする仕様ファイルを、次のいずれかのオプションを使用して指定します。
- リポジトリから仕様ファイルの URL（https://raw.githubusercontent.com/autodesk-platform-services/aps-sdk-openapi/refs/heads/main/oss/oss.yaml など）をコピーして貼り付けます。
- 仕様ファイルの URL（.yaml コンテンツの URL）をコピーして貼り付けます。
- (詳細) Postman を GitHub アカウントにリンクし、リポジトリの 1 つから 仕様ファイル URL を選択します。
- [Choose how to import your Specification] ダイアログで [Postman Collection] を選択します。
- Postman コレクションを作成する前に、左下に表示されている ⚙ View Import Settings に移動して次の設定になっていることを確認します（推奨）。
- Parameter generation: Schema
- Folder organization: Tags
- Enable optional parameters: false（オフ）
- Always inherit authentication: true（オン）
- [Import] ボタンをクリックしインポートします。
認証・認可
本ブログ記事執筆時点で、OpenAPI 仕様のインポートが自動設定されないのは認証/認可のフローです。Postman リクエストの認証を設定するにはさまざまな方法がありますが、最も汎用的なのはコレクション内のリクエストの使用方法に応じて、2-legged または 3-legged OAuth 認証フローを使用した Postman コレクションの設定です。
Environment（環境）
APS の Client ID や Client Secret のクレデンシャル情報を Postman の Environment – 環境 に保存すると、Postman の標準的な使用でユーザー インターフェイスに値が公開（表示）されることはなく、また、同じリクエストを異なる環境（異なる APS アプリなど）で簡単に再利用することが出来るようになります。新しい環境で Client ID と Client Secret を指定する手順は次のとおりです。
- Postman を開き、[Environments] セクションに移動して、[Create Environment] リンクをクリックします。
- 新しい環境に名前を指定します。（ここでは New Environment）
- 新しい環境変数 APS_CLIENT_ID を作成して Type を secret に設定後、 Initial value に Client ID を指定します。
- 同様に、新しい環境変数 APS_CLIENT_SECRET を作成、Type を secret に設定し、Initial value に Client Secret を指定します。
- 右上隅にある [保存] ボタンを使用して環境を保存します。
- New Environment を選択してアクティブ（チェックされた状態）にします。
2-legged Auth（2-legged 認証フロー）
Postman コレクションに 2-legged 認証フローを追加する手順は、次のとおりです。
- Postman で [Collections] セクションに移動して使用するコレクションを選択します。
- コレクションの詳細ページで [Authorization] タブに切り替えます。
- [Auth Type] を [OAuth 2.0] に設定し、[Add auth data to] が [Request Headers] に設定されていることを確認します。
- Configure New Token セクションで、トークンに名前（ここでは APS 2LO）を指定して、次の入力を設定します。
- Grant Type: Client Credentials
- Access Token URL:
{{baseUrl}}/authentication/v2/token - Client ID:
{{APS_CLIENT_ID}} - Client Secret:
{{APS_CLIENT_SECRET}} - Scope:
bucket:read data:read - Client Authentication: Send as Basic Auth Header
- 一番下にある [Get New Access Token] ボタンをクリックします。
- [MANAGE ACCESS TOKENS] ダイアログで [Use Token] ボタンをクリックします。
- コレクションの詳細ページに戻り、Auto-refresh Token オプションが有効になっていることを確認します。
- コレクションを保存します。
注: {{baseUrl}}で指定されている変数は、インポートした OpenAPI 仕様のコレクションに対して定義されていて、Variables タブで確認することが出来ます。既定値は、APS エンドポイントのベース URLである https://developer.api.autodesk.com になっているはずです。
3-Legged Auth（3-legged 認証フロー）
Postman コレクションに 3-legged 認証フローを追加する手順は、次のとおりです。
- Postman で [Collections] セクションに移動して使用するコレクションを選択します。
- コレクションの詳細ページで [Authorize] タブに切り替えます。
- [Auth Type] を [OAuth 2.0] に設定し、[Add auth data to] が [Request Headers] に設定されていることを確認します。
- Configure New Token セクションで、トークンに名前（ここでは APS 3LO）を指定して、次の入力を設定します。
- Grant Type: Authorization Code
Authorize using browser にチェックすると Callback URL フィールドにコールバック URL がグレー表示されるのでメモして 5. のアプリ設定で指定します。 - Auth URL:
{{baseUrl}}/authentication/v2/authorize - Access Token URL:
{{baseUrl}}/authentication/v2/token - Client ID:
{{APS_CLIENT_ID}} - Client Secret:
{{APS_CLIENT_SECRET}} - Scope:
data:read - Client Authentication: Send as Basic Auth header
- https://aps.autodesk.com/myapps で APS アプリに移動し、Postman によって生成されたコールバック URL を追加して、[Save changes] ボタンで設定を保存してください。
- Postman に戻り、一番下の [Get New Access Token] ボタンをクリックします。
- [MANAGE ACCESS TOKENS] ダイアログで [Use Token] ボタンをクリックします。
- コレクションの詳細ページに戻り、Auto-refresh Token オプションが有効になっていることを確認します。
- コレクションを保存します。
注: 2-Legged Auth と同様に、 {{baseUrl}}変数がインポートした OpenAPI 仕様のコレクションに対して定義されています。
Tips:
- [Get New Access Token] ボタン クリック後、次のエラーが表示される場合には、Client ID と Client Secret を設定した環境がアクティブになっていない（チェックがはずれている）可能性があります。
{ “developerMessage”:”The client_id specified does not have access to the api product”, “moreInfo”: “https://aps.autodesk.com/en/docs/oauth/v2/developers_guide/error_handling/", “errorCode”: “AUTH-001”}
- 3-Legged Auth（3-legged 認証フロー）で Authorize using browser にチェックすると、ブラウザ側での認可処理後、Postman への画面遷移を額人するポップアップが表示されます。ブラウザ設定でポップアップがブロックされていると、遷移に失敗してしまいます。
- 3-Legged Auth（3-legged 認証フロー）が正常に動作せず、Postman 起動時に次のメッセージが表示される場合には、アクセスを許可して動作を確認してみてください。
これで、Postman リクエストのコレクションを使用する準備が整いました。
※ 本記事は Using APS OpenAPI Specs with Postman | Autodesk Platform Services から転写・意訳・補足したものです。
By Toshiaki Isezaki
You must be logged in to post a comment.