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

Bu paket, Sohbet 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) | Paket (Conda) | API başvuru belgeleri | Ü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 lütfen https://github.com/Azure/azure-sdk-for-python/issues/20691

Başlarken

Önkoşullar

• Bu paketi kullanmak için Python 3.7 veya üzeri gereklidir.
• Dağıtılan bir İletişim Hizmetleri kaynağı. Ayarlamak için Azure Portal'ı veya Azure PowerShell kullanabilirsiniz.

Paketi yükleme

Azure İletişim Hizmeti Sohbet SDK'sını yükleyin.

pip install --pre azure-communication-chat

Kullanıcı Erişim Belirteçleri

Kullanıcı erişim belirteçleri, Azure İletişim Hizmetleri için doğrudan kimlik doğrulaması yapabilen istemci uygulamaları oluşturmanıza olanak tanır. Bu belirteçleri azure.communication.identity modülüyle oluşturabilir ve ardından bunları kullanarak İletişim Hizmetleri SDK'larını başlatabilirsiniz. azure.communication.identity kullanma örneği:

pip install azure-communication-identity

from azure.communication.identity import CommunicationIdentityClient
identity_client = CommunicationIdentityClient.from_connection_string("<connection string of your Communication service>")
user = identity_client.create_user()
tokenresponse = identity_client.get_token(user, scopes=["chat"])
token = tokenresponse.token

Bu user belirteçle oluştururken bu kullanıcının yeni sohbet yazışmasının katılımcısı olarak eklenmesi gerektiğinden, yukarıda oluşturulan daha sonra kullanılacaktır. Bunun nedeni oluşturma isteğinin başlatıcısının sohbet yazışmasının katılımcıları listesinde yer alması gerekir.

Sohbet İstemcisi Oluşturma

Bu, sohbet yazışmaları oluşturmanıza, almanıza, listelemenize veya silmenize olanak sağlar.

from azure.communication.chat import ChatClient, CommunicationTokenCredential

# Your unique Azure Communication service endpoint
endpoint = "https://<RESOURCE_NAME>.communcationservices.azure.com"
chat_client = ChatClient(endpoint, CommunicationTokenCredential(token))

Sohbet Yazışması İstemcisi Oluşturma

ChatThreadClient, ileti gönderme, ileti alma, sohbet yazışması konusunu güncelleştirme, sohbet yazışmasına katılımcı ekleme gibi bir sohbet yazışmasına özgü işlemler gerçekleştirmenize olanak tanır.

ChatClient kullanarak yeni bir sohbet yazışması oluşturarak alabilirsiniz:

create_chat_thread_result = chat_client.create_chat_thread(topic)
chat_thread_client = chat_client.get_chat_thread_client(create_chat_thread_result.chat_thread.id)

Ayrıca, istemci isteğin yinelenebilir olması için de yönlendirebilir; diğer bir ifadeyle, istemci aynı Idempotency-Token ile isteği birden çok kez yaparsa ve sunucu isteği birden çok kez yürütmeden uygun bir yanıt alırsa. Idempotency-Token değeri, istemci tarafından oluşturulan, her zaman için genel olarak benzersiz olan isteğin tanımlayıcısını temsil eden opak bir dizedir.

create_chat_thread_result = chat_client.create_chat_thread(
    topic,
    thread_participants=thread_participants,
    idempotency_token=idempotency_token
)
chat_thread_client = chat_client.get_chat_thread_client(create_chat_thread_result.chat_thread.id)

Alternatif olarak, daha önce bir sohbet yazışması oluşturduysanız ve thread_id varsa, bunu şu şekilde oluşturabilirsiniz:

chat_thread_client = chat_client.get_chat_thread_client(thread_id) # thread_id is the id of an existing chat thread

Önemli kavramlar

Sohbet konuşması bir sohbet yazışması tarafından temsil edilir. İş parçacığındaki her kullanıcıya iş parçacığı katılımcısı adı verilir. Yazışma katılımcıları 1:1 sohbetinde birbirleriyle özel olarak sohbet edebilir veya 1:N grup sohbetinde bir araya gelebilir. Kullanıcılar ayrıca başkalarının ne zaman yazdığını ve iletileri ne zaman okuduğunu neredeyse gerçek zamanlı güncelleştirmeler alır.

Bir ChatClient sınıf başlatıldıktan sonra aşağıdaki sohbet işlemlerini gerçekleştirebilirsiniz:

