Box Developers

Box Relay用に2つの新しいAPIエンドポイントをリリースしました。1つ目のエンドポイントでは、指定したフォルダに対して構成されたワークフローを取得できます。もう1つのエンドポイントでは、トリガータイプがWORKFLOW_MANUAL_STARTに設定されているワークフロー内のフローを開始できます。このガイドでは、これらの新しいエンドポイントの使用方法を説明します。

前提条件

· 手動開始フローを作成しておく必要があります。こちらのガイドを参照してください。

ステップ1

Boxアプリケーションを設定します。上記の新しいエンドポイントを使用するには、開発者コンソールの構成セクションにあるアプリケーションスコープ で [Box Relayを管理する]、[Boxに格納されているすべてのファイルとフォルダの読み取り]、[Boxに格納されているすべてのファイルとフォルダへの書き込み] を有効にする必要があります。アプリケーションの認証方法によっては、管理者によるアプリケーションの再承認が必要になる場合があります。

--

--

Box APIをこれまで以上に簡単にご利用いただけるように、新しいBox CLIのクイックスタートガイドをリリースしました。

Box CLIは、使い勝手の良いコマンドラインツールで、これにより、開発者でも開発者以外のユーザーでもBox APIを利用してルーチンや一括操作を実行できるようになります。コードを書く必要はありません。これらの操作は、一連のコマンドによって実行されます。

このクイックスタートガイドでは、以下の手順を説明します。

1. Boxアプリケーションを作成、構成、承認する

2. CLIをインストールして構成する

3. CLIを使用してコマンドを実行する

4. フラグや一括コマンドを使用する

--

--

こちらでご案内しているとおり、日本時間2021年5月11日にBox APIを呼び出したときに返されるレスポンスヘッダーを変更する予定です。今回の変更により、Boxのネットワークおよび可観測性のインフラストラクチャの継続的なアップグレードの一環として、レスポンスヘッダーが常に小文字で返されるようになります。Box SDKのユーザーはこの影響を受けませんが、直接APIを利用している場合、このようなレスポンスヘッダーを使用しているかどうかやその使用方法によって影響を受ける可能性があります。

影響を受ける可能性のあるお客様にはすでにご案内していますが、お使いのBoxアプリケーションがこれらの標準に準拠しているかどうかを再度ご確認ください。以下の例では、業界のベストプラクティスやBoxのAPIドキュメントに従って、大文字と小文字を区別せずにレスポンスヘッダーをBoxから取得し、アクセスする方法を示しています。

サンプルの設定

このNode/Expressサンプルでは、Boxからアクセストークンを取得するためのAPI呼び出しを実行します。レスポンスでは、ヘッダーも取得されます。これを使用すると、プログラムのフローにも役立ちます。注意すべき重要なコードがいくつかあります。

ここでは、コンテンツタイプと長さに関するリクエストヘッダーを設定しています。これらのリクエストヘッダーは、今回のリリースによる影響を受けません。影響を受けるのはレスポンスヘッダーのみです。つまり、これらの値を設定する際に、既存のコードを変更する必要はありません。

headers: {
'Content-Type': 'application/x-www-form-urlencoded',
'Content-Length': req.length
}

次に、このAPIリクエストをBoxに対して実行し、レスポンスが返されたら、特定のヘッダー (Content-Type) を取得するために以下の2行を使用します。このようにAPIレスポンスヘッダーを取得して使用する部分をコード内で検索してください。ここでは、Content-Typeが大文字と小文字を区別して確認されているため、今回の影響を受ける可能性があります。

let contentType = response.headers[‘Content-Type’];
console.log(contentType);

以下のコードサンプルでは、optionsにリクエストの詳細を設定し、Boxのアクセストークンを取得するためにPOSTリクエストを送信しました。レスポンスが返されたら、エラーがないか確認し、レスポンスヘッダーを取得してから、レスポンスのパラメータからアクセストークン/有効期限を抽出します。

大文字と小文字を区別しないレスポンスヘッダーの確認への切り替え

上記 (response.headers[‘Content-Type’]) のようにヘッダーを取得した場合、レスポンスヘッダーは大文字と小文字を区別して取得されます。ヘッダーを取得するタイミングではなく、その使用方法に注意が必要です。特定のヘッダーが存在することを予想して、その予想を基にプログラムの実行を進めた際に問題になる場合があります。

このようなヘッダーを大文字と小文字を区別せずに確認する方法は多数ありますが、その1つに、すべてのレスポンスヘッダーを強制的に大文字と小文字のいずれかに変換してから使用する方法があります。その方法は以下のとおりです。

  1. すべてのレスポンスヘッダーをループ処理します。
  2. 各ヘッダー: キー/値ペアとしてJSONオブジェクトに保存します。
  3. 各キー: ヘッダーキー (Content-Typeなど) を強制的に小文字に変換し、キーとして保存します。
  4. 各値: ヘッダー値を変更せずに保存します。

