Verwenden des CloudEvents 1.0-Schemas mit Event Grid

  • Artikel

Zusätzlich zu seinem Standardereignisschema unterstützt Azure Event Grid 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 mithilfe eines gemeinsamen Ereignisschemas für die Veröffentlichung und Nutzung von cloudbasierten Ereignissen. Dieses Schema ermöglicht einheitliche Tools, Standardverfahren für Routing und Behandlung von Ereignissen sowie universelle Verfahren zum Deserialisieren des äußeren Ereignisschemas. 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.

Dieser Artikel beschreibt den Einsatz des CloudEvents-Schemas mit Event Grid.

CloudEvents-Schema

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

Eine ausführliche Beschreibung der verfügbaren Felder sowie ihrer Typen und Definitionen finden Sie unter 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".

Für CloudEvents konfigurieren

Sie können Event Grid für die Eingabe und Ausgabe von Ereignissen im CloudEvents-Schema verwenden. In der folgenden Tabelle sind die möglichen Transformationen beschrieben:

Event Grid-Ressource Eingabeschema Schema für Bereitstellung
Systemthemen Event Grid-Schema Event Grid-Schema oder CloudEvents-Schema
Benutzerdefinierte Themen/Domänen Event Grid-Schema Event Grid-Schema oder CloudEvents-Schema
Benutzerdefinierte Themen/Domänen CloudEvents-Schema CloudEvents-Schema
Benutzerdefinierte Themen/Domänen Benutzerdefiniertes Schema Benutzerdefiniertes Schema, Event Grid-Schema oder CloudEvents-Schema
Partnerthemen CloudEvents-Schema CloudEvents-Schema

In allen Ereignisschemas erfordert Event Grid vor dem Veröffentlichen in einem Event Grid-Thema und vor dem Erstellen eines Ereignisabonnements eine Überprüfung.

Weitere Informationen finden Sie unter Event Grid – Sicherheit und Authentifizierung.

Eingabeschema

Das Eingabeschema für ein benutzerdefiniertes Thema wird beim Erstellen des benutzerdefinierten Themas 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 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

Endpunktüberprüfung mit CloudEvents 1.0

Wenn Sie mit Event Grid bereits vertraut sind, kennen Sie wahrscheinlich auch den Handshake zur Überprüfung von Endpunkten, mit dem Missbrauch verhindert werden soll. CloudEvents v1.0 implementiert eine eigene Semantik für den Schutz vor Missbrauch über die HTTP OPTIONS-Methode. Weitere Informationen dazu finden Sie unter HTTP 1.1-Webhooks für die Ereignisbereitstellung – Version 1.0. Wenn Sie das CloudEvents-Schema für die Ausgabe nutzen, verwendet Event Grid anstelle des Event Grid-Mechanismus für Überprüfungsereignisse den Missbrauchschutz von CloudEvents v1.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);
}

Hinweis

Weitere Informationen finden Sie unter Azure Event Grid-Trigger für Azure Functions.

Nächste Schritte