Klientbibliotek för Azure Communication Chat Package för Python – version 1.2.0

Det här paketet innehåller en Python SDK för Azure Communication Services för chatt. Läs mer om Azure Communication Services här

Källkod | Paket (Pypi) | Paket (Conda) | API-referensdokumentation | Produktdokumentation

Friskrivning

Stöd för Azure SDK Python-paket för Python 2.7 har upphört den 1 januari 2022. Mer information och frågor finns i https://github.com/Azure/azure-sdk-for-python/issues/20691

Komma igång

Förutsättningar

• Python 3.7 eller senare krävs för att använda det här paketet.
• En distribuerad Communication Services-resurs. Du kan använda Azure-portalen eller Azure PowerShell för att konfigurera den.

Installera paketet

Installera Azure Communication Service Chat SDK.

pip install --pre azure-communication-chat

Användaråtkomsttoken

Med användaråtkomsttoken kan du skapa klientprogram som autentiseras direkt till Azure Communication Services. Du kan generera dessa token med modulen azure.communication.identity och sedan använda dem för att initiera Communication Services-SDK:erna. Exempel på användning av 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

Ovanstående user skapas senare eftersom användaren ska läggas till som deltagare i en ny chatttråd när du skapar den med den här token. Det beror på att initieraren för create-begäran måste finnas i listan över deltagarna i chatttråden.

Skapa chattklienten

På så sätt kan du skapa, hämta, lista eller ta bort chatttrådar.

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

Skapa chatttrådsklient

Med ChatThreadClient kan du utföra åtgärder som är specifika för en chatttråd, till exempel skicka meddelande, hämta meddelande, uppdatera chatttrådsämnet, lägga till deltagare i chatttråd osv.

Du kan hämta den genom att skapa en ny chatttråd med Hjälp av 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)

Dessutom kan klienten också dirigera så att begäran kan upprepas. om klienten gör begäran flera gånger med samma Idempotency-Token och den får ett lämpligt svar igen utan att servern kör begäran flera gånger. Värdet för Idempotency-Token är en täckande sträng som representerar en klientgenererad, globalt unik för hela tiden, identifierare för begäran.

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)

Om du har skapat en chatttråd tidigare och har dess thread_id kan du också skapa den genom att:

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

Viktiga begrepp

En chattkonversation representeras av en chatttråd. Varje användare i tråden kallas för en tråddeltagare. Tråddeltagare kan chatta med varandra privat i en 1:1-chatt eller i en 1:N-gruppchatt. Användarna får också nästan realtidsuppdateringar för när andra skriver och när de har läst meddelandena.

När du har initierat en ChatClient klass kan du utföra följande chattåtgärder:

Skapa, hämta, uppdatera och ta bort trådar

Utföra CRD-åtgärder (Create-Read-Delete) på trådar

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

När du har initierat en ChatThreadClient klass kan du utföra följande chattåtgärder:

Uppdatera tråd

Utföra uppdateringsåtgärd i trådavsnittet

update_topic(topic, **kwargs)

Hämta egenskaper för chatttråd

get_properties(**kwargs)

Skicka, hämta, uppdatera och ta bort meddelanden

Utföra CRUD-åtgärder (Create-Read-Update-Delete) på meddelanden

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

Hämta, lägga till och ta bort deltagare

Utföra CRD-åtgärder (Create-Read-Delete) på tråddeltagare

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

Skicka inmatningsmeddelande

Meddela tjänsten om att skriva meddelanden

send_typing_notification(**kwargs)

Skicka och hämta läskvitto

Meddela tjänsten att ett meddelande läse och hämta en lista över lästa meddelanden.

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

Exempel

Följande avsnitt innehåller flera kodfragment som täcker några av de vanligaste uppgifterna, inklusive:

• Trådåtgärder
• Meddelandeåtgärder
• Åtgärder för tråddeltagare
• Händelseråtgärder

Trådåtgärder

Skapa en tråd

create_chat_thread Använd metoden för att skapa en chatttråd.

• Använd topic, obligatoriskt, för att ge ett trådämne;
• Använd thread_participants, valfritt, för att ange en lista över som ChatParticipant ska läggas till i tråden.
  • user, obligatoriskt är CommunicationUserIdentifier det du skapade av CommunicationIdentityClient.create_user() från användaråtkomsttoken
  • display_name, valfritt, är visningsnamnet för tråddeltagaren.
  • share_history_time, valfritt, tid från vilken chatthistoriken delas med deltagaren.
• Använd idempotency_token, valfritt, för att ange den unika identifieraren för begäran.

CreateChatThreadResult är resultatet som returneras från skapandet av en tråd, kan du använda den för att hämta chatttråden id som skapades. Detta id kan sedan användas för att hämta ett ChatThreadClient objekt med hjälp av get_chat_thread_client metoden . ChatThreadClient kan användas för att utföra andra chattåtgärder i den här chatttråden.

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

Hämta en tråd

Använd-metoden get_properties hämtar en ChatThreadProperties från tjänsten, thread_id är trådens unika ID.

chat_thread_properties = chat_thread_client.get_properties()

Lista chatttrådar

Använd-metoden list_chat_threads hämtar listan över skapade chatttrådar

• Använd results_per_page, valfritt, Det maximala antalet meddelanden som ska returneras per sida.
• Använd start_time, valfritt, Starttiden där intervallfrågan.

En iterator för [ChatThreadItem] är svaret som returneras från listningstrådar

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)

Uppdatera ett trådämne

Använd update_topic metoden för att uppdatera en tråds egenskaper. topic används för att beskriva ändringen av trådämnet

