CosmosClient 類別

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

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

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

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

具現化新的 CosmosClient。

繼承

builtins.object

CosmosClient

建構函式

CosmosClient(url: str, credential: Any, consistency_level: str | None = None, **kwargs: Any)

參數

url

str

必要

Cosmos DB 帳戶的 URL。

credential

Union[str, Dict[str, str], TokenCredential]

必要

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

consistency_level

str

預設值: None

會話使用的一致性層級。 預設值為 [無] (帳戶層級) 。 進一步瞭解一致性層級和可能的值： 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 用戶端的新實例：

   from azure.cosmos import exceptions, CosmosClient, PartitionKey

   import os

   url = os.environ["ACCOUNT_URI"]
   key = os.environ["ACCOUNT_KEY"]
   client = CosmosClient(url, key)

方法

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

create_database

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

create_database(id: str, populate_query_metrics: bool | None = None, offer_throughput: int | ThroughputProperties | None = None, **kwargs: Any) -> DatabaseProxy

參數

id

必要

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

offer_throughput

必要

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

session_token

str

用於會話一致性的權杖。

initial_headers

dict[str,str]

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

etag

str

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

match_condition

MatchConditions

要用於 etag 的比對條件。

response_hook

Callable

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

傳回

代表新資料庫的 DatabaseProxy 實例。

傳回類型

DatabaseProxy

例外狀況

CosmosResourceExistsError

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

範例

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

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

create_database_if_not_exists

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

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

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

create_database_if_not_exists(id: str, populate_query_metrics: bool | None = None, offer_throughput: int | ThroughputProperties | None = None, **kwargs: Any) -> DatabaseProxy

參數

id

必要

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

populate_query_metrics

bool

必要

在回應標頭中啟用傳回查詢計量。

offer_throughput

int 或 <xref:azure.cosmos.ThroughputProperties.>

必要

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

session_token

str

用於會話一致性的權杖。

initial_headers

dict[str,str]

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

etag

str

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

match_condition

MatchConditions

要用於 etag 的比對條件。

response_hook

Callable

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

傳回

代表資料庫的 DatabaseProxy 實例。

傳回類型

DatabaseProxy

例外狀況

CosmosHttpResponseError

資料庫讀取或建立失敗。

delete_database

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

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

參數

database

str 或 dict(str, str) 或 DatabaseProxy

必要

識別碼 (名稱) ，代表要刪除之資料庫的屬性或 <xref:azure.cosmos.cosmos_client.DatabaseProxy> 實例。

session_token

str

用於會話一致性的權杖。

initial_headers

dict[str,str]

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

etag

str

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

match_condition

MatchConditions

要用於 etag 的比對條件。

response_hook

Callable

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

傳回類型

None

例外狀況

CosmosHttpResponseError

如果無法刪除資料庫。

from_connection_string

從連接字串建立 CosmosClient 實例。

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

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

參數

conn_str

str

必要

連接字串。

credential

str 或 dict(str, str)

預設值: None

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

consistency_level

Optional[str]

預設值: None

會話使用的一致性層級。 預設值為 [無] (帳戶層級) 。

例外狀況

CosmosResourceExistsError

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

get_database_account

擷取資料庫帳戶資訊。

get_database_account(**kwargs: Any) -> DatabaseAccount

參數

response_hook

Callable

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

傳回

代表 Cosmos DB 資料庫帳戶的 DatabaseAccount 實例。

傳回類型

DatabaseAccount

例外狀況

CosmosResourceExistsError

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

get_database_client

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

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

參數

database

str 或 dict(str, str) 或 DatabaseProxy

必要

識別碼 (名稱) ，代表要讀取之資料庫的屬性或 DatabaseProxy 實例。

傳回

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

傳回類型

DatabaseProxy

例外狀況

CosmosResourceExistsError

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

list_databases

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

list_databases(max_item_count: int | None = None, populate_query_metrics: bool | None = None, **kwargs: Any) -> Iterable[Dict[str, Any]]

參數

max_item_count

int

必要

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

session_token

str

用於會話一致性的權杖。

initial_headers

dict[str,str]

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

response_hook

Callable

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

傳回

可反覆運算 (聽寫) 的資料庫屬性。

傳回類型

Iterable[dict[str, str]]

例外狀況

CosmosResourceExistsError

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

query_databases

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

query_databases(query: str | None = None, parameters: List[Dict[str, Any]] | None = None, enable_cross_partition_query: bool | None = None, max_item_count: int | None = None, populate_query_metrics: bool | None = None, **kwargs: Any) -> Iterable[Dict[str, Any]]

參數

query

str

必要

要執行的 Azure Cosmos DB SQL 查詢。

parameters

List[Dict[str, Any]]

必要

查詢的參數選擇性陣列。 如果未提供任何查詢，則會忽略。

enable_cross_partition_query

bool

必要

允許掃描無法做為索引的查詢，已選擇在要求的路徑上退出。

max_item_count

int

必要

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

session_token

str

用於會話一致性的權杖。

initial_headers

dict[str,str]

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

response_hook

Callable

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

傳回

可反覆運算 (聽寫) 的資料庫屬性。

傳回類型

Iterable[dict[str, str]]

例外狀況

CosmosResourceExistsError

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