CloudEvents v 1.0-schema gebruiken met Event GridUse CloudEvents v1.0 schema with Event Grid

Naast het standaard schemavan de gebeurtenis, ondersteunt Azure Event grid systeem eigen gebeurtenissen in de JSON-implementatie van CloudEvents v 1.0 en http-protocol binding.In addition to its default event schema, Azure Event Grid natively supports events in the JSON implementation of CloudEvents v1.0 and HTTP protocol binding. CloudEvents is een open specificatie voor het beschrijven van gebeurtenis gegevens.CloudEvents is an open specification for describing event data.

CloudEvents vereenvoudigt interoperabiliteit door een gemeen schappelijk gebeurtenis schema te bieden voor het publiceren en gebruiken van Cloud gebeurtenissen.CloudEvents simplifies interoperability by providing a common event schema for publishing, and consuming cloud based events. Dit schema biedt uniforme hulp middelen, standaard methoden voor route ring & het afhandelen van gebeurtenissen en universele manieren om het buitenste gebeurtenis schema te deserialiseren.This schema allows for uniform tooling, standard ways of routing & handling events, and universal ways of deserializing the outer event schema. Met een gemeen schappelijk schema kunt u gemakkelijker werk op verschillende platforms integreren.With a common schema, you can more easily integrate work across platforms.

CloudEvents wordt gebouwd door verschillende deel nemers, waaronder micro soft, via de systeem eigen Cloud Computing Foundation.CloudEvents is being built by several collaborators, including Microsoft, through the Cloud Native Computing Foundation. Het is momenteel beschikbaar als versie 1,0.It's currently available as version 1.0.

In dit artikel wordt beschreven hoe u het CloudEvents-schema gebruikt met Event Grid.This article describes how to use the CloudEvents schema with Event Grid.

Belangrijk

Het gebruik van deze functie van Azure PowerShell vereist de AzureRM -module geïnstalleerd.Using this Azure feature from PowerShell requires the AzureRM module installed. Dit is een oudere module alleen beschikbaar voor Windows PowerShell 5.1 die nieuwe functies niet meer ontvangt.This is an older module only available for Windows PowerShell 5.1 that no longer receives new features. De Az en AzureRM modules zijn niet compatibel wanneer voor de dezelfde versies van PowerShell is geïnstalleerd.The Az and AzureRM modules are not compatible when installed for the same versions of PowerShell. Als u beide versies moet:If you need both versions:

  1. De Az-module verwijderen vanuit een PowerShell 5.1-sessie.Uninstall the Az module from a PowerShell 5.1 session.
  2. De AzureRM-module installeren vanuit een PowerShell 5.1-sessie.Install the AzureRM module from a PowerShell 5.1 session.
  3. Download en installeer PowerShell Core 6.x of hoger.Download and install PowerShell Core 6.x or later.
  4. Installeer de Az-module in een PowerShell Core-sessie.Install the Az module in a PowerShell Core session.

Preview-functie installerenInstall preview feature

Deze functie is beschikbaar als preview-versie.This feature is in preview. Als u wilt gebruiken, moet u een extensie van de Preview-versie of de module te installeren.To use it, you must install a preview extension or module.

Extensie voor Azure CLI installerenInstall extension for Azure CLI

Voor Azure CLI, moet u de Event Grid-extensie.For Azure CLI, you need the Event Grid extension.

In CloudShell:In CloudShell:

  • Als u de uitbreiding eerder hebt geïnstalleerd, bijgewerkt az extension update -n eventgridIf you've installed the extension previously, update it az extension update -n eventgrid
  • Als u de uitbreiding eerder nog niet hebt geïnstalleerd, installeren az extension add -n eventgridIf you haven't installed the extension previously, install it az extension add -n eventgrid

