TableClient 類別

參考

要與 Azure 資料表帳戶中特定資料表互動的用戶端。

從認證建立 TableClient。

AzureSasCredential (azure-core) ，或來自 azure-identity 的 AsyncTokenCredential 實作。 :p aramtype 認證：

~azure.core.credentials.AzureNamedKeyCredential 或 ~azure.core.credentials.AzureSasCredential 或 ~azure.core.credentials_async。AsyncTokenCredential 或 None

繼承: azure.data.tables.aio._base_client_async.AsyncTablesBaseClient

TableClient

建構函式

TableClient(endpoint: str, table_name: str, *, credential: AzureSasCredential | AzureNamedKeyCredential | AsyncTokenCredential | None = None, **kwargs)

參數

endpoint: str

必要

Azure 資料表帳戶的 URL。

table_name: str

必要

資料表名稱。

credential

要用來驗證的認證。如果帳戶 URL 已經有 SAS 權杖，則這是選擇性的。此值可以是其中一個 AzureNamedKeyCredential (azure-core) ，

api_version: str

指定用於這個要求的作業版本。預設值為「2019-02-02」。請注意，覆寫此預設值可能會導致不支援的行為。

變數

account_name: str

資料表帳戶的名稱。

table_name: str

資料表的名稱。

scheme: str

資料表帳戶完整 URL 中的配置元件。

url: str

儲存體端點。

api_version: str

服務 API 版本。

方法

close	這個方法是關閉用戶端所開啟的通訊端。搭配內容管理員使用時，不需要使用它。
create_entity	在資料表中插入實體。
create_table	在指定的帳號下建立新的資料表。
delete_entity	刪除資料表中指定的實體。如果找不到實體或 PartitionKey-RowKey 配對，將不會引發任何錯誤。
delete_table	刪除目前帳戶底下的資料表。如果找不到指定的資料表名稱，將不會引發任何錯誤。
from_connection_string	從連接字串建立 TableClient。
from_table_url	要與特定資料表互動的用戶端。
get_entity	取得資料表中的單一實體。
get_table_access_policy	擷取資料表上指定之任何預存存取原則的詳細資料，這些原則可能與共享存取簽章搭配使用。
list_entities	列出資料表中的實體。
query_entities	列出資料表中的實體。
set_table_access_policy	設定可用於共用存取簽章之資料表的預存存取原則。
submit_transaction	將作業清單認可為單一交易。如果其中任一個作業失敗，將會拒絕整個交易。
update_entity	更新資料表中的實體。
upsert_entity	更新/合併或插入實體至資料表。

close

這個方法是關閉用戶端所開啟的通訊端。搭配內容管理員使用時，不需要使用它。

async close() -> None

create_entity

在資料表中插入實體。

async create_entity(entity: TableEntity | Mapping[str, Any], **kwargs) -> Mapping[str, Any]

參數

entity: TableEntity 或 Mapping

必要

資料表實體的屬性。

傳回

從服務傳回的字典對應作業中繼資料

傳回類型

dict[str, Any]

例外狀況

ResourceExistsError

如果實體已經存在

範例

將實體新增至資料表


   async with table_client:
       try:
           await table_client.create_table()
       except HttpResponseError:
           print("Table already exists")

       try:
           resp = await table_client.create_entity(entity=self.entity)
           print(resp)
       except ResourceExistsError:
           print("Entity already exists")

create_table

在指定的帳號下建立新的資料表。

async create_table(**kwargs) -> TableItem

傳回

代表所建立資料表的 TableItem。

傳回類型

TableItem

例外狀況

ResourceExistsError

如果實體已經存在

delete_entity

刪除資料表中指定的實體。如果找不到實體或 PartitionKey-RowKey 配對，將不會引發任何錯誤。

async delete_entity(partition_key: str, row_key: str, **kwargs) -> None

參數

partition_key: str

必要

實體的分割區索引鍵。

row_key: str

必要

實體的資料列索引鍵。

entity: Union[TableEntity, Mapping[str, str]]

必要

要刪除的實體

etag: str

實體的 Etag

match_condition: MatchConditions

