정규 요청

정규 요청에서는 서명된 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 동사를 사용할 수 있으며 이는 정규 요청의 일부로 지정되어야 합니다.

• DELETE
• GET
• HEAD
• POST¹
• PUT

¹ 서명된 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에 사용된 다른 모든 퍼센트 인코딩도 리소스 경로에 포함되어야 합니다.

정규 쿼리 문자열

정규 요청은 X-Goog-Signature 또는 X-Amz-Signature 쿼리 문자열 매개변수를 제외하고 관련 서명을 사용하는 모든 서명된 요청에 이후 포함될 각 쿼리 문자열 매개변수를 지정합니다. 정규 요청에 지정된 쿼리 문자열을 정규 쿼리 문자열이라고 합니다.

쿼리 문자열은 리소스 경로 끝부분에서 물음표(?) 뒤에 나오는 부분입니다.

예를 들어 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 값을 초로 환산한 것입니다. 가장 긴 만료 시간 값은 604,800초(7일)입니다.
• X-Goog-SignedHeaders: 정규 요청에 정의된 헤더의 이름을 세미콜론으로 구분한 목록입니다. 서명된 헤더라고도 합니다. host는 헤더 이름 중 하나여야 합니다.

이러한 쿼리 문자열 매개변수는 이후에 요청을 인증하는 서명을 포함하는 X-Goog-Signature 쿼리 문자열 매개변수와 함께 서명된 URL 자체에 사용됩니다.

정규 헤더

정규 요청에 포함된 모든 헤더는 이후에 관련 서명을 사용하는 서명된 요청에 포함됩니다. 그러나 필수 헤더에 설명된 경우를 제외하고는 정규 요청에 지정되지 않은 추가 헤더도 서명된 요청에 포함될 수 있습니다. 정규 요청에 지정된 헤더를 정규 헤더라고 합니다.

정규 헤더에는 커스텀 헤더와 x-goog-로 시작되는 확장 헤더가 포함될 수 있습니다.

정규 헤더를 지정할 때는 다음 사항에 유의하세요.

• 모든 헤더 이름은 소문자여야 합니다.
• 코드 포인트 값을 기준으로 한 사전식 정렬을 사용하여 헤더 이름별로 모든 헤더를 정렬합니다.
• 각 헤더를 줄바꿈(\n)으로 구분합니다.
• 쉼표로 구분된 값 목록으로 하나의 헤더 이름을 만들어 중복된 헤더 이름을 제거합니다. 값 사이에는 공백이 없어야 하며 쉼표로 구분된 목록의 순서는 요청에 헤더가 나타나는 순서와 일치해야 합니다. 자세한 내용은 RFC 7230 섹션 3.2를 참조하세요.
• 여러 개의 공백이나 줄바꿈(CRLF 또는 LF)을 단일 공백으로 바꿉니다. 여러 개의 공백에 대한 자세한 내용은 RFC 7230, 섹션 3.2.4를 참조하세요.

• 헤더 이름 다음에 표시되는 콜론 주위의 공백을 삭제합니다.

  예를 들어 콜론 다음에 있는 공백을 삭제하지 않고 커스텀 헤더 x-goog-acl: private을 사용하면 사용자가 계산한 요청 서명이 Cloud Storage에서 계산한 서명과 일치하지 않으므로 403 Forbidden 오류가 반환됩니다.

예시

다음과 같은 헤더 집합이 있는 경우:

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을 만드는 데 사용되는 경우 이 값은 문자열 UNSIGNED-PAYLOAD여야 합니다.

• 정규 요청이 Authorization 헤더를 사용하는 요청의 일부로 사용되는 경우:

  • 요청의 일부로 임의의 페이로드를 허용하려면 UNSIGNED-PAYLOAD를 사용합니다. 재개 가능한 업로드 요청을 시작하는 경우 UNSIGNED-PAYLOAD도 사용하는 것이 좋습니다. 포함된 sha256 값은 재개 가능한 업로드에서 무시됩니다.

  • 특정 페이로드만 허용하려면 이 값은 원하는 페이로드의 소문자로, 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

다음 단계

• 서명 및 정규 요청을 사용하는 방법에 대해 알아보기
• 정규 요청을 사용하는 요청 작성
• 정규 요청을 사용하는 서명된 URL 작성
• 서명된 URL에 대해 자세히 알아보기