Bagikan melalui

Pustaka klien AzureCommunicationRoutingService REST untuk JavaScript

  • Artikel

Azure Communication Routing Service

Harap sangat bergantung pada dokumen klien REST kami untuk menggunakan pustaka ini

Tautan utama:

Memulai

Lingkungan yang didukung saat ini

  • Versi LTS dari Node.js

Prasyarat

Memiliki Sumber Daya ACS

Buat sumber daya ACS di Portal Microsoft Azure atau gunakan sumber daya yang sudah ada.

Pasang paket @azure-rest/communication-job-router

Instal pustaka klien REST klien Rest AzureCommunicationRoutingService untuk JavaScript dengan npm:

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

Membuat dan mengautentikasi AzureCommunicationRoutingServiceClient

Untuk menggunakan kredensial token Azure Active Directory (AAD), berikan instans jenis kredensial yang diinginkan yang diperoleh dari pustaka @azure/identitas .

Untuk mengautentikasi dengan AAD, Anda harus menginstal terlebih dahulu npm@azure/identity

Setelah penyiapan, Anda dapat memilih jenis kredensial@azure/identity mana yang akan digunakan. Sebagai contoh, DefaultAzureCredential dapat digunakan untuk mengautentikasi klien.

Atur nilai ID klien, ID penyewa, dan rahasia klien aplikasi AAD sebagai variabel lingkungan: AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_CLIENT_SECRET

Tutorial: Merutekan pekerjaan ke pekerja menggunakan Job Router Rest SDK Azure Communication Services (ACS)

Dalam tutorial ini, Anda akan mempelajari:

  • Cara membuat antrean.
  • Cara membuat pekerja dan menetapkannya ke antrean.
  • Cara merutekan pekerjaan ke pekerja.
  • Cara berlangganan dan menangani peristiwa Job Router.
  • Cara menyelesaikan dan menutup pekerjaan.

Memulai server NodeJS Express

Dalam shell (cmd, PowerShell, Bash, dll.), buat folder yang disebut RouterQuickStart dan di dalam folder ini jalankan npx express-generator. Ini akan menghasilkan proyek Ekspres sederhana yang akan mendengarkan di port 3000.

Contoh

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

Menginstal SDK Router Pekerjaan Azure ACS

RouterQuickStart Di folder , instal ACS Job Router SDK dengan mengeksekusi npm install @azure-rest/communication-job-router --save.

Pekerjaan Perutean

Membangun AzureCommunicationRoutingServiceClient

Pertama kita perlu membuat 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);

Membuat Kebijakan Distribusi

Kebijakan ini menentukan pekerja mana yang akan menerima penawaran pekerjaan karena pekerjaan didistribusikan dari antrean mereka.

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

Membuat Antrean

Antrean ini menawarkan pekerjaan kepada pekerja sesuai dengan kebijakan distribusi yang dibuat sebelumnya.

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

Membuat Pekerja

Pekerja ini ditetapkan ke antrean "Penjualan" yang dibuat sebelumnya dan memiliki beberapa label.

  • pengaturan availableForOffers ke true berarti pekerja ini siap untuk menerima penawaran pekerjaan.
  • lihat dokumentasi label kami untuk lebih memahami label dan pemilih label.
  // 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,
      },
    ],
  }
});

Siklus Hidup Pekerjaan

Lihat dokumentasi siklus hidup pekerjaan kami untuk lebih memahami siklus hidup pekerjaan.

Membuat Pekerjaan

Pekerjaan ini diantrekan pada antrean "Penjualan" yang dibuat sebelumnya.

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

(Opsional) Membuat Pekerjaan Dengan Kebijakan Klasifikasi

Membuat Kebijakan Klasifikasi

Kebijakan ini mengklasifikasikan pekerjaan setelah pembuatan.

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

Membuat dan mengklasifikasikan pekerjaan

Pekerjaan ini akan diklasifikasikan dengan kebijakan klasifikasi yang dibuat sebelumnya. Ini juga memiliki 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"
}

Berlangganan Peristiwa

Salah satu cara untuk berlangganan peristiwa ACS Job Router adalah melalui Portal Microsoft Azure.

  1. Navigasikan ke sumber daya ACS Anda di Portal Microsoft Azure dan buka bilah "Peristiwa".
  2. Tambahkan langganan peristiwa untuk peristiwa "RouterWorkerOfferIssued".
  3. Pilih sarana yang sesuai untuk menerima peristiwa (misalnya Webhook, Azure Functions, Bus Layanan).

Lihat dokumentasi "berlangganan peristiwa Job Router" kami untuk lebih memahami berlangganan peristiwa Job Router.

Rute di aplikasi NodeJS Anda yang menerima peristiwa mungkin terlihat seperti ini:

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

Menerima atau Menolak Penawaran Pekerjaan

Setelah menerima RouterWorkerOfferIssued acara, Anda dapat menerima atau menolak penawaran pekerjaan.

  • workerid - Id pekerja yang menerima penawaran pekerjaan.
  • offerId - Id penawaran yang diterima atau ditolak.
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();

Menyelesaikan Pekerjaan

Respons assignmentId yang diterima dari langkah sebelumnya diperlukan untuk menyelesaikan pekerjaan.

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

Tutup Pekerjaan

Setelah pekerja menyelesaikan fase pembungkusan pekerjaan jobRouterClient , dapat menutup pekerjaan dan melampirkan kode disposisi ke sana untuk referensi di masa mendatang.

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

Pemecahan Masalah

Pencatatan

Mengaktifkan pengelogan dapat membantu menemukan informasi yang berguna tentang kegagalan. Untuk melihat log permintaan dan respons HTTP, atur variabel lingkungan AZURE_LOG_LEVEL ke info. Atau, pengelogan dapat diaktifkan saat runtime dengan memanggil setLogLevel di @azure/logger:

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

setLogLevel("info");

Untuk instruksi lebih rinci tentang cara mengaktifkan log, Anda dapat melihat dokumen paket @azure/pencatat.