Azure Communication Services (ACS) Job Router SDK for JavaScript

[アーティクル]
08/02/2023

このパッケージには、Azure Communication Services (ACS) ジョブルーターサービス用の JavaScript SDK が含まれています。

作業の開始

主要概念

ジョブルーターの主な概念に関するドキュメントを参照して、ジョブルーターについて理解を深めてください。

前提条件

Azure サブスクリプション。
Azure Communication Services (ACS) リソース。
- ACS リソースを作成する必要がある場合は、Azure Portal、Azure PowerShell、または Azure CLI を使用できます。

［インストール中］

npm install @azure/communication-job-router

ブラウザーのサポート

Web サイトで Azure SDK ライブラリを使用するには、ブラウザー内で動作するようにコードを変換する必要があります。これを行うには、 bundler というツールを使用します。バンドルについて理解を深めるために、バンドルに関するドキュメントを参照してください。

チュートリアル:Azure Communication Services (ACS) ジョブルーター SDK を使用してジョブをワーカーにルーティングする

このチュートリアルでは、次の事項について説明します。

キューを作成する方法。
ワーカーを作成してキューに割り当てる方法。
ジョブをワーカーにルーティングする方法。
ジョブルーターイベントをサブスクライブして処理する方法。
ジョブを完了して閉じる方法。

設定

(省略可能)IDE をインストールする

VSCode や Webstorm などの IDE をインストールします。

NodeJS のインストール

NodeJS をインストールします。

NodeJS Express サーバーを起動する

シェル (cmd、PowerShell、Bash など) で、という名前 RouterQuickStart のフォルダーを作成し、このフォルダー内にを実行 npx express-generatorします。これにより、でリッスン port 3000する単純な Express プロジェクトが生成されます。

例

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

ACS リソースを使用する

Azure Portal で ACS リソースを作成するか、既存のリソースを使用します。

Azure ACS ジョブルーター SDK をインストールする

フォルダーに RouterQuickStart 、を実行して ACS ジョブルーター SDK を npm install @azure/communication-job-router --saveインストールします。

ルーティングジョブ

ジョブルータークライアントの構築

まず、とを jobRouterAdministrationClient 構築する必要があります jobRouterClient。

jobRouterAdministrationClient には、分類ポリシー、配布ポリシー、例外ポリシー、キューのメソッドが用意されています。
jobRouterClient には、ジョブと Worker のメソッドが用意されています。

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

配布ポリシーを作成する

このポリシーは、ジョブがキューから分散される際に、どのワーカーがジョブオファーを受け取るかを決定します。

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

分類ポリシーを作成する

このポリシーは、作成時にジョブを分類します。

優先順位付け規則について理解を深めるために、ルールのドキュメントを参照してください。

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

キューを作成する

このキューは、以前に作成した配布ポリシーに従って、ワーカーにジョブを提供します。

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

Worker の作成

これらのワーカーは、以前に作成した "Sales" キューに割り当てられ、いくつかのラベルがあります。

をに設定 availableForOffers すると true 、これらのワーカーはジョブオファーを受け入れる準備が整います。
ラベルとラベルセレクターについて理解を深めるために、ラベルのドキュメントを参照してください。

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

ジョブのライフサイクル

ジョブのライフサイクルをより深く理解するには、ジョブのライフサイクルに関するドキュメントを参照してください。

ジョブを作成する

このジョブは、以前に作成した "Sales" キューにエンキューされます。

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

(省略可能)分類ポリシーを使用してジョブを作成する

このジョブは、以前に作成した分類ポリシーで分類されます。また、ラベルもあります。

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

events

ジョブルーターイベントは、Azure Event Grid経由で配信されます。 Azure Event Gridについて理解を深めるために、Azure Event Gridドキュメントを参照してください。

前の例を使うと、次のようになります。

ジョブは "Sales" キューにエンキューされます。
ジョブを処理するためにワーカーが選択され、そのワーカーにジョブオファーが発行されRouterWorkerOfferIssued、Azure Event Grid経由でイベントが送信されます。

