Bibliothèque cliente de package JobRouter Azure Communication pour Python - version 1.0.0
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.
- Python 3.7 ou version ultérieure est requis pour utiliser ce package. Pour plus d’informations, consultez notre page sur la stratégie de prise en charge des versions du Kit de développement logiciel (SDK) Azure pour Python.
- Pour créer un service de communication, vous pouvez utiliser le portail Azure, le Azure PowerShell
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
Idet 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.
Azure SDK for Python