.NET용 Azure Event Grid 클라이언트 라이브러리 - 버전 4.14.1

  • 아티클

Azure Event Grid를 사용하면 이벤트 기반 아키텍처를 가진 애플리케이션을 쉽게 빌드할 수 있습니다. Event Grid 서비스는 모든 애플리케이션에 대해 모든 원본에서 모든 대상으로 이벤트의 모든 라우팅을 완전히 관리합니다. Azure 서비스 이벤트 및 사용자 지정 이벤트를 서비스에 직접 게시할 수 있습니다. 그러면 이벤트를 필터링하여 기본 제공 처리기 또는 사용자 지정 웹후크와 같은 다양한 받는 사람에게 보낼 수 있습니다. Azure Event Grid 대해 자세히 알아보려면 Event Grid란?

Azure Event Grid 클라이언트 라이브러리를 사용하여 다음을 수행합니다.

시작

패키지 설치

NuGet에서 클라이언트 라이브러리를 설치합니다.

dotnet add package Azure.Messaging.EventGrid

필수 구성 요소

사용자 지정 Event Grid 토픽 또는 도메인이 있는 Azure 구독 및 Azure 리소스 그룹이 있어야 합니다. 이 단계별 자습서에 따라 Event Grid 리소스 공급자를 등록하고 Azure Portal 사용하여 Event Grid topics 만듭니다. Azure CLI를 사용하는 유사한 자습서가 있습니다.

클라이언트 인증

클라이언트 라이브러리가 토픽 또는 도메인과 상호 작용하려면 Event Grid 토픽 및 credential토픽의 액세스 키를 사용하여 만들 수 있는 의 가 필요합니다endpoint.

Azure Portal에서 또는 아래 AzureCLI 코드 조각을 사용하여 Event Grid 토픽에 대한 엔드포인트를 찾을 수 있습니다.

az eventgrid topic show --name <your-resource-name> --resource-group <your-resource-group-name> --query "endpoint"

액세스 키는 포털을 통해서나 아래의 Azure CLI 코드 조각을 사용하여 찾을 수도 있습니다.

az eventgrid topic key list --name <your-resource-name> --resource-group <your-resource-group-name> --query "key1"

토픽 액세스 키를 사용하여 인증

액세스 키 및 토픽 엔드포인트가 있으면 다음과 같이 게시자 클라이언트를 만들 수 있습니다.

EventGridPublisherClient client = new EventGridPublisherClient(
    new Uri("<endpoint>"),
    new AzureKeyCredential("<access-key>"));

공유 액세스 서명을 사용하여 인증

또한 Event Grid는 액세스 키를 공유하지 않고 특정 시간까지 만료되는 리소스에 대한 액세스를 제공할 수 있는 공유 액세스 서명으로 인증을 지원합니다. 일반적으로 워크플로는 한 애플리케이션이 SAS 문자열을 생성하고 문자열을 사용하는 다른 애플리케이션에 문자열을 전달하는 것입니다. SAS 생성:

var builder = new EventGridSasBuilder(new Uri(topicEndpoint), DateTimeOffset.Now.AddHours(1));
var keyCredential = new AzureKeyCredential(topicAccessKey);
string sasToken = builder.GenerateSas(keyCredential);

소비자의 관점에서 사용하는 방법은 다음과 같습니다.

var sasCredential = new AzureSasCredential(sasToken);
EventGridPublisherClient client = new EventGridPublisherClient(
    new Uri(topicEndpoint),
    sasCredential);

EventGridPublisherClient 은 을 통해 EventGridPublisherClientOptions옵션 구성 집합도 허용합니다. 예를 들어 이벤트 데이터를 JSON으로 직렬화하는 데 사용할 사용자 지정 직렬 변환기를 지정할 수 있습니다.

Azure Active Directory를 사용하여 인증

Azure Event Grid 요청의 ID 기반 인증을 위해 Azure AD(Azure Active Directory)와 통합됩니다. Azure AD 사용하여 RBAC(역할 기반 액세스 제어)를 사용하여 사용자, 그룹 또는 애플리케이션에 Azure Event Grid 리소스에 대한 액세스 권한을 부여할 수 있습니다. Azure ID 라이브러리는 인증을 위한 간편한 Azure Active Directory 지원을 제공합니다.

