Filtrar objetos de origem por horário de modificação

É possível filtrar quais objetos serão transferidos com base no horário da última modificação. Isso permite transferir apenas objetos modificados:

  • Antes ou depois de uma data e hora específicas
  • Antes ou depois de um período especificado em relação ao job de transferência

Esse recurso é útil para configurar transferências incrementais ou para pular objetos que estão fora de um período.

A filtragem por horário da última modificação é compatível com transferências de todas as origens, exceto listas de URLs.

Filtros baseados em tempo

A filtragem é definida com os valores last modified since, last modified before, minimum time elapsed since modified e maximum time elapsed since modified. É possível usar os filtros individualmente ou em conjunto para criar uma janela de tempo.

Campo Descrição
Última modificação desde Inclui na transferência objetos que foram modificados pela última vez na data e hora indicadas ou depois.
Última modificação antes de Inclui objetos na transferência que foram modificados pela última vez antes desse carimbo de data/hora.
Tempo mínimo decorrido desde a modificação Inclui objetos na transferência que foram modificados pela última vez há pelo menos esse tempo. Por exemplo, esse filtro pode ser usado para incluir apenas objetos que foram modificados há pelo menos um mês. Os objetos sem um "horário da última modificação" também são transferidos.
Tempo máximo decorrido desde a modificação Inclui objetos na transferência que foram modificados pela última vez há menos tempo do que esse período. Por exemplo, esse filtro pode ser usado para incluir apenas objetos que foram modificados nos últimos sete dias. Os objetos sem um "horário da última modificação" também são transferidos.

Especificar um filtro baseado em tempo

É possível especificar filtros de tempo de modificação ao criar ou atualizar um job de transferência.

Os carimbos de data/hora precisam estar em UTC e formatados como uma string RFC 3339 (por exemplo, 2025-10-31T10:00:00Z). As durações usam o formato de duração absoluta (por exemplo, P1M para 1 mês; 1h30m para 1 hora e 30 minutos).

Console do Google Cloud

Para especificar um filtro de tempo no console do Google Cloud :

  1. Acesse a página Criar job de transferência ou Editar job de transferência.
  2. Na seção Escolher dados para transferir, selecione Datas e horários como o Tipo de filtro.
  3. Insira uma data e hora para o Período absoluto ou uma duração para o Período relativo. Vários filtros podem ser especificados juntos.

CLI da gcloud

Para filtrar por horário de modificação usando a CLI gcloud, transmita as flags de filtro baseadas em tempo para o comando gcloud transfer jobs create ou gcloud transfer jobs update:

gcloud transfer jobs create SOURCE DESTINATION \
  --include-modified-before-absolute="DATETIME" \
  --include-modified-after-absolute="DATETIME" \
  --include-modified-before-relative="DURATION" \
  --include-modified-after-relative="DURATION"

Em que:

  • --include-modified-before-absolute inclui objetos modificados pela última vez antes de uma data/hora absoluta. Por exemplo, ao especificar 2020-01-01, a transferência inclui objetos modificados pela última vez antes de 1º de janeiro de 2020. Use o formato de data e hora %Y-%m-%dT%H:%M:%S%z.
  • --include-modified-after-absolute inclui objetos modificados pela última vez após uma data/hora absoluta. Por exemplo, ao especificar "2020-01-01", a transferência inclui objetos modificados pela última vez após 1º de janeiro de 2020. Use o formato de data e hora %Y-%m-%dT%H:%M:%S%z.
  • --include-modified-before-relative inclui objetos que foram modificados fora de um período especificado. Por exemplo, especificar uma duração de 10d transfere objetos modificados pela última vez mais de 10 dias antes do horário de início da transferência. Use o formato de duração absoluta (por exemplo, P1M para 1 mês ou 1h30m para 1 hora e 30 minutos).
  • --include-modified-after-relative inclui objetos modificados em um período especificado. Por exemplo, especificar uma duração de 10d transfere objetos modificados pela última vez menos de 10 dias antes do horário de início da transferência. Use o formato de duração absoluta (por exemplo, P1M para 1 mês ou 1h30m para 1 hora e 30 minutos).

Exemplo (modificado depois):

O comando a seguir transfere apenas objetos modificados a partir de 1º de outubro de 2025.

gcloud transfer jobs create gs://my-source-bucket gs://my-sink-bucket \
  --include-modified-after-absolute="2025-10-01T00:00:00Z"

