Клиентская библиотека пакета Azure JobRouter для Python версии 1.0.0

Статья
11/22/2023

Этот пакет содержит пакет SDK python для Службы коммуникации Azure для JobRouter. Дополнительные сведения о Службы коммуникации Azure см. здесь.

Исходный код | Пакет (Pypi) | Документация по продукту

Заявление об отказе

Поддержка пакетов Python для Пакета Sdk Azure для Python 2.7 закончилась 1 января 2022 г. Дополнительные сведения и вопросы см. на https://github.com/Azure/azure-sdk-for-python/issues/20691

Начало работы

Предварительные требования

Для использования этого пакета вам потребуется подписка Azure и ресурс службы коммуникации .

Для использования этого пакета требуется Python 3.7 или более поздней версии. Дополнительные сведения см. на нашей странице о политике поддержки версий Пакета AZURE SDK для Python.
Чтобы создать службу коммуникации, можно использовать портал Azure, Azure PowerShell

Установка пакета

Установите клиентную библиотеку Azure JobRouter для Python с помощью pip:

pip install azure-communication-jobrouter

Основные понятия

Задание

Задание представляет единицу работы, которую необходимо перенаправить в доступную рабочую роль. Реальным примером этого может быть входящий звонок или чат в контексте центра обработки вызовов.

Рабочий узел

Рабочая роль представляет источник, доступный для обработки задания. Каждая рабочая роль регистрируется в очередях или более для получения заданий. Реальным примером этого может быть агент, работающий в центре обработки вызовов.

Очередь

Очередь представляет упорядоченный список заданий, ожидающих обработки работником. Рабочие будут регистрироваться в очереди, чтобы получить от нее работу. Реальным примером этого может быть очередь вызовов в центре обработки вызовов.

Channel

Канал представляет группирование заданий по определенному типу. Когда рабочая роль регистрируется для получения работы, он также должен указать, для каких каналов он может обрабатывать работу и сколько из них может обрабатываться параллельно. Реальный пример этого может быть voice calls или chats в центре обработки вызовов.

ПРЕДЛОЖЕНИЕ

Предложение распространяется JobRouter на рабочую роль для обработки определенного задания при определении соответствия. Обычно это уведомление доставляется через EventGrid. Рабочая роль может либо принять, либо отклонить предложение с помощью API JobRouter, либо срок его действия истечет в соответствии с сроком жизни, настроенным в политике распространения. Реальным примером этого может быть звонок агента в центре обработки вызовов.

Политика распространения

Политика распространения представляет набор конфигурации, который управляет распределением заданий в очереди между рабочими ролей, зарегистрированными в этой очереди. Эта конфигурация включает срок действия предложения до истечения срока действия и режим распространения, определяющий порядок выбора рабочих ролей при наличии нескольких доступных.

Режим распределения

Три типа режимов:

Циклический перебор: рабочие упорядочены по Id и выбирается следующий работник после предыдущего, который получил предложение.
Самый длинный простаив: работник, который не работал на задании дольше всего.
Лучшая рабочая роль. Вы можете указать выражение для сравнения двух рабочих ролей, чтобы определить, какую из них выбрать.

Метки

Метки можно прикрепить к рабочим ролям, заданиям и очередям. Это пары значений ключей string, которые могут иметь типы данных или numberboolean . Реальным примером этого может быть уровень квалификации конкретного работника, команда или географическое расположение.

Селекторы меток

Селекторы меток можно прикрепить к заданию, чтобы выбрать подмножество рабочих ролей, обслуживающих очередь. Реальный пример этого может быть условием при входящем вызове, что агент должен иметь минимальный уровень знаний о конкретном продукте.

Политика классификации

Политику классификации можно использовать для динамического выбора очереди, определения приоритета задания и селекторов меток рабочей роли к заданию с помощью подсистемы правил.

Политика исключений

Политика исключений управляет поведением задания на основе триггера и выполняет требуемое действие. Политика исключений присоединяется к очереди, чтобы управлять поведением заданий в очереди.

Примеры

Инициализация клиента

Чтобы инициализировать клиент SMS, можно использовать строка подключения для создания экземпляра. Кроме того, можно использовать проверку подлинности Active Directory с помощью DefaultAzureCredential.

