ハッシュと ETag: ベスト プラクティス

Cloud Storage では、バケットとの間で転送されるデータの検証が推奨されます。このページでは、CRC32C または MD5 のチェックサムを使用して検証を実行するためのベスト プラクティスについて説明します。

ハッシュを使用してデータの破損から保護する

Cloud へのアップロードや Cloud からのダウンロード中にデータが破損する可能性がある状況は、次のように多岐に及びます。

  • クライアントやサーバーのコンピュータ上のメモリエラーや、パスに沿ったルーター
  • ソフトウェアのバグ（たとえば、ユーザーが使用するライブラリにある）
  • アップロードが長時間にわたって行われた場合のソースファイルの変更

Cloud Storage では、データの整合性チェックに使用できるハッシュとして、CRC32C と MD5 の 2 種類のハッシュがサポートされています。CRC32C は、整合性チェックを実行するための推奨の検証方法です。希望する場合は MD5 ハッシュを使用できますが、MD5 ハッシュは複合オブジェクトや XML API マルチパート アップロードから作成されたオブジェクトではサポートされていません。

CRC32C

Cloud Storage のすべてのオブジェクトに CRC32C ハッシュがあります。CRC32C を計算するためのライブラリには、以下があります。

Base64 でエンコードされた CRC32C のバイト順はビッグ エンディアンです。

MD5

Cloud Storage は、次の条件を満たすオブジェクトに対する MD5 ハッシュをサポートしています。

このハッシュは、完全なオブジェクトにのみ適用されるため、範囲 GET の実行によって生じる部分ダウンロードの整合性チェックには使用できません。

ETag

次のすべてに該当する場合、オブジェクトの ETag ヘッダーはオブジェクトの MD5 値を返します。

それ以外の場合は、仕様のとおりです。ETag で使用される値について、基になるデータまたはメタデータが変更されるたびに値が変化するということ以外は想定できません。

XML API からのリクエストと JSON API からのリクエストでは、同じオブジェクトでも ETag 値が異なる場合があります。

検証

ダウンロードの整合性チェックは、ダウンロードしたデータをすばやくハッシュ化して結果をサーバーによって提供されたハッシュと比較することで実行できます。ハッシュ値が不適切なダウンロード済みのデータを破棄し、高コストになりがちな無限ループを回避するロジックを再試行します。

Cloud Storage は、次の場合にサーバー側の検証を行います。

  • Cloud Storage 内でコピーまたは書き換えリクエストを実行したとき。

  • アップロード リクエストでオブジェクトに想定される MD5 または CRC32C ハッシュを指定したとき。指定したハッシュが Cloud Storage の計算値と一致する場合にのみ、Cloud Storage はオブジェクトを作成します。一致しない場合、リクエストは BadRequestException: 400 エラーで拒否されます。

また、アップロードされたオブジェクトのメタデータをリクエストして、報告されたハッシュ値を比較し、不一致の場合にオブジェクトを削除することで、クライアント側でアップロードの検証を行うように選択することも可能です。この方法は、アップロードの開始時にオブジェクトの MD5 または CRC32C ハッシュが不明な場合に有効です。独立したプロセスで互いのデータの削除や置換が行われる競合状態を回避するには、オブジェクトの生成と前提条件を使用します。

並列複合アップロードの場合は、コンポーネントのアップロードごとに整合性チェックを実行してから、コンポーネントの前提条件をその作成リクエストとともに使用して、競合状態を回避します。オブジェクト作成では、サーバー側 MD5 検証が提供されないため、エンドツーエンドの整合性チェックを実行するユーザーは、クライアント側検証を新しい複合オブジェクトに適用する必要があります。

XML API

XML API では、Base64 でエンコードされた MD5 と CRC32C のハッシュは、x-goog-hash ヘッダーを介して露出され受け付けられます。これまで、MD5 はオブジェクトの ETag として使用されていましたが、オブジェクトの変更時に変更以外を保証しない不透明な ETag 値が一部のオブジェクトで使用されるため、ETag としての使用の仮定を回避する必要があります。

サーバー側アップロード検証は、x-goog-hash リクエスト ヘッダーを使用してローカルで計算されたハッシュを入力することで実行できます。さらに、標準 HTTP の Content-MD5 ヘッダーを使用して MD5 を指定できます（仕様をご覧ください）。

JSON API

JSON API では、オブジェクト リソースの md5Hash プロパティと crc32c プロパティにそれぞれ、Base64 でエンコードされた MD5 のハッシュと CRC32C のハッシュが含まれています。どちらのメタデータ プロパティを指定するかはオプションです。再開可能なアップロードまたは JSON API マルチパート アップロードの一部としてどちらかのプロパティを指定すると、新しいオブジェクトに対してサーバー側検証がトリガーされます。Cloud Storage でどちらかのプロパティの値が計算され、その値が指定した値と一致しない場合、オブジェクトは作成されません。アップロードでこれらのプロパティを指定しない場合には、Cloud Storage で値が計算され、オブジェクトのメタデータに書き込まれます。

Google Cloud CLI

Google Cloud CLI の場合、Cloud Storage バケットとの間でコピーされたデータが検証されます。これは、cp、mv、rsync コマンドに適用されます。ソースデータのチェックサムが宛先データのチェックサムと一致しない場合、gcloud CLI は無効なコピーを削除し、警告メッセージを出力します。これが発生するのは非常にまれです。発生した場合は、オペレーションを再試行する必要があります。

この自動検証はオブジェクト自体のファイナライズの後に行われるため、無効なオブジェクトが認識されて削除されるまでに 1～3 秒ほどかかります。また、アップロードが完了した後、検証を行う前に gcloud CLI が中断され、無効なオブジェクトが残る可能性があります。この問題は、--content-md5=MD5 フラグの使用時に発生するサーバー側の検証を使用して、単一ファイルを Cloud Storage にアップロードすると回避できます。

次のステップ