Клиентская библиотека REST AzureCommunicationRoutingService для JavaScript

Статья
11/22/2023

Служба маршрутизации коммуникаций Azure

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

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

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

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

LTS версии Node.js

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

Для использования этого пакета у вас должна быть подписка Azure .

Иметь ресурс ACS

Создайте ресурс ACS на портале Azure или используйте существующий ресурс.

Установите пакет `@azure-rest/communication-job-router`.

Установите клиентскую библиотеку REST клиента REST AzureCommunicationRoutingService для JavaScript с помощью npm:

npm install @azure-rest/communication-job-router

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

Чтобы использовать учетные данные маркера Azure Active Directory (AAD), укажите экземпляр нужного типа учетных данных, полученных из библиотеки @azure и удостоверений .

Для проверки подлинности с помощью AAD необходимо сначала npm установить @azure/identity

После настройки можно выбрать тип учетных данных для @azure/identity использования. Например, для проверки подлинности клиента можно использовать DefaultAzureCredential .

Задайте значения идентификатора клиента, идентификатора клиента и секрета клиента приложения AAD в качестве переменных среды: AZURE_CLIENT_ID, AZURE_TENANT_ID AZURE_CLIENT_SECRET

Руководство по Маршрутизация заданий в рабочие роли с помощью пакета SDK rest маршрутизатора заданий Службы коммуникации Azure (ACS)

Из этого руководства вы узнаете:

Создание очереди.
Сведения о создании рабочих ролей и их назначении в очередь.
Маршрутизация заданий для рабочих ролей.
Как подписаться на события маршрутизатора заданий и обрабатывать их.
Инструкции по завершению и закрытию заданий.

Запуск сервера NodeJS Express

В оболочке (cmd, PowerShell, Bash и т. д.) создайте папку с именем RouterQuickStart и выполните внутри этой папки .npx express-generator При этом будет создан простой проект Express, который будет прослушивать .port 3000

Пример

mkdir RouterQuickStart
cd RouterQuickStart
npx express-generator
npm install
DEBUG=routerquickstart:* npm start

Установка пакета SDK для маршрутизатора заданий Azure ACS

В папке RouterQuickStart установите пакет SDK для маршрутизатора заданий ACS, выполнив .npm install @azure-rest/communication-job-router --save

Задания маршрутизации

Создание AzureCommunicationRoutingServiceClient

Сначала необходимо создать AzureCommunicationRoutingServiceClient.

const JobRouterClient = require("@azure-rest/communication-job-router").default;

const connectionString = "endpoint=https://<YOUR_ACS>.communication.azure.com/;accesskey=<YOUR_ACCESS_KEY>";
const routerClient = JobRouterClient(connectionString);

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

Эта политика определяет, какие работники будут получать предложения о заданиях по мере распределения заданий из очередей.

const distributionPolicy = await routerClient.path("/routing/distributionPolicies/{id}", "distributionPolicy-1").patch({
  contentType: "application/merge-patch+json",
  body: {
    name: "distribution-policy-123",
    offerExpiresAfterSeconds: 30,
    mode: {
      kind: "longestIdle",
      minConcurrentOffers: 1,
      maxConcurrentOffers: 3,
    },
  }
});

Создание очереди

Эта очередь предлагает задания для рабочих ролей в соответствии с ранее созданной политикой распространения.

const salesQueueId = "queue-123";
await routerClient.path("/routing/queues/{id}", salesQueueId).patch({
  contentType: "application/merge-patch+json",
  body: {
    distributionPolicyId: distributionPolicy.body.id,
    name: "Main",
    labels: {},
  }
});

Создание рабочих ролей

Эти рабочие роли назначаются созданной ранее очереди "Продажи" и имеют некоторые метки.

значение availableForOffers означает true , что эти работники готовы принять предложения о работе.
Дополнительные сведения о метках и селекторах меток см. в документации по меткам.

  // Create worker "Alice".
const workerAliceId = "773accfb-476e-42f9-a202-b211b41a4ea4";
const workerAliceResponse = await routerClient.path("/routing/workers/{workerId}", workerAliceId).patch({
  contentType: "application/merge-patch+json",
  body: {
    capacity: 120,
    queues: [salesQueueId],
    labels: {
      Xbox: 5,
      german: 4,
      name: "Alice"
    },
    channels: [
      {
        channelId: "CustomChatChannel",
        capacityCostPerJob: 10,
      },
      {
        channelId: "CustomVoiceChannel",
        capacityCostPerJob: 100,
      },
    ],
  }
});

