Cloud Logging para operações em lote de armazenamento

Nesta página, descrevemos como configurar e visualizar os registros de operações em lote de armazenamento usando o Cloud Logging. Um job de operações em lote de armazenamento pode ser configurado para gerar entradas de registro do Cloud Logging para cada job de transformação. Cada entrada de registro corresponde à transformação tentada de um objeto.

As operações em lote do Storage oferecem suporte ao registro no Cloud Logging e nos registros de auditoria do Cloud Storage. Embora as duas opções capturem ações de operações em lote de armazenamento, recomendamos usar o Cloud Logging. O Cloud Logging oferece uma plataforma centralizada para análise de registros, monitoramento em tempo real e filtragem avançada, oferecendo uma solução robusta para gerenciar e entender sua atividade de operação em lote.

Antes de começar

Verifique se você tem acesso ao Cloud Logging. Para usar o Cloud Logging, recomendamos conceder o papel Logs Viewer (roles/logging.viewer) do Identity and Access Management. O papel do Identity and Access Management Logs Viewer (roles/logging.viewer) fornece as permissões necessárias para visualizar os dados do Cloud Logging. Para mais informações sobre as permissões de acesso do Logging, consulte Controle de acesso com o IAM.

Para verificar e conceder as permissões do IAM, siga estas etapas:

Entender os detalhes da geração de registros

Quando o registro está ativado, as operações em lote de armazenamento capturam os seguintes detalhes:

  • Ação registrável: o valor da ação registrável é sempre transform.

  • Estados registráveis: para cada ação, é possível escolher registrar um ou ambos os seguintes estados:

    • SUCCEEDED: a ação foi concluída.
    • FAILED: a ação falhou.

Ativar a geração de registros

Para ativar a geração de registros, especifique as ações e os estados a serem registrados.

Linha de comando

Ao criar um job de operações em lote de armazenamento com gcloud storage batch-operations jobs create, use as flags --log-actions e --log-action-states para ativar a geração de registros.

gcloud storage batch-operations jobs create JOB_NAME \
  --manifest-location=MANIFEST_LOCATION \
  --delete-object \
  --log-actions=transform \
  --log-action-states=LOG_ACTION_STATES

Em que:

  • JOB_NAME é o nome que você quer dar ao job. Por exemplo, my-job.
  • MANIFEST_LOCATION é o local do manifesto. Por exemplo, gs://my-bucket/manifest.csv.
  • LOG_ACTION_STATES é uma lista separada por vírgulas de estados a serem registrados. Por exemplo, succeeded,failed.

API REST

Create a storage batch operations job com um LoggingConfig.

{
   "loggingConfig": {
      "logActions": ["TRANSFORM"],
      "logActionStates": ["LOG_ACTION_STATES"],
        }
}

Em que:

LOG_ACTION_STATES é uma lista separada por vírgulas de estados a serem registrados. Por exemplo, "SUCCEEDED","FAILED".

Ver registros

Para ver os registros de operações em lote de armazenamento, faça o seguinte:

Console

  1. Acesse o menu de navegação Google Cloud e selecione Logging > Análise de registros :<br\></br\>

    Acesse o Explorador de registros

  2. Selecionar um projeto do Google Cloud

  3. No menu Upgrade, alterne de Leitor de registros legados para Explorador de registros.

  4. Para filtrar seus registros e mostrar apenas entradas de operações em lote do Cloud Storage, digite storage_batch_operations_job no campo de consulta e clique em Executar consulta.

  5. No painel Resultados da consulta, clique em Editar hora para alterar o período de retorno dos resultados.

Veja mais informações em Como usar o Explorador de registros.

Linha de comando

Para usar a CLI gcloud para pesquisar registros de operações em lote de armazenamento, use o comando gcloud logging read.

Especifique um filtro para limitar os resultados aos registros de operações em lote de armazenamento.

gcloud logging read "resource.type=storage_batch_operations_job"

API REST

Use o método entries.list da API Cloud Logging.

Para filtrar os resultados e incluir apenas entradas relacionadas a operações em lote de armazenamento, use o campo filter. Confira abaixo um exemplo de objeto de solicitação JSON:

{
"resourceNames":
  [
    "projects/my-project-name"
  ],
  "orderBy": "timestamp desc",
  "filter": "resource.type=\"storage_batch_operations_job\""
}

