Sobre os objetos do Cloud Storage

Nesta página, descrevemos objetos, um recurso do Cloud Storage. Para uma visão geral do funcionamento do Cloud Storage, consulte a visão geral do produto do Cloud Storage.

Objetos

Objetos são os dados individuais que você armazena no Cloud Storage. Não há limite no número de objetos que você crie em um bucket.

Os objetos têm dois componentes: dados e metadados. Os dados de objeto geralmente são um arquivo que você quer armazenar no Cloud Storage e é completamente opaco no Cloud Storage. Metadados de objeto são uma coleção de pares de nome-valor que descrevem várias qualidades de objeto.

Duas partes importantes de metadados de objetos comuns a todos os objetos são o nome e o número de geração do objeto. Ao adicionar um objeto a um bucket do Cloud Storage, você especifica o nome do objeto, e o Cloud Storage atribui o número de geração. Juntos, o nome e a geração identificam exclusivamente o objeto nesse bucket.

Use listas de controle de acesso (ACLs) para controlar o acesso a objetos individuais. Também é possível usar o Identity and Access Management (IAM) para controlar o acesso a todos os objetos em um bucket ou em uma pasta gerenciada.

Considerações de nomenclatura

Ao nomear objetos no Cloud Storage, é essencial seguir requisitos específicos para garantir a compatibilidade e evitar erros. Esses requisitos se aplicam a buckets de namespace plano e buckets com namespace hierárquico ativado.

Requisitos gerais

  • Os nomes de objetos podem conter qualquer sequência de caracteres Unicode válidos.
  • Os nomes de objeto não podem conter caracteres retorno de carro ou nova linha.
  • Os nomes de objeto não podem começar com .well-known/acme-challenge/.
  • Objetos não podem ser nomeados como . ou ...

Limites de tamanho de objeto específicos do namespace

O tamanho máximo de um nome de objeto varia de acordo com o namespace do bucket:

  • Tamanho do nome do objeto em um bucket de namespace simples: de 1 a 1.024 bytes quando codificado em UTF-8.

  • Tamanho do nome do objeto em buckets ativados com o namespace hierárquico: os nomes de objetos podem ser divididos em duas partes:

    • Nome da pasta: o nome da pasta em que o objeto está. O tamanho máximo do nome da pasta é de 512 bytes quando codificado em UTF-8.
    • Nome da base: o nome do objeto que está 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 de base como my-object.txt armazenado em uma pasta chamada my-folder/.

Recomendações

