Azure Communication JobRouter Package-Clientbibliothek für Python – Version 1.0.0

Artikel
11/22/2023

Dieses Paket enthält ein Python SDK für Azure Communication Services für JobRouter. Weitere Informationen zu Azure Communication Services finden Sie hier.

Quellcode | Paket (Pypi) | Produktdokumentation

Haftungsausschluss

Die Unterstützung von Python-Paketen für Das Azure SDK für Python 2.7 wurde am 01. Januar 2022 eingestellt. Weitere Informationen und Antworten finden Sie unter https://github.com/Azure/azure-sdk-for-python/issues/20691.

Erste Schritte

Voraussetzungen

Sie benötigen ein Azure-Abonnement und eine Communication Service-Ressource , um dieses Paket verwenden zu können.

Für die Verwendung dieses Pakets ist Python 3.7 oder höher erforderlich. Weitere Informationen finden Sie auf unserer Seite zur Supportrichtlinie für Azure SDK für Python-Versionen.
Um einen neuen Communication Service zu erstellen, können Sie das Azure-Portal verwenden, das Azure PowerShell

Installieren des Pakets

Installieren Sie die Azure Communication JobRouter-Clientbibliothek für Python mit pip:

pip install azure-communication-jobrouter

Wichtige Begriffe

Auftrag

Ein Auftrag stellt die Arbeitseinheit dar, die an einen verfügbaren Worker weitergeleitet werden muss. Ein reales Beispiel hierfür kann ein eingehender Anruf oder Chat im Kontext eines Callcenters sein.

Worker

Ein Worker stellt die verfügbare Bereitstellung für die Verarbeitung eines Auftrags dar. Jeder Worker registriert sich mit oder mehr Warteschlangen, um Aufträge zu empfangen. Ein reales Beispiel hierfür kann ein Agent sein, der in einem Callcenter arbeitet.

Warteschlange

Eine Warteschlange stellt eine geordnete Liste von Aufträgen dar, die darauf warten, von einem Worker bedient zu werden. Worker registrieren sich bei einer Warteschlange, um Arbeit von ihr zu erhalten. Ein reales Beispiel hierfür kann eine Anrufwarteschlange in einem Callcenter sein.

Kanal

Ein Kanal stellt eine Gruppierung von Aufträgen nach einem bestimmten Typ dar. Wenn sich ein Worker für den Empfang von Arbeit registriert, muss er auch angeben, für welche Kanäle er die Arbeit verarbeiten kann und wie viel von jedem gleichzeitig verarbeitet werden kann. Ein reales Beispiel hierfür kann oder chats in einem Callcenter seinvoice calls.

Angebot

Ein Angebot wird von JobRouter auf einen Worker erweitert, um einen bestimmten Auftrag zu behandeln, wenn er eine Übereinstimmung bestimmt. Diese Benachrichtigung wird normalerweise über EventGrid übermittelt. Der Worker kann das Angebot entweder über die JobRouter-API annehmen oder ablehnen, oder es läuft entsprechend der zeit ab, in der die Verteilungsrichtlinie konfiguriert ist. Ein reales Beispiel hierfür kann das Klingeln eines Agents in einem Callcenter sein.

Verteilungsrichtlinie

Eine Verteilungsrichtlinie stellt einen Konfigurationssatz dar, der steuert, wie Aufträge in einer Warteschlange an Worker verteilt werden, die bei dieser Warteschlange registriert sind. Diese Konfiguration umfasst, wie lange ein Angebot gültig ist, bevor es abläuft, und den Verteilungsmodus, der die Reihenfolge definiert, in der Worker ausgewählt werden, wenn mehrere verfügbar sind.

Verteilungsmodus

Die 3 Arten von Modi sind

Roundrobin: Worker werden nach Id sortiert und der nächste Worker nach dem vorherigen Worker, der ein Angebot erhalten hat, wird ausgewählt.
Längster Leerlauf: Der Worker, der am längsten nicht an einem Auftrag gearbeitet hat.
Best Worker: Sie können einen Ausdruck angeben, um 2 Worker zu vergleichen, um zu bestimmen, welche Worker ausgewählt werden sollen.

Bezeichnungen

Sie können Bezeichnungen an Worker, Aufträge und Warteschlangen anfügen. Hierbei handelt es sich um Schlüsselwertpaare, die von string- number oder boolean -Datentypen sein können. Ein reales Beispiel hierfür kann das Qualifikationsniveau eines bestimmten Mitarbeiters oder des Teams oder des geografischen Standorts sein.

Bezeichnungsauswahl

Etikettenselektoren können an einen Auftrag angefügt werden, um eine Teilmenge der Worker, die die Warteschlange bedienen, als Ziel zu verwenden. Ein reales Beispiel hierfür kann eine Bedingung für einen eingehenden Anruf sein, dass der Agent über ein mindestes Maß an Kenntnissen über ein bestimmtes Produkt verfügen muss.