上記の手順が完了した時点で、すべてのヘッダーは標準の小文字の値に強制的に変換されているため、JSONオブジェクトで (たとえば) content-typeキーがあるかどうかを確認できます。これで、通常どおりプログラムの実行を続行し、必要な値が使用できるかどうかを確認できます。

上記のContent-Typeを確認する行を、次のように、大文字と小文字を区別しないヘッダーの確認に変更します。

上記のコードスニペットに関する注意事項がいくつかあります。

  1. response.headersには、レスポンス内のヘッダーがすべて含まれます。このサンプルでは、Node/Expressを使用しています。
  2. 各ヘッダーをループ処理して、小文字のヘッダー名をキーとして新しいヘッダーオブジェクトに保存し、ヘッダー値を変更せずに保存します。レスポンスヘッダーのでは大文字と小文字が区別される場合もあれば、区別されない場合もありますが、値の大文字と小文字が区別されることが予想される場合は、を強制的に大文字と小文字のどちらかに変換することをお勧めします。
  3. Nodeでは、.toLowerCase() を使用して強制的に小文字に変換できます。これは、前述のheader.toLowerCase() に相当します。
  4. すべて小文字のヘッダーを含む新しいヘッダーオブジェクトができたら、content-typeヘッダーを小文字の値として問題なく使用できます。これがBoxによって返されるヘッダーであれば、値が返されます。

これは、コード内で大文字と小文字を区別せずにレスポンスヘッダーを確認する方法の一例にすぎません。これにより、将来的にアプリケーションコードの柔軟性が高まるだけでなく、HTTP標準に準拠した開発が可能になります。

--

--

Box APIを初めて使用するユーザーであっても、カスタムアプリケーションの承認作業を任されているBox管理者であっても、Boxに保存されているコンテンツを保護するために実装されているセキュリティメカニズムを理解しておくことは重要です。この記事を読み終えるまでに、Box APIを操作する際のアクセス制限について理解を深めていただければ幸いです。なお、セキュリティに関して、APIはBoxウェブアプリと同じ原則および規制事項に従うこととなります。

トークン

--

--

JWTアプリケーションの新しい認証方法としてクライアント資格情報許可がリリースされました。これまで、アプリケーションのIDを確認してアクセストークンを取得するには、公開/秘密キーペアとアサーションが必要でしたが、このオープンスタンダードにより、クライアントIDとクライアントシークレットだけでトークンをリクエストできるようになりました。 この認証方法を使用できるのは、アプリの種類としてカスタムアプリケーションを使用する新しいアプリケーションのみで、この認証方法による既存のアプリケーションへの影響はありません。また、認証方法を選択できるのは、アプリケーションの新規作成時のみです。作成後に別の認証方法に切り替えることはできません。Box管理者が自分で承認したアプリの可視性や制御を強化できるように、選択した認証方法がEnterpriseの承認要求に含まれるようになります。 Box開発者コンソールでキーペアを生成する場合と同様、アプリケーションのクライアントシークレットを表示またはコピーするには、Boxアカウントで2要素認証を有効にしておくことが必要になります。これまでどおり、クライアントシークレットは機密情報であり、保護する必要がありますが、ボタンをクリックすればいつでもリセットできます。

クライアント資格情報許可
クライアント資格情報許可

JWTアプリケーションの新しい認証方法としてクライアント資格情報許可がリリースされました。これまで、アプリケーションのIDを確認してアクセストークンを取得するには、公開/秘密キーペアとアサーションが必要でしたが、このオープンスタンダードにより、クライアントIDとクライアントシークレットだけでトークンをリクエストできるようになりました。

この認証方法を使用できるのは、アプリの種類としてカスタムアプリケーションを使用する新しいアプリケーションのみで、この認証方法による既存のアプリケーションへの影響はありません。また、認証方法を選択できるのは、アプリケーションの新規作成時のみです。作成後に別の認証方法に切り替えることはできません。Box管理者が自分で承認したアプリの可視性や制御を強化できるように、選択した認証方法がEnterpriseの承認要求に含まれるようになります。

Box開発者コンソールでキーペアを生成する場合と同様、アプリケーションのクライアントシークレットを表示またはコピーするには、Boxアカウントで2要素認証を有効にしておくことが必要になります。これまでどおり、クライアントシークレットは機密情報であり、保護する必要がありますが、ボタンをクリックすればいつでもリセットできます。

クライアント資格情報許可タイプは、エンドユーザーの認証が不要なマシン間の統合を作成する場合に最適です。この許可タイプを使用すると、Box Enterpriseに対するプロトタイプやスクリプトを最も短時間で簡単に作成でき、ほとんどの場合、サーバーをBoxアプリケーションの代わりとして機能させることができます。クライアント資格情報許可タイプを利用するすべてのアプリケーションには、サービスアカウントが関連付けられています。このサービスアカウントは、アプリケーションを表す、管理者に似たユーザーです。そのため、これらのアプリケーションでは使用前にBox管理者による明示的な承認が必要です。承認されると、アプリケーションはデフォルトでサービスアカウントユーザーとしてリクエストを行います。

