Klientská knihovna balíčku azure Communication Chat pro Python – verze 1.2.0

Tento balíček obsahuje sadu Python SDK pro Azure Communication Services pro chat. Další informace o Azure Communication Services najdete tady.

Zdrojový kód | Balíček (Pypi) | Balíček (Conda) | Referenční dokumentace k | rozhraní APIDokumentace k produktu

Právní omezení

Podpora balíčků Azure SDK Python pro Python 2.7 skončila 1. ledna 2022. Další informace a dotazy najdete na https://github.com/Azure/azure-sdk-for-python/issues/20691

Začínáme

Požadavky

• K použití tohoto balíčku se vyžaduje Python 3.7 nebo novější.
• Nasazený prostředek komunikačních služeb K jeho nastavení můžete použít Azure Portal nebo Azure PowerShell.

Instalace balíčku

Nainstalujte sadu SDK chatu služby Azure Communication Service.

pip install --pre azure-communication-chat

Uživatelské přístupové tokeny

Uživatelské přístupové tokeny umožňují vytvářet klientské aplikace, které se přímo ověřují pro Azure Communication Services. Tyto tokeny můžete vygenerovat pomocí modulu azure.communication.identity a pak je použít k inicializaci sad SDK služby Communication Services. Příklad použití azure.communication.identity:

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

Vytvořený user výše uvedený kód se použije později, protože tento uživatel by měl být přidán jako účastník nového vlákna chatu při jeho vytváření pomocí tohoto tokenu. Je to proto, že iniciátor žádosti o vytvoření musí být v seznamu účastníků vlákna chatu.

Vytvoření chatovacího klienta

To vám umožní vytvářet, získávat, vypisovat nebo odstraňovat vlákna chatu.

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

Vytvoření klienta vlákna chatu

ChatThreadClient vám umožní provádět operace specifické pro vlákno chatu, jako je odeslání zprávy, získání zprávy, aktualizace tématu vlákna chatu, přidání účastníků do vlákna chatu atd.

Můžete ho získat vytvořením nového vlákna chatu pomocí ChatClient:

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)

Kromě toho může klient také směrovat tak, aby požadavek byl opakovatelný; to znamená, že pokud klient odešle požadavek vícekrát se stejnými Idempotency-Token a vrátí odpovídající odpověď, aniž by server požadavek několikrát spouštějí. Hodnota Idempotency-Token je neprůzrazný řetězec představující klientem vygenerovaný globálně jedinečný identifikátor požadavku.

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)

Případně pokud jste už vytvořili vlákno chatu a máte jeho thread_id, můžete ho vytvořit pomocí:

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

Klíčové koncepty

Chatová konverzace je reprezentována vláknem chatu. Každý uživatel ve vlákně se nazývá účastník vlákna. Účastníci vlákna můžou mezi sebou soukromě chatovat v individuálním chatu nebo se schoulit ve skupinovém chatu 1:N. Uživatelé také získají téměř v reálném čase aktualizace, když ostatní píšou a když si zprávy přečetli.

Po inicializaci ChatClient třídy můžete provádět následující operace chatu:

Vytváření, získání, aktualizace a odstranění vláken

Provádění operací CRD (Create-Read-Delete) u vláken

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

Po inicializaci ChatThreadClient třídy můžete provádět následující operace chatu:

Aktualizovat vlákno

Provedení operace aktualizace v tématu vlákna

update_topic(topic, **kwargs)

Získání vlastností vlákna chatu

get_properties(**kwargs)

Odesílání, získání, aktualizace a odstranění zpráv

Provádění operací CRUD (Create-Read-Update-Delete) u zpráv

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

Získání, přidání a odebrání účastníků

Provádění operací CRD (Create-Read-Delete) u účastníků vlákna

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

Odeslání oznámení o psaní

Upozorněte službu na zadání oznámení.

send_typing_notification(**kwargs)

Odeslání a získání potvrzení o přečtení

Upozorněte službu, že je přečtená zpráva, a získejte seznam přečtených zpráv.

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

