Biblioteca cliente del paquete de chat de Comunicación de Azure para Python, versión 1.2.0

Este paquete contiene un SDK de Python para Azure Communication Services para chat. Obtenga más información sobre Azure Communication Services aquí.

Código | fuentePaquete (Pypi) | Paquete (Conda) | Documentación | de referencia de APIDocumentación del producto

Declinación de responsabilidades

Los paquetes de Python del SDK de Azure admiten Python 2.7 finalizó el 01 de enero de 2022. Para más información y preguntas, consulte https://github.com/Azure/azure-sdk-for-python/issues/20691.

Introducción

Requisitos previos

• Se requiere Python 3.7 o posterior para usar este paquete.
• Un recurso de Communication Services implementado. Puede usar Azure Portal o el Azure PowerShell para configurarlo.

Instalar el paquete

Instale el SDK de chat de Azure Communication Service.

pip install --pre azure-communication-chat

Tokens de acceso de usuario

Los tokens de acceso de usuario permiten compilar aplicaciones cliente que se autentiquen directamente en Azure Communication Services. Puede generar estos tokens con el módulo azure.communication.identity y, después, usarlos para inicializar los SDK de Communication Services. Ejemplo de uso de 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

El user elemento creado anteriormente se usará más adelante, ya que ese usuario debe agregarse como participante de un nuevo subproceso de chat al crearlo con este token. Esto se debe a que el iniciador de la solicitud de creación debe estar en la lista de los participantes del subproceso de chat.

Crear el cliente de chat

Esto le permitirá crear, obtener, enumerar o eliminar subprocesos de chat.

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

Crear cliente de subprocesos de chat

ChatThreadClient le permitirá realizar operaciones específicas de un subproceso de chat, como enviar un mensaje, obtener un mensaje, actualizar el tema del subproceso de chat, agregar participantes a la conversación de chat, etc.

Para obtenerlo, cree un nuevo subproceso de chat mediante 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)

Además, el cliente también puede dirigir para que la solicitud sea repetible; es decir, si el cliente realiza la solicitud varias veces con la misma Idempotency-Token y obtendrá una respuesta adecuada sin que el servidor ejecute la solicitud varias veces. El valor del Idempotency-Token es una cadena opaca que representa un identificador globalmente único para todo el tiempo generado por el cliente para la solicitud.

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)

Como alternativa, si ha creado un subproceso de chat antes y tiene su thread_id, puede crearlo mediante:

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

Conceptos clave

Una conversación de chat se representa mediante un subproceso de chat. Cada usuario del subproceso se denomina participante del subproceso. Los participantes de subprocesos pueden chatear entre sí de forma privada en un chat de 1:1 o agruparse en un chat de grupo 1:N. Los usuarios también obtienen actualizaciones casi en tiempo real para cuando otros escriben y cuando han leído los mensajes.

Una vez inicializada una ChatClient clase, puede realizar las siguientes operaciones de chat:

Creación, obtención, actualización y eliminación de subprocesos

Realizar operaciones CRD(Create-Read-Delete) en subprocesos

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

Una vez inicializada una ChatThreadClient clase, puede realizar las siguientes operaciones de chat:

Actualizar subproceso

Realizar la operación de actualización en el tema de subprocesos

update_topic(topic, **kwargs)

Obtener propiedades del subproceso de chat

get_properties(**kwargs)

Enviar, obtener, actualizar y eliminar mensajes

Realizar operaciones CRUD(Create-Read-Update-Delete) en mensajes

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

Obtener, agregar y quitar participantes

Realizar operaciones CRD(Create-Read-Delete) en los participantes del subproceso

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

Envío de notificación de escritura

Notificación al servicio de notificación de escritura

send_typing_notification(**kwargs)

Envío y obtención de recibo de lectura

Notifique al servicio que un mensaje se lee y obtiene una lista de mensajes de lectura.

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

Ejemplos

En las secciones siguientes se proporcionan varios fragmentos de código que abarcan algunas de las tareas más comunes, entre las que se incluyen:

• Operaciones de subprocesos
• Operaciones de mensaje
• Operaciones de participantes de subprocesos
• Operaciones de eventos

Operaciones de subprocesos

Creación de un subproceso

Use el método create_chat_thread para crear un subproceso de chat.

• Use topic, obligatorio, para proporcionar un tema de subproceso;
• Use thread_participants, opcional, para proporcionar una lista que ChatParticipant se va a agregar al subproceso;
  • user, obligatorio, es el CommunicationUserIdentifier que creó CommunicationIdentityClient.create_user() a partir de tokens de acceso de usuario.
  • display_name es opcional y es el nombre para mostrar del participante de la conversación.
  • share_history_time es opcional y es la hora a partir de la cual el historial de chat se compartió con el participante.
• Use idempotency_token, opcional, para especificar el identificador único de la solicitud.

CreateChatThreadResult es el resultado devuelto por la creación de un subproceso, puede utilizarlo para capturar id del subproceso de chat que se ha creado. Se puede utilizar id luego para capturar un objeto ChatThreadClient mediante el método get_chat_thread_client. Se puede usar ChatThreadClient para realizar otras operaciones de chat en este subproceso de chat.

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

Obtener un subproceso

Use el método get_properties para recuperar ChatThreadProperties del servicio; thread_id es el identificador único del subproceso.

chat_thread_properties = chat_thread_client.get_properties()

Lista de las conversaciones de chat

El método Use list_chat_threads recupera la lista de subprocesos de chat creados.

• Use results_per_page, opcional, el número máximo de mensajes que se devolverán por página.
• Use start_time, opcional, la hora de inicio en la que se encuentra la consulta de intervalo.

Un iterador de [ChatThreadItem] es la respuesta que devuelven los subprocesos de lista.

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)