JSON 図形の例 RouterWorkerOfferIssued :

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

イベントのサブスクライブ

ACS ジョブルーターイベントをサブスクライブする方法の 1 つは、Azure Portal を使用することです。

Azure Portal で ACS リソースに移動し、[イベント] ブレードを開きます。
"RouterWorkerOfferIssued" イベントのイベントサブスクリプションを追加します。
イベントを受け取る適切な手段 (Webhook、Azure Functions、Service Bus など) を選択します。

ジョブルーターイベントのサブスクライブについて理解を深めるために、「ジョブルーターイベントをサブスクライブする」ドキュメントを参照してください。

イベントを受信する NodeJS アプリケーション内のルートは、次のようになります。

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

求人を承諾または辞退する

イベントを受け取ったら、 RouterWorkerOfferIssued ジョブオファーを承諾または拒否できます。

workerid - ジョブオファーを受け入れるワーカーの ID。
offerId - 承諾または拒否されるオファーの ID。

const acceptResponse = await jobRouterClient.acceptJobOffer(workerId, offerId);
// or
const declineResponse = await jobRouterClient.declineJobOffer(workerId, offerId);

ジョブを完了する

ジョブを assignmentId 完了するには、前の手順の応答から受信したが必要です。

await jobRouterClient.completeJob(jobId, assignmentId);

ジョブを閉じる

ワーカーがジョブのラップアップフェーズを完了したら、 jobRouterClient はジョブを閉じて、後で参照できるように処理コードをアタッチできます。

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

次の手順

この SDK の使用に関するその他の詳細な例については、 samples ディレクトリを参照してください。

共同作成

この SDK に投稿する場合は、コードをビルドしてテストする方法の詳細については、投稿ガイドを参照してください。

Microsoft Azure SDK for JavaScript

次の方法で共有

Azure Communication Services (ACS) Job Router SDK for JavaScript

作業の開始

主要概念

前提条件

［インストール中］

ブラウザーのサポート

チュートリアル:Azure Communication Services (ACS) ジョブルーター SDK を使用してジョブをワーカーにルーティングする

設定

(省略可能)IDE をインストールする

NodeJS のインストール

NodeJS Express サーバーを起動する

例

ACS リソースを使用する

Azure ACS ジョブルーター SDK をインストールする

ルーティングジョブ

ジョブルータークライアントの構築

配布ポリシーを作成する

分類ポリシーを作成する

キューを作成する

Worker の作成

ジョブのライフサイクル

ジョブを作成する

(省略可能)分類ポリシーを使用してジョブを作成する

events

イベントのサブスクライブ

求人を承諾または辞退する

ジョブを完了する

ジョブを閉じる

次の手順

共同作成

フィードバック

その他のリソース

次の方法で共有

Azure Communication Services (ACS) Job Router SDK for JavaScript

作業の開始

主要概念

前提条件

［インストール中］

ブラウザーのサポート

チュートリアル:Azure Communication Services (ACS) ジョブ ルーター SDK を使用してジョブをワーカーにルーティングする

設定

(省略可能)IDE をインストールする

NodeJS のインストール

NodeJS Express サーバーを起動する

例

ACS リソースを使用する

Azure ACS ジョブ ルーター SDK をインストールする

ルーティング ジョブ

ジョブ ルーター クライアントの構築

配布ポリシーを作成する

分類ポリシーを作成する

キューを作成する

Worker の作成

ジョブのライフサイクル

ジョブを作成する

(省略可能)分類ポリシーを使用してジョブを作成する

events

イベントのサブスクライブ

求人を承諾または辞退する

ジョブを完了する

ジョブを閉じる

次の手順

共同作成

関連プロジェクト

フィードバック

その他のリソース

チュートリアル:Azure Communication Services (ACS) ジョブルーター SDK を使用してジョブをワーカーにルーティングする

Azure ACS ジョブルーター SDK をインストールする

ルーティングジョブ

ジョブルータークライアントの構築