Voor een lokale installatie:For a local installation:

  1. De Azure CLI installeren.Install the Azure CLI. Zorg ervoor dat u de meest recente versie hebt door te controleren met az --version.Make sure that you have the latest version, by checking with az --version.
  2. Vorige versies van de extensie verwijderen az extension remove -n eventgridUninstall previous versions of the extension az extension remove -n eventgrid
  3. Installeer de eventgrid uitbreiding met az extension add -n eventgridInstall the eventgrid extension with az extension add -n eventgrid

Module voor PowerShell installerenInstall module for PowerShell

Voor PowerShell, moet u de AzureRM.EventGrid module.For PowerShell, you need the AzureRM.EventGrid module.

In CloudShell:In CloudShell:

  • De module installeren Install-Module -Name AzureRM.EventGrid -AllowPrerelease -Force -Repository PSGalleryInstall the module Install-Module -Name AzureRM.EventGrid -AllowPrerelease -Force -Repository PSGallery

Voor een lokale installatie:For a local installation:

  1. Open de PowerShell-console als beheerderOpen PowerShell console as administrator
  2. De module installeren Install-Module -Name AzureRM.EventGrid -AllowPrerelease -Force -Repository PSGalleryInstall the module Install-Module -Name AzureRM.EventGrid -AllowPrerelease -Force -Repository PSGallery

Als de -AllowPrerelease parameter is niet beschikbaar, gebruikt u de volgende stappen uit:If the -AllowPrerelease parameter isn't available, use the following steps:

  1. Voer Install-Module PowerShellGet -Force uit.Run Install-Module PowerShellGet -Force
  2. Voer Update-Module PowerShellGet uit.Run Update-Module PowerShellGet
  3. Sluit de console van PowerShellClose the PowerShell console
  4. Opnieuw opstarten van PowerShell als beheerderRestart PowerShell as administrator
  5. De module installeren Install-Module -Name AzureRM.EventGrid -AllowPrerelease -Force -Repository PSGalleryInstall the module Install-Module -Name AzureRM.EventGrid -AllowPrerelease -Force -Repository PSGallery

CloudEvent-schemaCloudEvent schema

Hier volgt een voor beeld van een Azure Blob Storage-gebeurtenis in de indeling CloudEvents:Here is an example of an Azure Blob Storage event in 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"
        }
    }
}

Hiervindt u een gedetailleerde beschrijving van de beschik bare velden, hun typen en definities in CloudEvents v 1.0.A detailed description of the available fields, their types, and definitions in CloudEvents v1.0 is available here.

De waarden van headers voor gebeurtenissen die in het CloudEvents-schema en het Event Grid schema worden bezorgd, zijn hetzelfde als voor content-type.The headers values for events delivered in the CloudEvents schema and the Event Grid schema are the same except for content-type. Voor het CloudEvents-schema is die header waarde "content-type":"application/cloudevents+json; charset=utf-8".For CloudEvents schema, that header value is "content-type":"application/cloudevents+json; charset=utf-8". Voor Event Grid schema is die header waarde "content-type":"application/json; charset=utf-8".For Event Grid schema, that header value is "content-type":"application/json; charset=utf-8".

Event Grid configureren voor CloudEventsConfigure Event Grid for CloudEvents

U kunt Event Grid gebruiken voor zowel invoer als uitvoer van gebeurtenissen in het CloudEvents-schema.You can use Event Grid for both input and output of events in CloudEvents schema. U kunt CloudEvents gebruiken voor systeem gebeurtenissen, zoals Blob Storage gebeurtenissen en IoT Hub gebeurtenissen, en aangepaste gebeurtenissen.You can use CloudEvents for system events, like Blob Storage events and IoT Hub events, and custom events. Het kan ook deze gebeurtenissen op de achtergrond transformeren.It can also transform those events on the wire back and forth.

Invoer schemaInput schema Uitvoer schemaOutput schema
CloudEvents-indelingCloudEvents format CloudEvents-indelingCloudEvents format
Event Grid indelingEvent Grid format CloudEvents-indelingCloudEvents format
CloudEvents-indelingCloudEvents format Event Grid indelingEvent Grid format
Event Grid indelingEvent Grid format Event Grid indelingEvent Grid format

