Cloud Storage 用 App Engine クライアント ライブラリの関数

Cloud Storage 用 App Engine クライアント ライブラリには次の関数があります。

関数

• cloudstorage.copy2() - 指定したファイルを、同じ Cloud Storage バケットの指定した新しいファイル名にコピーします。
• cloudstorage.delete() - 指定したオブジェクトを Cloud Storage バケットから削除します。
• cloudstorage.listbucket() - Cloud Storage バケットのオブジェクトを一覧表示します。
• cloudstorage.open() - 指定したモードに応じて Cloud Storage バケットの既存のオブジェクトを読み取り用または上書き用に開いたり、新規オブジェクトを作成したりします。
• cloudstorage.stat() - ファイルに関するメタデータ情報（コンテンツのタイプ、サイズ、タイムスタンプ、MD5 ダイジェスト、Cloud Storage ヘッダーなど）を提供します。

cloudstorage.open() が呼び出されて、指定した Cloud Storage オブジェクトを表すファイルに似たオブジェクトが返されると、Cloud Storage バケットにオブジェクトを書き込むための write() や close()、または、Cloud Storage バケットからオブジェクトを読み取るための read() などの標準的な Python ファイル関数を使用できます。

クラス

• GCSFileStat()
• RetryParams()

関数

cloudstorage.copy2 (src, dst, metadata=None, retry_params=None)

指定したファイルを、指定した新しいファイル名にコピーします。デフォルトではメタデータも一緒にコピーします。オプションとして、コピーのメタデータを上書きするには、任意の metadata パラメータを指定します。

指定した Cloud Storage オブジェクトが存在しない場合には cloudstorage.NotFoundError、承認に失敗した場合には cloudstorage.AuthorizationError がそれぞれ生成されます。

引数

src（必須）

オブジェクトを表す完全な Cloud Storage ファイル名（形式は /bucket/object_name）。完全なファイル名でなければならず、区切り文字 `/` を含めることができます。

dst（必須）

オブジェクトのコピーを表す完全な Cloud Storage ファイル名（形式は /bucket/object_name）。完全なファイル名でなければならず、区切り文字 `/` を含めることができます。

metadata= None（省略可能）

このコピーのメタデータのディクショナリ（たとえば {'x-goog-meta-foo': 'bar'}）。 metadata パラメータを指定した場合、元のメタデータはどれも新規ファイルにコピーされません。メタデータが指定されていない場合（None）、ソースファイルのメタデータがすべてコピーされます。

retry_params= None（省略可能）

RetryParams オブジェクト。この呼び出しのデフォルトのタイムアウトや再試行の設定を変更する場合は、ここで指定します。

例

ファイルをコピーし、新しいメタデータを追加して、ソースファイルが存在しない場合のエラーを無視します。

import cloudstorage

try:
  cloudstorage.copy2('/my_bucket/README', '/my_bucket/README2', metadata={'x-goog-meta-zzzzz': 'zzzzz'})
except cloudstorage.NotFoundError:
  pass

トップへ戻る

cloudstorage.delete (filename, retry_params=None)

指定したファイルを Cloud Storage バケットから削除します。

指定した Cloud Storage オブジェクトが存在しない場合、cloudstorage.NotFoundError を生成します。

引数

filename （必須）

オブジェクトを表す完全な Cloud Storage ファイル名（形式は /bucket/object_name）。完全なファイル名でなければならず、区切り文字 `/` を含めることができます。

retry_params= None（省略可能）

RetryParams オブジェクト。この呼び出しのデフォルトのタイムアウトや再試行の設定を変更する場合は、ここで指定します。

例

ファイルを削除しますが、ファイルが存在しない場合のエラーを無視します。

import cloudstorage

try:
  cloudstorage.delete(filename)
except cloudstorage.NotFoundError:
  pass

トップへ戻る

cloudstorage.listbucket (path_prefix, marker=None, max_keys=None, delimiter=None, retry_params=None)

バケット イテレータ オブジェクトを返します。このイテレータでは、すべてのフィルタに一致するオブジェクトのリストがソートした状態で返されます。なお、この関数は非同期的です。イテレータによって結果が取得されるる前に、イテレータが呼び出されない限り、ブロックしません。

delimiter 引数を使用するかどうかに応じて、この関数は次の 2 つの異なるモードで動作します。

• 通常モード（デフォルト）: 階層の概念なしで、バケット内のすべてのファイルを一覧表示します。（Cloud Storage には実際のディレクトリ階層がありません。）
• ディレクトリ エミュレーション モード: delimiter 引数を指定した場合、それがパスの区切り文字として使用され、ディレクトリの階層をエミュレートします。

引数

path_prefix（必須）

/bucket または /bucket/prefix という形式の Cloud Storage パス（たとえば /bucket/foo/2001）。フルパスが path_prefix で始まるオブジェクトのみが返されます。

marker= None（省略可能）

文字列。別のパス プレフィクス。辞書順でマーカーの後続にあるフルパスを持つオブジェクトのみが限定的に返されます。「マーカー」として使用されるファイルは返されません。たとえば superduperfoo3.txt から始めてすべてのファイルの一覧を得るには、superduperfoo3.txt の直前のファイルを次のように指定します。

