Share via

Azure Communication Services (ACS) Job Router SDK für JavaScript

  • Artikel

Dieses Paket enthält das JavaScript SDK für den Azure Communication Services-Auftragsrouterdienst (ACS).

Erste Schritte

Wichtige Konzepte

Weitere Informationen zu Auftragsroutern finden Sie in der Dokumentation zu den wichtigsten Konzepten für den Auftragsrouter.

Voraussetzungen

Installieren von

npm install @azure/communication-job-router

Browserunterstützung

Um Azure SDK-Bibliotheken auf einer Website verwenden zu können, müssen Sie Ihren Code so konvertieren, dass er im Browser funktioniert. Dazu verwenden Sie ein Tool, das als Bundler bezeichnet wird. Lesen Sie unsere Bündelungsdokumentation , um die Bündelung besser zu verstehen.

Tutorial: Weiterleiten von Aufträgen an Worker mithilfe des Azure Communication Services (ACS) Job Router SDK

In diesem Tutorial lernen Sie Folgendes:

  • Erstellen einer Warteschlange
  • Hier erfahren Sie, wie Sie Worker erstellen und einer Warteschlange zuweisen.
  • Weiterleiten von Aufträgen an Worker
  • Abonnieren und Behandeln von Auftragsrouterereignissen
  • Abschließen und Schließen von Aufträgen.

Einrichten

(Optional) Installieren einer IDE

Installieren Sie eine IDE wie VSCode oder Webstorm.

Installieren von NodeJS

Installieren Sie NodeJS.

Starten eines NodeJS Express-Servers

Erstellen Sie in einer Shell (cmd, PowerShell, Bash usw.) einen Ordner namens RouterQuickStart , und führen Sie in diesem Ordner aus npx express-generator. Dadurch wird ein einfaches Express-Projekt generiert, das auf port 3000lauscht.

Beispiel

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

Verfügen über eine ACS-Ressource

Erstellen Sie eine ACS-Ressource im Azure-Portal , oder verwenden Sie eine vorhandene Ressource.

Installieren des Azure ACS-Auftragsrouter-SDK

Installieren Sie im RouterQuickStart Ordner das ACS Job Router SDK, indem Sie ausführen npm install @azure/communication-job-router --save.

Routingaufträge

Erstellen von Auftragsrouterclients

Zuerst müssen wir eine jobRouterAdministrationClient und eine jobRouterClienterstellen.

  • jobRouterAdministrationClient stellt Methoden für Klassifizierungsrichtlinien, Verteilungsrichtlinien, Ausnahmerichtlinien und Warteschlangen bereit.
  • jobRouterClient stellt Methoden für Jobs und Worker bereit.
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);

Erstellen einer Verteilungsrichtlinie

Diese Richtlinie bestimmt, welche Mitarbeiter Jobangebote erhalten, wenn Aufträge aus ihren Warteschlangen verteilt werden.

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

Erstellen einer Klassifizierungsrichtlinie

Diese Richtlinie klassifiziert Aufträge bei der Erstellung.

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

Erstellen einer Warteschlange

Diese Warteschlange bietet Workern Aufträge gemäß unserer zuvor erstellten Verteilungsrichtlinie.

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

Erstellen von Workern

Diese Worker sind der zuvor erstellten "Sales"-Warteschlange zugewiesen und verfügen über einige Bezeichnungen.

  • die Einstellung availableForOffers auf true bedeutet, dass diese Mitarbeiter bereit sind, Jobangebote anzunehmen.
  • Weitere Informationen finden Sie in der Dokumentation zu Bezeichnungen , um Bezeichnungen und Bezeichnungsselektoren besser zu verstehen.
  // 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
});

Auftragslebenszyklus

Lesen Sie unsere Dokumentation zum Auftragslebenszyklus , um den Lebenszyklus eines Auftrags besser zu verstehen.

Erstellen eines Auftrags

Dieser Auftrag wird in die Warteschlange der zuvor erstellten "Sales"-Warteschlange eingereiht.

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

(Optional) Erstellen eines Auftrags mit einer Klassifizierungsrichtlinie

Dieser Auftrag wird mit unserer zuvor erstellten Klassifizierungsrichtlinie klassifiziert. Es hat auch eine Bezeichnung.

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

Ereignisse

Auftragsrouterereignisse werden über Azure Event Grid übermittelt. Weitere Informationen zu Azure Event Grid finden Sie in unserer Azure Event Grid-Dokumentation.

Im vorherigen Beispiel:

  • Der Auftrag wird in die Warteschlange "Sales" eingereiht.
  • Ein Worker wird ausgewählt, um den Auftrag zu bearbeiten, ein Auftragsangebot wird an diesen Worker ausgestellt, und ein RouterWorkerOfferIssued Ereignis wird über Azure Event Grid gesendet.

JSON-Beispiel-Shape 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"
}

Abonnieren von Ereignissen

Eine Möglichkeit zum Abonnieren von ACS-Auftragsrouterereignissen ist das Azure-Portal.

  1. Navigieren Sie im Azure-Portal zu Ihrer ACS-Ressource, und öffnen Sie das Blatt "Ereignisse".
  2. Fügen Sie ein Ereignisabonnement für das Ereignis "RouterWorkerOfferIssued" hinzu.
  3. Wählen Sie ein geeignetes Mittel zum Empfangen des Ereignisses aus (z. B. Webhook, Azure Functions, Service Bus).

Informationen zum Abonnieren von Auftragsrouterereignissen finden Sie in der Dokumentation zum Abonnieren von Auftragsrouterereignissen.

Die Route in Ihrer NodeJS-Anwendung, die Ereignisse empfängt, kann in etwa wie folgt aussehen:

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

Annehmen oder Ablehnen des Auftragsangebots

Sobald Sie ein RouterWorkerOfferIssued Ereignis erhalten haben, können Sie das Stellenangebot annehmen oder ablehnen.

  • workerid – Die ID des Arbeitnehmers, der das Jobangebot annimmt.
  • offerId - Die ID des Angebots, das angenommen oder abgelehnt wird.
const acceptResponse = await jobRouterClient.acceptJobOffer(workerId, offerId);
// or
const declineResponse = await jobRouterClient.declineJobOffer(workerId, offerId);

Abschließen des Auftrags

Der assignmentId aus der Antwort des vorherigen Schritts empfangene ist erforderlich, um den Auftrag abzuschließen.

await jobRouterClient.completeJob(jobId, assignmentId);

Schließen des Auftrags

Nachdem der Worker die Abschlussphase des Auftrags abgeschlossen hat, kann der jobRouterClient den Auftrag schließen und einen Dispositionscode an ihn zur späteren Referenz anfügen.

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

Nächste Schritte

Sehen Sie sich das Beispielverzeichnis an, um weitere detaillierte Beispiele für die Verwendung dieses SDK zu finden.

Mitwirken

Wenn Sie zu diesem SDK beitragen möchten, lesen Sie den Leitfaden zum Mitwirken, um mehr über das Erstellen und Testen des Codes zu erfahren.