Voor alle gebeurtenis schema's moet Event Grid worden gevalideerd bij het publiceren naar een event grid-onderwerp en bij het maken van een gebeurtenis abonnement.For all event schemas, Event Grid requires validation when publishing to an event grid topic and when creating an event subscription. Zie voor meer informatie, Event Grid-beveiliging en verificatie.For more information, see Event Grid security and authentication.

Invoer schemaInput schema

Wanneer u het aangepaste onderwerp maakt, stelt u het invoer schema voor een aangepast onderwerp in.You set the input schema for a custom topic when you create the custom topic.

Gebruik voor Azure CLI:For Azure CLI, use:

# If you have not already installed the extension, do it now.
# This extension is required for preview features.
az extension add --name eventgrid

az eventgrid topic create \
  --name <topic_name> \
  -l westcentralus \
  -g gridResourceGroup \
  --input-schema cloudeventschemav1_0

Gebruik voor PowerShell:For PowerShell, use:

# If you have not already installed the module, do it now.
# This module is required for preview features.
Install-Module -Name AzureRM.EventGrid -AllowPrerelease -Force -Repository PSGallery

New-AzureRmEventGridTopic `
  -ResourceGroupName gridResourceGroup `
  -Location westcentralus `
  -Name <topic_name> `
  -InputSchema CloudEventSchemaV1_0

De huidige versie van CloudEvents biedt geen ondersteuning voor batch verwerking van gebeurtenissen.The current version of CloudEvents doesn't support batching of events. Als u gebeurtenissen met een CloudEvent-schema naar een onderwerp wilt publiceren, moet u elke gebeurtenis afzonderlijk publiceren.To publish events with CloudEvent schema to a topic, publish each event individually.

Uitvoer schemaOutput schema

U stelt het uitvoer schema in wanneer u het gebeurtenis abonnement maakt.You set the output schema when you create the event subscription.

Gebruik voor Azure CLI:For Azure CLI, use:

topicID=$(az eventgrid topic show --name <topic-name> -g gridResourceGroup --query id --output tsv)

az eventgrid event-subscription create \
  --name <event_subscription_name> \
  --source-resource-id $topicID \
  --endpoint <endpoint_URL> \
  --event-delivery-schema cloudeventschemav1_0

Gebruik voor PowerShell:For PowerShell, use:

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

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

Op dit moment kunt u geen Event Grid trigger gebruiken voor een Azure Functions-app wanneer de gebeurtenis wordt bezorgd in het CloudEvents-schema.Currently, you can't use an Event Grid trigger for an Azure Functions app when the event is delivered in the CloudEvents schema. Gebruik een HTTP-trigger.Use an HTTP trigger. Zie using CloudEvents with Azure functions(Engelstalig) voor voor beelden van het implementeren van een http-trigger die gebeurtenissen ontvangt in het CloudEvents-schema.For examples of implementing an HTTP trigger that receives events in the CloudEvents schema, see Using CloudEvents with Azure Functions.

Eindpunt validatie met CloudEvents v 1.0Endpoint Validation with CloudEvents v1.0

Als u al bekend bent met Event Grid, is het mogelijk dat u op de hoogte bent van de verificatie-handshake van het Event Grid om misbruik te voor komen.If you are already familiar with Event Grid, you may be aware of Event Grid's endpoint validation handshake for preventing abuse. CloudEvents v 1.0 implementeert zijn eigen beveiligings semantiek met behulp van de http-opties methode.CloudEvents v1.0 implements its own abuse protection semantics using the HTTP OPTIONS method. Hier vindt u meer informatie.You can read more about it here. Wanneer u het CloudEvents-schema voor uitvoer gebruikt, wordt Event Grid gebruikt met de CloudEvents v 1.0-beschermings beveiliging in plaats van het Event Grid validatie gebeurtenis mechanisme.When using the CloudEvents schema for output, Event Grid uses with the CloudEvents v1.0 abuse protection in place of the Event Grid validation event mechanism.

Gebruiken met Azure FunctionsUse with Azure Functions

