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

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:

Portal do Azure

Você pode encontrar o ponto de extremidade do tópico na guia Visão geral da página Tópico da Grade de Eventos no portal do Azure.

CLI do Azure

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

PowerShell do Azure

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

Cabeçalho

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:

Portal do Azure

Para obter a chave de acesso para o tópico personalizado, selecione a guia Chave de acesso na página Tópico da Grade de Eventos no portal do Azure.

CLI do Azure

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

PowerShell do Azure

(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. Quando um cliente envia eventos para 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. Quando um cliente recebe eventos em um lote, o número máximo permitido de eventos é de 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"
}]

Enviar o evento de exemplo

Esta seção mostra como enviar um evento de exemplo para o tópico personalizado.

Portal do Azure

1. No portal do Azure, inicie o Cloud Shell.

2. No Cloud Shell, execute os comandos do Azure PowerShell ou da CLI do Azure no Bash ou na sessão do PowerShell.

   

CLI do Azure

endpoint=$(az eventgrid topic show --name <topic name> -g <resource group name> --query "endpoint" --output tsv)

key=$(az eventgrid topic key list --name <topic name> -g <resource group name> --query "key1" --output tsv)

event='[ {"id": "'"$RANDOM"'", "eventType": "recordInserted", "subject": "myapp/vehicles/motorcycles", "eventTime": "'`date +%Y-%m-%dT%H:%M:%S%z`'", "data":{ "make": "Ducati", "model": "Monster"},"dataVersion": "1.0"} ]'

curl -X POST -H "aeg-sas-key: $key" -d "$event" $endpoint

PowerShell do Azure

$resourceGroupName = "<resource group name>"
$topicName = "<topic name>"

$endpoint = (Get-AzEventGridTopic -ResourceGroupName $resourceGroupName -Name $topicName).Endpoint

$keys = Get-AzEventGridTopicKey -ResourceGroupName $resourceGroupName -Name $topicName

$eventID = Get-Random 99999
#Date format should be SortableDateTimePattern (ISO 8601)
$eventDate = Get-Date -Format s

#Construct body using Hashtable
$htbody = @{
    id= $eventID
    eventType="recordInserted"
    subject="myapp/vehicles/motorcycles"
    eventTime= $eventDate   
    data= @{
        make="Ducati"
        model="Monster"
    }
    dataVersion="1.0"
}

#Use ConvertTo-Json to convert event body from Hashtable to JSON Object
#Append square brackets to the converted JSON payload since they are expected in the event's JSON payload syntax
$body = "["+(ConvertTo-Json $htbody)+"]"

Invoke-WebRequest -Uri $endpoint -Method POST -Body $body -Headers @{"aeg-sas-key" = $keys.Key1}

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>"
    }]
  }
}

Conteúdo relacionado

• Para obter informações sobre o monitoramento de entregas de evento, consulte Entrega de mensagens da Grade de Eventos do Monitor.
• Para saber mais sobre a chave de autenticação, confira Event Grid security and authentication (Segurança e autenticação da Grade de Eventos).
• Para obter mais informações sobre como criar uma assinatura da Grade de Eventos do Azure, confira Event Grid subscription schema (Esquema de assinatura da Grade de Eventos).