正規リクエスト

正規リクエストでは、署名付き URL などの V4 署名認証リクエストを Cloud Storage に送信する際にユーザーが含める必要があるリクエストの要素が定義されます。

概要

正規リクエストは、Cloud Storage に対する特定の HTTP リクエストを表す文字列です。正規リクエストと RSA 鍵などの暗号鍵を使用して署名を作成します。この署名は実際のリクエストに認証として含まれます。

正規リクエストには、HTTP 動詞、クエリ文字列パラメータ、実際のリクエストで使用されるヘッダー、要求されるオブジェクトやバケットなどのリソース情報が含まれます。

正規リクエストでは、Cloud Storage がリクエストを受信したときに、ユーザーが計算したものと同じ署名を計算できます。使用するバージョンと Cloud Storage による計算結果のバージョンが一致しない場合、リクエストは失敗します。

構造

正規リクエストの構造は次のようになります。各要素の間には改行を使用します。

HTTP_VERB
PATH_TO_RESOURCE
CANONICAL_QUERY_STRING
CANONICAL_HEADERS

SIGNED_HEADERS
PAYLOAD

HTTP 動詞

署名付きリクエストでは、次の HTTP 動詞を使用できます。HTTP 動詞は、正規リクエストの一部として指定する必要があります。

  • DELETE
  • GET
  • HEAD
  • POST1
  • PUT

1 署名付き URL は、再開可能なアップロードを開始する POST リクエストに対してのみ使用できます。詳細は、再開可能なアップロードでの署名付き URL の使用をご覧ください。

リソースパス

正規リクエストには、リクエストが適用されるリソースへのパスが含まれます。リソースのパスは、ホスト名の後からクエリ文字列の前までの部分です。

たとえば、Cloud Storage の URL が https://storage.googleapis.com/example-bucket/cat-pics/tabby.jpeg の場合、リソースへのパスは /example-bucket/cat-pics/tabby.jpeg です。

https://example-bucket.storage.googleapis.com/cat-pics/tabby.jpeg のような別の Cloud Storage URL を使用する場合、リソースへのパスは /cat-pics/tabby.jpeg です。

署名付き URL で使用できるその他の URL エンドポイントについては、XML API リクエスト エンドポイントをご覧ください。

リソースパスを定義する際に、予約済み文字（?=!#$&'()*+,:;@[]"）をパーセント エンコードする必要があります。URL で使用されている他のパーセント エンコーディングもリソースパスに含める必要があります。

正規クエリ文字列

正規リクエストには、任意のクエリ文字列パラメータが含まれますが、このクエリ文字列パラメータは関連する署名を使用する署名付きリクエストに後で含まれていなければなりません。一方、このような署名付きリクエストには、正規リクエストで指定されていない追加のクエリ文字列パラメータも含めることが可能です。正規リクエストで指定されたクエリ文字列は、正規クエリ文字列と呼ばれます。

クエリ文字列は、リソースパスの末尾にある疑問符（?）の後に続くすべての文字列です。

たとえば、Cloud Storage の URL が https://storage.googleapis.com/example-bucket/cat-pics/tabby.jpeg?generation=1360887697105000&userProject=my-project の場合、クエリ文字列は generation=1360887697105000&userProject=my-project です。

正規クエリ文字列の作成時には、次の点に注意してください。

  • クエリ文字列のパラメータは、コードポイント値による辞書的な並べ替えを使用して名前の順で並べ替える必要があります。

  • クエリ文字列の各パラメータは、& で区切る必要があります。

  • 正規クエリ文字列が空の場合、正規リクエスト全体でこの部分は改行（\n）になります。

必須のクエリ文字列パラメータ

クエリ文字列パラメータのほとんどは必要に応じて追加されますが、正規リクエストを使用して署名付き URL を作成する場合は、次のクエリ文字列パラメータを必ず正規リクエストで使用してください。

  • X-Goog-Algorithm: URL の署名に使用するアルゴリズムです。有効な値は GOOG4-RSA-SHA256 と GOOG4-HMAC-SHA256 です。
  • X-Goog-Credential: URL の署名に使用する認証情報です。認証情報は、承認者と認証情報スコープで構成され、AUTHORIZER%2FCREDENTIAL_SCOPE の形式で指定します。承認者には、サービス アカウント名または HMAC キーアクセス ID を指定できます。
  • X-Goog-Date: 署名付き URL が使用可能になる日付と時刻。ISO 8601 の基本形式（YYYYMMDD'T'HHMMSS'Z'）で表示されます。
  • X-Goog-Expires: 署名付き URL の有効期間。X-Goog-Date に格納された値からの秒数で表されます。有効期間の最大値は 604800 秒（7 日間）です。
  • X-Goog-SignedHeaders: 正規リクエストで定義されたヘッダーの名前のセミコロン区切りのリストです。これらは「署名付きヘッダー」とも呼ばれます。host はヘッダー名のいずれかにする必要があります。