Exemplo (janela de tempo):

O comando a seguir transfere apenas objetos modificados durante o mês de outubro de 2025.

gcloud transfer jobs create gs://my-source-bucket gs://my-sink-bucket \
  --include-modified-after-absolute="2025-10-01T00:00:00Z" \
  --include-modified-before-absolute="2025-11-01T00:00:00Z"

Exemplo (tempo decorrido):

O comando a seguir transfere apenas objetos modificados nos últimos sete dias.

gcloud transfer jobs create gs://my-source-bucket gs://my-sink-bucket \
  --include-modified-after-relative="7d"

REST

Para filtrar por horário de modificação usando a API REST, especifique os campos de filtro baseados em tempo no objectConditions do seu transferSpec.

{
  "description": "DESCRIPTION",
  "status": "ENABLED",
  "projectId": "PROJECT_ID",
  "transferSpec": {
    "gcsDataSource": {
      "bucketName": "SOURCE_BUCKET"
    },
    "gcsDataSink": {
      "bucketName": "DESTINATION_BUCKET"
    },
    "objectConditions": {
      "lastModifiedBefore": "DATETIME",
      "lastModifiedSince": "DATETIME",
      "minTimeElapsedSinceLastModification": "DURATION",
      "maxTimeElapsedSinceLastModification": "DURATION"
    }
  }
}

Em que:

  • lastModifiedBefore inclui objetos modificados pela última vez antes do horário especificado. Use um carimbo de data/hora RFC 3339, por exemplo, 2020-01-01T00:00:00Z.
  • lastModifiedSince inclui objetos modificados pela última vez no horário especificado ou depois dele. Use um carimbo de data/hora RFC 3339, por exemplo, 2020-01-01T00:00:00Z.
  • minTimeElapsedSinceLastModification inclui objetos modificados pela última vez pelo menos esse tempo antes do horário de início da transferência. Especifique a duração em segundos seguida por s. Por exemplo, 864000s (10 dias) transfere objetos modificados pela última vez 10 ou mais dias antes do horário de início da transferência.
  • maxTimeElapsedSinceLastModification inclui objetos modificados pela última vez menos do que esse tempo antes do horário de início da transferência. Especifique a duração em segundos seguida por s. Por exemplo, 864000s (10 dias) transfere objetos modificados pela última vez menos de 10 dias antes do horário de início da transferência.

Exemplo (janela de tempo):

O corpo JSON a seguir configura um job para transferir apenas objetos modificados durante outubro de 2025.

{
  "description": "Transfer October 2025 data",
  "status": "ENABLED",
  "projectId": "PROJECT_ID",
  "transferSpec": {
    "gcsDataSource": {
      "bucketName": "SOURCE_BUCKET"
    },
    "gcsDataSink": {
      "bucketName": "DESTINATION_BUCKET"
    },
    "objectConditions": {
      "lastModifiedSince": "2025-10-01T00:00:00Z",
      "lastModifiedBefore": "2025-11-01T00:00:00Z"
    }
  }
}

Para mais informações, consulte a referência de ObjectConditions.

Interação com outros filtros

Quando você usa vários filtros, o Serviço de transferência do Cloud Storage os aplica na seguinte ordem:

  1. Incluir prefixos: restringe os objetos a serem considerados.

  2. Condições do objeto (padrão glob e horário da última modificação): filtra os objetos que correspondem ao prefixo de inclusão. Um objeto precisa corresponder ao filtro glob e ao filtro de última modificação para ser incluído no resultado.

  3. Excluir prefixos: remove objetos do resultado.

Saiba mais sobre filtragem por prefixo e filtragem com padrões glob.

Exemplo: combinação de todos os filtros

Imagine que você tenha a seguinte configuração de filtro para uma transferência do AWS S3 ou do Azure:

  • include_prefix: "logs/"
  • match_glob: "**/*.log"
  • lastModifiedSince: "2025-10-31T00:00:00Z"
  • exclude_prefix: "logs/temp/"

Resultado: o serviço vai executar a transferência da seguinte maneira:

  1. Primeiro, ele considera apenas objetos no diretório logs/.
  2. Em seguida, ele procura objetos que terminam em .log E foram modificados em ou após 31 de outubro de 2025.
  3. Por fim, ele remove da lista todos os objetos que estão no diretório logs/temp/.