// Create worker "Bob".
const workerBobId = "21837c88-6967-4078-86b9-1207821a8392";
const workerBobResponse = await routerClient.path("/routing/workers/{workerId}", workerBobId).patch({
  contentType: "application/merge-patch+json",
  body: {
    capacity: 100,
    queues: [salesQueueId],
    labels: {
      Xbox: 5,
      english: 3,
      name: "Alice"
    },
    channels: [
      {
        channelId: "CustomChatChannel",
        capacityCostPerJob: 10,
      },
      {
        channelId: "CustomVoiceChannel",
        capacityCostPerJob: 100,
      },
    ],
  }
});

Жизненный цикл задания

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

Создание задания

Это задание помещается в очередь ранее созданной очереди "Продажи".

const jobId = "router-job-123";
const result = await routerClient.path("/routing/jobs/{id}", jobId).patch({
  contentType: "application/merge-patch+json",
  body: {
    channelReference: "66e4362e-aad5-4d71-bb51-448672ebf492",
    channelId: "voice",
    priority: 2,
    queueId: "salesQueueId",
    labels: {},
  }
});

(Необязательно) Создание задания с помощью политики классификации

Создание политики классификации

Эта политика классифицирует задания после создания.

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

const classificationPolicyId = "classification-policy-123";
const result = await routerClient.path("/routing/classificationPolicies/{id}", classificationPolicyId).patch({
  contentType: "application/merge-patch+json",
  body: {
    name: "Default Classification Policy",
    fallbackQueueId: salesQueueId,
    queueSelectorAttachments: [
      {
        kind: "static",
        queueSelector: { key: "department", labelOperator: "equal", value: "xbox" }
      },
    ],
    workerSelectorAttachments: [{
      kind: "static",
      workerSelector: { key: "english", labelOperator: "greaterThan", value: 5 }
    }],
    prioritizationRule: {
      kind: "expression",
      language: "powerFx",
      expression: "If(job.department = \"xbox\", 2, 1)"
    }
  }
});

Создание и классификация задания

Это задание будет классифицироваться с помощью ранее созданной политики классификации. Он также имеет метку.

const result = await routerClient.path("/routing/jobs/{id}", jobId).patch({
  contentType: "application/merge-patch+json",
  body: {
    channelReference: "66e4362e-aad5-4d71-bb51-448672ebf492",
    channelId: "voice",
    classificationPolicyId: classificationPolicy.id,
    labels: {
      department: "xbox"
    },
  }
});
``

## Events

Job Router events are delivered via Azure Event Grid. Refer to our [Azure Event Grid documentation](/azure/event-grid/overview) to better understand Azure Event Grid.

In the previous example:

- The job gets enqueued to the “Sales" queue.
- A worker is selected to handle the job, a job offer is issued to that worker, and a `RouterWorkerOfferIssued` event is sent via Azure Event Grid.

Example `RouterWorkerOfferIssued` JSON shape:

```json
{
  "id": "1027db4a-17fe-4a7f-ae67-276c3120a29f",
  "topic": "/subscriptions/{subscription-id}/resourceGroups/{group-name}/providers/Microsoft.Communication/communicationServices/{communication-services-resource-name}",
  "subject": "worker/{worker-id}/job/{job-id}",
  "data": {
    "workerId": "w100",
    "jobId": "7f1df17b-570b-4ae5-9cf5-fe6ff64cc712",
    "channelReference": "test-abc",
    "channelId": "FooVoiceChannelId",
    "queueId": "625fec06-ab81-4e60-b780-f364ed96ade1",
    "offerId": "525fec06-ab81-4e60-b780-f364ed96ade1",
    "offerTimeUtc": "2023-08-17T02:43:30.3847144Z",
    "expiryTimeUtc": "2023-08-17T02:44:30.3847674Z",
    "jobPriority": 5,
    "jobLabels": {
      "Locale": "en-us",
      "Segment": "Enterprise",
      "Token": "FooToken"
    },
    "jobTags": {
      "Locale": "en-us",
      "Segment": "Enterprise",
      "Token": "FooToken"
    }
  },
  "eventType": "Microsoft.Communication.RouterWorkerOfferIssued",
  "dataVersion": "1.0",
  "metadataVersion": "1",
  "eventTime": "2023-08-17T00:55:25.1736293Z"
}

Подписка на события

Одним из способов подписки на события маршрутизатора заданий ACS является портал Azure.

Перейдите к ресурсу ACS на портале Azure и откройте колонку "События".
Добавьте подписку на событие RouterWorkerOfferIssued.
Выберите подходящее средство для получения события (например, веб-перехватчик, Функции Azure, служебная шина).

Дополнительные сведения о подписке на события маршрутизатора заданий см. в документации по подписке на события маршрутизатора заданий.

Маршрут в приложении NodeJS, которое получает события, может выглядеть примерно так:

app.post('/event', (req, res) => {
    req.body.forEach(eventGridEvent => {
        // Deserialize the event data into the appropriate type
        if (eventGridEvent.eventType === "Microsoft.EventGrid.SubscriptionValidationEvent") {
            res.send({ validationResponse: eventGridEvent.data.validationCode });
        } else if (eventGridEvent.eventType === "Microsoft.Azure.CommunicationServices.RouterWorkerOfferIssued") {
           // RouterWorkerOfferIssued handling logic;
        } else if ...
    });
    ...
});

Принятие или отклонение предложения о работе

Получив событие, RouterWorkerOfferIssued вы можете принять или отклонить предложение о работе.

workerid — идентификатор работника, принимающего предложение о работе.
offerId — идентификатор предложения, принятого или отклоненного.

const acceptResponse = await routerClient.path("/routing/workers/{workerId}/offers/{offerId}:accept", workerId, offerId).post();
// or
const declineResponse = await routerClient.path("/routing/workers/{workerId}/offers/{offerId}:decline", workerId, offerId).post();

Завершение задания

Для assignmentId завершения задания требуется полученный из ответа предыдущего шага.

const completeJob = await routerClient.path("/routing/jobs/{id}/assignments/{assignmentId}:complete", jobId, acceptResponse.body.assignmentId).post({
  body: {
    note: `Job has been completed by ${workerId} at ${new Date()}`
  }
});

Закрытие задания

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

const closeJob = await routerClient.path("/routing/jobs/{id}/assignments/{assignmentId}:close", jobId, acceptResponse.body.assignmentId).post({
  body: {
    note: `Job has been closed by ${workerId} at ${new Date()}`
  }
});

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

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

Включение ведения журнала может помочь выявить полезные сведения о сбоях. Чтобы просмотреть журнал HTTP-запросов и ответов, задайте для переменной среды AZURE_LOG_LEVEL значение info. Кроме того, ведение журнала можно включить во время выполнения, вызвав setLogLevel в @azure/logger:

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

setLogLevel("info");

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

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

Клиентская библиотека REST AzureCommunicationRoutingService для JavaScript

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

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

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

Иметь ресурс ACS

Установите пакет `@azure-rest/communication-job-router`.

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

Руководство по Маршрутизация заданий в рабочие роли с помощью пакета SDK rest маршрутизатора заданий Службы коммуникации Azure (ACS)

Запуск сервера NodeJS Express

Пример

Установка пакета SDK для маршрутизатора заданий Azure ACS

Задания маршрутизации

Создание AzureCommunicationRoutingServiceClient

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

Создание очереди

Создание рабочих ролей

Жизненный цикл задания

Создание задания

(Необязательно) Создание задания с помощью политики классификации

Создание политики классификации

Создание и классификация задания

Подписка на события

Принятие или отклонение предложения о работе

Завершение задания

Закрытие задания

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

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

Обратная связь

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

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

Клиентская библиотека REST AzureCommunicationRoutingService для JavaScript

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

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

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

Иметь ресурс ACS

Установите пакет @azure-rest/communication-job-router.

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

Руководство по Маршрутизация заданий в рабочие роли с помощью пакета SDK rest маршрутизатора заданий Службы коммуникации Azure (ACS)

Запуск сервера NodeJS Express

Пример

Установка пакета SDK для маршрутизатора заданий Azure ACS

Задания маршрутизации

Создание AzureCommunicationRoutingServiceClient

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

Создание очереди

Создание рабочих ролей

Жизненный цикл задания

Создание задания

(Необязательно) Создание задания с помощью политики классификации

Создание политики классификации

Создание и классификация задания

Подписка на события

Принятие или отклонение предложения о работе

Завершение задания

Закрытие задания

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

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

Обратная связь

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

Установите пакет `@azure-rest/communication-job-router`.

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