Azure Communication Chat Package-clientbibliotheek voor Python - versie 1.2.0

Dit pakket bevat een Python-SDK voor Azure Communication Services voor Chat. Lees hier meer over Azure Communication Services

Broncode | Pakket (Pypi) | Pakket (Conda) | API-referentiedocumentatie | Productdocumentatie

Disclaimer

Ondersteuning voor Azure SDK Python-pakketten voor Python 2.7 is beëindigd op 1 januari 2022. Voor meer informatie en vragen raadpleegt u https://github.com/Azure/azure-sdk-for-python/issues/20691

Aan de slag

Vereisten

• Python 3.7 of hoger is vereist voor het gebruik van dit pakket.
• Een geïmplementeerde Communication Services-resource. U kunt azure portal of de Azure PowerShell gebruiken om het in te stellen.

Het pakket installeren

Installeer de Azure Communication Service Chat SDK.

pip install --pre azure-communication-chat

Tokens voor gebruikerstoegang

Met toegangstokens voor gebruikers kunt u clienttoepassingen maken die zich rechtstreeks verifiëren bij Azure Communication Services. U kunt deze tokens genereren met de module azure.communication.identity en deze vervolgens gebruiken om de Communication Services SDK's te initialiseren. Voorbeeld van het gebruik van 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

De user hierboven gemaakte wordt later gebruikt, omdat die gebruiker moet worden toegevoegd als deelnemer aan een nieuwe chat-thread wanneer u deze met dit token maakt. De oorzaak hiervan is dat de initiator van de aanvraag voor het maken in de lijst met deelnemers van de chat-thread moet staan.

De chatclient maken

Hiermee kunt u chatthreads maken, ophalen, weergeven of verwijderen.

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 maken

Met De ChatThreadClient kunt u bewerkingen uitvoeren die specifiek zijn voor een chatgesprek, zoals bericht verzenden, bericht ophalen, het onderwerp van de chat-thread bijwerken, deelnemers toevoegen aan chatgesprek, enzovoort.

U kunt deze verkrijgen door een nieuwe chat-thread te maken met behulp van 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)

Daarnaast kan de client ook doorsturen zodat de aanvraag herhaalbaar is; dat wil gezegd, als de client de aanvraag meerdere keren met dezelfde Idempotency-Token en deze een geschikt antwoord krijgt zonder dat de server de aanvraag meerdere keren uitvoert. De waarde van de Idempotency-Token is een ondoorzichtige tekenreeks die een door de client gegenereerde, wereldwijd unieke id voor altijd vertegenwoordigt voor de aanvraag.

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)

Als u eerder een chat-thread hebt gemaakt en u de bijbehorende thread_id hebt, kunt u deze ook maken door:

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

Belangrijkste concepten

Een chatgesprek wordt vertegenwoordigd door een chatgesprek. Elke gebruiker in de thread wordt een threaddeelnemer genoemd. Threaddeelnemers kunnen privé met elkaar chatten in een 1:1-chat of in een 1:N-groepschat. Gebruikers krijgen ook bijna realtime updates voor wanneer anderen typen en wanneer ze de berichten hebben gelezen.

Nadat u een ChatClient klasse hebt geïnitialiseerd, kunt u de volgende chatbewerkingen uitvoeren:

Threads maken, ophalen, bijwerken en verwijderen

CRD-bewerkingen (Create-Read-Delete) uitvoeren op threads

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

Nadat u een ChatThreadClient klasse hebt geïnitialiseerd, kunt u de volgende chatbewerkingen uitvoeren:

Thread bijwerken

Updatebewerking uitvoeren op threadonderwerp

update_topic(topic, **kwargs)

Eigenschappen van chatthread ophalen

get_properties(**kwargs)

Berichten verzenden, ophalen, bijwerken en verwijderen

CRUD-bewerkingen (Create-Read-Update-Delete) uitvoeren op berichten

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

Deelnemers ophalen, toevoegen en verwijderen

CRD-bewerkingen (Create-Read-Delete) uitvoeren op threaddeelnemers

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

Melding over typen verzenden

De service op de hoogte stellen van het typen van een melding

send_typing_notification(**kwargs)

Leesbevestiging verzenden en ophalen

Informeer de service dat een bericht is gelezen en haal een lijst met gelezen berichten op.

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

Voorbeelden

