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

Esse pacote contém um SDK do Python para Serviços de Comunicação do Azure para Chat. Leia mais sobre Serviços de Comunicação do Azure aqui

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

Aviso de isenção de responsabilidade

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

Introdução

Pré-requisitos

• É necessário ter o Python 3.7 ou posterior para usar esse pacote.
• Um recurso dos Serviços de Comunicação implantado. Você pode usar 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 do usuário

Os tokens de acesso do usuário permitem que você crie aplicativos cliente que se autenticam diretamente nos Serviços de Comunicação do Azure. Você pode gerar esses tokens com o módulo azure.communication.identity e usá-los para inicializar os SDKs dos Serviços de Comunicação. Exemplo 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

O user criado acima será usado posteriormente, pois esse usuário deve ser adicionado como participante de um novo thread de chat ao criá-lo com esse token. Isso ocorre porque o iniciador da solicitação de criação deve estar na lista dos participantes do thread de chat.

Criar o cliente de chat

Isso permitirá que você crie, obtenha, liste ou exclua 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 thread de chat

O ChatThreadClient permitirá que você execute operações específicas a um thread de chat, como enviar mensagem, receber mensagem, atualizar o tópico do thread de chat, adicionar participantes ao thread de chat etc.

Você pode obtê-lo criando um novo thread de chat usando 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 a solicitação seja repetível; ou seja, se o cliente fizer a solicitação várias vezes com o mesmo Idempotency-Token e retornar uma resposta apropriada sem que o servidor execute a solicitação várias vezes. O valor do Idempotency-Token é uma cadeia de caracteres opaca que representa um identificador gerado pelo cliente, globalmente exclusivo para todos os tempos, para a solicitação.

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, se você tiver criado um thread de chat antes e tiver seu thread_id, poderá criá-lo por:

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

Principais conceitos

Uma conversa de chat é representada por um thread de chat. Cada usuário no thread é chamado de participante do thread. Os participantes do thread podem conversar entre si em particular em um chat 1:1 ou se amontoar em um chat em grupo 1:N. Os usuários também recebem atualizações quase em tempo real para quando outras pessoas estão digitando e quando leem as mensagens.

Depois de inicializar uma ChatClient classe, você poderá fazer as seguintes operações de chat:

Criar, obter, atualizar e excluir 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, você poderá fazer as seguintes operações de chat:

Atualizar thread

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

update_topic(topic, **kwargs)

Obter propriedades de thread de chat

get_properties(**kwargs)

Enviar, obter, atualizar e excluir 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) em participantes do thread

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

Enviar uma notificação de digitação

Notificar o serviço de notificação de digitação

send_typing_notification(**kwargs)

Enviar e obter recibo de leitura

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

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

Exemplos

As seções a seguir fornecem vários snippets de código que abrangem algumas das tarefas mais comuns, incluindo:

• Operações de thread
• Operações de mensagem
• Operações do participante do thread
• Operações de eventos

Operações de thread

Criar um thread

Use o método create_chat_thread para criar uma conversa de chat.

• Use topic, obrigatório, para fornecer um tópico de thread;
• Use thread_participants, opcional, para fornecer uma lista a ChatParticipant ser adicionada ao thread;
  • user, obrigatório, é o CommunicationUserIdentifier que você criou por CommunicationIdentityClient.create_user() de Tokens de Acesso do Usuário
  • display_name, opcional, é o nome de exibição do participante do thread.
  • share_history_time, opcional, é o horário no qual o histórico do chat é compartilhado com o participante.
• Use idempotency_token, opcional, para especificar o identificador exclusivo para a solicitação.

CreateChatThreadResult é o resultado retornado pela criação de um thread; você pode usá-lo para buscar o id do thread de chat que foi criado. Esse id pode ser usado para buscar um objeto ChatThreadClient usando o método get_chat_thread_client. ChatThreadClient pode ser usado para executar outras operações de chat para esse thread 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 thread

O método get_properties recupera um ChatThreadProperties do serviço; thread_id é a ID exclusiva do thread.

chat_thread_properties = chat_thread_client.get_properties()

Listar threads de chat

