Partager via

Azure Communication Services (ACS) Job Router SDK pour JavaScript

  • Article

Ce package contient le Kit de développement logiciel (SDK) JavaScript pour le service de routeur de travaux Azure Communication Services (ACS).

Mise en route

Concepts clés

Reportez-vous à notre documentation sur les concepts clés de Job Router pour mieux comprendre Job Router.

Prérequis

Installation de

npm install @azure/communication-job-router

Prise en charge des navigateurs

Pour utiliser les bibliothèques du Kit de développement logiciel (SDK) Azure sur un site web, vous devez convertir votre code pour qu’il fonctionne dans le navigateur. Pour ce faire, utilisez un outil appelé bundler. Reportez-vous à notre documentation sur le regroupement pour mieux comprendre le regroupement.

Tutoriel : Acheminer des travaux vers des workers à l’aide du kit sdk Azure Communication Services (ACS) Job Router

Ce tutoriel vous apprendra à effectuer les opérations suivantes :

  • Comment créer une file d’attente.
  • Comment créer des workers et les affecter à une file d’attente.
  • Guide pratique pour acheminer des travaux vers les workers.
  • Comment s’abonner aux événements Job Router et les gérer.
  • Comment terminer et fermer des travaux.

Configuration

(Facultatif) Installer un IDE

Installez un IDE tel que VSCode ou Webstorm.

Installer NodeJS

Installez NodeJS.

Démarrer un serveur NodeJS Express

Dans un interpréteur de commandes (cmd, PowerShell, Bash, etc.), créez un dossier appelé RouterQuickStart et à l’intérieur de ce dossier, exécutez npx express-generator. Cela génère un projet Express simple qui écoutera sur port 3000.

Exemple

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

Avoir une ressource ACS

Créez une ressource ACS dans le portail Azure ou utilisez une ressource existante.

Installer le Kit de développement logiciel (SDK) Azure ACS Job Router

Dans le RouterQuickStart dossier , installez le Kit de développement logiciel (SDK) ACS Job Router en exécutant npm install @azure/communication-job-router --save.

Travaux de routage

Construire des clients de routeur de travaux

Tout d’abord, nous devons construire un jobRouterAdministrationClient et un jobRouterClient.

  • jobRouterAdministrationClient fournit des méthodes pour les stratégies de classification, les stratégies de distribution, les stratégies d’exception et les files d’attente.
  • jobRouterClient fournit des méthodes pour les travaux et les workers.
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);

Créer une stratégie de distribution

Cette stratégie détermine quels travailleurs recevront des offres d’emploi lorsque les travaux sont distribués hors de leurs files d’attente.

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

Créer une stratégie de classification

Cette stratégie classifie les travaux lors de leur création.

  • Reportez-vous à notre documentation sur les règles pour mieux comprendre les règles de hiérarchisation.
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)"
  }
});

Création d’une file d’attente

Cette file d’attente offre des travaux aux workers conformément à notre stratégie de distribution créée précédemment.

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

Créer des workers

Ces workers sont affectés à notre file d’attente « Ventes » créée précédemment et ont des étiquettes.

  • la valeur availableForOffers de true signifie que ces travailleurs sont prêts à accepter des offres d’emploi.
  • reportez-vous à notre documentation sur les étiquettes pour mieux comprendre les étiquettes et les sélecteurs d’étiquettes.
  // 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
});

Cycle de vie des travaux

Reportez-vous à notre documentation sur le cycle de vie d’un travail pour mieux comprendre le cycle de vie d’un travail.

Création d’un travail

Ce travail est mis en file d’attente dans notre file d’attente « Ventes » créée précédemment.

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

(Facultatif) Créer un travail avec une stratégie de classification

Ce travail sera classé avec notre stratégie de classification créée précédemment. Il a également une étiquette.

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

Événements

Les événements Job Router sont remis via Azure Event Grid. Reportez-vous à notre documentation Azure Event Grid pour mieux comprendre Azure Event Grid.

Dans l’exemple précédent :

  • Le travail est mis en file d’attente « Sales ».
  • Un worker est sélectionné pour gérer le travail, une offre de travail est émise à ce worker et un RouterWorkerOfferIssued événement est envoyé via Azure Event Grid.

Exemple de RouterWorkerOfferIssued forme 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"
}

Abonnement à des événements

L’une des façons de s’abonner aux événements ACS Job Router consiste à utiliser le portail Azure.

  1. Accédez à votre ressource ACS dans le portail Azure et ouvrez le panneau « Événements ».
  2. Ajoutez un abonnement aux événements pour l’événement « RouterWorkerOfferIssued ».
  3. Sélectionnez un moyen approprié pour recevoir l’événement (par exemple, Webhook, Azure Functions, Service Bus).

Reportez-vous à notre documentation « S’abonner aux événements Job Router » pour mieux comprendre l’abonnement aux événements Job Router.

L’itinéraire dans votre application NodeJS qui reçoit des événements peut ressembler à ceci :

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

Accepter ou refuser l’offre d’emploi

Une fois que vous recevez un RouterWorkerOfferIssued événement, vous pouvez accepter ou refuser l’offre d’emploi.

  • workerid - ID du travailleur acceptant l’offre d’emploi.
  • offerId - ID de l’offre acceptée ou refusée.
const acceptResponse = await jobRouterClient.acceptJobOffer(workerId, offerId);
// or
const declineResponse = await jobRouterClient.declineJobOffer(workerId, offerId);

Terminer le travail

Le assignmentId reçu de la réponse de l’étape précédente est requis pour terminer le travail.

await jobRouterClient.completeJob(jobId, assignmentId);

Fermer le travail

Une fois que le worker a terminé la phase de résumé du travail, le jobRouterClient peut fermer le travail et y attacher un code de disposition pour référence ultérieure.

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

Étapes suivantes

Consultez le répertoire d’exemples pour obtenir d’autres exemples détaillés d’utilisation de ce Kit de développement logiciel (SDK).

Contribution

Si vous souhaitez contribuer à ce Kit de développement logiciel (SDK), lisez le guide de contribution pour en savoir plus sur la génération et le test du code.