これらのクエリ文字列パラメータは、リクエストの認証に使用する署名を含む X-Goog-Signature クエリ文字列パラメータとあわせて、後で署名付き URL 自体で使用する必要があります。

正規ヘッダー

正規リクエストには、任意のヘッダーが含まれますが、このヘッダーは関連する署名を使用する署名付きリクエストに後で含まれていなければなりません。一方、このような署名付きリクエストには、正規リクエストで指定されていない追加のヘッダーも含めることができます（ただし、必須ヘッダーの項で記載されている場合を除きます）。正規リクエストで指定されたヘッダーは「正規ヘッダー」と呼ばれます。

正規ヘッダーには、カスタム ヘッダーと、x-goog- で始まる拡張ヘッダーが含まれます。

正規ヘッダーを指定する場合は、次の点に注意してください。

  • すべてのヘッダー名を小文字にします。
  • すべてのヘッダー名を、コードポイント値の辞書順で並べ替えます。
  • 各ヘッダーを改行（\n）で区切ります。
  • 重複したヘッダー名は、値をカンマで区切ってリストすることで 1 つのヘッダー名にまとめます。値と値の間に空白文字がなく、カンマ区切りのリストの順番がリクエストに表示されるヘッダーの順番と同じであることを確認してください。詳細については、RFC 7230 のセクション 3.2 を参照してください。
  • 折りたたみ空白文字や改行（CRLF または LF）はすべて単一の空白文字に置き換えます。折りたたみ空白文字について詳しくは、RFC 7230 のセクション 3.2.4 をご覧ください。

  • ヘッダー名の後のコロンの前後に空白文字があれば削除します。

    たとえば、コロンの後の空白文字を削除せずにカスタム ヘッダー x-goog-acl: private を使用すると、403 Forbidden エラーが返されます。これは、計算したリクエスト署名が、Cloud Storage によって計算される署名と一致しないためです。

例

次の一連のヘッダーがあるとします。

host: storage.googleapis.com
content-type: text/plain
x-goog-meta-reviewer: jane
x-goog-meta-reviewer: john

正規リクエストの正規ヘッダーの構成は次のようになります。

content-type:text/plain
host:storage.googleapis.com
x-goog-meta-reviewer:jane,john

必須の正規ヘッダー

content-type など、大部分のヘッダーは必要に応じて追加されますが、次のヘッダーを署名付きリクエストで使用する場合は、必ず正規ヘッダーに定義する必要があります。

  • host: Cloud Storage へのアクセスに使用される URI。
  • プレフィックス x-goog- が付いているヘッダー。正規ヘッダーとして追加できるのは x-goog-content-sha256 だけです。
  • プレフィックス x-amz- が付いているヘッダー。正規ヘッダーとして追加できるのは x-amz-content-sha256 だけです。

署名付きヘッダー

「署名付きヘッダー」は、正規ヘッダーの名前の部分です。

署名付きヘッダーリストを作成するには、すべてのヘッダー名を小文字に変換し、それらを文字コードで並べ替えて、それぞれをセミコロン（;）で区切ります。

例

次の一連のヘッダーがあるとします。

host: storage.googleapis.com
content-type: text/plain
x-goog-meta-reviewer: jane
x-goog-meta-reviewer: john

正規リクエストの署名付きヘッダーの構成は次のようになります。

content-type;host;x-goog-meta-reviewer

ペイロード

  • 正規 URL リクエストが署名付き URL の作成に使用される場合、この値は単純に文字列 UNSIGNED-PAYLOAD になります。

  • 正規リクエストが、Authorization ヘッダーを使用するリクエストの一部として使用される場合:

    • 任意のペイロードをリクエストの一部として許可する場合は、UNSIGNED-PAYLOAD を使用します。

    • 特定のペイロードのみを許可する場合、この値は、目的のペイロードの小文字で 16 進エンコードされた SHA-256 ハッシュにする必要があります。空のペイロードを要求するには、ハッシュ関数の入力として空の文字列を使用します。ハッシュ化されたペイロードの例（この場合は空のペイロード）を次に示します。

      e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855

例

正しい形式の正規リクエストの例を次に示します。改行は実際の改行であり、\n ではありません。

GET
/example-bucket/tabby.jpeg

host:storage.googleapis.com
x-amz-content-sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
x-amz-date:20190301T190859Z

host;x-amz-content-sha256;x-amz-date
e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855

次のステップ