Schéma CloudEvents v1.0 avec Azure Event Grid

Azure Event Grid prend en charge en mode natif les événements dans l’implémentation JSON de CloudEvents v1.0 et la liaison de protocole HTTP. CloudEvents est une spécification ouverte qui décrit les données d’événement. CloudEvents simplifie l’interopérabilité grâce à un schéma d’événement commun pour la publication et la consommation des événements basés sur le cloud. Ce schéma permet l’utilisation d’outils uniformes, la mise en œuvre de méthodes de routage et de gestion des événements standard, ainsi que de méthodes universelles pour désérialiser le schéma d’événement externe. Avec un schéma commun, vous pouvez plus facilement intégrer le travail entre plusieurs plateformes.

Plusieurs collaborateurs, dont Microsoft, travaillent à l’élaboration de CloudEvents par le biais de la Cloud Native Computing Foundation. Il est actuellement disponible en version 1.0.

Cet article décrit l’utilisation du schéma CloudEvents avec Event Grid.

Exemple d'événement utilisant le schéma CloudEvents

Voici un exemple d’événement Stockage Blob Azure dans le format 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"
        }
    }
}

Une description détaillée des champs disponibles, de leurs types et définitions dans CloudEvents v1.0 est disponible ici.

Les valeurs des en-têtes pour les événements remis dans le schéma CloudEvents et le schéma Event Grid sont identiques, à l’exception de content-type. Pour le schéma CloudEvents, cette valeur d’en-tête est "content-type":"application/cloudevents+json; charset=utf-8". Pour le schéma Event Grid, cette valeur d’en-tête est "content-type":"application/json; charset=utf-8".

Configuration pour CloudEvents

Vous pouvez utiliser Event Grid pour l’entrée et la sortie des événements dans le schéma CloudEvents. Vous pouvez utiliser CloudEvents pour des événements système, tels que les événements Stockage Blob et les événements IoT Hub, et des événements personnalisés. En plus de prendre en charge CloudEvents, Event Grid prend en charge un format d’événement Event Grid propriétaire, non extensible, mais entièrement fonctionnel. Le tableau suivant décrit la transformation prise en charge lors de l’utilisation des formats CloudEvents et Event Grid comme schéma d’entrée dans les rubriques et comme schéma de sortie dans les abonnements aux événements. Un schéma de sortie Event Grid ne peut pas être utilisé lors de l’utilisation de CloudEvents comme schéma d’entrée, car CloudEvents prend en charge les attributs d’extension qui ne sont pas pris en charge par le schéma Event Grid.

Pour tous les schémas d’événement, Event Grid requiert une validation au moment de la publication sur une rubrique Event Grid et de la création d’un abonnement aux événements. Pour en savoir plus, consultez la page Sécurité et authentification pour Event Grid.

Schéma d’entrée

Vous définissez le schéma d’entrée d’une rubrique personnalisée lorsque vous créez la rubrique personnalisée à l’aide du paramètre input-schema.

Pour l’interface de ligne de commande Azure, utilisez :

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

Pour PowerShell, utilisez la commande suivante :

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

Schéma de sortie

Vous définissez le schéma de sortie lorsque vous créez l’abonnement aux événements à l’aide du paramètre event-delivery-schema.

Pour l’interface de ligne de commande Azure, utilisez :

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

Pour PowerShell, utilisez la commande suivante :

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

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

Utiliser avec Azure Functions

Visual Studio ou Visual Studio Code

Si vous utilisez Visual Studio ou Visual Studio Code et le langage de programmation C# pour développer des fonctions, assurez-vous que vous utilisez le dernier package NuGet Microsoft.Azure.WebJobs.Extensions.EventGrid (version 3.3.1 ou ultérieure).

Dans Visual Studio, utilisez la console Outils ->Gestionnaire de package NuGet ->Gestionnaire de package, puis exécutez la Install-Package commande ().Install-Package Microsoft.Azure.WebJobs.Extensions.EventGrid -Version 3.3.1 Vous pouvez également cliquer avec le bouton droit sur le projet dans la fenêtre Explorateur de solutions, puis sélectionner le menu Gérer les packages NuGet pour rechercher le package NuGet et l’installer ou le mettre à jour vers la dernière version.

Dans VS Code, mettez à jour le numéro de version du package Microsoft.Azure.WebJobs.Extensions.EventGrid dans le fichier csproj pour votre projet 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>

L’exemple suivant montre une fonction Azure Functions version 3.x développée dans Visual Studio ou Visual Studio Code. Il utilise un paramètre de liaison CloudEvent et 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);
        }
    }
}

Expérience de développement Portail Azure

Si vous utilisez le Portail Azure pour développer une fonction Azure, procédez comme suit :

1. Remplacez le nom du paramètre dans le fichier function.json par cloudEvent.

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

2. Mettez à jour le fichier run.csx comme indiqué dans l’exemple de code suivant.

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

Contenu connexe

Pour plus d’informations sur la validation de points de terminaison avec CloudEvents, consultez Validation de points de terminaison avec CloudEvents 1.0.