要在其中執行作業的條件。支援的值包括：MatchConditions.IfNotModified、MatchConditions.無條件地。預設值為無條件。

傳回

無

例外狀況

HttpResponseError

範例

將實體新增至資料表


   async with table_client:
       try:
           resp = await table_client.create_entity(entity=self.entity)
       except ResourceExistsError:
           print("Entity already exists!")

       await table_client.delete_entity(row_key=self.entity["RowKey"], partition_key=self.entity["PartitionKey"])  # type: ignore[call-overload]
       print("Successfully deleted!")

delete_table

刪除目前帳戶底下的資料表。如果找不到指定的資料表名稱，將不會引發任何錯誤。

async delete_table(**kwargs) -> None

傳回

無

例外狀況

HttpResponseError

範例

從 TableClient 物件中刪除資料表。


   async with TableClient.from_connection_string(
       conn_str=self.connection_string, table_name=self.table_name
   ) as table_client:
       await table_client.delete_table()
       print("Deleted table {}!".format(table_client.table_name))

from_connection_string

從連接字串建立 TableClient。

from_connection_string(conn_str: str, table_name: str, **kwargs) -> TableClient

參數

conn_str: str

必要

Azure 資料表帳戶的連接字串。

table_name: str

必要

資料表名稱。

傳回

資料表用戶端。

傳回類型

TableClient

範例

從連接字串建立 TableClient。


   from azure.data.tables.aio import TableClient

   async with TableClient.from_connection_string(
       conn_str=self.connection_string, table_name="tableName"
   ) as table_client:
       print("Table name: {}".format(table_client.table_name))

from_table_url

要與特定資料表互動的用戶端。

from_table_url(table_url: str, *, credential: AzureNamedKeyCredential | AzureSasCredential | None = None, **kwargs) -> TableClient

參數

table_url: str

必要

資料表的完整 URI，包括使用 SAS 權杖。

credential: AzureNamedKeyCredential 或 AzureSasCredential 或 None

要用來驗證的認證。如果資料表 URL 已經有 SAS 權杖，則這是選擇性的。

傳回

資料表用戶端。

傳回類型

TableClient

get_entity

取得資料表中的單一實體。

async get_entity(partition_key: str, row_key: str, **kwargs) -> TableEntity

參數

partition_key: str

必要

實體的分割區索引鍵。

row_key: str

必要

實體的資料列索引鍵。

select: str 或 list[str]

指定要傳回之實體的所需屬性。

傳回

從服務傳回的字典對應作業中繼資料

傳回類型

TableEntity

例外狀況

HttpResponseError

範例

從 PartitionKey 和 RowKey 取得實體


   # Get Entity by partition and row key
   got_entity = await table.get_entity(
       partition_key=my_entity["PartitionKey"], row_key=my_entity["RowKey"]  # type: ignore[arg-type]
   )
   print("Received entity: {}".format(got_entity))

get_table_access_policy

擷取資料表上指定之任何預存存取原則的詳細資料，這些原則可能與共享存取簽章搭配使用。

async get_table_access_policy(**kwargs) -> Mapping[str, TableAccessPolicy | None]

傳回

SignedIdentifiers 的字典

傳回類型

dict[str, TableAccessPolicy],

dict[str, None]

例外狀況

HttpResponseError

list_entities

列出資料表中的實體。

list_entities(**kwargs) -> AsyncItemPaged[TableEntity]

參數

results_per_page: int

每個服務要求傳回的實體數目。

select: str 或 list[str]

指定要傳回之實體的所需屬性。

傳回

的非同步反覆運算器 TableEntity

傳回類型

AsyncItemPaged[TableEntity]

例外狀況

HttpResponseError

範例

從 TableClient 查詢實體


   # Query the entities in the table
   i = 0
   async for entity in table.list_entities():
       print("Entity #{}: {}".format(i, entity))
       i += 1

query_entities

列出資料表中的實體。

query_entities(query_filter: str, **kwargs) -> AsyncItemPaged[TableEntity]

參數

query_filter: str

必要

指定篩選準則以傳回特定實體。如需篩選格式的詳細資訊，請參閱範例檔。

results_per_page: int

每個服務要求傳回的實體數目。

select: str 或 list[str]

