Publicar eventos em tópicos personalizados da Grade de Eventos do Azure com chaves de acesso

  • Artigo

Este artigo descreve como publicar um evento para um tópico personalizado usando uma chave de acesso. Ele mostra o formato dos dados de postagem e evento. O Contrato de Nível de Serviço (SLA) só se aplica às publicações que correspondem ao formato esperado.

Observação

A autenticação do Microsoft Entra dá suporte de autenticação superior ao oferecido pela chave de acesso ou pela autenticação de token SAS (Assinatura de Acesso Compartilhado). Com a autenticação do Microsoft Entra, a identidade é validada no provedor de identidade do Microsoft Entra. Como desenvolvedor, você não precisará manipular chaves em seu código se usar a autenticação do Microsoft Entra. Você também se beneficiará de todos os recursos de segurança incorporados à plataforma de identidade da Microsoft, como o Acesso Condicional, que pode ajudar a melhorar a postura de segurança do seu aplicativo. Para saber mais, confira Autenticar clientes de publicação usando o Microsoft Entra ID.

Ponto de extremidade

Ao enviar o HTTP POST para um tópico personalizado, use o formato URI: https://<topic-endpoint>?api-version=2018-01-01. Por exemplo, um URI válido é: https://exampletopic.westus2-1.eventgrid.azure.net/api/events?api-version=2018-01-01. Para obter o ponto de extremidade para um tópico personalizado usando a CLI do Azure, use:

az eventgrid topic show --name <topic-name> -g <topic-resource-group> --query "endpoint"

Para obter o ponto de extremidade para um tópico personalizado usando o Azure PowerShell, use:

(Get-AzEventGridTopic -ResourceGroupName <topic-resource-group> -Name <topic-name>).Endpoint

Na solicitação, inclua um valor de cabeçalho chamado aeg-sas-key que contém uma chave para autenticação. Por exemplo, um valor de cabeçalho válido é aeg-sas-key: xxxxxxxxxxxxxxxxxxxxxxx. Para obter a chave para um tópico personalizado usando a CLI do Azure, use:

az eventgrid topic key list --name <topic-name> -g <topic-resource-group> --query "key1"

Para obter a chave para um tópico personalizado usando o PowerShell, use:

(Get-AzEventGridTopicKey -ResourceGroupName <topic-resource-group> -Name <topic-name>).Key1

Dados de evento

Para tópicos personalizados, os dados de nível superior contêm os mesmos campos do que os eventos definidos pelo recurso padrão. Uma dessas propriedades é uma propriedade data que contém propriedades exclusivas para o tópico personalizado. Como publicador de eventos, você determina as propriedades para esse objeto de dados. Aqui está o esquema:

[
  {
    "id": string,    
    "eventType": string,
    "subject": string,
    "eventTime": string-in-date-time-format,
    "data":{
      object-unique-to-each-publisher
    },
    "dataVersion": string
  }
]

Para obter uma descrição dessas propriedades, consulte esquema de evento de Grade de Eventos do Azure. Ao postar eventos em um tópico da grade de eventos, a matriz pode ter um tamanho total de até 1 MB. O tamanho máximo permitido para um evento também é 1 MB. Eventos acima de 64 KB são cobrados em incrementos de 64 KB. Ao receber eventos em um lote, o número máximo permitido de eventos é 5.000 por lote.

Por exemplo, um esquema de dados de evento válido é:

[{
  "id": "1807",
  "eventType": "recordInserted",
  "subject": "myapp/vehicles/motorcycles",
  "eventTime": "2017-08-10T21:03:07+00:00",
  "data": {
    "make": "Ducati",
    "model": "Monster"
  },
  "dataVersion": "1.0"
}]

Resposta

Após a postagem para o ponto de extremidade do tópico, você receberá uma resposta. A resposta é um código de resposta HTTP padrão. Algumas respostas comuns são:

Result Resposta
Sucesso 200 OK
Os dados de evento têm formato incorreto 400 Solicitação Inválida
Chave de acesso inválida 401 Não Autorizado
Ponto de extremidade incorreto 404 Não Encontrado
Matriz ou evento excede os limites de tamanho O conteúdo 413 é muito grande

Para erros, o corpo da mensagem tem o seguinte formato:

{
    "error": {
        "code": "<HTTP status code>",
        "message": "<description>",
        "details": [{
            "code": "<HTTP status code>",
            "message": "<description>"
    }]
  }
}

Próximas etapas