Usar o esquema do CloudEvents v1.0 com a grade de eventos

Além de seu esquema de eventos padrão, a Grade de Eventos do Azure dá suporte nativo a eventos na implementação JSON do CloudEvents v1.0 e vinculação de protocolo HTTP. CloudEvents é uma especificação aberta para descrever dados de eventos.

O CloudEvents simplifica a interoperabilidade fornecendo um esquema de eventos comum para publicação e consumo de eventos baseados em nuvem. Esse esquema permite ferramentas uniformes, formas padrão de roteamento e manipulação de eventos e maneiras universais de desserializar o esquema de eventos externos. Com um esquema comum, você pode integrar mais facilmente o trabalho entre plataformas.

O CloudEvents está a ser construído por vários colaboradores, incluindo a Microsoft, através da Cloud Native Computing Foundation. Atualmente está disponível como versão 1.0.

Este artigo descreve como usar o esquema CloudEvents com a grade de eventos.

Esquema CloudEvent

Aqui está um exemplo de um evento do Armazenamento de Blob do Azure no formato CloudEvents:

{
    "specversion": "1.0",
    "type": "Microsoft.Storage.BlobCreated",  
    "source": "/subscriptions/{subscription-id}/resourceGroups/{resource-group}/providers/Microsoft.Storage/storageAccounts/{storage-account}",
    "id": "9aeb0fdf-c01e-0131-0922-9eb54906e209",
    "time": "2019-11-18T15:13:39.4589254Z",
    "subject": "blobServices/default/containers/{storage-container}/blobs/{new-file}",
    "dataschema": "#",
    "data": {
        "api": "PutBlockList",
        "clientRequestId": "4c5dd7fb-2c48-4a27-bb30-5361b5de920a",
        "requestId": "9aeb0fdf-c01e-0131-0922-9eb549000000",
        "eTag": "0x8D76C39E4407333",
        "contentType": "image/png",
        "contentLength": 30699,
        "blobType": "BlockBlob",
        "url": "https://gridtesting.blob.core.windows.net/testcontainer/{new-file}",
        "sequencer": "000000000000000000000000000099240000000000c41c18",
        "storageDiagnostics": {
            "batchId": "681fe319-3006-00a8-0022-9e7cde000000"
        }
    }
}

Para obter uma descrição detalhada dos campos disponíveis, seus tipos e definições, consulte CloudEvents v1.0.

Os valores de cabeçalhos para eventos entregues no esquema CloudEvents e no esquema Event Grid são os mesmos, exceto para content-type. Para o esquema CloudEvents, esse valor de cabeçalho é "content-type":"application/cloudevents+json; charset=utf-8". Para o esquema de Grade de Eventos, esse valor de cabeçalho é "content-type":"application/json; charset=utf-8".

Configurar para CloudEvents

Você pode usar a grade de eventos para entrada e saída de eventos no esquema CloudEvents. A tabela a seguir descreve as transformações possíveis:

Recurso Grade de Eventos	Esquema de entrada	Esquema de entrega
Tópicos de sistema	Esquema da Grelha de Eventos	Esquema de grade de eventos ou esquema CloudEvents
Tópicos/domínios personalizados	Esquema da Grelha de Eventos	Esquema de grade de eventos ou esquema CloudEvents
Tópicos/domínios personalizados	Esquema CloudEvents	Esquema CloudEvents
Tópicos/domínios personalizados	Esquema personalizado	Esquema personalizado, esquema de grade de eventos ou esquema do CloudEvents
Tópicos para parceiros	Esquema CloudEvents	Esquema CloudEvents

Para todos os esquemas de eventos, a Grade de Eventos requer validação quando você está publicando em um tópico de Grade de Eventos e quando está criando uma assinatura de evento.

Para obter mais informações, consulte Segurança e autenticação da grade de eventos.

Esquema de entrada

Você define o esquema de entrada para um tópico personalizado ao criar o tópico personalizado.

Para a CLI do Azure, use:

az eventgrid topic create --name demotopic -l westcentralus -g gridResourceGroup --input-schema cloudeventschemav1_0

Para o PowerShell, utilize:

New-AzEventGridTopic -ResourceGroupName gridResourceGroup -Location westcentralus -Name demotopic -InputSchema CloudEventSchemaV1_0

Esquema de saída

Você define o esquema de saída ao criar a assinatura do evento.

Para a CLI do Azure, use:

topicID=$(az eventgrid topic show --name demotopic -g gridResourceGroup --query id --output tsv)

