Biblioteka klienta pakietu czatu usługi Azure Communication dla języka Python — wersja 1.2.0

Ten pakiet zawiera zestaw SDK języka Python dla Azure Communication Services na potrzeby czatu. Dowiedz się więcej o Azure Communication Services tutaj

Kod | źródłowyPakiet (Pypi) | Pakiet (Conda) | Dokumentacja referencyjna interfejsu | APIDokumentacja produktu

Zrzeczenie odpowiedzialności

Obsługa pakietów języka Python dla zestawu Azure SDK dla języka Python 2.7 zakończyła się 1 stycznia 2022 r. Aby uzyskać więcej informacji i pytań, zapoznaj się z artykułem https://github.com/Azure/azure-sdk-for-python/issues/20691

Wprowadzenie

Wymagania wstępne

• Do korzystania z tego pakietu jest wymagany język Python w wersji 3.7 lub nowszej.
• Wdrożony zasób usług Komunikacyjnych. Możesz użyć witryny Azure Portal lub Azure PowerShell, aby ją skonfigurować.

Instalowanie pakietu

Zainstaluj zestaw SDK czatu usługi Azure Communication Service.

pip install --pre azure-communication-chat

Tokeny dostępu użytkowników

Tokeny dostępu użytkowników umożliwiają tworzenie aplikacji klienckich, które są bezpośrednio uwierzytelniane w Azure Communication Services. Te tokeny można wygenerować za pomocą modułu azure.communication.identity, a następnie użyć ich do zainicjowania zestawów SDK usług Communication Services. Przykład użycia pliku 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

Utworzone user powyżej zostaną użyte później, ponieważ ten użytkownik powinien zostać dodany jako uczestnik nowego wątku czatu podczas tworzenia go za pomocą tego tokenu. Jest to spowodowane tym, że inicjator żądania utworzenia musi znajdować się na liście uczestników wątku czatu.

Tworzenie klienta czatu

Pozwoli to tworzyć, pobierać, wyświetlać lub usuwać wątki czatu.

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

Tworzenie klienta wątku czatu

Obiekt ChatThreadClient umożliwia wykonywanie operacji specyficznych dla wątku czatu, takiego jak wysyłanie wiadomości, pobieranie wiadomości, aktualizowanie tematu wątku czatu, dodawanie uczestników do wątku czatu itp.

Możesz go pobrać, tworząc nowy wątek czatu przy użyciu obiektu 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)

Ponadto klient może również kierować żądanie tak, aby było powtarzalne; oznacza to, że jeśli klient wykonuje żądanie wiele razy z tym samym Idempotency-Token i otrzyma odpowiednią odpowiedź bez serwera wykonującego żądanie wiele razy. Wartość Idempotency-Token jest nieprzezroczystym ciągiem reprezentującym wygenerowaną przez klienta, globalnie unikatową przez cały czas identyfikator żądania.

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)

Alternatywnie, jeśli wcześniej utworzono wątek czatu i masz jego thread_id, możesz go utworzyć, wykonując następujące czynności:

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

Kluczowe pojęcia

Konwersacja czatu jest reprezentowana przez wątek czatu. Każdy użytkownik wątku jest nazywany uczestnikiem wątku. Uczestnicy wątku mogą rozmawiać ze sobą prywatnie na czacie 1:1 lub przytulać się w 1:N czat grupowy. Użytkownicy otrzymują również aktualizacje niemal w czasie rzeczywistym, gdy inni piszą i kiedy czytają komunikaty.

Po zainicjowaniu ChatClient klasy można wykonać następujące operacje czatu:

Tworzenie, pobieranie, aktualizowanie i usuwanie wątków

Wykonywanie operacji CRD(Create-Read-Delete) w wątkach

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

Po zainicjowaniu ChatThreadClient klasy można wykonać następujące operacje czatu:

Aktualizuj wątek

Wykonywanie operacji aktualizacji w temacie wątku

update_topic(topic, **kwargs)

Pobieranie właściwości wątku czatu

get_properties(**kwargs)

Wysyłanie, pobieranie, aktualizowanie i usuwanie komunikatów

Wykonywanie operacji CRUD(Create-Read-Update-Delete) na komunikatach

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

Pobieranie, dodawanie i usuwanie uczestników

Wykonywanie operacji CRD(Create-Read-Delete) na uczestników wątku

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

Wysyłanie powiadomienia o wpisywaniu

Powiadamianie usługi o wpisaniu powiadomienia

send_typing_notification(**kwargs)

Wysyłanie i pobieranie potwierdzenia odczytu

