Biblioteca de cliente do Pacote de Chat de Comunicação do Azure para Python – versão 1.2.0

Este pacote contém um SDK Python para Azure Communication Services para Chat. Leia mais sobre Azure Communication Services aqui

Código fonte | Pacote (Pypi) | Pacote (Conda) | Documentação | de referência da APIDocumentação do produto

Exclusão de Responsabilidade

O suporte de pacotes Python do SDK do Azure para Python 2.7 terminou a 01 de janeiro de 2022. Para obter mais informações e perguntas, consulte https://github.com/Azure/azure-sdk-for-python/issues/20691

Introdução

Pré-requisitos

• O Python 3.7 ou posterior é necessário para utilizar este pacote.
• Um recurso dos Serviços de Comunicação implementado. Pode utilizar o Portal do Azure ou o Azure PowerShell para configurá-lo.

Instalar o pacote

Instale o SDK de Chat do Serviço de Comunicação do Azure.

pip install --pre azure-communication-chat

Tokens de Acesso de Utilizador

Os tokens de acesso de utilizador permitem-lhe criar aplicações cliente que se autenticam diretamente no Azure Communication Services. Pode gerar estes tokens com o módulo azure.communication.identity e, em seguida, utilizá-los para inicializar os SDKs dos Serviços de Comunicação. Exemplo de utilização 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

O user criado acima será utilizado mais tarde, porque esse utilizador deve ser adicionado como participante de um novo tópico de chat ao criá-lo com este token. É porque o iniciador do pedido de criação tem de estar na lista dos participantes do tópico de chat.

Criar o Cliente de Chat

Isto permite-lhe criar, obter, listar ou eliminar threads 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))

Criar Cliente de Tópicos de Chat

O ChatThreadClient permite-lhe executar operações específicas de um tópico de chat, como enviar mensagem, receber mensagem, atualizar o tópico do tópico de chat, adicionar participantes ao tópico de chat, etc.

Pode obtê-lo ao criar um novo tópico de chat com o 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)

Além disso, o cliente também pode direcionar para que o pedido seja repetível; ou seja, se o cliente fizer o pedido várias vezes com o mesmo Idempotency-Token e obterá uma resposta adequada sem que o servidor execute o pedido várias vezes. O valor do Idempotency-Token é uma cadeia opaca que representa um identificador globalmente exclusivo para todos os tempos gerado pelo cliente para o pedido.

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)

Em alternativa, se já tiver criado um tópico de chat e tiver o respetivo thread_id, pode criá-lo ao:

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

Conceitos-chave

Uma conversa de chat é representada por um tópico de chat. Cada utilizador no thread é chamado de participante de thread. Os participantes do thread podem conversar entre si em privado numa conversa 1:1 ou amontoar-se numa conversa de grupo 1:N. Os utilizadores também recebem atualizações quase em tempo real para quando outras pessoas estão a escrever e quando lerem as mensagens.

Depois de inicializar uma ChatClient classe, pode efetuar as seguintes operações de chat:

Criar, obter, atualizar e eliminar threads

Executar operações CRD(Create-Read-Delete) em threads

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

Depois de inicializar uma ChatThreadClient classe, pode efetuar as seguintes operações de chat:

Atualizar thread

Executar a operação atualização no tópico de thread

update_topic(topic, **kwargs)

Obter propriedades do tópico de chat

get_properties(**kwargs)

Enviar, obter, atualizar e eliminar mensagens

Executar operações CRUD(Create-Read-Update-Delete) em mensagens

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

Obter, adicionar e remover participantes

Executar operações CRD (Create-Read-Delete) nos participantes do thread

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

Enviar notificação de escrita

Notificar o serviço de notificação de escrita

send_typing_notification(**kwargs)

Enviar e obter recibo de leitura

Notifique o serviço de que uma mensagem é lida e obtenha uma lista de mensagens de leitura.

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

Exemplos

As secções seguintes fornecem vários fragmentos de código que abrangem algumas das tarefas mais comuns, incluindo:

• Operações de Thread
• Operações de Mensagens
• Operações de Participantes do Thread
• Operações de Eventos

Operações de Thread

Criar um thread

Utilize o create_chat_thread método para criar um tópico de chat.

• Utilize topic, necessário, para fornecer um tópico de tópico;
• Utilize thread_participants, opcional, para fornecer uma lista a ChatParticipant adicionar ao thread;
  • user, necessário, é o CommunicationUserIdentifier que criou por CommunicationIdentityClient.create_user() a partir de Tokens de Acesso de Utilizador
  • display_name, opcional, é o nome a apresentar para o participante do thread.
  • share_history_time, opcional, hora a partir da qual o histórico de conversas é partilhado com o participante.
• Utilize idempotency_token, opcional, para especificar o identificador exclusivo do pedido.

CreateChatThreadResult é o resultado devolvido da criação de um thread, pode utilizá-lo para obter o id tópico de chat que foi criado. Em id seguida, pode ser utilizado para obter um ChatThreadClient objeto com o get_chat_thread_client método . ChatThreadClient pode ser utilizado para executar outras operações de chat neste tópico 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)

Obter um tópico

O método de utilização get_properties obtém um ChatThreadProperties do serviço; thread_id é o ID exclusivo do thread.

chat_thread_properties = chat_thread_client.get_properties()

Listar tópicos de chat

Método de utilização list_chat_threads obtém a lista de threads de chat criados

• Utilize results_per_page, opcional, o número máximo de mensagens a devolver por página.
• Utilize start_time, opcional, a hora de início em que a consulta de intervalo.

Um iterador de [ChatThreadItem] é a resposta devolvida a partir da listagem de threads

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)

