Клиентская библиотека пакета чата коммуникации Azure для Python версии 1.2.0

Этот пакет содержит пакет SDK python для Службы коммуникации Azure для чата. Дополнительные сведения о Службы коммуникации Azure см. здесь.

Исходный код | Пакет (Pypi) | Пакет (Conda) | Справочная документация по | APIДокументация по продукту

Заявление об отказе

Поддержка пакетов Python для Пакета Sdk Azure для Python 2.7 закончилась 1 января 2022 г. Дополнительные сведения и вопросы см. на https://github.com/Azure/azure-sdk-for-python/issues/20691

Начало работы

Предварительные требования

• Для использования этого пакета требуется Python 3.7 или более поздней версии.
• Развернутый ресурс Служб коммуникации. Для настройки можно использовать портал Azure или Azure PowerShell.

Установка пакета

Установите пакет SDK для чата Службы коммуникации Azure.

pip install --pre azure-communication-chat

Маркеры доступа пользователей

Маркеры доступа пользователей позволяют создавать клиентские приложения, которые напрямую проходят проверку подлинности в Службах коммуникации Azure. Эти маркеры можно создать с помощью модуля azure.communication.identity, а затем использовать их для инициализации пакетов SDK для Служб коммуникации. Пример использования 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

Созданный user выше объект будет использоваться позже, так как этот пользователь должен быть добавлен в качестве участника нового потока чата при его создании с помощью этого маркера. Это связано с тем, что инициатор запроса на создание должен находиться в списке участников потока чата.

Создание клиента чата

Это позволит создавать, получать, перечислять или удалять потоки чата.

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

Создание клиента потока чата

ChatThreadClient позволяет выполнять операции, относящиеся к потоку чата, такие как отправка сообщения, получение сообщения, обновление темы чата, добавление участников в поток чата и т. д.

Вы можете получить его, создав новый поток чата с помощью 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)

Кроме того, клиент также может направлять запрос, чтобы запрос был повторяемым; то есть, если клиент выполняет запрос несколько раз с одной и той же Idempotency-Token, и он получит соответствующий ответ, если сервер не выполнит запрос несколько раз. Значение Idempotency-Token является непрозрачной строкой, представляющей созданный клиентом, глобально уникальный для всех времен идентификатор запроса.

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)

Кроме того, если вы уже создали поток чата и у вас есть его thread_id, вы можете создать его следующим образом:

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

Основные понятия

Беседа в чате представлена потоком чата. Каждый пользователь в потоке называется участником потока. Участники потока могут общаться друг с другом в частном порядке в чате 1:1 или ютиться в групповом чате 1:N. Пользователи также получают обновления практически в режиме реального времени, когда другие пользователи вводят текст и когда они прочитали сообщения.

После инициализации ChatClient класса можно выполнять следующие операции чата:

Создание, получение, обновление и удаление потоков

Выполнение операций CRD(Create-Read-Delete) в потоках

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

После инициализации ChatThreadClient класса можно выполнять следующие операции чата:

Поток обновления

Выполнение операции обновления в разделе потока

update_topic(topic, **kwargs)

Получение свойств потока чата

get_properties(**kwargs)

Отправка, получение, обновление и удаление сообщений

Выполнение операций CRUD(Create-Read-Update-Delete) с сообщениями

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

Получение, добавление и удаление участников

Выполнение операций CRD(Create-Read-Delete) с участниками потока

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

Отправка уведомления о вводе

Уведомление службы о вводе уведомления

send_typing_notification(**kwargs)

Отправка и получение уведомления о прочтении

Уведомите службу о считываемом сообщении и получите список прочитанных сообщений.

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

Примеры

В следующих разделах представлено несколько фрагментов кода, охватывающих некоторые из наиболее распространенных задач, в том числе:

• Операции с потоками
• Операции с сообщениями
• Операции с участниками потока
• Операции с событиями

Операции с потоками

Создание потока

Для создания потока чата используйте метод create_chat_thread.

• Используйте topic, обязательный, чтобы предоставить раздел потока;
• Используйте thread_participants, необязательно, чтобы предоставить список , ChatParticipant который будет добавлен в поток;
  • userобязательно. Это CommunicationUserIdentifier объект, созданный CommunicationIdentityClient.create_user() из маркеров доступа пользователей.
  • display_name (необязательно) — это отображаемое имя для участника потока.
  • share_history_time (необязательно) — это время, начиная с которого участнику предоставляется доступ к журналу чата.
• Используйте idempotency_token, необязательно, чтобы указать уникальный идентификатор для запроса.

CreateChatThreadResult является результатом, возвращаемым при создании потока, который можно использовать для получения id созданного потока чата. Затем этот id можно использовать, чтобы получить объект ChatThreadClient с помощью метода get_chat_thread_client. ChatThreadClient можно использовать для выполнения других операций чата в этом потоке чата.

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

Получение потока

Используйте метод get_properties для извлечения ChatThreadProperties из службы. thread_id — это уникальный идентификатор потока.

chat_thread_properties = chat_thread_client.get_properties()

Перечисление потоков чата

Метод Use list_chat_threads извлекает список созданных потоков чата.

• Используйте results_per_page(необязательно) максимальное количество сообщений, возвращаемых на страницу.
• Используйте start_time( необязательно) время начала запроса диапазона.

Итератор [ChatThreadItem] является ответом, возвращенным из списка потоков.

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)

