JavaScript용 Azure Event Grid 클라이언트 라이브러리 - 버전 5.1.0-beta.1

Azure Event Grid 대규모로 안정적인 이벤트 배달을 제공하는 클라우드 기반 서비스입니다.

클라이언트 라이브러리를 사용하여 다음을 수행할 수 있습니다.

• Event Grid, 클라우드 이벤트 1.0 스키마 또는 사용자 지정 스키마를 사용하여 Event Grid로 이벤트 보내기
• Event Grid 처리기에 전달된 이벤트 디코딩 및 처리
• Event Grid topics 대한 공유 액세스 서명 생성

주요 링크:

• 소스 코드
• 패키지(NPM)
• API 참조 설명서
• 제품 설명서
• 샘플

시작

현재 지원되는 환경

• Node.js의 LTS 버전
• 최신 버전의 Safari, Chrome, Edge, Firefox.

자세한 내용은 지원 정책을 참조하세요.

사전 요구 사항

• Azure 구독.
• 기존 Event Grid 토픽 또는 도메인입니다. 리소스를 만들어야 하는 경우 Azure Portal 또는 Azure CLI를 사용할 수 있습니다.

Azure CLI를 사용하는 경우 및 <your-resource-name> 를 고유한 이름으로 바꿉 <your-resource-group-name> 니다.

Event Grid 토픽 만들기

az eventgrid topic create --location <location> --resource-group <your-resource-group-name> --name <your-resource-name>

Event Grid 도메인 만들기

az eventgrid domain create --location <location> --resource-group <your-resource-group-name> --name <your-resource-name>

@azure/eventgrid 패키지를 설치합니다.

를 사용하여 JavaScript용 Azure Event Grid 클라이언트 라이브러리를 npm설치합니다.

npm install @azure/eventgrid

EventGridPublisherClient 만들기 및 인증

Event Grid API에 액세스하는 클라이언트 개체를 만들려면 Event Grid 토픽 및 credential의 이 필요합니다endpoint. Event Grid 클라이언트는 액세스 키에서 만든 액세스 키 또는 SAS(공유 액세스 서명)를 사용할 수 있습니다.

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

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

액세스 키 사용

Azure Portal을 사용하여 Event Grid 리소스를 찾아 액세스 키를 검색하거나 아래 Azure CLI 코드 조각을 사용합니다.

az eventgrid topic key list --resource-group <your-resource-group-name> --name <your-event-grid-topic-name>

API 키와 엔드포인트가 있으면 다음과 같이 클래스를 AzureKeyCredential 사용하여 클라이언트를 인증할 수 있습니다.

const { EventGridPublisherClient, AzureKeyCredential } = require("@azure/eventgrid");

const client = new EventGridPublisherClient(
  "<endpoint>",
  "<endpoint schema>",
  new AzureKeyCredential("<Access Key>")
);

SAS 토큰 사용

액세스 키와 마찬가지로 SAS 토큰을 사용하면 Event Grid 토픽에 이벤트를 보내는 데 액세스할 수 있습니다. 다시 생성될 때까지 사용할 수 있는 액세스 키와 달리 SAS 토큰에는 더 이상 유효하지 않은 분노 시간이 있습니다. 인증에 SAS 토큰을 사용하려면 다음과 같이 를 AzureSASCredential 사용합니다.

const { EventGridPublisherClient, AzureSASCredential } = require("@azure/eventgrid");

const client = new EventGridPublisherClient(
  "<endpoint>",
  "<endpoint schema>",
  new AzureSASCredential("<SAS Token>")
);

함수를 사용하여 SAS 토큰을 생성할 generateSharedAccessSigniture 수 있습니다.

const { generateSharedAccessSignature, AzureKeyCredential } = require("@azure/eventgrid");

// Create a SAS Token which expires on 2020-01-01 at Midnight.
const token = generateSharedAccessSignature(
  "<endpoint>",
  new AzureKeyCredential("<API key>"),
  new Date("2020-01-01T00:00:00")
);

AAD(Azure Active Directory) 사용

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

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

@azure/identity 패키지를 사용하면 개발 및 프로덕션 환경 모두에서 요청에 원활하게 권한을 부여할 수 있습니다. Azure Active Directory에 대한 자세한 내용은 추가 정보를 참조@azure/identity하세요.

예를 들어 를 사용하여 DefaultAzureCredential Azure Active Directory를 사용하여 인증할 클라이언트를 생성할 수 있습니다.

const { EventGridPublisherClient } = require("@azure/eventgrid");
const { DefaultAzureCredential } = require("@azure/identity");

