Utiliser le schéma CloudEvents v1.0 avec Event Grid

  • Article

En plus de son schéma d’événement par défaut, 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 d’événements informatiques. 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 comment utiliser le schéma CloudEvents avec Event Grid.

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}",
    "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"
        }
    }
}

Pour obtenir une description détaillée des champs disponibles, de leur type et de leur définition, consultez CloudEvents v1.0.

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

Configurer pour CloudEvents

Vous pouvez utiliser Event Grid pour l’entrée et la sortie des événements dans le schéma CloudEvents. Le tableau suivant décrit les transformations possibles :

Ressource Event Grid Schéma d’entrée Schéma de remise
Rubriques sur le système Schéma Event Grid Schéma Event Grid ou CloudEvents
Rubriques/domaines personnalisés Schéma Event Grid Schéma Event Grid ou CloudEvents
Rubriques/domaines personnalisés Schéma CloudEvents Schéma CloudEvents
Rubriques/domaines personnalisés Schéma personnalisé Schéma personnalisé, schéma Event Grid ou schéma CloudEvents
Rubriques de partenaire Schéma CloudEvents Schéma CloudEvents

Pour tous les schémas d’événement, Event Grid nécessite une validation lorsque vous publiez dans une rubrique Event Grid et lorsque vous créez 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 pour une rubrique personnalisée lorsque vous la créez.

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.

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

Validation de point de terminaison avec CloudEvents v1.0

Si vous êtes déjà familiarisé avec Event Grid, vous pouvez être conscient de l’établissement d'une liaison de validation de point de terminaison pour empêcher les abus. CloudEvents v1.0 implémente sa propre sémantique de protection contre les abus à l’aide de la méthode HTTP OPTIONS. Pour en savoir plus à ce sujet, consultez Webhooks HTTP 1.1 pour la remise d’événements (version 1.0). Lorsque vous utilisez le schéma CloudEvents pour la sortie, Event Grid l’utilise avec la protection contre les abus CloudEvents v1.0 à la place du mécanisme d’événement de validation Event Grid.

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);
}

Notes

Pour en savoir plus, consultez Déclencheur Azure Event Grid pour Azure Functions.

Étapes suivantes