Acerca dos objetos do Cloud Storage

Esta página descreve os objetos, um recurso no Cloud Storage. Para uma vista geral de como funciona o Cloud Storage, consulte a vista geral do produto Cloud Storage.

Objetos

Os objetos são os elementos individuais de dados que armazena no Cloud Storage. Não existe limite para o número de objetos que pode criar num contentor.

Os objetos têm dois componentes: dados de objetos e metadados de objetos. Os dados de objetos são normalmente um ficheiro que quer armazenar no Cloud Storage e são completamente opacos para o Cloud Storage. Os metadados de objetos são uma coleção de pares de nome-valor que descrevem várias qualidades de objetos.

Dois elementos importantes dos metadados de objetos comuns a todos os objetos são o nome do objeto e o respetivo número de geração. Quando adiciona um objeto a um contentor do Cloud Storage, especifica o nome do objeto e o Cloud Storage atribui o número de geração. Em conjunto, o nome e a geração identificam de forma exclusiva o objeto nesse contentor.

Pode usar listas de controlo de acesso (ACLs) para controlar o acesso a objetos individuais. Também pode usar a gestão de identidade e de acesso (IAM) para controlar o acesso a todos os objetos num contentor ou numa pasta gerida.

Considerações sobre a nomenclatura

Ao atribuir nomes a objetos no Cloud Storage, é essencial cumprir requisitos específicos para garantir a compatibilidade e evitar erros. Estes requisitos aplicam-se a contentores de espaço de nomes simples e a contentores com o espaço de nomes hierárquico ativado.

Requisitos gerais

  • Os nomes de objetos podem conter qualquer sequência de carateres Unicode válidos.
  • Os nomes dos objetos não podem conter carateres de retorno ou de alimentação de linha.
    • Tenha em atenção que as barras invertidas enviadas através de interfaces, como a CLI gcloud e a Google Cloud consola, são ignoradas nos bastidores. Por exemplo, \n torna-se \\n. A restrição de retorno de carro e alimentação de linha refere-se estritamente a carateres de escape ANSI.
  • Os nomes de objetos não podem começar por .well-known/acme-challenge/.
  • Os objetos não podem ter o nome . nem ...

Limites de tamanho de objetos específicos do espaço de nomes

O tamanho máximo de um nome de objeto varia consoante o espaço de nomes do contentor:

  • Tamanho do nome do objeto num contentor de espaço de nomes simples: 1 a 1024 bytes quando codificado em UTF-8.

  • Tamanho do nome do objeto em contentores ativados com o espaço de nomes hierárquico: os nomes dos objetos podem ser divididos em duas partes:

    • Nome da pasta: o nome da pasta na qual o objeto reside. O tamanho máximo do nome da pasta é de 512 bytes quando codificado em UTF-8.
    • Nome base: o nome do objeto que reside na pasta. O tamanho máximo do nome base é de 512 bytes quando codificado em UTF-8.

    Por exemplo, o caminho my-folder/my-object.txt representa um objeto com um nome base my-object.txt armazenado numa pasta denominada my-folder/.

Recomendações