Обновление раздела потока

Используйте update_topic метод для обновления свойств потока. topic используется для описания изменения раздела потока

• Используйте для 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

Удаление потока

Используйте delete_chat_thread метод для удаления потока; thread_id — это уникальный идентификатор потока.

• Используйте thread_id, который требуется, чтобы указать уникальный идентификатор потока.

chat_client.delete_chat_thread(thread_id=thread_id)

Операции с сообщениями

Отправка сообщения

Используйте send_message метод для отправки сообщения в поток, определенный .thread_id

• Используйте content, обязательный, чтобы предоставить содержимое сообщения чата.
• Используйте chat_message_type, необязательно, чтобы указать тип сообщения чата. Возможные значения: ChatMessageType.TEXT, ChatMessageType.HTML, 'text', 'html'; если они не указаны, ChatMessageType.TEXT будут заданы.
• Используйте sender_display_name, необязательно, чтобы указать отображаемое имя отправителя. Если оно не указано, будет задано пустое имя.

SendChatMessageResult — ответ, возвращенный при отправке сообщения. Содержит идентификатор, который является уникальным идентификатором сообщения.

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)

Получение сообщения

Метод Use get_message извлекает сообщение из службы; message_id является уникальным идентификатором сообщения.

• Используйте message_id, обязательно, чтобы указать идентификатор существующего сообщения ChatMessage — это ответ, возвращенный при получении сообщения, он содержит идентификатор, который является уникальным идентификатором сообщения, а другие поля см. в статье 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)

Вывод списка сообщений

Метод Use list_messages извлекает сообщения из службы.

• Используйте results_per_page(необязательно) максимальное количество сообщений, возвращаемых на страницу.
• Используйте start_time( необязательно) время начала запроса диапазона.

Итератор [ChatMessage] является ответом, возвращенным из списка сообщений.

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)

Обновление сообщения

Используйте для update_message обновления сообщения, определяемого threadId и messageId.

• Используйте message_id как обязательный уникальный идентификатор сообщения.
• Используйте content (необязательно) в качестве обновляемого содержимого сообщения. Если не указано, то должно быть пустым.

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

Удаление сообщения

Используйте delete_message для удаления сообщения.

• Используйте message_id, обязательно, — это уникальный идентификатор сообщения.

chat_thread_client.delete_message(message_id=send_message_result_id)

Операции с участниками потока

Перечисление участников потока

Используйте list_participants, чтобы получить участников потока.

• Используйте results_per_page (необязательно), чтобы указать максимальное число участников, возвращаемых на каждой странице.
• Используйте skip (необязательно), чтобы пропустить участников вплоть до указанной позиции в ответе.

Итератор [ChatParticipant] является ответом, возвращаемым из списка участников.

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)

Добавление участников потока

Используйте add_participants метод для добавления участников потока в поток.

• Используйте thread_participants, обязательный, чтобы получить список ChatParticipant для добавления в поток;
  • userобязательно. Это CommunicationUserIdentifier объект, созданный CommunicationIdentityClient.create_user() из маркеров доступа пользователей.
  • display_name (необязательно) — это отображаемое имя для участника потока.
  • share_history_time (необязательно) — это время, начиная с которого участнику предоставляется доступ к журналу чата.

возвращается list(tuple(ChatParticipant, ChatError)); Если участник успешно добавлен, ожидается пустой список. Если произошла ошибка при добавлении участника, список заполняется сбойными участниками вместе с возникшей ошибкой.

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)

Удаление участника потока

Используйте метод remove_participant, чтобы удалить участников из потока, идентифицируемого с помощью threadId. identifier — это объект, CommunicationUserIdentifier созданный CommunicationIdentityClient.create_user() из azure-communication-identity

и был добавлен в этот поток чата.

• Используйте identifier , чтобы указать 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))

Операции с событиями

Отправка уведомления о вводе

Используйте send_typing_notification метод для публикации события уведомления о вводе в поток от имени пользователя.

chat_thread_client.send_typing_notification()

Отправка уведомления о прочтении

Используйте send_read_receipt метод для отправки события уведомления о прочтении в поток от имени пользователя.

• Используйте 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)

Получение списка уведомлений о прочтении

Метод Use list_read_receipts извлекает уведомления о прочтении для потока.

• Используйте results_per_page, необязательно, Максимальное количество уведомлений о прочтении, возвращаемых на страницу.
• Используйте skip,необязательно, чтобы пропускать уведомления о прочтении до указанной позиции в ответе.

Итератор [ChatMessageReadReceipt] является ответом, возвращенным из списка уведомлений о прочтении.

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)

Пример кода

Ниже приведены примеры кода, демонстрирующие распространенные операции сценария с клиентской библиотекой чата коммуникации Azure. Асинхронные версии примеров (файлы примеров Python, добавленные с _asyncпомощью ) показывают асинхронные операции. Перед запуском примера кода ознакомьтесь с предварительными условиями.

чтобы создать ресурс, а затем задать некоторые переменные среды

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

Устранение неполадок

Возникли проблемы? Этот раздел должен содержать подробные сведения о том, что там делать.

Дальнейшие действия

Здесь должны быть приведены дополнительные примеры кода, а также ссылки на соответствующие примеры тестов.

Участие

Если вы столкнулись с ошибками или у вас есть предложения, сообщите о проблеме в разделе Проблемы проекта.