CloudEvents v1.0-schema gebruiken met Event Grid

  • Artikel

Naast het standaard gebeurtenisschema biedt Azure Event Grid systeemeigen ondersteuning voor gebeurtenissen in de JSON-implementatie van CloudEvents v1.0 en HTTP-protocolbinding. CloudEvents is een open specificatie voor het beschrijven van gebeurtenisgegevens.

CloudEvents vereenvoudigt de interoperabiliteit door een gemeenschappelijk gebeurtenisschema te bieden voor het publiceren en gebruiken van cloudgebeurtenissen. Dit schema biedt uniforme tooling, standaard manieren om gebeurtenissen te routeren en te verwerken, en universele manieren om het buitenste gebeurtenisschema te deserialiseren. Met een gemeenschappelijk schema kunt u eenvoudiger werk op verschillende platforms integreren.

CloudEvents wordt gebouwd door verschillende medewerkers, waaronder Microsoft, via de Cloud Native Computing Foundation. Het is momenteel beschikbaar als versie 1.0.

In dit artikel wordt beschreven hoe u het CloudEvents-schema gebruikt met Event Grid.

CloudEvent-schema

Hier volgt een voorbeeld van een Azure Blob Storage-gebeurtenis in CloudEvents-indeling:

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

Zie CloudEvents v1.0 voor een gedetailleerde beschrijving van de beschikbare velden, hun typen en definities.

De headerwaarden voor gebeurtenissen die worden geleverd in het CloudEvents-schema en het Event Grid-schema zijn hetzelfde, met uitzondering van content-type. Voor het CloudEvents-schema is "content-type":"application/cloudevents+json; charset=utf-8"die headerwaarde . Voor het Event Grid-schema is "content-type":"application/json; charset=utf-8"die headerwaarde .

Configureren voor CloudEvents

U kunt Event Grid gebruiken voor zowel invoer als uitvoer van gebeurtenissen in het CloudEvents-schema. In de volgende tabel worden de mogelijke transformaties beschreven:

Event Grid-resource Invoerschema Leveringsschema
Systeemonderwerpen Event Grid-schema Event Grid-schema of CloudEvents-schema
Aangepaste onderwerpen/domeinen Event Grid-schema Event Grid-schema of CloudEvents-schema
Aangepaste onderwerpen/domeinen CloudEvents-schema CloudEvents-schema
Aangepaste onderwerpen/domeinen Aangepast schema Aangepast schema, Event Grid-schema of CloudEvents-schema
Partneronderwerpen CloudEvents-schema CloudEvents-schema

Voor alle gebeurtenisschema's vereist Event Grid validatie wanneer u publiceert naar een Event Grid-onderwerp en wanneer u een gebeurtenisabonnement maakt.

Zie Event Grid-beveiliging en -verificatie voor meer informatie.

Invoerschema

U stelt het invoerschema voor een aangepast onderwerp in wanneer u het aangepaste onderwerp maakt.

Gebruik voor de Azure CLI het volgende:

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

Gebruik voor PowerShell:

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

Uitvoerschema

U stelt het uitvoerschema in wanneer u het gebeurtenisabonnement maakt.

Gebruik voor de Azure CLI het volgende:

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

Gebruik voor PowerShell:

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

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

Eindpuntvalidatie met CloudEvents v1.0

Als u al bekend bent met Event Grid, bent u mogelijk op de hoogte van de eindpuntvalidatiehanddruk voor het voorkomen van misbruik. CloudEvents v1.0 implementeert zijn eigen semantiek voor misbruikbeveiliging met behulp van de METHODE HTTP OPTIONS. Zie HTTP 1.1 Web Hooks voor gebeurtenislevering - versie 1.0 voor meer informatie hierover. Wanneer u het CloudEvents-schema voor uitvoer gebruikt, maakt Event Grid gebruik van cloudevents v1.0 misbruikbeveiliging in plaats van het Event Grid-validatiemechanisme.

Gebruiken met Azure Functions

Visual Studio of Visual Studio Code

Als u Visual Studio of Visual Studio Code en de C#-programmeertaal gebruikt om functies te ontwikkelen, moet u ervoor zorgen dat u het nieuwste Microsoft.Azure.WebJobs.Extensions.EventGrid NuGet-pakket (versie 3.3.1 of hoger) gebruikt.

Gebruik in Visual Studio de Tools ->NuGet Pakketbeheer ->Pakketbeheer Console en voer de Install-Package opdracht (Install-Package Microsoft.Azure.WebJobs.Extensions.EventGrid -Version 3.3.1). U kunt ook met de rechtermuisknop op het project klikken in het venster Solution Explorer en het menu NuGet-pakketten beheren selecteren om naar het NuGet-pakket te bladeren en het te installeren of bij te werken naar de nieuwste versie.

Werk in VS Code het versienummer voor het pakket Microsoft.Azure.WebJobs.Extensions.EventGrid bij in het csproj-bestand voor uw Azure Functions-project.

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

In het volgende voorbeeld ziet u een Azure Functions-functie versie 3.x die is ontwikkeld in Visual Studio of Visual Studio Code. Het maakt gebruik van een CloudEvent bindingsparameter en 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);
        }
    }
}

Ontwikkelervaring in Azure Portal

Als u Azure Portal gebruikt om een Azure-functie te ontwikkelen, voert u de volgende stappen uit:

  1. Werk de naam van de parameter in function.json het bestand bij naar cloudEvent.

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

  2. Werk het run.csx bestand bij zoals wordt weergegeven in de volgende voorbeeldcode.

    #r "Azure.Core"

using Azure.Messaging;

public static void Run(CloudEvent cloudEvent, ILogger logger)
{
    logger.LogInformation("Event received {type} {subject}", cloudEvent.Type, cloudEvent.Subject);
}

Notitie

Zie de Azure Event Grid-trigger voor Azure Functions voor meer informatie.

Volgende stappen