Pustaka klien Paket Obrolan Azure Communication untuk Python - versi 1.2.0

Paket ini berisi Python SDK untuk Azure Communication Services untuk Obrolan. Baca selengkapnya tentang Azure Communication Services di sini

Kode sumber | Paket (Pypi) | Paket (Conda) | Dokumentasi | referensi APIDokumentasi produk

Pengelakan

Dukungan paket Azure SDK Python untuk Python 2.7 telah berakhir 01 Januari 2022. Untuk informasi dan pertanyaan lebih lanjut, silakan merujuk ke https://github.com/Azure/azure-sdk-for-python/issues/20691

Memulai

Prasyarat

• Python 3.7 atau yang lebih baru diharuskan untuk menggunakan paket ini.
• Sumber daya Communication Services yang disebarkan. Anda dapat menggunakan Portal Microsoft Azure atau Azure PowerShell untuk menyiapkannya.

Instal paketnya

Instal Azure Communication Service Chat SDK.

pip install --pre azure-communication-chat

Token Akses Pengguna

Token akses pengguna memungkinkan Anda membuat aplikasi klien yang langsung mengautentikasi ke Azure Communication Services. Anda dapat membuat token ini dengan modul azure.communication.identity, lalu menggunakannya untuk menginisialisasi SDK Communication Services. Contoh penggunaan 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

Yang user dibuat di atas akan digunakan nanti, karena pengguna tersebut harus ditambahkan sebagai peserta utas obrolan baru saat Anda membuatnya dengan token ini. Ini karena inisiator permintaan buat harus ada dalam daftar peserta utas obrolan.

Membuat Klien Obrolan

Ini akan memungkinkan Anda untuk membuat, mendapatkan, mencantumkan, atau menghapus utas obrolan.

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

Buat Klien Utas Obrolan

ChatThreadClient akan memungkinkan Anda melakukan operasi khusus untuk utas obrolan, seperti mengirim pesan, mendapatkan pesan, memperbarui topik utas obrolan, menambahkan peserta ke utas obrolan, dll.

Anda bisa mendapatkannya dengan membuat utas obrolan baru menggunakan 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)

Selain itu, klien juga dapat mengarahkan sehingga permintaan dapat diulang; artinya, jika klien membuat permintaan beberapa kali dengan Idempotency-Token yang sama dan akan mendapatkan kembali respons yang sesuai tanpa server menjalankan permintaan beberapa kali. Nilai Idempotency-Token adalah string buram yang mewakili yang dihasilkan klien, unik secara global untuk semua waktu, pengidentifikasi untuk permintaan tersebut.

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)

Atau, jika Anda telah membuat utas obrolan sebelumnya dan Anda memiliki thread_id, Anda dapat membuatnya dengan:

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

Konsep utama

Percakapan obrolan diwakili oleh utas obrolan. Setiap pengguna dalam utas disebut peserta utas. Peserta utas dapat mengobrol satu sama lain secara pribadi dalam obrolan 1:1 atau berkumpul di obrolan grup 1:N. Pengguna juga mendapatkan pembaruan mendekati real-time saat orang lain mengetik dan ketika mereka telah membaca pesan.

Setelah menginisialisasi ChatClient kelas, Anda dapat melakukan operasi obrolan berikut:

Membuat, mendapatkan, memperbarui, dan menghapus utas

Melakukan operasi CRD(Create-Read-Delete) pada utas

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

Setelah menginisialisasi ChatThreadClient kelas, Anda dapat melakukan operasi obrolan berikut:

Perbarui utas

Melakukan operasi Pembaruan pada topik utas

update_topic(topic, **kwargs)

Mendapatkan properti utas Obrolan

get_properties(**kwargs)

Mengirim, mendapatkan, memperbarui, dan menghapus pesan

Melakukan operasi CRUD(Create-Read-Update-Delete) pada pesan

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

Mendapatkan, menambahkan, dan menghapus peserta

Melakukan operasi CRD(Create-Read-Delete) pada peserta utas

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

Kirim pemberitahuan pengetikan

Memberi tahu layanan pemberitahuan pengetikan

send_typing_notification(**kwargs)

Mengirim dan mendapatkan tanda terima baca

