Partager via

Bibliothèque cliente du package Azure Communication Chat pour Python - version 1.2.0

  • Article

Ce package contient un Kit de développement logiciel (SDK) Python pour Azure Communication Services pour Chat. En savoir plus sur Azure Communication Services ici

| Code sourcePackage (Pypi) | Package (Conda) | Documentation de référence sur les | APIDocumentation produit

Clause d’exclusion de responsabilité

La prise en charge des packages Python du SDK Azure pour Python 2.7 a pris fin le 1er janvier 2022. Pour obtenir plus d’informations et poser des questions, reportez-vous à https://github.com/Azure/azure-sdk-for-python/issues/20691

Prise en main

Prérequis

  • Python 3.7 ou version ultérieure est requis pour utiliser ce package.
  • Une ressource Communication Services déployée. Vous pouvez utiliser le portail Azure ou le Azure PowerShell pour le configurer.

Installer le package

Installez le Kit de développement logiciel (SDK) De conversation Azure Communication Service.

pip install --pre azure-communication-chat

Jetons d’accès utilisateur

Les jetons d’accès utilisateur vous permettent de créer des applications clientes qui s’authentifient directement auprès d’Azure Communication Services. Vous pouvez générer ces jetons avec le module azure.communication.identity, puis les utiliser pour initialiser les SDK Communication Services. Exemple d’utilisation d’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

Le user fichier créé ci-dessus sera utilisé ultérieurement, car cet utilisateur doit être ajouté en tant que participant au nouveau fil de conversation lorsque vous le créez avec ce jeton. Cela est dû au fait que l’initiateur de la demande de création doit figurer dans la liste des participants du thread de conversation.

Créer le client de conversation

Cela vous permet de créer, obtenir, répertorier ou supprimer des threads de conversation.

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

Créer un client de thread de conversation

ChatThreadClient vous permet d’effectuer des opérations spécifiques à un thread de conversation, telles que l’envoi d’un message, l’obtention d’un message, la mise à jour de la rubrique du fil de conversation, l’ajout de participants au fil de conversation, etc.

Vous pouvez l’obtenir en créant un thread de conversation à l’aide de 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)

En outre, le client peut également diriger afin que la demande soit reproductible ; autrement dit, si le client effectue la demande plusieurs fois avec le même Idempotency-Token et qu’il obtient une réponse appropriée sans que le serveur n’exécute la demande plusieurs fois. La valeur de l'Idempotency-Token est une chaîne opaque représentant un identificateur généré par le client, globalement unique pour tout le temps, pour la demande.

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)

Sinon, si vous avez déjà créé un thread de conversation et que vous avez son thread_id, vous pouvez le créer en :

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

Concepts clés

Une conversation de conversation est représentée par un thread de conversation. Chaque utilisateur du thread est appelé participant au thread. Les participants au thread peuvent discuter entre eux en privé dans une conversation 1 :1 ou se blottir dans une conversation de groupe 1 :N. Les utilisateurs bénéficient également de mises à jour quasiment en temps réel pour le moment où d’autres personnes tapent et lorsqu’ils ont lu les messages.

Une fois que vous avez initialisé une ChatClient classe, vous pouvez effectuer les opérations de conversation suivantes :

Créer, obtenir, mettre à jour et supprimer des threads

Effectuer des opérations CRD (Create-Read-Delete) sur des threads

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

Une fois que vous avez initialisé une ChatThreadClient classe, vous pouvez effectuer les opérations de conversation suivantes :

Thread de mise à jour

Effectuer une opération de mise à jour sur une rubrique de thread

update_topic(topic, **kwargs)

Obtenir les propriétés du thread de conversation

get_properties(**kwargs)

Envoyer, obtenir, mettre à jour et supprimer des messages

Effectuer des opérations CRUD (Create-Read-Update-Delete) sur les messages

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

Obtenir, ajouter et supprimer des participants

Effectuer des opérations CRD (Create-Read-Delete) sur les participants au thread

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

Envoyer une notification de saisie

Notifier le service de la notification de saisie

send_typing_notification(**kwargs)

