Funções na biblioteca de cliente do App Engine para Cloud Storage

A biblioteca de cliente do App Engine para Cloud Storage oferece as seguintes funções:

Funções

  • cloudstorage.copy2() copia o arquivo especificado para o novo nome de arquivo especificado no mesmo bucket do Cloud Storage.
  • cloudstorage.delete() exclui o objeto especificado do bucket do Cloud Storage.
  • cloudstorage.listbucket() lista os objetos no bucket do Cloud Storage.
  • cloudstorage.open() abre um objeto existente no bucket do Cloud Storage para leitura ou substituição, ou cria um novo objeto, dependendo do modo especificado.
  • cloudstorage.stat() fornece informações de metadados sobre o arquivo, como o tipo de conteúdo, tamanho, carimbo de data/hora, resumo MD5 e cabeçalhos do Cloud Storage.

Depois que cloudstorage.open() for invocado para retornar o objeto semelhante a arquivo que representa o objeto do Cloud Storage especificado, você poderá usar as funções de arquivo Python padrão, como write() e close(), para gravar um objeto no bucket do Cloud Storage ou read() para ler um objeto do bucket do Cloud Storage.

Classes

Funções

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

Copia o arquivo especificado para o novo nome de arquivo especificado. Por padrão, copia também os metadados. Opcionalmente, você pode substituir os metadados na cópia fornecendo o parâmetro opcional metadata.

Gera cloudstorage.NotFoundError se o objeto especificado do Cloud Storage não existir ou cloudstorage.AuthorizationError se a autorização falhou.

Argumentos

src (Obrigatório)
O nome completo do arquivo do Cloud Storage para o objeto, no formato /bucket/object_name. O nome de arquivo precisa estar completo e pode incluir o delimitador `/`.
dst (Obrigatório)
O nome completo do arquivo do Cloud Storage para a cópia do objeto, no formato /bucket/object_name. O nome de arquivo precisa estar completo e pode incluir o delimitador `/`.
metadata=None (opcional)
Um dict de metadados para esta cópia, por exemplo, {'x-goog-meta-foo': 'bar'}. Se você fornecer o parâmetro de metadados, nenhum dos metadados originais será copiado para o novo arquivo. Se nenhum metadado for fornecido, (None), todos os metadados do arquivo de origem serão copiados.
retry_params= None (opcional.)
Um objeto RetryParams com as alterações que você quer fazer nas configurações padrão de tempo limite e de novas tentativas para esta chamada.

Exemplo

Para copiar um arquivo, mas adicionar novos metadados e ignorar o erro, se o arquivo de origem não existir:
import cloudstorage

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

Voltar ao início


cloudstorage.delete (filename, retry_params=None)

Exclui o arquivo especificado do bucket do Cloud Storage.

Gera cloudstorage.NotFoundError se o objeto do Cloud Storage especificado não existir.

Argumentos

filename (obrigatório)
O nome completo do arquivo do Cloud Storage para o objeto, no formato /bucket/object_name. O nome de arquivo precisa estar completo e pode incluir o delimitador `/`.
retry_params= None (opcional.)
Um objeto RetryParams com as alterações que você quer fazer nas configurações padrão de tempo limite e de novas tentativas para esta chamada.

Exemplo

Para excluir um arquivo, mas ignorar o erro quando o arquivo não existir:
import cloudstorage

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

Voltar ao início


cloudstorage.listbucket (path_prefix, marker=None, max_keys=None, delimiter=None, retry_params=None)
Retorna um objeto iterador do bucket. Esse iterador retorna uma lista classificada de objetos que correspondem a todos os filtros. Note que esta função é assíncrona. Ela não bloqueia, a menos que o iterador seja chamado antes de receber resultados.

Essa função opera em dois modos diferentes, dependendo de você usar ou não o argumento delimiter:

  • Modo normal (padrão): lista todos os arquivos no bucket sem qualquer conceito de hierarquia. O Cloud Storage não tem hierarquias de diretórios reais.
  • Modo de emulação de diretório: se você especificar o argumento delimiter, ele será usado como um separador de caminho para emular uma hierarquia de diretórios.

Argumentos

path_prefix (obrigatório)
Um caminho do Cloud Storage no formato /bucket ou /bucket/prefix, por exemplo, /bucket/foo/2001. Somente objetos que têm o caminho completo começando com path_prefix serão retornados.
marker= None (opcional)
String. Outro prefixo de caminho. Somente serão retornados os objetos que tiverem caminho completo iniciado de maneira lexicográfica após o marcador exclusivamente. O arquivo usado como `marcador` não é retornado. Por exemplo, se quiser que todos os arquivos listados a partir de superduperfoo3.txt sejam listados, especifique o arquivo imediatamente anterior a superduperfoo3.txt, por exemplo: 
stat = cloudstorage.listbucket("/my_bucket/foo", marker='/my_bucket/foo/superduperfoo2.txt')
 Uma maneira de usar esse parâmetro é usá-lo com max_keys para "percorrer" os nomes de arquivo do bucket.