İş parçacıklarını oluşturma, alma, güncelleştirme ve silme

İş parçacıklarında CRD(Create-Read-Delete) işlemleri gerçekleştirme

create_chat_thread(topic, **kwargs)
list_chat_threads(**kwargs)
delete_chat_thread(thread_id, **kwargs)

Bir ChatThreadClient sınıf başlatıldıktan sonra aşağıdaki sohbet işlemlerini gerçekleştirebilirsiniz:

İş parçacığını güncelleştirme

İş parçacığı konusunda Güncelleştirme işlemi gerçekleştirme

update_topic(topic, **kwargs)

Sohbet yazışması özelliklerini alma

get_properties(**kwargs)

İleti gönderme, alma, güncelleştirme ve silme

İletilerde CRUD(Create-Read-Update-Delete) işlemleri gerçekleştirme

send_message(content, **kwargs)
get_message(message_id, **kwargs)
list_messages(**kwargs)
update_message(message_id, content, **kwargs)
delete_message(message_id, **kwargs)

Katılımcıları alma, ekleme ve kaldırma

İş parçacığı katılımcılarında CRD(Create-Read-Delete) işlemleri gerçekleştirme

list_participants(**kwargs)
add_participants(thread_participants, **kwargs)
remove_participant(participant_identifier, **kwargs)

Yazma bildirimi gönderme

Bildirim yazma hizmetini bilgilendirin

send_typing_notification(**kwargs)

Okundu bilgisi gönderme ve alma

Bir iletinin okunduğunu hizmete bildirin ve okunan iletilerin listesini alın.

send_read_receipt(message_id, **kwargs)
list_read_receipts(**kwargs)

Örnekler

Aşağıdaki bölümlerde, aşağıdakiler de dahil olmak üzere en yaygın görevlerden bazılarını kapsayan çeşitli kod parçacıkları sağlanır:

• İş Parçacığı İşlemleri
• İleti İşlemleri
• İş Parçacığı Katılımcısı İşlemleri
• Olay İşlemleri

İş Parçacığı İşlemleri

İş parçacığı oluşturma

Sohbet yazışması create_chat_thread oluşturmak için yöntemini kullanın.

• topicbir iş parçacığı konusu vermek için gerekli kullanın;
• thread_participantsİş parçacığına eklenecek bir liste ChatParticipant sağlamak için isteğe bağlı kullanın;
  • user, gerekli, CommunicationUserIdentifier kullanıcı erişim belirteçlerinden CommunicationIdentityClient.create_user() tarafından oluşturduğunuzdur
  • display_nameisteğe bağlı olarak, iş parçacığı katılımcısının görünen adıdır.
  • share_history_time, isteğe bağlı, sohbet geçmişinin katılımcıyla paylaşıldığı saat.
• idempotency_tokenİsteğin benzersiz tanımlayıcısını belirtmek için isteğe bağlı kullanın.

CreateChatThreadResult bir yazışma oluşturmadan döndürülen sonuçtur, oluşturulan sohbet yazışmasını id getirmek için bunu kullanabilirsiniz. Bu id daha sonra yöntemini kullanarak get_chat_thread_client bir ChatThreadClient nesneyi getirmek için kullanılabilir. ChatThreadClient bu sohbet yazışmasına başka sohbet işlemleri gerçekleştirmek için kullanılabilir.

# Without idempotency_token and thread_participants
topic = "test topic"
create_chat_thread_result = chat_client.create_chat_thread(topic)
chat_thread_client = chat_client.get_chat_thread_client(create_chat_thread_result.chat_thread.id)

# With idempotency_token and thread_participants
from azure.communication.identity import CommunicationIdentityClient
from azure.communication.chat import ChatParticipant, ChatClient, CommunicationTokenCredential
import uuid
from datetime import datetime

# create an user
identity_client = CommunicationIdentityClient.from_connection_string('<connection_string>')
user = identity_client.create_user()

# user access tokens
tokenresponse = identity_client.get_token(user, scopes=["chat"])
token = tokenresponse.token

## OR pass existing user
# from azure.communication.chat import CommunicationUserIdentifier
# user_id = 'some_user_id'
# user = CommunicationUserIdentifier(user_id)

# create the chat_client
endpoint = "https://<RESOURCE_NAME>.communcationservices.azure.com"
chat_client = ChatClient(endpoint, CommunicationTokenCredential(token))

# modify function to implement customer logic
def get_unique_identifier_for_request(**kwargs):
    res = uuid.uuid4()
    return res

