SDK do Router de Tarefas do Azure Communication Services (ACS) para JavaScript

Este pacote contém o SDK JavaScript para o Serviço de Router de Tarefas do Azure Communication Services (ACS).

Introdução

Conceitos-chave

Veja a nossa documentação sobre os principais conceitos do Router de Tarefas para compreender melhor o Router de Tarefas.

Pré-requisitos

• Uma subscrição do Azure.
• Um recurso Azure Communication Services (ACS).
  • Se precisar de criar um recurso ACS, pode utilizar o Portal do Azure, Azure PowerShell ou a CLI do Azure.

Instalação

npm install @azure/communication-job-router

Browser support (Suporte do browser)

Para utilizar bibliotecas do SDK do Azure num site, tem de converter o seu código para funcionar dentro do browser. Pode fazê-lo através de uma ferramenta denominada bundler. Veja a nossa documentação de agrupamento para compreender melhor a agregação.

Tutorial: Encaminhar trabalhos para trabalhadores com o SDK do Router de Trabalhos do Azure Communication Services (ACS)

Neste tutorial, irá aprender:

• Como criar uma fila.
• Como criar trabalhadores e atribuí-los a uma fila.
• Como encaminhar empregos para os trabalhadores.
• Como subscrever e processar eventos do Router de Tarefas.
• Como concluir e fechar tarefas.

Configurar

(Opcional) Instalar um IDE

Instale um IDE, como o VSCode ou o Webstorm.

Instalar o NodeJS

Instale o NodeJS.

Iniciar um servidor NodeJS Express

Numa shell (cmd, PowerShell, Bash, etc.), crie uma pasta chamada RouterQuickStart e dentro desta pasta execute npx express-generator. Isto irá gerar um projeto Express simples que irá escutar em port 3000.

Exemplo

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

Ter um Recurso ACS

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

Instalar o SDK do Router de Tarefas ACS do Azure

RouterQuickStart Na pasta, instale o SDK do Router de Tarefas ACS ao executar npm install @azure/communication-job-router --save.

Tarefas de Encaminhamento

Construir Clientes router de tarefas

Primeiro, temos de 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 Trabalhadores.

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

Esta política determina quais os trabalhadores que receberão ofertas de emprego à medida que os postos de trabalho são distribuídos das 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

Esta política classifica as tarefas após a criação.

• Veja a documentação das nossas regras para compreender melhor as regras de atribuição de prioridades.

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

Esta fila oferece empregos aos trabalhadores de acordo com a 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 Trabalhadores

Estes trabalhadores são atribuídos à nossa fila "Vendas" criada anteriormente e têm algumas etiquetas.

• o availableForOfferstrue que significa que estes trabalhadores estão prontos para aceitar ofertas de emprego.
• veja a documentação das nossas etiquetas para compreender melhor as etiquetas e os seletores de etiquetas.

  // 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 da Tarefa

Veja a nossa documentação sobre o ciclo de vida do trabalho para compreender melhor o ciclo de vida de uma tarefa.

Create a Job (Crie uma Tarefa)

Esta tarefa está colocada na fila "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 Tarefa com uma Política de Classificação

Esta tarefa será classificada com a nossa política de classificação criada anteriormente. Também tem uma etiqueta.

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

Evento

Os eventos do Router de Tarefas são entregues através de Azure Event Grid. Veja a nossa documentação de Azure Event Grid para compreender melhor Azure Event Grid.

No exemplo anterior:

• A tarefa é colocada em fila de espera "Vendas".
• Uma função de trabalho é selecionada para processar a tarefa, é emitida uma oferta de trabalho para esse trabalho e é enviado um RouterWorkerOfferIssued evento através de Azure Event Grid.

Forma JSON de exemplo RouterWorkerOfferIssued :

{
  "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"
}

Subscrever Eventos

Uma forma de subscrever eventos do Router de Tarefas ACS é através do Portal do Azure.

1. Navegue para o recurso ACS no Portal do Azure e abra o painel "Eventos".
2. Adicione uma subscrição de evento para o evento "RouterWorkerOfferIssued".
3. Selecione um meio adequado para receber o evento (por exemplo, Webhook, Funções do Azure, Service Bus).

Veja a nossa documentação "subscrever eventos do Router de Tarefas" para compreender melhor a subscrição de eventos do Router de Tarefas.

A rota na sua aplicação NodeJS que recebe eventos pode ter um aspeto semelhante ao seguinte:

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 Emprego

Assim que receber um RouterWorkerOfferIssued evento, pode aceitar ou recusar a oferta de emprego.

• workerid - O ID do trabalhador que aceita a oferta de emprego.
• offerId - O ID da oferta a ser aceite ou recusado.

const acceptResponse = await jobRouterClient.acceptJobOffer(workerId, offerId);
// or
const declineResponse = await jobRouterClient.declineJobOffer(workerId, offerId);

Concluir a Tarefa

A assignmentId resposta recebida da resposta do passo anterior é necessária para concluir a tarefa.

await jobRouterClient.completeJob(jobId, assignmentId);

Fechar a Tarefa

Depois de a função de trabalho concluir a fase de moldagem da tarefa, pode fechar a jobRouterClient tarefa e anexar-lhe um código de disposição para referência futura.

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

Passos seguintes

Veja o diretório de exemplos para obter exemplos detalhados adicionais da utilização deste SDK.

Contribuir

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

Projetos relacionados

• SDK do Microsoft Azure para JavaScript