Menggunakan skema CloudEvents v1.0 dengan Azure Event Grid

  • Artikel

Selain skema peristiwa defaultnya, Azure Event Grid secara asli mendukung peristiwa dalam implementasi JSON CloudEvents v1.0 dan pengikatan protokol HTTP. CloudEvents adalah spesifikasi terbuka untuk menjelaskan data peristiwa.

CloudEvents menyederhanakan interoperabilitas dengan menyediakan skema peristiwa umum untuk menerbitkan dan mengonsumsi peristiwa berbasis awan. Skema ini memungkinkan perkakas seragam, cara standar perutean dan penanganan peristiwa, dan cara universal untuk mendeserialisasi skema kejadian luar. Dengan skema umum, Anda dapat lebih mudah mengintegrasikan pekerjaan di seluruh platform.

CloudEvents sedang dibangun oleh beberapa kolaborator, termasuk Microsoft, melalui Cloud Native Computing Foundation. Saat ini tersedia sebagai versi 1.0.

Artikel ini menjelaskan cara menggunakan skema CloudEvents dengan Event Grid.

Skema CloudEvent

Berikut ini contoh kejadian Azure Blob Storage dalam format 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"
        }
    }
}

Untuk deskripsi terperinci tentang bidang yang tersedia, tipe, dan definisinya, lihat CloudEvents v1.0.

Nilai header untuk kejadian yang dikirimkan dalam skema CloudEvents dan skema Azure Event Grid sama kecuali untuk content-type. Untuk skema CloudEvents, nilai header tersebut adalah "content-type":"application/cloudevents+json; charset=utf-8". Untuk skema Azure Event Grid, nilai header tersebut adalah "content-type":"application/json; charset=utf-8".

Mengonfigurasi untuk CloudEvents

Anda dapat menggunakan Azure Event Grid untuk input dan output peristiwa dalam skema CloudEvents. Tabel berikut ini menjelaskan kemungkinan transformasi:

Sumber daya Azure Event Grid Skema input Skema pengiriman
Topik sistem Skema Azure Event Grid Skema Azure Event Grid atau skema CloudEvents
Topik/domain kustom Skema Azure Event Grid Skema Azure Event Grid atau skema CloudEvents
Topik/domain kustom Skema CloudEvents Skema CloudEvents
Topik/domain kustom Skema kustom Skema kustom, skema Event Grid, atau skema CloudEvents
Topik mitra Skema CloudEvents Skema CloudEvents

Untuk semua skema kejadian, Event Grid memerlukan validasi saat Anda menerbitkan ke topik Event Grid dan saat Anda membuat langganan kejadian.

Untuk mengetahui informasi selengkapnya, lihat Keamanan dan autentikasi Event Grid.

Skema input

Anda mengatur skema input untuk topik kustom saat Anda membuat topik kustom.

Untuk Azure CLI, gunakan:

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

Untuk PowerShell, gunakan:

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

Skema output

Anda mengatur skema output saat membuat langganan kejadian.

Untuk Azure CLI, gunakan:

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

Untuk PowerShell, gunakan:

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

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

Validasi titik akhir dengan CloudEvents v1.0

Jika Anda sudah terbiasa dengan Event Grid, Anda mungkin mengetahui jabat tangan validasi titik akhir untuk mencegah penyalahgunaan. CloudEvents v1.0 mengimplementasikan semantik perlindungan penyalahgunaannya sendiri dengan menggunakan metode HTTP OPTIONS. Untuk membaca selengkapnya tentang hal itu, lihat HTTP 1.1 Web Hooks untuk pengiriman kejadian - Versi 1.0. Saat Anda menggunakan skema CloudEvents untuk output, Event Grid menggunakan perlindungan penyalahgunaan CloudEvents v1.0 sebagai menggantikan mekanisme peristiwa validasi Event Grid.

Gunakan dengan Azure Functions

Visual Studio atau Visual Studio Code

Jika Anda menggunakan Visual Studio atau Visual Studio Code, dan bahasa pemrograman C# untuk mengembangkan fungsi, pastikan Anda menggunakan paket NuGet Microsoft.Azure.WebJobs.Extensions.EventGrid terbaru (versi 3.3.1 atau lebih tinggi).

Di Visual Studio, gunakan Alat ->NuGet Package Manager ->Package Manager Console, dan jalankan Install-Package perintah (Install-Package Microsoft.Azure.WebJobs.Extensions.EventGrid -Version 3.3.1). Atau, klik kanan proyek di jendela Penjelajah Solusi, dan pilih menu Kelola Paket NuGet untuk menelusuri paket NuGet, dan menginstal atau memperbaruinya ke versi terbaru.

Di Visual Studio Code, perbarui nomor versi untuk paket Microsoft.Azure.WebJobs.Extensions.EventGrid dalam file csproj untuk proyek Azure Functions Anda.

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

Contoh berikut menunjukkan fungsi Azure Functions versi 3.x yang dikembangkan di Visual Studio atau Visual Studio Code. Ini menggunakan CloudEvent parameter pengikatan dan 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);
        }
    }
}

pengalaman pengembangan portal Azure

Jika Anda menggunakan portal Azure untuk mengembangkan fungsi Azure, ikuti langkah-langkah berikut:

  1. Perbarui nama parameter dalam function.json file ke cloudEvent.

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

  2. Perbarui file seperti yang run.csx ditunjukkan dalam kode sampel berikut.

    #r "Azure.Core"

using Azure.Messaging;

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

Catatan

Untuk informasi selengkapnya, lihat Pemicu Azure Event Grid untuk Azure Functions.

Langkah berikutnya