指定要傳回之實體的所需屬性。

parameters: dict[str, Any]

使用其他使用者定義的參數來格式化查詢的字典

傳回

的非同步反覆運算器 TableEntity

傳回類型

AsyncItemPaged[TableEntity]

例外狀況

HttpResponseError

範例

從 TableClient 查詢實體


   async with TableClient.from_connection_string(self.connection_string, self.table_name) as table_client:
       try:
           print("Basic sample:")
           print("Entities with name: marker")
           parameters = {"name": "marker"}
           name_filter = "Name eq @name"
           queried_entities = table_client.query_entities(
               query_filter=name_filter, select=["Brand", "Color"], parameters=parameters
           )
           async for entity_chosen in queried_entities:
               print(entity_chosen)

           print("Sample for querying entities withtout metadata:")
           print("Entities with name: marker")
           parameters = {"name": "marker"}
           name_filter = "Name eq @name"
           headers = {"Accept": "application/json;odata=nometadata"}
           queried_entities = table_client.query_entities(
               query_filter=name_filter, select=["Brand", "Color"], parameters=parameters, headers=headers
           )
           async for entity_chosen in queried_entities:
               print(entity_chosen)

           print("Sample for querying entities with multiple params:")
           print("Entities with name: marker and brand: Crayola")
           parameters = {"name": "marker", "brand": "Crayola"}
           name_filter = "Name eq @name and Brand eq @brand"
           queried_entities = table_client.query_entities(
               query_filter=name_filter, select=["Brand", "Color"], parameters=parameters
           )
           async for entity_chosen in queried_entities:
               print(entity_chosen)

           print("Sample for querying entities' values:")
           print("Entities with 25 < Value < 50")
           parameters = {"lower": 25, "upper": 50}  # type: ignore
           name_filter = "Value gt @lower and Value lt @upper"
           queried_entities = table_client.query_entities(
               query_filter=name_filter, select=["Value"], parameters=parameters
           )
           async for entity_chosen in queried_entities:
               print(entity_chosen)
       except HttpResponseError as e:
           raise

set_table_access_policy

設定可用於共用存取簽章之資料表的預存存取原則。

async set_table_access_policy(signed_identifiers: Mapping[str, TableAccessPolicy | None], **kwargs) -> None

參數

signed_identifiers: dict[str, TableAccessPolicy]

必要

要為數據表設定的存取原則

傳回

無

例外狀況

HttpResponseError

submit_transaction

將作業清單認可為單一交易。

如果其中任一個作業失敗，將會拒絕整個交易。

async submit_transaction(operations: Iterable[Tuple[TransactionOperation | str, TableEntity | Mapping[str, Any]] | Tuple[TransactionOperation | str, TableEntity | Mapping[str, Any], Mapping[str, Any]]] | AsyncIterable[Tuple[TransactionOperation | str, TableEntity | Mapping[str, Any]] | Tuple[TransactionOperation | str, TableEntity | Mapping[str, Any], Mapping[str, Any]]], **kwargs) -> List[Mapping[str, Any]]

參數

operations: Union[Iterable[Tuple[str, <xref:Entity>, Mapping[str, Any]]],AsyncIterable[Tuple[str, <xref:Entity>, Mapping[str, Any]]]]

必要

交易中要認可的作業清單。這應該是可反覆運算的 (或可非同步反覆運算的 Tuple) ，其中包含作業名稱、要操作的實體，以及選擇性地針對該作業使用其他 kwargs 的聽寫。例如：


   - ('upsert', {'PartitionKey': 'A', 'RowKey': 'B'})
   - ('upsert', {'PartitionKey': 'A', 'RowKey': 'B'}, {'mode': UpdateMode.REPLACE})

傳回

交易中每個作業的回應中繼資料對應清單。

傳回類型

list[Mapping[str, Any]]

例外狀況

TableTransactionError

範例