De Azure Functions Event grid-binding biedt geen systeem eigen ondersteuning voor CloudEvents, dus de http-geactiveerde functies worden gebruikt voor het lezen van CloudEvents-berichten.The Azure Functions Event Grid binding does not natively support CloudEvents, so HTTP-triggered functions are used to read CloudEvents messages. Wanneer u een HTTP-trigger gebruikt om CloudEvents te lezen, moet u code schrijven voor wat de Event Grid trigger automatisch doet:When using an HTTP trigger to read CloudEvents, you have to write code for what the Event Grid trigger does automatically:

  • Hiermee verzendt u een validatie antwoord naar een validatie aanvraagvoor het abonnement.Sends a validation response to a subscription validation request.
  • Hiermee wordt de functie aangeroepen per element van de gebeurtenis matrix die is opgenomen in de hoofd tekst van de aanvraag.Invokes the function once per element of the event array contained in the request body.

Voor informatie over de URL die moet worden gebruikt om de functie lokaal aan te roepen of wanneer deze wordt uitgevoerd in azure, raadpleegt u de referentie documentatie voor http-trigger bindingenFor information about the URL to use for invoking the function locally or when it runs in Azure, see the HTTP trigger binding reference documentation

Met de volgende C# voorbeeld code voor een http-trigger wordt Event grid trigger gedrag gesimuleerd.The following sample C# code for an HTTP trigger simulates Event Grid trigger behavior. Gebruik dit voor beeld voor gebeurtenissen die in het CloudEvents-schema worden bezorgd.Use this example for events delivered in the CloudEvents schema.

[FunctionName("HttpTrigger")]
public static async Task<HttpResponseMessage> Run([HttpTrigger(AuthorizationLevel.Anonymous, "get", "post", Route = null)]HttpRequestMessage req, ILogger log)
{
    log.LogInformation("C# HTTP trigger function processed a request.");

    var requestmessage = await req.Content.ReadAsStringAsync();
    var message = JToken.Parse(requestmessage);

    if (message.Type == JTokenType.Array)
    {
        // If the request is for subscription validation, send back the validation code.
        if (string.Equals((string)message[0]["eventType"],
        "Microsoft.EventGrid.SubscriptionValidationEvent",
        System.StringComparison.OrdinalIgnoreCase))
        {
            log.LogInformation("Validate request received");
            return req.CreateResponse<object>(new
            {
                validationResponse = message[0]["data"]["validationCode"]
            });
        }
    }
    else
    {
        // The request is not for subscription validation, so it's for an event.
        // CloudEvents schema delivers one event at a time.
        log.LogInformation($"Source: {message["source"]}");
        log.LogInformation($"Time: {message["eventTime"]}");
        log.LogInformation($"Event data: {message["data"].ToString()}");
    }

    return req.CreateResponse(HttpStatusCode.OK);
}

Met de volgende Java script-voorbeeld code voor een HTTP-trigger wordt Event Grid trigger gedrag gesimuleerd.The following sample JavaScript code for an HTTP trigger simulates Event Grid trigger behavior. Gebruik dit voor beeld voor gebeurtenissen die in het CloudEvents-schema worden bezorgd.Use this example for events delivered in the CloudEvents schema.

module.exports = function (context, req) {
    context.log('JavaScript HTTP trigger function processed a request.');

    var message = req.body;
    // If the request is for subscription validation, send back the validation code.
    if (message.length > 0 && message[0].eventType == "Microsoft.EventGrid.SubscriptionValidationEvent") {
        context.log('Validate request received');
        var code = message[0].data.validationCode;
        context.res = { status: 200, body: { "ValidationResponse": code } };
    }
    else {
        // The request is not for subscription validation, so it's for an event.
        // CloudEvents schema delivers one event at a time.
        var event = JSON.parse(message);
        context.log('Source: ' + event.source);
        context.log('Time: ' + event.eventTime);
        context.log('Data: ' + JSON.stringify(event.data));
    }
    context.done();
};

Volgende stappenNext steps