요청 엔드포인트

이 페이지는 Cloud Storage에 액세스하는 데 사용할 수 있는 여러 가지 요청 엔드포인트(URI)를 설명합니다. Cloud Storage는 HTTP/1.1, HTTP/2, HTTP/3 프로토콜을 지원합니다.

일반적인 API 요청

Cloud Storage API 중 하나로 직접 요청을 하는 경우, 다음 URI를 사용합니다.

JSON API

  • 객체 업로드를 제외한 일반적인 JSON API 요청의 경우, 다음 엔드포인트를 사용하여 PLACEHOLDER를 적절한 값으로 바꿉니다.

    https://storage.googleapis.com/storage/v1/PATH_TO_RESOURCE
  • JSON API 객체 업로드에는 다음 엔드포인트를 사용합니다. 여기에서 PLACEHOLDER를 적절한 값으로 바꿉니다.

    https://storage.googleapis.com/upload/storage/v1/b/BUCKET_NAME/o
  • 일괄 요청의 경우, 다음 엔드포인트를 사용하고 PLACEHOLDER를 적절한 값으로 바꿉니다.

    https://storage.googleapis.com/batch/storage/v1/PATH_TO_RESOURCE
  • JSON API 객체 다운로드의 경우 필요에 따라 다음 엔드포인트를 사용할 수 있습니다. 여기에서 PLACEHOLDER는 적절한 값으로 바꿉니다.

    https://storage.googleapis.com/download/storage/v1/b/BUCKET_NAME/o/OBJECT_NAME?alt=media

JSON API 엔드포인트는 HTTPS 요청만 수용합니다.

XML API

  • XML API 요청의 경우 가상 호스팅 스타일 또는 경로 스타일 엔드포인트를 사용할 수 있습니다. 이때 PLACEHOLDER를 적절한 값으로 대체합니다.

    가상 호스팅 스타일:

    https://BUCKET_NAME.storage.googleapis.com/OBJECT_NAME
    경로 스타일:
    https://storage.googleapis.com/BUCKET_NAME/OBJECT_NAME

XML API 엔드포인트는 보안 소켓 레이어(SSL) 암호화를 지원하므로 HTTP 또는 HTTPS를 사용할 수 있습니다. 특히 OAuth 2.0을 사용하여 Cloud Storage에 인증한다면 HTTPS를 사용하는 것이 좋습니다.

프록시를 통해 연결할 때의 권장 사례에 대한 문제해결 주제를 참조하세요.

URI 경로 부분 인코딩

버킷 이름 지정객체 이름 지정에 대한 일반적인 고려사항 외에도, Cloud Storage 도구 간의 호환성을 보장하기 위해 다음 문자가 요청 URI의 객체 이름 또는 쿼리 문자열에 표시되는 경우 이를 인코딩해야 합니다.

!, #, $, &, ', (, ), *, +, ,, /, :, ;, =, ?, @, [, ], 공백 문자

예를 들어 example-bucket 버킷에서 foo??bar라는 객체에 JSON API GET 요청을 보내려면 요청 URI는 다음과 같아야 합니다.

GET https://storage.googleapis.com/storage/v1/b/example-bucket/o/foo%3f%3fbar

나열된 문자 중 일부는 모든 시나리오에서 인코딩되지 않아야 합니다. 또한 일반적으로 Cloud Storage 클라이언트 라이브러리와 같은 클라이언트 라이브러리를 통해 인코딩이 처리되므로, 이러한 도구를 사용할 때 원시 객체 이름을 전달할 수 있습니다.

URI에 백분율 인코딩을 사용하는 방법에 대한 자세한 내용은 RFC 3986의 섹션 3.3 경로를 참조하세요.

Cloud Console 엔드포인트

Cloud Console을 사용할 때 다음 URL을 사용하여 다른 리소스에 액세스합니다.

리소스 URL
프로젝트의 버킷 목록 https://console.cloud.google.com/storage/browser?project=PROJECT_ID
버킷의 객체 목록 https://console.cloud.google.com/storage/browser/BUCKET_NAME
객체의 세부정보 https://console.cloud.google.com/storage/browser/_details/BUCKET_NAME/OBJECT_NAME

gsutil 엔드포인트

기본적으로 gsutil은 JSON API 요청 엔드포인트를 통해 Cloud Storage에 액세스합니다. 다음과 같이 .boto 구성 파일의 'GSUtil' 섹션에서 prefer_api 변수를 xml 또는 json으로 설정하여 이 기본값을 제어할 수 있습니다.

prefer_api = xml

가능한 경우 gsutil에 선호 API가 사용되지만, 가능하지 않으면 gsutil이 다른 API를 사용하도록 자동으로 대체됩니다. 예를 들어 ubla 명령어가 XML API에서 지원되지 않기 때문에 gsutil에서는 항상 해당 명령어에 대해 JSON API가 사용됩니다. 마찬가지로 gsutil은 JSON API를 지원하지 않는 Cloud Storage 제공업체와 상호작용할 때 항상 XML API를 사용합니다.

성능 및 비용 고려사항

XML API는 boto 프레임워크를 사용합니다. 이 프레임워크는 MD5 해시가 없는 경우 다운로드한 파일을 다시 읽어 MD5 해시를 계산합니다. MD5 해시가 메타데이터에 포함되어 있지 않은 객체의 경(예: 복합 객체) 다운로드에 필요한 대역폭과 경과 시간이 두 배가 됩니다. 복합 객체를 사용하는 경우 prefer_apixml로 설정하지 않아야 합니다.