クライアント資格情報許可タイプの詳細については、SDKを使用しないJWT認証に関するガイドを参照してください。

For an English translation of this release, please see this post.

--

--

ファイルリクエストAPIがリリースされました

APIの新しいコレクションが利用可能になりました。開発者はこれを使用して、ファイルリクエストを作成および更新できます。Boxでは、ファイルリクエストの管理に役立つよう、リファレンスドキュメントを更新したほか、新しいガイドも追加しました。

Boxファイルリクエストを使用すると、どのユーザーに対しても、迅速かつ安全にファイルおよび関連付けられているメタデータをリクエストできます。ドラッグアンドドロップ方式のグラフィカルインターフェイスを使用して作成できるウェブフォームでは、以下のことが可能です。

  • Boxアカウントの有無に関係なくどのユーザーに対しても、フォルダにコラボレータを追加することなく、安全にファイルをリクエストする。
  • メタデータフォームフィールド (必須/省略可として設定可能) を使用して追加情報を要求する。
  • リンク設定を使用して、追加のセキュリティと追跡を有効にする。
  • Box Relayを使用して自動化ワークフローを開始する。

既存のファイルリクエストのコピーを作成するために必要なのは、既存のファイルリクエストの一意のIDと、新しいリクエストの適用先となるフォルダのIDだけです。

最初のファイルリクエストを作成する

このAPIを使用して新しいファイルリクエストを作成するには、Boxウェブアプリを使用して、Boxアカウントの任意のフォルダにテンプレートのファイルリクエストを作成する必要があります。

ファイルリクエストを作成するには、フォルダを選択し、ページの上部にある省略記号をクリックします。次に、メニューから [ファイルリクエスト] を選択します。

--

--

新しいフォルダロックAPI

フォルダロックAPIがリリースされました

新しいフォルダロックAPIの正式版をリリースしました。Box内のフォルダ構造に対する制御とセキュリティが強化されたこれらの新しいAPIを使用することにより、ロックが解除されない限りフォルダが移動または削除されないようにすることができます。

このリリースの一環として、新しく3つエンドポイントが利用可能になりました。その結果、以下の操作が可能になります。

新しいフォルダロックを作成する

フォルダにロックを適用すると、そのフォルダを移動したり、別の所有者に転送したり、削除したりできなくなります。ただし、こうした操作がユーザーアカウントを削除する際の、Boxコンテンツの標準的な転送および削除プロセスに含まれる場合は除きます。

現在、フォルダロックでは2つのロック操作 (移動と削除) が自動的に適用されます。

フォルダロックのPOSTの例

詳細については、ガイドまたはAPIリファレンスを参照してください。

フォルダに適用されているロックのリストを取得する

フォルダにフォルダロックが適用されているかどうかを確認する場合は、このエンドポイントを使用すると、フォルダIDを指定して、現在フォルダに適用されているすべてのフォルダロックのリストを取得できます。

フォルダロックのGETの例

詳細については、ガイドまたはAPIリファレンスを参照してください。

フォルダからロックを削除する

新しいフォルダロックを作成したり、フォルダに適用されているロックのリストを取得したりすると、リターンペイロードの一部としてフォルダロックIDが返されます。このロックIDを使用して、現在フォルダに適用されているすべてのロックを削除できます。

フォルダロックのDELETEの例

詳細については、ガイドまたはAPIリファレンスを参照してください。

この新機能をぜひご利用ください。

For an English translation of this release, please see this post.

--

--

アプリ作成プロセスを簡素化し、できるだけ短時間で最初のAPI呼び出しを実行できるように取り組む中で、シンプルな新しいアプリ作成フローが実現しました。現在、アプリケーションには、カスタムアプリ、アクセス制限付きアプリ、Boxカスタムスキルの3種類があります。各種アプリをどのような場合に選択するかについての説明や、選択に役立つドキュメントへのリンクを追加しました。アプリケーションの種類の選択は、使用できる認証方法に影響します。

選択が完了すると、開発者コンソールにあるアプリケーションの構成タブに自動的にリダイレクトされます。ここですぐにアプリケーションの構成を完了し、開発者トークンを生成してAPI呼び出しを開始できます。

アクセス制限付きアプリ

中でも注目すべきは、Boxの新しいアプリの種類であるアクセス制限付きアプリです。これは、Box Viewを使用する場合や別のアプリケーション内でBoxのプレビューサービスを使用する場合に選択してください。この種類で利用できるのは、APIの機能が制限されているアプリトークン認証のみです。

詳細については、アプリの種類の選択に関するガイドを参照してください。

For an English translation of this release, please see this post.

--

--