Compartir vía

Esquema CloudEvents v1.0 con Azure Event Grid

  • Artículo

Azure Event Grid admite de forma nativa eventos de la implementación de JSON de CloudEvents v1.0 y el enlace del protocolo HTTP. CloudEvents es una especificación abierta para la descripción de datos de eventos. CloudEvents simplifica la interoperabilidad al proporcionar un esquema de eventos común para la publicación y el consumo de eventos basados en la nube. Este esquema permite herramientas uniformes, formas estándar de enrutar y administrar eventos y formas universales de deserializar el esquema de eventos externo. Con un esquema común, puede integrar más fácilmente el trabajo entre plataformas.

En la compilación de CloudEvents participan varios colaboradores, entre ellos Microsoft, mediante Cloud Native Compute Foundation. Actualmente está disponible en versión 1.0.

En este artículo se describe el uso del esquema CloudEvents con Event Grid.

Evento de ejemplo con el esquema CloudEvents

El siguiente es un ejemplo de un evento de Azure Blob Storage con el formato de 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"
        }
    }
}

Una descripción detallada de los campos disponibles, sus tipos y definiciones en CloudEvents v1.0 se encuentra disponible aquí.

Los valores de encabezados de los eventos proporcionados en el esquema de CloudEvents y el esquema de Event Grid son los mismos excepto para content-type. En el esquema de CloudEvents, ese valor de encabezado es "content-type":"application/cloudevents+json; charset=utf-8". En el esquema de Event Grid, ese valor de encabezado es "content-type":"application/json; charset=utf-8".

Configuración de CloudEvents

Puede usar Event Grid con eventos de entrada y salida de esquema CloudEvents. CloudEvents se puede usar con eventos del sistema, como eventos de Blob Storage y eventos de IoT Hub, y con eventos personalizados. Además de admitir CloudEvents, Event Grid admite un formato de evento de Event Grid de su propiedad, no extensible, pero totalmente funcional. En la tabla siguiente se describe la transformación admitida al usar los formatos CloudEvents y Event Grid como esquema de entrada en temas y como esquema de salida en suscripciones de eventos. No se puede usar un esquema de salida de Event Grid al usar CloudEvents como esquema de entrada porque CloudEvents admite atributos de extensión que no son compatibles con el esquema de Event Grid.

Esquema de entrada Esquema de salida
Formato de CloudEvents Formato de CloudEvents
Formato de Event Grid Formato de CloudEvents
Formato de Event Grid Formato de Event Grid

Con todos los esquemas de eventos, Event Grid exige la validación cuando se realiza una publicación en un tema de Event Grid y cuando se crea una suscripción de eventos. Para más información, vea Event Grid security and authentication (Seguridad y autenticación de Event Grid).

Esquema de entrada

El esquema de entrada de un tema personalizado se establece al crear este utilizando el parámetro input-schema.

Con la CLI de Azure, use:

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

Para PowerShell, use:

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

Esquema de salida

El esquema de salida se establece al crear la suscripción de eventos mediante el parámetro event-delivery-schema.

Con la CLI de 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 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

Uso con Azure Functions

Visual Studio o Visual Studio Code

Si usa Visual Studio o Visual Studio Code, y el lenguaje de programación C# para desarrollar funciones, asegúrese de que usa el paquete NuGet más reciente de Microsoft.Azure.WebJobs.Extensions.EventGrid (versión 3.3.1 o superior).

En Visual Studio, use Herramientas ->Administrador de paquetes NuGet ->Consola del Administrador de paquetes y ejecute el comando Install-Package (Install-Package Microsoft.Azure.WebJobs.Extensions.EventGrid -Version 3.3.1). Como alternativa, haga clic con el botón derecho en el proyecto en la ventana Explorador de soluciones y seleccione el menú Administrar paquetes NuGet para buscar el paquete NuGet e instalarlo o actualizarlo a la versión más reciente.

En VS Code, actualice el número de versión del paquete Microsoft.Azure.WebJobs.Extensions.EventGrid en el archivo csproj del proyecto de 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>

En el ejemplo siguiente se muestra una función Azure Functions, versión 3.x, desarrollada en Visual Studio o en Visual Studio Code. Usa un parámetro de enlace CloudEvent y 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);
        }
    }
}

Experiencia de desarrollo de Azure Portal

Si usa Azure Portal para desarrollar una función de Azure, siga estos pasos:

  1. Actualice el nombre del parámetro en el archivo function.json a cloudEvent.

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

  2. Actualice el archivo run.csx, tal como se muestra en el código de ejemplo siguiente.

    #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 más información, consulte Desencadenador de Azure Event Grid de Azure Functions.

Contenido relacionado

Para obtener información sobre la validación de puntos de conexión con Cloud Events, consulte Validación de puntos de conexión con CloudEvents 1.0.