使用交易一次傳送多個要求


   from azure.data.tables.aio import TableClient
   from azure.data.tables import TableTransactionError
   from azure.core.exceptions import ResourceExistsError

   self.table_client = TableClient.from_connection_string(
       conn_str=self.connection_string, table_name=self.table_name
   )

   try:
       await self.table_client.create_table()
       print("Created table")
   except ResourceExistsError:
       print("Table already exists")

   await self._create_entities()

   operations = [
       ("create", self.entity1),
       ("delete", self.entity2),
       ("upsert", self.entity3),
       ("update", self.entity4, {"mode": "replace"}),
   ]
   try:
       await self.table_client.submit_transaction(operations)  # type: ignore[arg-type]
   except TableTransactionError as e:
       print("There was an error with the transaction operation")
       print("Error: {}".format(e))

update_entity

更新資料表中的實體。

async update_entity(entity: TableEntity | Mapping[str, Any], mode: str | UpdateMode = UpdateMode.MERGE, **kwargs) -> Mapping[str, Any]

參數

entity: TableEntity 或 dict[str, Any]

必要

資料表實體的屬性。

mode: UpdateMode

必要

合併或取代實體

etag: str

實體的 Etag

match_condition: <xref:azure.core.MatchCondition>

要在其中執行作業的條件。支援的值包括：MatchConditions.IfNotModified、MatchConditions.無條件地。預設值為無條件。

傳回

從服務傳回的作業元資料字典

傳回類型

dict[str, Any]

例外狀況

HttpResponseError

範例

從 TableClient 查詢實體


   # Update the entity
   created["text"] = "NewMarker"
   await table.update_entity(mode=UpdateMode.REPLACE, entity=created)

   # Get the replaced entity
   replaced = await table.get_entity(partition_key=created["PartitionKey"], row_key=created["RowKey"])
   print("Replaced entity: {}".format(replaced))

   # Merge the entity
   replaced["color"] = "Blue"
   await table.update_entity(mode=UpdateMode.MERGE, entity=replaced)

   # Get the merged entity
   merged = await table.get_entity(partition_key=replaced["PartitionKey"], row_key=replaced["RowKey"])
   print("Merged entity: {}".format(merged))

upsert_entity

更新/合併或插入實體至資料表。

async upsert_entity(entity: TableEntity | Mapping[str, Any], mode: str | UpdateMode = UpdateMode.MERGE, **kwargs) -> Mapping[str, Any]

參數

entity: TableEntity 或 dict[str, Any]

必要

資料表實體的屬性。

mode: UpdateMode

必要

合併或取代實體

傳回

從服務傳回的字典對應作業中繼資料

傳回類型

dict[str, Any]

例外狀況

HttpResponseError

範例

更新/合併或將實體插入資料表


   # Try Replace and insert on fail
   insert_entity = await table.upsert_entity(mode=UpdateMode.REPLACE, entity=entity1)
   print("Inserted entity: {}".format(insert_entity))

   created["text"] = "NewMarker"
   merged_entity = await table.upsert_entity(mode=UpdateMode.MERGE, entity=entity)
   print("Merged entity: {}".format(merged_entity))

屬性

api_version

用於要求的儲存體 API 版本。

傳回

儲存體 API 版本。

url

此實體的完整端點 URL，包括使用 SAS 權杖。

這可能是主要端點或次要端點，視目前的 <xref:azure.data.tables.aio.location_mode> 而定。

傳回

使用時包含 SAS 權杖的完整端點 URL。

傳回類型

str

共用方式為

TableClient 類別

建構函式

參數

變數

方法

close

create_entity

參數

傳回

傳回類型

例外狀況

範例

create_table

傳回

傳回類型

例外狀況

delete_entity

參數

傳回

例外狀況

範例

delete_table

傳回

例外狀況

範例

from_connection_string

參數

傳回

傳回類型

範例

from_table_url

參數

傳回

傳回類型

get_entity

參數

傳回

傳回類型

例外狀況

範例

get_table_access_policy

傳回

傳回類型

例外狀況

list_entities

參數

傳回

傳回類型

例外狀況

範例

query_entities

參數

傳回

傳回類型

例外狀況

範例

set_table_access_policy

參數

傳回

例外狀況

submit_transaction

參數

傳回

傳回類型

例外狀況

範例

update_entity

參數

傳回

傳回類型

例外狀況

範例

upsert_entity

參數

傳回

傳回類型

例外狀況

範例

屬性