Bibliothèque de client REST AzureCommunicationRoutingService pour JavaScript

Article
11/22/2023

Service de routage des communications Azure

S’il vous plaît s’appuyer fortement sur notre documentation cliente REST pour utiliser cette bibliothèque

Liens clés :

Prise en main

Environnements actuellement pris en charge

Versions LTS de Node.js

Prérequis

Vous devez disposer d’un abonnement Azure pour utiliser ce package.

Avoir une ressource ACS

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

Installez le package `@azure-rest/communication-job-router`

Installez la bibliothèque de client REST du client REST AzureCommunicationRoutingService pour JavaScript avec npm:

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

Créez et authentifiez un`AzureCommunicationRoutingServiceClient`

Pour utiliser des informations d’identification de jeton Azure Active Directory (AAD), fournissez une instance du type d’informations d’identification souhaité obtenu à partir de la bibliothèque @azure/identité.

Pour vous authentifier auprès d’AAD, vous devez d’abord npm installer @azure/identity

Après l’installation, vous pouvez choisir le type d’informations d’identification@azure/identity à utiliser. Par exemple, DefaultAzureCredential peut être utilisé pour authentifier le client.

Définissez les valeurs de l’ID client, de l’ID de locataire et de la clé secrète client de l’application AAD en tant que variables d’environnement : AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_CLIENT_SECRET

Tutoriel : Acheminer des travaux vers les workers à l’aide du KIT DE développement logiciel (SDK) Rest du routeur de travail Azure Communication Services (ACS)

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 les travaux vers les workers.
Comment s’abonner aux événements Job Router et les gérer.
Comment terminer et fermer des travaux.

Démarrer un serveur Express NodeJS

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

Exemple

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

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

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

Travaux de routage

Construire AzureCommunicationRoutingServiceClient

Nous devons d’abord construire 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);

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 en dehors de leurs files d’attente.

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

Création d’une file d’attente

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

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

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 sur true signifie que ces travailleurs sont prêts à accepter des offres d’emploi.
consultez 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 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,
      },
    ],
  }
});

Cycle de vie des travaux

Consultez notre documentation sur le cycle de vie des travaux pour mieux comprendre le cycle de vie d’un travail.

Création d’un travail

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

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

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

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

Créer et classer un travail

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

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

Abonnement à des événements

L’un des moyens de s’abonner aux événements ACS Job Router consiste à utiliser le portail Azure.

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

Consultez 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 qui accepte l’offre d’emploi.
offerId - ID de l’offre acceptée ou refusée.

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

Terminer le travail

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

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

Fermer le travail

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

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

Résolution des problèmes

Journalisation

L’activation de la journalisation peut vous aider à mieux comprendre les échecs. Pour avoir un journal des requêtes et réponses HTTP, définissez la variable d’environnement AZURE_LOG_LEVEL sur info. Vous pouvez également activer la journalisation au moment de l’exécution en appelant setLogLevel dans @azure/logger :

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

setLogLevel("info");

Pour obtenir des instructions plus détaillées sur l’activation des journaux, consultez les documents relatifs au package @azure/logger.

Partager via

Bibliothèque de client REST AzureCommunicationRoutingService pour JavaScript

Prise en main

Environnements actuellement pris en charge

Prérequis

Avoir une ressource ACS

Installez le package `@azure-rest/communication-job-router`

Créez et authentifiez un`AzureCommunicationRoutingServiceClient`

Tutoriel : Acheminer des travaux vers les workers à l’aide du KIT DE développement logiciel (SDK) Rest du routeur de travail Azure Communication Services (ACS)

Démarrer un serveur Express NodeJS

Exemple

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

Travaux de routage

Construire AzureCommunicationRoutingServiceClient

Créer une stratégie de distribution

Création d’une file d’attente

Créer des workers

Cycle de vie des travaux

Création d’un travail

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

Créer une stratégie de classification

Créer et classer un travail

Abonnement à des événements

Accepter ou refuser l’offre d’emploi

Terminer le travail

Fermer le travail

Résolution des problèmes

Journalisation

Ressources supplémentaires

Partager via

Bibliothèque de client REST AzureCommunicationRoutingService pour JavaScript

Prise en main

Environnements actuellement pris en charge

Prérequis

Avoir une ressource ACS

Installez le package @azure-rest/communication-job-router

Créez et authentifiez unAzureCommunicationRoutingServiceClient

Tutoriel : Acheminer des travaux vers les workers à l’aide du KIT DE développement logiciel (SDK) Rest du routeur de travail Azure Communication Services (ACS)

Démarrer un serveur Express NodeJS

Exemple

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

Travaux de routage

Construire AzureCommunicationRoutingServiceClient

Créer une stratégie de distribution

Création d’une file d’attente

Créer des workers

Cycle de vie des travaux

Création d’un travail

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

Créer une stratégie de classification

Créer et classer un travail

Abonnement à des événements

Accepter ou refuser l’offre d’emploi

Terminer le travail

Fermer le travail

Résolution des problèmes

Journalisation

Ressources supplémentaires

Installez le package `@azure-rest/communication-job-router`

Créez et authentifiez un`AzureCommunicationRoutingServiceClient`