O método Use list_chat_threads recupera a lista de threads de chat criados

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

Um iterador de [ChatThreadItem] é a resposta retornada pela 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 thread

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

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

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

chat_thread = chat_thread_client.get_properties(thread_id)

assert chat_thread.topic == topic

Excluir um thread

Use delete_chat_thread o método para excluir um thread; thread_id é a ID exclusiva do thread.

• Use thread_id, que é obrigatório, para especificar a ID exclusiva do thread.

chat_client.delete_chat_thread(thread_id=thread_id)

Operações de mensagem

Enviar uma mensagem

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

• Use content, obrigatório, para fornecer o conteúdo da mensagem de chat.
• Use 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á definido
• Use sender_display_name,opcional, para especificar o nome de exibição do remetente, se não for especificado, o nome vazio será definido

SendChatMessageResult é a resposta retornada do envio de uma mensagem; ela contém uma ID, que é a ID exclusiva 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 Use get_message recupera uma mensagem do serviço; message_id é a ID exclusiva da mensagem.

• Use message_id,required, para especificar a ID de mensagem de uma mensagem ChatMessage existente é a resposta retornada da obtenção de uma mensagem, ela contém uma ID, que é a ID exclusiva 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

O método Use list_messages recupera mensagens do serviço.

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

Um iterador de [ChatMessage] é a resposta retornada pela 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

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

• Use message_id, que é obrigatório e é a ID exclusiva da mensagem.
• Use content, que é opcional e é o conteúdo da mensagem a ser atualizado; se não for especificado, será atribuído como 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

Excluir uma mensagem

Use delete_message para excluir uma mensagem.

• Use message_id, obrigatório, é a ID exclusiva da mensagem.

chat_thread_client.delete_message(message_id=send_message_result_id)

Operações do participante do thread

Listar participantes do thread

Use list_participants para recuperar os participantes do thread de chat.

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

Um iterador de [ChatParticipant] é a resposta retornada pela 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

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

• Use thread_participants, obrigatório, para listar o ChatParticipant a ser adicionado ao thread;
  • user, obrigatório, é o CommunicationUserIdentifier que você criou por CommunicationIdentityClient.create_user() de Tokens de Acesso do Usuário
  • display_name, opcional, é o nome de exibição do participante do thread.
  • share_history_time, opcional, é o horário no qual o histórico do chat é compartilhado com o participante.

Um list(tuple(ChatParticipant, ChatError)) é retornado. Quando o participante é adicionado com êxito, uma lista vazia é esperada. No caso de um erro encontrado ao adicionar o participante, a lista é populada com os participantes com falha, em conjunto com o erro que foi 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

Use o método remove_participant para remover o participante da conversa identificada por threadId. identifier é o CommunicationUserIdentifier que você criou por CommunicationIdentityClient.create_user() de azure-communication-identity

e foi adicionado a esse thread de chat.

• Use identifier para especificar o CommunicationUserIdentifier que você 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 uma notificação de digitação

Use send_typing_notification o método para postar um evento de notificação de digitação em um thread, em nome de um usuário.

chat_thread_client.send_typing_notification()

Enviar confirmação de leitura

Use send_read_receipt o método para postar um evento de confirmação de leitura em um thread, em nome de um usuário.

• Use message_id para especificar a 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 confirmações de leitura

O método Use list_read_receipts recupera recibos de leitura para um thread.

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

Um iterador de [ChatMessageReadReceipt] é a resposta retornada pela listagem dos 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)

Exemplo de código

Estes são exemplos de código que mostram operações de cenário comuns com a biblioteca de clientes do Chat de Comunicação do Azure. As versões assíncronas dos exemplos (os arquivos de exemplo do Python acrescentados com _async) mostram operações assíncronas. Antes de executar o código de exemplo, consulte 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

Solução de problemas

Está com problemas? Esta seção deve conter detalhes sobre o que fazer lá.

Próximas etapas

Mais código de exemplo deve ir aqui, juntamente com links para os testes de exemplo apropriados.

Participante

Se você encontrar bugs ou tiver sugestões, registre um problema na seção Problemas do projeto.