Biblioteka klienta REST usługi AzureCommunicationRoutingService dla języka JavaScript

Artykuł
11/22/2023

Azure Communication Routing Service

Skorzystaj z tej biblioteki w dużej mierze na naszych dokumentach klienta REST

Kluczowe linki:

Wprowadzenie

Obecnie obsługiwane środowiska

Wersje ltS Node.js

Wymagania wstępne

Aby użyć tego pakietu, musisz mieć subskrypcję platformy Azure .

Posiadanie zasobu ACS

Utwórz zasób ACS w witrynie Azure Portal lub użyj istniejącego zasobu.

Instalowanie pakietu `@azure-rest/communication-job-router`

Zainstaluj bibliotekę klienta REST klienta REST usługi AzureCommunicationRoutingService dla języka JavaScript przy użyciu polecenia npm:

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

Tworzenie i uwierzytelnianie `AzureCommunicationRoutingServiceClient`

Aby użyć poświadczeń tokenu usługi Azure Active Directory (AAD), podaj wystąpienie żądanego typu poświadczeń uzyskanego z biblioteki @azure/tożsamości .

Aby uwierzytelnić się za pomocą usługi AAD, należy najpierw npm zainstalować @azure/identity

Po skonfigurowaniu można wybrać typ poświadczeń@azure/identity do użycia. Na przykład wartość DefaultAzureCredential może służyć do uwierzytelniania klienta.

Ustaw wartości identyfikatora klienta, identyfikatora dzierżawy i wpisu tajnego klienta aplikacji usługi AAD jako zmienne środowiskowe: AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_CLIENT_SECRET

Samouczek: kierowanie zadań do procesów roboczych przy użyciu zestawu SDK REST routera zadań Azure Communication Services (ACS)

Z tego samouczka dowiesz się:

Jak utworzyć kolejkę.
Tworzenie procesów roboczych i przypisywanie ich do kolejki.
Jak kierować zadania do procesów roboczych.
Jak subskrybować zdarzenia routera zadań i obsługiwać je.
Jak wykonać i zamknąć zadania.

Uruchamianie serwera NodeJS Express

W powłoce (cmd, PowerShell, Bash itp.) utwórz folder o nazwie RouterQuickStart i wewnątrz tego folderu wykonaj polecenie npx express-generator. Spowoduje to wygenerowanie prostego projektu Express, który będzie nasłuchiwać przy użyciu elementu port 3000.

Przykład

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

Instalowanie zestawu SDK routera zadań usługi Azure ACS

W folderze RouterQuickStart zainstaluj zestaw SDK routera zadań ACS, wykonując polecenie npm install @azure-rest/communication-job-router --save.

Zadania routingu

Konstruowanie elementu AzureCommunicationRoutingServiceClient

Najpierw musimy skonstruować element 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);

Tworzenie zasad dystrybucji

Te zasady określają, którzy pracownicy otrzymają oferty pracy, ponieważ zadania są dystrybuowane poza kolejkami.

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

Tworzenie kolejki

Ta kolejka oferuje zadania pracownikom zgodnie z wcześniej utworzonymi zasadami dystrybucji.

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

Tworzenie procesów roboczych

Ci pracownicy są przypisywani do naszej wcześniej utworzonej kolejki "Sales" i mają pewne etykiety.

ustawienie availableForOffers oznacza, że true ci pracownicy są gotowi zaakceptować oferty pracy.
Zapoznaj się z naszą dokumentacją etykiet , aby lepiej zrozumieć etykiety i selektory etykiet.

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

Cykl życia zadania

Zapoznaj się z naszą dokumentacją cyklu życia zadań , aby lepiej zrozumieć cykl życia zadania.

Tworzenie zadania

To zadanie jest w kolejce do kolejki utworzonej wcześniej "Sales".

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

(Opcjonalnie) Tworzenie zadania za pomocą zasad klasyfikacji

Tworzenie zasad klasyfikacji

Te zasady klasyfikują zadania podczas tworzenia.

Zapoznaj się z naszą dokumentacją reguł , aby lepiej zrozumieć reguły określania priorytetów.

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

Tworzenie i klasyfikowanie zadania

To zadanie zostanie sklasyfikowane przy użyciu naszych wcześniej utworzonych zasad klasyfikacji. Ma również etykietę.

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

Subskrybowanie zdarzeń

Jednym ze sposobów subskrybowania zdarzeń routera zadań ACS jest użycie witryny Azure Portal.