Klassifizierungsrichtlinie

Eine Klassifizierungsrichtlinie kann verwendet werden, um eine Warteschlange dynamisch auszuwählen, die Auftragspriorität zu bestimmen und einen Auftrag mithilfe einer Regel-Engine worker label selektoren an einen Auftrag anzufügen.

Ausnahmerichtlinie

Eine Ausnahmerichtlinie steuert das Verhalten eines Auftrags basierend auf einem Trigger und führt eine gewünschte Aktion aus. Die Ausnahmerichtlinie wird an eine Warteschlange angefügt, damit sie das Verhalten von Aufträgen in der Warteschlange steuern kann.

Beispiele

Clientinitialisierung

Zum Initialisieren des SMS-Clients kann die Verbindungszeichenfolge zum Instanziieren verwendet werden. Alternativ können Sie auch die Active Directory-Authentifizierung mit DefaultAzureCredential verwenden.

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)

Verteilungsrichtlinie

Bevor wir eine Warteschlange erstellen können, benötigen wir eine Verteilungsrichtlinie.

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
)

Warteschlange

Als Nächstes können wir die Warteschlange erstellen.

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
)

Auftrag

Jetzt können wir einen Auftrag direkt an diese Warteschlange übermitteln, mit einem Workerselektor, der vorschreibt, dass die Bezeichnung Some-Skill des Workers größer als 10 ist.

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

Jetzt registrieren wir einen Worker, um Arbeit aus dieser Warteschlange zu empfangen, mit einer Bezeichnung von Some-Skill gleich 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
)

Angebot

Wir sollten ein RouterWorkerOfferIssued aus unserem EventGrid-Abonnement erhalten.

Es gibt mehrere verschiedene Azure-Dienste, die als Ereignishandler fungieren. In diesem Szenario wird von Webhooks für die Ereignisübermittlung ausgegangen. Weitere Informationen zur Übermittlung von Webhook-Ereignissen

Sobald Ereignisse an den Ereignishandler übermittelt wurden, können wir die JSON-Nutzlast in einer Liste von Ereignissen deserialisieren.

# 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

Wir könnten jedoch auch einige Sekunden warten und dann den Worker direkt mit der JobRouter-API abfragen, um zu sehen, ob ein Angebot an ihn ausgegeben wurde.

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

Angebot annehmen

Sobald ein Worker ein Angebot erhält, kann er zwei mögliche Aktionen ausführen: Annehmen oder Ablehnen. Wir werden das Angebot annehmen.

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

Abschluss eines Auftrags

Sobald der Worker mit dem Auftrag fertig ist, muss der Worker den Auftrag als completedmarkieren.

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

Schließen eines Auftrags

Nachdem ein Auftrag abgeschlossen wurde, kann der Worker vor dem Schließen des Auftrags Packaktionen für den Auftrag ausführen und schließlich seine Kapazität freigeben, um weitere eingehende Aufträge zu akzeptieren.

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

Problembehandlung

Treten Probleme auf? Dieser Abschnitt sollte Details dazu enthalten, was dort zu tun ist.

Nächste Schritte

Weitere Informationen zu Router in Azure Communication Services

Weiterer Beispielcode

Sehen Sie sich das Beispielverzeichnis an, um detaillierte Beispiele für die Verwendung dieser Bibliothek zu finden.

Feedback geben

Wenn Sie Fehler oder Vorschläge haben, melden Sie ein Problem im Abschnitt Probleme des Projekts.

Mitwirken

Beiträge und Vorschläge für dieses Projekt sind willkommen. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. Weitere Informationen finden Sie unter cla.microsoft.com.

Für dieses Projekt gelten die Microsoft-Verhaltensregeln für Open Source (Microsoft Open Source Code of Conduct). Weitere Informationen finden Sie in den häufig gestellten Fragen zum Verhaltenskodex. Sie können sich auch an opencode@microsoft.com wenden, wenn Sie weitere Fragen oder Anmerkungen haben.

Freigeben über

Azure Communication JobRouter Package-Clientbibliothek für Python – Version 1.0.0

Haftungsausschluss

Erste Schritte

Voraussetzungen

Installieren des Pakets

Wichtige Begriffe

Auftrag

Worker

Warteschlange

Kanal

Angebot

Verteilungsrichtlinie

Verteilungsmodus

Bezeichnungen

Bezeichnungsauswahl

Klassifizierungsrichtlinie

Ausnahmerichtlinie

Beispiele

Clientinitialisierung

Verteilungsrichtlinie

Warteschlange

Auftrag

Worker

Angebot

Angebot annehmen

Abschluss eines Auftrags

Schließen eines Auftrags

Problembehandlung

Nächste Schritte

Weiterer Beispielcode

Feedback geben

Mitwirken

Zusätzliche Ressourcen