CloudEvents v1.0-Schema mit Azure Event Grid

Azure Event Grid unterstützt nativ Ereignisse in der JSON-Implementierung von CloudEvents 1.0 und in der HTTP-Bindung. CloudEvents ist eine offene Spezifikation zur Beschreibung von Ereignisdaten. CloudEvents vereinfacht die Interoperabilität, indem ein allgemeines Ereignisschema für die Veröffentlichung bereitgestellt wird und cloudbasierte Ereignisse genutzt werden. Dieses Schema ermöglicht einheitliche Tools und Standardmöglichkeiten für Routing und Behandlung von Ereignissen sowie universelle Möglichkeiten, das äußere Ereignisschema zu deserialisieren. Mit einem allgemeinen Schema können Sie Arbeit leichter plattformübergreifend integrieren.

CloudEvents wird von mehreren Partnern, einschließlich Microsoft, über die Cloud Native Computing Foundation entwickelt. Es ist derzeit in Version 1.0 verfügbar.

In diesem Artikel wird die Verwendung des CloudEvents-Schemas mit Event Grid beschrieben.

Beispielereignis mit CloudEvents-Schema

Dies ist ein Beispiel für ein Azure Blob Storage-Ereignis im CloudEvents-Format:

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

Hier finden Sie eine ausführliche Beschreibung der verfügbaren Felder, Typen und Definitionen in CloudEvents v1.0.

Die im CloudEvents- und Event Grid-Schema übermittelten Headerwerte für Ereignisse sind mit Ausnahme von content-type identisch. Für das CloudEvents-Schema ist dieser Headerwert "content-type":"application/cloudevents+json; charset=utf-8". Für das Event Grid-Schema ist dieser Headerwert "content-type":"application/json; charset=utf-8".

Konfiguration für CloudEvents

Sie können Event Grid für die Eingabe und Ausgabe von Ereignissen im CloudEvents-Schema verwenden. Sie können CloudEvents für Systemereignisse wie Blob Storage-Ereignisse und IoT Hub-Ereignisse sowie benutzerdefinierte Ereignisse verwenden. Zusätzlich zur Unterstützung von CloudEvents unterstützt Event Grid ein proprietäres, nonextensibles, aber voll funktionsfähiges Event Grid-Ereignisformat. In der folgenden Tabelle wird die Transformation beschrieben, die bei der Verwendung von CloudEvents- und Event Grid-Formaten als Eingabeschema in Themen und als Ausgabeschema in Ereignisabonnements unterstützt wird. Ein Event Grid-Ausgabeschema kann nicht verwendet werden, wenn CloudEvents als Eingabeschema verwendet wird, weil CloudEvents Erweiterungsattribute unterstützt, die vom Event Grid-Schema nicht unterstützt werden.

Für alle Ereignisschemas setzt Event Grid beim Veröffentlichen in einem Event Grid-Thema und Erstellen eines Ereignisabonnements eine Überprüfung voraus. Weitere Informationen finden Sie unter Event Grid – Sicherheit und Authentifizierung.

Eingabeschema

Das Eingabeschema für ein benutzerdefiniertes Thema wird beim Erstellen des benutzerdefinierten Themas mit dem Parameter input-schema festgelegt.

Verwenden Sie für die Azure CLI Folgendes:

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

Verwenden Sie für PowerShell Folgendes:

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

Ausgabeschema

Das Ausgabeschema wird beim Erstellen des Ereignisabonnements mit dem Parameter event-delivery-schema festgelegt.

Verwenden Sie für die Azure CLI Folgendes:

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

Verwenden Sie für PowerShell Folgendes:

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

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

Verwendung mit Azure Functions

Visual Studio oder Visual Studio Code

Wenn Sie Funktionen mit Visual Studio oder Visual Studio Code in der Programmiersprache C# entwickeln, stellen Sie sicher, dass Sie das neueste NuGet-Paket von Microsoft.Azure.WebJobs.Extensions.EventGrid (Version 3.3.1 oder höher) verwenden.

Wechseln Sie in Visual Studio zu Tools ->NuGet-Paket-Manager ->Paket-Manage-Konsole, und führen Sie den Befehl Install-Package (Install-Package Microsoft.Azure.WebJobs.Extensions.EventGrid -Version 3.3.1) aus. Alternativ können Sie im Fenster „Projektmappen-Explorer“ mit der rechten Maustaste auf das Projekt klicken und das Menü NuGet-Pakete verwalten auswählen, um nach dem NuGet-Paket zu suchen und es zu installieren oder auf die neueste Version zu aktualisieren.

Aktualisieren Sie in VS Code die Versionsnummer für das Paket Microsoft.Azure.WebJobs.Extensions.EventGrid in der Datei csproj für Ihr Azure Functions-Projekt.

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

Das folgende Beispiel zeigt eine Funktion der Azure Functions-Version 3.x, die entweder in Visual Studio oder Visual Studio Code entwickelt wurde. Es verwendet den Bindungsparameter CloudEvent sowie 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);
        }
    }
}

Entwicklung im Azure-Portal

Wenn Sie das Azure-Portal verwenden, um eine Azure-Funktion zu entwickeln, führen Sie die folgenden Schritte aus:

1. Ändern Sie den Namen des Parameters in der Datei function.json in cloudEvent.

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

2. Aktualisieren Sie die Datei run.csx wie im folgenden Beispielcode gezeigt:

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

Zugehöriger Inhalt

Weitere Informationen zur Endpunktüberprüfung mit Cloudereignissen finden Sie unter Endpunktüberprüfung mit CloudEvents 1.0.