from azure.communication.jobrouter import (
    JobRouterClient,
    JobRouterAdministrationClient
)

connection_string = "endpoint=ENDPOINT;accessKey=KEY"
router_client = JobRouterClient.from_connection_string(conn_str = connection_string)
router_admin_client = JobRouterAdministrationClient.from_connection_string(conn_str = connection_string)

Политика распространения

Прежде чем создать очередь, нам потребуется политика распространения.

from azure.communication.jobrouter.models import (
    LongestIdleMode,
    DistributionPolicy
)

distribution_policy: DistributionPolicy = DistributionPolicy(
    offer_expires_after_seconds = 24 * 60 * 60,
    mode = LongestIdleMode(
        min_concurrent_offers = 1,
        max_concurrent_offers = 1
    )
)

distribution_policy: DistributionPolicy = router_admin_client.upsert_distribution_policy(
    "distribution-policy-1",
    distribution_policy
)

Очередь

Затем можно создать очередь.

from azure.communication.jobrouter.models import (
    RouterQueue
)

queue: RouterQueue = RouterQueue(
    distribution_policy_id = "distribution-policy-1"
)

queue: RouterQueue = router_admin_client.upsert_queue(
    "queue-1",
    queue
)

Задание

Теперь мы можем отправить задание непосредственно в эту очередь, с помощью селектора рабочей роли требует, чтобы у рабочей роли была метка Some-Skill больше 10.

from azure.communication.jobrouter.models import (
    RouterJob,
    RouterWorkerSelector,
    LabelOperator
)

router_job: RouterJob = RouterJob(
    channel_id = "my-channel",
    queue_id = "queue-1",
    channel_reference = "12345",
    priority = 1,
    requested_worker_selectors = [
        RouterWorkerSelector(key = "Some-Skill", label_operator = LabelOperator.EQUAL, value = 10)
    ]
)

job: RouterJob = router_client.upsert_job(
    "jobId-1",
    router_job
)

Рабочий узел

Теперь мы регистрируем рабочую роль для получения работы из этой очереди с меткой Some-Skill 11.

from azure.communication.jobrouter.models import (
    RouterWorker,
    RouterChannel
)

router_worker: RouterWorker = RouterWorker(
    capacity = 1,
    queues = [
        "queue-1"
    ],
    labels = {
        "Some-Skill": 11
    },
    channels = [
        RouterChannel(channel_id = "my-channel", capacity_cost_per_job = 1)
    ],
    available_for_offers = True
)

worker = router_client.upsert_worker(
    "worker-1",
    router_worker
)

ПРЕДЛОЖЕНИЕ

Мы должны получить RouterWorkerOfferIssued из нашей подписки EventGrid.

Существует несколько разных служб Azure, которые действуют в качестве обработчика событий. В этом сценарии мы будем предполагать веб-перехватчики для доставки событий. Дополнительные сведения о доставке событий веб-перехватчика

После доставки событий в обработчик событий можно десериализовать полезные данные JSON в список событий.

# Parse the JSON payload into a list of events
from azure.eventgrid import EventGridEvent
import json

## deserialize payload into a list of typed Events
events = [EventGridEvent.from_json(json.loads(msg)) for msg in payload]

offer_id = ""
for event in events:
    if event.event_type == "Microsoft.Communication.RouterWorkerOfferIssued":
        offer_id = event.data.offer_id
    else:
        continue

Однако можно также подождать несколько секунд, а затем запросить рабочую роль непосредственно в API JobRouter, чтобы узнать, было ли ей выдано предложение.

from azure.communication.jobrouter.models import (
    RouterWorker,
)

router_worker: RouterWorker = router_client.get_worker(worker_id = "worker-1")

for offer in router_worker.offers:
    print(f"Worker {router_worker.id} has an active offer for job {offer.job_id}")

Принять предложение

Когда работник получает предложение, он может выполнить два возможных действия: принять или отклонить. Мы примем предложение.

from azure.communication.jobrouter.models import (
    RouterJobOffer,
    AcceptJobOfferResult,
    RouterJobStatus
)

# fetching the offer id
job_offer: RouterJobOffer = [offer for offer in router_worker.offers if offer.job_id == "jobId-1"][0]
offer_id = job_offer.offer_id

