JavaScript 用 AzureCommunicationRoutingService REST クライアントライブラリ

[アーティクル]
11/22/2023

Azure Communication Routing Service

このライブラリを使用するには、 REST クライアントドキュメントに大きく依存してください

主要リンク:

はじめに

現在サポートされている環境

Node.js の LTS バージョン

前提条件

このパッケージを使用するには、Azure サブスクリプションが必要です。

ACS リソースを使用する

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

`@azure-rest/communication-job-router` パッケージのインストール

を使用して、JavaScript 用の AzureCommunicationRoutingService REST クライアント REST クライアントライブラリを npmインストールします。

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

`AzureCommunicationRoutingServiceClient` を作成して認証する

Azure Active Directory (AAD) トークン資格情報を使用するには、@azure/ID ライブラリから取得した目的の資格情報の種類のインスタンスを指定します。

AAD で認証するには、最初 npm にをインストールする必要があります。 @azure/identity

セットアップ後、使用する資格情報@azure/identityの種類を選択できます。たとえば、 DefaultAzureCredential を使用してクライアントを認証できます。

AAD アプリケーションのクライアント ID、テナント ID、クライアントシークレットの値を環境変数として設定します(AZURE_CLIENT_ID、AZURE_TENANT_ID、AZURE_CLIENT_SECRET

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

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

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

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

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

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

ルーティングジョブ

AzureCommunicationRoutingServiceClient を構築する

まず、を構築する必要があります 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);

配布ポリシーを作成する

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

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

キューを作成する

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

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

Worker の作成

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

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

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

ジョブのライフサイクル

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

ジョブを作成する

このジョブは、以前に作成した "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: {},
  }
});

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

分類ポリシーを作成する

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

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

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

ジョブの作成と分類

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

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

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

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

ジョブを完了する

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

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

ジョブを閉じる

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

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

トラブルシューティング

ログ記録

ログの記録を有効にすると、エラーに関する有用な情報を明らかにするのに役立つ場合があります。 HTTP 要求と応答のログを表示するには、環境変数 AZURE_LOG_LEVEL を info に設定します。または、@azure/logger で setLogLevel を呼び出して、実行時にログ記録を有効にすることもできます。

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

setLogLevel("info");

ログを有効にする方法の詳細については、@azure/logger パッケージに関するドキュメントを参照してください。

次の方法で共有

JavaScript 用 AzureCommunicationRoutingService REST クライアントライブラリ

はじめに

現在サポートされている環境

前提条件

ACS リソースを使用する

`@azure-rest/communication-job-router` パッケージのインストール

`AzureCommunicationRoutingServiceClient` を作成して認証する

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

NodeJS Express サーバーを起動する

例

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

ルーティングジョブ

AzureCommunicationRoutingServiceClient を構築する

配布ポリシーを作成する

キューを作成する

Worker の作成

ジョブのライフサイクル

ジョブを作成する

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

分類ポリシーを作成する

ジョブの作成と分類

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

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

ジョブを完了する

ジョブを閉じる

トラブルシューティング

ログ記録

その他のリソース

次の方法で共有

JavaScript 用 AzureCommunicationRoutingService REST クライアント ライブラリ

はじめに

現在サポートされている環境

前提条件

ACS リソースを使用する

@azure-rest/communication-job-router パッケージのインストール

AzureCommunicationRoutingServiceClient を作成して認証する

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

NodeJS Express サーバーを起動する

例

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

ルーティング ジョブ

AzureCommunicationRoutingServiceClient を構築する

配布ポリシーを作成する

キューを作成する

Worker の作成

ジョブのライフサイクル

ジョブを作成する

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

分類ポリシーを作成する

ジョブの作成と分類

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

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

ジョブを完了する

ジョブを閉じる

トラブルシューティング

ログ記録

その他のリソース

JavaScript 用 AzureCommunicationRoutingService REST クライアントライブラリ

`@azure-rest/communication-job-router` パッケージのインストール

`AzureCommunicationRoutingServiceClient` を作成して認証する

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

ルーティングジョブ