Actualización de un tema de subprocesos

Use update_topic el método para actualizar las propiedades de un subproceso. topic se usa para describir el cambio del tema del subproceso.

• Use topic para dar a un subproceso un nuevo tema;

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

chat_thread = chat_thread_client.get_properties(thread_id)

assert chat_thread.topic == topic

Eliminación de un subproceso

Use delete_chat_thread el método para eliminar un subproceso; thread_id es el identificador único del subproceso.

• Utilice thread_id, obligatorio, para especificar el identificador único del subproceso.

chat_client.delete_chat_thread(thread_id=thread_id)

Operaciones de mensaje

Envío de un mensaje

Use send_message el método para enviar un mensaje a un subproceso identificado por thread_id.

• Use content, obligatorio, para proporcionar el contenido del mensaje de chat.
• Use chat_message_type, opcional, para proporcionar el tipo de mensaje de chat. Entre los valores posibles se incluyen: ChatMessageType.TEXT, ChatMessageType.HTML, 'text', 'html'; si no se especifica, ChatMessageType.TEXT se establecerá .
• Use sender_display_name,opcional, para especificar el nombre para mostrar del remitente, si no se especifica, se establecerá un nombre vacío.

SendChatMessageResult es la respuesta que se devuelve al enviar un mensaje. Contiene un id. que es el identificador único del mensaje.

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)

Obtención de mensajes

El método Use get_message recupera un mensaje del servicio; message_id es el identificador único del mensaje.

• Use message_id,required, para especificar el identificador de mensaje de un mensaje ChatMessage existente es la respuesta devuelta de obtener un mensaje, contiene un identificador, que es el identificador único del mensaje y otros campos, consulte 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)

Enumerar mensajes

El método Use list_messages recupera los mensajes del servicio.

• Use results_per_page, opcional, el número máximo de mensajes que se devolverán por página.
• Use start_time, opcional, la hora de inicio en la que se encuentra la consulta de intervalo.

Un iterador de [ChatMessage] es la respuesta que devuelven los mensajes de lista.

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)

Actualización de un mensaje

Use update_message para actualizar un mensaje identificado por threadId y messageId.

• Use message_id, obligatorio, que es el identificador único del mensaje.
• Use content, opcional, que es el contenido del mensaje que se va a actualizar; si no se especifica, se asignará para que esté vacío.

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

Eliminar un mensaje

Use delete_message para eliminar un mensaje.

• Use message_id, obligatorio, es el identificador único del mensaje.

chat_thread_client.delete_message(message_id=send_message_result_id)

Operaciones de participantes de subprocesos

Enumerar participantes del subproceso

Use list_participants para recuperar los participantes de la conversación.

• De forma opcional, use results_per_page para establecer el número máximo de participantes que se van a devolver por página.
• De forma opcional, use skip para omitir los participantes hasta una posición especificada en la respuesta.

Un iterador de [ChatParticipant] es la respuesta que devuelven los mensajes de la lista.

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)

Agregar participantes de subprocesos

Use add_participants el método para agregar participantes de subprocesos al subproceso.

• Use thread_participants, obligatorio, para enumerar el ChatParticipant que se va a agregar al subproceso;
  • user, obligatorio, es el CommunicationUserIdentifier que creó CommunicationIdentityClient.create_user() a partir de tokens de acceso de usuario.
  • display_name es opcional y es el nombre para mostrar del participante de la conversación.
  • share_history_time es opcional y es la hora a partir de la cual el historial de chat se compartió con el participante.

Se devuelve list(tuple(ChatParticipant, ChatError)). Cuando un participante se agrega correctamente, se espera una lista vacía. En caso de que se produzca un error al agregar un participante, la lista se rellena con los participantes con error junto con el error producido.

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)

Quitar participante del subproceso

Utilice el método remove_participant para quitar participantes de la conversación identificada por threadId. identifier es el CommunicationUserIdentifier objeto creado por CommunicationIdentityClient.create_user() a partir de . azure-communication-identity

y se agregó a este subproceso de chat.

• Use identifier para especificar el CommunicationUserIdentifier objeto que ha creado.

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

Operaciones de eventos

Envío de notificación de escritura

Use send_typing_notification el método para publicar un evento de notificación de escritura en un subproceso, en nombre de un usuario.

chat_thread_client.send_typing_notification()

Envío de confirmación de lectura

Use send_read_receipt el método para publicar un evento de recepción de lectura en un subproceso, en nombre de un usuario.

• Use message_id para especificar el identificador del mensaje cuyo recibo de lectura se va a enviar.

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)

Enumeración de las confirmaciones de lectura

El método Use list_read_receipts recupera recibos de lectura para un subproceso.

• Use results_per_page, opcional, el número máximo de recibos de lectura que se devolverán por página.
• Use skip,opcional, para omitir los recibos de lectura hasta una posición especificada en respuesta.

Un iterador de [ChatMessageReadReceipt] es la respuesta que devuelve las confirmaciones de lectura de lista.

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)

Código de ejemplo

Estos son ejemplos de código que muestran operaciones de escenario comunes con la biblioteca cliente de Chat de comunicación de Azure. Las versiones asincrónicas de los ejemplos (los archivos de ejemplo de Python anexados con _async) muestran operaciones asincrónicas. Antes de ejecutar el código de ejemplo, consulte Requisitos previos.

para crear un recurso y, a continuación, establecer algunas variables de entorno

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

Solución de problemas

¿Algún problema? Esta sección debe contener detalles sobre qué hacer allí.

Pasos siguientes

Más código de ejemplo debe ir aquí, junto con vínculos a las pruebas de ejemplo adecuadas.

Contribuciones

Si encuentra algún error o tiene sugerencias, envíe un problema en la sección Problemas del proyecto.