Condividi tramite

Libreria client del pacchetto JobRouter di Comunicazione di Azure per Python - versione 1.0.0

  • Articolo

Questo pacchetto contiene python SDK per Servizi di comunicazione di Azure per JobRouter. Altre informazioni su Servizi di comunicazione di Azure sono disponibili qui

Codice | sorgentePacchetto (Pypi) | Documentazione del prodotto

Dichiarazione di non responsabilità

Il supporto dei pacchetti Python di Azure SDK per Python 2.7 è terminato il 01 gennaio 2022. Per altre informazioni e domande, fare riferimento a https://github.com/Azure/azure-sdk-for-python/issues/20691

Introduzione

Prerequisiti

Per usare questo pacchetto è necessaria una sottoscrizione di Azure e una risorsa del servizio di comunicazione .

Installare il pacchetto

Installare la libreria client di Processo di comunicazione di Azure per Python con pip:

pip install azure-communication-jobrouter

Concetti chiave

Processo

Un processo rappresenta l'unità di lavoro, che deve essere indirizzata a un ruolo di lavoro disponibile. Un esempio reale di questo può essere una chiamata o una chat in arrivo nel contesto di un call center.

Worker

Un ruolo di lavoro rappresenta la fornitura disponibile per gestire un processo. Ogni ruolo di lavoro esegue la registrazione con o più code per ricevere processi. Un esempio reale di questo può essere un agente che lavora in un call center.

Coda

Una coda rappresenta un elenco ordinato di processi in attesa di essere servito da un ruolo di lavoro. I ruoli di lavoro verranno registrati con una coda per ricevere il lavoro da esso. Un esempio reale di questo può essere una coda di chiamate in un call center.

Canale

Un canale rappresenta un raggruppamento di processi in base a un tipo. Quando un lavoratore esegue la registrazione per ricevere il lavoro, deve specificare anche per i canali che possono gestire il lavoro e la quantità di ognuna delle quali può gestire contemporaneamente. Un esempio reale di questo può essere voice calls o chats in un call center.

Offerta

Un'offerta viene estesa da JobRouter a un ruolo di lavoro per gestire un determinato processo quando determina una corrispondenza, questa notifica viene in genere recapitata tramite EventGrid. Il ruolo di lavoro può accettare o rifiutare l'offerta usando l'API JobRouter oppure scade in base al tempo necessario per la configurazione dei criteri di distribuzione. Un esempio reale di questo può essere l'anello di un agente in un call center.

Criteri di distribuzione

Un criterio di distribuzione rappresenta un set di configurazione che regola il modo in cui i processi in una coda vengono distribuiti ai ruoli di lavoro registrati con tale coda. Questa configurazione include il periodo di validità di un'offerta prima della scadenza e la modalità di distribuzione, che definiscono l'ordine in cui vengono scelti i ruoli di lavoro quando sono disponibili più ruoli di lavoro.

Modalità di distribuzione

I 3 tipi di modalità sono

  • Round Robin: i ruoli di lavoro vengono ordinati in base Id al ruolo di lavoro successivo dopo quello precedente che ha ricevuto un'offerta.
  • Inattività più lunga: il ruolo di lavoro che non funziona su un processo per il più lungo tempo.
  • Migliore ruolo di lavoro: è possibile specificare un'espressione per confrontare 2 ruoli di lavoro per determinare quale selezionare.

Etichette

È possibile allegare etichette a ruoli di lavoro, processi e code. Si tratta di coppie chiave-valore che possono essere di tipi di stringdati o numberboolean . Un esempio reale di questo può essere il livello di competenza di un determinato lavoratore o del team o della posizione geografica.

Selettori di etichette

I selettori di etichetta possono essere collegati a un processo per definire come destinazione un subset di ruoli di lavoro che servono la coda. Un esempio reale di questo può essere una condizione in una chiamata in ingresso che l'agente deve avere un livello minimo di conoscenza di un determinato prodotto.

Criteri di classificazione

Un criterio di classificazione può essere usato per selezionare in modo dinamico una coda, determinare la priorità del processo e collegare i selettori delle etichette di lavoro a un processo sfruttando un motore regole.

Criteri di eccezione

Un criterio di eccezione controlla il comportamento di un processo in base a un trigger ed esegue un'azione desiderata. I criteri di eccezione sono associati a una coda in modo che possano controllare il comportamento dei processi nella coda.

Esempio

Inizializzazione client

Per inizializzare il client SMS, è possibile usare il stringa di connessione per creare un'istanza. In alternativa, è anche possibile usare l'autenticazione di Active Directory usando 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)

Criteri di distribuzione

Prima di poter creare una coda, è necessario un criterio di distribuzione.

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
)

Coda

Successivamente, è possibile creare la coda.

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
)

Processo

È ora possibile inviare un processo direttamente a tale coda, con un selettore di lavoro che richiede al ruolo di lavoro di avere l'etichetta Some-Skill maggiore di 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

Si registra ora un ruolo di lavoro per ricevere lavoro da tale coda, con un'etichetta Some-Skill uguale a 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
)

Offerta

Si dovrebbe ottenere un RouterWorkerOfferIssued dalla sottoscrizione di EventGrid.

Esistono diversi servizi di Azure che fungono da gestore eventi. Per questo scenario si presupporranno webhook per il recapito di eventi. Altre informazioni sul recapito di eventi webhook

Quando gli eventi vengono recapitati al gestore eventi, è possibile deserializzare il payload JSON in un elenco di eventi.

# 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

Tuttavia, è anche possibile attendere alcuni secondi e quindi eseguire una query sul ruolo di lavoro direttamente sull'API JobRouter per verificare se è stata rilasciata un'offerta.

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

Accettare un'offerta

Quando un lavoratore riceve un'offerta, può eseguire due possibili azioni: accettare o rifiutare. Accetteremo l'offerta.

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

Completamento di un processo

Al termine del processo, il lavoratore deve contrassegnare il processo come 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.")

Chiusura di un processo

Al termine di un processo, il ruolo di lavoro può eseguire azioni di wrapping per il processo prima di chiudere il processo e infine rilasciare la capacità per accettare più processi in ingresso

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

Risoluzione dei problemi

Si verificano problemi? Questa sezione deve contenere i dettagli relativi alle operazioni da eseguire.

Passaggi successivi

Altro codice di esempio

Per esempi dettagliati su come usare questa libreria, vedere la directory degli esempi .

Commenti e suggerimenti

Se si verificano bug o si hanno suggerimenti, segnalare un problema nella sezione Problemi del progetto

Contributo

In questo progetto sono benvenuti i contributi e i suggerimenti. Per la maggior parte dei contenuti è necessario sottoscrivere un contratto di licenza di collaborazione (CLA, Contributor License Agreement) che stabilisce che l'utente ha il diritto di concedere, e di fatto concede a Microsoft i diritti d'uso del suo contributo. Per informazioni dettagliate, visitare cla.microsoft.com.

Questo progetto ha adottato il Codice di comportamento di Microsoft per l'open source. Per altre informazioni, vedere Code of Conduct FAQ (Domande frequenti sul Codice di comportamento Open Source di Microsoft) oppure contattare opencode@microsoft.com per eventuali altre domande o commenti.