一貫性の確保

ガイド API呼び出し 一貫性の確保

一貫性の確保

いくつかのBox APIでは、アプリケーションとBox間の一貫性を制御するためのヘッダーがサポートされています。

etagif-match、およびif-none-match

APIを介してリクエスト可能なファイルシステムの項目(ファイルまたはフォルダ)の多くは、項目のetag値を返します。

たとえば、ファイルリソースはJSON応答でetagを返します。

curl https://api.box.com/2.0/files/12345 \
    -H "authorization: Bearer ACCESS_TOKEN"
{
  "id": 12345,
  "etag": 1,
  "type": "file",
  "sequence_id": 3,
  "name": "Contract.pdf",
  ...
}

このetagif-matchまたはif-none-matchヘッダーの値として使用できるのは、etag値が受信されてからリソースが変更されていないことを確認するためか、または変更されていない項目を不必要にダウンロードしないようにするためです。

たとえば、同じファイルを取得するのはそのファイルが変更された場合のみにするには、if-none-matchヘッダーでetag値を渡します。

curl https://api.box.com/2.0/files/12345 \
  -H "authorization: Bearer ACCESS_TOKEN" \
  -H "if-none-match: 1"

ファイルが変更されていない場合、このAPI呼び出しでは空の応答が返されます。

一貫性のある変更の確保

if-matchヘッダーを使用すると、アプリケーションは、最後に調べた項目がその後別のアプリケーションまたはユーザーによって変更が加えられても、項目が変更されないようにすることができます。これにより、2つのアプリケーションまたは2人のユーザーが項目を同時に変更しても変更が失われることはありません。

このヘッダーは、以下のエンドポイントでサポートされます。

if-match対応のエンドポイント
POST /files/:id/content新しいファイルバージョンをアップロード
PUT /files/:idファイルの情報を更新
DELETE /files/:idファイルを削除
PUT /folders/:idフォルダの情報を更新
DELETE /folders/:idフォルダの削除
PUT /web_links/:idウェブリンクの情報を更新
DELETE /web_links/:idウェブリンクを削除

これらのAPI呼び出しの応答は、項目が存在するかどうか、およびetag値が最新バージョンと一致するかどうかによって異なります。

項目があるか?Etagが一致するか?HTTPステータス
はいはい200
はいいいえ412
いいえはい412
いいえいいえ404

項目の移動

if-matchヘッダーを使用してファイル、フォルダ、またはウェブリンクの移動を防ぐことはできません。Boxでは、必ず最新の項目が新しい場所に移動されます。

リクエストによる不要なダウンロードの防止

if-none-matchヘッダーを使用すると、アプリケーションは、最後に調べてから変更されていない項目の情報がダウンロードされないようにすることができます。これにより、不要な情報がダウンロードされなくなるため、アプリケーションの速度が向上し、帯域幅が節約されます。

if-none-match対応のエンドポイント
GET /files/:idファイルの情報を取得
GET /folders/:idフォルダの情報を取得
GET /web_links/:idウェブリンクの情報を取得
GET /shared_items共有項目の情報を取得

これらのAPI呼び出しの応答は、項目が存在するかどうか、およびetag値が最新バージョンと一致するかどうかによって異なります。

項目があるか?Etagが一致するか?HTTPステータス
はいはい304
はいいいえ200
いいえはい404
いいえいいえ404