Clientbibliothek des Azure Communication Chat-Pakets für Python– Version 1.2.0

Dieses Paket enthält ein Python SDK für Azure Communication Services für Chat. Weitere Informationen zu Azure Communication Services finden Sie hier.

Quellcode | Paket (Pypi) | Paket (Conda) | API-Referenzdokumentation | Produktdokumentation

Haftungsausschluss

Die Unterstützung von Azure SDK-Python-Paketen für Python 2.7 endet am 01. Januar 2022. Weitere Informationen und Antworten finden Sie unter https://github.com/Azure/azure-sdk-for-python/issues/20691.

Erste Schritte

Voraussetzungen

• Für die Verwendung dieses Pakets ist Python 3.7 oder höher erforderlich.
• Eine bereitgestellte Communication Services-Ressource. Sie können das Azure-Portal oder die Azure PowerShell zum Einrichten verwenden.

Installieren des Pakets

Installieren Sie das Azure Communication Service Chat SDK.

pip install --pre azure-communication-chat

Benutzer-Zugriffstoken

Mit Benutzerzugriffstoken können Sie Clientanwendungen erstellen, die gegenüber Azure Communication Services direkt authentifiziert werden. Sie können diese Token mit dem Modul azure.communication.identity generieren und sie dann verwenden, um die Communication Services-SDKs zu initialisieren. Beispiel für die Verwendung von 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

Die user oben erstellte wird später verwendet, da dieser Benutzer beim Erstellen mit diesem Token als Teilnehmer eines neuen Chatthreads hinzugefügt werden sollte. Dies liegt daran, dass der Initiator der Erstellungsanforderung in der Liste der Teilnehmer des Chatthreads enthalten sein muss.

Erstellen des Chatclients

Dadurch können Sie Chatthreads erstellen, abrufen, auflisten oder löschen.

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

Erstellen eines Chatthreadclients

Der ChatThreadClient ermöglicht es Ihnen, Vorgänge auszuführen, die speziell für einen Chatthread gelten, z. B. Nachrichten senden, Nachrichten abrufen, das Chatthreadthema aktualisieren, Teilnehmer zum Chatthread hinzufügen usw.

Sie können ihn erhalten, indem Sie mithilfe von ChatClient einen neuen Chatthread erstellen:

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)

Darüber hinaus kann der Client auch weiterleiten, damit die Anforderung wiederholbar ist. Das heißt, wenn der Client die Anforderung mehrmals mit demselben Idempotency-Token und erhält eine entsprechende Antwort, ohne dass der Server die Anforderung mehrmals ausführt. Der Wert der Idempotency-Token ist eine undurchsichtige Zeichenfolge, die einen vom Client generierten, global eindeutigen Bezeichner für die Anforderung darstellt.

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)

Wenn Sie zuvor einen Chatthread erstellt haben und seine thread_id haben, können Sie ihn auch wie folgt erstellen:

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

Wichtige Begriffe

Eine Chatunterhaltung wird durch einen Chatthread dargestellt. Jeder Benutzer im Thread wird als Threadteilnehmer bezeichnet. Threadteilnehmer können privat in einem 1:1-Chat miteinander chatten oder sich in einem 1:N-Gruppenchat zusammenraufen. Benutzer erhalten außerdem nahezu in Echtzeit Updates für den Zeitpunkt, an dem andere Benutzer eingeben und die Nachrichten gelesen haben.

Nachdem Sie eine ChatClient Klasse initialisiert haben, können Sie die folgenden Chatvorgänge ausführen:

Erstellen, Abrufen, Aktualisieren und Löschen von Threads

Ausführen von CRD-Vorgängen (Create-Read-Delete) für Threads

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

Nachdem Sie eine ChatThreadClient Klasse initialisiert haben, können Sie die folgenden Chatvorgänge ausführen:

Updatethread

Ausführen eines Updatevorgangs für das Threadthema

update_topic(topic, **kwargs)

Abrufen von Chatthreadeigenschaften

get_properties(**kwargs)

Senden, Abrufen, Aktualisieren und Löschen von Nachrichten

Ausführen von CRUD-Vorgängen (Create-Read-Update-Delete) für Nachrichten

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

Abrufen, Hinzufügen und Entfernen von Teilnehmern

Ausführen von CRD-Vorgängen (Create-Read-Delete) für Threadteilnehmer

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

Senden einer Eingabebenachrichtigung

Benachrichtigen des Diensts über die Eingabe einer Benachrichtigung

send_typing_notification(**kwargs)

Senden und Abrufen der Lesebestätigung

Benachrichtigen Sie den Dienst, dass eine Nachricht gelesen wird, und rufen Sie eine Liste der gelesenen Nachrichten ab.

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

Beispiele

Die folgenden Abschnitte enthalten mehrere Codeausschnitte, die einige der häufigsten Aufgaben abdecken, einschließlich:

• Threadvorgänge
• Nachrichtenvorgänge
• Threadteilnehmervorgänge
• Ereignisvorgänge

Threadvorgänge

Erstellen eines Threads

Verwenden Sie die create_chat_thread-Methode, um einen Chatthread zu erstellen.

• Verwenden Sie topicerforderlich, um ein Threadthema zu geben.
• Verwenden Sie thread_participantsoptional , um eine Liste anzugeben, die ChatParticipant dem Thread hinzugefügt werden soll.
  • user, erforderlich, es ist die, die CommunicationUserIdentifier Sie von CommunicationIdentityClient.create_user() aus Benutzerzugriffstoken erstellt haben.
  • display_name (optional) ist der Anzeigename für den Threadteilnehmer.
  • share_history_time (optional) ist der Zeitpunkt, ab dem der Chatverlauf für den Teilnehmer freigegeben wird.
• Verwenden Sie idempotency_tokenoptional , um den eindeutigen Bezeichner für die Anforderung anzugeben.

CreateChatThreadResult ist das Ergebnis, das beim Erstellen eines Threads zurückgegeben wurde. Sie können es verwenden, um die ID (id) des erstellten Chatthreads abzurufen. Diese ID (id) kann dann zum Abrufen eines ChatThreadClient-Objekts mithilfe der Methode get_chat_thread_client verwendet werden. Mit ChatThreadClient können weitere Chatvorgänge für diesen Chatthread ausgeführt werden.

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

Abrufen eines Threads

Mithilfe der Methode get_properties wird ChatThreadProperties aus dem Dienst abgerufen. thread_id ist die eindeutige ID des Threads.

chat_thread_properties = chat_thread_client.get_properties()

Auflisten von Chatthreads

Die Use-Methode list_chat_threads ruft die Liste der erstellten Chatthreads ab.

• Verwenden Sie results_per_page, optional, Die maximale Anzahl von Nachrichten, die pro Seite zurückgegeben werden sollen.
• Verwenden Sie start_time, optional, Die Startzeit, in der die Bereichsabfrage ausgeführt wird.

Beim Auflisten von Threads wird als Antwort ein Iterator vom Typ [ChatThreadItem] zurückgegeben.

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)

Aktualisieren eines Threadthemas

Verwenden Sie update_topic die -Methode, um die Eigenschaften eines Threads zu aktualisieren. topic wird verwendet, um die Änderung des Threadthemas zu beschreiben.

• Verwenden Sie topic , um thread ein neues Thema zu geben;

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

chat_thread = chat_thread_client.get_properties(thread_id)

assert chat_thread.topic == topic

Löschen eines Threads

Verwenden Sie delete_chat_thread die -Methode, um einen Thread zu löschen; thread_id ist die eindeutige ID des Threads.

• Verwenden Sie thread_id (erforderlich), um die eindeutige ID des Threads anzugeben.

chat_client.delete_chat_thread(thread_id=thread_id)

Nachrichtenvorgänge

Senden einer Nachricht

Verwenden Sie send_message die -Methode, um eine Nachricht an einen Thread zu senden, der durch identifiziert wird thread_id.

• Verwenden Sie contenterforderlich, um den Chatnachrichteninhalt bereitzustellen.
• Verwenden Sie chat_message_typeoptional , um den Chatnachrichtentyp anzugeben. Mögliche Werte: ChatMessageType.TEXT, ChatMessageType.HTML, 'text', 'html'; wenn nicht angegeben, ChatMessageType.TEXT wird festgelegt.
• Verwenden Sie sender_display_nameoptional, um den Anzeigenamen des Absenders anzugeben. Wenn nicht angegeben, wird ein leerer Name festgelegt.

SendChatMessageResult ist die Antwort, die nach dem Senden einer Nachricht zurückgegeben wird. Sie enthält eine ID, bei der es sich um die eindeutige ID der Nachricht handelt.

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)

Abrufen einer Nachricht

Die Use-Methode get_message ruft eine Nachricht vom Dienst ab; message_id ist die eindeutige ID der Nachricht.

• Verwenden Sie message_id, erforderlich, um die Nachrichten-ID einer vorhandenen Nachricht ChatMessage anzugeben, ist die Antwort, die vom Abrufen einer Nachricht zurückgegeben wird, enthält eine ID, die die eindeutige ID der Nachricht ist. Weitere Felder finden Sie unter 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)

Auflisten von Nachrichten

Mit der - list_messages Methode werden Nachrichten aus dem Dienst abgerufen.

• Verwenden Sie results_per_page, optional, Die maximale Anzahl von Nachrichten, die pro Seite zurückgegeben werden sollen.
• Verwenden Sie start_time, optional, Die Startzeit, in der die Bereichsabfrage ausgeführt wird.

Beim Auflisten von Nachrichten wird als Antwort ein Iterator vom Typ [ChatMessage] zurückgegeben.

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)

