Biblioteca de cliente REST do AzureCommunicationRoutingService para JavaScript

Artigo
11/22/2023

Serviço de Encaminhamento de Comunicações do Azure

Confie fortemente nos nossos documentos de cliente REST para utilizar esta biblioteca

Ligações principais:

Introdução

Ambientes atualmente suportados

Versões LTS do Node.js

Pré-requisitos

Tem de ter uma subscrição do Azure para utilizar este pacote.

Ter um Recurso ACS

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

Instalar o pacote `@azure-rest/communication-job-router`

Instale a biblioteca de cliente REST do cliente REST AzureCommunicationRoutingService para JavaScript com npm:

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

Criar e autenticar um `AzureCommunicationRoutingServiceClient`

Para utilizar uma credencial de token do Azure Active Directory (AAD), forneça uma instância do tipo de credencial pretendido obtido a partir da biblioteca de @azure/identidade .

Para autenticar com o AAD, primeiro tem de npm instalar @azure/identity

Após a configuração, pode escolher o tipo de credencial a utilizar @azure/identity . Por exemplo, DefaultAzureCredential pode ser utilizado para autenticar o cliente.

Defina os valores do ID de cliente, do ID do inquilino e do segredo do cliente da aplicação do AAD como variáveis de ambiente: AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_CLIENT_SECRET

Tutorial: Encaminhar tarefas para trabalhadores com o SDK Rest 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 trabalhos para trabalhadores.
Como subscrever e processar eventos do Router de Tarefas.
Como concluir e fechar tarefas.

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

Instalar o SDK do Router de Tarefas dos ACS do Azure

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

Tarefas de Encaminhamento

Construir o AzureCommunicationRoutingServiceClient

Primeiro, temos de construir um 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);

Criar uma Política de Distribuição

Esta política determina quais os trabalhadores que receberão ofertas de emprego à medida que os trabalhos são distribuídos das suas filas.

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

Criar uma Fila

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

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

Criar Trabalhadores

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

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

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

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 em fila na fila "Vendas" criada anteriormente.

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

(Opcional) Criar Tarefa com uma Política de Classificação

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

Criar e classificar tarefas

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

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

Subscrever Eventos

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

Navegue para o recurso ACS no Portal do Azure e abra o painel "Eventos".
Adicione uma subscrição de evento para o evento "RouterWorkerOfferIssued".
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 Job Router" para compreender melhor a subscrição de eventos do Job Router.

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 recusada.

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();

Concluir a Tarefa

O assignmentId recebido da resposta do passo anterior é necessário para concluir a tarefa.

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()}`
  }
});

Fechar a Tarefa

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

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()}`
  }
});

Resolução de problemas

Registo

Ativar o registo pode ajudar a descobrir informações úteis sobre falhas. Para ver um registo de pedidos e respostas HTTP, defina a variável de AZURE_LOG_LEVEL ambiente como info. Em alternativa, o registo pode ser ativado no runtime ao chamar setLogLevel no @azure/logger:

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

setLogLevel("info");

Para obter instruções mais detalhadas sobre como ativar os registos, pode ver os documentos do pacote @azure/logger.

Partilhar via

Biblioteca de cliente REST do AzureCommunicationRoutingService para JavaScript

Introdução

Ambientes atualmente suportados

Pré-requisitos

Ter um Recurso ACS

Instalar o pacote `@azure-rest/communication-job-router`

Criar e autenticar um `AzureCommunicationRoutingServiceClient`

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

Iniciar um servidor NodeJS Express

Exemplo

Instalar o SDK do Router de Tarefas dos ACS do Azure

Tarefas de Encaminhamento

Construir o AzureCommunicationRoutingServiceClient

Criar uma Política de Distribuição

Criar uma Fila

Criar Trabalhadores

Ciclo de Vida da Tarefa

Create a Job (Crie uma Tarefa)

(Opcional) Criar Tarefa com uma Política de Classificação

Criar uma Política de Classificação

Criar e classificar tarefas

Subscrever Eventos

Aceitar ou Recusar a Oferta de Emprego

Concluir a Tarefa

Fechar a Tarefa

Resolução de problemas

Registo

Recursos adicionais

Partilhar via

Biblioteca de cliente REST do AzureCommunicationRoutingService para JavaScript

Introdução

Ambientes atualmente suportados

Pré-requisitos

Ter um Recurso ACS

Instalar o pacote @azure-rest/communication-job-router

Criar e autenticar um AzureCommunicationRoutingServiceClient

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

Iniciar um servidor NodeJS Express

Exemplo

Instalar o SDK do Router de Tarefas dos ACS do Azure

Tarefas de Encaminhamento

Construir o AzureCommunicationRoutingServiceClient

Criar uma Política de Distribuição

Criar uma Fila

Criar Trabalhadores

Ciclo de Vida da Tarefa

Create a Job (Crie uma Tarefa)

(Opcional) Criar Tarefa com uma Política de Classificação

Criar uma Política de Classificação

Criar e classificar tarefas

Subscrever Eventos

Aceitar ou Recusar a Oferta de Emprego

Concluir a Tarefa

Fechar a Tarefa

Resolução de problemas

Registo

Recursos adicionais

Instalar o pacote `@azure-rest/communication-job-router`

Criar e autenticar um `AzureCommunicationRoutingServiceClient`