Formato CloudEvents

CloudEvents (cloudevents.io) é uma especificação para descrever dados de eventos de uma maneira comum. A especificação está na Cloud Native Computing Foundation (CNCF) e é organizada pelo Serverless Working Group da CNCF.

O Eventarc envia eventos para o serviço do Cloud Run no formato CloudEvents por meio de uma solicitação HTTP.

Formato de solicitação HTTP

Os serviços do Cloud Run recebem eventos dos roteadores de eventos como solicitações POST HTTP formatadas para a especificação de vinculação de protocolo HTTP da versão 1.0 do CloudEvents. Cada solicitação HTTP contém cabeçalhos específicos de eventos e um corpo, e é enviada ao caminho do URL raiz (/) do serviço.

Além de outros cabeçalhos HTTP, todos os eventos têm os seguintes cabeçalhos HTTP do CloudEvents:

Header Descrição Exemplo
ce-id Identificador exclusivo do evento. 1096434104173400
ce-source Identifica a origem do evento. //pubsub.googleapis.com/projects/my-project/topics/my-topic
ce-specversion A versão de especificação do CloudEvents usada para este evento. 1.0
ce-type O tipo de dados de evento. google.cloud.pubsub.topic.v1.messagePublished
ce-time Hora da geração do evento, no formato RFC 3339 (opcional). 2020-12-20T13:37:33.647Z

Formato de payload HTTP

Registros de auditoria do Cloud

Os eventos do tipo google.cloud.audit.log.v1.written têm o seguinte formato:

Cabeçalhos

ce-specversion: 1.0
ce-type: google.events.cloud.audit.v1.LogEntryData
ce-source: //SERVICE_NAME/projects/PROJECT_ID
ce-id: MESSAGE_ID
ce-time: PUBLISH_TIME
Content-Type: application/json; charset=utf-8
Content-Length: CONTENT_LENGTH
  • SERVICE_NAME: o URI da API do Google para o serviço que está emitindo o evento (bigquery.googleapis.com, por exemplo) para eventos do BigQuery.
  • PROJECT_ID: o ID do projeto do GCP.
  • MESSAGE_ID, PUBLISH_TIME, CONTENT_LENGTH: gerada pelo sistema.

Texto

O payload é um objeto JSON que detalha o evento dos registros de auditoria do Cloud. Em protoPayload, você pode encontrar os valores resourceName, serviceName e methodName. Veja um exemplo de registro de auditoria do Cloud Storage:

{
  "protoPayload": {
    "status": {},
    "authenticationInfo": { ... },
    "requestMetadata": {
      "callerIp": "...",
      "callerSuppliedUserAgent": "...",
      "requestAttributes": {
        "time": "YYYY-MM-DDThh:mm:ss.sZ",
        "auth": {}
      },
      "destinationAttributes": {}
    },
    "serviceName": "storage.googleapis.com",
    "methodName": "storage.objects.create",
    "authorizationInfo": [
      {
        "resource": "projects/_/buckets/MY_BUCKET/objects/MY_FILE.txt",
        "permission": "storage.objects.create",
        "granted": true,
        "resourceAttributes": {}
      },
      {
        "resource": "projects/_/buckets/MY_BUCKET/objects/MY_FILE.txt",
        "permission": "storage.objects.delete",
        "granted": true,
        "resourceAttributes": {}
      }
    ],
    "resourceName": "projects/_/buckets/MY_PROJECT/objects/MY_FILE.txt",
    "serviceData": {
      "policyDelta": {
        "bindingDeltas": [ ... ]
      },
      "@type": "type.googleapis.com/google.iam.v1.logging.AuditData"
    },
    "resourceLocation": {
      "currentLocations": [
        "us-central1"
      ]
    }
  },
  "insertId": "-qklu1af11306y",
  "resource": {
    "type": "gcs_bucket",
    "labels": {
      "location": "us-central1",
      "bucket_name": "MY_BUCKET",
      "project_id": "MY_PROJECT"
    }
  },
  "timestamp": "2021-04-09T17:57:16.718915757Z",
  "severity": "INFO",
  "logName": "projects/MY_PROJECT/logs/cloudaudit.googleapis.com%2Fdata_access",
  "receiveTimestamp": "2021-04-09T17:57:17.748555474Z"
}

Pub/Sub

Os eventos do tipo google.cloud.pubsub.topic.v1.messagePublished têm o seguinte formato:

Cabeçalhos

ce-specversion: 1.0
ce-type: google.cloud.pubsub.topic.v1.messagePublished
ce-source: //pubsub.googleapis.com/TOPIC
ce-id: MESSAGE_ID
ce-time: PUBLISH_TIME
Content-Type: application/json; charset=utf-8
Content-Length: CONTENT_LENGTH
  • TOPIC: o tópico do Pub/Sub em que o evento foi publicado.
  • MESSAGE_ID, PUBLISH_TIME, CONTENT_LENGTH: gerada pelo sistema.

Texto

O payload é uma mensagem push do Pub/Sub. No campo data, é possível encontrar a mensagem como uma string codificada em Base64.

{
   "message": {
     "attributes": {
       "key": "value"
     },
     "data": "SGVsbG8gV29ybGQK",
     "messageId": "136969346945",
     "publishTime": "2021-10-02T15:01:23.045123456Z"
   },
   "subscription": "projects/MY_PROJECT/subscriptions/MY_SUBSCRIPTION"
}

Código aberto

A estrutura do corpo HTTP de todos os eventos está disponível no repositório CloudEvents do GitHub.

Ele contém os seguintes itens para ajudar você a entender e usar os dados do CloudEvents na sua linguagem de programação:

  • Buffers de protocolo do Google para payloads de dados do CloudEvents
  • Esquemas JSON gerados
  • Um catálogo público de esquema JSON

Links para bibliotecas de cliente também estão incluídos.