DataverseClient 類別

Microsoft Dataverse 營運的高階客戶端。

此用戶端提供簡單且穩定的介面，透過 Web API 與 Dataverse 環境互動。 它透過 Azure 身份處理認證，並將 HTTP 操作委派給內部的 OData 用戶端。

主要功能：

  • OData CRUD 操作：建立、讀取、更新、刪除紀錄

  • SQL 查詢：透過 Web API ?sql 參數執行唯讀 SQL

  • 資料表元資料：建立、檢查及刪除自訂資料表;建立與刪除欄位

  • 檔案上傳：將檔案上傳到支援分塊的檔案欄位

備註

用戶端在首次使用時會懶散地初始化內部 OData 用戶端，允許輕量級建置而無需立即呼叫網路。

備註

所有與 Dataverse Web API 通訊的方法可能會產生

HttpError 關於未成功

HTTP 回應（例如 401、403、404、429、500）。 個別方法

docstring 僅記錄域特定例外。

操作組織於命名空間中：

  • client.records – 建立、更新、刪除及取得紀錄（單次或分頁查詢）

  • client.query – 查詢與搜尋操作

  • client.tables – 表格與欄位元資料管理

  • client.files – 檔案上傳操作

  • client.dataframe – pandas DataFrame 封裝器用於記錄 CRUD

  • client.batch – 將多個操作批次化成單一 HTTP 請求

v0 beta 方法（、client.createclient.query_sql 等）在 1.0 GA 中被移除。 現在 AttributeError 呼叫 GA 會收到訊息，並指定 GA 替換和 codemod 指令——以前這些呼叫只會發出一個空洞 AttributeError 且沒有遷移提示，因此除錯半遷移的程式碼非常痛苦。 請參見_REMOVED_BETA_METHODS。

用戶端支援 Python 的上下文管理器協定，用於自動資源清理與 HTTP 連線池：

建構函式

DataverseClient(base_url: str, credential: TokenCredential, config: DataverseConfig | None = None, *, context: OperationContext | None = None)

參數

名稱 Description
base_url
必要
str

例如 "https://org.crm.dynamics.com"你的 Dataverse 環境 URL。 尾部斬擊會自動移除。
credential
必要
TokenCredential

Azure Identity credential for authentication.
config
DataverseConfig 或 None

語言、超時和重試的可選設定。 若未提供，預設值將從 載入 from_env。

預設值: None
context
必要
OperationContext 或 None

可選地附加在外掛 User-Agent 標頭後的呼叫者定義上下文物件，用於外掛/工具歸屬。 不能與 config – Pass the context with DataverseConfig with instead with the context s.

僅限關鍵字的參數

名稱 Description
context
預設值: None

範例

推薦 – 情境管理器 （啟用 HTTP 連線池）：


   from azure.identity import InteractiveBrowserCredential
   from PowerPlatform.Dataverse.client import DataverseClient

   credential = InteractiveBrowserCredential()

   with DataverseClient("https://org.crm.dynamics.com", credential) as client:
       record_id = client.records.create("account", {"name": "Contoso Ltd"})
       client.records.update("account", record_id, {"telephone1": "555-0100"})
   # Session closed, caches cleared automatically

手動生命週期：


   client = DataverseClient("https://org.crm.dynamics.com", credential)
   try:
       record_id = client.records.create("account", {"name": "Contoso Ltd"})
   finally:
       client.close()

方法

close

關閉客戶端並釋放資源。

關閉 HTTP 會話（如果有的話）、清除內部快取，並將客戶端標記為關閉。 可以多次打電話。 成交後，任何操作都會被提升 RuntimeError。

當使用客戶端作為上下文管理器時，會自動呼叫。

範例：


   client = DataverseClient(base_url, credential)
   try:
       client.records.create("account", {"name": "Contoso"})
   finally:
       client.close()
flush_cache

清除快取的客戶端元資料或狀態。

close

關閉客戶端並釋放資源。

關閉 HTTP 會話（如果有的話）、清除內部快取，並將客戶端標記為關閉。 可以多次打電話。 成交後，任何操作都會被提升 RuntimeError。

當使用客戶端作為上下文管理器時，會自動呼叫。

範例：


   client = DataverseClient(base_url, credential)
   try:
       client.records.create("account", {"name": "Contoso"})
   finally:
       client.close()

close() -> None

flush_cache

清除快取的客戶端元資料或狀態。

flush_cache(kind) -> int

參數

名稱 Description
kind
必要
str

快取類型會沖洗。 目前支援的價值觀：

  • "picklist"： 清除用於標籤轉整數轉換的選擇清單標籤快取

未來類型（例如 "entityset"、 "primaryid"）可以在不破壞此簽名的情況下加入。

傳回

類型 Description
int

移除的快取條目數量。

範例

清除選擇清單快取：


   removed = client.flush_cache("picklist")
   print(f"Cleared {removed} cached picklist entries")