Biblioteca cliente REST de AzureCommunicationRoutingService para JavaScript

Artículo
11/22/2023

Servicio de enrutamiento de comunicación de Azure

Confíe en gran medida en nuestros documentos de cliente REST para usar esta biblioteca.

Vínculos principales:

Introducción

Entornos admitidos actualmente

Versiones de LTS de Node.js

Requisitos previos

Debe tener una suscripción de Azure para usar este paquete.

Tener un recurso de ACS

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

Instalar el paquete `@azure-rest/communication-job-router`

Instale la biblioteca cliente REST del cliente REST AzureCommunicationRoutingService para JavaScript con npm:

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

Crear y autenticar una `AzureCommunicationRoutingServiceClient`

Para usar una credencial de token de Azure Active Directory (AAD), proporcione una instancia del tipo de credencial deseado obtenido de la biblioteca de @azure/identidad .

Para autenticarse con AAD, primero npm debe instalar @azure/identity

Después de la instalación, puede elegir qué tipo de credencial@azure/identity usar. Por ejemplo, Se puede usar DefaultAzureCredential para autenticar al cliente.

Establezca los valores del identificador de cliente, el identificador de inquilino y el secreto de cliente de la aplicación de AAD como variables de entorno: AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_CLIENT_SECRET

Tutorial: Enrutamiento de trabajos a trabajadores mediante el SDK rest del 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.

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

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-rest/communication-job-router --save.

Trabajos de enrutamiento

Construcción de AzureCommunicationRoutingServiceClient

En primer lugar, es necesario construir un 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);

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

Creación de una cola

Esta cola ofrece trabajos a los trabajadores según nuestra directiva de distribución creada 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: {},
  }
});

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 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 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 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) Crear trabajo con una directiva de clasificación

Crear una directiva de clasificación

Esta directiva clasifica los trabajos tras la creación.

Consulte nuestra documentación sobre reglas para comprender mejor las reglas de priorización.

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

Creación y clasificación de trabajos

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

Suscripción a eventos

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

Vaya al recurso de ACS en Azure Portal y abra la hoja "Eventos".
Agregue una suscripción de eventos para el evento "RouterWorkerOfferIssued".
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 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();

Completar el trabajo

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

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

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.

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

Solución de problemas

Registro

La habilitación del registro puede ayudar a descubrir información útil sobre los errores. Para ver un registro de solicitudes y respuestas HTTP, establezca la variable de entorno AZURE_LOG_LEVEL en info. Como alternativa, el registro se puede habilitar en tiempo de ejecución llamando a setLogLevel en @azure/logger:

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

setLogLevel("info");

Para obtener instrucciones más detalladas sobre cómo habilitar los registros, consulte los documentos del paquete @azure/logger.

Compartir a través de

Biblioteca cliente REST de AzureCommunicationRoutingService para JavaScript

Introducción

Entornos admitidos actualmente

Requisitos previos

Tener un recurso de ACS

Instalar el paquete `@azure-rest/communication-job-router`

Crear y autenticar una `AzureCommunicationRoutingServiceClient`

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

Inicio de un servidor de NodeJS Express

Ejemplo

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

Trabajos de enrutamiento

Construcción de AzureCommunicationRoutingServiceClient

Crear una directiva de distribución

Creación de una cola

Creación de trabajos

Ciclo de vida del trabajo

Creación de un trabajo

(Opcional) Crear trabajo con una directiva de clasificación

Crear una directiva de clasificación

Creación y clasificación de trabajos

Suscripción a eventos

Aceptar o rechazar la oferta de trabajo

Completar el trabajo

Cerrar el trabajo

Solución de problemas

Registro

Recursos adicionales

Compartir a través de

Biblioteca cliente REST de AzureCommunicationRoutingService para JavaScript

Introducción

Entornos admitidos actualmente

Requisitos previos

Tener un recurso de ACS

Instalar el paquete @azure-rest/communication-job-router

Crear y autenticar una AzureCommunicationRoutingServiceClient

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

Inicio de un servidor de NodeJS Express

Ejemplo

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

Trabajos de enrutamiento

Construcción de AzureCommunicationRoutingServiceClient

Crear una directiva de distribución

Creación de una cola

Creación de trabajos

Ciclo de vida del trabajo

Creación de un trabajo

(Opcional) Crear trabajo con una directiva de clasificación

Crear una directiva de clasificación

Creación y clasificación de trabajos

Suscripción a eventos

Aceptar o rechazar la oferta de trabajo

Completar el trabajo

Cerrar el trabajo

Solución de problemas

Registro

Recursos adicionales

Instalar el paquete `@azure-rest/communication-job-router`

Crear y autenticar una `AzureCommunicationRoutingServiceClient`