Freigeben über

AzureCommunicationRoutingService-REST-Clientbibliothek für JavaScript

  • Artikel

Azure Communication Routing Service

Verlassen Sie sich bei der Verwendung dieser Bibliothek stark auf unsere REST-Clientdokumentation.

Wichtige Links:

Erste Schritte

Die derzeitig unterstützten Umgebungen

  • LTS-Versionen von Node.js

Voraussetzungen

Verfügen über eine ACS-Ressource

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

Installieren Sie das Paket @azure-rest/communication-job-router.

Installieren Sie die REST-Clientbibliothek des AzureCommunicationRoutingService-REST-Clients für JavaScript mit npm:

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

Erstellen und Authentifizieren eines AzureCommunicationRoutingServiceClient

Um Azure Active Directory-Tokenanmeldeinformationen (AAD) zu verwenden, geben Sie eine instance des gewünschten Anmeldeinformationstyps an, der aus der @azure-/Identitätsbibliothek abgerufen wurde.

Um sich bei AAD zu authentifizieren, müssen Sie zuerst npm installieren. @azure/identity

Nach dem Setup können Sie auswählen, aus @azure/identity welcher Art von Anmeldeinformationen verwendet werden soll. Beispielsweise kann DefaultAzureCredential verwendet werden, um den Client zu authentifizieren.

Legen Sie die Werte der Client-ID, mandanten-ID und des geheimen Clientschlüssels der AAD-Anwendung als Umgebungsvariablen fest: AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_CLIENT_SECRET

Tutorial: Weiterleiten von Aufträgen an Worker mithilfe des Azure Communication Services (ACS) Job Router Rest 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.

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

Installieren des Azure ACS-Auftragsrouter-SDK

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

Routingaufträge

Erstellen von AzureCommunicationRoutingServiceClient

Zuerst müssen wir eine AzureCommunicationRoutingServiceClienterstellen.

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

Erstellen einer Verteilungsrichtlinie

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

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

Erstellen einer Warteschlange

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

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

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

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

(Optional) Erstellen eines Auftrags mit einer Klassifizierungsrichtlinie

Erstellen einer Klassifizierungsrichtlinie

Diese Richtlinie klassifiziert Aufträge bei der Erstellung.

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

Erstellen und Klassifizieren von Aufträgen

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

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

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

Abschließen des Auftrags

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

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

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.

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

Problembehandlung

Protokollierung

Die Aktivierung der Protokollierung kann hilfreiche Informationen über Fehler aufdecken. Um ein Protokoll von HTTP-Anforderungen und -Antworten anzuzeigen, legen Sie die Umgebungsvariable AZURE_LOG_LEVEL auf info fest. Alternativ kann die Protokollierung zur Laufzeit aktiviert werden, indem Sie setLogLevel in @azure/logger aufrufen:

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

setLogLevel("info");

Ausführlichere Anweisungen zum Aktivieren von Protokollen finden Sie in der Paketdokumentation zu @azure/logger.