AzureCommunicationRoutingService REST-klientbibliotek för JavaScript

Artikel
11/22/2023

Azure Communication Routing Service

Förlita dig starkt på våra REST-klientdokument för att använda det här biblioteket

Nyckellänkar:

Komma igång

Miljöer som stöds för närvarande

LTS-versioner av Node.js

Förutsättningar

Du måste ha en Azure-prenumeration för att kunna använda det här paketet.

Ha en ACS-resurs

Skapa en ACS-resurs i Azure-portalen eller använd en befintlig resurs.

Installera `@azure-rest/communication-job-router`-paketet

Installera REST-klientbiblioteket för AzureCommunicationRoutingService REST för JavaScript med npm:

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

Skapa och autentisera en `AzureCommunicationRoutingServiceClient`

Om du vill använda en AAD-tokenautentisering (Azure Active Directory) anger du en instans av önskad typ av autentiseringsuppgifter som hämtats från @azure/identitetsbiblioteket .

Om du vill autentisera med AAD måste du först npm installera @azure/identity

Efter installationen kan du välja vilken typ av autentiseringsuppgifter du @azure/identity vill använda. StandardAzureCredential kan till exempel användas för att autentisera klienten.

Ange värdena för klient-ID, klient-ID och klienthemlighet för AAD-programmet som miljövariabler: AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_CLIENT_SECRET

Självstudie: Dirigera jobb till arbetare med hjälp av Azure Communication Services (ACS) Rest SDK för jobbrouter

I den här kursen lär du dig:

Så här skapar du en kö.
Så här skapar du arbetare och tilldelar dem till en kö.
Så här dirigerar du jobb till arbetare.
Så här prenumererar du på och hanterar jobbrouterhändelser.
Så här slutför och stänger du jobb.

Starta en NodeJS Express-server

I ett gränssnitt (cmd, PowerShell, Bash osv.) skapar du en mapp med namnet RouterQuickStart och kör npx express-generatori den här mappen . Detta genererar ett enkelt Express-projekt som lyssnar på port 3000.

Exempel

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

Installera Azure ACS Job Router SDK

RouterQuickStart Installera ACS Job Router SDK i mappen genom att npm install @azure-rest/communication-job-router --saveköra .

Routningsjobb

Skapa AzureCommunicationRoutingServiceClient

Först måste vi skapa en AzureCommunicationRoutingServiceClient.

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

Skapa en distributionsprincip

Den här principen avgör vilka arbetare som ska få jobberbjudanden när jobb distribueras från sina köer.

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

Skapa en kö

Den här kön erbjuder jobb till arbetare enligt vår tidigare skapade distributionsprincip.

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

Skapa arbetare

Dessa arbetare tilldelas till vår tidigare skapade "Sales"-kö och har några etiketter.

innebär availableForOffers att true dessa arbetstagare är redo att acceptera jobberbjudanden.
Se dokumentationen för etiketter för att bättre förstå etiketter och etikettväljare.

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

Jobblivscykel

Läs vår dokumentation om jobblivscykeln för att bättre förstå livscykeln för ett jobb.

Skapa ett jobb

Det här jobbet visas i vår tidigare skapade "Sales"-kö.

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

(Valfritt) Skapa jobb med en klassificeringsprincip

Skapa en klassificeringsprincip

Den här principen klassificerar jobb när de skapas.

Läs vår regeldokumentation för att bättre förstå prioriteringsregler.

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

Skapa och klassificera jobb

Det här jobbet kommer att klassificeras med vår tidigare skapade klassificeringsprincip. Den har också en etikett.

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

Prenumerera på händelser

Ett sätt att prenumerera på ACS-jobbrouterhändelser är via Azure-portalen.

Gå till din ACS-resurs i Azure-portalen och öppna bladet Händelser.
Lägg till en händelseprenumeration för händelsen "RouterWorkerOfferIssued".
Välj ett lämpligt sätt att ta emot händelsen (t.ex. Webhook, Azure Functions, Service Bus).

Läs vår dokumentation om att prenumerera på jobbroutrar för att bättre förstå prenumerationen på Job Router-händelser.

Vägen i nodeJS-programmet som tar emot händelser kan se ut ungefär så här:

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

Acceptera eller avvisa jobberbjudandet

När du får ett RouterWorkerOfferIssued evenemang kan du acceptera eller avvisa jobberbjudandet.

workerid - ID:t för arbetstagaren som accepterar jobberbjudandet.
offerId - ID för erbjudandet accepteras eller avvisas.

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

Slutför jobbet

Det assignmentId mottagna svaret från föregående steg krävs för att slutföra jobbet.

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

Stäng jobbet

När arbetaren har slutfört omslutningsfasen för jobbet jobRouterClient kan du stänga jobbet och koppla en dispositionskod till det för framtida referens.

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

Felsökning

Loggning

Aktivering av loggning kan hjälpa dig att hitta användbar information om fel. Om du vill se en logg över HTTP-begäranden och svar anger du AZURE_LOG_LEVEL miljövariabeln till info. Du kan också aktivera loggning vid körning genom att anropa setLogLevel i @azure/logger:

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

setLogLevel("info");

Mer detaljerade anvisningar om hur du aktiverar loggar finns i @azure-/loggningspaketdokumenten.

Dela via

AzureCommunicationRoutingService REST-klientbibliotek för JavaScript

Komma igång

Miljöer som stöds för närvarande

Förutsättningar

Ha en ACS-resurs

Installera `@azure-rest/communication-job-router`-paketet

Skapa och autentisera en `AzureCommunicationRoutingServiceClient`

Självstudie: Dirigera jobb till arbetare med hjälp av Azure Communication Services (ACS) Rest SDK för jobbrouter

Starta en NodeJS Express-server

Exempel

Installera Azure ACS Job Router SDK

Routningsjobb

Skapa AzureCommunicationRoutingServiceClient

Skapa en distributionsprincip

Skapa en kö

Skapa arbetare

Jobblivscykel

Skapa ett jobb

(Valfritt) Skapa jobb med en klassificeringsprincip

Skapa en klassificeringsprincip

Skapa och klassificera jobb

Prenumerera på händelser

Acceptera eller avvisa jobberbjudandet

Slutför jobbet

Stäng jobbet

Felsökning

Loggning

Ytterligare resurser

Dela via

AzureCommunicationRoutingService REST-klientbibliotek för JavaScript

Komma igång

Miljöer som stöds för närvarande

Förutsättningar

Ha en ACS-resurs

Installera @azure-rest/communication-job-router-paketet

Skapa och autentisera en AzureCommunicationRoutingServiceClient

Självstudie: Dirigera jobb till arbetare med hjälp av Azure Communication Services (ACS) Rest SDK för jobbrouter

Starta en NodeJS Express-server

Exempel

Installera Azure ACS Job Router SDK

Routningsjobb

Skapa AzureCommunicationRoutingServiceClient

Skapa en distributionsprincip

Skapa en kö

Skapa arbetare

Jobblivscykel

Skapa ett jobb

(Valfritt) Skapa jobb med en klassificeringsprincip

Skapa en klassificeringsprincip

Skapa och klassificera jobb

Prenumerera på händelser

Acceptera eller avvisa jobberbjudandet

Slutför jobbet

Stäng jobbet

Felsökning

Loggning

Ytterligare resurser

Installera `@azure-rest/communication-job-router`-paketet

Skapa och autentisera en `AzureCommunicationRoutingServiceClient`