正規リクエスト

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

概要

「正規リクエスト」は、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 リクエストはサポートされません。

リソースパス

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

たとえば、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-SHA256GOOG4-HMAC-SHA256 です。
  • X-Goog-Credential: URL の署名に使用する認証情報です。認証情報は、承認者と認証情報スコープで構成され、[AUTHORIZER]%2F[CREDENTIAL_SCOPE] の形式で指定します。承認者には、サービス アカウント名または HMAC アクセスキーを指定します。
  • X-Goog-Date: 現在の日付と時刻。[ISO 8601][8] の基本形式(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 エラーが返されます。これは、計算したリクエスト署名が、Google によって計算される署名と一致しないためです。

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

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-project-id
  • x-goog-copy-source
  • x-goog-metadata-directive
  • x-amz-copy-source
  • x-amz-metadata-directive

署名付きヘッダー

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

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

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

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 ヘッダーを使用するリクエストの一部として使用される場合、この値は、16 進エンコードされた SHA-256 ハッシュ リクエスト ペイロードである必要があります。ペイロードが空の場合は、ハッシュ関数への入力として空の文字列を使用します。ハッシュ化されたペイロードの例(この場合は空のペイロード)を次に示します。

    3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855

正しい形式の正規リクエストの例を次に示します。改行は実際の改行であり、\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

次のステップ

このページは役立ちましたか?評価をお願いいたします。

フィードバックを送信...

ご不明な点がありましたら、Google のサポートページをご覧ください。