topic = "test topic"
thread_participants = [ChatParticipant(
    identifier=user,
    display_name='name',
    share_history_time=datetime.utcnow()
)]

# obtains idempotency_token using some customer logic
idempotency_token = get_unique_identifier_for_request()

create_chat_thread_result = chat_client.create_chat_thread(
    topic,
    thread_participants=thread_participants,
    idempotency_token=idempotency_token)
thread_id = create_chat_thread_result.chat_thread.id

# fetch ChatThreadClient
chat_thread_client = chat_client.get_chat_thread_client(create_chat_thread_result.chat_thread.id)

# Additionally, you can also check if all participants were successfully added or not
# and subsequently retry adding the failed participants again
def decide_to_retry(error, **kwargs):
    """
    Insert some custom logic to decide if retry is applicable based on error
    """
    return True

retry = [thread_participant for thread_participant, error in create_chat_thread_result.errors if decide_to_retry(error)]
if retry:
    chat_thread_client.add_participants(retry)

İş parçacığı alma

Use get_properties yöntemi hizmetten bir ChatThreadProperties alır; thread_id iş parçacığının benzersiz kimliğidir.

chat_thread_properties = chat_thread_client.get_properties()

Sohbet yazışmalarını listeleme

Use list_chat_threads yöntemi, oluşturulan sohbet yazışmalarının listesini alır

• İsteğe bağlı, Sayfa başına döndürülecek ileti sayısı üst sınırını kullanın results_per_page.
• , isteğe bağlı, aralık sorgusunun bulunduğu başlangıç saati kullanın start_time.

Yineleyicisi [ChatThreadItem] , listeleme iş parçacıklarından döndürülen yanıttır

from azure.communication.chat import ChatClient, CommunicationTokenCredential
from datetime import datetime, timedelta

token = "<token>"
endpoint = "https://<RESOURCE_NAME>.communcationservices.azure.com"
chat_client = ChatClient(endpoint, CommunicationTokenCredential(token))
start_time = datetime.utcnow() - timedelta(days=2)

chat_threads = chat_client.list_chat_threads(results_per_page=5, start_time=start_time)
for chat_thread_item_page in chat_threads.by_page():
    for chat_thread_item in chat_thread_item_page:
        print("thread id:", chat_thread_item.id)

İş parçacığı konusunu güncelleştirme

İş parçacığının özelliklerini güncelleştirmek için yöntemini kullanın update_topic . topic iş parçacığı konusunun değişikliğini açıklamak için kullanılır

• Yazışmaya yeni bir konu vermek için kullanın topic ;

topic = "new topic"
chat_thread_client.update_topic(topic=topic)

chat_thread = chat_thread_client.get_properties(thread_id)

assert chat_thread.topic == topic

İş parçacığını silme

Bir iş parçacığını silmek için yöntemini kullanın delete_chat_thread ; thread_id iş parçacığının benzersiz kimliğidir.

• İş parçacığının benzersiz kimliğini belirtmek için gerekli değerini kullanın thread_id.

chat_client.delete_chat_thread(thread_id=thread_id)

İleti İşlemleri

İleti gönderme

tarafından thread_idtanımlanan bir iş parçacığına ileti göndermek için yöntemini kullanınsend_message.

• Sohbet iletisi içeriğini sağlamak için gerekli seçeneğini kullanın content.
• chat_message_typesohbet iletisi türünü sağlamak için isteğe bağlı kullanın. Olası değerler şunlardır: ChatMessageType.TEXT, ChatMessageType.HTML, 'text', 'html'; belirtilmezse ayarlanacaktır ChatMessageType.TEXT
• sender_display_nameGönderenin görünen adını belirtmek için isteğe bağlı kullanın, belirtilmezse boş ad ayarlanır

SendChatMessageResult , ileti göndermeden döndürülen yanıttır, iletinin benzersiz kimliği olan bir kimlik içerir.

from azure.communication.chat import ChatMessageType

topic = "test topic"
create_chat_thread_result = chat_client.create_chat_thread(topic)
thread_id = create_chat_thread_result.chat_thread.id
chat_thread_client = chat_client.get_chat_thread_client(create_chat_thread_result.chat_thread.id)

content='hello world'
sender_display_name='sender name'
chat_message_type = ChatMessageType.TEXT

# without specifying sender_display_name and chat_message_type
send_message_result = chat_thread_client.send_message(content)
send_message_result_id = send_message_result.id
print("Message sent: id: ", send_message_result_id)