Azure Active Directory를 사용하여 토픽 또는 도메인에 이벤트를 보내려면 인증된 ID에 "EventGrid 데이터 보낸 사람" 역할이 할당되어야 합니다.

EventGridPublisherClient client = new EventGridPublisherClient(
    new Uri(topicEndpoint),
    new DefaultAzureCredential());

주요 개념

일반적인 Event Grid 개념에 대한 자세한 내용은 Azure Event Grid 개념입니다.

EventGridPublisherClient

게시자가 Event Grid 서비스에 이벤트를 보냅니다. Microsoft는 여러 가지 Azure 서비스에 대한 이벤트를 게시합니다. 를 사용하여 자체 애플리케이션에서 이벤트를 게시할 EventGridPublisherClient수 있습니다.

이벤트 스키마

이벤트는 시스템에서 발생한 일을 완전히 설명하는 가장 적은 양의 정보입니다. Event Grid는 이벤트를 인코딩하기 위해 여러 스키마를 지원합니다. 사용자 지정 토픽 또는 도메인을 만들 때 이벤트를 게시할 때 사용할 스키마를 지정합니다.

Event Grid 스키마

사용자 지정 스키마를 사용하도록 토픽을 구성할 수 있지만 이미 정의된 Event Grid 스키마를 사용하는 것이 더 일반적입니다. 여기에서 사양 및 요구 사항을 참조 하세요.

CloudEvents v1.0 스키마

또 다른 옵션은 CloudEvents v1.0 스키마를 사용하는 것입니다. CloudEvents 는 일반적인 방식으로 이벤트 데이터를 설명하는 사양을 생성하는 클라우드 네이티브 컴퓨팅 파운데이션 프로젝트입니다. CloudEvents의 서비스 요약은 여기에서 찾을 수 있습니다.

토픽 또는 도메인이 사용하도록 EventGridPublisherClient 구성된 스키마에 관계없이 이벤트를 게시하는 데 사용됩니다. 게시에 SendEvents 또는 SendEventsAsync 메서드를 사용합니다.

이벤트 전달

Event Grid에서 소비자에게 전달되는 이벤트는 JSON으로 전달됩니다. 전달되는 소비자 유형에 따라 Event Grid 서비스는 단일 페이로드의 일부로 하나 이상의 이벤트를 제공할 수 있습니다. 이벤트 처리는 이벤트가 전달된 스키마에 따라 달라집니다. 그러나 일반 패턴은 동일하게 유지됩니다.

  • JSON에서 개별 이벤트로 이벤트를 구문 분석합니다. 이벤트 스키마(Event Grid 또는 CloudEvents)에 따라 이제 봉투의 이벤트에 대한 기본 정보(이벤트 시간 및 형식과 같은 모든 이벤트에 대해 존재하는 속성)에 액세스할 수 있습니다.
  • 이벤트 데이터를 역직렬화합니다. 또는 CloudEvent가 EventGridEvent 지정된 경우 사용자는 특정 형식으로 역직렬화하여 이벤트 페이로드 또는 데이터에 액세스하려고 시도할 수 있습니다. 이 시점에서 사용자 지정 serializer를 제공하여 데이터를 올바르게 디코딩할 수 있습니다.

스레드로부터의 안전성

모든 클라이언트 instance 메서드는 스레드로부터 안전하고 서로 독립적임을 보장합니다(지침). 이렇게 하면 스레드 간에 클라이언트 인스턴스를 다시 사용하는 것이 항상 안전합니다.

추가 개념

클라이언트 옵션 | 응답 | 에 액세스 장기 실행 작업 | 오류 | 처리 진단 | 조롱 | 클라이언트 수명

예제

Event Grid 토픽에 Event Grid 이벤트 게시

Event Grid에 이벤트 게시는 를 사용하여 EventGridPublisherClient수행됩니다. 제공된 메서드를 SendEvent/SendEventAsync 사용하여 단일 이벤트를 토픽에 게시합니다.

// Add EventGridEvents to a list to publish to the topic
EventGridEvent egEvent =
    new EventGridEvent(
        "ExampleEventSubject",
        "Example.EventType",
        "1.0",
        "This is the event data");

// Send the event
await client.SendEventAsync(egEvent);

이벤트 일괄 처리를 게시하려면 메서드를 SendEvents/SendEventsAsync 사용합니다.