const client = new EventGridPublisherClient(
  "<endpoint>",
  "<endpoint schema>",
  new DefaultAzureCredential()
);

주요 개념

EventGridPublisherClient

EventGridPublisherClient 은 Event Grid 토픽 또는 Event Grid 도메인에 이벤트를 보내는 데 사용됩니다.

이벤트 스키마

Event Grid는 인코딩 이벤트에 대한 여러 스키마를 지원합니다. 사용자 지정 토픽 또는 도메인을 만들 때 이벤트를 게시할 때 사용할 스키마를 지정합니다. 사용자 지정 스키마를 사용하도록 토픽을 구성할 수 있지만 이미 정의된 Event Grid 스키마 또는 CloudEvents 1.0 스키마를 사용하는 것이 더 일반적입니다. CloudEvents 는 일반적인 방식으로 이벤트 데이터를 설명하는 사양을 생성하는 클라우드 네이티브 컴퓨팅 파운데이션 프로젝트입니다. EventGridPublisherClient를 생성할 때 토픽에서 사용하도록 구성된 스키마를 지정해야 합니다.

토픽이 Event Grid 스키마를 사용하도록 구성된 경우 "EventGrid"를 스키마 유형으로 설정합니다.

const client = new EventGridPublisherClient(
  "<endpoint>",
  "EventGrid",
  new AzureKeyCredential("<API Key>")
);

토픽이 클라우드 이벤트 스키마를 사용하도록 구성된 경우 "CloudEvent"를 스키마 유형으로 설정합니다.

const client = new EventGridPublisherClient(
  "<endpoint>",
  "CloudEvent",
  new AzureKeyCredential("<API Key>")
);

토픽이 사용자 지정 이벤트 스키마를 사용하도록 구성된 경우 "사용자 지정"을 스키마 유형으로 설정합니다.

const client = new EventGridPublisherClient(
  "<endpoint>",
  "Custom",
  new AzureKeyCredential("<API Key>")
);

토픽이 예상하도록 구성된 것과 다른 스키마를 사용하여 클라이언트를 생성하면 서비스에서 오류가 발생하며 이벤트가 게시되지 않습니다.

아래 Azure CLI 코드 조각을 사용하여 Event Grid 토픽에 대해 구성된 입력 스키마를 확인할 수 있습니다.

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

EventGridDeserializer

Event Grid에서 소비자에게 전달되는 이벤트는 JSON으로 전달됩니다. 전달되는 소비자 유형에 따라 Event Grid 서비스는 단일 페이로드의 일부로 하나 이상의 이벤트를 제공할 수 있습니다. 이러한 이벤트는 와 같은 JSON.parse일반적인 JavaScript 메서드를 사용하여 역직렬화될 수 있지만 이 라이브러리는 라는 EventGridDeserializer이벤트를 역직렬화하기 위한 도우미 형식을 제공합니다.

를 직접 사용하는 JSON.parse 것과 비교하여 는 EventGridDeserializer 이벤트를 역직렬화하면서 몇 가지 추가 변환을 수행합니다.

1. EventGridDeserializer 는 이벤트의 필수 속성이 있고 올바른 형식임을 확인합니다.
2. EventGridDeserializer 는 이벤트 시간 속성을 JavaScript Date 개체로 변환합니다.
3. 클라우드 이벤트를 사용하는 경우 이진 데이터를 이벤트의 데이터 속성에 사용할 수 있습니다(를 사용하여 Uint8Array). Event Grid를 통해 이벤트를 보내면 Base 64로 인코딩됩니다. EventGridDeserializer는 이 데이터를 의 instance 다시 디코딩합니다Uint8Array.
4. 시스템 이벤트(다른 Azure 서비스에서 생성된 이벤트) EventGridDeserializer 를 역직렬화하는 경우 개체가 해당 데이터를 설명하는 해당 인터페이스와 일치할 수 있도록 data 추가 변환을 수행합니다. TypeScript를 사용할 때 이러한 인터페이스는 시스템 이벤트에 대한 데이터 개체의 속성에 액세스할 때 강력한 입력이 있는지 확인합니다.

의 instance EventGridDeserializer 만들 때 개체를 추가로 변환 data 하는 데 사용되는 사용자 지정 역직렬 변환기를 제공할 수 있습니다.

분산 추적 및 클라우드 이벤트