az eventgrid event-subscription create --name demotopicsub --source-resource-id $topicID --endpoint <endpoint_URL> --event-delivery-schema cloudeventschemav1_0

Para o PowerShell, utilize:

$topicid = (Get-AzEventGridTopic -ResourceGroupName gridResourceGroup -Name <topic-name>).Id

New-AzEventGridSubscription -ResourceId $topicid -EventSubscriptionName <event_subscription_name> -Endpoint <endpoint_URL> -DeliverySchema CloudEventSchemaV1_0

Validação de endpoint com CloudEvents v1.0

Se você já estiver familiarizado com a Grade de Eventos, talvez esteja ciente do handshake de validação do ponto de extremidade para evitar abusos. O CloudEvents v1.0 implementa sua própria semântica de proteção contra abuso usando o método HTTP OPTIONS. Para ler mais sobre isso, consulte HTTP 1.1 Web Hooks para entrega de eventos - Versão 1.0. Quando você usa o esquema CloudEvents para saída, a Grade de Eventos usa a proteção contra abuso do CloudEvents v1.0 no lugar do mecanismo de eventos de validação da Grade de Eventos.

Usar com o Azure Functions

Visual Studio ou Visual Studio Code

Se você estiver usando Visual Studio ou Visual Studio Code e linguagem de programação C# para desenvolver funções, certifique-se de que está usando o pacote NuGet Microsoft.Azure.WebJobs.Extensions.EventGrid mais recente (versão 3.3.1 ou superior).

No Visual Studio, use o Tools -NuGet Package Manager ->>Package Manager Console e execute o Install-Package comando ().Install-Package Microsoft.Azure.WebJobs.Extensions.EventGrid -Version 3.3.1 Como alternativa, clique com o botão direito do mouse no projeto na janela Gerenciador de Soluções e selecione o menu Gerenciar Pacotes NuGet para procurar o pacote NuGet e instalá-lo ou atualizá-lo para a versão mais recente.

No VS Code, atualize o número da versão do pacote Microsoft.Azure.WebJobs.Extensions.EventGrid no arquivo csproj do seu projeto do Azure Functions.

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net6.0</TargetFramework>
    <AzureFunctionsVersion>v4</AzureFunctionsVersion>
  </PropertyGroup>
  <ItemGroup>
    <PackageReference Include="Microsoft.Azure.WebJobs.Extensions.EventGrid" Version="3.3.1" />
    <PackageReference Include="Microsoft.NET.Sdk.Functions" Version="4.1.1" />
  </ItemGroup>
  <ItemGroup>
    <None Update="host.json">
      <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
    </None>
    <None Update="local.settings.json">
      <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
      <CopyToPublishDirectory>Never</CopyToPublishDirectory>
    </None>
  </ItemGroup>
</Project>

O exemplo a seguir mostra uma função do Azure Functions versão 3.x desenvolvida no Visual Studio ou no Visual Studio Code. Ele usa um CloudEvent parâmetro binding e EventGridTrigger.

using Azure.Messaging;
using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Extensions.EventGrid;
using Microsoft.Extensions.Logging;

namespace Company.Function
{
    public static class CloudEventTriggerFunction
    {
        [FunctionName("CloudEventTriggerFunction")]
        public static void Run(ILogger logger, [EventGridTrigger] CloudEvent e)
        {
            logger.LogInformation("Event received {type} {subject}", e.Type, e.Subject);
        }
    }
}

Experiência de desenvolvimento do portal do Azure

Se estiver a utilizar o portal do Azure para desenvolver uma função do Azure, siga estes passos:

1. Atualize o nome do parâmetro no function.json arquivo para cloudEvent.

   {
     "bindings": [
       {
         "type": "eventGridTrigger",
         "name": "cloudEvent",
         "direction": "in"
       }
     ]
   }    
   

2. Atualize o run.csx arquivo conforme mostrado no código de exemplo a seguir.

   #r "Azure.Core"
   
   using Azure.Messaging;
   
   public static void Run(CloudEvent cloudEvent, ILogger logger)
   {
       logger.LogInformation("Event received {type} {subject}", cloudEvent.Type, cloudEvent.Subject);
   }
   

Nota

Para obter mais informações, consulte Gatilho de grade de eventos do Azure para o Azure Functions.

Próximos passos

• Para obter informações sobre como monitorar entregas de eventos, consulte Monitorar a entrega de mensagens da grade de eventos.
• Recomendamos que você teste, comente e contribua para o CloudEvents.
• Para obter mais informações sobre como criar uma assinatura da Grade de Eventos do Azure, consulte Esquema de assinatura da Grade de Eventos.