# specifying sender_display_name and chat_message_type
send_message_result_w_type = chat_thread_client.send_message(
            content,
            sender_display_name=sender_display_name,
            chat_message_type=chat_message_type # equivalent to chat_message_type = 'text'
)
send_message_result_w_type_id = send_message_result_w_type.id
print("Message sent: id: ", send_message_result_w_type_id)

İleti alma

Use get_message yöntemi hizmetten bir ileti alır; message_id iletinin benzersiz kimliğidir.

• Var olan bir iletinin ChatMessage ileti kimliğini belirtmek için , gerekli değerini kullanınmessage_id; ileti alındığında döndürülen yanıttır, iletinin benzersiz kimliği olan bir kimlik içerir ve diğer alanlar lütfen azure.communication.chat.ChatMessage'a bakın

chat_message = chat_thread_client.get_message(message_id=send_message_result_id)
print("get_chat_message succeeded, message id:", chat_message.id, "content: ", chat_message.content)

İletileri listeleme

Use list_messages yöntemi hizmetten iletileri alır.

• İsteğe bağlı, Sayfa başına döndürülecek ileti sayısı üst sınırını kullanın results_per_page.
• , isteğe bağlı, aralık sorgusunun bulunduğu başlangıç saati kullanın start_time.

Yineleyicisi [ChatMessage] , iletilerin listelenmesinden döndürülen yanıttır

from datetime import datetime, timedelta

start_time = datetime.utcnow() - timedelta(days=1)

chat_messages = chat_thread_client.list_messages(results_per_page=1, start_time=start_time)
for chat_message_page in chat_messages.by_page():
    for chat_message in chat_message_page:
        print("ChatMessage: Id=", chat_message.id, "; Content=", chat_message.content.message)

İletiyi güncelleştirme

threadId ve messageId ile tanımlanan bir iletiyi güncelleştirmek için kullanın update_message .

• kullanın message_id, gerekli, iletinin benzersiz kimliğidir.
• kullanın content, isteğe bağlı, güncelleştirilecek ileti içeriğidir; belirtilmezse boş olarak atanır

content = "updated message content"
chat_thread_client.update_message(send_message_result_id, content=content)

chat_message = chat_thread_client.get_message(message_id=send_message_result_id)

assert chat_message.content.message == content

İleti silme

İletiyi silmek için kullanın delete_message .

• komutunu kullanın message_id, gerekli, iletinin benzersiz kimliğidir.

chat_thread_client.delete_message(message_id=send_message_result_id)

İş Parçacığı Katılımcı İşlemleri

İş parçacığı katılımcılarını listeleme

İş parçacığının katılımcılarını almak için kullanın list_participants .

• kullanın results_per_page, isteğe bağlı, Sayfa başına döndürülecek en fazla katılımcı sayısı.
• skipKatılımcıları yanıt olarak belirtilen konuma atlamak için isteğe bağlı kullanın.

Yineleyicisi [ChatParticipant] , liste katılımcılarından döndürülen yanıttır

chat_participants = chat_thread_client.list_participants(results_per_page=5, skip=5)
for chat_participant_page in chat_participants.by_page():
    for chat_participant in chat_participant_page:
        print("ChatParticipant: ", chat_participant)

yazışma katılımcıları ekleme

İş parçacığına iş parçacığı katılımcıları eklemek için yöntemini kullanın add_participants .

• thread_participantsİş parçacığına eklenecek öğesini listelemek ChatParticipant için gerekli kullanın;
  • user, gerekli, CommunicationUserIdentifier kullanıcı erişim belirteçlerinden CommunicationIdentityClient.create_user() tarafından oluşturduğunuzdur
  • display_nameisteğe bağlı olarak, iş parçacığı katılımcısının görünen adıdır.
  • share_history_time, isteğe bağlı, sohbet geçmişinin katılımcıyla paylaşıldığı saat.

bir list(tuple(ChatParticipant, ChatError)) döndürülür. Katılımcı başarıyla eklendiğinde boş bir liste beklenir. Katılımcı eklenirken bir hatayla karşılaşıldığında, liste, karşılaşılan hatayla birlikte başarısız katılımcılarla doldurulur.

from azure.communication.identity import CommunicationIdentityClient
from azure.communication.chat import ChatParticipant
from datetime import datetime

# create 2 users
identity_client = CommunicationIdentityClient.from_connection_string('<connection_string>')
new_users = [identity_client.create_user() for i in range(2)]

