Azure Communication Chat Package ügyfélkódtár Pythonhoz – 1.2.0-s verzió

Ez a csomag egy Python SDK-t tartalmaz a csevegéshez Azure Communication Services. További információ a Azure Communication Services itt

Forráskód | Csomag (Pypi) | Csomag (Conda) | API-referenciadokumentáció | Termékdokumentáció

Felelősséget kizáró nyilatkozat

Az Azure SDK Python-csomagok támogatása a Python 2.7-hez 2022. január 01-én véget ért. További információkért és kérdésekért lásd: https://github.com/Azure/azure-sdk-for-python/issues/20691

Első lépések

Előfeltételek

• A csomag használatához Python 3.7 vagy újabb verzió szükséges.
• Üzembe helyezett Communication Services-erőforrás. A beállításához használhatja az Azure Portalt vagy a Azure PowerShell.

A csomag telepítése

Telepítse az Azure Communication Service Chat SDK-t.

pip install --pre azure-communication-chat

Felhasználói hozzáférési jogkivonatok

A felhasználói hozzáférési jogkivonatokkal olyan ügyfélalkalmazásokat hozhat létre, amelyek közvetlenül hitelesítik magukat Azure Communication Services. Ezeket a jogkivonatokat az azure.communication.identity modullal hozhatja létre, majd használhatja őket a Communication Services SDK-k inicializálására. Példa az azure.communication.identity használatára:

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

A user fent létrehozott üzenet később lesz használatban, mivel a felhasználót új csevegési szál résztvevőjeként kell hozzáadni, amikor ezzel a jogkivonattal hozza létre. Ennek az az oka, hogy a létrehozási kérelem kezdeményezőjének szerepelnie kell a csevegési szál résztvevőinek listájában.

A csevegőügyfél létrehozása

Ez lehetővé teszi csevegési szálak létrehozását, lekérését, listázását vagy törlését.

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

Csevegőszál-ügyfél létrehozása

A ChatThreadClient lehetővé teszi a csevegési szálhoz kapcsolódó műveletek végrehajtását, például üzenetküldést, üzenet lekérését, a csevegési téma frissítését, résztvevők hozzáadását a csevegési szálhoz stb.

Ehhez hozzon létre egy új csevegési szálat a ChatClient használatával:

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)

Emellett az ügyfél közvetlenül is irányíthatja a kérést, hogy megismételhető legyen; vagyis ha az ügyfél többször is ugyanazzal a Idempotency-Token küldi el a kérést, és megfelelő választ kap, anélkül, hogy a kiszolgáló többször is végrehajtja a kérést. A Idempotency-Token értéke egy átlátszatlan sztring, amely egy ügyfél által generált, globálisan minden alkalommal egyedi, a kérés azonosítóját jelöli.

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)

Másik lehetőségként, ha korábban létrehozott egy csevegési szálat, és rendelkezik annak thread_id, a következő módon hozhatja létre:

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

Fő fogalmak

A csevegéseket egy csevegési szál képviseli. A szál minden felhasználóját szál résztvevőnek nevezzük. A beszélgetés résztvevői privát módon cseveghetnek egy 1:1-ás csevegésben, vagy egy 1:N csoportos csevegésben. A felhasználók közel valós idejű frissítéseket kapnak arról is, hogy mások mikor gépelnek, és mikor olvasták el az üzeneteket.

Miután inicializált egy osztályt ChatClient , a következő csevegési műveleteket végezheti el:

Szálak létrehozása, lekérése, frissítése és törlése

CRD-műveletek (létrehozás-olvasás-törlés) végrehajtása szálakon

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

Miután inicializált egy osztályt ChatThreadClient , a következő csevegési műveleteket végezheti el:

Hozzászóláslánc frissítése

Frissítési művelet végrehajtása száltémakörön

update_topic(topic, **kwargs)

Csevegési szál tulajdonságainak lekérése

get_properties(**kwargs)

Üzenetek küldése, lekérése, frissítése és törlése

CRUD(Create-Read-Update-Delete) műveletek végrehajtása üzeneteken

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

Résztvevők beolvasása, hozzáadása és eltávolítása

CRD-műveletek végrehajtása (létrehozás-olvasás-törlés) a szál résztvevőin

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

Gépelési értesítés küldése

Értesítés a szolgáltatásnak a gépelésről

send_typing_notification(**kwargs)