stat = cloudstorage.listbucket("/my_bucket/foo", marker='/my_bucket/foo/superduperfoo2.txt')

このパラメータを使用する 1 つの方法として、バケット ファイル名を「ページ割り付け」するために max_keys とともに使用できます。

max_keys= None（省略可能）

整数返されるオブジェクトの最大数を指定します。必要なオブジェクトの数がわかっている場合にこれを使用します。（指定しない場合、Cloud Storage クライアント ライブラリはすべての結果を自動的にバッファしてページングします。）これを marker とともに使用すると、バケット内のファイル名を「ページ割り付け」できます。

stats = cloudstorage.listbucket(bucket + '/foo', max_keys=page_size, marker=stat.filename)

delimiter= None（省略可能）

文字列。ディレクトリ モードを有効にします。ディレクトリの区切り文字として使われる 1 つまたは複数の文字を指定できます。

retry_params= None（省略可能）

RetryParams オブジェクト。この呼び出しのデフォルトのタイムアウトや再試行の設定を変更する場合は、ここで指定します。

結果値

一致するファイルの GCSFileStat オブジェクトのイテレータを、ファイル名でソートした状態で返します。通常モードでは、返される GCSFileStat オブジェクトに次のデータが含まれます。

• filename
• etag（ファイルのコンテンツの MD5 ハッシュを示す 16 進数表現）
• st_size（ヘッダーのコンテンツ長）
• st_ctime
• is_dir

注: GCSFileStat オブジェクトの is_dir プロパティが True である場合、そのオブジェクトの他のプロパティは filename のみになります。is_dir が False の場合は、GCSFileStat には他のすべてのプロパティも含まれます。

トップへ戻る

cloudstorage.open(filename, mode='r', content_type=None, options=None, read_buffer_size=storage_api.ReadBuffer.DEFAULT_BUFFER_SIZE, retry_params=None)

読み取りモード（r）では、指定した Cloud Storage オブジェクトが読み取り用に開きます。書き込みモード w では、指定したファイルが存在すれば、上書き用にそれが開きます（内容の追加はサポートされていません）。ファイルが存在しない場合、指定したバケットにそれが作成されます。

書き込みが完了した後、そのファイルを読み取るかまたは Cloud Storage に保存する場合は、close 関数を使ってファイルを閉じてください。close を呼び出さなくてもエラーにはなりませんが、ファイルを読み取ることも Cloud Storage に保持することもできません。

発生するエラー:

• cloudstorage.NotFoundError は、読み取りモードで、指定したオブジェクトが存在しない場合に発生します。

引数

filename（必須）

開くファイル（形式は /bucket/object）。例えば、/my_bucket/lyrics/southamerica/list5.txt。

mode （省略可能）

文字列。読み取り用にファイルを開くには 'r' を指定します（デフォルト）。既存のファイルを上書き用に開くか、新規ファイルを作成するには、'w' を指定します。

content_type: （省略可能）

文字列。書き込みモードでのみ使用します。ファイルの MIME タイプを指定してください（有効な任意の MIME タイプを指定できます）。この値を指定しない場合、Cloud Storage はオブジェクトが提供されると、デフォルトで binary/octet-stream タイプになります。

options: （省略可能）

ディクショナリ。書き込みモードでのみ使用します。サポートされているオプションは x-goog-acl、x-goog-meta-、cache-control、content-disposition、content-encoding です。

x-goog-acl オプションを指定しない場合、Cloud Storage ではバケットのデフォルト ACL が使用されます。x-goog-acl に有効な値は、x-goog-acl に関する Cloud Storage ドキュメントに一覧表示されています。

x-goog-meta- ヘッダーを使用して、カスタム オブジェクト メタデータを指定できます。次に例を示します。

gcs_file = cloudstorage.open(filename, 'w', content_type='text/plain', options={'x-goog-acl': 'private','x-goog-meta-foo': 'foo', 'x-goog-meta-bar': 'bar'})

read_buffer_size: （省略可能）

整数読み取りモードでのみ使用されます。この値を設定しない場合、デフォルトのバッファサイズが使用されます（これが推奨されます）。読み取るときには、最適なプリフェッチ パフォーマンスを得るために read_buffer_size で読み取ってください。

retry_params= None（省略可能）

RetryParams オブジェクト。この呼び出しのデフォルトのタイムアウトや再試行の設定を変更する場合は、ここで指定します。

結果値

読み取りまたは書き込みのバッファを返します。標準的な Python read、write、close 関数を呼び出せるファイルに似たインターフェースがここでサポートされます。読み取り/書き込みが終了した後にこのバッファを閉じる必要があります。

トップへ戻る

cloudstorage.stat(filename, retry_params=None)

ファイル メタデータを含む GCSFileStat オブジェクトを返します。

指定した Cloud Storage オブジェクトが存在しない場合、cloudstorage.NotFoundError を生成します。

引数

filename（必須）

開くファイル（形式は /bucket/object）。例えば、/my_bucket/lyrics/southamerica/list5.txt

retry_params= None（省略可能）

RetryParams オブジェクト。この呼び出しのデフォルトのタイムアウトや再試行の設定を変更する場合は、ここで指定します。

結果値

ファイル メタデータを含む GCSFileStat オブジェクトを返します。

トップへ戻る