# accepting the offer sent to `worker-1`
accept_job_offer_result: AcceptJobOfferResult = router_client.accept_job_offer(
    worker_id = "worker-1",
    offer_id = offer_id
)

print(f"Offer: {job_offer.offer_id} sent to worker: {router_worker.id} has been accepted")
print(f"Job has been assigned to worker: {router_worker.id} with assignment: {accept_job_offer_result.assignment_id}")

# verify job assignment is populated when querying job
updated_job = router_client.get_job(job_id = "jobId-1")
print(f"Job assignment has been successful: {updated_job.job_status == RouterJobStatus.Assigned and accept_job_offer_result.assignment_id in updated_job.assignments}")

Завершение задания

Завершив работу с заданием, рабочая роль должна пометить задание как completed.

import datetime
from azure.communication.jobrouter.models import (
    CompleteJobOptions
)
complete_job_result = router_client.complete_job(
    "jobId-1",
    accept_job_offer_result.assignment_id,
    CompleteJobOptions(
        note = f"Job has been completed by {router_worker.id} at {datetime.datetime.utcnow()}"
    )
)

print(f"Job has been successfully completed.")

Закрытие задания

После завершения задания рабочая роль может выполнить завершающие действия с заданием, прежде чем закрыть задание и, наконец, освободить его способность принимать больше входящих заданий.

from azure.communication.jobrouter.models import (
    RouterJob,
    RouterJobStatus,
    CloseJobOptions,
)

close_job_result = router_client.close_job(
    "jobId-1",
    accept_job_offer_result.assignment_id,
    CloseJobOptions(
        note = f"Job has been closed by {router_worker.id} at {datetime.datetime.utcnow()}"
    )
)

print(f"Job has been successfully closed.")

update_job: RouterJob = router_client.get_job(job_id = "jobId-1")
print(f"Updated job status: {update_job.job_status == RouterJobStatus.CLOSED}")

import time
from datetime import datetime, timedelta
from azure.communication.jobrouter.models import (
    RouterJob,
    RouterJobStatus,
    CloseJobOptions,
)

close_job_in_future_result = router_client.close_job(
    "jobId-1",
    accept_job_offer_result.assignment_id,
    CloseJobOptions(
        note = f"Job has been closed by {router_worker.id} at {datetime.utcnow()}",
        close_at = datetime.utcnow() + timedelta(seconds = 2)
    )
)

print(f"Job has been marked to close")
time.sleep(secs = 2)
update_job: RouterJob = router_client.get_job(job_id = "jobId-1")
print(f"Updated job status: {update_job.job_status == RouterJobStatus.CLOSED}")

Устранение неполадок

Возникли проблемы? Этот раздел должен содержать подробные сведения о том, что там делать.

Дальнейшие действия

Дополнительные сведения о маршрутизаторе в Службы коммуникации Azure

Больше примеров кода

Подробные примеры использования этой библиотеки см. в каталоге примеров .

Отзывы

Если вы столкнулись с ошибками или у вас есть предложения, сообщите о проблеме в разделе Проблемы проекта.

Участие

На этом проекте приветствуются публикации и предложения. Для участия в большинстве процессов по разработке документации необходимо принять лицензионное соглашение участника (CLA), в котором указывается, что вы предоставляете нам права на использование ваших публикаций. Дополнительные сведения см . на странице cla.microsoft.com.

В рамках этого проекта действуют правила поведения в отношении продуктов с открытым исходным кодом Майкрософт. Дополнительные сведения см. в разделе часто задаваемых вопросов о правилах поведения или обратитесь к opencode@microsoft.com с любыми дополнительными вопросами или комментариями.

Поделиться через

Клиентская библиотека пакета Azure JobRouter для Python версии 1.0.0

Заявление об отказе

Начало работы

Предварительные требования

Установка пакета

Основные понятия

Задание

Рабочий узел

Очередь

Channel

ПРЕДЛОЖЕНИЕ

Политика распространения

Режим распределения

Метки

Селекторы меток

Политика классификации

Политика исключений

Примеры

Инициализация клиента

Политика распространения

Очередь

Задание

Рабочий узел

ПРЕДЛОЖЕНИЕ

Принять предложение

Завершение задания

Закрытие задания

Устранение неполадок

Дальнейшие действия

Больше примеров кода

Отзывы

Участие

Дополнительные ресурсы