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

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

Funções

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

Depois de invocar cloudstorage.open() para devolver o objeto semelhante a um ficheiro que representa o objeto do Cloud Storage especificado, pode usar as funções de ficheiro padrão do Python, como write() e close(), para escrever um objeto no contentor do Cloud Storage ou read() para ler um objeto do contentor do Cloud Storage.

Aulas

Funções

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

Copia o ficheiro especificado para o novo nome de ficheiro especificado, copiando também os metadados por predefinição. Opcionalmente, pode substituir os metadados na cópia fornecendo o parâmetro metadata opcional.

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

Argumentos

src (Obrigatório)
O nome completo do ficheiro do Cloud Storage para o objeto, no formato /bucket/object_name. Tem de ser um nome de ficheiro completo e pode incluir o delimitador `/`.
dst (Obrigatório)
O nome completo do ficheiro do Cloud Storage para a cópia do objeto, no formato /bucket/object_name. Tem de ser um nome de ficheiro completo e pode incluir o delimitador `/`.
metadata= None (Opcional.)
Um dicionário de metadados para esta cópia, por exemplo, {'x-goog-meta-foo': 'bar'}. Se fornecer o parâmetro de metadados, nenhum dos metadados originais é copiado para o novo ficheiro. Se não forem fornecidos metadados (None), todos os metadados do ficheiro de origem são copiados.
retry_params= None (Opcional.)
Um objeto RetryParams no qual fornece as alterações que quer fazer às predefinições de limite de tempo e definições de repetição para esta chamada.

Exemplo

Para copiar um ficheiro, mas adicionar novos metadados e ignorar o erro se o ficheiro 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)

Elimina o ficheiro especificado do contentor do Cloud Storage.

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

Argumentos

filename (Obrigatório)
O nome completo do ficheiro do Cloud Storage para o objeto, no formato /bucket/object_name. Tem de ser um nome de ficheiro completo e pode incluir o delimitador `/`.
retry_params= None (Opcional.)
Um objeto RetryParams no qual fornece as alterações que quer fazer às predefinições de limite de tempo e definições de repetição para esta chamada.

Exemplo

Para eliminar um ficheiro, mas ignorar o erro quando o ficheiro não existe:
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)
Devolve um objeto iterador de contentor. Este iterador devolve uma lista ordenada de objetos que correspondem a todos os filtros. Tenha em atenção que esta função é assíncrona. Não bloqueia, a menos que o iterador seja chamado antes de o iterador obter resultados.

Esta função opera em dois modos diferentes, consoante use ou não o argumento delimiter:

  • Modo normal (predefinição): lista todos os ficheiros no contentor sem qualquer conceito de hierarquia. (O Cloud Storage não tem hierarquias de diretórios reais.)
  • Modo de emulação de diretório: se especificar o argumento delimiter, este é 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. Apenas são devolvidos os objetos cujo caminho completo começa com path_prefix.
marker= None (opcional)
String. Outro prefixo do caminho. Apenas são devolvidos os objetos cujo caminho completo começa lexicograficamente após o marcador, exclusivamente. O ficheiro usado como `marker` não é devolvido. Por exemplo, se quiser que todos os ficheiros listados a partir de superduperfoo3.txt sejam listados, especifique o ficheiro imediatamente anterior a superduperfoo3.txt, por exemplo: 
stat = cloudstorage.listbucket("/my_bucket/foo", marker='/my_bucket/foo/superduperfoo2.txt')
 Uma forma de usar este parâmetro é usá-lo com max_keys para "navegar" pelos nomes dos ficheiros do contentor.
max_keys= None (opcional)
Número inteiro. Especifica o número máximo de objetos a devolver. Use-o se souber quantos objetos quer. (Caso contrário, a biblioteca do cliente do Cloud Storage armazena automaticamente em buffer e pagina todos os resultados.) Pode ser usado com marker para percorrer os nomes de ficheiros num contentor. 
stats = cloudstorage.listbucket(bucket + '/foo', max_keys=page_size, marker=stat.filename)
delimitador= Nenhum (opcional)
String. Ativa o modo de diretório. Pode especificar um ou vários carateres a usar como separador de diretórios.
retry_params= None (Opcional.)
Um objeto RetryParams no qual fornece as alterações que quer fazer às predefinições de limite de tempo e definições de repetição para esta chamada.

Valor do resultado

Devolve um iterador de objetos GCSFileStat sobre os ficheiros correspondentes, ordenados por nome de ficheiro. No modo normal, os objetos GCSFileStat devolvidos têm os seguintes dados:

  • filename
  • etag (A representação hexadecimal do hash MD5 do conteúdo do ficheiro)
  • st_size (duração do conteúdo dos cabeçalhos)
  • st_ctime
  • is_dir

Nota: se a propriedade is_dir do objeto GCSFileStat for True, a única outra propriedade no objeto é filename. Se is_dir for False, o GCSFileStat também contém 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), abre o objeto do Cloud Storage especificado para leitura. No modo de escrita w, se o ficheiro especificado existir, este é aberto para substituição (o anexo não é suportado). Se o ficheiro não existir, é criado no contentor especificado.

Quando terminar de escrever, se quiser ler o ficheiro e/ou armazená-lo no Cloud Storage, feche o ficheiro com a função close. Não é um erro se não chamar close, mas o ficheiro não vai ser legível nem persistente no Cloud Storage.

Aumentos:

Argumentos

filename (Obrigatório)
O ficheiro a abrir, no formato /bucket/object. Por exemplo,/my_bucket/lyrics/southamerica/list5.txt.
mode (Opcional)
String. Especifique "r" para abrir um ficheiro para leitura (predefinição). Especifique "w" para abrir um ficheiro existente para substituição ou para criar um novo ficheiro.

content_type: (opcional)
String. Usado apenas no modo de escrita. Deve especificar o tipo MIME do ficheiro (pode especificar qualquer tipo MIME válido). Se não fornecer este valor, o Cloud Storage usa o tipo binary/octet-stream por predefinição quando publica o objeto.
opções: (opcional)

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

Se não fornecer uma opção x-goog-acl, o Cloud Storage usa a LCA predefinida do contentor. Os valores válidos para x-goog-acl estão listados na documentação do Cloud Storage para x-goog-acl.

Pode especificar metadados de objetos personalizados através de 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 não definir este valor, é usado o tamanho do buffer predefinido (recomendado). Quando lê, deve fazê-lo por read_buffer_size para um desempenho de obtenção prévia ideal.
retry_params= None (Opcional.)
Um objeto RetryParams no qual fornece as alterações que quer fazer às predefinições de limite de tempo e definições de repetição para esta chamada.

Valor do resultado

Devolve um buffer de leitura ou escrita, que suporta uma interface semelhante a um ficheiro na qual pode invocar as funções read, write e close padrão do Python. Este buffer tem de ser fechado depois de terminar a leitura ou a escrita.

Voltar ao início


cloudstorage.stat(filename, retry_params=None)

Devolve um objeto GCSFileStat que contém metadados do ficheiro.

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

Argumentos

filename (Obrigatório)
O ficheiro a abrir, no formato /bucket/object. Por exemplo,/my_bucket/lyrics/southamerica/list5.txt
retry_params= None (Opcional.)
Um objeto RetryParams no qual fornece as alterações que quer fazer às predefinições de limite de tempo e definições de repetição para esta chamada.

Valor do resultado

Devolve um objeto GCSFileStat que contém metadados do ficheiro.

Voltar ao início