Envoyer et obtenir un reçu de lecture

Informez le service qu’un message est lu et obtenez la liste des messages de lecture.

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

Exemples

Les sections suivantes fournissent plusieurs extraits de code couvrant certaines des tâches les plus courantes, notamment :

Opérations de thread

Créer un thread

Utilisez la méthode create_chat_thread pour créer un fil de conversation.

  • Utilisez topic, obligatoire, pour donner une rubrique de thread ;
  • Utilisez thread_participants, facultatif, pour fournir une liste à ChatParticipant ajouter au thread ;
    • user, obligatoire, il s’agit du CommunicationUserIdentifier que vous avez créé par CommunicationIdentityClient.create_user() à partir de jetons d’accès utilisateur
    • display_name, facultatif, est le nom d’affichage pour le participant au fil.
    • share_history_time, facultatif. Il s’agit du moment à partir duquel l’historique de conversation est partagé avec le participant.
  • Utilisez idempotency_token, facultatif, pour spécifier l’identificateur unique de la demande.

CreateChatThreadResult est le résultat retourné par la création d’un thread, vous pouvez l’utiliser pour extraire l’id du fil de conversation qui a été créé. Vous pouvez ensuite utiliser cette id pour extraire un objet ChatThreadClient à l’aide de la méthode get_chat_thread_client. ChatThreadClient peut être utilisé pour effectuer d’autres opérations de conversation sur ce thread de conversation.

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

Obtenir un thread

La méthode get_properties récupère un ChatThreadProperties à partir du service ; thread_id est l’ID unique du thread.

chat_thread_properties = chat_thread_client.get_properties()

Répertorier les fils de conversation

La méthode Use list_chat_threads récupère la liste des threads de conversation créés

  • Utilisez results_per_page, facultatif, Le nombre maximal de messages à retourner par page.
  • Utilisez start_time, facultatif, Heure de début où la requête de plage.

Un itérateur de [ChatThreadItem] est la réponse retournée par l’énumération des 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)

Mettre à jour une rubrique de thread

Utilisez la update_topic méthode pour mettre à jour les propriétés d’un thread. topic est utilisé pour décrire la modification de la rubrique de thread

  • Utilisez topic pour donner au thread une nouvelle rubrique ;
topic = "new topic"
chat_thread_client.update_topic(topic=topic)

chat_thread = chat_thread_client.get_properties(thread_id)

assert chat_thread.topic == topic

Supprimer un thread

Utilisez delete_chat_thread la méthode pour supprimer un thread ; thread_id est l’ID unique du thread.

  • Utilisez thread_id, requis, pour spécifier l’ID unique du thread.
chat_client.delete_chat_thread(thread_id=thread_id)

Opérations de message

Envoyer un message

Utilisez send_message la méthode pour envoyer un message à un thread identifié par thread_id.

  • Utilisez content, obligatoire, pour fournir le contenu du message de conversation.
  • Utilisez chat_message_type, facultatif, pour fournir le type de message de conversation. Les valeurs possibles incluent : ChatMessageType.TEXT, ChatMessageType.HTML, 'text', 'html'; si elles ne sont pas spécifiées, ChatMessageType.TEXT seront définies
  • Utilisez sender_display_name,facultatif, pour spécifier le nom d’affichage de l’expéditeur. S’il n’est pas spécifié, le nom vide sera défini

SendChatMessageResult est la réponse retournée à la suite de l’envoi du message; elle contient un ID, qui est l’ID unique du message.

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)

Obtenir un message

La méthode Use get_message récupère un message du service ; message_id est l’ID unique du message.

  • Utilisez message_id,obligatoire, pour spécifier l’ID de message d’un message ChatMessage existant est la réponse renvoyée par l’obtention d’un message, il contient un ID, qui est l’ID unique du message, et d’autres champs, reportez-vous à 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)

Lister les messages

La méthode Use list_messages récupère les messages du service.

  • Utilisez results_per_page, facultatif, Le nombre maximal de messages à retourner par page.
  • Utilisez start_time, facultatif, Heure de début où la requête de plage.

