SDK do Roteador de Trabalho do Serviços de Comunicação do Azure (ACS) para JavaScript

  • Artigo

Esse pacote contém o SDK do JavaScript para o serviço de roteador de trabalho do ACS (Serviços de Comunicação do Azure).

Introdução

Conceitos Principais

Consulte nossa documentação de conceitos principais do Roteador de Trabalho para entender melhor o Roteador de Trabalho.

Pré-requisitos

Instalando o

npm install @azure/communication-job-router

Suporte ao navegador

Para usar bibliotecas do SDK do Azure em um site, você precisa converter seu código para funcionar dentro do navegador. Você faz isso usando uma ferramenta chamada bundler. Consulte nossa documentação de agrupamento para entender melhor o agrupamento.

Tutorial: Rotear trabalhos para trabalhos usando o SDK do Roteador de Trabalho do SERVIÇOS DE COMUNICAÇÃO DO AZURE (ACS)

Neste tutorial, você irá aprender:

  • Como criar uma fila.
  • Como criar trabalhos e atribuí-los a uma fila.
  • Como rotear trabalhos para os trabalhadores.
  • Como assinar e manipular eventos do Roteador de Trabalho.
  • Como concluir e fechar trabalhos.

Ao configurar o

(Opcional) Instalar um IDE

Instale um IDE, como VSCode ou Webstorm.

Instalar o NodeJS

Instale o NodeJS.

Iniciar um servidor NodeJS Express

Em um shell (cmd, PowerShell, Bash etc.), crie uma pasta chamada RouterQuickStart e, dentro dessa pasta, execute npx express-generator. Isso gerará um projeto express simples que escutará em port 3000.

Exemplo

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

Ter um recurso do ACS

Crie um recurso do ACS no Portal do Azure ou use um recurso existente.

Instalar o SDK do Roteador de Trabalho do ACS do Azure

RouterQuickStart Na pasta , instale o SDK do Roteador de Trabalho do ACS executando npm install @azure/communication-job-router --save.

Trabalhos de roteamento

Construir clientes do roteador de trabalho

Primeiro, precisamos construir um jobRouterAdministrationClient e um jobRouterClient.

  • jobRouterAdministrationClient fornece métodos para Políticas de Classificação, Políticas de Distribuição, Políticas de Exceção e Filas.
  • jobRouterClient fornece métodos para Trabalhos e Trabalhos.
const {
  JobRouterClient,
  JobRouterAdministrationClient,
} = require("@azure/communication-job-router");

const acsConnectionString =
  "endpoint=https://<YOUR_ACS>.communication.azure.com/;accesskey=<YOUR_ACCESS_KEY>";
const jobRouterClient = new JobRouterClient(acsConnectionString);
const jobRouterAdministrationClient = new JobRouterAdministrationClient(acsConnectionString);

Criar uma política de distribuição

Essa política determina quais trabalhadores receberão ofertas de trabalho à medida que os trabalhos forem distribuídos fora de suas filas.

const distributionPolicy = await jobRouterAdministrationClient.createDistributionPolicy(
  "default-distribution-policy-id",
  {
    name: "Default Distribution Policy",
    offerExpiresAfterSeconds: 30,
    mode: {
      objectType: "longest-idle",
      minConcurrentOffers: 1,
      maxConcurrentOffers: 3,
    },
  }
);

Criar uma política de classificação

Essa política classifica os trabalhos após a criação.

const classificationPolicy = await jobRouterAdministrationClient.createClassificationPolicy("default-classification-policy-id", {
  name: "Default Classification Policy",
  fallbackQueueId: salesQueueResponse.Id,
  queueSelectors: [{
    kind: "static",
    labelSelector: { key: "department", labelOperator: "equal", value: "xbox" }
  }],
  workerSelectors: [{
    kind: "static",
    labelSelector: { key: "english", labelOperator: "greaterThan", value: 5 }
  }],
  prioritizationRule: {
    kind: "expression-rule",
    language: "powerFx";
    expression: "If(job.department = \"xbox\", 2, 1)"
  }
});

criar uma fila

Essa fila oferece trabalhos aos trabalhadores de acordo com nossa política de distribuição criada anteriormente.

const salesQueueResponse = await jobRouterAdministrationClient.createQueue("sales-queue-id", {
  name: "Sales",
  distributionPolicyId: distributionPolicy.Id,
  labels: {
    department: "xbox",
  },
});

Criar Trabalhos

