Share via

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

  • Статья

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

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

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

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

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

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

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

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

Если вы используете 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.

Например, можно использовать для 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 преобразует свойство времени события в объект JavaScript Date .
  3. При использовании облачных событий двоичные данные могут использоваться для свойства данных события (с помощью Uint8Array). При отправке события через Сетку событий оно кодируется в кодировке Base 64. EventGridDeserializerдекодирует эти данные обратно в экземпляр .Uint8Array
  4. При десериализации системного события (события, созданного другой службой Azure), EventGridDeserializer выполняет дополнительные преобразования, data чтобы объект соответствовал соответствующему интерфейсу, описывающего его данные. При использовании 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 и средству ведения журнала.

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

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

Участие

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

Просмотры