Cloud Logging para operações em lote de armazenamento

Nesta página, descrevemos como configurar e visualizar 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 de armazenamento oferecem suporte à geração de registros 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 o uso do 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 a atividade de operações 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 Logs Viewer (roles/logging.viewer) do Identity and Access Management fornece as permissões do Identity and Access Management 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 a geração de registros está ativada, 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 registrar um ou ambos os estados a seguir:

    • SUCCEEDED: a ação foi bem-sucedida.
    • 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 visualizar registros de operações em lote de armazenamento, faça o seguinte:

Console

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

    Acesse o Explorador de registros

  2. Selecionar um Cloud de Confiance projeto do

  3. No menu Upgrade, alterne de Leitor de registros legados para Análise de registros.

  4. Para filtrar seus registros e mostrar apenas entradas de operações em lote de armazenamento, 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.

Para mais informações sobre como usar a Análise de registros, consulte Como usar a Análise de registros.

Linha de comando

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

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 a seguir 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 de registro de operações em lote de armazenamento

Todos os campos específicos de 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 serviço, há uma estrutura comum compartilhada em todas as TransformActivityLog entradas. Esta seção descreve os campos de registro comuns e detalha os campos específicos da operação.

  • Campos de registro comuns

    Os campos a seguir 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 registro.
    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 informações de identificação adicionais 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 as entradas de registro para diferentes operações em lote está no objeto de nível superior aninhado no jsonPayload. Apenas um dos objetos a seguir está disponível em uma determinada entrada de registro, correspondente à 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
}
}

    • Reescrever objeto (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"
}
}

    • Colocar 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 reescrita 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 é preenchido se a chave de criptografia do objeto for alterada 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 e só é preenchido se a disposição do conteúdo for 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 de conteúdo for 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 e só é preenchido se o idioma do conteúdo for 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ó é preenchido se o tipo de conteúdo for definido ou modificado.
    PutMetadata.cache_control_after String Especifica o Cache-Control valor do cabeçalho após a conclusão do PutMetadata job. É um campo opcional e só é preenchido se o controle de cache for 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 e só é preenchido se o horário personalizado for definido ou modificado.
    PutMetadata.custom_metadata_after Mapa (chave: string, valor: string) Contém um mapa de Custom- Metadata pares de chave-valor após a transformação. Esse campo inclui todos os metadados definidos pelo usuário que foram definidos ou modificados no objeto. Ele permite o armazenamento flexível de metadados adicionais.