Python için Azure İletişim JobRouter Paketi istemci kitaplığı - sürüm 1.0.0

Makale
11/22/2023

Bu paket, JobRouter için Azure İletişim Hizmetleri için bir Python SDK'sı içerir. Azure İletişim Hizmetleri hakkında daha fazla bilgiyi burada bulabilirsiniz

Kaynak kodu | Paket (Pypi) | Ürün belgeleri

Bildirim

Python 2.7 için Azure SDK Python paketleri desteği 01 Ocak 2022'de sona erdi. Daha fazla bilgi ve soru için bkz. https://github.com/Azure/azure-sdk-for-python/issues/20691

Başlarken

Önkoşullar

Bu paketi kullanmak için bir Azure aboneliğine ve İletişim Hizmeti Kaynağına ihtiyacınız vardır.

Bu paketi kullanmak için Python 3.7 veya üzeri gereklidir. Diğer ayrıntılar için python sürümü destek ilkesi için Azure SDK'sı sayfamızı okuyun.
Yeni bir İletişim Hizmeti oluşturmak için Azure PowerShell Azure Portal'ı kullanabilirsiniz

Paketi yükleme

Pip ile Python için Azure communication JobRouter istemci kitaplığını yükleyin:

pip install azure-communication-jobrouter

Önemli kavramlar

İş

İş, kullanılabilir bir Çalışana yönlendirilmesi gereken iş birimini temsil eder. Bunun gerçek bir örneği, çağrı merkezi bağlamında gelen arama veya sohbet olabilir.

Işçi

Çalışan, bir işi işlemek için kullanılabilecek kaynağı temsil eder. Her çalışan, iş almak için veya daha fazla kuyruğa kaydolarak. Bunun gerçek bir örneği, çağrı merkezinde çalışan bir temsilci olabilir.

Kuyruk

Kuyruk, çalışan tarafından sunulmayı bekleyen işlerin sıralı listesini temsil eder. Çalışanlar, bu kuyruktan iş almak için bir kuyruğa kaydolacak. Bunun gerçek bir örneği, çağrı merkezindeki bir çağrı kuyruğu olabilir.

Kanal

Kanal, işleri bir türe göre gruplandırma işlemini temsil eder. Bir çalışan iş almak için kaydolduğunda, hangi kanalların işleneceğini ve her birinin ne kadarını eşzamanlı olarak işleyebileceğini de belirtmelidir. Bunun gerçek bir örneği çağrı merkezinde veya voice callschats olabilir.

Sunduğu

Bir Teklif JobRouter tarafından, bir eşleşme belirlediğinde belirli bir işi işlemesi için çalışana genişletilir; bu bildirim normalde EventGrid aracılığıyla teslim edilir. Çalışan, th JobRouter API'sini kullanarak teklifi kabul edebilir veya reddedebilir ya da dağıtım ilkesinde yapılandırılan yaşam süresine göre süresi dolar. Bunun gerçek bir örneği, çağrı merkezindeki bir aracının çaldırılması olabilir.

Dağıtım İlkesi

Dağıtım İlkesi, bir kuyruktaki işlerin bu kuyruğa kayıtlı çalışanlara nasıl dağıtıldığını yöneten bir yapılandırma kümesini temsil eder. Bu yapılandırma, bir Teklifin süresi dolmadan önce geçerli olduğu zamanı ve birden çok kullanılabilir olduğunda çalışanların hangi sırayla seçileceğini tanımlayan dağıtım modunu içerir.

Dağıtım Modu

3 mod türü şunlardır:

Hepsini Bir Kez Deneme: Çalışanlar tarafından sipariş Id edilir ve teklif alan bir öncekinden sonraki çalışan seçilir.
En Uzun Boşta: Bir iş üzerinde en uzun süredir çalışmayan çalışan.
En İyi Çalışan: Hangisinin seçileceğini belirlemek için 2 çalışanı karşılaştıracak bir ifade belirtebilirsiniz.

Etiketler

Çalışanlara, işlere ve kuyruklara etiket ekleyebilirsiniz. Bunlar , number veya boolean veri türleri olabilecek stringanahtar değer çiftleridir. Bunun gerçek bir örneği, belirli bir çalışanın, ekibin veya coğrafi konumun beceri düzeyi olabilir.

Etiket Seçicileri

Etiket seçicileri, kuyruğa hizmet veren bir çalışan alt kümesini hedeflemek için bir işe eklenebilir. Bunun gerçek bir örneği, gelen bir çağrıda aracının belirli bir ürünle ilgili minimum bilgi düzeyine sahip olması gerektiğini belirten bir koşul olabilir.

Sınıflandırma ilkesi

Sınıflandırma ilkesi, kural altyapısı kullanılarak bir kuyruğu dinamik olarak seçmek, iş önceliğini belirlemek ve çalışan etiketi seçicilerini bir işe eklemek için kullanılabilir.