Olvasási visszaigazolás küldése és lekérése

Értesítse a szolgáltatást az üzenetek olvasásáról, és kérje le az olvasott üzenetek listáját.

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

Példák

A következő szakaszok számos kódrészletet biztosítanak, amelyek a leggyakoribb feladatokat fedik le, többek között az alábbiakat:

• Szálműveletek
• Üzenetműveletek
• Szál résztvevőinek műveletei
• Eseményműveletek

Szálműveletek

Szál létrehozása

A metódus használatával create_chat_thread hozzon létre egy csevegési szálat.

• Tématémakör megadásához használja topica kötelezőt;
• A (nem kötelező) paranccsal thread_participantslistázhatja a ChatParticipant szálhoz hozzáadni kívánt listát;
  • user, kötelező, a CommunicationUserIdentifier felhasználói hozzáférési jogkivonatokból létrehozott CommunicationIdentityClient.create_user()
  • display_name, nem kötelező, a szál résztvevőjének megjelenített neve.
  • share_history_time, nem kötelező, a csevegési előzményeknek a résztvevővel való megosztásának időpontja.
• A kérés egyedi azonosítójának megadásához használja idempotency_tokena (nem kötelező) parancsot.

CreateChatThreadResult a szál létrehozásakor visszaadott eredmény, a használatával lekérheti a id létrehozott csevegési szálat. Ezzel id a metódussal lekérhet egy ChatThreadClient objektumot get_chat_thread_client . ChatThreadClient más csevegési műveletek végrehajtására is használható ehhez a csevegési szálhoz.

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

Szál lekérése

A use get_properties metódus lekéri az a-t ChatThreadProperties a szolgáltatásból; thread_id ez a szál egyedi azonosítója.

chat_thread_properties = chat_thread_client.get_properties()

Csevegési szálak listázása

A Use list_chat_threads metódus lekéri a létrehozott csevegési szálak listáját

• Használja results_per_pagea következőt: , nem kötelező, Az egy oldalonként visszaadandó üzenetek maximális száma.
• Használja start_timea következőt: , nem kötelező, A tartomány lekérdezésének kezdő időpontja.

A iterátora [ChatThreadItem] a listázási szálakból visszaadott válasz

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)

Tématémakör frissítése

A szál tulajdonságainak frissítéséhez használja update_topic a metódust. topic A tématémakör változásának leírására szolgál

• A használatával topic új témakört adhat a szálnak;

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

chat_thread = chat_thread_client.get_properties(thread_id)

assert chat_thread.topic == topic

Szál törlése

Szál törlésére használható delete_chat_thread módszer; thread_id a szál egyedi azonosítója.

• A szál egyedi azonosítójának megadásához használja thread_ida kötelezőt.

chat_client.delete_chat_thread(thread_id=thread_id)

Üzenetműveletek

Üzenet küldése

A metódussal send_message üzenetet küldhet a által thread_idazonosított szálnak.

• A csevegőüzenet tartalmának megadásához használja contenta kötelezőt.
• A csevegőüzenet típusának megadásához használja chat_message_typea (nem kötelező) lehetőséget. A lehetséges értékek a következők: ChatMessageType.TEXT, ChatMessageType.HTML, 'text'; 'html'ha nincs megadva, ChatMessageType.TEXT be lesz állítva
• A (nem kötelező) használatával sender_display_nameadja meg a feladó megjelenítendő nevét, ha nincs megadva, üres név lesz beállítva

SendChatMessageResult az üzenet küldésekor visszaadott válasz, amely tartalmaz egy azonosítót, amely az üzenet egyedi azonosítója.

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)

Üzenet lekérése

A Use get_message metódus lekéri az üzenetet a szolgáltatásból; message_id ez az üzenet egyedi azonosítója.

• A (kötelező) használatával message_idmegadhatja egy meglévő üzenet ChatMessage üzenetazonosítóját az üzenet lekérésekor visszaadott válasz, tartalmaz egy azonosítót, amely az üzenet egyedi azonosítója, és egyéb mezőket az azure.communication.chat.ChatMessage webhelyen talál.

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)

Üzenetek listázása

A Use list_messages metódus lekéri az üzeneteket a szolgáltatásból.

• Használja results_per_pagea következőt: , nem kötelező, Az egy oldalonként visszaadandó üzenetek maximális száma.
• Használja start_timea következőt: , nem kötelező, A tartomány lekérdezésének kezdő időpontja.

