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

아티클
09/25/2024

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 출력 스키마를 사용할 수 없습니다.

입력 스키마	출력 스키마
CloudEvents 형식	CloudEvents 형식
Event Grid 형식	CloudEvents 형식
Event Grid 형식	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 함수를 개발하는 경우 다음 단계를 수행합니다.

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

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

다음 샘플 코드와 같이 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);
}

참고 항목

자세한 내용은 Azure Functions의 Azure Event Grid 트리거를 참조하세요.

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

다음을 통해 공유

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

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

CloudEvents에 대한 구성

입력 스키마

출력 스키마

Azure Functions와 함께 사용

Visual Studio 또는 Visual Studio Code

Azure Portal 개발 환경

피드백

추가 리소스

다음을 통해 공유

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

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

CloudEvents에 대한 구성

입력 스키마

출력 스키마

Azure Functions와 함께 사용

Visual Studio 또는 Visual Studio Code

Azure Portal 개발 환경

관련 콘텐츠

피드백

추가 리소스