Atualizar um tópico de tópico

Utilize o update_topic método para atualizar as propriedades de um thread. topic é utilizado para descrever a alteração do tópico de tópico

• Utilize topic para dar um novo tópico ao thread;

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

chat_thread = chat_thread_client.get_properties(thread_id)

assert chat_thread.topic == topic

Eliminar um thread

Utilize delete_chat_thread o método para eliminar um thread; thread_id é o ID exclusivo do thread.

• Utilize thread_id, necessário, para especificar o ID exclusivo do thread.

chat_client.delete_chat_thread(thread_id=thread_id)

Operações de Mensagens

Enviar uma mensagem

Utilize o send_message método para enviar uma mensagem para um thread identificado por thread_id.

• Utilize content, necessário, para fornecer o conteúdo da mensagem de chat.
• Utilize chat_message_type, opcional, para fornecer o tipo de mensagem de chat. Os valores possíveis incluem: ChatMessageType.TEXT, ChatMessageType.HTML, 'text', 'html'; se não for especificado, ChatMessageType.TEXT serão definidos
• Utilize sender_display_name,opcional, para especificar o nome a apresentar do remetente, se não for especificado, o nome vazio será definido

SendChatMessageResult é a resposta devolvida ao enviar uma mensagem, que contém um ID, que é o ID exclusivo da mensagem.

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)

Obter uma mensagem

O método de utilização get_message obtém uma mensagem do serviço; message_id é o ID exclusivo da mensagem.

• Utilize message_id,obrigatório, para especificar o ID da mensagem de uma mensagem ChatMessage existente: a resposta devolvida ao receber uma mensagem contém um ID, que é o ID exclusivo da mensagem e outros 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)

Listar mensagens

Utilizar list_messages o método obtém mensagens do serviço.

• Utilize results_per_page, opcional, o número máximo de mensagens a devolver por página.
• Utilize start_time, opcional, a hora de início em que a consulta de intervalo.

Um iterador de [ChatMessage] é a resposta devolvida da listagem de mensagens

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)

Atualizar uma mensagem

Utilize update_message para atualizar uma mensagem identificada por threadId e messageId.

• Utilizar message_id,obrigatório é o ID exclusivo da mensagem.
• Utilizar content, opcional, é o conteúdo da mensagem a ser atualizado; se não for especificado, está atribuído para estar vazio

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 uma mensagem

Utilize delete_message para eliminar uma mensagem.

• Utilizar message_id, obrigatório, é o ID exclusivo da mensagem.

chat_thread_client.delete_message(message_id=send_message_result_id)

Operações de Participantes do Thread

Listar participantes do thread

Utilize list_participants para obter os participantes do thread.

• Utilize results_per_page, opcional, o número máximo de participantes a devolver por página.
• Utilize skip, opcional, para ignorar os participantes até uma posição especificada em resposta.

Um iterador de [ChatParticipant] é a resposta devolvida da listagem de participantes

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)

Adicionar participantes do thread

Utilize o add_participants método para adicionar participantes de threads ao thread.

• Utilize thread_participants, necessário, para listar o ChatParticipant a adicionar ao thread;
  • user, necessário, é o CommunicationUserIdentifier que criou por CommunicationIdentityClient.create_user() a partir de Tokens de Acesso de Utilizador
  • display_name, opcional, é o nome a apresentar para o participante do thread.
  • share_history_time, opcional, hora a partir da qual o histórico de conversas é partilhado com o participante.

É list(tuple(ChatParticipant, ChatError)) devolvido um. Quando o participante é adicionado com êxito, é esperada uma lista vazia. Em caso de erro encontrado ao adicionar o participante, a lista é preenchida com os participantes com falhas, juntamente com o erro encontrado.

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)

Remover participante do thread

Utilize o remove_participant método para remover o participante do thread identificado pelo threadId. identifier é o CommunicationUserIdentifier que criou por CommunicationIdentityClient.create_user() a partir de azure-communication-identity

e foi adicionado a este tópico de chat.

• Utilize identifier para especificar o CommunicationUserIdentifier que criou

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

Operações de Eventos

Enviar notificação de escrita

Utilize send_typing_notification o método para publicar um evento de notificação de escrita num thread, em nome de um utilizador.

chat_thread_client.send_typing_notification()

Enviar recibo de leitura

Utilize o send_read_receipt método para publicar um evento de recibo de leitura num thread, em nome de um utilizador.

• Utilize message_id para especificar o ID da mensagem cujo recibo de leitura deve ser enviado

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)

Listar recibos de leitura

Utilizar list_read_receipts o método obtém recibos de leitura para um thread.

• Utilize results_per_page, opcional, o número máximo de recibos de leitura a devolver por página.
• Utilize skip,opcional para ignorar recibos de leitura até uma posição especificada em resposta.

Um iterador de [ChatMessageReadReceipt] é a resposta devolvida da listagem de recibos de leitura

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 Exemplo

Estes são exemplos de código que mostram operações de cenário comuns com a biblioteca de cliente do Chat de Comunicação do Azure. As versões assíncronas dos exemplos (os ficheiros de exemplo python anexados com _async) mostram operações assíncronas. Antes de executar o código de exemplo, veja Pré-requisitos

para criar um recurso e, em seguida, definir algumas Variáveis de Ambiente

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

Resolução de problemas

Está a ter problemas? Esta secção deve conter detalhes sobre o que fazer lá.

Passos seguintes

Deve aceder mais código de exemplo aqui, juntamente com ligações para os testes de exemplo adequados.

Contribuir

Se encontrar erros ou tiver sugestões, submeta um problema na secção Problemas do projeto.