メタデータAPIの変更に関するご案内 – Box Support

実施予定のアップグレードとその理由について

Boxによる新しいメタデータストレージシステムへのアップグレードは、Boxをご利用のお客様に多くの効果をもたらします。たとえば、メタデータクエリAPI を使用すると、SQLのようなクエリを実行し、メタデータに基づいてファイルとフォルダを検索できるようになります。また、今回の更新により、Boxはより高品質なサービスを提供できるようになるほか、これまで不可能だったメタデータの機能も追加できるようになります。

変更内容

この変更の一環として、APIの動作がより一貫性のあるものになります。以下の3つの変更が予定されています。

メタデータの日付 (datetime) フィールドの変更 - RFC3339タイムスタンプの仕様に準拠した実装の場合、対応は不要です (Box Developerドキュメントで説明されています)。
エラーコードの変更 - 特定のメタデータに関連した、応答本文で返されるエラーコードを処理している場合は、対応が必要になる可能性があります。
メタデータインスタンスのバージョン番号の変更 - これは暗黙的な動作を明確にするためだけの変更で、クライアント側のロジックでは使用されないため、対応は不要です。

サポートの利用方法

この変更に伴い、ご利用のサンドボックス環境でのメタデータの操作で何らかの異常に気付いた場合は、問題の説明と裏付けとなる証拠を添えて Product Support までお問い合わせください。

変更の詳細情報

メタデータの日付 (datetime) フィールドの変更

これまでは、タイムゾーンオフセットを含むdatetime値をメタデータフィールドで指定した場合、その後の操作 (GETリクエストなど) では、指定したとおりに (タイムゾーンオフセットを含む) datetime値が返されるか、Zulu time (UTC) に標準化されたdatetime値が返されていました。今後、Boxから返されるメタデータフィールドのdatetime値は常にZulu timeに標準化されます。

変更前: 「2020-02-20T13:00:00.000Z」または「2020-02-20T12:00:00.000-01:00」
変更後: 「2020-02-20T13:00:00.000Z」
これまで、Boxから返されるメタデータのdatetime値の1秒未満の有効桁数は0～3桁でした。今後、返されるメタデータのdatetime値の有効桁数はミリ秒までになります。

変更前: 「2020-02-20T12:00:00Z」または「2020-02-20T12:00:00.000Z」
変更後: 「2020-02-20T12:00:00.000Z」
これまでは、「test」演算子を使用した場合、datetime値の比較にはリテラル文字列値が使用されていました。今後は、UNIXタイムスタンプを使用してミリ秒単位 (エポックからのミリ秒) でdatetime値が比較されます。

変更前: 「2020-01-21T19:20:00.123-08:00」は「2020-01-22T03:20:00.123Z」と等しくない
変更後: 「2020-01-21T19:20:00.123-08:00」は「2020-01-22T03:20:00.123Z」と等しい

この変更に対して必要な対応

RFC3339に準拠した日時解析を実装しているアプリケーションの場合、すべて有効なRFC3339形式となるため、何も行う必要はありません。 RFC3339に準拠した日時解析を実装していないアプリケーションの場合は、アプリケーションを更新して実装する必要があります。 Box SDKではRFC3339に準拠した解析がサポートされているため、日時解析に最新バージョンのBox SDKを使用しているアプリケーションの場合、変更は不要です。

エラーコードの変更

標準的なBox API言語をより一貫性のあるものにし、わかりにくいエラーを最小限に抑えるために、Boxでは、API応答で返される、メタデータ関連のエラーコードとエラーメッセージを複数更新します。 HTTPステータスコードは変更されません。以下に例を示します。

変更前: HTTPステータスコード: 「404」| エラーコード: 「instance_tuple_not_found」
変更後: HTTPステータスコード: 「404」| エラーコード: 「not_found」

エラーコードの変更をまとめた詳細なリストについては、こちらを参照してください。

この変更に対して必要な対応

汎用的なHTTPステータスコードではなく特定のエラーコードを処理する場合は、新しいエラーコード値を処理するためにアプリケーションロジックの更新が必要になることがあります。

メタデータインスタンスのバージョン番号の変更

これまでは、親テンプレートのフィールドが削除された場合や親テンプレートのフィールド内の列挙型オプションが削除された場合に、メタデータインスタンスに関連付けられたバージョン番号が暗黙的に増加していました。今後は、このような変更を行った場合でも、メタデータインスタンスのバージョン番号が増加することはありません。 Boxは現在、メタデータインスタンスのバージョンについて以前の値に戻すことも以前の値を読み取ることもサポートしていません。また、今回の変更でもサポートする予定はありません。