Beri tahu layanan bahwa pesan dibaca dan dapatkan daftar pesan baca.

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

Contoh

Bagian berikut ini menyediakan beberapa cuplikan kode yang mencakup beberapa tugas yang paling umum, termasuk:

• Operasi Utas
• Operasi Pesan
• Operasi Peserta Utas
• Operasi Peristiwa

Operasi Utas

Membuat utas

Gunakan metode create_chat_thread untuk membuat utas obrolan.

• Gunakan topic, diperlukan, untuk memberikan topik utas;
• Gunakan thread_participants, opsional, untuk memberikan daftar yang ChatParticipant akan ditambahkan ke utas;
  • user, diperlukan, itu adalah yang CommunicationUserIdentifier Anda buat oleh CommunicationIdentityClient.create_user() dari Token Akses Pengguna
  • display_name, opsional, adalah nama tampilan untuk peserta utas.
  • share_history_time, opsional, adalah waktu ketika riwayat obrolan dibagikan dengan peserta.
• Gunakan idempotency_token, opsional, untuk menentukan pengidentifikasi unik untuk permintaan tersebut.

CreateChatThreadResult adalah hasil yang dikembalikan dari membuat utas, Anda dapat menggunakannya untuk mengambil id utas obrolan yang dibuat. Ini id kemudian dapat digunakan untuk mengambil ChatThreadClient objek menggunakan get_chat_thread_client metode . ChatThreadClient dapat digunakan untuk melakukan operasi obrolan lain ke utas obrolan ini.

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

Mendapatkan utas

Metode penggunaan get_properties mengambil dari layanan; thread_id adalah ID unik dari utasChatThreadProperties.

chat_thread_properties = chat_thread_client.get_properties()

Daftar utas obrolan

Menggunakan list_chat_threads metode mengambil daftar utas obrolan yang dibuat

• Gunakan results_per_page, opsional, Jumlah maksimum pesan yang akan dikembalikan per halaman.
• Gunakan start_time, opsional, Waktu mulai di mana kueri rentang.

Iterator [ChatThreadItem] adalah respons yang ditampilkan dari mencantumkan utas

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)

Memperbarui topik utas

Gunakan update_topic metode untuk memperbarui properti utas. topic digunakan untuk menjelaskan perubahan topik utas

• Gunakan topic untuk memberikan topik baru pada utas;

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

chat_thread = chat_thread_client.get_properties(thread_id)

assert chat_thread.topic == topic

Menghapus utas

Gunakan delete_chat_thread metode untuk menghapus utas; thread_id adalah ID unik utas.

• Gunakan thread_id, diperlukan, untuk menentukan ID unik utas.

chat_client.delete_chat_thread(thread_id=thread_id)

Operasi Pesan

Mengirim pesan

Gunakan send_message metode untuk mengirim pesan ke utas yang diidentifikasi oleh thread_id.

• Gunakan content, diperlukan, untuk menyediakan konten pesan obrolan.
• Gunakan chat_message_type, opsional, untuk menyediakan jenis pesan obrolan. Nilai yang mungkin termasuk: , , , 'html'; jika tidak ditentukan, ChatMessageType.TEXT'text'akan diatur ChatMessageType.HTMLChatMessageType.TEXT
• Gunakan sender_display_name,opsional, untuk menentukan nama tampilan pengirim, jika tidak ditentukan, nama kosong akan diatur

SendChatMessageResult adalah respons yang dikembalikan dari mengirim pesan, berisi id, yang merupakan ID unik pesan.

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)

Mendapatkan pesan

Metode penggunaan get_message mengambil pesan dari layanan; message_id adalah ID unik pesan.

• Gunakan message_id, diperlukan, untuk menentukan id pesan dari pesan ChatMessage yang ada adalah respons yang dikembalikan dari mendapatkan pesan, berisi id, yang merupakan ID unik pesan, dan bidang lainnya, silakan lihat azure.communication.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)

Mencantumkan pesan

Metode penggunaan list_messages mengambil pesan dari layanan.

• Gunakan results_per_page, opsional, Jumlah maksimum pesan yang akan dikembalikan per halaman.
• Gunakan start_time, opsional, Waktu mulai di mana kueri rentang.