Esses trabalhos são atribuídos à nossa fila "Vendas" criada anteriormente e têm alguns rótulos.

  • configuração availableForOffers para true significa que esses trabalhadores estão prontos para aceitar ofertas de trabalho.
  • consulte nossa documentação de rótulos para entender melhor os rótulos e os seletores de rótulo.
  // Create worker "Alice".
  const workerAliceId = "773accfb-476e-42f9-a202-b211b41a4ea4";
  const workerAliceResponse = await jobRouterClient.createWorker(workerAliceId, {
    totalCapacity: 120,
    labels: {
      Xbox: 5,
      german: 4
      name: "Alice",
    },
    queueAssignments: { [salesQueueResponse.Id]: {} },
    availableForOffers: true
  });

// Create worker "Bob".
const workerBobId = "21837c88-6967-4078-86b9-1207821a8392";
const workerBobResponse = await jobRouterClient.createWorker(workerBobId, {
  totalCapacity: 100,
  labels: {
    xbox: 5,
    english: 3
    name: "Bob"
  },
  queueAssignments: { [salesQueueResponse]: {} },
  availableForOffers: true
});

Ciclo de vida do trabalho

Consulte nossa documentação do ciclo de vida do trabalho para entender melhor o ciclo de vida de um trabalho.

Crie um trabalho

Esse trabalho é enfileirado em nossa fila de "Vendas" criada anteriormente.

const job = await jobRouterClient.createJob("job-id", {
  // e.g. callId or chat threadId
  channelReference: "66e4362e-aad5-4d71-bb51-448672ebf492",
  channelId: "voice",
  priority: 2,
  queueId: salesQueueResponse.Id,
});

(Opcional) Criar trabalho com uma política de classificação

Esse trabalho será classificado com nossa política de classificação criada anteriormente. Ele também tem um rótulo.

const classificationJob = await JobRouterClient.createJob("classification-job-id", {
  // e.g. callId or chat threadId
  channelReference: "66e4362e-aad5-4d71-bb51-448672ebf492",
  channelId: "voice",
  classificationPolicyId: classificationPolicy.Id,
  labels: {
    department: "xbox",
  },
});

Eventos

Os eventos do Roteador de Trabalho são entregues por meio de Grade de Eventos do Azure. Consulte nossa documentação do Grade de Eventos do Azure para entender melhor Grade de Eventos do Azure.

No exemplo anterior:

  • O trabalho é enfileirado na fila "Vendas".
  • Um trabalho é selecionado para lidar com o trabalho, uma oferta de trabalho é emitida para esse trabalho e um RouterWorkerOfferIssued evento é enviado por meio de Grade de Eventos do Azure.

Exemplo RouterWorkerOfferIssued de forma 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"
}

Assinando eventos

Uma maneira de assinar eventos do Roteador de Trabalho do ACS é por meio do Portal do Azure.

  1. Navegue até o recurso ACS no Portal do Azure e abra a folha "Eventos".
  2. Adicione uma assinatura de evento para o evento "RouterWorkerOfferIssued".
  3. Selecione um meio apropriado para receber o evento (por exemplo, Webhook, Azure Functions, Barramento de Serviço).

Consulte nossa documentação "Assinar eventos do Roteador de Trabalho" para entender melhor a assinatura de eventos do Roteador de Trabalho.

A rota em seu aplicativo NodeJS que recebe eventos pode ter esta aparência:

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 ...
    });
    ...
});

Aceitar ou recusar a oferta de trabalho

Depois de receber um RouterWorkerOfferIssued evento, você poderá aceitar ou recusar a oferta de trabalho.

  • workerid - A ID do trabalhador que aceita a oferta de trabalho.
  • offerId - A ID da oferta que está sendo aceita ou recusada.
const acceptResponse = await jobRouterClient.acceptJobOffer(workerId, offerId);
// or
const declineResponse = await jobRouterClient.declineJobOffer(workerId, offerId);

Concluir o trabalho

O assignmentId recebido da resposta da etapa anterior é necessário para concluir o trabalho.

await jobRouterClient.completeJob(jobId, assignmentId);

Fechar o trabalho

Depois que o trabalho tiver concluído a fase de encapsulamento do trabalho, o jobRouterClient poderá fechar o trabalho e anexar um código de disposição a ele para referência futura.

await jobRouterClient.closeJob(jobId, assignmentId, { dispositionCode: "Resolved" });

Próximas etapas

Dê uma olhada no diretório de exemplos para obter exemplos detalhados adicionais de como usar esse SDK.

Participante

Se você quiser contribuir com esse SDK, leia o guia de contribuição para saber mais sobre como criar e testar o código.