XML API 개요

이 문서는 Cloud Storage XML API를 간략하게 설명하고 소프트웨어 개발자를 대상으로 합니다. 여기에서는 RESTful 서비스와 웹 프로그래밍에 익숙하고 HTTP 요청을 통해 작동하는 애플리케이션을 만드는 데 익숙하다고 가정합니다. 이에 해당하지 않는다면 다음 대안 중 하나를 사용해 보세요.

  • Cloud Storage를 처음 시작하는 경우 먼저 Cloud Console 빠른 시작 또는 gsutil 빠른 시작을 시도해 보세요. 이 가이드에서는 API를 직접 사용할 필요 없이 Cloud Storage를 사용하는 기본적인 방법을 보여줍니다.

  • 특정 프로그래밍 언어로 작업하는 경우 Cloud Storage 클라이언트 라이브러리를 사용할 수 있습니다.

  • 모바일 또는 웹 앱 개발자인 경우 Cloud Storage용 Firebase SDK를 사용할 수 있습니다.

  • 소프트웨어 개발자가 아닌 개인 정보를 클라우드에 저장하고 다른 사용자와 공유하려면 Google 드라이브를 사용하면 됩니다.

개요

Cloud Storage XML API는 프로그래매틱 방식으로 Cloud Storage 데이터를 관리할 수 있는 RESTful 인터페이스입니다. RESTful API로서 메서드 정보와 정보 복제를 사용하여 수행할 작업을 정의합니다.

HTTP 메서드를 사용하여 범위에 지정된 리소스에 대한 작업을 수행합니다. XML API에서 사용할 수 있는 작업 목록은 XML API 요청 메서드를 참조하세요.

XML API를 통한 Cloud Storage 액세스는 다른 스토리지 제공업체에서 작동해야 하는 도구와 라이브러리를 사용하거나 다른 스토리지 제공업체에서 Cloud Storage로 마이그레이션하는 경우에 유용합니다. 번역사의 경우, 기존 도구와 라이브러리를 몇 가지만 변경하면 Cloud Storage에 요청을 보낼 수 있습니다. Cloud Storage로의 마이그레이션에 대한 자세한 내용은 Amazon S3에서 Google Cloud Storage로 마이그레이션을 참조하세요.

요청

Cloud Storage XML API는 HTTP 요청을 수행하고 HTTP 응답을 처리하기 위한 웹 인터페이스를 제공합니다. 이 API는 HTTP/1.1, HTTP/2 및 HTTP/3 프로토콜과 호환됩니다. 각 요청은 표준 HTTP 메서드를 구현합니다. 이러한 메서드와 함께 다양한 HTTP 요청 헤더를 사용할 수 있습니다.

인증

Cloud Storage에 대한 모든 요청은 인증되어야 합니다. 단, 익명 액세스가 가능한 객체 또는 버킷에 대한 요청은 예외입니다. Cloud Storage 요청에 대한 승인 헤더를 설정하는 방법에 대한 자세한 내용은 인증을 참조하세요.

엔드포인트

대부분의 Cloud Storage XML API 요청은 버킷 및 객체에 액세스할 때 다음 URI를 사용합니다.

storage.googleapis.com

URI에 버킷과 객체를 추가하여 범위를 더 자세히 지정할 수 있습니다. 결과 URL은 다음 두 가지 형식을 취할 수 있습니다.

BUCKET_NAME.storage.googleapis.com/OBJECT_NAME
storage.googleapis.com/BUCKET_NAME/OBJECT_NAME

Cloud Storage URI는 보안 소켓 레이어 (SSL) 암호화를 사용하는 보안 요청 (HTTP) 및 보안 요청 (HTTPS)과 함께 사용할 수 있습니다.

XML API의 전용 업로드 및 다운로드 엔드포인트와 같은 추가 엔드포인트는 요청 엔드포인트를 참조하세요.

헤더 및 쿼리 문자열 매개변수

Cloud Storage XML API는 HTTP 요청 헤더를 지원합니다. x-goog- 프리픽스가 있는 여러 확장 프로그램 (커스텀) 요청 헤더도 지원합니다. 요청 헤더 요구사항은 수행하는 요청의 종류에 따라 다릅니다. 자주 사용되는 몇 가지 요청 헤더는 다음과 같습니다.

요청 헤더 설명 사용량
Authorization 요청의 인증 문자열입니다. 인증된 모든 요청에 필요합니다.
Content-Length 요청 본문의 크기 (헤더 제외)입니다. 청크 분할 전송을 제외한 모든 PUT 및 POST 요청에 필요합니다.
Content-Type 요청 본문의 MIME 유형(예: application/xml 또는 text/html) 항목 본문이 포함된 요청에 권장됩니다.
Date 요청 날짜 및 시간입니다. 모든 요청의 필수 항목.
Host 요청의 URI입니다. 모든 요청의 필수 항목.
x-goog-project-id 사용할 프로젝트의 ID입니다. Amazon S3와의 호환성과 같이 상호 운용성을 위해 XML API를 사용하는 경우를 제외하고 버킷 또는 버킷 나열에 필요합니다. 자세한 내용은 Amazon S3에서 Google Cloud Storage로 마이그레이션을 참조하세요.

