Delen via

AzureCommunicationRoutingService REST-clientbibliotheek voor JavaScript

  • Artikel

Azure Communication Routing Service

Vertrouw sterk op onze REST-clientdocumenten om deze bibliotheek te gebruiken

Belangrijke koppelingen:

Aan de slag

Momenteel ondersteunde omgevingen

  • LTS-versies van Node.js

Vereisten

Een ACS-resource hebben

Maak een ACS-resource in Azure Portal of gebruik een bestaande resource.

Installeer het pakket @azure-rest/communication-job-router

Installeer de REST-clientbibliotheek van de Rest-client van AzureCommunicationRoutingService voor JavaScript met npm:

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

Een maken en verifiëren AzureCommunicationRoutingServiceClient

Als u een AAD-tokenreferentie (Azure Active Directory) wilt gebruiken, geeft u een exemplaar op van het gewenste referentietype dat is verkregen uit de @azure-/identiteitsbibliotheek .

Als u zich wilt verifiëren met AAD, moet u eerst npm installeren @azure/identity

Na de installatie kunt u kiezen welk type referentie@azure/identity u wilt gebruiken. Als voorbeeld kan DefaultAzureCredential worden gebruikt om de client te verifiëren.

Stel de waarden van de client-id, tenant-id en clientgeheim van de AAD-toepassing in als omgevingsvariabelen: AZURE_CLIENT_ID, AZURE_TENANT_ID AZURE_CLIENT_SECRET

Zelfstudie: Taken naar werkrollen routeren met behulp van de Azure Communication Services (ACS) Job Router Rest SDK

In deze zelfstudie leert u het volgende:

  • Een wachtrij maken.
  • Werkrollen maken en deze toewijzen aan een wachtrij.
  • Taken doorsturen naar werkrollen.
  • Hoe u zich kunt abonneren op taakrouter-gebeurtenissen en deze afhandelen.
  • Taken voltooien en sluiten.

Een NodeJS Express-server starten

Maak in een shell (cmd, PowerShell, Bash, enzovoort) een map met de naam RouterQuickStart en voer in deze map uit npx express-generator. Hiermee wordt een eenvoudig Express-project gegenereerd dat luistert op port 3000.

Voorbeeld

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

De Azure ACS-taakrouter-SDK installeren

Installeer in de RouterQuickStart map de ACS Job Router SDK door uit te npm install @azure-rest/communication-job-router --savevoeren.

Routeringstaken

AzureCommunicationRoutingServiceClient maken

Eerst moeten we een AzureCommunicationRoutingServiceClientmaken.

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

Een distributiebeleid maken

Met dit beleid wordt bepaald welke werknemers jobaanbiedingen ontvangen wanneer taken buiten hun wachtrijen worden verdeeld.

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

Een wachtrij maken

Deze wachtrij biedt taken aan werknemers volgens ons eerder gemaakte distributiebeleid.

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

Werkrollen maken

Deze werknemers worden toegewezen aan de eerder gemaakte wachtrij 'Verkoop' en hebben enkele labels.

  • ingesteld op availableForOffers betekent true dat deze werknemers klaar zijn om vacatures te accepteren.
  • raadpleeg onze documentatie over labels voor een beter begrip van labels en labelkiezers.
  // 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,
      },
    ],
  }
});

Taaklevenscyclus

Raadpleeg onze documentatie over de levenscyclus van een taak voor meer inzicht in de levenscyclus van een taak.

Een taak maken

Deze taak is toegevoegd aan de eerder gemaakte wachtrij 'Verkoop'.

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

(Optioneel) Taak maken met een classificatiebeleid

Een classificatiebeleid maken

Dit beleid classificeert taken bij het maken.

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

Taak maken en classificeren

Deze taak wordt geclassificeerd met het eerder gemaakte classificatiebeleid. Het heeft ook een label.

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

Abonneren op gebeurtenissen

Een manier om u te abonneren op acs-taakrouter-gebeurtenissen is via de Azure-portal.

  1. Navigeer naar uw ACS-resource in Azure Portal en open de blade Gebeurtenissen.
  2. Voeg een gebeurtenisabonnement toe voor de gebeurtenis RouterWorkerOfferIssued.
  3. Selecteer een geschikte methode om de gebeurtenis te ontvangen (bijvoorbeeld Webhook, Azure Functions, Service Bus).

Raadpleeg onze documentatie 'abonneren op taakrouter-gebeurtenissen' voor meer informatie over het abonneren op taakrouter-gebeurtenissen.

De route in uw NodeJS-toepassing die gebeurtenissen ontvangt, kan er ongeveer als volgt uitzien:

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

De jobaanbieding accepteren of weigeren

Zodra u een RouterWorkerOfferIssued gebeurtenis hebt ontvangen, kunt u de jobaanbieding accepteren of weigeren.

  • workerid - De id van de werknemer die de jobaanbieding accepteert.
  • offerId - De id van de aanbieding die wordt geaccepteerd of geweigerd.
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();

De taak voltooien

De assignmentId ontvangen van het antwoord van de vorige stap is vereist om de taak te voltooien.

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

De taak sluiten

Zodra de werkrol de afrondingsfase van de taak heeft voltooid, kan de jobRouterClient taak worden gesloten en een verwijderingscode aan de taak worden toegevoegd voor toekomstig gebruik.

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

Problemen oplossen

Logboekregistratie

Het inschakelen van logboekregistratie kan helpen bij het ontdekken van nuttige informatie over fouten. Als u een logboek met HTTP-aanvragen en -antwoorden wilt zien, stelt u de AZURE_LOG_LEVEL omgevingsvariabele in op info. U kunt logboekregistratie ook tijdens runtime inschakelen door aan te roepen setLogLevel in de @azure/logger:

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

setLogLevel("info");

Voor meer gedetailleerde instructies over het inschakelen van logboeken kunt u de @azure-/loggerpakketdocumenten bekijken.