• Använd topic för att ge tråden ett nytt ämne;

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

chat_thread = chat_thread_client.get_properties(thread_id)

assert chat_thread.topic == topic

Ta bort en tråd

Använd delete_chat_thread metoden för att ta bort en tråd. thread_id Är trådens unika ID.

• Använd thread_id, obligatoriskt, för att ange trådens unika ID.

chat_client.delete_chat_thread(thread_id=thread_id)

Meddelandeåtgärder

Skicka ett meddelande

Använd send_message metoden för att skicka ett meddelande till en tråd som identifieras av thread_id.

• Använd content, obligatoriskt, för att ange innehållet i chattmeddelandet.
• Använd chat_message_type, valfritt, för att ange typ av chattmeddelande. Möjliga värden är: ChatMessageType.TEXT, ChatMessageType.HTML, 'text', 'html'; om det inte anges anges, ChatMessageType.TEXT kommer att anges
• Använd sender_display_name,valfritt för att ange avsändarens visningsnamn, om det inte anges anges, kommer det tomma namnet att anges

SendChatMessageResult är svaret som returneras från att skicka ett meddelande, det innehåller ett ID, vilket är det unika ID:t för meddelandet.

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)

Hämta ett meddelande

Använd-metoden get_message hämtar ett meddelande från tjänsten, message_id är det unika ID:t för meddelandet.

• Använd message_id,required för att ange meddelande-ID för ett befintligt meddelande ChatMessage är svaret som returneras från att få ett meddelande, det innehåller ett ID, vilket är det unika ID:t för meddelandet, och andra fält finns i 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)

Lista meddelanden

Använd-metoden list_messages hämtar meddelanden från tjänsten.

• Använd results_per_page, valfritt, Det maximala antalet meddelanden som ska returneras per sida.
• Använd start_time, valfritt, Starttiden där intervallfrågan.

En iterator för är svaret som returneras från listningsmeddelanden [ChatMessage]

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)

Uppdatera ett meddelande

Använd update_message för att uppdatera ett meddelande som identifieras av threadId och messageId.

• Använd message_id,required, är det unika ID:t för meddelandet.
• Använd content, valfritt, är meddelandeinnehållet som ska uppdateras. Om det inte anges tilldelas det att vara tomt

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

Ta bort ett meddelande

Använd delete_message för att ta bort ett meddelande.

• Använd message_id, krävs, är det unika ID:t för meddelandet.

chat_thread_client.delete_message(message_id=send_message_result_id)

Åtgärder för tråddeltagare

Lista tråddeltagare

Använd list_participants för att hämta deltagarna i tråden.

• Använd results_per_page, valfritt, Det maximala antalet deltagare som ska returneras per sida.
• Använd skip, valfritt, för att hoppa över deltagare upp till en angiven position som svar.

En iterator för [ChatParticipant] är svaret som returneras från listningsdeltagare

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)

Lägg till tråddeltagare

Använd add_participants metoden för att lägga till tråddeltagare i tråden.

• Använd thread_participants, obligatoriskt, för att visa en lista över som ChatParticipant ska läggas till i tråden.
  • user, obligatoriskt är CommunicationUserIdentifier det du skapade av CommunicationIdentityClient.create_user() från användaråtkomsttoken
  • display_name, valfritt, är visningsnamnet för tråddeltagaren.
  • share_history_time, valfritt, tid från vilken chatthistoriken delas med deltagaren.

A list(tuple(ChatParticipant, ChatError)) returneras. När deltagaren har lagts till förväntas en tom lista. Om ett fel uppstår när deltagaren läggs till fylls listan i med de misslyckade deltagarna tillsammans med det fel som påträffades.

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)

Ta bort tråddeltagare

Använd remove_participant metoden för att ta bort tråddeltagaren från tråden som identifieras av threadId. identifier är den CommunicationUserIdentifier du skapade av CommunicationIdentityClient.create_user() från azure-communication-identity

och lades till i den här chatttråden.

• Använd identifier för att ange den CommunicationUserIdentifier du skapade

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

Händelseråtgärder

Skicka inmatningsmeddelande

Använd send_typing_notification metoden för att publicera en typningsmeddelandehändelse i en tråd för en användares räkning.

chat_thread_client.send_typing_notification()

Skicka läskvitto

Använd send_read_receipt metoden för att publicera en läskvittohändelse i en tråd för en användares räkning.

• Använd message_id för att ange ID för meddelandet vars läskvitto ska skickas

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)

Visa en lista över läskvitton

Använd list_read_receipts metoden hämtar läskvitton för en tråd.

• Använd results_per_page, valfritt, Det maximala antalet läskvitton som ska returneras per sida.
• Använd skip,valfritt för att hoppa över läskvitton upp till en angiven position som svar.

En iterator för [ChatMessageReadReceipt] är svaret som returneras från listan över läskvitton

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)

Exempelkod

Det här är kodexempel som visar vanliga scenarioåtgärder med Azure Communication Chat-klientbiblioteket. Asynkrona versioner av exemplen (python-exempelfilerna som läggs till med _async) visar asynkrona åtgärder. Innan du kör exempelkoden läser du Krav

för att skapa en resurs och ange sedan några miljövariabler

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

Felsökning

Stöter du på problem? Det här avsnittet bör innehålla information om vad du ska göra där.

Nästa steg

Mer exempelkod bör gå hit, tillsammans med länkar till lämpliga exempeltester.

Bidra

Om du stöter på buggar eller har förslag kan du ange ett problem i avsnittet Problem i projektet.