Iterator adalah [ChatMessage] respons yang dikembalikan dari mencantumkan pesan

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)

Memperbarui pesan

Gunakan update_message untuk memperbarui pesan yang diidentifikasi oleh threadId dan messageId.

• Gunakan message_id, diperlukan, adalah ID unik pesan.
• Gunakan content, opsional, adalah konten pesan yang akan diperbarui; jika tidak ditentukan, konten tersebut ditetapkan menjadi kosong

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

Menghapus pesan

Gunakan delete_message untuk menghapus pesan.

• Gunakan message_id, diperlukan, adalah ID unik pesan.

chat_thread_client.delete_message(message_id=send_message_result_id)

Operasi Peserta Utas

Daftar peserta utas

Gunakan list_participants untuk mengambil peserta utas.

• Gunakan results_per_page, opsional, Jumlah maksimum peserta yang akan dikembalikan per halaman.
• Gunakan skip, opsional, untuk melompati peserta hingga posisi tertentu sebagai respons.

Iterator adalah [ChatParticipant] respons yang dikembalikan dari peserta daftar

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)

Menambahkan peserta utas

Gunakan add_participants metode untuk menambahkan peserta utas ke utas.

• Gunakan thread_participants, diperlukan, untuk mencantumkan ChatParticipant yang akan ditambahkan ke utas;
  • user, diperlukan, itu adalah yang CommunicationUserIdentifier Anda buat oleh CommunicationIdentityClient.create_user() dari Token Akses Pengguna
  • display_name, opsional, adalah nama tampilan untuk peserta utas.
  • share_history_time, opsional, adalah waktu ketika riwayat obrolan dibagikan dengan peserta.

list(tuple(ChatParticipant, ChatError)) dikembalikan. Ketika peserta berhasil ditambahkan, daftar kosong diharapkan. Jika terjadi kesalahan saat menambahkan peserta, daftar diisi dengan peserta yang gagal bersama dengan kesalahan yang ditemui.

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)

Menghapus peserta utas

Gunakan remove_participant metode untuk menghapus peserta utas dari utas yang diidentifikasi oleh threadId. identifier adalah yang CommunicationUserIdentifier Anda buat oleh CommunicationIdentityClient.create_user() dari azure-communication-identity

dan ditambahkan ke dalam utas obrolan ini.

• Gunakan identifier untuk menentukan yang CommunicationUserIdentifier Anda buat

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

Operasi Peristiwa

Kirim pemberitahuan pengetikan

Gunakan send_typing_notification metode untuk memposting peristiwa pemberitahuan pengetikan ke utas, atas nama pengguna.

chat_thread_client.send_typing_notification()

Mengirim tanda terima dibaca

Gunakan send_read_receipt metode untuk memposting peristiwa tanda terima baca ke utas, atas nama pengguna.

• Gunakan message_id untuk menentukan id pesan yang tanda terima bacanya akan dikirim

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)

Daftar tanda terima yang telah dibaca

Menggunakan list_read_receipts metode mengambil tanda terima baca untuk utas.

• Gunakan results_per_page, opsional, Jumlah maksimum tanda terima baca yang akan dikembalikan per halaman.
• Gunakan skip, opsional, untuk melompati tanda terima baca hingga posisi tertentu sebagai respons.

Iterator adalah [ChatMessageReadReceipt] respons yang dikembalikan dari daftar tanda terima baca

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)

Kode Sampel

Ini adalah sampel kode yang menunjukkan operasi skenario umum dengan pustaka klien Azure Communication Chat. Versi asinkron sampel (file sampel python ditambahkan dengan _async) menunjukkan operasi asinkron. Sebelum menjalankan kode sampel, lihat Prasyarat

untuk membuat sumber daya, lalu atur beberapa Variabel Lingkungan

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

Pemecahan Masalah

Mengalami masalah? Bagian ini harus berisi detail tentang apa yang harus dilakukan di sana.

Langkah berikutnya

Lebih banyak kode sampel harus masuk ke sini, bersama dengan tautan ke tes contoh yang sesuai.

Berkontribusi

Jika Anda menemukan bug atau memiliki saran, silakan ajukan masalah di bagian Masalah proyek.