Compartilhar via

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

  • Artigo

A Grade de Eventos do Azure o oferece suporte nativo à implementação JSON do CloudEvents v1.0 e à vinculação ao protocolo HTTP. CloudEvents é uma especificação aberta para descrever dados de eventos. O CloudEvents simplifica a interoperabilidade, fornecendo um esquema comum do evento para publicar e consumir eventos com base em nuvem. Esse esquema permite ferramentas uniforme, formas padrão de roteamento e manipulação de eventos e maneiras universais de desserializar o esquema de evento externo. Com um esquema comum, você pode integrar facilmente mais trabalho entre plataformas.

O CloudEvents está sendo criado por vários colaboradores, incluindo a Microsoft, por meio da Cloud Native Computing Foundation. Ele está disponível como versão 1.0.

Este artigo descreve o esquema CloudEvents com a Grade de Eventos.

Exemplo de evento usando o esquema CloudEvents

Aqui está um exemplo de um evento de Armazenamento de Blobs 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 dos cabeçalhos para eventos entregues no esquema CloudEvents e no esquema da Grade de Eventos 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 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 CloudEvents. Você pode usar o CloudEvents para eventos do sistema, como eventos do Armazenamento de Blob e eventos do Hub IoT e eventos personalizados. Além de dar suporte ao CloudEvents, a Grade de Eventos dá suporte a um formato de evento proprietário, não existente, mas totalmente funcional da Grade de Eventos. A tabela a seguir descreve a transformação com suporte ao usar os formatos CloudEvents e Grade de Eventos como um esquema de entrada em tópicos e como um esquema de saída em assinaturas de evento. Um esquema de saída da Grade de Eventos não pode ser usado ao usar o CloudEvents como um esquema de entrada porque o CloudEvents dá suporte a atributos de extensão que não têm suporte no esquema da Grade de Eventos.

Esquema de entrada Esquema de saída
Formato de CloudEvents Formato de CloudEvents
Formato da Grade de Eventos Formato de CloudEvents
Formato da Grade de Eventos Formato da Grade de Eventos

Para todos os esquemas de evento, a Grade de Eventos requer validação ao publicar em um tópico de grade de eventos e ao criar uma inscrição de evento. Para saber mais, confira Event Grid security and authentication (Segurança e autenticação da Grade de Eventos).

Esquema de entrada

Quando você cria o tópico personalizado, define o esquema de entrada para ele usando o parâmetro input-schema.

Para a CLI do Azure, use:

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

Para o PowerShell, use:

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

Esquema de saída

Quando você cria a assinatura de evento, define o esquema de saída usando o parâmetro event-delivery-schema.

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, use:

$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 estiver usando o Visual Studio ou o Visual Studio Code e a linguagem de programação C# para desenvolver funções, certifique-se de estar usando o pacote NuGet Microsoft.Azure.WebJobs.Extensions.EventGrid mais recente (versão 3.3.1 ou superior).

No Visual Studio, use as Ferramentas – >Gerenciador de Pacotes NuGet – >Console do Gerenciador de Pacotes e execute o comando Install-Package (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 instale-o ou atualize-o para a versão mais recente.

No VS Code, atualize o número de versão do pacote Microsoft.Azure.WebJobs.Extensions.EventGrid no arquivo csproj do projeto 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 parâmetro de associação CloudEvent 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 no portal do Azure

Se estiver usando o portal do Azure para desenvolver uma função do Azure, siga estas etapas:

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

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

  2. Atualize o arquivo run.csx 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);
}

Observação

Para mais informações, confira Gatilho da Grade de Eventos do Azure para o Azure Functions.

Conteúdo relacionado

Para obter informações sobre a validação de ponto de extremidade com eventos de nuvem, confira Validação do ponto de extremidade com o CloudEvents 1.0.