XML API는 또한 다른 객체 및 버킷 구성과 같은 버킷 메타데이터 필드를 가져오기 위해 별도의 호출이 필요합니다. 가능한 경우 JSON API를 사용하면 작업이 더 적게 사용되므로 비용이 절감됩니다.

커스텀 도메인

자체 도메인을 소유하고 있으면 URI를 Cloud Storage 버킷을 포함한 하나 이상의 Google Cloud 서비스에 매핑할 수 있습니다. 이 Cloud Storage 요청 엔드포인트를 설명하는 데 버킷 바인딩 호스트 이름이라는 용어가 사용됩니다. 커스텀 도메인을 Cloud Storage 버킷에 연결하려면 DNS 레코드에서 A 또는 CNAME 리디렉션을 만듭니다.

A 레코드

커스텀 도메인을 Cloud Storage 버킷에 연결할 때는 일반적으로 A 레코드를 사용해야 합니다.

  • A 레코드는 HTTPS 요청을 지원합니다.
  • A 레코드를 사용하면 단일 호스트 이름에서 들어오는 트래픽을 여러 버킷 및 다른 Google Cloud 서비스로 보낼 수 있습니다.
  • A 레코드는 버킷 이름에 제한을 두지 않습니다.

A 레코드를 사용하는 경우의 단점은 추가 설정 및 추가 Google Cloud 리소스를 사용해야 한다는 점입니다. A 레코드로 커스텀 도메인을 사용하는 방법에 대한 가이드는 부하 분산기 및 SSL 인증서 설정을 참조하세요.

CNAME 레코드

커스텀 도메인을 Cloud Storage 버킷에 연결할 때 CNAME 레코드를 사용할 수 있지만 이렇게 하면 몇 가지 제한사항이 있습니다.

  • CNAME 레코드는 HTTP 요청만 지원합니다.
  • CNAME 레코드는 지정된 호스트 이름의 트래픽을 단일 버킷으로만 전달할 수 있습니다.
  • CNAME 레코드는 호스트 이름 및 연결된 버킷 이름이 일치해야 하며, 버킷 이름 유효성을 검사해야 합니다.
  • CNAME 레코드는 mydomain.com과 같은 최상위 도메인이 아닌 www.mydomain.com과 같은 하위 도메인에만 사용할 수 있습니다.

CNAME 레코드를 사용하는 경우 CNAME 레코드의 호스트 이름 부분에 다음 URI를 추가해야 합니다.

c.storage.googleapis.com.

예를 들어 도메인이 example.com이고 고객에게 여행 지도를 제공하고자 한다고 가정해 보겠습니다. Cloud Storage에 travel-maps.example.com이라는 버킷을 만든 다음 CNAME의 요청을 Cloud Storage URI로 리디렉션하는 travel-maps.example.com 레코드를 DNS에 만들 수 있습니다. 이렇게 하려면 DNS에 다음 CNAME 레코드를 게시합니다.

NAME                      TYPE     DATA
travel-maps               CNAME    c.storage.googleapis.com.

이렇게 함으로써 고객은 다음 URL을 사용하여 파리 지도에 액세스할 수 있습니다.

http://travel-maps.example.com/paris.jpg

도메인 등록 서비스에는 CNAME 리소스 레코드 추가를 포함하여 도메인을 관리하기 위한 수단이 있어야 합니다. 예를 들어 Google Domains를 사용하는 경우 Google Domains 도움말 페이지리소스 레코드 드롭다운 섹션에서 리소스 레코드 추가 안내를 확인할 수 있습니다.

인증된 브라우저 다운로드

인증된 브라우저 다운로드는 쿠키 기반 인증을 사용합니다. 쿠키 기반 인증은 사용자에게 신원 확인을 위해 Google 계정에 로그인할 것을 요청합니다. 지정된 Google 계정에는 객체를 다운로드할 수 있는 적절한 권한이 있어야 합니다. 예를 들어 Identity and Access Management를 사용하여 객체에 대한 액세스를 제어하는 경우 사용자의 Google 계정에 storage.objects.viewer 권한이 있어야 합니다. 이 권한은 스토리지 객체 뷰어 역할에 부여됩니다.

쿠키 기반 인증을 사용하여 객체를 다운로드하려면 다음 URL을 사용하고 PLACEHOLDER를 적절한 값으로 바꿉니다.

https://storage.cloud.google.com/BUCKET_NAME/OBJECT_NAME

예를 들어 example-maps 버킷에서 london.jpg 이미지를 공유한 경우 URL은 다음과 같습니다.

https://storage.cloud.google.com/example-maps/london.jpg

인증된 브라우저 다운로드를 수행하려면 HTTPS를 사용해야 합니다. HTTPS에 대한 HTTP 리디렉션을 사용하려고 시도합니다.

공개 객체에 액세스

storage.cloud.google.com URI에 대한 모든 요청은 인증되어야 합니다. allUsers에 객체 액세스 권한이 있는 경우에도 마찬가지입니다. 사용자가 인증 없이 익명 액세스가 가능한 객체를 다운로드할 수 있게 하려면 직접 API 요청에서 설명하는 storage.googleapis.com URI를 사용합니다. 자세한 내용과 예시는 공개 데이터 액세스를 참조하세요.

다음 단계