閱讀英文

共用方式為


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 實例。

傳回類型

例外狀況

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

範例

在 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 實例。

傳回類型

例外狀況

資料庫讀取或建立失敗。

delete_database

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

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

參數

database
strdict(str, str) 或 DatabaseProxy
必要

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

session_token
str

用於會話一致性的權杖。

initial_headers
dict[str,str]

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

etag
str

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

match_condition
MatchConditions

要用於 etag 的比對條件。

response_hook
Callable

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

傳回類型

例外狀況

如果無法刪除資料庫。

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
strdict(str, str)
預設值: None

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

consistency_level
Optional[str]
預設值: None

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

例外狀況

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

get_database_account

擷取資料庫帳戶資訊。

get_database_account(**kwargs: Any) -> DatabaseAccount

參數

response_hook
Callable

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

傳回

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

傳回類型

例外狀況

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

get_database_client

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

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

參數

database
strdict(str, str) 或 DatabaseProxy
必要

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

傳回

代表所擷取資料庫的 DatabaseProxy 實例。

傳回類型

例外狀況

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

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

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

傳回

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

傳回類型

例外狀況

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

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

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

傳回

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

傳回類型

例外狀況

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