Preservação de metadados

Neste documento, descrevemos os metadados preservados quando você usa o Serviço de transferência do Cloud Storage para transferir dados entre várias origens e destinos.

Informações gerais

O Serviço de transferência do Cloud Storage preserva os seguintes metadados:

Os metadados personalizados criados pelo usuário para transferências originadas do Cloud Storage, do Amazon S3 ou do Microsoft Azure Blob Storage são preservados.
As transferências entre buckets do Cloud Storage têm a opção de preservar ACLs de objetos, chaves de criptografia gerenciadas pelo cliente, classe de armazenamento, horário de criação do objeto (como o valor de um campo customTime) e retenções temporárias.
Para transferências de qualquer origem para um bucket do Cloud Storage, a classe de armazenamento do objeto no bucket de destino pode ser definida como qualquer classe compatível como parte da transferência.
O tamanho do arquivo e o horário da última modificação (mtime) são preservados para transferências originadas de sistemas de arquivos POSIX. mtime não é preservado para pastas.
Opcionalmente, links simbólicos, UID numérico, GID numérico e MODE numérico podem ser preservados para transferências de e para sistemas de arquivos POSIX.
Para transferências somente entre sistemas de arquivos, se o UID, o GID ou o MODE forem preservados, esses metadados também serão preservados para as pastas. O Cloud Storage recria pastas no sistema de arquivos de destino e restaura UID, GID e/ou MODE. Isso inclui pastas vazias. mtime não é preservado.

Os metadados no nível da pasta não serão preservados se a transferência for por manifesto.

Os campos de metadados que não são explicitamente mencionados neste documento não são preservados.

Comportamento de preservação de metadados

As seções a seguir listam exemplos de metadados de diferentes sistemas de armazenamento de origem e como o Serviço de transferência do Cloud Storage preserva os metadados de cada um. Para ver uma lista completa de metadados, consulte a documentação do sistema de armazenamento de origem.

Amazon S3 para Cloud Storage

Exemplo de metadados	Comportamento de preservação
Campos de metadados de chave fixa do Amazon S3, como: `Cache-Control`, `Content-Disposition` e `Content-Type`.	Preservado como metadados de chave fixa.
Metadados definidos pelo usuário do Amazon S3, formatados como pares de chave-valor. Para mais informações, consulte a seção Metadados de objetos definidos pelo usuário de Metadados e chave de objetos.	Preservado como um campo de metadados personalizado em objetos de destino do Cloud Storage, que você pode editar ou remover posteriormente.
`ETag`	Preservado como um campo de metadados personalizado com a chave `x-goog-source-etag`, que você pode editar posteriormente ou remover.
Tamanho do objeto.	Preservado como `size`.
Listas de controle de acesso (ACLs, na sigla em inglês) do Amazon S3. Para uma lista completa, consulte a seção Chaves de condição da Visão geral da lista de controle de acesso (ACL, na sigla em inglês).	Não preservado.
Tags de objeto do Amazon S3, definidas por você como pares de chave-valor. Para mais informações, consulte Tags de objetos.	Não preservado.
Metadados definidos pelo sistema do Amazon S3, exceto para `ETag` e o tamanho do objeto. Para uma lista completa, consulte a seção Metadados de objeto definidos pelo sistema de Metadados e chave do objeto.	Não preservado. Os metadados de carimbo de data/hora da origem não são preservados. A hora da criação, `timeCreated`, reflete a hora em que um objeto é criado no Cloud Storage. Da mesma forma, `updated` reflete a hora em que os metadados de um objeto são modificados no Cloud Storage.
Classe de armazenamento	Existem várias opções para configurar a classe de armazenamento durante uma transferência. Defina a classe de armazenamento de cada objeto como a do bucket de destino. Esse é o comportamento padrão. Defina uma classe de armazenamento específica em todos os objetos que estão sendo transferidos. Consulte a documentação de referência metadataOptions para mais detalhes.

Armazenamento do Microsoft Azure para o Cloud Storage

Exemplo de metadados	Comportamento de preservação
Campos de metadados de chave fixa do Microsoft Azure Storage, como: `Cache-Control`, `Content-Disposition` e `Content-Type`.	Preservado como metadados de chave fixa.
Metadados definidos pelo usuário do Microsoft Azure Storage, formatados como pares de chave-valor. Para mais informações, consulte Como configurar e recuperar propriedades e metadados para recursos de serviços do Blob .	Preservado como um campo de metadados personalizado em objetos de destino do Cloud Storage, que você pode editar ou remover posteriormente.
`ETag`	Preservado como um campo de metadados personalizado com a chave `x-goog-source-etag`, que você pode editar posteriormente ou remover.
Tamanho do objeto.	Preservado como `size`.
Permissões do sistema de arquivos POSIX compatível com o Azure Data Lake Storage (ADLS) de 2a geração.	Não preservado.
Controle de acesso do Microsoft Azure Storage, especificamente `x-ms-blob-public-access`. Para mais informações consulte a seção Cabeçalhos de respostas de Receber ACL do contêiner .	Não preservado.
Tags de índice do Microsoft Azure Storage. Para mais informações, consulte Gerenciar e encontrar dados do Azure Blob com tags de índice do blob .	Não preservado.
Metadados de carimbo de data/hora do Microsoft Azure Storage, como: `Last-Modified`, `x-ms-creation-time`, `x-ms-version`, `x-ms-request-server-encrypted` e `x-ms-encryption-scope`. Para mais informações, consulte Definir metadados do Blob .	Não preservado. Os metadados de carimbo de data/hora da origem não são preservados. A hora da criação, `timeCreated`, reflete a hora em que um objeto é criado no Cloud Storage. Da mesma forma, `updated` reflete a hora em que os metadados de um objeto são modificados no Cloud Storage.
Classe de armazenamento	Existem várias opções para configurar a classe de armazenamento durante uma transferência. Defina a classe de armazenamento de cada objeto como a do bucket de destino. Esse é o comportamento padrão. Defina uma classe de armazenamento específica em todos os objetos que estão sendo transferidos. Consulte a documentação de referência metadataOptions para mais detalhes.