이 라이브러리는 를 사용하여 분산 추적을 지원합니다 @azure/core-tracing. 분산 추적을 사용하는 경우 이 라이브러리는 작업 중에 범위를 만듭니다 send . 또한 클라우드 이벤트 1.0 스키마를 사용하여 이벤트를 보낼 때 SDK는 분산 추적 확장을 사용하여 이벤트에 분산 추적 메타데이터를 추가합니다. 및 tracestate 확장 속성의 traceparent 값은 이벤트를 보내는 HTTP 요청의 및 tracestate 헤더에 해당 traceparent 합니다. 이벤트에 확장 속성이 이미 있는 traceparent 경우 업데이트되지 않습니다.

Kubernetes의 Event Grid

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

예제

Event Grid 스키마를 사용하여 Event Grid 토픽에 사용자 지정 이벤트 게시

const { EventGridPublisherClient, AzureKeyCredential } = require("@azure/eventgrid");

const client = new EventGridPublisherClient(
  "<endpoint>",
  "EventGrid",
  new AzureKeyCredential("<API key>")
);

await client.send([
  {
    eventType: "Azure.Sdk.SampleEvent",
    subject: "Event Subject",
    dataVersion: "1.0",
    data: {
      hello: "world",
    },
  },
]);

Event Grid 스키마를 사용하여 Event Grid 도메인의 토픽에 사용자 지정 이벤트 게시

Event Grid 도메인에 이벤트를 게시하는 것은 Event Grid 토픽에 게시하는 것과 유사합니다. 단, 이벤트에 Event Grid 스키마를 사용하는 경우 속성을 포함 topic 해야 합니다. 클라우드 이벤트 1.0 스키마에서 이벤트를 게시할 때 필수 source 속성은 게시할 도메인의 토픽 이름으로 사용됩니다.

const { EventGridPublisherClient, AzureKeyCredential } = require("@azure/eventgrid");

const client = new EventGridPublisherClient(
  "<endpoint>",
  "EventGrid",
  new AzureKeyCredential("<API key>")
);

await client.send([
  {
    topic: "my-sample-topic",
    eventType: "Azure.Sdk.SampleEvent",
    subject: "Event Subject",
    dataVersion: "1.0",
    data: {
      hello: "world",
    },
  },
]);

이벤트 역직렬화

EventGridDeserializer 는 Event Grid에서 제공하는 이벤트를 역직렬화하는 데 사용할 수 있습니다. 이 예제에서는 및 isSystemEvent 를 사용하여 EventGridDeserializer 역직렬화된 클라우드 이벤트를 사용하여 이벤트 유형을 검색합니다.

const { EventGridDeserializer, isSystemEvent } = require("@azure/eventgrid");

async function main() {
  const deserializer = new EventGridDeserializer();
  const message = {
    id: "5bc888aa-c2f4-11ea-b3de-0242ac130004",
    source:
      "/subscriptions/<subscriptionid>/resourceGroups/dummy-rg/providers/Microsoft.EventGrid/topics/dummy-topic",
    specversion: "1.0",
    type: "Microsoft.ContainerRegistry.ImagePushed",
    subject: "Test Subject",
    time: "2020-07-10T21:27:12.925Z",
    data: {
      hello: "world",
    },
  };
  const deserializedMessage = await deserializer.deserializeCloudEvents(message);
  console.log(deserializedMessage);

  if (
    deserializedMessage != null &&
    deserializedMessage.length !== 0 &&
    isSystemEvent("Microsoft.ContainerRegistry.ImagePushed", deserializedMessage[0])
  ) {
    console.log("This is a Microsoft.ContainerRegistry.ImagePushed event");
  }
}

main();

문제 해결

로깅

로깅을 사용하도록 설정하면 실패에 대한 유용한 정보를 파악하는 데 도움이 될 수 있습니다. HTTP 요청 및 응답 로그를 보려면 AZURE_LOG_LEVEL 환경 변수를 info로 설정합니다. 또는 @azure/logger에서 setLogLevel을 호출하여 런타임에 로깅을 사용하도록 설정할 수 있습니다.

const { setLogLevel } = require("@azure/logger");

setLogLevel("info");

로그를 사용하도록 설정하는 방법에 대한 자세한 지침은 @azure/로거 패키지 문서를 참조하세요.

다음 단계

이 라이브러리를 사용하는 방법에 대한 자세한 예제는 샘플 디렉터리를 참조하세요.

참여

이 라이브러리에 기여하려면 기여 가이드 를 참조하여 코드를 빌드하고 테스트하는 방법에 대해 자세히 알아보세요.

관련된 프로젝트

• Javascript용 Microsoft Azure SDK