Aktualisieren einer Nachricht

Verwenden Sie update_message , um eine Nachricht zu aktualisieren, die durch threadId und messageId identifiziert wird.

• message_id (erforderlich) ist die eindeutige ID der Nachricht
• content (optional) ist der Nachrichteninhalt, der aktualisiert werden soll. Wird kein Inhalt angegeben, wird er als leer zugewiesen.

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

Löschen einer Nachricht

Verwenden Sie delete_message , um eine Nachricht zu löschen.

• Verwenden Sie message_id, erforderlich, ist die eindeutige ID der Nachricht.

chat_thread_client.delete_message(message_id=send_message_result_id)

Threadteilnehmervorgänge

Auflisten von Threadteilnehmern

Verwenden Sie list_participants, um die Teilnehmer des Threads abzurufen.

• Verwenden Sie optional results_per_page: die maximale Anzahl von Teilnehmern, die pro Seite zurückgegeben werden sollen.
• Verwenden Sie skip optional, um die Teilnehmer bis zu angegebenen Position in der Antwort zu überspringen.

Beim Auflisten von Teilnehmern wird als Antwort ein Iterator vom Typ [ChatParticipant] zurückgegeben.

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)

Hinzufügen von Threadteilnehmern

Verwenden Sie add_participants die -Methode, um dem Thread Threadteilnehmer hinzuzufügen.

• Verwenden Sie thread_participantserforderlich, um die auflisten, die ChatParticipant dem Thread hinzugefügt werden soll.
  • user, erforderlich, es ist die, die CommunicationUserIdentifier Sie von CommunicationIdentityClient.create_user() aus Benutzerzugriffstoken erstellt haben.
  • display_name (optional) ist der Anzeigename für den Threadteilnehmer.
  • share_history_time (optional) ist der Zeitpunkt, ab dem der Chatverlauf für den Teilnehmer freigegeben wird.

Ein list(tuple(ChatParticipant, ChatError)) wird zurückgegeben. Wenn der Teilnehmer erfolgreich hinzugefügt wurde, wird eine leere Liste erwartet. Tritt beim Hinzufügen des Teilnehmers ein Fehler auf, wird die Liste mit den Teilnehmern, bei denen ein Fehler auftrat, sowie den aufgetretenen Fehler aufgefüllt.

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)

Threadteilnehmer entfernen

Verwenden Sie die Methode remove_participant, um den per Thread-ID identifizierten Threadteilnehmer aus dem Thread zu entfernen. identifier ist die , die CommunicationUserIdentifier Sie von CommunicationIdentityClient.create_user() aus erstellt haben. azure-communication-identity

und wurde diesem Chatthread hinzugefügt.

• Verwenden Sie identifier , um die CommunicationUserIdentifier von Ihnen erstellte anzugeben.

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

Ereignisvorgänge

Senden einer Eingabebenachrichtigung

Verwenden Sie send_typing_notification die -Methode, um ein Eingabebenachrichtigungsereignis im Namen eines Benutzers in einem Thread zu posten.

chat_thread_client.send_typing_notification()

Senden einer Lesebestätigung

Verwenden Sie send_read_receipt die -Methode, um ein Lesebestätigungsereignis im Namen eines Benutzers in einem Thread zu posten.

• Verwenden Sie message_id , um die ID der Nachricht anzugeben, deren Lesebestätigung gesendet werden soll.

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)

Auflisten von Lesebestätigungen

Mit der - list_read_receipts Methode werden Lesebestätigungen für einen Thread abgerufen.

• Verwenden Sie results_per_pageoptional, Die maximale Anzahl von Lesebestätigungen, die pro Seite zurückgegeben werden sollen.
• Verwenden Sie skipoptional, um Lesebestätigungen bis zu einer angegebenen Position als Antwort zu überspringen.

Beim Auflisten von Lesebestätigungen wird als Antwort ein Iterator vom Typ [ChatMessageReadReceipt] zurückgegeben.

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)

Beispielcode

Dies sind Codebeispiele, die allgemeine Szenariovorgänge mit der Azure Communication Chat-Clientbibliothek veranschaulichen. Die asynchronen Versionen der Beispiele (die Python-Beispieldateien, die mit _asyncangefügt sind) zeigen asynchrone Vorgänge. Informationen zum Ausführen des Beispielcodes finden Sie unter Voraussetzungen.

, um eine Ressource zu erstellen, und legen Sie dann einige Umgebungsvariablen fest.

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

Problembehandlung

Treten Probleme auf? Dieser Abschnitt sollte Details dazu enthalten, was dort zu tun ist.

Nächste Schritte

Hier finden Sie weitere Beispielcode sowie Links zu den entsprechenden Beispieltests.

Mitwirken

Wenn Fehler auftreten oder Vorschläge vorliegen, melden Sie ein Problem im Abschnitt Probleme des Projekts.