Cloud Logging para operações em lote de armazenamento

Esta página descreve como configurar e ver os registos de operações em lote de armazenamento através do Cloud Logging. Um trabalho de operações em lote de armazenamento pode ser configurado para gerar entradas de registo do Cloud Logging para cada trabalho de transformação. Cada entrada de registo corresponde à transformação tentada de um objeto.

As operações em lote de armazenamento suportam o registo no Cloud Logging e nos registos de auditoria do Cloud Storage. Embora ambas as opções capturem ações de operações em lote de armazenamento, recomendamos que use o Cloud Logging. O Cloud Logging oferece uma plataforma centralizada para análise de registos, monitorização em tempo real e filtragem avançada, oferecendo uma solução robusta para gerir e compreender a atividade de operações em lote.

Antes de começar

Confirme que tem acesso ao Cloud Logging. Para usar o Cloud Logging, recomendamos que conceda a função do Identity and Access Management Logs Viewer (roles/logging.viewer). A função Logs Viewer (roles/logging.viewer) Identity and Access Management fornece as autorizações de acesso e gestão de identidades necessárias para ver os seus dados do Cloud Logging. Para mais informações sobre as autorizações de acesso ao Logging, consulte o artigo Controlo de acesso com a IAM.

Para validar e conceder as autorizações do IAM, conclua os seguintes passos:

Compreenda os detalhes de registo

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

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

  • Estados registáveis: para cada ação, pode optar por registar um ou ambos os seguintes estados:

    • SUCCEEDED: a ação foi bem-sucedida.
    • FAILED: a ação falhou.

Ative o registo

Para ativar o registo, especifique as ações e os estados a registar.

Linha de comandos

Quando criar uma tarefa de operações em lote de armazenamento com gcloud storage batch-operations jobs create, use os sinalizadores --log-actions e --log-action-states para ativar o registo.

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

Onde:

  • JOB_NAME é o nome que quer dar ao seu trabalho. Por exemplo, my-job.
  • MANIFEST_LOCATION é a localização do seu manifesto. Por exemplo, gs://my-bucket/manifest.csv.
  • LOG_ACTION_STATES é uma lista separada por vírgulas de estados a registar. Por exemplo, succeeded,failed.

API REST

Create a storage batch operations job com um LoggingConfig.

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

Onde:

LOG_ACTION_STATES é uma lista de estados separados por vírgulas a registar. Por exemplo, "SUCCEEDED","FAILED".

Ver registos

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

Consola

  1. Aceda ao Google Cloud menu de navegação e selecione Registo > Explorador de registos :<br\></br\>

    Aceda ao Explorador de registos

  2. Selecione um Google Cloud projeto.

  3. No menu Atualizar, mude de Visualizador de registos antigo para Explorador de registos.

  4. Para filtrar os registos de modo a mostrar apenas as entradas de operações em lote de armazenamento, escreva 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 durante o qual devem ser devolvidos os resultados.

Para mais informações sobre a utilização do Explorador de registos, consulte o artigo Usar o Explorador de registos.

Linha de comandos

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

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

gcloud logging read "resource.type=storage_batch_operations_job"

API REST

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

Para filtrar os resultados de modo a incluir apenas entradas relacionadas com operações em lote de armazenamento, use o campo filter. Segue-se um exemplo de um objeto de pedido JSON:

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

Onde:

my-project-name é o nome do seu projeto.

Formato do registo de operações em lote de armazenamento