De volgende secties bevatten verschillende codefragmenten voor enkele van de meest voorkomende taken, waaronder:

• Threadbewerkingen
• Berichtbewerkingen
• Bewerkingen van threaddeelnemers
• Gebeurtenisbewerkingen

Threadbewerkingen

Een thread maken

Gebruik de methode create_chat_thread om een chat-thread te maken.

• Gebruik topic, vereist, om een threadonderwerp te geven;
• Gebruik thread_participants, optioneel, om een lijst op te geven die ChatParticipant aan de thread moet worden toegevoegd;
  • user, vereist, is het de CommunicationUserIdentifier die u hebt gemaakt door CommunicationIdentityClient.create_user() op basis van gebruikerstoegangstokens
  • display_name, optioneel, is de weergavenaam voor de threaddeelnemer.
  • share_history_timeoptioneel, het tijdstip waarop de chatgeschiedenis wordt gedeeld met de deelnemer.
• Gebruik idempotency_tokenoptioneel om de unieke id voor de aanvraag op te geven.

CreateChatThreadResult is het resultaat dat wordt geretourneerd door het maken van een thread, kunt u deze gebruiken om de id op te halen van de chat-thread die is gemaakt. Dit id kan vervolgens worden gebruikt om een ChatThreadClient -object op te halen met behulp van de get_chat_thread_client -methode. ChatThreadClient kan worden gebruikt om andere chatbewerkingen uit te voeren voor deze chat-thread.

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

Een thread ophalen

Methode Use get_properties haalt een ChatThreadProperties op uit de service; thread_id is de unieke id van de thread.

chat_thread_properties = chat_thread_client.get_properties()

Chat-threads weergeven

Methode Use list_chat_threads haalt de lijst met gemaakte chat-threads op

• Gebruik results_per_pageoptioneel het maximum aantal berichten dat per pagina moet worden geretourneerd.
• Gebruik start_time, optioneel, De begintijd waarin de bereikquery wordt uitgevoerd.

Een iterator van [ChatThreadItem] is het antwoord dat wordt geretourneerd door het weergeven van 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)

Een threadonderwerp bijwerken

Gebruik update_topic de methode om de eigenschappen van een thread bij te werken. topic wordt gebruikt om de wijziging van het threadonderwerp te beschrijven

• Gebruik topic om thread een nieuw onderwerp te geven;

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

chat_thread = chat_thread_client.get_properties(thread_id)

assert chat_thread.topic == topic

Een thread verwijderen

Methode gebruiken delete_chat_thread om een thread te verwijderen; thread_id is de unieke id van de thread.

• Gebruik thread_id, vereist, om de unieke id van de thread op te geven.

chat_client.delete_chat_thread(thread_id=thread_id)

Berichtbewerkingen

Een bericht verzenden

Gebruik send_message de methode om een bericht te verzenden naar een thread die wordt geïdentificeerd door thread_id.

• Gebruik content, vereist, om de inhoud van het chatbericht op te geven.
• Gebruik chat_message_typeoptioneel om het type chatbericht op te geven. Mogelijke waarden zijn: ChatMessageType.TEXT, ChatMessageType.HTML, 'text', ; 'html'indien niet opgegeven, ChatMessageType.TEXT worden ingesteld
• Gebruik sender_display_nameoptioneel om de weergavenaam van de afzender op te geven. Als dit niet is opgegeven, wordt een lege naam ingesteld

SendChatMessageResult is het antwoord dat wordt geretourneerd door het verzenden van een bericht. Het bevat een id, die de unieke id van het bericht is.

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)

Een bericht ophalen

Methode Use get_message haalt een bericht op van de service; message_id is de unieke id van het bericht.

• Gebruik message_id, vereist, om de bericht-id van een bestaand bericht ChatMessage op te geven is het antwoord dat wordt geretourneerd na het ontvangen van een bericht, het bevat een id, wat de unieke id van het bericht is, en andere velden raadpleegt u 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)

Berichten weergeven

Methode Use list_messages haalt berichten op van de service.

• Gebruik results_per_pageoptioneel het maximum aantal berichten dat per pagina moet worden geretourneerd.
• Gebruik start_time, optioneel, De begintijd waarin de bereikquery wordt uitgevoerd.

Een iterator van [ChatMessage] is het antwoord dat wordt geretourneerd door het weergeven van berichten

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)

