CosmosClient 類別

Azure Cosmos DB 帳戶的用戶端邏輯標記法。

使用此用戶端來設定和執行對 Azure Cosmos DB 服務的要求。

其建議在應用程式的每一存留期內維護單一 CosmosClient 實例，以有效管理連線和效能。

CosmosClient 初始化是繁重的作業 - 請勿使用初始化 CosmosClient 實例作為認證或網路連線驗證。

具現化新的 CosmosClient。

繼承

builtins.object

CosmosClient

建構函式

CosmosClient(url: str, credential: str | Dict[str, str] | TokenCredential, *, consistency_level: str | None = None, **kwargs: Any)

參數

url

str

必要

Cosmos DB 帳戶的 URL。

credential

Union[str, Dict[str, str], AsyncTokenCredential]

必要

可以是帳戶金鑰或資源權杖的字典。

consistency_level

str

會話使用的一致性層級。 預設值為 [無] (帳戶層級) 。 進一步瞭解一致性層級和可能的值： https://aka.ms/cosmos-consistency-levels

timeout

int

合併 HTTP 要求和回應處理的絕對逾時，以秒為單位。

connection_timeout

int

HTTP 要求逾時，以秒為單位。

connection_mode

str

用戶端的連線模式 - 目前僅支援「閘道」。

proxy_config

ProxyConfiguration

連線 Proxy 組態。

ssl_config

SSLConfiguration

連線 SSL 組態。

connection_verify

bool

是否要驗證連線，預設值為 True。

connection_cert

str

驗證連線的替代憑證。

retry_total

int

重試次數上限。

retry_backoff_max

int

重試等候時間上限，以秒為單位。

retry_fixed_interval

int

已修正以毫秒為單位的重試間隔。

retry_read

int

通訊端讀取重試嘗試的數目上限。

retry_connect

int

連線錯誤重試嘗試的數目上限。

retry_status

int

錯誤狀態碼的重試嘗試次數上限。

retry_on_status_codes

list[int]

要重試的特定狀態代碼清單。

retry_backoff_factor

float

計算重試嘗試之間等候時間的因素。

enable_endpoint_discovery

bool

啟用異地複寫資料庫帳戶的端點探索。 (預設：True)

preferred_locations

list[str]

異地複寫資料庫帳戶的慣用位置。

enable_diagnostics_logging

bool

啟用 CosmosHttpLogging 原則。 必須與記錄器搭配使用才能運作。

logger

Logger

用來收集要求診斷的記錄器。 可以傳入用戶端層級 (，以記錄) 或單一要求層級的所有要求。 要求將會記錄在 INFO 層級。

範例

建立 Cosmos DB 用戶端的新實例：

       async with CosmosClient(url, key) as client:

方法

close	關閉此 CosmosClient 實例。
create_database	建立具有指定識別碼的新資料庫 (名稱) 。
create_database_if_not_exists	如果資料庫不存在，請建立資料庫。 如果資料庫已經存在，則會傳回現有的設定。 ..注意：如果現有資料庫設定與傳入的專案不同，此函式不會檢查或更新現有的資料庫設定或提供輸送量。
delete_database	刪除具有指定識別碼的資料庫 (名稱) 。
from_connection_string	從連接字串建立 CosmosClient 實例。 這可以從Azure 入口網站擷取。如需選擇性關鍵字引數的完整清單，請參閱 CosmosClient 建構函式。
get_database_client	擷取識別碼為 (名稱) 識別碼的現有資料庫。
list_databases	列出 Cosmos DB SQL 資料庫帳戶中的資料庫。
query_databases	查詢 Cosmos DB SQL 資料庫帳戶中的資料庫。

close

關閉此 CosmosClient 實例。

async close() -> None

create_database

建立具有指定識別碼的新資料庫 (名稱) 。

async create_database(id: str, **kwargs: Any) -> DatabaseProxy

參數

id

str

必要

要建立之資料庫的識別碼 (名稱) 。

offer_throughput

Union[int, ThroughputProperties]

此供應專案的布建輸送量。

session_token

str

用於會話一致性的權杖。

initial_headers

dict[str, str]

要作為要求一部分傳送的初始標頭。

etag

str

ETag 值，或萬用字元 (*)。 用來檢查資源是否已變更，並根據 match_condition 參數所指定的條件採取行動。

match_condition

MatchConditions

要用於 etag 的比對條件。

response_hook

Callable[[Dict[str, str], Dict[str, Any]], None]

使用回應中繼資料叫用的可呼叫 。

傳回

代表新資料庫的 DatabaseProxy 實例。

傳回類型

DatabaseProxy

例外狀況

CosmosResourceExistsError

具有指定識別碼的資料庫已經存在。

範例

在 Cosmos DB 帳戶中建立資料庫：

           database_name = "testDatabase"
           try:
               database = await client.create_database(id=database_name)
           except exceptions.CosmosResourceExistsError:
               database = client.get_database_client(database=database_name)