Un itérateur de [ChatMessage] est la réponse retournée par l’énumération des messages

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)

Mettre à jour un message

Utilisez update_message pour mettre à jour un message identifié par threadId et messageId.

  • message_id est l’ID unique du message.
  • content, facultatif, est le contenu du message à mettre à jour ; s’il n’est pas spécifié, il est considéré comme vide
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

Supprimer un message

Utilisez delete_message pour supprimer un message.

  • Utilisez message_id, obligatoire, est l’ID unique du message.
chat_thread_client.delete_message(message_id=send_message_result_id)

Opérations des participants au thread

Lister les participants au thread

Utilisez list_participants pour récupérer les participants à la conversation.

  • (Facultatif) Utilisez results_per_page, ce qui correspond au nombre maximal de participants à renvoyer par page.
  • (Facultatif) Utilisez skip pour ignorer les participants jusqu’à une position spécifiée dans la réponse.

Un itérateur de [ChatParticipant] est la réponse retournée par l’énumération des participants.

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)

Ajouter des participants au thread

Utilisez add_participants la méthode pour ajouter des participants au thread.

  • Utilisez thread_participants, obligatoire, pour répertorier le ChatParticipant à ajouter au thread ;
    • user, obligatoire, il s’agit du CommunicationUserIdentifier que vous avez créé par CommunicationIdentityClient.create_user() à partir de jetons d’accès utilisateur
    • display_name, facultatif, est le nom d’affichage pour le participant au fil.
    • share_history_time, facultatif. Il s’agit du moment à partir duquel l’historique de conversation est partagé avec le participant.

Un list(tuple(ChatParticipant, ChatError)) est retourné. Quand le participant est correctement ajouté, une liste vide est attendue. En cas d’erreur rencontrée lors de l’ajout d’un participant, la liste est remplie avec les participants n’ayant pas pu être ajoutés, ainsi que l’erreur rencontrée.

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)

Supprimer le participant au thread

Utilisez la méthode remove_participant pour supprimer des participants du fil de conversation identifié par threadId. identifier est le CommunicationUserIdentifier que vous avez créé par CommunicationIdentityClient.create_user() à partir de azure-communication-identity

et a été ajouté à ce fil de conversation.

  • Utilisez identifier pour spécifier le que CommunicationUserIdentifier vous avez créé
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))

Opérations d’événements

Envoyer une notification de saisie

Utilisez send_typing_notification la méthode pour publier un événement de notification de saisie dans un thread, au nom d’un utilisateur.

chat_thread_client.send_typing_notification()

Envoyer une confirmation de lecture

Utilisez send_read_receipt la méthode pour publier un événement de confirmation de lecture sur un thread, au nom d’un utilisateur.

  • Permet message_id de spécifier l’ID du message dont la réception de lecture doit être envoyée
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)

Répertorier les confirmations de lecture

La méthode Use list_read_receipts récupère les reçus de lecture pour un thread.

  • Utilisez results_per_page, facultatif, Le nombre maximal de reçus de lecture à retourner par page.
  • Utilisez skip,facultatif, pour ignorer les reçus de lecture jusqu’à une position spécifiée en réponse.

Un itérateur de [ChatMessageReadReceipt] est la réponse retournée par l’énumération des accusés de lecture

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)

Exemple de code

Il s’agit d’exemples de code qui montrent les opérations de scénario courantes avec la bibliothèque cliente Azure Communication Chat. Les versions asynchrones des exemples (les exemples de fichiers Python ajoutés avec _async) affichent des opérations asynchrones. Avant d’exécuter l’exemple de code, reportez-vous à Prérequis

pour créer une ressource, puis définir des variables d’environnement

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

Dépannage

Vous rencontrez des problèmes ? Cette section doit contenir des détails sur la procédure à suivre.

Étapes suivantes

D’autres exemples de code doivent être fournis ici, ainsi que des liens vers les exemples de tests appropriés.

Contribution

Si vous rencontrez des bogues ou si vous avez des suggestions, signalez un problème dans la section Problèmes du projet.

Impressions