Özel durum ilkesi

Özel durum ilkesi, tetikleyiciye göre bir İşin davranışını denetler ve istenen eylemi yürütür. Özel durum ilkesi, Kuyruktaki İşlerin davranışını denetleyebilmesi için kuyruğa eklenir.

Örnekler

İstemci Başlatma

SMS İstemcisi'ni başlatmak için bağlantı dizesi örneği açmak için kullanılabilir. Alternatif olarak, DefaultAzureCredential kullanarak Active Directory kimlik doğrulamayı da kullanabilirsiniz.

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)

Dağıtım İlkesi

Kuyruk oluşturabilmek için önce bir Dağıtım İlkesine ihtiyacımız vardır.

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
)

Kuyruk

Ardından kuyruğu oluşturabiliriz.

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
)

İş

Artık doğrudan bu kuyruğa bir iş gönderebiliriz. Çalışan seçici, çalışanın etiketi Some-Skill 10'dan büyük olmasını gerektirir.

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
)

Işçi

Şimdi bu kuyruktan 11'e eşit etikete Some-Skill sahip bir çalışanı iş alacak şekilde kaydediyoruz.

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
)

Sunduğu

EventGrid aboneliğimizden bir RouterWorkerOfferIssued almalıdır.

Olay işleyicisi olarak davranan birkaç farklı Azure hizmeti vardır. Bu senaryoda, olay teslimi için Web kancaları varsayacağız. Web kancası olay teslimi hakkında daha fazla bilgi edinin

Olaylar olay işleyicisine teslim edildikten sonra JSON yükünü seri durumdan çıkararak bir olay listesi oluşturabiliriz.

# 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

Ancak birkaç saniye bekleyip çalışanı doğrudan JobRouter API'sine karşı sorgulayarak bir teklif sunulup sunulmadığını da görebiliriz.

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

Teklifi kabul etme

Bir çalışan teklif aldıktan sonra iki olası eylem gerçekleştirebilir: kabul etme veya reddetme. Teklifi kabul edeceğiz.

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

bir işi tamamlama

Çalışanın işi tamamladıktan sonra, çalışanın işi olarak completedişaretlemesi gerekir.

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

İşi kapatma

Bir iş tamamlandıktan sonra, çalışan işi kapatmadan ve son olarak daha fazla gelen işi kabul etmek için kapasitesini serbest bırakmadan önce işin sarmalama eylemlerini gerçekleştirebilir

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

Sorun giderme

Sorunlarla mı karşılaşılıyor? Bu bölüm, orada ne yapacağınıza ilişkin ayrıntıları içermelidir.

Sonraki adımlar

Azure İletişim Hizmetleri'da Yönlendirici hakkında daha fazla bilgi edinin

Daha fazla örnek kod

Bu kitaplığın nasıl kullanılacağına ilişkin ayrıntılı örnekler için lütfen samples dizinine göz atın.

Geri Bildirim Sağlama

Herhangi bir hatayla karşılaşırsanız veya önerileriniz varsa lütfen projenin Sorunlar bölümünde bir sorun oluşturun

Katkıda bulunma

Bu proje, katkı ve önerilere açıktır. Çoğu durumda, sağladığınız katkıyı kullanmamız için bize hak tanıma hakkına sahip olduğunuzu ve bu hakkı bize tanıdığınızı bildiren bir Katkıda Bulunan Lisans Sözleşmesi’ni (CLA) kabul etmeniz gerekir. Ayrıntılar için cla.microsoft.com adresini ziyaret edin.

Bu proje Microsoft Open Source Code of Conduct (Microsoft Açık Kaynak Kullanım Kuralları) belgesinde listelenen kurallara uygundur. Daha fazla bilgi için Kullanım Kuralları SSS bölümüne bakın veya ek sorularınız veya yorumlarınızla iletişime geçin opencode@microsoft.com .

Aracılığıyla paylaş

Python için Azure İletişim JobRouter Paketi istemci kitaplığı - sürüm 1.0.0

Bildirim

Başlarken

Önkoşullar

Paketi yükleme

Önemli kavramlar

İş

Işçi

Kuyruk

Kanal

Sunduğu

Dağıtım İlkesi

Dağıtım Modu

Etiketler

Etiket Seçicileri

Sınıflandırma ilkesi

Özel durum ilkesi

Örnekler

İstemci Başlatma

Dağıtım İlkesi

Kuyruk

İş

Işçi

Sunduğu

Teklifi kabul etme

bir işi tamamlama

İşi kapatma

Sorun giderme

Sonraki adımlar

Daha fazla örnek kod

Geri Bildirim Sağlama

Katkıda bulunma

Ek kaynaklar