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 对象的类文件对象后，您可以使用 write() 和 close() 等 Python 标准文件函数向 Cloud Storage 存储分区写入对象，或使用 read() 读取 Cloud Storage 存储分区中的对象。

类

函数

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 参数，此函数会以两种不同的模式运行：

  • 常规模式（默认）：列出存储分区中的所有文件，无层次结构。（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')
使用该参数的唯一方法是将其与 max_keys 一起使用，以便对存储分区文件名进行“分页”。
max_keys= None（可选）
整数。指定要返回最大对象数。如果您知道所需的对象数量，请使用该函数。（否则，Cloud Storage 客户端库将自动缓冲所有结果并对其进行分页。）该参数可与 marker 一起使用，用于对存储分区中的文件名进行分页。
stats = cloudstorage.listbucket(bucket + '/foo', max_keys=page_size, marker=stat.filename)
delimiter= None（可选）
字符串。启动目录模式。您可以指定一个或多个字符作为目录分隔符。
retry_params= None（可选）
RetryParams 对象，用于声明您要对相应调用的默认超时和重试设置进行的任何更改。

结果值

返回匹配文件的 GCSFileStat 对象迭代器，按文件名排序。常规模式下，返回的 GCSFileStat 对象包含以下数据：

  • filename
  • etag（文件内容的 MD5 哈希的十六进制表示）
  • 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 中读取或保留。

引发：

参数

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 的 Cloud Storage 文档中列出了 x-goog-acl 的有效值。

您可以使用 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 对象。

返回页首