다음을 통해 공유

JavaScript용 ACS(Azure Communication Services) 작업 라우터 SDK

  • 아티클

이 패키지에는 ACS(Azure Communication Services) 작업 라우터 서비스에 대한 JavaScript SDK가 포함되어 있습니다.

시작하기

주요 개념

작업 라우터를 더 잘 이해하려면 작업 라우터 키 개념 설명서를 참조하세요.

사전 요구 사항

설치

npm install @azure/communication-job-router

브라우저 지원

웹 사이트에서 Azure SDK 라이브러리를 사용하려면 브라우저 내에서 작동하도록 코드를 변환해야 합니다. 번들러라는 도구를 사용하여 이 작업을 수행합니다. 번들링을 더 잘 이해하려면 번들 설명서를 참조하세요.

자습서: ACS(Azure Communication Services) 작업 라우터 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.

라우팅 작업

작업 라우터 클라이언트 생성

먼저 및 jobRouterClient을 jobRouterAdministrationClient 생성해야 합니다.

  • jobRouterAdministrationClient 는 분류 정책, 배포 정책, 예외 정책 및 큐에 대한 메서드를 제공합니다.
  • jobRouterClient 는 작업 및 작업자에 대한 메서드를 제공합니다.
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",
  },
});

작업자 만들기

이러한 작업자는 이전에 만든 "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",
  },
});

이벤트

작업 라우터 이벤트는 Azure Event Grid 통해 전달됩니다. Azure Event Grid 더 잘 이해하려면 Azure Event Grid 설명서를 참조하세요.

이전 예제:

  • 작업이 "Sales" 큐에 큐에 추가됩니다.
  • 작업을 처리하도록 작업자가 선택되고, 작업 제안이 해당 작업자에게 발급되고RouterWorkerOfferIssued, 이벤트가 Azure Event Grid 통해 전송됩니다.

예제 RouterWorkerOfferIssued 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 작업 라우터 이벤트를 구독하는 한 가지 방법은 Azure Portal을 사용하는 것입니다.

  1. Azure Portal에서 ACS 리소스로 이동하여 "이벤트" 블레이드를 엽니다.
  2. "RouterWorkerOfferIssued" 이벤트에 대한 이벤트 구독을 추가합니다.
  3. 이벤트를 수신할 적절한 방법을 선택합니다(예: 웹후크, 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 사용에 대한 자세한 예제는 샘플 디렉터리를 살펴보세요.

참여

이 SDK에 기여하려면 기여 가이드 를 참조하여 코드를 빌드하고 테스트하는 방법에 대해 자세히 알아보세요.