// Example of a custom ObjectSerializer used to serialize the event payload to JSON
var myCustomDataSerializer = new JsonObjectSerializer(
    new JsonSerializerOptions()
    {
        PropertyNamingPolicy = JsonNamingPolicy.CamelCase
    });

// Add EventGridEvents to a list to publish to the topic
List<EventGridEvent> eventsList = new List<EventGridEvent>
{
    // EventGridEvent with custom model serialized to JSON
    new EventGridEvent(
        "ExampleEventSubject",
        "Example.EventType",
        "1.0",
        new CustomModel() { A = 5, B = true }),

    // EventGridEvent with custom model serialized to JSON using a custom serializer
    new EventGridEvent(
        "ExampleEventSubject",
        "Example.EventType",
        "1.0",
        myCustomDataSerializer.Serialize(new CustomModel() { A = 5, B = true })),
};

// Send the events
await client.SendEventsAsync(eventsList);

Event Grid 토픽에 CloudEvents 게시

Event Grid에 이벤트 게시는 를 사용하여 EventGridPublisherClient수행됩니다. 제공된 메서드를 SendEvents/SendEventsAsync 사용하여 토픽에 이벤트를 게시합니다.

// Example of a custom ObjectSerializer used to serialize the event payload to JSON
var myCustomDataSerializer = new JsonObjectSerializer(
    new JsonSerializerOptions()
    {
        PropertyNamingPolicy = JsonNamingPolicy.CamelCase
    });

// Add CloudEvents to a list to publish to the topic
List<CloudEvent> eventsList = new List<CloudEvent>
{
    // CloudEvent with custom model serialized to JSON
    new CloudEvent(
        "/cloudevents/example/source",
        "Example.EventType",
        new CustomModel() { A = 5, B = true }),

    // CloudEvent with custom model serialized to JSON using a custom serializer
    new CloudEvent(
        "/cloudevents/example/source",
        "Example.EventType",
        myCustomDataSerializer.Serialize(new CustomModel() { A = 5, B = true }),
        "application/json"),

    // CloudEvents also supports sending binary-valued data
    new CloudEvent(
        "/cloudevents/example/binarydata",
        "Example.EventType",
        new BinaryData(Encoding.UTF8.GetBytes("This is treated as binary data")),
        "application/octet-stream")};

// Send the events
await client.SendEventsAsync(eventsList);

Event Grid 도메인에 Event Grid 이벤트 게시

이벤트 도메인은 동일한 애플리케이션과 관련된 많은 수의 Event Grid topics 대한 관리 도구입니다. 수천 개의 개별 토픽을 가질 수 있는 메타 항목으로 생각할 수 있습니다. 이벤트 도메인을 만들면 Event Grid에 토픽을 만들 때와 비슷한 게시 엔드포인트가 제공됩니다.

이벤트 도메인의 모든 토픽에 이벤트를 게시하려면 사용자 지정 토픽과 동일한 방식으로 이벤트를 도메인의 엔드포인트에 푸시합니다. 유일한 차이점은 이벤트를 전달할 토픽을 지정해야 한다는 것입니다.

// Add EventGridEvents to a list to publish to the domain
// Don't forget to specify the topic you want the event to be delivered to!
List<EventGridEvent> eventsList = new List<EventGridEvent>
{
    new EventGridEvent(
        "ExampleEventSubject",
        "Example.EventType",
        "1.0",
        "This is the event data")
    {
        Topic = "MyTopic"
    }
};

// Send the events
await client.SendEventsAsync(eventsList);

CloudEvents를 보내기 위해 CloudEvent 원본은 도메인 토픽으로 사용됩니다.

List<CloudEvent> eventsList = new List<CloudEvent>();

for (int i = 0; i < 10; i++)
{
    CloudEvent cloudEvent = new CloudEvent(
        // the source is mapped to the domain topic
        $"Subject-{i}",
        "Microsoft.MockPublisher.TestEvent",
        "hello")
    {
        Id = $"event-{i}",
        Time = DateTimeOffset.Now
    };
    eventsList.Add(cloudEvent);
}

await client.SendEventsAsync(eventsList);

이벤트 수신 및 역직렬화

이벤트 처리기 역할을 하는 여러 가지 Azure 서비스가 있습니다.

