適用于 Python 的 Azure 通訊身分識別套件用戶端程式庫 - 1.4.0 版
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 通訊服務工作,包括:
建立新使用者
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。