이 페이지에서는 위치 엔드포인트를 사용하여 Cloud Storage에 액세스하는 방법을 설명합니다. 위치 엔드포인트를 사용하면 국제 무기 거래 규정(ITAR)을 준수하는 방식으로 워크로드를 실행할 수 있습니다.
ITAR을 준수하는 방식으로 Cloud Storage를 사용할 때의 제한사항에 대한 자세한 내용은 ITAR에 대한 제한 및 한도를 참조하세요.
개요
위치 엔드포인트는 영향을 받는 리소스가 엔드포인트에서 지정된 위치에 있는 경우에만 요청 처리를 허용하는 요청 엔드포인트입니다. 예를 들어 버킷 삭제 요청에서 엔드포인트 https://us-central1-storage.googleapis.com을 사용하는 경우 버킷이 US-CENTRAL1에 있는 경우에만 요청이 진행됩니다.
리소스가 있는 곳과 다른 위치에서 요청을 처리할 수 있는 전역 엔드포인트와 달리 위치 엔드포인트는 리소스가 있는 엔드포인트에서 지정한 위치 내에서 요청이 처리되도록 보장합니다. 위치 엔드포인트를 사용할 경우 저장 데이터 및 전송 중 데이터가 관할권 내에 있도록 보장하여 데이터 상주 요구사항을 충족할 수 있습니다.
위치 엔드포인트를 사용하면 다음을 보장할 수 있습니다.
Cloud Storage에 저장된 데이터는 지정된 위치를 벗어나지 않습니다.
데이터는 온프레미스에서 Google Cloud로 전송될 때 엔드포인트에서 지정한 리전에서 종료됩니다.
데이터는 Google Cloud 서비스 간에 전송될 때 관할권에 유지됩니다.
위치 엔드포인트를 사용할 경우 다음 책임을 집니다.
데이터 상주 보증을 얻기 위해서는 위치 엔드포인트에 대한 요청이 엔드포인트로 지정된 동일한 위치에서 시작되어야 합니다. 예를 들어 Compute Engine 가상 머신을 사용하여
us-central1-storage.googleapis.com엔드포인트를 통해US-CENTRAL1에 상주하는 버킷에 대한 요청을 수행하는 경우 가상 머신도US-CENTRAL1에 상주해야 합니다.위치 엔드포인트는 지원되는 작업을 수행할 때만 사용해야 합니다. 지원되지 않는 작업을 수행하면 오류가 발생합니다.
위치 엔드포인트는 상호 연결 또는 VPN을 통해 온프레미스에서 Google Cloud로 전송 중인 트래픽과 Google Cloud 서비스 간에 전송 중인 트래픽을 지원합니다(예: BigQuery에서 Cloud Storage로). 인터넷 트래픽은 지원되지 않습니다.
지원되는 작업
다음 표에는 위치 엔드포인트로 수행할 수 있는 작업과 수행할 수 없는 작업이 요약되어 있습니다. 일반적으로 위치 내 작업은 위치 엔드포인트를 사용하여 수행할 수 있지만 위치 간 작업은 수행할 수 없습니다.
위치 엔드포인트를 사용하여 지원되지 않는 작업을 수행하려고 시도하면 Cloud Storage는 다음 메시지와 함께 400 HTTP 오류 코드를 반환합니다. "The endpoint does not implement this operation. Please use the global endpoint."
| 작업 | 객체 데이터 변형 | 위치 엔드포인트에서 사용 지원 |
|---|---|---|
| objects compose | 예 | 예1 |
| objects delete | 아니요 | 예1 |
| objects get | 예 | 예1 |
| objects insert | 예 | 예1 |
| objects list | 아니요 | 예1 |
| objects patch | 아니요 | 예1 |
| objects copy | 예 | 예4 |
| objects rewrite | 예 | 예4 |
| buckets insert | 아니요 | 예2 |
| buckets delete | 아니요 | 예3 |
| buckets get | 아니요 | 예2 |
| buckets patch | 아니요 | 예2 |
| buckets update | 아니요 | 예2 |
| buckets getIamPolicy | 아니요 | 예2 |
| buckets setIamPolicy | 아니요 | 예2 |
| buckets testIamPermissions | 아니요 | 예2 |
| buckets lockRetentionPolicy | 아니요 | 예2 |
| buckets BucketAccessControls | 아니요 | 예2 |
| buckets DefaultObjectAccessControls | 아니요 | 예2 |
| buckets ObjectAccessControls | 아니요 | 예2 |
| HMAC 키 작업 | 아니요 | 아니요 |
| 서비스 계정 작업 | 아니요 | 아니요 |
| Pub/Sub 알림 작업 | 작업에 따라 다름 | 아니요 |
| 객체 변경 알림 작업 | 작업에 따라 다름 | 아니요 |
| 일괄 작업 | 작업에 따라 다름 | 아니요 |
1 위치 엔드포인트를 사용하여 이 작업을 수행하려면 영향을 받는 객체가 포함된 버킷이 엔드포인트에서 지정된 위치에 있어야 합니다. 예를 들어 us-central1-storage.googleapis.com에 대한 객체 삭제 요청은 US-CENTRAL1 리전에 있는 버킷의 객체를 삭제하는 데만 사용할 수 있습니다. US-CENTRAL1이 아닌 위치에서 객체를 삭제하려고 하면 작업이 NOT_FOUND 오류를 반환합니다.
2 위치 엔드포인트를 사용하여 이 작업을 수행하려면 엔드포인트에서 지정한 위치에 버킷이 있어야 합니다. 예를 들어 us-central1-storage.googleapis.com에 대한 버킷 만들기 요청은 US-CENTRAL1 리전에서 버킷을 만드는 데만 사용할 수 있습니다. US-CENTRAL1이 아닌 위치에 버킷을 만들려고 하면 작업이 INVALID_ARGUMENT 오류를 반환합니다.
3 위치 엔드포인트를 사용하여 이 작업을 수행하려면 엔드포인트에서 지정한 위치에 버킷이 있어야 합니다. 예를 들어 us-central1-storage.googleapis.com에 대한 버킷 삭제 요청은 US-CENTRAL1 리전에 있는 버킷을 삭제하는 데만 사용할 수 있습니다. US-CENTRAL1이 아닌 위치에서 버킷을 삭제하려고 하면 작업이 NOT_FOUND 오류를 반환합니다.
4 위치 엔드포인트를 사용하여 이 작업을 수행하려면 소스 및 대상 버킷이 엔드포인트에서 지정된 위치에 모두 있어야 합니다. 예를 들어 두 버킷이 모두 같은 위치에 있는 경우 위치 엔드포인트를 사용하여 한 버킷에서 다른 버킷으로 객체를 복사할 수 있습니다. 그러나 버킷이 다른 위치에 있는 경우 위치 엔드포인트를 사용하여 한 버킷에서 다른 버킷으로 객체를 복사할 수 없습니다. 소스 또는 대상 버킷이 엔드포인트에서 지정한 위치와 다른 위치에 있는 경우 작업은 NOT_FOUND 오류를 반환합니다.
지원되는 리전
위치 엔드포인트는 모든 미국 리전, US 멀티 리전, NAM4 사전 정의된 이중 리전에서 지원됩니다. 지정할 수 있는 리전에 대한 자세한 내용은 버킷 위치를 참조하세요.
요청하기
콘솔
ITAR을 준수하는 방식으로 Google Cloud 콘솔을 사용하여 작업을 수행하는 방법에 대한 자세한 내용은 ITAR에 대한 제한 및 한도를 참조하세요.
명령줄
위치 엔드포인트에서 사용할 Google Cloud CLI를 구성하려면 다음 안내를 따르세요.
api_endpoint_overrides/storage속성을 사용할 위치 엔드포인트로 설정합니다.gcloud config set api_endpoint_overrides/storage https://LOCATION-storage.googleapis.com/
이 속성을 설정한 후에는 평소와 같이 gcloud CLI 명령어를 사용할 수 있습니다.
또는 각 명령어에서 CLOUDSDK_API_ENDPOINT_OVERRIDES_STORAGE 환경 변수를 설정하여 개별 명령어에 위치 엔드포인트를 사용할 수 있습니다. 예를 들면 다음과 같습니다.
CLOUDSDK_API_ENDPOINT_OVERRIDES_STORAGE=https://LOCATION-storage.googleapis.com/ gcloud ls gs://my-bucket
클라이언트 라이브러리
Cloud Storage 클라이언트 라이브러리는 요청 엔드포인트를 자동으로 관리하지만 수동으로 위치 엔드포인트를 설정할 수도 있습니다. 위치 엔드포인트를 설정하는 방법은 요청 엔드포인트를 사용하는 클라이언트 라이브러리 코드 샘플을 참조하세요.
REST API
JSON API
위치 엔드포인트에 요청할 때 다음 URI를 사용합니다.
객체 업로드를 제외한 일반 JSON API 요청의 경우 다음 엔드포인트를 사용합니다.
https://LOCATION-storage.googleapis.com
LOCATION을 지원되는 버킷 위치로 바꿉니다. 예를 들면
us-central1입니다.JSON API 객체 업로드의 경우 다음 엔드포인트를 사용합니다.
https://LOCATION-storage.googleapis.com/upload/storage/v1/b/BUCKET_NAME/o
다음과 같이 바꿉니다.
LOCATION을 지원되는 버킷 위치로 바꿉니다. 예를 들면
us-central1입니다.BUCKET_NAME을 객체를 업로드할 버킷의 이름으로 바꿉니다. 예를 들면
my-example-bucket입니다.
JSON API 객체 다운로드의 경우 다음 엔드포인트를 사용합니다.
https://LOCATION-storage.googleapis.com/download/storage/v1/b/BUCKET_NAME/o/OBJECT_NAME?alt=media
다음과 같이 바꿉니다.
LOCATION을 지원되는 버킷 위치로 바꿉니다. 예를 들면
us-central1입니다.BUCKET_NAME을 다운로드하려는 객체가 포함된 버킷의 이름으로 바꿉니다. 예를 들면
my-example-bucket입니다.OBJECT_NAME을 다운로드하려는 객체의 이름으로 바꿉니다. 예를 들면
waterfall.png입니다.
JSON API 엔드포인트는 HTTPS 요청만 지원합니다.
XML API
XML API를 사용하여 위치 엔드포인트에 요청할 때 가상 호스팅 스타일 엔드포인트 또는 경로 스타일 엔드포인트를 사용할 수 있습니다.
가상 호스팅 스타일 엔드포인트:
https://BUCKET_NAME.LOCATION-storage.googleapis.com
경로 스타일 엔드포인트:
https://LOCATION-storage.googleapis.com/BUCKET_NAME
두 엔드포인트 유형 모두 다음과 같이 바꿉니다.
LOCATION을 지원되는 버킷 위치로 바꿉니다. 예를 들면
us-central1입니다.BUCKET_NAME을 유효한 버킷 이름으로 바꿉니다. 예를 들면
my-example-bucket입니다.
XML API 엔드포인트는 보안 소켓 레이어(SSL) 암호화를 지원하므로, HTTP 또는 HTTPS를 사용할 수 있습니다. 특히 OAuth 2.0을 사용하여 Cloud Storage에 인증한다면 HTTPS를 사용하는 것이 좋습니다.
올바른 형식의 요청
Cloud Storage 도구에서 요청이 호환되는지 확인하려면 다음 안내를 따르세요.
요청 URI의 객체 이름 또는 쿼리 문자열에 표시되는 특수문자를 올바르게 인코딩해야 합니다.
버킷 이름 지정 및 객체 이름 지정 고려사항을 숙지합니다.
알려진 제약조건
mTLS 엔드포인트는 지원되지 않습니다.