create_database_if_not_exists

如果資料庫不存在，請建立資料庫。

如果資料庫已經存在，則會傳回現有的設定。

..注意：如果現有資料庫設定與傳入的專案不同，此函式不會檢查或更新現有的資料庫設定或提供輸送量。

async create_database_if_not_exists(id: str, **kwargs: Any) -> DatabaseProxy

參數

id

str

必要

要讀取或建立之資料庫的識別碼 (名稱) 。

offer_throughput

Union[int, ThroughputProperties]

此供應專案的布建輸送量。

session_token

str

用於會話一致性的權杖。

initial_headers

dict[str, str]

要作為要求一部分傳送的初始標頭。

etag

str

ETag 值，或萬用字元 (*)。 用來檢查資源是否已變更，並根據 match_condition 參數所指定的條件採取行動。

match_condition

MatchConditions

要用於 etag 的比對條件。

response_hook

Callable[[Dict[str, str], Dict[str, Any]], None]

使用回應中繼資料叫用的可呼叫 。

傳回

代表資料庫的 DatabaseProxy 實例。

傳回類型

DatabaseProxy

例外狀況

CosmosHttpResponseError

資料庫讀取或建立失敗。

delete_database

刪除具有指定識別碼的資料庫 (名稱) 。

async delete_database(database: str | DatabaseProxy | Dict[str, Any], **kwargs: Any) -> None

參數

database

Union[str, DatabaseProxy, Dict[str, Any]]

必要

識別碼 (名稱) 、代表要刪除之資料庫的屬性或 DatabaseProxy 實例的聽寫。

session_token

str

用於會話一致性的權杖。

initial_headers

dict[str, str]

要作為要求一部分傳送的初始標頭。

etag

str

ETag 值，或萬用字元 (*)。 用來檢查資源是否已變更，並根據 match_condition 參數所指定的條件採取行動。

match_condition

MatchConditions

要用於 etag 的比對條件。

response_hook

Callable[[Dict[str, str]], None]

使用回應中繼資料叫用的可呼叫 。

傳回類型

None

例外狀況

CosmosHttpResponseError

如果無法刪除資料庫。

from_connection_string

從連接字串建立 CosmosClient 實例。

這可以從Azure 入口網站擷取。如需選擇性關鍵字引數的完整清單，請參閱 CosmosClient 建構函式。

from_connection_string(conn_str: str, *, credential: str | Dict[str, str] | None = None, consistency_level: str | None = None, **kwargs: Any) -> CosmosClient

參數

conn_str

str

必要

連接字串。

credential

Union[str, Dict[str, str]]

要使用的替代認證，而不是連接字串中提供的金鑰。

consistency_level

str

會話使用的一致性層級。 預設值為 [無] (帳戶層級) 。 進一步瞭解一致性層級和可能的值： https://aka.ms/cosmos-consistency-levels

傳回

CosmosClient 實例

傳回類型

CosmosClient

get_database_client

擷取識別碼為 (名稱) 識別碼的現有資料庫。

get_database_client(database: str | DatabaseProxy | Dict[str, Any]) -> DatabaseProxy

參數

database

Union[str, DatabaseProxy, Dict[str, Any]]

必要

識別碼 (名稱) 、代表要取得之資料庫的屬性或 DatabaseProxy 實例的聽寫。

傳回

DatabaseProxy實例，表示擷取的資料庫。

傳回類型

DatabaseProxy

list_databases

列出 Cosmos DB SQL 資料庫帳戶中的資料庫。

list_databases(**kwargs: Any) -> AsyncItemPaged[Dict[str, Any]]

參數

max_item_count

int

列舉作業中要傳回的專案數目上限。

session_token

str

用於會話一致性的權杖。

initial_headers

dict[str, str]

要作為要求一部分傳送的初始標頭。

response_hook

Callable[[Dict[str, str]], None]

使用回應中繼資料叫用的可呼叫 。

傳回

(聽寫) 之資料庫屬性的 AsyncItemPaged。

傳回類型

<xref:AsyncItemPaged>[Dict[str, str]]

query_databases

查詢 Cosmos DB SQL 資料庫帳戶中的資料庫。

query_databases(**kwargs: Any) -> AsyncItemPaged[Dict[str, Any]]

參數

query

Union[str, Dict[str, Any]]

要執行的 Azure Cosmos DB SQL 查詢。

parameters

List[Dict[str, Any]]

查詢的參數選擇性陣列。 每個參數都是具有 'name' 和 'value' 索引鍵的 dict () 。

max_item_count

int

列舉作業中要傳回的專案數目上限。

session_token

str

用於會話一致性的權杖。

initial_headers

dict[str, str]

要作為要求一部分傳送的初始標頭。

response_hook

Callable[[Dict[str, str]], None]

使用回應中繼資料叫用的可呼叫 。

傳回

(聽寫) 之資料庫屬性的 AsyncItemPaged。

傳回類型

<xref:AsyncItemPaged>[Dict[str, str]]