Сетка событий Azure клиентская библиотека для JavaScript версии 5.1.0-beta.1

Статья
11/15/2023

Сетка событий Azure — это облачная служба, которая обеспечивает надежную доставку событий в большом масштабе.

Используйте клиентские библиотеки, чтобы:

Отправка событий в Сетку событий с помощью схем Сетки событий, Облачных событий 1.0 или пользовательской схемы
Декодирование и обработка событий, доставленных в обработчик Сетки событий
Создание подписанных URL-адресов для разделов Сетки событий

Основные ссылки:

Начало работы

Поддерживаемые в настоящее время среды

LTS версии Node.js
Последние версии Safari, Chrome, Edge и Firefox.

Чтобы получить дополнительные сведения, ознакомьтесь с нашей политикой поддержки.

Предварительные требования

Подписка Azure.
Существующий раздел или домен Сетки событий . Если вам нужно создать ресурс, можно использовать портал Azure или Azure CLI.

Если вы используете Azure CLI, замените <your-resource-group-name> и <your-resource-name> собственными уникальными именами:

Создайте раздел Сетки событий.

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

создать Домен в Сетке событий;

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

Установите пакет `@azure/eventgrid`.

Установите клиентскую библиотеку Сетка событий Azure для JavaScript с помощью npm:

npm install @azure/eventgrid

Создание и проверка подлинности `EventGridPublisherClient`

Чтобы создать клиентский объект для доступа к API Сетки событий, вам потребуется endpoint раздел Сетки событий и credential. Клиент Сетки событий может использовать ключ доступа или подписанный URL-адрес (SAS), созданный из ключа доступа.

Конечную точку для раздела Сетки событий можно найти на портале Azure или с помощью следующего фрагмента кода Azure CLI :

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

Использование ключа доступа

Используйте портал Azure , чтобы перейти к ресурсу Сетки событий и получить ключ доступа, или используйте приведенный ниже фрагмент кода 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 предоставляет доступ к отправке событий в раздел Сетки событий. В отличие от ключа доступа, который можно использовать до повторного создания, маркер 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")
);

Использование Azure Active Directory (AAD)

Azure EventGrid обеспечивает интеграцию с Azure Active Directory (Azure AD) для проверки подлинности запросов на основе удостоверений. С помощью Azure AD можно использовать управление доступом на основе ролей (RBAC), чтобы предоставить пользователям, группам или приложениям доступ к ресурсам Сетка событий Azure.

Чтобы отправлять события в раздел или домен с TokenCredential, удостоверению, прошедшему проверку подлинности, должна быть назначена роль "Отправитель данных EventGrid".

@azure/identity С помощью пакета можно легко авторизовать запросы как в среде разработки, так и в рабочей среде. Дополнительные сведения об Azure Active Directory см. в файле сведений@azure/identity.

Например, use может использовать 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 используется для отправки событий в раздел Сетки событий или домен Сетки событий.

Схемы событий

Сетка событий поддерживает несколько схем для кодирования событий. При создании пользовательского раздела или домена указывается схема, которая будет использоваться при публикации событий. Хотя вы можете настроить раздел для использования пользовательской схемы , чаще всего используется уже определенная схема Сетки событий или схема CloudEvents 1.0. CloudEvents — это проект Cloud Native Computing Foundation, который создает спецификацию для общего описания данных событий. При создании EventGridPublisherClient необходимо указать, какая схема настроена для использования в разделе:

Если в разделе настроено использование схемы Сетки событий, задайте "EventGrid" в качестве типа схемы:

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

Если в разделе настроено использование схемы облачных событий, задайте "CloudEvent" в качестве типа схемы:

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

Если в разделе настроено использование пользовательской схемы событий, задайте "Custom" в качестве типа схемы:

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

Создание клиента с схемой, отличной от ожидаемой для раздела, приведет к ошибке службы, и ваши события не будут опубликованы.

Чтобы узнать, какая входная схема была настроена для раздела Сетки событий, можно с помощью следующего фрагмента кода Azure CLI :

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

EventGridDeserializer

События, доставляемые потребителям службой "Сетка событий", доставляются в формате JSON. В зависимости от типа доставляемого объекта-получателя служба "Сетка событий" может доставлять одно или несколько событий в составе одной полезной нагрузки. Хотя эти события можно десериализовать с помощью обычных методов JavaScript, таких как JSON.parse, эта библиотека предлагает вспомогательный тип для десериализации событий, называемый EventGridDeserializer.

По сравнению с использованием JSON.parse напрямую выполняет EventGridDeserializer некоторые дополнительные преобразования при десериализации событий:

EventGridDeserializer проверяет наличие обязательных свойств события и правильность их типов.
EventGridDeserializer преобразует свойство времени события в объект JavaScript Date .
При использовании облачных событий двоичные данные могут использоваться для свойства данных события (с помощью Uint8Array). При отправке события через Сетку событий оно кодируется в кодировке Base 64. EventGridDeserializer декодирует эти данные обратно в экземпляр Uint8Array.
При десериализации системного события (события, созданного другой службой Azure) EventGridDeserializer выполняет дополнительные преобразования, data чтобы объект соответствовал соответствующему интерфейсу, описывающего его данные. При использовании TypeScript эти интерфейсы обеспечивают строгую типизацию при доступе к свойствам объекта данных для системного события.

При создании экземпляра можно предоставить пользовательские десериализаторы EventGridDeserializer , которые используются для дальнейшего data преобразования объекта.

Распределенная трассировка и облачные события

Эта библиотека поддерживает распределенную трассировку с помощью @azure/core-tracing. При использовании распределенной трассировки эта библиотека создает диапазон во время send операции. Кроме того, при отправке событий с помощью схемы Облачные события 1.0 пакет SDK добавит метаданные распределенной трассировки к событиям с помощью расширения распределенной трассировки. Значения свойств traceparent расширения и tracestate соответствуют заголовкам traceparent и tracestate из HTTP-запроса, который отправляет события. Если событие уже имеет traceparent свойство расширения, оно не обновляется.

Сетка событий в Kubernetes

Эта библиотека была протестирована и проверена в Kubernetes с помощью Azure Arc.

Примеры

Публикация пользовательского события в разделе Сетки событий с помощью схемы сетки событий

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",
    },
  },
]);

Публикация пользовательского события в разделе в домене Сетки событий с помощью схемы сетки событий

Публикация событий в домене Сетки событий аналогична публикации в разделе Сетки событий, за исключением того, что при использовании схемы Сетки topic событий для событий необходимо включить свойство . При публикации событий в схеме Cloud Events 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 может использоваться для десериализации событий, предоставляемых Сеткой событий. В этом примере у нас есть облачное событие, которое десериализуется с помощью EventGridDeserializer и используется для isSystemEvent определения типа событий.

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. Кроме того, ведение журнала можно включить во время выполнения, вызвав setLogLevel в @azure/logger:

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

setLogLevel("info");

Более подробные инструкции по включению журналов см. в документации по пакету @azure и средства ведения журнала.

Дальнейшие действия

Подробные примеры использования этой библиотеки см. в каталоге примеров .

Участие

Если вы хотите вносить изменения в эту библиотеку, ознакомьтесь с руководством по внесению изменений, в котором содержатся сведения о создании и тестировании кода.

Пакет SDK Microsoft Azure для JavaScript

Просмотры

Поделиться через

Сетка событий Azure клиентская библиотека для JavaScript версии 5.1.0-beta.1

Начало работы

Поддерживаемые в настоящее время среды

Предварительные требования

Создайте раздел Сетки событий.

создать Домен в Сетке событий;

Установите пакет `@azure/eventgrid`.

Создание и проверка подлинности `EventGridPublisherClient`

Использование ключа доступа

Использование маркера SAS

Использование Azure Active Directory (AAD)

Основные понятия

EventGridPublisherClient

Схемы событий

EventGridDeserializer

Распределенная трассировка и облачные события

Сетка событий в Kubernetes

Примеры

Публикация пользовательского события в разделе Сетки событий с помощью схемы сетки событий

Публикация пользовательского события в разделе в домене Сетки событий с помощью схемы сетки событий

Десериализация события

Устранение неполадок

Ведение журнала

Дальнейшие действия

Участие

Дополнительные ресурсы

Поделиться через

Сетка событий Azure клиентская библиотека для JavaScript версии 5.1.0-beta.1

Начало работы

Поддерживаемые в настоящее время среды

Предварительные требования

Создайте раздел Сетки событий.

создать Домен в Сетке событий;

Установите пакет @azure/eventgrid.

Создание и проверка подлинности EventGridPublisherClient

Использование ключа доступа

Использование маркера SAS

Использование Azure Active Directory (AAD)

Основные понятия

EventGridPublisherClient

Схемы событий

EventGridDeserializer

Распределенная трассировка и облачные события

Сетка событий в Kubernetes

Примеры

Публикация пользовательского события в разделе Сетки событий с помощью схемы сетки событий

Публикация пользовательского события в разделе в домене Сетки событий с помощью схемы сетки событий

Десериализация события

Устранение неполадок

Ведение журнала

Дальнейшие действия

Участие

Связанные проекты

Дополнительные ресурсы

Установите пакет `@azure/eventgrid`.

Создание и проверка подлинности `EventGridPublisherClient`