Przejdź do zasobu ACS w witrynie Azure Portal i otwórz blok "Zdarzenia".
Dodaj subskrypcję zdarzeń dla zdarzenia "RouterWorkerOfferIssued".
Wybierz odpowiednie środki, aby odebrać zdarzenie (np. element webhook, Azure Functions, Service Bus).

Zapoznaj się z naszą dokumentacją "subskrybuj zdarzenia routera zadań" , aby lepiej zrozumieć subskrybowanie zdarzeń routera zadań.

Trasa w aplikacji NodeJS, która odbiera zdarzenia, może wyglądać następująco:

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

Zaakceptuj lub odrzuć ofertę zadania

Po otrzymaniu RouterWorkerOfferIssued zdarzenia możesz zaakceptować lub odrzucić ofertę pracy.

workerid - Identyfikator pracownika akceptującego ofertę pracy.
offerId - Identyfikator zaakceptowanej lub odrzuconej oferty.

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

Ukończ zadanie

Do assignmentId ukończenia zadania wymagane jest odebranie odpowiedzi poprzedniego kroku.

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

Zamknij zadanie

Po zakończeniu fazy opakowowania zadania jobRouterClient proces roboczy może zamknąć zadanie i dołączyć do niego kod dyspozycji na potrzeby przyszłego odwołania.

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

Rozwiązywanie problemów

Rejestrowanie

Włączenie rejestrowania może pomóc odkryć przydatne informacje o błędach. Aby wyświetlić dziennik żądań HTTP i odpowiedzi, ustaw zmienną AZURE_LOG_LEVEL środowiskową na info. Możesz też włączyć rejestrowanie w czasie wykonywania, wywołując polecenie w elemecie setLogLevel@azure/logger:

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

setLogLevel("info");

Aby uzyskać bardziej szczegółowe instrukcje dotyczące włączania dzienników, zapoznaj się z dokumentami dotyczącymi pakietu @azure/rejestratora.

Udostępnij za pośrednictwem

Biblioteka klienta REST usługi AzureCommunicationRoutingService dla języka JavaScript

Wprowadzenie

Obecnie obsługiwane środowiska

Wymagania wstępne

Posiadanie zasobu ACS

Instalowanie pakietu `@azure-rest/communication-job-router`

Tworzenie i uwierzytelnianie `AzureCommunicationRoutingServiceClient`

Samouczek: kierowanie zadań do procesów roboczych przy użyciu zestawu SDK REST routera zadań Azure Communication Services (ACS)

Uruchamianie serwera NodeJS Express

Przykład

Instalowanie zestawu SDK routera zadań usługi Azure ACS

Zadania routingu

Konstruowanie elementu AzureCommunicationRoutingServiceClient

Tworzenie zasad dystrybucji

Tworzenie kolejki

Tworzenie procesów roboczych

Cykl życia zadania

Tworzenie zadania

(Opcjonalnie) Tworzenie zadania za pomocą zasad klasyfikacji

Tworzenie zasad klasyfikacji

Tworzenie i klasyfikowanie zadania

Subskrybowanie zdarzeń

Zaakceptuj lub odrzuć ofertę zadania

Ukończ zadanie

Zamknij zadanie

Rozwiązywanie problemów

Rejestrowanie

Dodatkowe zasoby

Udostępnij za pośrednictwem

Biblioteka klienta REST usługi AzureCommunicationRoutingService dla języka JavaScript

Wprowadzenie

Obecnie obsługiwane środowiska

Wymagania wstępne

Posiadanie zasobu ACS

Instalowanie pakietu @azure-rest/communication-job-router

Tworzenie i uwierzytelnianie AzureCommunicationRoutingServiceClient

Samouczek: kierowanie zadań do procesów roboczych przy użyciu zestawu SDK REST routera zadań Azure Communication Services (ACS)

Uruchamianie serwera NodeJS Express

Przykład

Instalowanie zestawu SDK routera zadań usługi Azure ACS

Zadania routingu

Konstruowanie elementu AzureCommunicationRoutingServiceClient

Tworzenie zasad dystrybucji

Tworzenie kolejki

Tworzenie procesów roboczych

Cykl życia zadania

Tworzenie zadania

(Opcjonalnie) Tworzenie zadania za pomocą zasad klasyfikacji

Tworzenie zasad klasyfikacji

Tworzenie i klasyfikowanie zadania

Subskrybowanie zdarzeń

Zaakceptuj lub odrzuć ofertę zadania

Ukończ zadanie

Zamknij zadanie

Rozwiązywanie problemów

Rejestrowanie

Dodatkowe zasoby

Instalowanie pakietu `@azure-rest/communication-job-router`

Tworzenie i uwierzytelnianie `AzureCommunicationRoutingServiceClient`