Azure Event Grid를 사용하는 CloudEvents v1.0 스키마

Azure Event Grid는 기본적으로 CloudEvents v1.0의 JSON 구현 및 HTTP 프로토콜 바인딩의 이벤트를 지원합니다. CloudEvents는 이벤트 데이터를 설명하는 공개 사양입니다. CloudEvents는 클라우드 기반 이벤트를 게시 및 사용하기 위한 일반적인 이벤트 스키마를 제공하여 상호 운용성을 간소화합니다. 이 스키마를 통해 균일한 도구, 이벤트를 라우팅 및 처리하는 표준 방법, 외부 이벤트 스키마를 역직렬화하는 유니버설 방법이 가능해집니다. 공통 스키마를 통해 여러 플랫폼에서 작업을 보다 쉽게 통합할 수 있습니다.

CloudEvents는 Cloud Native Computing Foundation을 통해 Microsoft를 포함한 여러 협력자가 작성하고 있습니다. 현재 버전 1.0으로 제공됩니다.

이 문서에서는 Event Grid에서 CloudEvents 스키마를 사용하는 방법에 대해 설명합니다.

CloudEvents 스키마를 사용하는 샘플 이벤트

CloudEvents 형식의 Azure Blob Storage 이벤트의 예는 다음과 같습니다.

{
    "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"
        }
    }
}

CloudEvents v1.0에서 사용 가능한 필드, 해당 유형 및 정의에 대한 자세한 설명은 여기에서 확인할 수 있습니다.

content-type을 제외하고 CloudEvents 스키마 및 Event Grid 스키마에 배달된 이벤트에 대한 헤더 값은 동일합니다. CloudEvents 스키마의 경우 헤더 값은 "content-type":"application/cloudevents+json; charset=utf-8"입니다. Event Grid 스키마의 경우 헤더 값은 "content-type":"application/json; charset=utf-8"입니다.

CloudEvents에 대한 구성

CloudEvents 스키마에서 이벤트의 입출력 둘 다에 Event Grid를 사용할 수 있습니다. Blob Storage 이벤트 및 IoT Hub 이벤트와 같은 시스템 이벤트와 사용자 지정 이벤트에 CloudEvents를 사용할 수 있습니다. CloudEvents를 지원하는 것 외에도 Event Grid는 독점적이고, 확장이 불가능하지만 완벽하게 작동하는 Event Grid 이벤트 형식을 지원합니다. 다음 표에서는 CloudEvents 및 Event Grid 형식을 토픽의 입력 스키마로 사용하고 이벤트 구독에서 출력 스키마로 사용할 때 지원되는 변환에 대해 설명합니다. CloudEvents는 Event Grid 스키마에서 지원되지 않는 확장 특성을 지원하므로 CloudEvents를 입력 스키마로 사용할 때는 Event Grid 출력 스키마를 사용할 수 없습니다.

모든 이벤트 스키마에 대해, Event Grid는 Event Grid 토픽에 게시할 때와 이벤트 구독을 만들 때 유효성 검사를 요구합니다. 자세한 내용은 Event Grid 보안 및 인증을 참조하세요.

입력 스키마

input-schema 매개 변수를 사용하여 사용자 지정 토픽을 만들 때 해당 사용자 지정 토픽의 입력 스키마를 설정합니다.

Azure CLI의 경우 다음을 사용합니다.

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

PowerShell의 경우 다음을 사용합니다.

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

출력 스키마

event-delivery-schema 매개 변수를 사용하여 이벤트 구독을 만들 때 출력 스키마를 설정합니다.

Azure CLI의 경우 다음을 사용합니다.

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

PowerShell의 경우 다음을 사용합니다.

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

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

Azure Functions와 함께 사용

Visual Studio 또는 Visual Studio Code

Visual Studio 또는 Visual Studio Code 및 C# 프로그래밍 언어를 사용하여 함수를 개발하는 경우 최신 Microsoft.Azure.WebJobs.Extensions.EventGrid NuGet 패키지(버전 3.3.1 이상)를 사용하고 있는지 확인합니다.

Visual Studio에서 도구 ->NuGet 패키지 관리자 ->패키지 관리자 콘솔을 사용하고 Install-Package 명령(Install-Package Microsoft.Azure.WebJobs.Extensions.EventGrid -Version 3.3.1)을 실행합니다. 또는 솔루션 탐색기 창에서 프로젝트를 마우스 오른쪽 단추로 클릭하고 NuGet 패키지 관리 메뉴를 선택하여 NuGet 패키지를 찾은 후 설치하거나 최신 버전으로 업데이트합니다.

VS Code에서 Azure Functions 프로젝트의 csproj 파일에서 Microsoft.Azure.WebJobs.Extensions.EventGrid 패키지의 버전 번호를 업데이트합니다.

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

다음 예제에서는 Visual Studio 또는 Visual Studio Code에서 개발된 Azure Functions 버전 3.x 함수를 보여 줍니다. CloudEvent 바인딩 매개 변수 및 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);
        }
    }
}

Azure Portal 개발 환경

Azure Portal을 사용하여 Azure 함수를 개발하는 경우 다음 단계를 수행합니다.

1. function.json 파일에서 매개 변수 이름을 cloudEvent로 업데이트합니다.

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

2. 다음 샘플 코드와 같이 run.csx 파일을 업데이트합니다.

   #r "Azure.Core"
   
   using Azure.Messaging;
   
   public static void Run(CloudEvent cloudEvent, ILogger logger)
   {
       logger.LogInformation("Event received {type} {subject}", cloudEvent.Type, cloudEvent.Subject);
   }
   

관련 콘텐츠

Cloud Events를 사용한 엔드포인트 유효성 검사에 대한 자세한 내용은 CloudEvents 1.0을 사용한 엔드포인트 유효성 검사를 참조하세요.