Delen via

Azure Communication JobRouter Package-clientbibliotheek voor Python - versie 1.0.0

  • Artikel

Dit pakket bevat een Python-SDK voor Azure Communication Services voor JobRouter. Lees hier meer over Azure Communication Services

Broncode | Pakket (Pypi) | Productdocumentatie

Disclaimer

Ondersteuning voor Azure SDK Python-pakketten voor Python 2.7 is beëindigd op 1 januari 2022. Voor meer informatie en vragen raadpleegt u https://github.com/Azure/azure-sdk-for-python/issues/20691

Aan de slag

Vereisten

U hebt een Azure-abonnement en een Communication Service-resource nodig om dit pakket te kunnen gebruiken.

Het pakket installeren

Installeer de Azure Communication JobRouter-clientbibliotheek voor Python met pip:

pip install azure-communication-jobrouter

Belangrijkste concepten

Taak

Een taak vertegenwoordigt de werkeenheid, die moet worden doorgestuurd naar een beschikbare werkrol. Een praktijkvoorbeeld hiervan kan een binnenkomend gesprek of chatgesprek zijn in de context van een callcenter.

Werknemer

Een werkrol vertegenwoordigt het aanbod dat beschikbaar is voor het afhandelen van een taak. Elke werkrol registreert zich met of meer wachtrijen om taken te ontvangen. Een praktijkvoorbeeld hiervan kan een agent zijn die in een callcenter werkt.

Wachtrij

Een wachtrij vertegenwoordigt een geordende lijst met taken die wachten om te worden uitgevoerd door een werknemer. Werkrollen registreren zich met een wachtrij om er werk van te ontvangen. Een praktijkvoorbeeld hiervan kan een oproepwachtrij in een callcenter zijn.

Kanaal

Een kanaal vertegenwoordigt een groepering van taken op een bepaald type. Wanneer een werknemer zich registreert om werk te ontvangen, moet deze ook opgeven voor welke kanalen ze werk kunnen verwerken en hoeveel van elk kanaal ze gelijktijdig kunnen verwerken. Een praktijkvoorbeeld hiervan is voice calls of chats in een callcenter.

Aanbieding

Een aanbieding wordt door JobRouter uitgebreid naar een werkrol om een bepaalde taak af te handelen wanneer deze een overeenkomst bepaalt. Deze melding wordt normaal gesproken via EventGrid geleverd. De werkrol kan de aanbieding accepteren of weigeren met behulp van de JobRouter-API, of deze verloopt op basis van de time-to-live die is geconfigureerd voor het distributiebeleid. Een praktijkvoorbeeld hiervan kan het bellen van een medewerker in een callcenter zijn.

Distributiebeleid

Een distributiebeleid vertegenwoordigt een configuratieset die bepaalt hoe taken in een wachtrij worden gedistribueerd naar werkrollen die zijn geregistreerd bij die wachtrij. Deze configuratie omvat hoe lang een aanbieding geldig is voordat deze verloopt en de distributiemodus, waarmee de volgorde wordt gedefinieerd waarin werkrollen worden gekozen wanneer er meerdere beschikbaar zijn.

Distributiemodus

De drie typen modi zijn

  • Round Robin: Werkrollen worden besteld door Id en de volgende werknemer na de vorige die een aanbieding heeft gekregen, wordt gekozen.
  • Langste niet-actieve: de werkrol die het langst niet aan een taak heeft gewerkt.
  • Beste werkrol: u kunt een expressie opgeven om 2 werkrollen te vergelijken om te bepalen welke werkrol u wilt kiezen.

Labels

U kunt labels koppelen aan werkrollen, taken en wachtrijen. Dit zijn sleutelwaardeparen die van stringhet gegevenstype , number of boolean kunnen zijn. Een praktijkvoorbeeld hiervan kan het vaardigheidsniveau van een bepaalde werknemer of het team of de geografische locatie zijn.

Labelkiezers