Příklady

Následující části obsahují několik fragmentů kódu, které pokrývají některé z nejběžnějších úloh, mezi které patří:

• Operace s vlákny
• Operace se zprávami
• Operace účastníka vlákna
• Operace s událostmi

Operace s vlákny

Vytvoření vlákna

create_chat_thread Pomocí metody vytvořte vlákno chatu.

• Použijte topic, povinné, chcete-li zadat téma vlákna;
• Použijte thread_participants, volitelné, k zadání seznamu, který ChatParticipant má být přidán do vlákna;
  • user, povinné, jedná se o objekt, který CommunicationUserIdentifier jste vytvořili CommunicationIdentityClient.create_user() z přístupových tokenů uživatelů.
  • display_name, volitelné, je zobrazovaný název účastníka vlákna.
  • share_history_time, volitelný čas, od kterého se historie chatu sdílí s účastníkem.
• K zadání jedinečného identifikátoru požadavku použijte idempotency_tokenvolitelný parametr .

CreateChatThreadResult je výsledek vrácený vytvořením vlákna, můžete ho použít k načtení id vytvořeného vlákna chatu. To id se pak dá použít k načtení objektu ChatThreadClientget_chat_thread_client pomocí metody . ChatThreadClient lze použít k provádění dalších operací chatu s tímto vláknem chatu.

# 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)

Získání vlákna

Use get_properties metoda načte ze služby thread_id . ChatThreadProperties Je jedinečné ID vlákna.

chat_thread_properties = chat_thread_client.get_properties()

Seznam vláken chatu

Použití metody načte seznam vytvořených vláken chatu.list_chat_threads

• Použijte results_per_page, volitelné, maximální počet zpráv, které se mají vrátit na stránku.
• Použijte start_timenepovinný čas zahájení dotazu na rozsah.

Iterátor je [ChatThreadItem] odpověď vrácená z výpisu vláken.

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)

Aktualizace tématu vlákna

Pomocí update_topic metody aktualizujte vlastnosti vlákna. topic slouží k popisu změny tématu vlákna.

• Použít topic k dát vláknu nové téma;

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

chat_thread = chat_thread_client.get_properties(thread_id)

assert chat_thread.topic == topic

Odstranění vlákna

Pomocí delete_chat_thread metody odstraňte vlákno; thread_id je jedinečné ID vlákna.

• K zadání jedinečného ID vlákna použijte thread_id, povinné.

chat_client.delete_chat_thread(thread_id=thread_id)

Operace se zprávami

Odeslat zprávu

Pomocí send_message metody odešle zprávu do vlákna identifikovaného nástrojem thread_id.

• K poskytnutí obsahu zprávy chatu použijte contentpožadovanou možnost.
• K zadání typu zprávy chatu použijte chat_message_typevolitelnou možnost . Mezi možné hodnoty patří: , , , ; 'html'pokud nejsou zadané, ChatMessageType.TEXT nastaví se. 'text'ChatMessageType.HTMLChatMessageType.TEXT
• K zadání zobrazovaného jména odesílatele použijte sender_display_namevolitelné. Pokud není zadaný, nastaví se prázdný název.

SendChatMessageResult je odpověď vrácená odesláním zprávy, obsahuje ID, což je jedinečné ID zprávy.

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)

Získání zprávy

Metoda Use get_message načte zprávu ze služby; message_id je jedinečné ID zprávy.

• Pomocí parametru message_id,required) zadejte ID existující zprávy ChatMessage je odpověď vrácená po získání zprávy, obsahuje ID, což je jedinečné ID zprávy, a další pole najdete v tématu azure.communication.chat.ChatMessage.

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)

Seznam zpráv

Použití list_messages metody načte zprávy ze služby.

• Použijte results_per_page, volitelné, maximální počet zpráv, které se mají vrátit na stránku.
• Použijte start_timenepovinný čas zahájení dotazu na rozsah.

Iterátorem je odpověď vrácená z výpisu [ChatMessage] zpráv.

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)