참고: Event Grid 스키마의 이벤트 배달에 웹후크를 사용하는 경우 Event Grid는 해당 엔드포인트에 이벤트 배달을 시작하기 전에 웹후크 엔드포인트의 소유권을 증명해야 합니다. 이벤트 구독을 만들 때 Event Grid는 아래와 같이 구독 유효성 검사 이벤트를 엔드포인트로 보냅니다. 핸드셰이크를 완료하는 방법에 대한 자세한 내용은 Webhook 이벤트 배달을 참조하세요. CloudEvents 스키마의 경우 서비스는 HTTP 옵션 메서드를 사용하여 연결의 유효성을 검사합니다. CloudEvents 유효성 검사에 대해 자세히 알아보세요.

이벤트가 이벤트 처리기에 전달되면 JSON 페이로드를 이벤트 목록으로 역직렬화할 수 있습니다.

EventGridEvent사용:

// Parse the JSON payload into a list of events
EventGridEvent[] egEvents = EventGridEvent.ParseMany(BinaryData.FromStream(httpContent));

CloudEvent사용:

var bytes = await httpContent.ReadAsByteArrayAsync();
// Parse the JSON payload into a list of events
CloudEvent[] cloudEvents = CloudEvent.ParseMany(new BinaryData(bytes));

이벤트 데이터 역직렬화

여기에서 속성을 호출 ToObjectFromJson<T>()Data 하여 특정 형식으로 역직렬화하여 이벤트 데이터에 액세스할 수 있습니다. 올바른 형식 EventType 으로 역직렬화하기 위해 속성(Type CloudEvents의 경우)은 서로 다른 이벤트를 구분하는 데 도움이 됩니다. 사용자 지정 이벤트 데이터는 제네릭 메서드 ToObjectFromJson<T>()를 사용하여 역직렬화해야 합니다. 이벤트 데이터를 역직렬화하는 사용자 지정 ObjectSerializer 을 허용하는 확장 메서드 ToObject<T>() 도 있습니다.

foreach (CloudEvent cloudEvent in cloudEvents)
{
    switch (cloudEvent.Type)
    {
        case "Contoso.Items.ItemReceived":
            // By default, ToObjectFromJson<T> uses System.Text.Json to deserialize the payload
            ContosoItemReceivedEventData itemReceived = cloudEvent.Data.ToObjectFromJson<ContosoItemReceivedEventData>();
            Console.WriteLine(itemReceived.ItemSku);
            break;
        case "MyApp.Models.CustomEventType":
            // One can also specify a custom ObjectSerializer as needed to deserialize the payload correctly
            TestPayload testPayload = cloudEvent.Data.ToObject<TestPayload>(myCustomSerializer);
            Console.WriteLine(testPayload.Name);
            break;
        case SystemEventNames.StorageBlobDeleted:
            // Example for deserializing system events using ToObjectFromJson<T>
            StorageBlobDeletedEventData blobDeleted = cloudEvent.Data.ToObjectFromJson<StorageBlobDeletedEventData>();
            Console.WriteLine(blobDeleted.BlobType);
            break;
    }
}

TryGetSystemEventData()사용:

대부분 시스템 이벤트를 예상하는 경우 패턴 일치를 켜 TryGetSystemEventData() 고 사용하여 개별 이벤트에 대해 작동하는 것이 더 명확할 수 있습니다. 이벤트가 시스템 이벤트가 아닌 경우 메서드는 false를 반환하고 out 매개 변수는 null이 됩니다.

주의할 점은 나중에 서비스 및 SDK에서 시스템 이벤트로 추가되는 EventType 값이 있는 사용자 지정 이벤트 형식을 사용하는 경우 의 TryGetSystemEventData 반환 값이 에서 로 falsetrue변경됩니다. 서비스에서 이미 전송되고 있지만 아직 SDK에 추가되지 않은 이벤트에 대해 사용자 지정 이벤트를 선제적으로 만드는 경우에 발생할 수 있습니다. 이 경우 업그레이드 후 코드 흐름이 자동으로 변경되지 않도록 속성에서 Data 제네릭 ToObjectFromJson<T> 메서드를 사용하는 것이 좋습니다(물론 사용자 지정 모델이 아닌 새로 릴리스된 시스템 이벤트 모델을 사용하도록 코드를 수정할 수도 있음).

