Partager via

Bibliothèque cliente de package JobRouter Azure Communication pour Python - version 1.0.0

  • Article

Ce package contient un Kit de développement logiciel (SDK) Python pour Azure Communication Services pour JobRouter. En savoir plus sur Azure Communication Services ici

| Code sourcePackage (Pypi) | Documentation produit

Clause d’exclusion de responsabilité

La prise en charge des packages Python du SDK Azure pour Python 2.7 a pris fin le 1er janvier 2022. Pour obtenir plus d’informations et poser des questions, reportez-vous à https://github.com/Azure/azure-sdk-for-python/issues/20691

Prise en main

Prérequis

Vous avez besoin d’un abonnement Azure et d’une ressource Communication Service pour utiliser ce package.

Installer le package

Installez la bibliothèque cliente JobRouter d’Azure Communication pour Python avec pip :

pip install azure-communication-jobrouter

Concepts clés

Travail

Une mission représente l’unité de travail qui doit être acheminée vers un travailleur disponible. Un exemple réel de cela peut être un appel entrant ou une conversation dans le contexte d’un centre d’appels.

Worker

Un worker représente l’approvisionnement disponible pour gérer un travail. Chaque worker s’inscrit avec ou plusieurs files d’attente pour recevoir des travaux. Un agent travaillant dans un centre d’appels peut en être un exemple réel.

File d'attente

Une file d’attente représente une liste ordonnée de travaux en attente d’être pris en charge par un worker. Les workers s’inscrivent avec une file d’attente pour recevoir du travail à partir de celle-ci. Un exemple réel de cela peut être une file d’attente d’appels dans un centre d’appels.

Canal

Un canal représente un regroupement de travaux par un type quelconque. Quand un collaborateur s’inscrit pour recevoir du travail, il doit également spécifier les canaux pour lesquels il peut prendre du travail, ainsi que la quantité de travail qu’il peut gérer simultanément. Un exemple réel de cela peut être voice calls ou chats dans un centre d’appels.

Offre

Une offre est étendue par JobRouter à un worker pour gérer un travail particulier lorsqu’il détermine une correspondance. Cette notification est normalement remise via EventGrid. Le worker peut accepter ou refuser l’offre à l’aide de l’API JobRouter, ou elle expirera en fonction de la durée de vie configurée sur la stratégie de distribution. Un exemple réel de cela peut être la sonnerie d’un agent dans un centre d’appels.

Stratégie de distribution

Une stratégie de distribution représente un ensemble de configuration qui régit la façon dont les travaux d’une file d’attente sont distribués aux travailleurs inscrits avec cette file d’attente. Cette configuration inclut la durée de validité d’une offre avant son expiration et le mode de distribution, qui définit l’ordre dans lequel les workers sont sélectionnés quand plusieurs sont disponibles.

Distribution Mode

Les 3 types de modes sont

  • Tourniquet (Round Robin) : Les collaborateurs sont classés par Id et le collaborateur suivant situé après celui qui vient d’avoir une offre est choisi.
  • Inactif le plus longtemps : Le collaborateur qui n’a pas travaillé depuis le plus longtemps est choisi.
  • Meilleur worker : vous pouvez spécifier une expression pour comparer 2 workers afin de déterminer lequel choisir.

Étiquettes

Vous pouvez attacher des étiquettes à des workers, des travaux et des files d’attente. Il s’agit de paires de valeurs de clé qui peuvent être de types de stringdonnées , number ou boolean . Un exemple réel de cela peut être le niveau de compétence d’un travailleur particulier ou de l’équipe ou de l’emplacement géographique.

Sélecteurs d’étiquettes

Les sélecteurs d’étiquettes peuvent être attachés à un travail afin de cibler un sous-ensemble de workers desservant la file d’attente. Un exemple réel de cela peut être une condition d’un appel entrant selon lequel l’agent doit avoir un niveau minimal de connaissance d’un produit particulier.

Stratégie de classification

Une stratégie de classification peut être utilisée pour sélectionner dynamiquement une file d’attente, déterminer la priorité du travail et attacher des sélecteurs d’étiquettes de travail à un travail en tirant parti d’un moteur de règles.

Stratégie d’exception

Une stratégie d’exception contrôle le comportement d’une mission en fonction d’un déclencheur et exécute une action souhaitée. La stratégie d’exception est attachée à une file d’attente afin qu’elle puisse contrôler le comportement des missions dans la file d’attente.

Exemples

Initialisation du client

Pour initialiser le client SMS, le chaîne de connexion peut être utilisé pour instancier. Vous pouvez également utiliser l’authentification Active Directory à l’aide de 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)

Stratégie de distribution

Avant de pouvoir créer une file d’attente, nous avons besoin d’une stratégie de distribution.

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
)

File d'attente

Ensuite, nous pouvons créer la file d’attente.

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
)

Travail

Maintenant, nous pouvons envoyer une mission directement à cette file d’attente, avec un sélecteur de collaborateur qui exige que le collaborateur ait une étiquette Some-Skill supérieure à 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
)

Worker

Maintenant, nous inscrivons un worker pour recevoir du travail de cette file d’attente, avec une étiquette Some-Skill égale à 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
)

Offre

Nous devrions obtenir un RouterWorkerOfferIssued de notre abonnement EventGrid.

Il existe plusieurs services Azure différents qui font office de gestionnaire d’événements. Pour ce scénario, nous allons supposer des webhooks pour la remise d’événements. En savoir plus sur la remise d’événements webhook

Une fois les événements remis au gestionnaire d’événements, nous pouvons désérialiser la charge utile JSON dans une liste d’événements.

# 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

Toutefois, nous pouvons aussi attendre quelques secondes et interroger le collaborateur directement sur l’API JobRouter pour savoir si une offre lui a été envoyée.

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

Accepter une offre

Une fois qu’un travailleur reçoit une offre, il peut effectuer deux actions possibles : accepter ou refuser. Nous allons accepter l’offre.

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

Fin d’un travail

Une fois le travail terminé, il doit marquer le travail comme 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.")

Fermeture d’un travail

Une fois qu’un travail a été terminé, le worker peut effectuer des actions de résumé du travail avant de fermer le travail et de libérer sa capacité à accepter davantage de travaux entrants

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

Dépannage

Vous rencontrez des problèmes ? Cette section doit contenir des détails sur la procédure à suivre.

Étapes suivantes

Autres exemples de code

Consultez le répertoire d’exemples pour obtenir des exemples détaillés sur l’utilisation de cette bibliothèque.

Fournir des commentaires

Si vous rencontrez des bogues ou si vous avez des suggestions, veuillez déposer un problème dans la section Problèmes du projet

Contribution

Ce projet accepte les contributions et les suggestions. La plupart des contributions vous demandent d’accepter un contrat de licence de contribution (CLA) déclarant que vous avez le droit de nous accorder, et que vous nous accordez réellement, les droits d’utilisation de votre contribution. Pour plus d’informations, consultez cla.microsoft.com.

Ce projet a adopté le Code de conduite Open Source de Microsoft. Pour plus d’informations, consultez les Questions fréquentes (FAQ) sur le code de conduite ou envoyez vos questions ou vos commentaires à opencode@microsoft.com.