Condividi tramite

Servizi di comunicazione di Azure (ACS) Job Router SDK per JavaScript

  • Articolo

Questo pacchetto contiene JavaScript SDK per il servizio router del processo Servizi di comunicazione di Azure (ACS).

Introduzione

Concetti chiave

Vedere la documentazione relativa ai concetti chiave del router di processo per comprendere meglio Il router dei processi.

Prerequisiti

Installazione

npm install @azure/communication-job-router

Supporto browser

Per usare le librerie di Azure SDK in un sito Web, è necessario convertire il codice in modo che funzioni all'interno del browser. A tale scopo, si usa uno strumento denominato bundler. Fare riferimento alla documentazione di raggruppamento per comprendere meglio il raggruppamento.

Esercitazione: Instradare i processi ai lavoratori usando l'SDK del router del processo di Servizi di comunicazione di Azure (ACS)

In questa esercitazione si apprenderà:

  • Come creare una coda.
  • Come creare i lavoratori e assegnarli a una coda.
  • Come indirizzare i processi ai lavoratori.
  • Come sottoscrivere e gestire gli eventi del router di processo.
  • Come completare e chiudere i processi.

Configurazione

(Facoltativo) Installare un IDE

Installare un IDE, ad esempio VSCode o Webstorm.

Installare NodeJS

Installare NodeJS.

Avviare un server NodeJS Express

In una shell (cmd, PowerShell, Bash e così via), creare una cartella denominata RouterQuickStart e all'interno di questa cartella eseguire npx express-generator. In questo modo verrà generato un semplice progetto Express che verrà ascoltato su port 3000.

Esempio

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

Avere una risorsa ACS

Creare una risorsa ACS nel portale di Azure o usare una risorsa esistente.

Installare Azure ACS Job Router SDK

RouterQuickStart Nella cartella installare ACS Job Router SDK eseguendo npm install @azure/communication-job-router --save.

Processi di routing

Costruire client del router del processo

Prima di tutto è necessario costruire un jobRouterAdministrationClient oggetto e un jobRouterClient.

  • jobRouterAdministrationClient fornisce metodi per criteri di classificazione, criteri di distribuzione, criteri di eccezione e code.
  • jobRouterClient fornisce metodi per processi e lavoratori.
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);

Creare criteri di distribuzione

Questo criterio determina quali lavoratori riceveranno offerte di lavoro perché i processi vengono distribuiti dalle code.

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

Creare criteri di classificazione

Questo criterio classifica i processi alla creazione.

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

Creare una coda

Questa coda offre processi ai lavoratori in base ai criteri di distribuzione creati in precedenza.

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

Creare ruoli di lavoro

Questi lavoratori vengono assegnati alla coda "Sales" creata in precedenza e hanno alcune etichette.

  • impostazione availableForOffers per significa che questi lavoratori sono pronti ad true accettare offerte di lavoro.
  • fare riferimento alla documentazione delle etichette per comprendere meglio le etichette e i selettore di etichette.
  // 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 di vita del processo

Vedere la documentazione del ciclo di vita del processo per comprendere meglio il ciclo di vita di un processo.

Creare un processo

Questo processo viene eseguito in base alla coda "Sales" creata in precedenza.

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

(Facoltativo) Creare un processo con criteri di classificazione

Questo processo verrà classificato con i criteri di classificazione creati in precedenza. Ha anche un'etichetta.

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

evento

Gli eventi del router del processo vengono recapitati tramite Griglia di eventi di Azure. Vedere la documentazione Griglia di eventi di Azure per comprendere meglio Griglia di eventi di Azure.

Nell'esempio precedente:

  • Il processo viene accodato alla coda "Sales".
  • Un ruolo di lavoro viene selezionato per gestire il processo, viene rilasciata un'offerta di processo a tale ruolo e viene inviato un RouterWorkerOfferIssued evento tramite Griglia di eventi di Azure.

Forma JSON di esempio RouterWorkerOfferIssued :

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

Sottoscrizione di eventi

Un modo per sottoscrivere gli eventi del router processi ACS è tramite il portale di Azure.

  1. Passare alla risorsa ACS nel portale di Azure e aprire il pannello "Eventi".
  2. Aggiungere una sottoscrizione di evento per l'evento "RouterWorkerOfferIssued".
  3. Selezionare un mezzo appropriato per ricevere l'evento ,ad esempio Webhook, Funzioni di Azure, bus di servizio.

Per comprendere meglio la sottoscrizione agli eventi di Job Router, vedere la documentazione relativa alla sottoscrizione agli eventi del router di processo.

La route nell'applicazione NodeJS che riceve eventi può essere simile alla seguente:

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

Accettare o rifiutare l'offerta di processo

Dopo aver ricevuto un RouterWorkerOfferIssued evento, è possibile accettare o rifiutare l'offerta di processo.

  • workerid - ID del lavoratore che accetta l'offerta di lavoro.
  • offerId - ID dell'offerta accettata o rifiutata.
const acceptResponse = await jobRouterClient.acceptJobOffer(workerId, offerId);
// or
const declineResponse = await jobRouterClient.declineJobOffer(workerId, offerId);

Completare il processo

La assignmentId risposta ricevuta dal passaggio precedente è necessaria per completare il processo.

await jobRouterClient.completeJob(jobId, assignmentId);

Chiudere il processo

Dopo aver completato la fase di wrapping del processo, jobRouterClient il processo può chiudere il processo e collegare un codice di eliminazione per il riferimento futuro.

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

Passaggi successivi

Esaminare la directory degli esempi per altri esempi di uso di questo SDK.

Contributo

Se si vuole contribuire a questo SDK, leggere la guida ai contributi per altre informazioni su come compilare e testare il codice.