Powiadom usługę, że komunikat jest odczytywany i pobiera listę odczytanych komunikatów.

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

Przykłady

W poniższych sekcjach przedstawiono kilka fragmentów kodu obejmujących niektóre z najbardziej typowych zadań, w tym:

• Operacje wątków
• Operacje komunikatów
• Operacje uczestnika wątku
• Operacje zdarzeń

Operacje wątków

Tworzenie wątku

create_chat_thread Użyj metody , aby utworzyć wątek czatu.

• Użyj topic, wymagane, aby nadać temat wątku;
• Użyj opcji thread_participants, opcjonalnie, aby podać listę ChatParticipant , która ma zostać dodana do wątku;
  • user, wymagane, jest CommunicationUserIdentifier to utworzony przez CommunicationIdentityClient.create_user() z tokenów dostępu użytkowników
  • display_name, opcjonalnie, jest nazwą wyświetlaną uczestnika wątku.
  • share_history_time, opcjonalnie, czas, z którego historia czatu jest udostępniana uczestnikowi.
• Użyj opcji idempotency_token, opcjonalnie, aby określić unikatowy identyfikator żądania.

CreateChatThreadResult jest wynikiem zwróconym podczas tworzenia wątku. Można go użyć do pobrania id utworzonego wątku czatu. Następnie można go id użyć do pobrania ChatThreadClient obiektu przy użyciu get_chat_thread_client metody . ChatThreadClient może służyć do wykonywania innych operacji czatu w tym wątku czatu.

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

Pobieranie wątku

Metoda używa get_properties metody pobiera element ChatThreadProperties z usługi; thread_id jest unikatowym identyfikatorem wątku.

chat_thread_properties = chat_thread_client.get_properties()

Wyświetlanie listy wątków czatu

Użycie list_chat_threads metody pobiera listę utworzonych wątków czatu

• Użyj opcji results_per_page, opcjonalnie, maksymalna liczba komunikatów do zwrócenia na stronę.
• Użyj start_timeopcji , opcjonalnie, godzina rozpoczęcia, w której kwerenda zakresu.

Iterator [ChatThreadItem] elementu to odpowiedź zwrócona z wątków listy

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)

Aktualizowanie tematu wątku

Użyj update_topic metody , aby zaktualizować właściwości wątku. topic służy do opisywania zmiany tematu wątku

• Służy topic do nadawania wątkowi nowego tematu;

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

chat_thread = chat_thread_client.get_properties(thread_id)

assert chat_thread.topic == topic

Usuwanie wątku

Użyj delete_chat_thread metody , aby usunąć wątek; thread_id jest unikatowym identyfikatorem wątku.

• Użyj thread_id, wymagane, aby określić unikatowy identyfikator wątku.

chat_client.delete_chat_thread(thread_id=thread_id)

Operacje komunikatów

Wysyłanie komunikatu

Metoda służy send_message do wysyłania komunikatu do wątku zidentyfikowanego przez thread_idelement .

• Użyj polecenia content, wymagane, aby podać zawartość wiadomości na czacie.
• Użyj opcji chat_message_type, opcjonalnie, aby podać typ wiadomości czatu. Możliwe wartości to: ChatMessageType.TEXT, ChatMessageType.HTML, 'text', , 'html'; jeśli nie zostanie określony, ChatMessageType.TEXT zostanie ustawiona
• Użyj sender_display_nameopcji ,opcjonalnie, aby określić nazwę wyświetlaną nadawcy, jeśli nie zostanie określona, zostanie ustawiona pusta nazwa

SendChatMessageResult to odpowiedź zwrócona podczas wysyłania komunikatu, zawiera identyfikator, który jest unikatowym identyfikatorem komunikatu.

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)

Pobieranie komunikatu

Metoda use get_message pobiera komunikat z usługi; message_id jest unikatowym identyfikatorem komunikatu.

• Użyj message_idpolecenia ,required, aby określić identyfikator wiadomości istniejącej wiadomości ChatMessage to odpowiedź zwrócona podczas pobierania komunikatu, zawiera identyfikator, który jest unikatowym identyfikatorem wiadomości, a inne pola można znaleźć w artykule 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)

Wyświetlanie listy komunikatów

Metoda pobiera list_messages komunikaty z usługi.

• Użyj opcji results_per_page, opcjonalnie, maksymalna liczba komunikatów do zwrócenia na stronę.
• Użyj start_timeopcji , opcjonalnie, godzina rozpoczęcia, w której kwerenda zakresu.

