Condividi tramite

Schema CloudEvents v1.0 con Griglia di eventi di Azure

  • Articolo

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 degli eventi basati sul cloud. Questo schema consente strumenti uniformi, modi standard per il routing e la gestione degli eventi e modi universali per la deserializzazione dello 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 l'uso dello schema CloudEvents con Griglia di eventi.

Evento di esempio con lo schema CloudEvents

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

Una descrizione dettagliata dei campi disponibili, dei relativi tipi e delle definizioni in CloudEvents v1.0 è disponibile qui.

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, tale valore intestazione è "content-type":"application/cloudevents+json; charset=utf-8". Per lo schema Griglia di eventi, tale valore intestazione è "content-type":"application/json; charset=utf-8".

Configurazione per CloudEvents

È possibile usare Griglia di eventi sia per l'input che per l'output degli eventi nello schema CloudEvents. È possibile usare CloudEvents per gli eventi di sistema, ad esempio gli eventi di archiviazione BLOB, gli eventi dell'hub IoT e gli eventi personalizzati. Oltre a supportare CloudEvents, Griglia di eventi supporta un formato di eventi di Griglia di eventi proprietario, non estendibile, ma completamente funzionante. La tabella seguente descrive la trasformazione supportata quando si usano i formati CloudEvents e Griglia di eventi come schema di input negli argomenti e come schema di output nelle sottoscrizioni di eventi. Non è possibile usare uno schema di output di Griglia di eventi quando si usa CloudEvents come schema di input perché CloudEvents supporta gli attributi di estensione non supportati dallo schema di Griglia di eventi.

Schema di input Schema di output.
Formato CloudEvents Formato CloudEvents
Formato di Griglia di eventi Formato CloudEvents
Formato di Griglia di eventi Formato di Griglia di eventi

Per tutti gli schemi di eventi, Griglia di eventi richiede la convalida quando si esegue 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 usando il parametro input-schema.

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 usando il parametro event-delivery-schema.

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

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 più recente (versione 3.3.1 o versione successiva).

In Visual Studio usare Strumenti ->Gestione pacchetti NuGet ->Console di Gestione pacchetti ed eseguire il comando Install-Package (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 selezionare il menu Gestisci pacchetti NuGet per cercare il pacchetto NuGet e installarlo o aggiornarlo alla versione più recente.

In Visual Studio Code aggiornare il numero di versione per il pacchetto Microsoft.Azure.WebJobs.Extensions.EventGrid nel file csproj per il progetto di 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 di Funzioni di Azure versione 3.x sviluppata in Visual Studio o Visual Studio Code. Usa un parametro di binding CloudEvent 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);
        }
    }
}

Esperienza di sviluppo nel portale di Azure

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

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

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

  2. Aggiornare il file run.csx 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 di Griglia di eventi di Azure per Funzioni di Azure.

Contenuto correlato

Per informazioni sulla convalida degli endpoint con gli eventi cloud, vedere Convalida degli endpoint con CloudEvents 1.0.