A iterátora [ChatMessage] az üzenetek listázása által visszaadott válasz

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)

Üzenet frissítése

A használatával update_message frissítheti a threadId és a messageId által azonosított üzeneteket.

• A (kötelező) használata message_idaz üzenet egyedi azonosítója.
• A (nem kötelező) használatával contentfrissítendő az üzenet tartalma; ha nincs megadva, üresnek van rendelve

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

Üzenet törlése

Üzenet törléséhez használja a parancsot delete_message .

• A (kötelező) használata message_idaz üzenet egyedi azonosítója.

chat_thread_client.delete_message(message_id=send_message_result_id)

Szál résztvevőinek műveletei

Téma résztvevőinek listázása

A használatával list_participants lekérheti a szál résztvevőit.

• Használja results_per_pagea következőt: , nem kötelező, Az oldalanként visszaadható résztvevők maximális száma.
• A (nem kötelező) használatával skipa résztvevőket egy adott pozícióba ugorhatja válaszként.

A iterátora [ChatParticipant] a lista résztvevőitől kapott válasz

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)

Hozzászóláslánc résztvevőinek hozzáadása

A szál résztvevőinek hozzáadása a szálhoz metódus használatával add_participants .

• A (kötelező) paranccsal thread_participantslistázhatja a ChatParticipant szálhoz hozzáadni kívánt elemet;
  • user, kötelező, a CommunicationUserIdentifier felhasználói hozzáférési jogkivonatokból létrehozott CommunicationIdentityClient.create_user()
  • display_name, nem kötelező, a szál résztvevőjének megjelenített neve.
  • share_history_time, nem kötelező, a csevegési előzményeknek a résztvevővel való megosztásának időpontja.

A visszaadott érték list(tuple(ChatParticipant, ChatError)) . A résztvevő sikeres hozzáadása után üres lista várható. Ha hiba történt a résztvevő hozzáadása során, a rendszer feltölti a listát a sikertelen résztvevőkkel és a tapasztalt hibával.

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)

Szál résztvevőjének eltávolítása

Ezzel remove_participant a módszerrel távolíthatja el a szál résztvevőit a threadId által azonosított szálból. identifier a CommunicationUserIdentifier CommunicationIdentityClient.create_user() által létrehozott azure-communication-identity

és hozzá lett adva ehhez a csevegési szálhoz.

• A létrehozott identifier beállítás CommunicationUserIdentifier megadása

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

Eseményműveletek

Gépelési értesítés küldése

A metódussal send_typing_notification gépelési értesítési eseményt tehet közzé egy szálon egy felhasználó nevében.

chat_thread_client.send_typing_notification()

Olvasási visszaigazolás küldése

Olvasási visszaigazolási eseményt egy felhasználó nevében a metódussal send_read_receipt tehet közzé egy hozzászólásláncban.

• Annak message_id az üzenetnek az azonosítóját adja meg, amelynek az olvasási visszaigazolását el szeretné küldeni

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)

Olvasási visszaigazolások listázása

A use list_read_receipts metódus lekéri egy szál olvasási nyugtáit.

• Használja results_per_pagea következőt: , nem kötelező, Az oldalanként visszaadandó olvasási visszaigazolások maximális száma.
• A (nem kötelező) használatával skipaz olvasási visszaigazolásokat egy adott válaszpozícióba ugorhatja.

A iterátora az olvasási [ChatMessageReadReceipt] visszaigazolások listázásából visszaadott válasz

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)

Példakód

Ezek olyan kódminták, amelyek az Azure Communication Chat ügyfélkódtárával kapcsolatos gyakori forgatókönyvműveleteket mutatják be. A minták aszinkron verziói (a python-mintafájlok, hozzáfűzve _async) aszinkron műveleteket mutatnak. A mintakód futtatása előtt tekintse meg az előfeltételeket

erőforrás létrehozásához, majd állítson be néhány környezeti változót

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

Hibaelhárítás

Problémákba ütközik? Ennek a szakasznak tartalmaznia kell a teendők részleteit.

Következő lépések

Itt további mintakódot, valamint a megfelelő példatesztekre mutató hivatkozásokat kell használni.

Közreműködés

Ha bármilyen hibába ütközik, vagy javaslatai vannak, jelentse be a problémát a projekt Problémák szakaszában.