max_keys= None (opcional)
Número inteiro. Especifica o número máximo de objetos a serem retornados. Use-o se você souber quantos objetos quer. Caso contrário, a biblioteca de cliente do Cloud Storage automaticamente armazena e percorre todos os resultados. Pode ser usado com marker para paginar nomes de arquivos em um bucket. 
stats = cloudstorage.listbucket(bucket + '/foo', max_keys=page_size, marker=stat.filename)
delimiter= None (opcional)
String. Ativa o modo de diretório. Você pode especificar um ou vários caracteres para serem usados como um separador de diretório.
retry_params= None (opcional.)
Um objeto RetryParams com as alterações que você quer fazer nas configurações padrão de tempo limite e de novas tentativas para esta chamada.

Valor do resultado

Retorna um iterador de objetos GCSFileStat sobre os arquivos correspondentes, classificados por nome de arquivo. No modo normal, o valor retornado os objetos GCSFileStat têm os seguintes dados:

  • filename
  • etagA representação hexadecimal do hash MD5 do conteúdo do arquivo.
  • st_size (tamanho do conteúdo dos cabeçalhos)
  • st_ctime
  • is_dir

Observação: se a propriedade is_dir do objeto GCSFileStat for True, a única outra propriedade no objeto será filename. Se is_dir for False, o GCSFileStat também conterá todas as outras propriedades.

Voltar ao início


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

No modo de leitura (r), o objeto do Cloud Storage especificado para leitura é aberto. No modo de gravação w, se o arquivo especificado existir, ele será aberto para uma substituição (o anexo não é compatível). Se o arquivo não existir, ele será criado no bucket especificado.

Ao terminar de gravar, se você quiser ler o arquivo e/ou armazená-lo no Cloud Storage, feche o arquivo usando a função close. Não é um erro se você não chamar close, mas o arquivo não será legível ou persistirá no Cloud Storage.

Gera:

Argumentos

filename (obrigatório)
O arquivo a ser aberto, no formato /bucket/object. Por exemplo, /my_bucket/lyrics/southamerica/list5.txt.
mode (opcional)
String. Especifique 'r' para abrir um arquivo para leitura (padrão). Especifique 'w' para abrir um arquivo existente para substituir ou para criar um novo arquivo.

content_type: (opcional)
String. Usado apenas no modo de gravação. Especifique o tipo MIME do arquivo. Qualquer tipo MIME válido pode ser especificado. Se você não fornecer esse valor, o Cloud Storage usará o tipo binary/octet-stream por padrão quando disponibilizar o objeto.
options: (opcional)

Dict. Usado apenas no modo de gravação. As opções compatíveis são x-goog-acl, x-goog-meta-, cache-control, content-disposition e content-encoding.

Se você não fornecer uma opção x-goog-acl, o Cloud Storage usará a ACL padrão do bucket. Os valores válidos para x-goog-acl estão listados na documentação do Cloud Storage para x-goog-acl.

Você pode especificar metadados de objetos personalizados usando cabeçalhos x-goog-meta-. Por exemplo:

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: (opcional)
Número inteiro. Usado apenas no modo de leitura. Se você não definir esse valor, o tamanho do buffer padrão será usado (recomendado). Ao ler, você precisa ler por read_buffer_size para conseguir o melhor desempenho de pré-busca.
retry_params= None (opcional.)
Um objeto RetryParams com as alterações que você quer fazer nas configurações padrão de tempo limite e de novas tentativas para esta chamada.

Valor do resultado

Retorna um buffer de leitura ou gravação, compatível com uma interface semelhante a arquivo, na qual é possível invocar as funções read, write e close padrão do Python. Feche este buffer depois que você terminar de ler ou gravar.

Voltar ao início


cloudstorage.stat(filename, retry_params=None)

Retorna um objeto GCSFileStat contendo metadados de arquivo.

Gera cloudstorage.NotFoundError se o objeto do Cloud Storage especificado não existir.

Argumentos

filename (obrigatório)
O arquivo a ser aberto, no formato /bucket/object. Por exemplo, /my_bucket/lyrics/southamerica/list5.txt
retry_params= None (opcional.)
Um objeto RetryParams com as alterações que você quer fazer nas configurações padrão de tempo limite e de novas tentativas para esta chamada.

Valor do resultado

Retorna um objeto GCSFileStat contendo metadados de arquivo.

Voltar ao início