適用于 Python 的 Azure 通訊身分識別套件用戶端程式庫 - 1.4.0 版

發行項
12/06/2023

Azure 通訊身分識別用戶端套件旨在用來設定基本概念，以開啟使用 Azure 通訊服務供應專案的方式。此套件有助於建立其他用戶端套件所使用的身分識別使用者權杖，例如聊天、通話、簡訊。

| 原始程式碼套件 (Pypi) | 封裝 (Conda) | API 參考檔 | 產品檔

免責聲明

Python 2.7 的 Azure SDK Python 套件支援已于 2022 年 1 月 1 日結束。如需詳細資訊和問題，請參閱 https://github.com/Azure/azure-sdk-for-python/issues/20691

開始使用

Prerequisites

需要 Python 3.7 或更新版本才能使用此套件。
您必須擁有 Azure 訂用帳戶
已部署通訊服務資源。您可以使用Azure 入口網站或 Azure PowerShell來設定。

安裝套件

使用 pip安裝適用于 Python 的 Azure 通訊身分識別用戶端程式庫：

pip install azure-communication-identity

重要概念

CommunicationIdentityClient

CommunicationIdentityClient 會提供用於下列目的的作業：

建立/刪除要用於Azure 通訊服務的身分識別。這些身分識別可用來使用 Azure 通訊供應專案，並可透過權杖範圍限定為有限能力。
建立/撤銷範圍使用者存取權杖，以存取聊天、通話、簡訊等服務。權杖會針對有效的 Azure 通訊身分識別發出，而且可以隨時撤銷。

初始化身分識別用戶端

# You can find your endpoint and access token from your resource in the Azure Portal
import os
from azure.communication.identity import CommunicationIdentityClient
from azure.identity import DefaultAzureCredential

connection_str = "endpoint=ENDPOINT;accessKey=KEY"
endpoint = "https://<RESOURCE_NAME>.communication.azure.com"

# To use Azure Active Directory Authentication (DefaultAzureCredential) make sure to have
# AZURE_TENANT_ID, AZURE_CLIENT_ID and AZURE_CLIENT_SECRET as env variables.
identity_client_managed_identity = CommunicationIdentityClient(endpoint, DefaultAzureCredential())

#You can also authenticate using your connection string
identity_client = CommunicationIdentityClient.from_connection_string(connection_str)

範例

下一節提供數個程式碼片段，涵蓋一些最常見的Azure 通訊服務工作，包括：

建立新使用者
為使用者發出或重新整理存取權杖
在單一要求中建立使用者和權杖
撤銷使用者的存取權杖
正在刪除使用者
交換 Teams 使用者的 Azure AD 存取權杖以進行通訊識別存取權杖

建立新使用者

create_user使用方法來建立新的使用者。

user = identity_client.create_user()
print("User created with id:" + user.properties['id'])

為使用者發出或重新整理存取權杖

get_token使用方法來發出或重新整理使用者的限定範圍存取權杖。
以參數和清單 CommunicationTokenScope 的形式傳入使用者物件。範圍選項包括：

CHAT (使用此選項來完整存取聊天 API)
VOIP (使用此選項來完整存取呼叫 API)
CHAT_JOIN (聊天 API 的存取權，但沒有建立、刪除或更新聊天線程的授權，)
CHAT_JOIN_LIMITED (不允許新增或移除參與者) 的較有限的CHAT_JOIN版本
VOIP_JOIN (呼叫 API 的存取權，但沒有啟動新呼叫的授權)

tokenresponse = identity_client.get_token(user, scopes=[CommunicationTokenScope.CHAT])
print("Token issued with value: " + tokenresponse.token)

發行或重新整理具有使用者自訂到期的存取權杖

您可以指定權杖的到期時間。權杖可以設定為在一小時內到期，或最長為 24 小時。預設到期時間為 24 小時。

token_expires_in = timedelta(hours=1)
tokenresponse = identity_client.get_token(user, scopes=[CommunicationTokenScope.CHAT], token_expires_in=token_expires_in)
print("Token issued with value: " + tokenresponse.token)

在單一要求中建立使用者和權杖

為了方便起見，請使用 create_user_and_token 建立新的使用者，並使用一個函式呼叫發出權杖。這會轉譯成單一 Web 要求，而不是先建立使用者，然後再發行權杖。

user, tokenresponse = identity_client.create_user_and_token(scopes=[CommunicationTokenScope.CHAT])
print("User id:" + user.properties['id'])
print("Token issued with value: " + tokenresponse.token)

在單一要求中建立具有自訂到期的使用者和權杖

您可以指定權杖的到期時間。權杖可以設定為在一小時內到期，或最長為 24 小時。預設到期時間為 24 小時。

token_expires_in = timedelta(hours=1)
user, tokenresponse = identity_client.create_user_and_token(scopes=[CommunicationTokenScope.CHAT], token_expires_in=token_expires_in)
print("User id:" + user.properties['id'])
print("Token issued with value: " + tokenresponse.token)

撤銷使用者的存取權杖

用來 revoke_tokens 撤銷使用者的所有存取權杖。以參數的形式傳入使用者物件

identity_client.revoke_tokens(user)

正在刪除使用者

delete_user使用方法來刪除使用者。以參數的形式傳入使用者物件

identity_client.delete_user(user)

交換 Teams 使用者的 Azure AD 存取權杖以進行通訊識別存取權杖

get_token_for_teams_user使用方法來交換 Teams 使用者的 Azure AD 存取權杖，以取得新的通訊身分識別存取權杖。

identity_client.get_token_for_teams_user(aad_token, client_id, user_object_id)

疑難排解

Azure 通訊服務識別用戶端將會引發 Azure Core中定義的例外狀況。

下一步

提供意見反應

如果您遇到任何錯誤或有建議，請在專案的 [問題 ] 區段中提出問題

參與

此專案歡迎參與和提供建議。大部分的參與都要求您同意「參與者授權合約 (CLA)」，宣告您有權且確實授與我們使用投稿的權利。如需詳細資料，請前往 https://cla.microsoft.com 。

當您提交提取要求時，CLA Bot 會自動判斷您是否需要提供 CLA，並適當地裝飾 PR (例如標籤、註解)。請遵循 bot 提供的指示。您只需要使用我們的 CLA 在所有存放庫上執行此動作一次。

此專案採用 Microsoft Open Source Code of Conduct (Microsoft 開放原始碼管理辦法)。如需詳細資訊，請參閱管理辦法常見問題集，如有任何其他問題或意見請連絡 opencode@microsoft.com。

共用方式為