Delen via

Azure Communication Services (ACS) taakrouter SDK voor JavaScript

  • Artikel

Dit pakket bevat de JavaScript SDK voor de Azure Communication Services (ACS)-taakrouterservice.

Aan de slag

Belangrijkste concepten

Raadpleeg onze documentatie over de belangrijkste concepten van taakrouters om meer inzicht te krijgen in taakrouter.

Vereisten

Installeren

npm install @azure/communication-job-router

Browserondersteuning

Als u Azure SDK-bibliotheken op een website wilt gebruiken, moet u uw code converteren om in de browser te werken. U doet dit met behulp van een hulpprogramma dat een bundler wordt genoemd. Raadpleeg onze documentatie over bundeling voor meer informatie over bundeling.

Zelfstudie: Taken routeren naar werkrollen met behulp van de AZURE COMMUNICATION SERVICES (ACS) Job Router 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.

Instellen

(Optioneel) Een IDE installeren

Installeer een IDE zoals VSCode of Webstorm.

NodeJS installeren

Installeer NodeJS.

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

Een ACS-resource hebben

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

De Azure ACS-taakrouter-SDK installeren

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

Routeringstaken

Taakrouterclients maken

Eerst moeten we een jobRouterAdministrationClient en een jobRouterClientmaken.

  • jobRouterAdministrationClient biedt methoden voor classificatiebeleid, distributiebeleid, uitzonderingsbeleid en wachtrijen.
  • jobRouterClient biedt methoden voor Taken en Werkrollen.
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);

Een distributiebeleid maken

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

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

Een classificatiebeleid maken

Dit beleid classificeert taken bij het maken.

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

Een wachtrij maken

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

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

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

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

(Optioneel) Taak maken met een classificatiebeleid

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

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

gebeurtenis

Taakrouter-gebeurtenissen worden geleverd via Azure Event Grid. Raadpleeg onze Azure Event Grid documentatie voor meer informatie over Azure Event Grid.

In het vorige voorbeeld:

  • De taak wordt verzonden naar de wachtrij 'Verkoop'.
  • Er wordt een werkrol geselecteerd om de taak af te handelen, er wordt een jobaanbieding aan die werknemer uitgegeven en er wordt een RouterWorkerOfferIssued gebeurtenis verzonden via Azure Event Grid.

Voorbeeld van RouterWorkerOfferIssued JSON-shape:

{
  "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 jobRouterClient.acceptJobOffer(workerId, offerId);
// or
const declineResponse = await jobRouterClient.declineJobOffer(workerId, offerId);

De taak voltooien

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

await jobRouterClient.completeJob(jobId, assignmentId);

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.

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

Volgende stappen

Bekijk de map met voorbeelden voor aanvullende gedetailleerde voorbeelden van het gebruik van deze SDK.

Bijdragen

Als u wilt bijdragen aan deze SDK, leest u de handleiding voor bijdragen voor meer informatie over het bouwen en testen van de code.