Cloud Storage XML API는 또한 요청 범위를 지정하는 데 사용할 수 있는 다양한 쿼리 문자열 매개변수도 지원합니다. 다음 구문을 사용하여 요청의 HTTP 경로 부분에 쿼리 문자열 매개변수를 추가합니다.

PATH_TO_OBJECT/?PARAMETER=VALUE&PARAMETER=VALUE...

XML API 헤더 및 쿼리 문자열 매개변수의 전체 목록은 HTTP 헤더 및 쿼리 문자열 매개변수를 참조하세요.

요청 예

다음 예시는 일반적인 인증된 Cloud Storage 요청을 보여줍니다. 이 요청은 travel-maps라는 버킷에 저장된 객체 목록을 검색합니다. 이 요청은 객체 목록을 접두사 /europe/france가 있는 객체로만 제한합니다.

GET /?prefix=/europe/france/ HTTP/1.1
Host: travel-maps.storage.googleapis.com
Date: Wed, 17 Feb 2010 15:31:56 -0800
Content-Length: 0
Authorization: Bearer ya29.AHES6ZRVmB7fkLtd1XTmq6mo0S1wqZZi3-Lh_s-6Uw7p8vtgSwg

응답

Cloud Storage XML API는 표준 HTTP 응답 헤더와 여러 확장 프로그램 (커스텀) 응답 헤더를 반환합니다. 응답 헤더는 수행하는 작업에 따라 달라집니다. 자주 사용되는 몇 가지 응답 헤더는 다음과 같습니다.

응답 헤더 설명
Cache-Control 응답의 캐시 제어 설정입니다.
Content-Length 응답 본문(헤더 제외)의 크기입니다(바이트 단위).
Content-Type 응답 본문의 MIME 유형(예: application/xml 또는 text/html)
Date 응답의 날짜 및 시간입니다.
ETag HTTP 1.1 항목 태그: 이 태그를 사용하여

객체가 변경되었는지 여부를 나타냅니다.

응답에는 상태 코드도 포함될 수 있습니다. Cloud Storage는 표준 HTTP 상태 코드를 사용합니다. 오류 응답에는 오류 본문에 대한 정보가 포함된 XML 문서가 응답 본문에 포함됩니다. XML API에서 사용하는 상태 코드 목록은 HTTP 상태 및 오류 코드를 참조하세요.

다음 예시에서는 일반적인 Cloud Storage 응답을 보여줍니다. 이 예시는 버킷 콘텐츠 나열의 요청에 대한 응답입니다. 버킷 이름은 travel-maps이며 요청 범위가 지정되어 있으므로 프리픽스가 /europe/france/인 객체만 목록에 반환됩니다.

HTTP/1.1 200 OK
Content-Length: 4061
Content-Type: application/xml
Date: Wed, 17 Feb 2010 23:31:57 GMT
Cache-Control: private, max-age=0

<?xml version='1.0' encoding='utf-8'?>
<ListBucketResult xmlns='http://doc.storage.googleapis.com/2010-03-01'>
  <Name>travel-maps</Name>
  <Prefix>/europe/france/</Prefix>
  <Marker></Marker>
  <IsTruncated>false</IsTruncated>
  <Contents>
    <Key>europe/france/cannes.jpg</Key>
    <LastModified>2010-02-17T22:11:12.487Z</LastModified>
    <ETag>"53fc311c15eda0a031809982ccf92aac"</ETag>
    <Size>5061631</Size>
    <StorageClass>STANDARD</StorageClass>
    <Owner>
      <ID>84fac329bceSAMPLE777d5d22b8SAMPLE77d85ac2SAMPLE2dfcf7c4adf34da46</ID>
      <DisplayName></DisplayName>
    </Owner>
  </Contents>
  <Contents>
    <Key>europe/france/paris.jpg</Key>
    <LastModified>2010-02-17T22:09:57.457Z</LastModified>
    <ETag>"53fc311c15eda0a031809982ccf92aac"</ETag>
    <Size>5061631</Size>
    <StorageClass>STANDARD</StorageClass>
    <Owner>
      <ID>84fac329bceSAMPLE777d5d22b8SAMPLE77d85ac2SAMPLE2dfcf7c4adf34da46</ID>
      <DisplayName></DisplayName>
    </Owner>
  </Contents>
</ListBucketResult>