Клиентская библиотека Сетки событий Azure для JavaScript версии 5.10.0

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

Использование клиентской библиотеки для:

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

Ключевые ссылки:

• исходный код
• пакета (NPM)
• Справочная документация по API
• Документация продукта
• Примеры

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

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

• версии 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 README.

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

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

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

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

Эта библиотека поддерживает распределенную трассировку с помощью @azure/core-tracing. При использовании распределенной трассировки эта библиотека создаст диапазон во время операции send. Кроме того, при отправке событий с помощью схемы Cloud Events 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/loger.

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

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

Способствует

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

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

• пакет SDK Microsoft Azure для Javascript