Transferências entre buckets do Cloud Storage

Exemplo de metadados	Comportamento de preservação
Campos de metadados de chave fixa do Cloud Storage, como: `Cache-Control`, `Content-Disposition` e `Content-Type`. Para mais informações, consulte Metadados de objetos	Preservado como metadados de chave fixa.
Metadados definidos pelo usuário do Cloud Storage, formatados como pares de chave-valor. Para mais informações, consulte Metadados personalizados.	Preservado como um campo de metadados personalizado em objetos de destino do Cloud Storage, que você pode editar ou remover posteriormente.
Tamanho do objeto	Preservado como `size`.
Geração de objetos	Preservado como um campo de metadados personalizado com a chave `x-goog-reserved-source-generation`, que você pode editar posteriormente ou remover.
Retenções de objetos	As retenções de documentos baseadas em eventos não são preservadas. Se o bucket de destino tiver a propriedade de retenção baseada em eventos padrão ativada, uma retenção baseada em eventos será aplicada aos objetos transferidos. As retenções temporárias são preservadas por padrão. Para descartar retenções temporárias durante a transferência, defina o campo `temporaryHold` do objeto metadataOptions como `TEMPORARY_HOLD_SKIP`.
Access Control Lists (ACLs)	Como opção, é possível preservar as ACLs. Consulte a documentação de referência metadataOptions para mais detalhes. Ao preservar as ACLs, tenha cuidado para evitar a criação de objetos inacessíveis. Para mais informações, consulte a documentação Listas de controle de acesso do Cloud Storage.
Classe de armazenamento	Existem várias opções para configurar a classe de armazenamento durante uma transferência. Defina a classe de armazenamento de cada objeto como a do bucket de destino. Esse é o comportamento padrão. Preservar a classe de armazenamento do objeto de origem. Defina uma classe de armazenamento específica em todos os objetos que estão sendo transferidos. Consulte a documentação de referência metadataOptions para mais detalhes.
Chave de criptografia gerenciada pelo cliente	Se uma chave de criptografia gerenciada pelo cliente (CMEK) estiver sendo usada em um objeto, o objeto poderá usar a mesma chave quando for gravado no bucket de destino. O comportamento padrão é gravar o objeto no bucket de destino usando o método de criptografia do bucket. Ao preservar a CMEK original, esteja ciente destas limitações: O bucket de destino precisa estar no mesmo local que as CMEK. Se o bucket de destino estiver em outro projeto, adicione a conta de serviço do Cloud Storage do projeto de destino à chave. Consulte a documentação de referência metadataOptions para mais detalhes.
Metadados do carimbo de data/hora	Opcionalmente, `timeCreated` pode ser preservado O valor preservado é armazenado no campo `customTime` do objeto transferido no Cloud Storage. Consulte a documentação de referência metadataOptions para mais detalhes. Os metadados `updated` não são preservados.
Outros metadados não editáveis do Cloud Storage, como `etag` e `componentCount`.	Não preservado.

Para ver uma lista de metadados no Cloud Storage, consulte Objetos.

Transferência de lista de URLs para o Cloud Storage

Para mais informações sobre listas de URLs, consulte Como criar uma lista de URLs.

Exemplo de metadados	Comportamento de preservação
Campos de metadados de chave fixa, como: `Cache-Control`, `Content-Disposition` e `Content-Type`.	Preservado como metadados editáveis.
`Content-Length` e `MD5`	Preservados como metadados não editáveis. Se a origem não fornecer um valor de hash `MD5`, o valor não será preservado. Esse comportamento de preservação é específico de `Content-Length` e `MD5`. Todos os outros metadados não editáveis não listados não serão preservados.
Metadados de carimbo de data/hora, como: hora da criação, hora da modificação e outros metadados específicos da origem.	Não preservado. Os metadados de carimbo de data/hora da origem não são preservados. A hora da criação, `timeCreated`, reflete a hora em que um objeto é criado no Cloud Storage. Da mesma forma, `updated` reflete a hora em que os metadados de um objeto são modificados no Cloud Storage.
Classe de armazenamento	Existem várias opções para configurar a classe de armazenamento durante uma transferência. Defina a classe de armazenamento de cada objeto como a do bucket de destino. Esse é o comportamento padrão. Defina uma classe de armazenamento específica em todos os objetos que estão sendo transferidos. Consulte a documentação de referência metadataOptions para mais detalhes.

