你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

TableClient 类

用于与 Azure 表帐户中的特定表交互的客户端。

从凭据创建 TableClient。

继承

azure.data.tables._base_client.TablesBaseClient

TableClient

构造函数

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

参数

endpoint

str

必需

Azure 表帐户的 URL。

table_name

str

必需

表名称。

credential

AzureNamedKeyCredential 或 AzureSasCredential 或 TokenCredential 或 None

用于进行身份验证的凭据。 如果帐户 URL 已具有 SAS 令牌，则这是可选的。 该值可以是 AzureNamedKeyCredential (azure-core) 、AzureSasCredential (azure-core) 或 azure-identity 中的 TokenCredential 实现之一。

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	要与特定表交互的客户端。 AzureSasCredential (azure-core) ，或 azure-identity 中的 TokenCredential 实现。 :p aramtype 凭据： ~azure.core.credentials.AzureNamedKeyCredential 或 ~azure.core.credentials.AzureSasCredential 或 None
get_entity	获取表中的单个实体。
get_table_access_policy	检索有关表上指定的任何可能与共享访问签名一起使用的存储访问策略的详细信息。
list_entities	列出表中的实体。
query_entities	列出表中的实体。
set_table_access_policy	为可与共享访问签名一起使用的表设置存储访问策略。
submit_transaction	将操作列表作为单个事务提交。 如果其中任一操作失败，则会拒绝整个事务。
update_entity	更新表中的实体。
upsert_entity	更新/合并实体或将实体插入表中。

close

此方法用于关闭客户端打开的套接字。 与上下文管理器一起使用时，不需要使用它。

close() -> None

create_entity

在表中插入实体。

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

参数

entity

Union[TableEntity, Mapping[str, Any]]

必需

表实体的属性。

返回

从服务返回的字典映射操作元数据

返回类型

dict[str, Any]

例外

HttpResponseError

示例

创建实体并将其添加到表

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

create_table

在当前帐户下创建新表。

create_table(**kwargs) -> TableItem

返回

一个 TableItem，表示创建的表。

返回类型

TableItem

例外

ResourceExistsError

如果实体已存在

示例

从 TableClient 对象创建表

   with TableClient.from_connection_string(
       conn_str=self.connection_string, table_name=self.table_name
   ) as table_client:
       try:
           table_item = table_client.create_table()
           print("Created table {}!".format(table_item.name))
       except ResourceExistsError:
           print("Table already exists")

delete_entity

删除表中的指定实体。 如果未找到实体或 PartitionKey-RowKey 配对，则不会引发错误。

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.Unconditionally。 默认值为“无条件”。

返回

无

例外

HttpResponseError

示例

删除表的实体

   table_client.delete_entity(row_key=self.entity["RowKey"], partition_key=self.entity["PartitionKey"])
   print("Successfully deleted!")

delete_table

删除当前帐户下的表。 如果表不存在，则不会引发错误

delete_table(**kwargs) -> None

返回

无

例外

HttpResponseError

示例

从 TableClient 对象中删除表

   with TableClient.from_connection_string(
       conn_str=self.connection_string, table_name=self.table_name
   ) as table_client:
       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

示例

从connection_string对 TableServiceClient 进行身份验证

   from azure.data.tables import TableClient

   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

要与特定表交互的客户端。

AzureSasCredential (azure-core) ，或 azure-identity 中的 TokenCredential 实现。 :p aramtype 凭据：

~azure.core.credentials.AzureNamedKeyCredential 或 ~azure.core.credentials.AzureSasCredential 或 None

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

参数

table_url

必需

返回

表客户端。

返回类型

TableClient

get_entity

获取表中的单个实体。

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

参数

partition_key

str

必需

实体的分区键。

row_key

str

必需

实体的行键。

select

str 或 list[str]

指定要返回的实体的所需属性。

返回

从服务返回的字典映射操作元数据

返回类型

TableEntity

例外

HttpResponseError

示例

从表中获取单个实体

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

get_table_access_policy

检索有关表上指定的任何可能与共享访问签名一起使用的存储访问策略的详细信息。

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

返回

SignedIdentifiers 字典

返回类型

dict[str, TableAccessPolicy],

dict[str, None]

例外

HttpResponseError

list_entities

列出表中的实体。

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

参数

results_per_page

int

每个服务请求返回的实体数。

select

str 或 list[str]

指定要返回的实体的所需属性。

返回

的迭代器 TableEntity

返回类型

ItemPaged[TableEntity]

例外

HttpResponseError

示例

列出表内保存的所有实体

   # Query the entities in the table
   entities = list(table.list_entities())
   for i, entity in enumerate(entities):
       print("Entity #{}: {}".format(entity, i))

query_entities

列出表中的实体。

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

参数

query_filter

str

必需

指定筛选器以返回某些实体。 有关筛选器格式的详细信息，请参阅 示例文档。

results_per_page

int

每个服务请求返回的实体数。

select

str 或 list[str]

指定要返回的实体的所需属性。

parameters

dict[str, Any]

使用用户定义的其他参数设置查询格式的字典

返回

的迭代器 TableEntity

返回类型

ItemPaged[TableEntity]

例外

HttpResponseError

示例

查询表中保存的实体

   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
           )

           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
           )
           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
           )
           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
           )
           for entity_chosen in queried_entities:
               print(entity_chosen)
       except HttpResponseError as e:
           raise

set_table_access_policy

为可与共享访问签名一起使用的表设置存储访问策略。

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

参数

signed_identifiers

dict[str, TableAccessPolicy] 或 dict[str, None]

必需

要为表设置的访问策略

返回

无

例外

HttpResponseError

submit_transaction

将操作列表作为单个事务提交。

如果其中任一操作失败，则会拒绝整个事务。

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

参数

operations

Iterable[Tuple[str, TableEntity, Mapping[str, Any]]]

必需

在事务中要提交的操作的列表。 这应该是一个可迭代的元组，其中包含一个操作名称、要在其上操作的实体，以及该操作的附加 kwargs（可选）的听写。 例如：

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

返回

包含事务中每个操作的响应元数据的映射列表。

返回类型

list[Mapping[str, Any]]

例外

TableTransactionError

示例

使用事务一次发送多个请求

   from azure.data.tables import TableClient, 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:
       self.table_client.create_table()
       print("Created table")
   except ResourceExistsError:
       print("Table already exists")

   self.table_client.upsert_entity(entity2)
   self.table_client.upsert_entity(entity3)
   self.table_client.upsert_entity(entity4)

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

update_entity

更新表中的实体。

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

参数

entity

TableEntity 或 dict[str, Any]

必需

表实体的属性。

mode

UpdateMode

必需

合并或替换实体

etag

str

实体的 Etag

match_condition

MatchConditions

执行操作的条件。 支持的值包括：MatchConditions.IfNotModified、MatchConditions.Unconditionally。 默认值为“无条件”。

返回

从服务返回的字典映射操作元数据

返回类型

dict[str, Any]

例外

HttpResponseError

示例

更新表中已退出的实体

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

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

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

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

upsert_entity

更新/合并实体或将实体插入表中。

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

参数

entity

TableEntity 或 dict[str, Any]

必需

表实体的属性。

mode

UpdateMode

必需

合并或替换实体

返回

从服务返回的字典映射操作元数据

返回类型

dict[str, Any]

例外

HttpResponseError

示例

更新/合并实体或将实体插入表中

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

   created["text"] = "NewMarker"
   merged_entity = 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.location_mode>。

返回

完整的终结点 URL，包括 SAS 令牌（如果使用）。

返回类型

str