Labelkiezers kunnen worden gekoppeld aan een taak om een subset van werkrollen aan de wachtrij te koppelen. Een praktijkvoorbeeld hiervan kan een voorwaarde zijn bij een binnenkomende oproep dat de agent een minimumniveau van kennis van een bepaald product moet hebben.

Classificatiebeleid

Een classificatiebeleid kan worden gebruikt om dynamisch een wachtrij te selecteren, de taakprioriteit te bepalen en werkrollabelkiezers aan een taak te koppelen door gebruik te maken van een regelengine.

Uitzonderingsbeleid

Een uitzonderingsbeleid bepaalt het gedrag van een taak op basis van een trigger en voert een gewenste actie uit. Het uitzonderingsbeleid is gekoppeld aan een wachtrij, zodat hiermee het gedrag van taken in de wachtrij kan worden bepaald.

Voorbeelden

Client initialisatie

Om de SMS-client te initialiseren, kan de verbindingsreeks worden gebruikt om te instantiëren. U kunt ook Active Directory-verificatie gebruiken met behulp van 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)

Distributiebeleid

Voordat we een wachtrij kunnen maken, hebben we een distributiebeleid nodig.

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
)

Wachtrij

Vervolgens kunnen we de wachtrij maken.

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
)

Taak

Nu kunnen we een taak rechtstreeks naar die wachtrij verzenden, met een werkrolselector waarvoor de werkrol het label Some-Skill groter dan 10 moet hebben.

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
)

Werknemer

Nu registreren we een werkrol om werk van die wachtrij te ontvangen, met een label van Some-Skill gelijk aan 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
)

Aanbieding

We moeten een RouterWorkerOfferIssued ophalen uit ons EventGrid-abonnement.

Er zijn verschillende Azure-services die fungeren als gebeurtenis-handler. Voor dit scenario gaan we uit van Webhooks voor de levering van gebeurtenissen. Meer informatie over het leveren van webhook-gebeurtenissen

Zodra gebeurtenissen zijn afgeleverd bij de gebeurtenis-handler, kunnen we deserialiseren van de JSON-nettolading in een lijst met gebeurtenissen.

# 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

We kunnen echter ook een paar seconden wachten en de werkrol vervolgens rechtstreeks opvragen op de JobRouter-API om te zien of er een aanbieding is uitgegeven.

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

Een aanbieding accepteren

Zodra een werknemer een aanbieding ontvangt, kan deze twee mogelijke acties ondernemen: accepteren of weigeren. We gaan het aanbod accepteren.

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

Een taak voltooien

Zodra de werkrol klaar is met de taak, moet de werknemer de taak markeren als 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.")

Een taak sluiten

Nadat een taak is voltooid, kan de werkrol acties voor het afronden van de taak uitvoeren voordat de taak wordt gesloten en ten slotte de capaciteit vrijgeeft om meer binnenkomende taken te accepteren

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

Problemen oplossen

Ondervindt u problemen? Deze sectie moet details bevatten over wat u daar moet doen.

Volgende stappen

Meer voorbeeldcode

Raadpleeg de map met voorbeelden voor gedetailleerde voorbeelden van het gebruik van deze bibliotheek.

Feedback geven

Als u fouten tegenkomt of suggesties hebt, kunt u een probleem melden in de sectie Problemen van het project

Bijdragen

Wij verwelkomen bijdragen en suggesties voor dit project. Voor de meeste bijdragen moet u instemmen met een licentieovereenkomst voor bijdragers (CLA: Contributor License Agreement) waarin u verklaart dat u gerechtigd bent ons het recht te geven uw bijdrage te gebruiken, en dat u dit ook doet. Ga naar cla.microsoft.com voor meer informatie.

Op dit project is de Microsoft Open Source Code of Conduct (Microsoft Open Source-gedragscode) van toepassing. Zie de Veelgestelde vragen over de gedragscode voor meer informatie of neem contact op opencode@microsoft.com met eventuele aanvullende vragen of opmerkingen.