Iterator [ChatMessage] elementu to odpowiedź zwrócona z listy komunikatów

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)

Aktualizowanie komunikatu

Służy update_message do aktualizowania komunikatu identyfikowanego przez identyfikator threadId i messageId.

• Użyj message_idparametru ,required, jest unikatowym identyfikatorem wiadomości.
• Użyj contentopcji , opcjonalnie, to zawartość komunikatu do zaktualizowania; jeśli nie zostanie określona, zostanie przypisana jako pusta

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

Usuwanie wiadomości

Użyj polecenia delete_message , aby usunąć komunikat.

• Użyj message_id, wymagane, jest unikatowym identyfikatorem wiadomości.

chat_thread_client.delete_message(message_id=send_message_result_id)

Operacje uczestnika wątku

Wyświetlanie listy uczestników wątku

Użyj polecenia list_participants , aby pobrać uczestników wątku.

• Użyj results_per_pageopcji , opcjonalnie, maksymalna liczba uczestników do zwrócenia na stronę.
• Użyj skipopcji , opcjonalnie, aby pominąć uczestników do określonej pozycji w odpowiedzi.

Iterator elementu [ChatParticipant] to odpowiedź zwrócona przez uczestników listy

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)

Dodawanie uczestników wątku

Użyj add_participants metody , aby dodać uczestników wątku do wątku.

• Użyj , thread_participantswymagane, aby wyświetlić listę ChatParticipant elementów do dodania do wątku;
  • user, wymagane, jest CommunicationUserIdentifier to utworzony przez CommunicationIdentityClient.create_user() z tokenów dostępu użytkowników
  • display_name, opcjonalnie, jest nazwą wyświetlaną uczestnika wątku.
  • share_history_time, opcjonalnie, czas, z którego historia czatu jest udostępniana uczestnikowi.

Zwracany jest element A list(tuple(ChatParticipant, ChatError)) . Po pomyślnym dodaniu uczestnika oczekiwana jest pusta lista. W przypadku wystąpienia błędu podczas dodawania uczestnika lista jest wypełniana niepowodzeniem uczestników wraz z błędem, który wystąpił.

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)

Usuwanie uczestnika wątku

Użyj remove_participant metody , aby usunąć uczestnika wątku z wątku zidentyfikowanego przez threadId. identifier jest elementem utworzonym CommunicationUserIdentifier przez CommunicationIdentityClient.create_user() z azure-communication-identity

i został dodany do tego wątku czatu.

• Użyj identifier polecenia , aby określić CommunicationUserIdentifier utworzony element

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

Operacje zdarzeń

Wysyłanie powiadomienia o wpisywaniu

Użyj send_typing_notification metody , aby opublikować zdarzenie powiadomienia w wątku w imieniu użytkownika.

chat_thread_client.send_typing_notification()

Wysyłanie potwierdzenia odczytu

Użyj send_read_receipt metody , aby opublikować zdarzenie potwierdzenia odczytu do wątku w imieniu użytkownika.

• Służy message_id do określania identyfikatora wiadomości, której potwierdzenie odczytu ma zostać wysłane

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)

Wyświetlanie listy potwierdzeń odczytu

Metoda pobiera list_read_receipts potwierdzenia odczytu dla wątku.

• Użyj results_per_pageopcji , opcjonalnie, maksymalna liczba potwierdzeń odczytu, które mają zostać zwrócone na stronę.
• Użyj opcji skip,opcjonalnie, aby pominąć potwierdzenia odczytu do określonej pozycji w odpowiedzi.

Iteratorem [ChatMessageReadReceipt] jest odpowiedź zwrócona z listy potwierdzeń odczytu

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)

Przykładowy kod

Są to przykłady kodu, które pokazują typowe operacje scenariuszy z biblioteką klienta usługi Azure Communication Chat. Asynchroniczne wersje przykładów (przykładowe pliki języka Python dołączone za pomocą _asyncpolecenia ) pokazują operacje asynchroniczne. Przed uruchomieniem przykładowego kodu zapoznaj się z tematem Wymagania wstępne

aby utworzyć zasób, a następnie ustawić niektóre zmienne środowiskowe

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

Rozwiązywanie problemów

Występują problemy? Ta sekcja powinna zawierać szczegółowe informacje dotyczące tego, co należy tam zrobić.

Następne kroki

Więcej przykładowego kodu powinno się znaleźć tutaj wraz z linkami do odpowiednich przykładowych testów.

Współtworzenie

Jeśli napotkasz jakiekolwiek usterki lub masz sugestie, zgłoś problem w sekcji Problemy w projekcie.