Een bericht bijwerken

Gebruik update_message om een bericht bij te werken dat wordt geïdentificeerd door threadId en messageId.

• Gebruik message_id,required, is de unieke id van het bericht.
• Gebruik content, optioneel, is de berichtinhoud die moet worden bijgewerkt. Als dit niet is opgegeven, wordt deze toegewezen als leeg

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

Een bericht verwijderen

Gebruik delete_message om een bericht te verwijderen.

• Gebruik message_id, vereist, is de unieke id van het bericht.

chat_thread_client.delete_message(message_id=send_message_result_id)

Bewerkingen van threaddeelnemers

Threaddeelnemers weergeven

Gebruik list_participants om de deelnemers van de thread op te halen.

• Gebruik results_per_page, optioneel, Het maximum aantal deelnemers dat per pagina moet worden geretourneerd.
• Gebruik skip, optioneel, om deelnemers over te slaan tot een opgegeven positie in antwoord.

Een iterator van [ChatParticipant] is het antwoord dat wordt geretourneerd door de lijst met deelnemers

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)

Threaddeelnemers toevoegen

Gebruik add_participants de methode om threaddeelnemers toe te voegen aan de thread.

• Gebruik thread_participants, vereist, om een ChatParticipant lijst weer te geven die aan de thread moet worden toegevoegd;
  • user, vereist, is het de CommunicationUserIdentifier die u hebt gemaakt door CommunicationIdentityClient.create_user() op basis van gebruikerstoegangstokens
  • display_name, optioneel, is de weergavenaam voor de threaddeelnemer.
  • share_history_time, optioneel, het tijdstip waarop de chatgeschiedenis wordt gedeeld met de deelnemer.

A list(tuple(ChatParticipant, ChatError)) wordt geretourneerd. Wanneer de deelnemer is toegevoegd, wordt een lege lijst verwacht. In het geval van een fout die is opgetreden tijdens het toevoegen van een deelnemer, wordt de lijst gevuld met de mislukte deelnemers, samen met de fout die is opgetreden.

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)

Threaddeelnemer verwijderen

Gebruik remove_participant de methode om threaddeelnemer te verwijderen uit de thread die wordt geïdentificeerd door threadId. identifier is de CommunicationUserIdentifier die u hebt gemaakt door CommunicationIdentityClient.create_user() van azure-communication-identity

en is toegevoegd aan deze chat-thread.

• Gebruik identifier om de CommunicationUserIdentifier op te geven die u hebt gemaakt

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

Gebeurtenisbewerkingen

Melding over typen verzenden

Gebruik send_typing_notification de methode om namens een gebruiker een meldingsevenement voor typen te posten in een thread.

chat_thread_client.send_typing_notification()

Leesbevestiging verzenden

Gebruik send_read_receipt de methode om namens een gebruiker een leesbevestiging te posten in een thread.

• Gebruik message_id om de id op te geven van het bericht waarvan de leesbevestiging moet worden verzonden

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)

Leesbevestigingen weergeven

Methode Use list_read_receipts haalt leesbevestigingen op voor een thread.

• Gebruik results_per_page, optioneel, Het maximum aantal leesbevestigingen dat per pagina moet worden geretourneerd.
• Gebruik skip,optioneel, om leesbevestigingen over te slaan tot een opgegeven positie in antwoord.

Een iterator van [ChatMessageReadReceipt] is het antwoord dat wordt geretourneerd door het weergeven van leesbevestigingen

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)

Voorbeeldcode

Dit zijn codevoorbeelden die algemene scenariobewerkingen laten zien met de Azure Communication Chat-clientbibliotheek. De asynchrone versies van de voorbeelden (de Python-voorbeeldbestanden toegevoegd met _async) tonen asynchrone bewerkingen. Raadpleeg Vereisten voordat u de voorbeeldcode uitvoert

om een resource te maken en vervolgens enkele omgevingsvariabelen in te stellen

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

Problemen oplossen

Ondervindt u problemen? Deze sectie moet details bevatten over wat u daar moet doen.

Volgende stappen

Hier moet meer voorbeeldcode worden weergegeven, samen met koppelingen naar de juiste voorbeeldtests.

Bijdragen

Als u fouten tegenkomt of suggesties hebt, kunt u een probleem melden in de sectie Problemen van het project.