Używanie schematu CloudEvents w wersji 1.0 z usługą Event Grid

  • Artykuł

Oprócz domyślnego schematu zdarzeń Azure Event Grid natywnie obsługuje zdarzenia w implementacji JSON powiązania protokołu CloudEvents w wersji 1.0 i protokołu HTTP. CloudEvents jest otwartą specyfikacją opisującą dane zdarzeń.

Rozwiązanie CloudEvents upraszcza współdziałanie, udostępniając wspólny schemat zdarzeń do publikowania i używania zdarzeń opartych na chmurze. Ten schemat umożliwia jednolite narzędzia, standardowe sposoby routingu i obsługi zdarzeń oraz uniwersalne sposoby deserializacji zewnętrznego schematu zdarzeń. Za pomocą wspólnego schematu można łatwiej zintegrować pracę między platformami.

Rozwiązanie CloudEvents jest tworzone przez kilku współpracowników, w tym firmę Microsoft, za pośrednictwem cloud Native Computing Foundation. Jest ona obecnie dostępna jako wersja 1.0.

W tym artykule opisano sposób używania schematu CloudEvents z usługą Event Grid.

Schemat CloudEvent

Oto przykład zdarzenia Azure Blob Storage w formacie 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"
        }
    }
}

Aby uzyskać szczegółowy opis dostępnych pól, ich typów i definicji, zobacz CloudEvents v1.0.

Wartości nagłówków dla zdarzeń dostarczonych w schemacie CloudEvents i schematu usługi Event Grid są takie same z wyjątkiem content-type. Dla schematu CloudEvents ta wartość nagłówka to "content-type":"application/cloudevents+json; charset=utf-8". Dla schematu usługi Event Grid ta wartość nagłówka to "content-type":"application/json; charset=utf-8".

Konfigurowanie dla usługi CloudEvents

Usługę Event Grid można używać zarówno do danych wejściowych, jak i wyjściowych zdarzeń w schemacie CloudEvents. W poniższej tabeli opisano możliwe przekształcenia:

Zasób usługi Event Grid Schemat wejściowy Schemat dostarczania
Tematy systemowe Schemat usługi Event Grid Schemat usługi Event Grid lub schemat CloudEvents
Tematy niestandardowe/domeny Schemat usługi Event Grid Schemat usługi Event Grid lub schemat CloudEvents
Tematy niestandardowe/domeny Schemat CloudEvents Schemat CloudEvents
Tematy niestandardowe/domeny Schemat niestandardowy Schemat niestandardowy, schemat usługi Event Grid lub schemat CloudEvents
Tematy partnerów Schemat CloudEvents Schemat CloudEvents

W przypadku wszystkich schematów zdarzeń usługa Event Grid wymaga weryfikacji podczas publikowania w temacie usługi Event Grid i podczas tworzenia subskrypcji zdarzeń.

Aby uzyskać więcej informacji, zobacz Zabezpieczenia i uwierzytelnianie usługi Event Grid.

Schemat wejściowy

Podczas tworzenia tematu niestandardowego należy ustawić schemat wejściowy dla tematu niestandardowego.

W przypadku interfejsu wiersza polecenia platformy Azure użyj:

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

W przypadku programu PowerShell użyj polecenia:

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

Schemat danych wyjściowych

Podczas tworzenia subskrypcji zdarzeń należy ustawić schemat wyjściowy.

W przypadku interfejsu wiersza polecenia platformy Azure użyj:

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

W przypadku programu PowerShell użyj polecenia:

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

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

Walidacja punktu końcowego za pomocą rozwiązania CloudEvents w wersji 1.0

Jeśli znasz już usługę Event Grid, być może znasz uzgadnianie poprawności punktu końcowego w celu zapobiegania nadużyciom. Usługa CloudEvents w wersji 1.0 implementuje własne semantyki ochrony przed nadużyciami przy użyciu metody HTTP OPTIONS. Aby dowiedzieć się więcej na ten temat, zobacz Http 1.1 Web Hooks for event delivery — Version 1.0 (Punkty zaczepienia sieci Web HTTP 1.1 na potrzeby dostarczania zdarzeń — wersja 1.0). W przypadku korzystania ze schematu CloudEvents dla danych wyjściowych usługa Event Grid używa ochrony przed nadużyciami usługi CloudEvents w wersji 1.0 zamiast mechanizmu zdarzeń weryfikacji usługi Event Grid.

Używanie z Azure Functions

Visual Studio lub Visual Studio Code

Jeśli używasz programu Visual Studio lub Visual Studio Code i języka programowania C# do opracowywania funkcji, upewnij się, że używasz najnowszej wersji pakietu NuGet Microsoft.Azure.WebJobs.Extensions.EventGrid (wersja 3.2.1 lub nowsza).

W programie Visual Studio użyj polecenia Tools ->NuGet Package Manager ->Package Manager i uruchom Install-Package polecenie (Install-Package Microsoft.Azure.WebJobs.Extensions.EventGrid -Version 3.2.1). Alternatywnie kliknij prawym przyciskiem myszy projekt w oknie Eksplorator rozwiązań, a następnie wybierz polecenie Zarządzaj pakietami NuGet, aby wyszukać pakiet NuGet, a następnie zainstalować lub zaktualizować go do najnowszej wersji.

W programie VS Code zaktualizuj numer wersji pakietu Microsoft.Azure.WebJobs.Extensions.EventGrid w pliku csproj dla projektu Azure Functions.

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net6.0</TargetFramework>
    <AzureFunctionsVersion>v4</AzureFunctionsVersion>
  </PropertyGroup>
  <ItemGroup>
    <PackageReference Include="Microsoft.Azure.WebJobs.Extensions.EventGrid" Version="3.2.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>

W poniższym przykładzie przedstawiono funkcję Azure Functions w wersji 3.x, która została opracowana w programie Visual Studio lub Visual Studio Code. Używa parametru CloudEvent powiązania i 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);
        }
    }
}

środowisko deweloperskie Azure Portal

Jeśli używasz Azure Portal do tworzenia funkcji platformy Azure, wykonaj następujące kroki:

  1. Zaktualizuj nazwę parametru w function.json pliku na cloudEvent.

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

  2. run.csx Zaktualizuj plik, jak pokazano w poniższym przykładowym kodzie.

    #r "Azure.Core"

using Azure.Messaging;

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

Uwaga

Aby uzyskać więcej informacji, zobacz Azure Event Grid trigger for Azure Functions (Wyzwalacz Azure Event Grid dla Azure Functions).

Następne kroki