Usare lo schema CloudEvents v1.0 con Griglia di eventi

Articolo
01/19/2024

Oltre allo schema di eventi predefinito, Griglia di eventi di Azure supporta in modo nativo gli eventi nell'implementazione JSON di CloudEvents v1.0 e nel binding del protocollo HTTP. CloudEvents è una specifica aperta per la descrizione dei dati degli eventi.

CloudEvents semplifica l'interoperabilità fornendo uno schema di eventi comune per la pubblicazione e l'utilizzo di eventi basati sul cloud. Questo schema consente strumenti uniformi, modi standard di routing e gestione degli eventi e modi universali per deserializzare lo schema di eventi esterni. Con uno schema comune, è possibile integrare più facilmente il lavoro tra le piattaforme.

CloudEvents viene compilato da diversi collaboratori, tra cui Microsoft, tramite Cloud Native Computing Foundation. È attualmente disponibile come versione 1.0.

Questo articolo descrive come usare lo schema CloudEvents con Griglia di eventi.

Schema CloudEvent

Di seguito è riportato un esempio di evento Archiviazione BLOB di Azure in formato 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"
        }
    }
}

Per una descrizione dettagliata dei campi disponibili, dei relativi tipi e definizioni, vedere CloudEvents v1.0.

I valori delle intestazioni per gli eventi recapitati nello schema CloudEvents e nello schema Griglia di eventi sono gli stessi, ad eccezione di content-type. Per lo schema CloudEvents, il valore dell'intestazione è "content-type":"application/cloudevents+json; charset=utf-8". Per lo schema di Griglia di eventi, il valore dell'intestazione è "content-type":"application/json; charset=utf-8".

Configurare per CloudEvents

È possibile usare Griglia di eventi sia per l'input che per l'output degli eventi nello schema CloudEvents. Nella tabella seguente vengono descritte le possibili trasformazioni:

Risorsa griglia di eventi	Schema di input	Schema di recapito
Argomenti di sistema	Schema di griglia di eventi	Schema di Griglia di eventi o schema CloudEvents
Argomenti/domini personalizzati	Schema di griglia di eventi	Schema di Griglia di eventi o schema CloudEvents
Argomenti/domini personalizzati	Schema di CloudEvents	Schema di CloudEvents
Argomenti/domini personalizzati	Schema personalizzato	Schema personalizzato, schema di Griglia di eventi o schema CloudEvents
Argomenti partner	Schema di CloudEvents	Schema di CloudEvents

Per tutti gli schemi eventi, Griglia di eventi richiede la convalida durante la pubblicazione in un argomento di Griglia di eventi e quando si crea una sottoscrizione di eventi.

Per altre informazioni, vedere Event Grid security and authentication (Sicurezza e autenticazione di Griglia di eventi).

Schema di input

Si imposta lo schema di input per un argomento personalizzato quando si crea l'argomento personalizzato.

Per l'interfaccia della riga di comando di Azure usare:

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

Per PowerShell, usare:

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

Schema di output.

Si imposta lo schema di output quando si crea la sottoscrizione dell'evento.

Per l'interfaccia della riga di comando di Azure usare:

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

Per PowerShell, usare:

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

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

Convalida degli endpoint con CloudEvents v1.0

Se si ha già familiarità con Griglia di eventi, è possibile conoscere l'handshake di convalida dell'endpoint per prevenire gli abusi. CloudEvents v1.0 implementa la propria semantica di protezione da abusi usando il metodo HTTP OPTIONS. Per altre informazioni, vedere Web Hook HTTP 1.1 per il recapito di eventi - Versione 1.0. Quando si usa lo schema CloudEvents per l'output, Griglia di eventi usa la protezione dagli abusi di CloudEvents v1.0 al posto del meccanismo di eventi di convalida di Griglia di eventi.

Usare CloudEvents con Funzioni di Azure

Visual Studio o Visual Studio Code

Se si usa Visual Studio o Visual Studio Code e il linguaggio di programmazione C# per sviluppare funzioni, assicurarsi di usare il pacchetto NuGet Microsoft.Azure.WebJobs.Extensions.EventGrid (versione 3.3.1 o successiva).

In Visual Studio usare Strumenti ->NuGet Gestione pacchetti ->Gestione pacchetti Console ed eseguire il Install-Package comando ().Install-Package Microsoft.Azure.WebJobs.Extensions.EventGrid -Version 3.3.1 In alternativa, fare clic con il pulsante destro del mouse sul progetto nella finestra Esplora soluzioni e scegliere Gestisci pacchetti NuGet dal menu per cercare il pacchetto NuGet e installarlo o aggiornarlo alla versione più recente.

In VS Code aggiornare il numero di versione per il pacchetto Microsoft.Azure.WebJobs.Extensions.EventGrid nel file csproj per il progetto Funzioni di Azure.

<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'esempio seguente illustra una funzione Funzioni di Azure versione 3.x sviluppata in Visual Studio o Visual Studio Code. Usa un CloudEvent parametro di associazione e 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);
        }
    }
}

portale di Azure esperienza di sviluppo

Se si usa il portale di Azure per sviluppare una funzione di Azure, seguire questa procedura:

Aggiornare il nome del parametro nel function.json file in cloudEvent.

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

Aggiornare il run.csx file come illustrato nel codice di esempio seguente.

#r "Azure.Core"

using Azure.Messaging;

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

Nota

Per altre informazioni, vedere trigger Griglia di eventi di Azure per Funzioni di Azure.

Passaggi successivi

Per informazioni sul monitoraggio dei recapiti degli eventi, vedere Monitorare il recapito dei messaggi di Griglia di eventi di Azure.
Microsoft invita gli utenti a testare, commentare e contribuire a CloudEvents.
Per altre informazioni sulla creazione di una sottoscrizione di Griglia di eventi di Azure, vedere Schema di sottoscrizione per Griglia di eventi.