foreach (EventGridEvent egEvent in egEvents)
{
    // If the event is a system event, TryGetSystemEventData will return the deserialized system event
    if (egEvent.TryGetSystemEventData(out object systemEvent))
    {
        switch (systemEvent)
        {
            case SubscriptionValidationEventData subscriptionValidated:
                Console.WriteLine(subscriptionValidated.ValidationCode);
                break;
            case StorageBlobCreatedEventData blobCreated:
                Console.WriteLine(blobCreated.BlobType);
                break;
            // Handle any other system event type
            default:
                Console.WriteLine(egEvent.EventType);
                // we can get the raw Json for the event using Data
                Console.WriteLine(egEvent.Data.ToString());
                break;
        }
    }
    else
    {
        switch (egEvent.EventType)
        {
            case "MyApp.Models.CustomEventType":
                TestPayload deserializedEventData = egEvent.Data.ToObjectFromJson<TestPayload>();
                Console.WriteLine(deserializedEventData.Name);
                break;
            // Handle any other custom event type
            default:
                Console.Write(egEvent.EventType);
                Console.WriteLine(egEvent.Data.ToString());
                break;
        }
    }
}

문제 해결

서비스 응답

SendEvents() 는 서비스에서 HTTP 응답 코드를 반환합니다. 는 RequestFailedException 실패한 요청에 대한 서비스 응답으로 throw됩니다. 예외에는 서비스에서 반환된 응답 코드에 대한 정보가 포함됩니다.

이벤트 데이터 역직렬화

  • 이벤트 데이터가 유효한 JSON이 아닌 경우 또는 ParseMany를 호출 Parse 할 때 가 JsonException throw됩니다.
  • 이벤트 스키마가 역직렬화되는 형식(예: EventGridSchema 이벤트에서 호출 CloudEvent.Parse )에 해당하지 않으면 이 ArgumentException throw됩니다.
  • 여러 이벤트를 포함하는 데이터에 대해 가 호출되면 Parse 이 ArgumentException throw됩니다. ParseMany 대신 여기에 사용해야 합니다.

콘솔 로깅 설정

서비스에 대해 수행하는 요청을 더 자세히 알아보려면 쉽게 콘솔 로깅을 사용하도록 설정할 수도 있습니다.

분산 추적

Event Grid 라이브러리는 추적을 기본으로 배포할 수 있습니다. 분산 추적에 대한 CloudEvents 사양 지침을 준수하기 위해 라이브러리는 분산 추적이 사용되는 경우 CloudEvent의 ExtensionAttributes에서 traceparent 및 tracestate를 설정합니다. 애플리케이션에서 분산 추적을 사용하도록 설정하는 방법에 대한 자세한 내용은 Azure SDK 분산 추적 설명서를 참조하세요.

Kubernetes의 Event Grid

이 라이브러리는 Azure Arc를 사용하여 Kubernetes에서 테스트 및 유효성을 검사했습니다.

다음 단계

Event Grid 클라이언트 라이브러리의 일반적인 사용법은 Event Grid 샘플에서 자세히 https://github.com/Azure/azure-sdk-for-net/blob/Azure.Messaging.EventGrid_4.14.1/sdk/eventgrid/Azure.Messaging.EventGrid/samples 확인하세요.

참여

이 프로젝트에 대한 기여와 제안을 환영합니다. 대부분의 경우 기여하려면 권한을 부여하며 실제로 기여를 사용할 권한을 당사에 부여한다고 선언하는 CLA(기여자 라이선스 계약)에 동의해야 합니다. 자세한 내용은 https://cla.microsoft.com.을 방문하세요.

끌어오기 요청을 제출하면 CLA-bot은 CLA를 제공하고 PR을 적절하게 데코레이팅해야 하는지 여부를 자동으로 결정합니다(예: 레이블, 설명). 봇에서 제공하는 지침을 따르기만 하면 됩니다. 이 작업은 CLA를 사용하여 모든 리포지토리에서 한 번만 수행하면 됩니다.

이 프로젝트에는 Microsoft Open Source Code of Conduct(Microsoft 오픈 소스 준수 사항)가 적용됩니다. 자세한 내용은 Code of Conduct FAQ(규정 FAQ)를 참조하세요. 또는 추가 질문이나 의견은 opencode@microsoft.com으로 문의하세요.

Impressions