Todos os campos específicos das operações em lote de armazenamento estão contidos num objeto jsonPayload. Embora o conteúdo exato de jsonPayload varie consoante o tipo de serviço, existe uma estrutura comum partilhada em todas as entradas TransformActivityLog. Esta secção descreve os campos de registo comuns e, em seguida, detalha os campos específicos da operação.

  • Campos de registo comuns

    Os seguintes campos aparecem em todos os registos:

    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 seguinte descreve cada um dos campos de registo comuns:

    Campos de registo comuns Tipo Descrição
    @type String Especifica o tipo de payload da entrada de registo e indica que o registo representa um TransformActivityLog para operações em lote de armazenamento.
    completeTime Indicação de tempo A data/hora em conformidade com a norma 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ó é apresentada se o valor de status.statusCode não for OK.
    status.errorType String O tipo de erro. O tipo de erro só é apresentado se o valor de status.statusCode não for OK.
    status.statusCode String O código de estado da operação. A operação é bem-sucedida se o valor for OK; qualquer outro valor indica uma falha.
    logName String O nome completo do recurso do registo, que indica o projeto e a stream de registos.
    receiveTimestamp Indicação de tempo A data/hora em que a entrada do registo foi recebida pelo sistema de registo.
    resource Objeto Informações sobre o recurso que gerou a entrada do registo.
    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 registo.
    objectMetadataBefore Objeto Contém metadados do objeto antes de se tentar a operação em lote.
    objectMetadataBefore.gcsObject Objeto Detalhes sobre o objeto.
    objectMetadataBefore.gcsObject.bucket String O nome do contentor 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 contentor.

  • Conteúdos específicos da operação jsonPayload

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

    • Eliminar objeto (DeleteObject)

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

    • Coloque a retenção de objetos (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"
}
}

    • Coloque 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 seguinte descreve os campos de registo específicos da operação:

    Campos de registo específicos da operação Tipo Descrição
    PutObjectHold Objeto Indica uma operação de manter premido num objeto.
    PutObjectHold.temporaryHoldAfter Booleano Se o valor for True, indica que foi aplicada uma retenção temporária ao objeto após a conclusão da tarefa de operações em lote de armazenamento. Os valores válidos são True ou False.
    PutObjectHold.eventBasedHoldAfter Booleano Se o valor for True, indica que foi aplicada uma retenção baseada em eventos ao objeto após a conclusão do trabalho de operações em lote de armazenamento. Os valores válidos são True ou False.
    RewriteObject Objeto Indica uma operação de reescrita num objeto.
    RewriteObject.kmsKeyVersionAfter String A versão da chave do Cloud Key Management Service usada após a tarefa de reescrita. O campo kmsKeyVersionAfter é preenchido se a chave de encriptação do objeto tiver sido alterada como resultado da reescrita. É um campo opcional, o que significa que 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 num objeto
    PutMetadata.content_disposition_after String Especifica o valor do cabeçalho Content-Disposition após a conclusão da tarefa PutMetadata. É um campo opcional e só é preenchido se a disposição do conteúdo tiver sido definida ou modificada.
    PutMetadata.content_encoding_after String Especifica o valor do cabeçalho Content-Encoding após a conclusão da tarefa PutMetadata. É um campo opcional e só é preenchido se a codificação de conteúdo tiver sido definida ou modificada.
    PutMetadata.content_language_after String Especifica o valor do cabeçalho Content-Language após a conclusão da tarefa PutMetadata. É um campo opcional e só é preenchido se o idioma do conteúdo tiver sido definido ou modificado.
    PutMetadata.content_type_after String Especifica o valor do cabeçalho Content-Type após a conclusão da tarefa PutMetadata. É um campo opcional e só é 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 da tarefa PutMetadata. É um campo opcional e só é preenchido se o controlo da cache tiver sido definido ou modificado.
    PutMetadata.custom_time_after String Especifica o valor do cabeçalho Custom-Time após a conclusão da tarefa PutMetadata. É um campo opcional e só é preenchido se a hora personalizada tiver sido definida ou modificada.
    PutMetadata.custom_metadata_after Map (key: string, value: string) Contém um mapa de pares de chave-valor Custom- Metadata após a transformação. Este campo inclui todos os metadados definidos pelo utilizador que foram definidos ou modificados no objeto. Permite o armazenamento flexível de metadados adicionais.