Box Postmanの高度なコレクション

Yuko Taniguchi

Published in

Box Developer Japan Blog

Oct 31, 2023

この記事では、開発者が開発プロセスでAPIコレクションをより柔軟に使用できるように、Boxがどのように要求前スクリプトを変換して各種Boxアプリケーション認証を処理したかについて説明します。

Boxの従来のPostmanコレクションは、開発者がBox Platform APIを操作するための基本的なインターフェースを構成しています。

エンドポイントとメソッドの間には、約150の項目があるため、これはかなり大きなコレクションで、分野別に整理されています。

従来のコレクションには、OAuth 2.0認証しかサポートされていないため、アクセストークンは有効期限が切れた後に更新されるという問題があります。アプリケーション承認プロセスは、BoxのガイドにあるPostmanクイックスタートを使用して自動化されましたが、Postman自体もこれをサポートしています。

高度なコレクションの操作方法

Postman環境に応じて、要求前スクリプトでは環境の種類を識別してから、アクセストークンの有効期限が切れているかどうかを確認し、必要に応じて新しいトークンを取得できます。

つまり、開発者は必要な数の環境を持ち、さまざまなBoxアプリケーションを指してそれらをすばやく切り替えることができます。

これは、たとえば、クライアント資格情報許可 (CCG) で認証されたサービスアカウントを使用してアプリケーションを開発していて、そのサービスアカウントが特定のコンテンツにアクセスできるかどうかを確認する場合に便利です。

別の例としては、ダウンスコープされたアクセストークンがどの項目にアクセスできるかをテストすることが挙げられます。

このように、開発者は、特定の管理対象ユーザーのセキュリティコンテキストを常に使用するOAuth認証による制限を受けません。

以下に、環境の例をいくつか示します。

環境の使用

環境が構成されると、開発者は環境をすばやく切り替えて、リクエストに対してまったく異なるセキュリティコンテキストを使用できます。

要求前スクリプトは、環境の種類を識別し、アクセストークンの有効期限が切れているかどうかを確認します。また、必要に応じて新しいトークンを取得して、リクエストを実行します。

高度なコレクションの設定方法

それぞれの環境の種類は異なり、それぞれにclient_idやclient_secretなどの多くのパラメータがあります。環境の作成を容易にするために、この領域の自動化を目的としてPostman APIとPostmanの機能を使用し、utilitiesフォルダの下にいくつかのメソッドを投入しました。

ただし、何もせずに利用できるわけではないので、開発者は一度その設定を行う必要があります。

手順は以下のとおりです。

Postman APIキーの取得

Postman APIを使用するには、APIキーが必要です。アカウントに移動してキーを作成します。

次に、Create Environmentsフォルダに移動し、[Authorization (承認)] タブで、先ほど作成したキーを使用してグローバル変数を設定します。

ここから、Postman APIを使用してリクエストを実行できます。

ワークスペースの構成

環境はワークスペースに作成されます。そのために、workspaceidを特定する必要があります。便宜上、Get Workspacesメソッドを追加しました。ここからワークスペースのリストを取得し、正しいIDをコピーできるようになります。

環境作成の各メソッドは、{{workspaceid}}変数を受け入れます。先に進み、グローバル変数を作成し、前のリクエストのworkspaceidを設定します。

環境の作成

上の手順は一度だけ実行する必要がある点に注意してください。

最後に、環境を作成できます。最も簡単な方法は、環境名を指定し、空の環境を作成した後、変数を手動で入力することだとわかりました。皆さんにとって最も効果的な方法を試してみてください。

環境の種類ごとに、リクエスト本文に入力するパラメータが多数あります。以下のように、少なくとも環境名を設定します。

リクエストを実行したら、Boxアプリの構成から変数を入力できます。

忘れずに保存してください。

環境が動作するかどうかをテストするには、新しい環境を選択し、Test Environmentメソッドを選択して、[Send (送信)] をクリックします。

他の種類のアプリ、認証、環境も同じ方法で構成できます。

JSONウェブトークン (JWT) 認証を使用する場合は、アプリから構成ファイルが生成される可能性が高くなります。

構成ファイルは次のようになります。

{
  "boxAppSettings": {
    "clientID": "febb9yq9nidfszj63ylzshqf2cg4emso",
    "clientSecret": "3N...Exi",
    "appAuth": {
      "publicKeyID": "39749s1s",
      "privateKey": "-----BEGIN ENCRYPTED PRIVATE KEY-----\n...MIIlCE=\n-----END ENCRYPTED PRIVATE KEY-----\n",
      "passphrase": "fa...c3"
    }
  },
  "enterpriseID": "877840855"
}

それぞれをコピーして環境の構成に貼り付けるだけです。

OAuth 2.0の特殊なケース

OAuth 2.0には、アクセストークンと更新トークンの両方があります。

Boxでは、アクセストークンの有効期間は60分ですが、OAuth更新トークンの有効期間は60日です。アクセストークンの有効期限が切れると、更新トークンを使用して更新でき、アクセストークンと更新トークンの両方についてそれぞれ60分間と60日間の新しいトークンを取得できます。

つまり、期限切れのアクセストークンを60日以内に更新して、両方の新しいトークンを取得でき、その場合、更新トークンはその時点から60日間有効になります。更新トークンが期限切れになった場合、ユーザーは、アプリを再度承認する必要があります。

OAuth 2.0の仕様では、ユーザーが自分の代わりにリソースにアクセスできるようにアプリケーションを明示的に承認する必要があることを示しています。これにより、ユーザーが認証ページにリダイレクトされ、アプリを承認すると再度リダイレクトされるという2段階のプロセスが開始されます。もちろん、Postmanではこのプロセスがサポートされています。

前提条件として、PostmanのリダイレクトURL https://oauth.pstmn.io/v1/callbackを受け入れるようBox OAuthアプリを構成しておく必要があります。

次に、少なくともclient_idとclient_secretが構成されているOAuth環境を選択します。

次に、Authorize OAuth Box Appフォルダに移動し、[Authorization (承認)] タブに移動します。一番下までスクロールして、[Get New Access Token (新しいアクセストークンの取得)] ボタンをクリックします。これにより、OAuth 2.0プロセスが開始されます。