# # conversely, you can also add an existing user to a chat thread; provided the user_id is known
# from azure.communication.chat import CommunicationUserIdentifier
#
# user_id = 'some user id'
# user_display_name = "Wilma Flinstone"
# new_user = CommunicationUserIdentifier(user_id)
# participant = ChatParticipant(
#     identifier=new_user,
#     display_name=user_display_name,
#     share_history_time=datetime.utcnow())

participants = []
for _user in new_users:
  chat_participant = ChatParticipant(
    identifier=_user,
    display_name='Fred Flinstone',
    share_history_time=datetime.utcnow()
  )
  participants.append(chat_participant)

response = chat_thread_client.add_participants(thread_participants=participants)

def decide_to_retry(error, **kwargs):
    """
    Insert some custom logic to decide if retry is applicable based on error
    """
    return True

# verify if all users has been successfully added or not
# in case of partial failures, you can retry to add all the failed participants
retry = [p for p, e in response if decide_to_retry(e)]
if retry:
    chat_thread_client.add_participants(retry)

İş parçacığı katılımcısını kaldırma

threadId tarafından tanımlanan iş parçacığından iş parçacığı katılımcısını kaldırmak için yöntemini kullanın remove_participant . identifierCommunicationUserIdentifier, CommunicationIdentityClient.create_user() tarafından oluşturduğunuzazure-communication-identity

ve bu sohbet yazışmasına eklendi.

• Oluşturduğunuz öğesini CommunicationUserIdentifier belirtmek için kullanın identifier

chat_thread_client.remove_participant(identifier=new_user)

# # conversely you can also do the following; provided the user_id is known
# from azure.communication.chat import CommunicationUserIdentifier
#
# user_id = 'some user id'
# chat_thread_client.remove_participant(identifier=CommunicationUserIdentifier(new_user))

Olay İşlemleri

Yazma bildirimi gönderme

Kullanıcı adına bir yazışmaya yazma bildirimi olayı göndermek için yöntemini kullanın send_typing_notification .

chat_thread_client.send_typing_notification()

Okundu bilgisi gönder

Okundu bilgisi olayını bir kullanıcı adına iş parçacığına göndermek için yöntemini kullanın send_read_receipt .

• Okundu bilgisi gönderilecek iletinin kimliğini belirtmek için kullanın message_id

content='hello world'
send_message_result = chat_thread_client.send_message(content)
send_message_result_id = send_message_result.id
chat_thread_client.send_read_receipt(message_id=send_message_result_id)

Okundu bilgilerini listeleme

Use list_read_receipts yöntemi bir iş parçacığı için okundu bilgilerini alır.

• kullanın results_per_page, isteğe bağlı, Sayfa başına döndürülecek en fazla okundu bilgisi sayısı.
• skipOkundu bilgilerini yanıtta belirtilen konuma atlamak için isteğe bağlı kullanın.

Yineleyicisi [ChatMessageReadReceipt] , okundu bilgilerini listelemeden döndürülen yanıttır

read_receipts = chat_thread_client.list_read_receipts(results_per_page=5, skip=5)

for read_receipt_page in read_receipts.by_page():
    for read_receipt in read_receipt_page:
        print(read_receipt)
        print(read_receipt.sender)
        print(read_receipt.chat_message_id)
        print(read_receipt.read_on)

Örnek Kod

Bunlar, Azure İletişim Sohbeti istemci kitaplığıyla yapılan yaygın senaryo işlemlerini gösteren kod örnekleridir. Örneklerin zaman uyumsuz sürümleri (ile _asynceklenen Python örnek dosyaları) zaman uyumsuz işlemleri gösterir. Örnek kodu çalıştırmadan önce Önkoşullar bölümüne bakın

kaynak oluşturmak ve ardından bazı Ortam Değişkenleri ayarlamak için

set AZURE_COMMUNICATION_SERVICE_ENDPOINT="https://<RESOURCE_NAME>.communcationservices.azure.com"
set COMMUNICATION_SAMPLES_CONNECTION_STRING="<connection string of your Communication service>"

pip install azure-communication-identity

python samples\chat_client_sample.py
python samples\chat_client_sample_async.py
python samples\chat_thread_client_sample.py
python samples\chat_thread_client_sample_async.py

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

Daha fazla örnek kodun ve uygun örnek testlerin bağlantılarının buraya gitmesi gerekir.

Katkıda bulunma

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