JavaScript için AzureCommunicationRoutingService REST istemci kitaplığı

  • Makale

Azure İletişim Yönlendirme Hizmeti

Lütfen bu kitaplığı kullanmak için REST istemci belgelerimize yoğun bir şekilde güvenin

Önemli bağlantılar:

Başlarken

Şu anda desteklenen ortamlar

  • Node.js LTS sürümleri

Önkoşullar

ACS Kaynağınız Var

Azure Portal'da bir ACS kaynağı oluşturun veya mevcut bir kaynağı kullanın.

@azure-rest/communication-job-router paketini yükleyin

ile npmJavaScript için AzureCommunicationRoutingService REST istemci REST istemci kitaplığını yükleyin:

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

Oluşturma ve kimlik doğrulaması AzureCommunicationRoutingServiceClient

Azure Active Directory (AAD) belirteci kimlik bilgilerini kullanmak için, @azure/kimlik kitaplığından alınan istenen kimlik bilgisi türünün bir örneğini sağlayın.

AAD ile kimlik doğrulaması yapmak için önce npm@azure/identity

Kurulumdan sonra, hangi kimlik bilgisi@azure/identity türünün kullanılacağını seçebilirsiniz. Örneğin, istemcinin kimliğini doğrulamak için DefaultAzureCredential kullanılabilir.

AAD uygulamasının istemci kimliği, kiracı kimliği ve istemci gizli dizisi değerlerini ortam değişkenleri olarak ayarlayın: AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_CLIENT_SECRET

Öğretici: Azure İletişim Hizmetleri (ACS) İş Yönlendiricisi Rest SDK'sını kullanarak işleri çalışanlara yönlendirme

Bu öğreticide şunları öğreneceksiniz:

  • Kuyruk oluşturma.
  • Çalışan oluşturma ve bir kuyruğa atama.
  • İşleri çalışanlara yönlendirme.
  • İş Yönlendiricisi olaylarına abone olma ve olayları işleme.
  • İşleri tamamlama ve kapatma.

NodeJS Express sunucusu başlatma

Bir kabukta (cmd, PowerShell, Bash vb.), adlı bir klasör RouterQuickStart oluşturun ve bu klasörün içinde komutunu yürütür npx express-generator. Bu, üzerinde port 3000dinleyecek basit bir Express projesi oluşturur.

Örnek

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

Azure ACS İş YönlendiriciSI SDK'sını yükleme

RouterQuickStart klasöründe, yürüterek ACS İş Yönlendirici SDK'sını npm install @azure-rest/communication-job-router --saveyükleyin.

Yönlendirme İşleri

AzureCommunicationRoutingServiceClient Oluşturma

İlk olarak bir AzureCommunicationRoutingServiceClientoluşturmamız gerekir.

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

Dağıtım İlkesi Oluşturma

Bu ilke, işler kuyruklarından dağıtıldığında hangi çalışanların iş tekliflerini alacağını belirler.

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

Kuyruk oluşturma

Bu kuyruk, daha önce oluşturulmuş dağıtım ilkemize göre çalışanlara işler sunar.

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

Çalışan Oluşturma

Bu çalışanlar daha önce oluşturulan "Satış" kuyruğumuza atanır ve bazı etiketlere sahiptir.

  • true ayarıavailableForOffers, bu çalışanların iş tekliflerini kabul etmeye hazır olduğu anlamına gelir.
  • etiketleri ve etiket seçicileri daha iyi anlamak için etiketler belgelerimize bakın.
  // 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,
      },
    ],
  }
});

İş Yaşam Döngüsü

bir işin yaşam döngüsünü daha iyi anlamak için iş yaşam döngüsü belgelerimize bakın .

İş Oluşturma

Bu iş, daha önce oluşturulmuş "Satışlar" kuyruğumuzda sıralanır.

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

(İsteğe bağlı) Sınıflandırma İlkesi ile İş Oluşturma

Sınıflandırma İlkesi Oluşturma

Bu ilke, oluşturma sırasında işleri sınıflandırır.

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

İş oluşturma ve sınıflandırma

Bu iş, daha önce oluşturulmuş sınıflandırma ilkemizle sınıflandırılır. Ayrıca bir etiketi vardır.

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

Olaylara Abone Olma

ACS İş Yönlendiricisi olaylarına abone olma yollarından biri Azure Portal'ı kullanmaktır.

  1. Azure Portalı'nda ACS kaynağınıza gidin ve "Olaylar" dikey penceresini açın.
  2. "RouterWorkerOfferIssued" olayı için bir olay aboneliği ekleyin.
  3. Olayı almak için uygun bir araç seçin (örn. Web kancası, Azure İşlevleri, Service Bus).

İş Yönlendiricisi olaylarına abone olmayı daha iyi anlamak için "İş Yönlendiricisi olaylarına abone olma" belgelerimize bakın.

NodeJS uygulamanızda olayları alan yol şuna benzer olabilir:

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

İş Teklifini Kabul Etme veya Reddetme

Bir RouterWorkerOfferIssued etkinlik aldıktan sonra iş teklifini kabul edebilir veya reddedebilirsiniz.

  • workerid - İş teklifini kabul eden çalışanın kimliği.
  • offerId - Kabul edilen veya reddedilen teklifin kimliği.
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();

İşi Tamamlama

İşi assignmentId tamamlamak için önceki adımın yanıtından alınan gereklidir.

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

İşi Kapatma

Çalışan işin sarmalama aşamasını tamamladıktan sonra işi jobRouterClient kapatabilir ve ileride başvurmak üzere buna bir değerlendirme kodu ekleyebilir.

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

Sorun giderme

Günlüğe Kaydetme

Günlüğe kaydetmenin etkinleştirilmesi hatalarla ilgili yararlı bilgilerin ortaya çıkarılmasına yardımcı olabilir. HTTP isteklerinin ve yanıtlarının günlüğünü görmek için ortam değişkenini AZURE_LOG_LEVEL olarak infoayarlayın. Alternatif olarak, günlüğü çalışma zamanında içinde çağrılarak setLogLevel@azure/loggeretkinleştirilebilir:

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

setLogLevel("info");

Günlükleri etkinleştirme hakkında daha ayrıntılı yönergeler için @azure/günlükçü paketi belgelerine bakabilirsiniz.