Transferências do sistema de arquivos POSIX

Ao transferir arquivos de sistemas de arquivos POSIX, o Serviço de transferência do Cloud Storage pode preservar determinados atributos como metadados personalizados. Se esses arquivos forem posteriormente gravados em um sistema de arquivos, o Storage Transfer Service poderá converter os metadados preservados de volta em atributos POSIX.

Exemplo de metadados	Comportamento de preservação
Horário modificado (`mtime`)	Preservado. `mtime` é preservado como metadados personalizados com a chave `goog-reserved-file-mtime`.
Tamanho do arquivo	Preservado. O tamanho do arquivo é preservado como `size`.
UID numérico , GID numérico , MODO numérico e links simbólicos	Opcional. O comportamento de preservação é especificado com o objeto `metadataOptions`. Consulte os detalhes em Como preservar metadados POSIX opcionais. O comportamento padrão é não preservar metadados.
Metadados da pasta	Os metadados da pasta são preservados somente para transferências entre sistemas de arquivos. As configurações de preservação de UID, GID e MODE da transferência se aplicam a arquivos e pastas para essas transferências. `mtime` não é preservado para pastas. `mtime` é definido como o horário de criação da pasta no sistema de arquivos de destino. Os metadados da pasta não são preservados para transferências de manifesto.
Classe de armazenamento	Existem várias opções para configurar a classe de armazenamento durante uma transferência. Defina a classe de armazenamento de cada objeto como a do bucket de destino. Esse é o comportamento padrão. Defina uma classe de armazenamento específica em todos os objetos que estão sendo transferidos. Consulte a documentação de referência metadataOptions para mais detalhes.

Como preservar metadados POSIX opcionais

Para preservar um ou mais UIDs numéricos, GIDs numéricos, MODO numérico e links simbólicos, especifique um objeto metadataOptions no corpo do job de transferência.

Essas opções se aplicam às transferências do POSIX para o Cloud Storage e do Cloud Storage para POSIX. No último caso, os metadados precisam ser preservados quando os arquivos foram transferidos inicialmente para o Cloud Storage.

{
  "description": "metadata-example",
  "projectId": "example-project-id"
  "transferSpec": {
    ...
    "transferOptions": {
      "metadataOptions": {
        "gid":     "GID_NUMBER",       # Default is "GID_SKIP"
        "uid":     "UID_NUMBER",       # Default is "UID_SKIP"
        "mode":    "MODE_PRESERVE",    # Default is "MODE_SKIP"
        "symlink": "SYMLINK_PRESERVE"  # Default is "SYMLINK_SKIP"
      }
    }
  }
}

POSIX para o Cloud Storage

Os metadados preservados são armazenados no Cloud Storage como pares de chave-valor de metadados personalizados.

O GID numérico é armazenado como goog-reserved-posix-gid.
O UID numérico é armazenado como goog-reserved-posix-uid.
O MODE numérico é armazenado como goog-reserved-posix-mode.

Para links simbólicos, o Storage Transfer Service preserva o link de destino como um objeto no Cloud Storage com as seguintes qualidades:

A chave do objeto é composta pelo prefixo de destino e pelo caminho do link simbólico, relativo ao root_directory.
Metadados do objeto:
- Todos os metadados de links simbólicos são preservados como metadados do objeto do Cloud Storage.
- Uma entrada de metadados personalizada é feita: goog-reserved-file-is-symlink:true.
O conteúdo do objeto é o destino do link simbólico. Por exemplo, para um link simbólico sym-> dir1/target, o conteúdo do objeto é "dir1/target".

O Serviço de transferência do Cloud Storage não valida o link ou copia o arquivo de destino.

Cloud Storage para POSIX

Se os metadados forem preservados quando os arquivos forem transferidos para o Cloud Storage, eles poderão ser gravados de volta nos arquivos quando forem transferidos de volta para um sistema de arquivos POSIX.

Se uma opção de metadados estiver definida para preservar, o Storage Transfer Service realiza as seguintes ações:

Links simbólicos: o Storage Transfer Service cria um arquivo de link simbólico que aponta para o link de destino. Se o arquivo de destino não existir, o link simbólico será corrompido.
GID, UID e MODE: os valores armazenados nos metadados do Cloud Storage são gravados de volta no arquivo.

POSIX para POSIX

As transferências entre sistemas de arquivos podem, opcionalmente, preservar GID, UID e MODE para arquivos e pastas.

O horário da última modificação é salvo para arquivos, mas não para pastas. mtime é definido como o horário de criação da pasta no sistema de arquivos de destino.

O Serviço de transferência do Cloud Storage salva metadados de pastas criando objetos de pasta de 0 byte no bucket intermediário e copiando esses metadados de volta para a pasta no sistema de arquivos de destino. Por esse motivo, o número de objetos criados no bucket intermediário pode ser maior que o número de arquivos transferidos.