Em que:

my-project-name é o nome do projeto;

Formato do registro de operações em lote do Storage

Todos os campos específicos das operações em lote de armazenamento estão contidos em um objeto jsonPayload. Embora o conteúdo exato de jsonPayload varie de acordo com o tipo de job, há uma estrutura comum compartilhada em todas as entradas de TransformActivityLog. Esta seção descreve os campos de registro comuns e detalha os campos específicos da operação.

  • Campos de registro comuns

    Os seguintes campos aparecem em todos os registros:

    jsonPayload: {
"@type": "type.googleapis.com/google.cloud.storagebatchoperations.logging.TransformActivityLog",
"completeTime": "YYYY-MM-DDTHH:MM:SS.SSSSSSSSSZ",
"status": {
  "errorMessage": "String indicating error",
  "errorType": "ENUM_VALUE",
  "statusCode": "ENUM_VALUE"
},
"logName": "projects/PROJECT_ID/logs/storagebatchoperations.googleapis.com%2Ftransform_activity",
"receiveTimestamp": "YYYY-MM-DDTHH:MM:SS.SSSSSSSSSZ",
"resource": {
  "labels": {
    "location":"us-central1",
    "job_id": "BATCH_JOB_ID",
    "resource_container": "RESOURCE_CONTAINER",
    // ... other labels
  },
  "type": "storagebatchoperations.googleapis.com/Job"
},
// Operation-specific details will be nested here (for example,
// "DeleteObject", "PutObjectHold", "RewriteObject", "PutMetadata")
// Each operation-specific object will also contain the following
// object: "objectMetadataBefore": {
//   "gcsObject": {
//     "bucket": "BUCKET_NAME",
//     "generation": "GENERATION_NUMBER",
//     "objectKey": "OBJECT_PATH"
//   }
// }
}

    A tabela a seguir descreve cada um dos campos de registro comuns:

    Campos de registro comuns Tipo Descrição
    @type String Especifica o tipo de payload da entrada de registro e indica que o registro representa um TransformActivityLog para operações em lote de armazenamento.
    completeTime Carimbo de data/hora O carimbo de data e hora em conformidade com a ISO 8601 em que a operação foi concluída.
    status Objeto Fornece informações sobre o resultado da atividade de operação em lote.
    status.errorMessage String Uma mensagem de erro se a operação falhar. A mensagem de erro só aparece se o valor de status.statusCode não for OK.
    status.errorType String O tipo de erro. O tipo de erro só aparece se o valor de status.statusCode não for OK.
    status.statusCode String O código de status da operação. A operação será bem-sucedida se o valor for OK. Qualquer outro valor indica falha.
    logName String O nome completo do recurso do registro, indicando o projeto e o fluxo de registros.
    receiveTimestamp Carimbo de data/hora O carimbo de data/hora em que a entrada de registro foi recebida pelo sistema de geração de registros.
    resource Objeto Informações sobre o recurso que gerou a entrada de registro.
    resource.labels Objeto Pares de chave-valor que fornecem mais informações de identificação sobre o recurso.
    resource.type String O tipo de recurso que gerou o registro.
    objectMetadataBefore Objeto Contém metadados do objeto antes da tentativa de operação em lote.
    objectMetadataBefore.gcsObject Objeto Detalhes sobre o objeto.
    objectMetadataBefore.gcsObject.bucket String O nome do bucket onde o objeto reside.
    objectMetadataBefore.gcsObject.generation String O número de geração do objeto antes da operação.
    objectMetadataBefore.gcsObject.objectKey String O caminho completo do objeto no bucket.

  • Conteúdo jsonPayload específico da operação

    A diferença entre entradas de registro para diferentes operações em lote está no objeto de nível superior aninhado no jsonPayload. Apenas um dos seguintes objetos está disponível em uma determinada entrada de registro, correspondendo à operação em lote específica realizada:

    • Excluir objeto (DeleteObject)

      jsonPayload:
{
"DeleteObject": {
  "objectMetadataBefore": {
    "gcsObject": {
      "bucket": "test-bucket",
      "generation": "1678912345678901",
      "objectKey": "test_object.txt"
    }
  }
  }
}

    • Colocar retenção de objeto (PutObjectHold)

      jsonPayload:
{
"PutObjectHold": {
  "objectMetadataBefore": {
    "gcsObject": {
      "bucket": "test-bucket",
      "generation": "1678912345678901",
      "objectKey": "test_object.txt"
    }
  },
  "temporaryHoldAfter": True,
  "eventBasedHoldAfter": True
}
}

    • Objeto de reescrita (RewriteObject)

      jsonPayload:
{
"RewriteObject": {
  "objectMetadataBefore": {
    "gcsObject": {
      "bucket": "test-bucket",
      "generation": "1678912345678901",
      "objectKey": "test_object.txt"
    }
  },
  "kmsKeyVersionAfter": "projects/my-gcp-project/locations/us-central1/keyRings/my-keyring-01/cryptoKeys/my-encryption-key/cryptoKeyVersions/1"
}
}

    • Inserir metadados (PutMetadata)

      jsonPayload:
{
"PutMetadata": {
  "objectMetadataBefore": {
    "gcsObject": {
      "bucket": "test-bucket",
      "generation": "1678912345678901",
      "objectKey": "test_object.txt"
    }
  },
  "content_disposition_after": "attachment; filename=\"report_final.pdf\"",
  "content_encoding_after": "gzip",
  "content_language_after": "en-US",
  "content_type_after": "application/pdf",
  "cache_control_after": "public, max-age=3600",
  "custom_time_after": "2025-06-27T10:00:00Z",
  "custom_metadata_after": {
    "project": "marketing",
    "version": "2.0",
    "approvedBy": "Admin"
  }
}
}

    A tabela a seguir descreve os campos de registro específicos da operação:

    Campos de registro específicos da operação Tipo Descrição
    PutObjectHold Objeto Indica uma operação de retenção em um objeto.
    PutObjectHold.temporaryHoldAfter Booleano Se o valor for True, isso indica que uma retenção temporária foi aplicada ao objeto após a conclusão do job de operações em lote de armazenamento. Os valores válidos são True ou False.
    PutObjectHold.eventBasedHoldAfter Booleano Se o valor for True, isso indica que uma retenção baseada em eventos foi aplicada ao objeto após a conclusão do job de operações em lote de armazenamento. Os valores válidos são True ou False.
    RewriteObject Objeto Indica uma operação de regravação em um objeto.
    RewriteObject.kmsKeyVersionAfter String A versão da chave do Cloud Key Management Service usada após o job de reescrita. O campo kmsKeyVersionAfter será preenchido se a chave de criptografia do objeto mudar como resultado da reescrita. É um campo opcional, o que significa que ele pode não estar presente se a versão da chave do Cloud KMS permanecer inalterada após a reescrita.
    PutMetadata Objeto Indica uma operação de atualização de metadados em um objeto.
    PutMetadata.content_disposition_after String Especifica o valor do cabeçalho Content-Disposition após a conclusão do job PutMetadata. É um campo opcional que só é preenchido se a disposição do conteúdo foi definida ou modificada.
    PutMetadata.content_encoding_after String Especifica o valor do cabeçalho Content-Encoding após a conclusão do job PutMetadata. É um campo opcional e só é preenchido se a codificação do conteúdo foi definida ou modificada.
    PutMetadata.content_language_after String Especifica o valor do cabeçalho Content-Language após a conclusão do job PutMetadata. É um campo opcional que só é preenchido se o idioma do conteúdo foi definido ou modificado.
    PutMetadata.content_type_after String Especifica o valor do cabeçalho Content-Type após a conclusão do job PutMetadata. É um campo opcional e só será preenchido se o tipo de conteúdo tiver sido definido ou modificado.
    PutMetadata.cache_control_after String Especifica o valor do cabeçalho Cache-Control após a conclusão do job PutMetadata. É um campo opcional que só é preenchido se o controle de cache foi definido ou modificado.
    PutMetadata.custom_time_after String Especifica o valor do cabeçalho Custom-Time após a conclusão do job PutMetadata. É um campo opcional que só é preenchido se o período personalizado foi definido ou modificado.
    PutMetadata.custom_metadata_after Mapa (chave: string, valor: string) Contém um mapa de pares de chave-valor Custom- Metadata após a transformação. Esse campo inclui todos os metadados definidos pelo usuário que foram definidos ou modificados no objeto. Isso permite o armazenamento flexível de metadados adicionais.