Recomendamos vivamente que evite o seguinte nos nomes dos objetos:

  • Carateres de controlo que são ilegais em XML 1.0 (#x7F–#x84 e #x86–#x9F): estes carateres causam problemas de listagem XML quando tenta listar os seus objetos.
  • O caráter #: os comandos da Google Cloud CLI interpretam os nomes de objetos que terminam com #<string numérica> como identificadores de versão. Por isso, a inclusão de # nos nomes de objetos pode dificultar ou impossibilitar a realização de operações nesses objetos com versões através da gcloud CLI.
  • Os carateres [, ], * ou ?: os comandos da CLI do Google Cloud interpretam estes carateres como carateres universais, pelo que a inclusão dos mesmos nos nomes dos objetos pode dificultar ou impossibilitar a realização de operações com carateres universais. Além disso, * e ? não são carateres válidos para nomes de ficheiros no Windows.
  • Os carateres :, ", <, > ou |: estes não são carateres válidos para nomes de ficheiros no Windows. Por isso, as tentativas de transferir um objeto que use esses carateres no respetivo nome para um ficheiro do Windows falham, a menos que o método de transferência inclua a mudança do nome do ficheiro do Windows resultante. O caráter /, embora também não seja um caráter válido para nomes de ficheiros no Windows, é normalmente aceitável para utilização em nomes de objetos para imitar uma estrutura de diretórios. As ferramentas, como a CLI Google Cloud, convertem automaticamente o caráter em \ quando fazem a transferência para um ambiente Windows.
  • Informações confidenciais ou de identificação pessoal (IIP): os nomes dos objetos são mais visíveis do que os dados dos objetos. Por exemplo, os nomes dos objetos aparecem nos URLs do objeto e quando lista objetos num contentor.

Não é possível mudar diretamente o nome dos objetos existentes, mas pode mudar indiretamente o nome de um objeto copiando e eliminando o objeto original.

Espaço de nomes do objeto

Pode armazenar objetos nos seguintes espaços de nomes:

Espaço de nomes simples

Os contentores configurados para armazenar objetos num espaço de nomes simples criam sempre objetos diretamente no contentor. Em contentores de espaço de nomes simples, não existe hierarquia no contentor, nem existem diretórios ou pastas nos quais os objetos existam.

Para sua conveniência, existem várias formas de tratar os objetos em contentores de espaço de nomes simples como se estivessem armazenados numa hierarquia de pastas:

  • As pastas geridas são um recurso do Cloud Storage que oferece acesso expandido a grupos de objetos com um prefixo de nome partilhado.

  • Ferramentas como o Google Cloud console e a CLI do Google Cloud interpretam o caráter de barra (/) no nome de um objeto como um delimitador, de modo a simular pastas em contentores que usam um espaço de nomes simples para objetos.

Por exemplo, se criar um objeto com o nome folder1/file.txt no contentor your-bucket, o caminho para o objeto é your-bucket/folder1/file.txt e o Cloud Storage não tem nenhuma pasta com o nome folder1 armazenada no mesmo. Do ponto de vista do Cloud Storage, a string folder1/ faz parte do nome do objeto.

No entanto, como o objeto tem um / no nome, algumas ferramentas implementam a apresentação de pastas. Por exemplo, quando usa a Google Cloud consola, navega para o objeto folder1/file1.txt como se fosse um objeto com o nome file1.txt numa pasta com o nome folder1. Da mesma forma, pode criar uma pasta gerida denominada folder1 e, em seguida, file1.txt ficaria sujeita à política de acesso definida por esta pasta gerida.

Tenha em atenção que, uma vez que os objetos residem num espaço de nomes simples, as estruturas profundamente aninhadas semelhantes a diretórios não têm o desempenho que um sistema de ficheiros nativo tem quando lista subdiretórios profundamente aninhados.

Consulte as práticas recomendadas da taxa de pedidos para ver recomendações sobre como otimizar o desempenho evitando nomes sequenciais durante carregamentos em grande escala. É provável que os objetos carregados com nomes sequenciais alcancem o mesmo servidor de back-end e restrinjam o desempenho.

Pastas simuladas

Para ajudar a organizar objetos nos seus contentores do Cloud Storage, algumas ferramentas simulam pastas, e as APIs JSON e XML têm capacidades que lhe permitem criar o seu próprio esquema de nomenclatura para simular pastas. Clique nos seguintes separadores para ver como diferentes ferramentas processam pastas simuladas.

Consola

A Google Cloud consola cria uma representação visual de pastas que se assemelha a um explorador de ficheiros local.

Na Google Cloud consola, pode criar uma pasta vazia num contentor ou carregar uma pasta existente.

Quando carrega uma pasta existente, o nome da pasta passa a fazer parte do caminho de todos os objetos contidos na pasta. Todas as subpastas e os objetos que contêm também são incluídos no carregamento.

Para criar uma pasta:

  1. Na Google Cloud consola, aceda à página Recipientes do Cloud Storage.

    Aceda a Recipientes

  2. Navegue para o contentor.

  3. Clique em Criar pasta para criar uma nova pasta vazia ou em Carregar pasta para carregar uma pasta existente.

Linha de comandos

As CLIs do Cloud Storage simulam a experiência típica de diretório de linha de comandos através de várias regras.

Para conseguir a ilusão de uma árvore de ficheiros hierárquica, a CLI gcloud aplica as seguintes regras para determinar se o URL de destino num comando deve ser tratado como um nome de objeto ou uma pasta:

  1. Se o URL de destino terminar com um caráter /, os comandos da CLI gcloud tratam o URL de destino como uma pasta. Por exemplo, considere o seguinte comando, em que your-file é o nome de um ficheiro:

    gcloud storage cp your-file gs://your-bucket/abc/

    Como resultado deste comando, o Cloud Storage cria um objeto com o nome abc/your-file no contentor your-bucket.

  2. Se copiar vários ficheiros de origem para um URL de destino, quer através da flag --recursive, quer de um caractere universal, como **, a CLI gcloud trata o URL de destino como uma pasta. Por exemplo, considere o seguinte comando em que top-dir é uma pasta que contém ficheiros como file1 e file2:

    gcloud storage cp top-dir gs://your-bucket/abc --recursive

    Como resultado deste comando, o Cloud Storage cria os objetos abc/top-dir/file1 e abc/top-dir/file2 no contentor your-bucket.

  3. Se nenhuma destas regras se aplicar, a CLI gcloud verifica os objetos no contentor para determinar se o URL de destino é um nome de objeto ou uma pasta. Por exemplo, considere o seguinte comando em que your-file é o nome de um ficheiro:

    gcloud storage cp your-file gs://your-bucket/abc

    A CLI gcloud faz um pedido de listagem de objetos para your-bucket, usando o delimitador / e o prefix=abc, para determinar se existem objetos em your-bucket cujo caminho começa com abc/. Se for esse o caso, a CLI gcloud trata abc/ como um nome de pasta e o comando cria o objeto abc/your-file no contentor your-bucket. Caso contrário, a CLI gcloud cria o objeto abc em your-bucket.

Esta abordagem baseada em regras difere da forma como muitas ferramentas funcionam, que criam objetos de 0 bytes para marcar a existência de pastas. A CLI gcloud compreende várias convenções usadas por essas ferramentas, como a convenção de adicionar _$folder$ ao final do nome do objeto de 0 bytes, mas não requer esses objetos marcadores para implementar um comportamento de nomenclatura consistente com os comandos UNIX.

Além destas regras, a forma como a CLI gcloud trata os ficheiros de origem depende de usar ou não a flag --recursive. Se usar a flag, a CLI gcloud cria nomes de objetos para espelhar a estrutura do diretório de origem, começando no ponto de processamento recursivo. Por exemplo, considere o seguinte comando em que home/top-dir é uma pasta que contém ficheiros como file1 e sub-dir/file2:

gcloud storage cp home/top-dir gs://your-bucket --recursive

Como resultado deste comando, o Cloud Storage cria os objetos top-dir/file1 e top-dir/sub-dir/file2 no contentor your-bucket.

Por outro lado, a cópia sem a flag --recursive, mesmo que sejam copiados vários ficheiros devido à presença de um caráter universal, como **, resulta em objetos com o nome do componente do caminho final dos ficheiros de origem. Por exemplo, se home/top-dir for uma pasta que contém ficheiros como file1 e sub-dir/file2, o comando:

gcloud storage cp home/top-dir/** gs://your-bucket

cria um objeto denominado file1 e um objeto denominado file2 no contentor your-bucket.

Voltas a tentar e atribuição de nomes

Quando a CLI gcloud volta a tentar um pedido interrompido, pode encontrar um problema em que a primeira tentativa copia um subconjunto de ficheiros e as tentativas subsequentes encontram uma pasta de destino já existente, o que faz com que os seus objetos sejam denominados incorretamente.

Por exemplo, considere o seguinte comando, em que existem subpastas em your-dir/, como dir1 e dir2, e ambas as subpastas contêm o ficheiro abc:

gcloud storage cp ./your-dir gs://your-bucket/new --recursive

Se o caminho gs://your-bucket/new ainda não existir, a CLI gcloud cria os seguintes objetos na primeira tentativa bem-sucedida:

new/dir1/abc
new/dir2/abc

No entanto, na próxima tentativa bem-sucedida do mesmo comando, a CLI gcloud cria os seguintes objetos:

new/your-dir/dir1/abc
new/your-dir/dir2/abc

Para que a CLI gcloud funcione de forma consistente em todas as tentativas, experimente o seguinte:

  1. Adicione uma barra ao final do URL de destino para que a CLI gcloud o trate sempre como uma pasta.

  2. Use gcloud storage rsync. Uma vez que o rsync não usa as regras de nomenclatura de pastas definidas pelo cp do Unix, funciona de forma consistente, quer a subpasta de destino exista ou não.

Notas adicionais

  • Não pode criar um objeto de zero bytes para imitar uma pasta vazia através da CLI gcloud.

  • Quando transfere para um sistema de ficheiros local, a CLI gcloud ignora os objetos cujo nome termina com um caráter /, porque não é permitido criar um ficheiro que termine com um / no Linux e macOS.

  • Se usar scripts para criar caminhos de ficheiros combinando subcaminhos, tenha em atenção que, uma vez que / é apenas um caráter que se encontra no nome do objeto, as CLIs interpretam gs://your-bucket/folder/ como um objeto diferente de gs://your-bucket/folder.

APIs REST

API JSON

As pastas não existem na API JSON. Pode restringir os objetos que lista e simular pastas através dos parâmetros de consulta prefix e delimiter.

Por exemplo, para listar todos os objetos no contentor my-bucket com o prefixo folder/subfolder/, faça um pedido de listagem de objetos através do seguinte URL:

"https://storage.googleapis.com/storage/v1/b/my-bucket/o?prefix=folder/subfolder/"

API XML

As pastas não existem na API XML. Pode restringir os objetos que lista e simular pastas usando os parâmetros de consulta prefix e delimiter.

Por exemplo, para listar todos os objetos no contentor my-bucket com o prefixo folder/subfolder/, faça um pedido de listagem de objetos através do seguinte URL:

"https://storage.googleapis.com/my-bucket?prefix=folder/subfolder/"

Remover pastas simuladas

Uma vez que as pastas simuladas não existem realmente, normalmente, pode remover pastas simuladas ao mudar o nome dos objetos para que a pasta simulada deixe de fazer parte do nome do objeto. Por exemplo, se tiver um objeto com o nome folder1/file, pode remover a pasta simulada folder1/ mudando o nome do objeto para apenas file.

No entanto, se tiver usado uma ferramenta que cria objetos de zero bytes como marcadores de posição de pastas, como a consola, tem de eliminar o objeto de zero bytes para remover a pasta. Google Cloud

Espaço de nomes hierárquico

O espaço de nomes hierárquico permite-lhe organizar objetos num contentor do Cloud Storage numa hierarquia de pastas semelhante a um sistema de ficheiros. O espaço de nomes hierárquico melhora o desempenho e ajuda a gerir os seus dados de forma eficiente. Para saber mais sobre o espaço de nomes hierárquico e quando o usar, consulte Espaço de nomes hierárquico.

Imutabilidade de objetos

Os objetos são imutáveis, o que significa que um objeto carregado não pode ser alterado durante o respetivo tempo de vida de armazenamento. A duração do armazenamento de um objeto é o tempo entre a criação bem-sucedida do objeto, como o carregamento, e a eliminação bem-sucedida do objeto. Na prática, isto significa que não pode fazer alterações incrementais a objetos, como operações de anexação ou operações de truncagem. No entanto, é possível substituir objetos armazenados no Cloud Storage, e esta ação é atómica: até que o novo carregamento seja concluído, a versão antiga do objeto é publicada para os leitores e, após a conclusão do carregamento, a nova versão do objeto é publicada para os leitores. Uma única operação de substituição marca o fim da duração total de um objeto imutável e o início da duração total de um novo objeto imutável.

O número de geração de um objeto muda sempre que substitui os dados do objeto. Assim, o número de geração identifica exclusivamente um objeto imutável.

Tenha em atenção que existe um limite de uma vez por segundo para substituir rapidamente o mesmo objeto. A substituição do mesmo objeto com maior frequência pode resultar em erros 429 Too Many Requests. Deve conceber a sua aplicação para carregar dados de um objeto específico não mais do que uma vez por segundo e processar erros 429 Too Many Requests ocasionais através de uma estratégia de repetição de retirada exponencial.

O que se segue?