Partilhar via

Esquema do CloudEvents v1.0 com a Grade de Eventos do Azure

  • Artigo

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 o uso do esquema CloudEvents com a grade de eventos.

Exemplo de evento usando o esquema CloudEvents

Aqui está um exemplo de um evento de 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}",    
    "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"
        }
    }
}

Uma descrição detalhada dos campos disponíveis, seus tipos e definições no CloudEvents v1.0 está disponível aqui.

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".

Configuração para CloudEvents

Você pode usar a grade de eventos para entrada e saída de eventos no esquema do CloudEvents. Você pode usar o CloudEvents para eventos do sistema, como eventos de Armazenamento de Blob e eventos do Hub IoT, e eventos personalizados. Além de suportar CloudEvents, o Event Grid suporta um formato de evento proprietário, não extensível, mas totalmente funcional. A tabela a seguir descreve a transformação suportada ao usar os formatos CloudEvents e Event Grid como um esquema de entrada em tópicos e como um esquema de saída em assinaturas de eventos. Um esquema de saída de Grade de Eventos não pode ser usado ao usar o CloudEvents como um esquema de entrada porque o CloudEvents oferece suporte a atributos de extensão que não são suportados pelo esquema de Grade de Eventos.

Esquema de entrada Esquema de saída
Formato CloudEvents Formato CloudEvents
Formato da grelha de eventos Formato CloudEvents
Formato da grelha de eventos Formato da grelha de eventos

Para todos os esquemas de eventos, a Grade de Eventos requer validação ao publicar em um tópico de Grade de Eventos e ao criar 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 quando cria o tópico personalizado usando o input-schema parâmetro.

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 de evento usando o event-delivery-schema parâmetro.

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

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.

Conteúdos relacionados

Para obter informações sobre a validação de endpoint com Cloud Events, consulte Validação de endpoint com CloudEvents 1.0.