Python 用 Azure Communication Chat Package クライアント ライブラリ - バージョン 1.2.0
このパッケージには、チャット用の python SDK for Azure Communication Servicesが含まれています。 Azure Communication Servicesの詳細については、こちらを参照してください
ソースコード | パッケージ (Pypi) | パッケージ (Conda) | API リファレンス ドキュメント | 製品ドキュメント
免責事項
Python 2.7 の Azure SDK Python パッケージのサポートは、2022 年 1 月 1 日に終了しました。 詳細と質問については、https://github.com/Azure/azure-sdk-for-python/issues/20691 を参照してください
作業の開始
前提条件
- このパッケージを使用するには、Python 3.7 以降が必要です。
- デプロイ済みの Communication Services リソース。 Azure Portal またはAzure PowerShellを使用して設定できます。
パッケージをインストールする
Azure Communication Service Chat SDK をインストールします。
pip install --pre azure-communication-chat
ユーザー アクセス トークン
ユーザーのアクセス トークンを使用することで、Azure Communication Services に対して直接認証を行うクライアント アプリケーションを作成できます。 azure.communication.identity モジュールを使用してこれらのトークンを生成し、それらを使用して Communication Services SDK を初期化できます。 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
userこのトークンを使用して作成するときに、そのユーザーを新しいチャット スレッドの参加者として追加する必要があるため、上記で作成した が後で使用されます。 これは、作成要求の発信側がチャット スレッドの参加者の一覧に含まれている必要があるためです。
チャット クライアントを作成する
これにより、チャット スレッドを作成、取得、一覧表示、または削除できます。
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 を使用すると、メッセージの送信、メッセージの取得、チャット スレッド トピックの更新、チャット スレッドへの参加者の追加など、チャット スレッドに固有の操作を実行できます。
これを取得するには、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)
さらに、クライアントは要求を繰り返し可能にするように指示することもできます。つまり、クライアントが同じ Idempotency-Token で要求を複数回行い、サーバーが要求を複数回実行せずに適切な応答を返す場合です。 Idempotency-Token の値は、クライアントによって生成され、常にグローバルに一意である要求の識別子を表す不透明な文字列です。
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)
または、以前にチャット スレッドを作成し、そのthread_idがある場合は、次の方法で作成できます。
chat_thread_client = chat_client.get_chat_thread_client(thread_id) # thread_id is the id of an existing chat thread
主要な概念
チャットの会話は、チャット スレッドによって表されます。 スレッド内の各ユーザーは、スレッド参加要素と呼ばれます。 スレッドの参加者は、1 対 1 のチャットで互いにプライベートにチャットしたり、1:N グループ チャットに参加したりできます。 また、ユーザーは、他のユーザーが入力しているときやメッセージを読んだときに、ほぼリアルタイムで更新を受け取ります。
クラスを ChatClient 初期化したら、次のチャット操作を実行できます。
スレッドの作成、取得、更新、削除
スレッドに対して CRD(Create-Read-Delete) 操作を実行する
create_chat_thread(topic, **kwargs)
list_chat_threads(**kwargs)
delete_chat_thread(thread_id, **kwargs)
クラスを ChatThreadClient 初期化したら、次のチャット操作を実行できます。
スレッドの更新
スレッド トピックで更新操作を実行する
update_topic(topic, **kwargs)
チャット スレッドのプロパティを取得する
get_properties(**kwargs)
メッセージの送信、取得、更新、削除
メッセージに対して CRUD(Create-Read-Update-Delete) 操作を実行する
send_message(content, **kwargs)
get_message(message_id, **kwargs)
list_messages(**kwargs)
update_message(message_id, content, **kwargs)
delete_message(message_id, **kwargs)
参加者を取得、追加、削除する
スレッド参加者に対して CRD(Create-Read-Delete) 操作を実行する
list_participants(**kwargs)
add_participants(thread_participants, **kwargs)
remove_participant(participant_identifier, **kwargs)
入力通知を送信する
入力通知をサービスに通知する
send_typing_notification(**kwargs)
開封確認メッセージを送信して取得する
メッセージが読み取られ、読み取りメッセージの一覧を取得することをサービスに通知します。
send_read_receipt(message_id, **kwargs)
list_read_receipts(**kwargs)
例
次のセクションでは、次のような最も一般的なタスクをカバーするいくつかのコード スニペットを示します。
スレッド操作
スレッドを作成する
チャット スレッドは、create_chat_thread メソッドを使用して作成します。
- スレッド トピックを指定するには、 を使用
topicする必要があります。 - スレッドに追加する を一覧表示
ChatParticipantするには、省略可能な を使用thread_participantsします。userは必須です。これはCommunicationUserIdentifier、ユーザー アクセス トークンから CommunicationIdentityClient.create_user() によって作成された です
display_name(省略可) は、スレッド参加者の表示名です。`shareHistoryTime` (省略可) は、参加者との間でチャット履歴が共有される際の起点となる時刻です。
- 要求の一意識別子を指定するには、省略可能な を使用
idempotency_tokenします。
CreateChatThreadResult は、スレッドの作成から返された結果であり、作成されたチャット スレッドの id を取得するために使用できます。 その後、この id は、get_chat_thread_client メソッドを使用して ChatThreadClient オブジェクトをフェッチするために使用できます。 ChatThreadClient は、このチャット スレッドに対して他のチャット操作を実行するために使用できます。
# 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)
スレッドを取得する
get_properties メソッドを使用して、サービスから ChatThreadProperties を取得します。thread_id はスレッドの一意の ID です。
chat_thread_properties = chat_thread_client.get_properties()
チャット スレッドを一覧表示する
Use list_chat_threads メソッドは、作成されたチャット スレッドの一覧を取得します
- 、省略可能、ページごとに返されるメッセージの最大数を使用
results_per_pageします。 - 、省略可能、範囲クエリの開始時刻を使用
start_timeします。
[ChatThreadItem] の反復子は、スレッドの一覧表示から返される応答です
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)
スレッド トピックを更新する
メソッドを使用して update_topic スレッドのプロパティを更新します。 topic は、スレッド トピックの変更を記述するために使用されます
- スレッドに新しいトピックを提供するには、 を使用
topicします。
topic = "new topic"
chat_thread_client.update_topic(topic=topic)
chat_thread = chat_thread_client.get_properties(thread_id)
assert chat_thread.topic == topic
スレッドを削除する
スレッドthread_idを削除するには、 メソッドを使用delete_chat_threadします。スレッドの一意の ID です。
- スレッドの一意の ID を指定するには、
thread_id(必須) を使用します。
chat_client.delete_chat_thread(thread_id=thread_id)
メッセージ操作
メッセージの送信
によって識別されるthread_idスレッドにメッセージを送信するには、 メソッドを使用send_messageします。
- チャット メッセージの内容を指定するには、 必須を使用
contentします。 - チャット メッセージの種類を指定するには、省略可能な を使用
chat_message_typeします。 指定できる値は、ChatMessageType.TEXT、ChatMessageType.HTML、、'html''text'、 です。指定されていない場合は、ChatMessageType.TEXTが設定されます。 - 送信者の表示名を指定するには 、省略可能を使用
sender_display_nameします。指定しない場合は、空の名前が設定されます
SendChatMessageResult は、メッセージの送信から返された応答です。ここには id (メッセージの一意の ID) が含まれています。
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)
メッセージを取得する
Use get_message メソッドは、サービス message_id からメッセージを取得します。メッセージの一意の ID です。
- を使用して
message_id、既存のメッセージのメッセージ ID を指定するには、メッセージChatMessageの取得から返される応答を指定し、メッセージの一意の ID である ID を含み、その他のフィールドは 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)
メッセージを一覧表示する
Use list_messages メソッドは、サービスからメッセージを取得します。
- 、省略可能、ページごとに返されるメッセージの最大数を使用
results_per_pageします。 - 、省略可能、範囲クエリの開始時刻を使用
start_timeします。
[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)
メッセージを更新する
threadId と messageId で識別されるメッセージを更新するには、 を使用 update_message します。
message_id(必須) を使用します。これは、メッセージの一意の ID です。content(省略可能) は、更新されるメッセージの内容です。指定しなかった場合は、空になります
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
メッセージを削除する
メッセージを削除するには、 を使用 delete_message します。
- を使用します
message_id。必須です。メッセージの一意の ID です。
chat_thread_client.delete_message(message_id=send_message_result_id)
スレッド参加者操作
スレッドの参加者を一覧表示する
スレッドの参加者を取得するには、list_participants を使用します。
results_per_page(省略可能) を使用します。これは、ページごとに返される参加者の最大数です。- 応答内の指定した位置まで参加者をスキップするには、
skip(省略可能) を使用します。
[ChatParticipant] の反復子は、参加者の一覧表示から返される応答です
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)
スレッド参加者を追加する
スレッド参加者をスレッドに追加するには、 メソッドを使用 add_participants します。
- スレッドに追加する を
ChatParticipant一覧表示するには、 を使用thread_participantsします。必須です。userは必須です。これはCommunicationUserIdentifier、ユーザー アクセス トークンから CommunicationIdentityClient.create_user() によって作成された です
display_name(省略可) は、スレッド参加者の表示名です。`shareHistoryTime` (省略可) は、参加者との間でチャット履歴が共有される際の起点となる時刻です。
list(tuple(ChatParticipant, ChatError)) が返される。 参加者が正常に追加されると、空の一覧が予期されます。 参加者の追加中にエラーが発生した場合は、失敗した参加者と、発生したエラーが一覧に設定されます。
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)
スレッド参加者を削除する
threadId で識別されるスレッドからスレッド参加者を削除するには、remove_participant メソッドを使用します。
identifier は、 CommunicationUserIdentifier CommunicationIdentityClient.create_user() によって作成された azure-communication-identity
と は、このチャット スレッドに追加されました。
- を使用して
identifier、作成した を指定しますCommunicationUserIdentifier。
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))
イベント操作
入力通知を送信する
メソッドを使用して send_typing_notification 、ユーザーの代わりに、型指定通知イベントをスレッドに投稿します。
chat_thread_client.send_typing_notification()
開封確認メッセージを送信する
メソッドを使用して send_read_receipt 、ユーザーの代わりに開封確認イベントをスレッドに投稿します。
- 開封確認メッセージを送信するメッセージの ID を指定するには、 を使用
message_idします。
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)
開封確認メッセージを一覧表示する
Use list_read_receipts メソッドは、スレッドの開封確認メッセージを取得します。
- 、省略可能、ページごとに返される開封確認メッセージの最大数を使用
results_per_pageします。 - 応答で指定した位置まで開封確認メッセージをスキップするには、省略可能な を使用
skipします。
[ChatMessageReadReceipt] の反復子は、開封確認メッセージの一覧表示から返される応答です
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)
サンプル コード
これらは、Azure Communication Chat クライアント ライブラリでの一般的なシナリオ操作を示すコード サンプルです。
サンプルの非同期バージョン (python サンプル ファイルに が追加) には、非同期操作が表示されます _async。
サンプル コードを実行する前に、「前提条件」を参照してください
リソースを作成し、環境変数を設定する
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
トラブルシューティング
問題が発生していますか? このセクションには、そこで何を行うかの詳細が含まれている必要があります。
次の手順
その他のサンプル コードについては、適切なサンプル テストへのリンクと共に 、こちらを参照してください。
共同作成
バグが発生した場合、または提案がある場合は、プロジェクトの [問題 ] セクションに問題を提出してください。
Azure SDK for Python
フィードバック
以下は間もなく提供いたします。2024 年を通じて、コンテンツのフィードバック メカニズムとして GitHub の issue を段階的に廃止し、新しいフィードバック システムに置き換えます。 詳細については、「https://aka.ms/ContentUserFeedback」を参照してください。
フィードバックの送信と表示