Aktualizace zprávy

Slouží update_message k aktualizaci zprávy identifikované podle threadId a messageId.

• Použijte message_id,required, je jedinečné ID zprávy.
• Použijte content, nepovinný, je obsah zprávy, který se má aktualizovat. Pokud není zadaný, přiřadí se, aby byla prázdná.

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

Odstranění zprávy

Slouží delete_message k odstranění zprávy.

• Použijte message_id, povinné, je jedinečné ID zprávy.

chat_thread_client.delete_message(message_id=send_message_result_id)

Operace účastníka vlákna

Vypsat účastníky vlákna

Slouží list_participants k načtení účastníků vlákna.

• Použijte results_per_page, volitelné, maximální počet účastníků, kteří se mají vrátit na stránku.
• Pomocí volitelného skipparametru přeskočíte účastníky až na zadanou pozici v odpovědi.

Iterátorem je odpověď vrácená z výpisu [ChatParticipant] účastníků.

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)

Přidání účastníků vlákna

Pomocí add_participants metody přidejte do vlákna účastníky vlákna.

• Použijte thread_participants, povinné, chcete-li ChatParticipant zobrazit seznam, který má být přidán do vlákna;
  • user, povinné, jedná se o objekt, který CommunicationUserIdentifier jste vytvořili CommunicationIdentityClient.create_user() z přístupových tokenů uživatelů.
  • display_name, volitelné, je zobrazovaný název účastníka vlákna.
  • share_history_time, volitelný čas, od kterého se historie chatu sdílí s účastníkem.

Vrátí se hodnota .list(tuple(ChatParticipant, ChatError)) Po úspěšném přidání účastníka se očekává prázdný seznam. V případě chyby při přidávání účastníka se seznam naplní neúspěšnými účastníky spolu s chybou, ke které došlo.

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)

Odebrat účastníka vlákna

Pomocí remove_participant metody odeberte účastníka vlákna z vlákna identifikovaného parametrem threadId. identifier je objekt, který CommunicationUserIdentifier jste vytvořili CommunicationIdentityClient.create_user() z azure-communication-identity

a byla přidána do tohoto vlákna chatu.

• Slouží identifier k zadání vytvořeného objektu CommunicationUserIdentifier .

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

Operace s událostmi

Odeslání oznámení o psaní

Použijte send_typing_notification metodu k odeslání události oznámení o psaní do vlákna jménem uživatele.

chat_thread_client.send_typing_notification()

Odeslat potvrzení o přečtení

Použijte send_read_receipt metodu k odeslání události potvrzení o přečtení do vlákna jménem uživatele.

• Slouží message_id k zadání ID zprávy, jejíž potvrzení o přečtení se má odeslat.

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)

Výpis potvrzení o přečtení

Use list_read_receipts metoda načte potvrzení o přečtení pro vlákno.

• Použijte results_per_page, volitelné, maximální počet potvrzení o přečtení, která se mají na stránku vrátit.
• Pomocí volitelného příkazu skippřeskočíte potvrzení o přečtení až na zadanou pozici v odpovědi.

Iterátor je [ChatMessageReadReceipt] odpověď vrácená z výpisu potvrzení o přečtení.

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)

Příklad kódu

Jedná se o ukázky kódu, které znázorňují operace běžných scénářů s klientskou knihovnou Azure Communication Chat. Asynchronní verze ukázek (ukázkové soubory Pythonu připojené k _async) zobrazují asynchronní operace. Před spuštěním ukázkového kódu si projděte požadavky.

vytvořte prostředek a pak nastavte některé proměnné prostředí.

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

Řešení potíží

Máte problémy? Tato část by měla obsahovat podrobnosti o tom, co tam dělat.

Další kroky

Sem by měl být uvedený další ukázkový kód spolu s odkazy na příslušné ukázkové testy.

Přispívání

Pokud narazíte na nějaké chyby nebo máte návrhy, nahlaste problém v části Problémy projektu.