Compartir a través de

SDK del enrutador de trabajos de Azure Communication Services (ACS) para JavaScript

  • Artículo

Este paquete contiene el SDK de JavaScript para el servicio de enrutador de trabajos de Azure Communication Services (ACS).

Introducción

Conceptos clave

Consulte nuestra documentación de conceptos clave del enrutador de trabajos para comprender mejor el enrutador de trabajos.

Prerrequisitos

Instalación de

npm install @azure/communication-job-router

Compatibilidad con exploradores

Para usar bibliotecas del SDK de Azure en un sitio web, debe convertir el código para que funcione dentro del explorador. Para ello, use una herramienta denominada bundler. Consulte nuestra documentación de agrupación para comprender mejor la agrupación.

Tutorial: Enrutamiento de trabajos a trabajadores mediante el SDK de enrutador de trabajos de Azure Communication Services (ACS)

En este tutorial, aprenderá a:

  • Cómo crear una cola.
  • Cómo crear trabajos y asignarlos a una cola.
  • Cómo enrutar trabajos a los trabajos.
  • Cómo suscribirse y controlar eventos del enrutador de trabajos.
  • Cómo completar y cerrar trabajos.

Instalación

(Opcional) Instalación de un IDE

Instale un IDE como VSCode o Webstorm.

Instalación de NodeJS

Instale NodeJS.

Inicio de un servidor de NodeJS Express

En un shell (cmd, PowerShell, Bash, etc.), cree una carpeta denominada RouterQuickStart y dentro de esta carpeta ejecute npx express-generator. Esto generará un proyecto express simple que escuchará en port 3000.

Ejemplo

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

Tener un recurso de ACS

Cree un recurso de ACS en Azure Portal o use un recurso existente.

Instalación del SDK del enrutador de trabajos de Azure ACS

En la RouterQuickStart carpeta , instale el SDK del enrutador de trabajos de ACS ejecutando npm install @azure/communication-job-router --save.

Trabajos de enrutamiento

Construir clientes de enrutador de trabajos

En primer lugar, es necesario construir un jobRouterAdministrationClient y un .jobRouterClient

  • jobRouterAdministrationClient proporciona métodos para directivas de clasificación, directivas de distribución, directivas de excepción y colas.
  • jobRouterClient proporciona métodos para trabajos y trabajos.
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);

Crear una directiva de distribución

Esta directiva determina qué trabajadores recibirán ofertas de trabajo a medida que los trabajos se distribuyen fuera de sus colas.

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

Crear una directiva de clasificación

Esta directiva clasifica los trabajos tras la creación.

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

Creación de una cola

Esta cola ofrece trabajos a los trabajadores según nuestra directiva de distribución creada anteriormente.

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

Creación de trabajos

Estos trabajos se asignan a la cola "Ventas" creada anteriormente y tienen algunas etiquetas.

  • establecer availableForOffers en true significa que estos trabajos están listos para aceptar ofertas de trabajo.
  • consulte nuestra documentación de etiquetas para comprender mejor las etiquetas y los selectores 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 del trabajo

Consulte nuestra documentación del ciclo de vida del trabajo para comprender mejor el ciclo de vida de un trabajo.

Creación de un trabajo

Este trabajo se pone en cola en la cola "Ventas" creada 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) Crear trabajo con una directiva de clasificación

Este trabajo se clasificará con nuestra directiva de clasificación creada anteriormente. También tiene una 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",
  },
});

Eventos

Los eventos del enrutador de trabajos se entregan a través de Azure Event Grid. Consulte nuestra documentación de Azure Event Grid para comprender mejor Azure Event Grid.

En el ejemplo anterior:

  • El trabajo se pone en cola en la cola "Sales".
  • Se selecciona un trabajo para controlar el trabajo, se emite una oferta de trabajo a ese trabajo y se envía un RouterWorkerOfferIssued evento a través de Azure Event Grid.

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

Suscripción a eventos

Una manera de suscribirse a los eventos del enrutador de trabajos de ACS es a través de Azure Portal.

  1. Vaya al recurso de ACS en Azure Portal y abra la hoja "Eventos".
  2. Agregue una suscripción de eventos para el evento "RouterWorkerOfferIssued".
  3. Seleccione un medio adecuado para recibir el evento (por ejemplo, Webhook, Azure Functions, Service Bus).

Consulte nuestra documentación de "suscribirse a eventos del enrutador de trabajos" para comprender mejor la suscripción a eventos del enrutador de trabajos.

La ruta de la aplicación NodeJS que recibe eventos puede tener un aspecto similar al siguiente:

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

Aceptar o rechazar la oferta de trabajo

Una vez que reciba un RouterWorkerOfferIssued evento, puede aceptar o rechazar la oferta de trabajo.

  • workerid : el identificador del trabajador que acepta la oferta de trabajo.
  • offerId - El identificador de la oferta que se acepta o rechaza.
const acceptResponse = await jobRouterClient.acceptJobOffer(workerId, offerId);
// or
const declineResponse = await jobRouterClient.declineJobOffer(workerId, offerId);

Completar el trabajo

La assignmentId respuesta del paso anterior es necesaria para completar el trabajo.

await jobRouterClient.completeJob(jobId, assignmentId);

Cerrar el trabajo

Una vez que el trabajo ha completado la fase de resumen del trabajo, jobRouterClient puede cerrar el trabajo y adjuntar un código de eliminación a él para futuras referencias.

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

Pasos siguientes

Eche un vistazo al directorio de ejemplos para obtener ejemplos detallados adicionales del uso de este SDK.

Contribuciones

Si quiere contribuir a este SDK, lea la guía de contribución para obtener más información sobre cómo compilar y probar el código.