Uso del esquema CloudEvents v1.0 con Event Grid

  • Artículo

Además de su esquema de eventos predeterminado, 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 uso 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 cómo usar el esquema CloudEvents con Event Grid.

Esquema CloudEvent

Este es un ejemplo de un evento de Azure Blob Storage en 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}",
    "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 obtener una descripción detallada de los campos disponibles, sus tipos y definiciones, consulte CloudEvents v1.0.

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

Configurar para CloudEvents

Puede usar Event Grid con eventos de entrada y salida en el esquema de CloudEvents. En la tabla siguiente, se describen las transformaciones posibles:

Recurso de Event Grid Esquema de entrada Esquema de entrega
Temas del sistema Esquema de Event Grid Esquema de Event Grid o de CloudEvents
Temas o dominios personalizados Esquema de Event Grid Esquema de Event Grid o de CloudEvents
Temas o dominios personalizados Esquema de CloudEvents Esquema de CloudEvents
Temas o dominios personalizados Esquema personalizado Esquema personalizado, de Event Grid o de CloudEvent
Temas de asociados Esquema de CloudEvents Esquema de CloudEvents

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.

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.

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

Validación de puntos de conexión con CloudEvents v1.0

Si ya está familiarizado con Event Grid, es posible que conozca el protocolo de enlace de validación de punto de conexión para evitar el uso inapropiado. CloudEvents v1.0 implementa su propia semántica de protección contra abusos mediante el método HTTP OPTIONS. Para más información al respecto, consulte Webhooks de HTTP 1.1 para la entrega de eventos: versión 1.0. Cuando usa el esquema de CloudEvents para la salida, Event Grid usa la protección contra abusos de CloudEvents v1.0 en lugar del mecanismo de eventos de validación de Event Grid.

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.

Pasos siguientes