정규 요청

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

  • 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 값을 초로 환산한 것입니다. 가장 긴 만료 시간 값은 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을 사용하면 사용자가 계산한 요청 서명이 Google에서 계산한 서명과 일치하지 않으므로 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-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을 만드는 데 사용되는 경우 이 값은 단순히 문자열 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

다음 단계

이 페이지가 도움이 되었나요? 평가를 부탁드립니다.

다음에 대한 의견 보내기...

도움이 필요하시나요? 지원 페이지를 방문하세요.