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 リクエストの Authorization ヘッダーの設定方法について詳しくは、認証をご覧ください。

エンドポイント

ほとんどの Cloud Storage XML API リクエストでは、次の URI を使用してバケットとオブジェクトにアクセスします。

storage.googleapis.com

URI にバケットやオブジェクトを追加して、さらにスコープを設定できます。生成される URL には次の 2 つの形式があります。

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

Cloud Storage の URI は、保護されていないリクエスト(HTTP)と、セキュア ソケット レイヤ(SSL)暗号化を使用した安全なリクエスト(HTTPS)で使用できます。

XML API 専用のアップロード エンドポイントやダウンロード エンドポイントなど、追加のエンドポイントについては、リクエスト エンドポイントをご覧ください。

ヘッダーとクエリ文字列パラメータ

Cloud Storage XML API は、HTTP リクエスト ヘッダーをサポートしています。また、x-goog- 接頭辞が付いた拡張(カスタム)リクエスト ヘッダーもサポートしています。リクエスト ヘッダーの要件は、実行するリクエストのタイプによって異なります。よく使用されるリクエスト ヘッダーには次のものがあります。

リクエスト ヘッダー 説明 使用方法
Authorization リクエストの認証文字列。 すべての認証リクエストで必須。
Content-Length ヘッダーを除くレスポンスの本文のサイズ(バイト単位)。 チャンク形式転送を除くすべての PUT および POST リクエストで必須。
Content-Type application/xmltext/html など、リクエスト本文の MIME タイプ。 エンティティ ボディを含むリクエストで推奨。
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 application/xmltext/html など、レスポンスの本文の MIME タイプ。
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>