É altamente recomendável que você evite isto nos seus nomes de objeto:

  • Caracteres de controle inválidos em XML 1.0 (#x7F–#x84 e #x86–#x9F): esses caracteres causam problemas ao tentar listar objetos em XML.
  • O caractere #: os comandos da CLI do Google Cloud interpretam nomes de objetos que terminam com #<string numérica> como identificadores de versão, então, incluir # em nomes de objetos pode tornar difícil ou impossível realizar operações nesses objetos com controle de versão usando a CLI gcloud.
  • Os caracteres [, ], * ou ?: os comandos da CLI do Google Cloud interpretam esses caracteres como curingas, portanto, incluí-los em nomes de objetos pode tornar difícil ou impossível realizar operações com caractere curinga. Além disso, * e ? não são caracteres válidos para nomes de arquivo no Windows.
  • Os caracteres :, ", <, > ou |: não são caracteres válidos para nomes de arquivos no Windows. Portanto, tentativas de fazer o download de um objeto que usa esses caracteres no nome falharão em um arquivo do Windows, a menos que o método de download inclua a renomeação do arquivo do Windows resultante. O caractere /, embora não seja um caractere válido para nomes de arquivo no Windows, normalmente pode ser usado em nomes de objeto para imitar uma estrutura de diretório. Ferramentas como a CLI do Google Cloud, que convertem automaticamente o caractere em \ ao fazer o download para um ambiente do Windows.
  • Informações confidenciais ou de identificação pessoal (PII, na sigla em inglês): os nomes de objetos são mais visíveis do que os dados de objetos. Por exemplo, nomes de objetos aparecem em URLs para o objeto e ao listar objetos em um bucket.

Os objetos existentes não podem ser renomeados diretamente, mas é possível renomear indiretamente um objeto copiando e excluindo o objeto original.

Namespace do objeto

É possível armazenar objetos nos seguintes namespaces:

Namespace plano

Os buckets com um namespace simples armazenam objetos em uma estrutura simples sem hierarquia, ou seja, sem diretórios ou pastas.

Por conveniência, há várias maneiras de os objetos serem tratados como se estivessem armazenados em uma hierarquia de pastas:

Por exemplo, se você criar um objeto chamado folder1/file.txt no bucket your-bucket, o caminho para o objeto será your-bucket/folder1/file.txt, e o Cloud Storage não terá uma pasta chamada folder1 armazenada nele. Pela perspectiva 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 aparência de pastas. Por exemplo, ao usar o console do Google Cloud, você navegaria até o objeto folder1/file1.txt como se fosse um objeto chamado file1.txt em uma pasta chamada folder1. Da mesma forma, você criaria uma pasta gerenciada chamada folder1. Assim, file1.txt estaria sujeito à política de acesso definida pela pasta gerenciada.

Observe que como os objetos residem em um namespace simples, as estruturas semelhantes a diretórios aninhados não têm o desempenho que um sistema de arquivos nativo tem ao listar subdiretórios aninhados em muitos níveis.

Consulte as práticas recomendadas de taxa de solicitação para ver recomendações sobre como otimizar o desempenho evitando nomes sequenciais durante uploads em grande escala. Objetos enviados com nomes sequenciais têm mais chances de atingir o mesmo servidor de back-end e restringir o desempenho.

Pastas simuladas

Para ajudar a organizar objetos nos buckets do Cloud Storage, algumas ferramentas simulam pastas. As APIs JSON e XML têm recursos que permitem projetar seu próprio esquema de nomenclatura para simular pastas. Clique nas guias a seguir para ver como diferentes ferramentas manipulam pastas simuladas.

Console

O console do Google Cloud cria uma representação visual de pastas semelhantes a um navegador de arquivos local.

No console do Google Cloud, é possível criar uma pasta vazia em um bucket ou fazer upload de uma pasta existente.

Quando você faz upload de uma pasta existente, o nome dela se torna parte do caminho de todos os objetos contidos nela. Todas as subpastas e os objetos que elas contêm também são incluídos no upload.

Para criar uma pasta:

  1. No Console do Cloud, acesse a página Buckets do Cloud Storage.

    Acessar buckets

  2. Navegue até o bucket.

  3. Clique em Criar pasta para criar uma nova pasta vazia ou em Fazer upload de pasta para fazer upload de uma pasta que já existe.

Linha de comando

As CLIs do Cloud Storage simulam a experiência típica do diretório de linha de comando usando várias regras.

Para alcançar a ilusão de uma árvore de arquivos hierárquica, a gcloud CLI aplicará as seguintes regras para determinar se o URL de destino em um comando será tratado como um nome de objeto ou uma pasta:

  1. Se o URL de destino terminar com um caractere /, os comandos da gcloud CLI tratarão o URL de destino como uma pasta. Por exemplo, considere o comando a seguir, em que your-file é o nome de um arquivo:

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

    Como resultado desse comando, o Cloud Storage cria um objeto chamado abc/your-file no bucket your-bucket.

  2. Se você copiar vários arquivos de origem para um URL de destino usando a flag --recursive ou um caractere curinga, como **, a gcloud CLI vai tratar o URL de destino como uma pasta. Por exemplo, considere o comando a seguir, em que top-dir é uma pasta que contém arquivos como file1 e file2:

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

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

  3. Se nenhuma dessas regras se aplicar, a gcloud CLI verificará os objetos no bucket 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 arquivo:

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

    A gcloud CLI faz uma solicitação de listagem de objetos para your-bucket, usando o delimitador / e prefixo=abc, para determinar se há objetos em your-bucket com caminhos começando com abc/. Nesse caso, a gcloud CLI trata abc/ como um nome de pasta e o comando cria o objeto abc/your-file no bucket your-bucket. Caso contrário, a gcloud CLI criará o objeto abc em your-bucket.

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

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

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

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

Por outro lado, a cópia sem a flag --recursive, mesmo quando vários arquivos são copiados devido à presença de um caractere curinga, como **, resulta em objetos nomeados pelo componente de caminho final dos arquivos de origem. Por exemplo, considerando que home/top-dir é uma pasta que contém arquivos como file1 e sub-dir/file2, o comando:

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

cria um objeto chamado file1 e outro chamado file2 no bucket your-bucket.

Novas tentativas e nomenclatura

Quando a gcloud CLI repete uma solicitação interrompida, talvez você encontre um problema em que a primeira tentativa copia um subconjunto de arquivos e as tentativas subsequentes encontram uma pasta de destino já existente, o que faz com que os objetos sejam nomeados incorretamente.

Por exemplo, considere o comando a seguir, em que há subpastas em your-dir/, como dir1 e dir2, e as duas subpastas contêm o arquivo abc:

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

Se o caminho gs://your-bucket/new ainda não existir, a gcloud CLI criará 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 gcloud CLI criará os seguintes objetos:

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

Para que a gcloud CLI funcione de maneira consistente em todas as tentativas, tente isto:

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

  2. Use gcloud storage rsync. Como rsync não usa as regras de nomenclatura de pastas definidas pelo cp do Unix, ele funciona de maneira consistente, independentemente de a subpasta de destino existir ou não.

Outras observações

  • Não é possível criar um objeto de zero byte para imitar uma pasta vazia usando a gcloud CLI.

  • Ao fazer o download para um sistema de arquivos local, a gcloud CLI pula objetos com nomes que terminam com um caractere /, porque a criação de um arquivo que termina com / não é permitida no Linux e no macOS.

  • Se você usar scripts para criar caminhos de arquivo combinando subcaminhos, observe que, como / é apenas um caractere que está no nome do objeto, as CLIs interpretarão gs://your-bucket/folder/ para ser um objeto diferente de gs://your-bucket//folder.

APIs REST

API JSON

Não há pastas na API JSON. É possível restringir os objetos listados e simular pastas usando os parâmetros de consulta prefix e delimiter.

Por exemplo, para listar todos os objetos no bucket my-bucket com o prefixo folder/subfolder/, faça uma solicitação de listagem de objetos usando este URL:

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

API XML

As pastas não existem na API XML. É possível restringir os objetos listados e simular pastas usando os parâmetros de consulta prefix e delimiter.

Por exemplo, para listar todos os objetos no bucket my-bucket com o prefixo folder/subfolder/, faça uma solicitação de listagem de objetos usando este URL:

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

Como remover pastas simuladas

Como as pastas simuladas não existem de verdade, normalmente é possível removê-las renomeando objetos para que a pasta simulada não faça mais parte do nome do objeto. Por exemplo, se você tiver um objeto chamado folder1/file, é possível remover a pasta simulada folder1/ renomeando o objeto como apenas file.

No entanto, se você usou uma ferramenta que cria objetos de zero byte como marcadores de pasta, como o console do Google Cloud, é necessário excluir o objeto de byte zero para remover a pasta.

Namespace hierárquico

O namespace hierárquico permite organizar objetos em um bucket do Cloud Storage em um sistema de arquivos, como uma hierarquia de pastas. O namespace hierárquico melhora o desempenho e ajuda a gerenciar seus dados de maneira eficiente. Para saber mais sobre o namespace hierárquico e quando usá-lo, consulte Namespace hierárquico.

Imutabilidade do objeto

Os objetos são imutáveis, o que significa não é possível alterar um objeto enviado durante toda a vida útil de armazenamento dele. A vida útil de armazenamento de um objeto é o tempo entre a criação bem-sucedida do objeto, como upload e exclusão do objeto. Na prática, isso significa que não é possível fazer alterações incrementais aos objetos, como operações de anexo ou de truncagem. No entanto, é possível substituir objetos armazenados no Cloud Storage. Isso acontece atomicamente: até que o novo upload seja concluído, a versão antiga do objeto é exibida aos leitores. Depois da conclusão do upload, a nova versão do objeto é exibida aos leitores. Uma única operação de substituição marca o final do ciclo de vida de um objeto imutável e o início do ciclo de vida de um novo objeto imutável.

O número de geração de um objeto é alterado sempre que você substitui os dados desse objeto. Assim, o número de geração identifica exclusivamente um objeto imutável.

Há um limite de uma vez por segundo para substituir rapidamente o mesmo objeto. A substituição do mesmo objeto com mais frequência pode resultar em erros 429 Too Many Requests. Projete seu aplicativo para fazer upload dos dados de um objeto específico no máximo uma vez por segundo e processar erros 429 Too Many Requests ocasionais usando uma estratégia de repetição de espera exponencial.

A seguir