Compartir a través de

Biblioteca cliente de Azure Tables para Python: versión 12.4.4

  • Artículo

Azure Tables es un servicio de almacenamiento de datos NoSQL al que se puede acceder desde cualquier lugar del mundo a través de llamadas autenticadas mediante HTTP o HTTPS. Las tablas se escalan según sea necesario para admitir la cantidad de datos insertados y permiten el almacenamiento de datos con acceso no complejo. El cliente de Azure Tables se puede usar para acceder a cuentas de Azure Storage o Cosmos. En este documento se trata azure-data-tables.

Tenga en cuenta que este paquete es un reemplazo para azure-cosmosdb-tables el que ahora está en desuso. Consulte la guía de migración para obtener más detalles.

Código | fuentePaquete (PyPI) | Paquete (Conda) | Documentación | de referencia de APIMuestras

Declinación de responsabilidades

Los paquetes de Python del SDK de Azure para Python 2.7 finalizaron el 01 de enero de 2022. Para obtener más información y preguntas, consulte https://github.com/Azure/azure-sdk-for-python/issues/20691Python 3.7 o posterior para usar este paquete. Para más información, consulte la directiva de compatibilidad con la versión de Azure SDK para Python.

Introducción

El SDK de Azure Tables puede acceder a una cuenta de Azure Storage o CosmosDB.

Requisitos previos

Creación de cuenta

Instalar el paquete

Instale la biblioteca cliente de Azure Tables para Python con pip:

pip install azure-data-tables

Creación del cliente

La biblioteca de tablas de Azure permite interactuar con dos tipos de recursos:

  • las tablas de la cuenta
  • las entidades de esas tablas. La interacción con estos recursos comienza con una instancia de un cliente. Para crear un objeto de cliente, necesitará la dirección URL del punto de conexión de Table Service de la cuenta y una credencial que le permita acceder a la cuenta. endpoint Puede encontrarse en la página de la cuenta de almacenamiento en Azure Portal, en la sección "Claves de acceso" o ejecutando el siguiente comando de la CLI de Azure:
# Get the table service URL for the account
az storage account show -n mystorageaccount -g MyResourceGroup --query "primaryEndpoints.table"

Una vez que tenga la dirección URL de la cuenta, se puede usar para crear el cliente de servicio:

from azure.data.tables import TableServiceClient
service = TableServiceClient(endpoint="https://<my_account_name>.table.core.windows.net/", credential=credential)

Para más información sobre las direcciones URL de Table Service y cómo configurar nombres de dominio personalizados para Azure Storage, consulte la documentación oficial.

Tipos de credenciales

El credential parámetro puede proporcionarse en varios formularios diferentes, según el tipo de autorización que desee usar. La biblioteca Tables admite las siguientes autorizaciones:

  • Clave compartida
  • Cadena de conexión
  • Token de firma de acceso compartido
Creación del cliente a partir de una clave compartida

Para usar una clave compartida de cuenta (también conocida como clave de cuenta o clave de acceso), proporcione la clave como una cadena. Esto se puede encontrar en la cuenta de almacenamiento en Azure Portal en la sección "Claves de acceso" o ejecutando el siguiente comando de la CLI de Azure:

az storage account keys list -g MyResourceGroup -n MyStorageAccount

Use la clave como parámetro de credencial para autenticar el cliente:

from azure.core.credentials import AzureNamedKeyCredential
from azure.data.tables import TableServiceClient

credential = AzureNamedKeyCredential("my_account_name", "my_access_key")

service = TableServiceClient(endpoint="https://<my_account_name>.table.core.windows.net", credential=credential)
Creación del cliente a partir de una cadena de conexión

Según el caso de uso y el método de autorización, es posible que prefiera inicializar una instancia de cliente con una cadena de conexión en lugar de proporcionar la dirección URL de la cuenta y las credenciales por separado. Para ello, pase la cadena de conexión al método de clase del from_connection_string cliente. La cadena de conexión se puede encontrar en la cuenta de almacenamiento en Azure Portal , en la sección "Claves de acceso" o con el siguiente comando de la CLI de Azure:

az storage account show-connection-string -g MyResourceGroup -n MyStorageAccount

from azure.data.tables import TableServiceClient
connection_string = "DefaultEndpointsProtocol=https;AccountName=<my_account_name>;AccountKey=<my_account_key>;EndpointSuffix=core.windows.net"
service = TableServiceClient.from_connection_string(conn_str=connection_string)
Creación del cliente a partir de un token de SAS

Para usar un token de firma de acceso compartido (SAS), proporcione el token como una cadena. Si la dirección URL de la cuenta incluye el token de SAS, omita el parámetro de credencial. Puede generar un token de SAS desde Azure Portal en Firma de acceso compartido o usar una de las generate_*_sas() funciones para crear un token sas para la cuenta o tabla:

from datetime import datetime, timedelta
from azure.data.tables import TableServiceClient, generate_account_sas, ResourceTypes, AccountSasPermissions
from azure.core.credentials import AzureNamedKeyCredential, AzureSasCredential

credential = AzureNamedKeyCredential("my_account_name", "my_access_key")
sas_token = generate_account_sas(
    credential,
    resource_types=ResourceTypes(service=True),
    permission=AccountSasPermissions(read=True),
    expiry=datetime.utcnow() + timedelta(hours=1),
)

table_service_client = TableServiceClient(endpoint="https://<my_account_name>.table.core.windows.net", credential=AzureSasCredential(sas_token))

Conceptos clave

Usos comunes de Table service incluidos:

  • Almacenamiento de TB de datos estructurados capaces de ofrecer servicio a aplicaciones de escalado web
  • Almacenamiento de conjuntos de datos que no requieren combinaciones complejas, claves externas o procedimientos almacenados y se pueden des normalizar para un acceso rápido
  • Consulta rápida de datos mediante un índice agrupado
  • Acceso a datos mediante el protocolo OData y expresiones de filtro LINQ

Los siguientes componentes componen el servicio Azure Tables:

  • La cuenta
  • Una tabla dentro de la cuenta, que contiene un conjunto de entidades
  • Una entidad dentro de una tabla, como diccionario

La biblioteca cliente de Azure Tables para Python permite interactuar con cada uno de estos componentes mediante el uso de un objeto de cliente dedicado.

Clientes

Se proporcionan dos clientes diferentes para interactuar con los distintos componentes de Table Service:

  1. TableServiceClient -
    • Obtener y establecer la configuración de la cuenta
    • Consulte, cree y elimine tablas dentro de la cuenta.
    • Obtenga para TableClient obtener acceso a una tabla específica mediante el get_table_client método .
  2. TableClient -
    • Interactúa con una tabla específica (que aún no es necesario).
    • Cree, elimine, consulte y upsert las entidades dentro de la tabla especificada.
    • Cree o elimine la propia tabla especificada.

Entities

Las entidades son similares a las filas. Una entidad tiene un PartitionKeyobjeto , y RowKeyun conjunto de propiedades. Una propiedad es un par de valores de nombre, similar a una columna. Cada entidad de una tabla no necesita tener las mismas propiedades. Las entidades se pueden representar como diccionarios como este como ejemplo:

entity = {
    'PartitionKey': 'color',
    'RowKey': 'brand',
    'text': 'Marker',
    'color': 'Purple',
    'price': '5'
}
  • create_entity : agregue una entidad a la tabla.
  • delete_entity : elimine una entidad de la tabla.
  • update_entity : actualice la información de una entidad combinando o reemplazando la entidad existente.
    • UpdateMode.MERGE agregará nuevas propiedades a una entidad existente que no eliminará las propiedades existentes.
    • UpdateMode.REPLACE reemplazará la entidad existente por la especificada, eliminando las propiedades existentes que no se incluyan en la entidad enviada.
  • query_entities : consulte las entidades existentes en una tabla mediante filtros OData.
  • get_entity : obtenga una entidad específica de una tabla por partición y clave de fila.
  • upsert_entity : combina o reemplaza una entidad en una tabla, o si la entidad no existe, inserta la entidad.
    • UpdateMode.MERGE agregará nuevas propiedades a una entidad existente que no eliminará las propiedades existentes.
    • UpdateMode.REPLACE reemplazará la entidad existente por la especificada, eliminando las propiedades existentes que no se incluyan en la entidad enviada.

Ejemplos

En las secciones siguientes se proporcionan varios fragmentos de código que abarcan algunas de las tareas de tabla más comunes, entre las que se incluyen:

Creación de una tabla

Cree una tabla en su cuenta y obtenga un TableClient para realizar operaciones en la tabla recién creada:

from azure.data.tables import TableServiceClient
table_service_client = TableServiceClient.from_connection_string(conn_str="<connection_string>")
table_name = "myTable"
table_client = table_service_client.create_table(table_name=table_name)

Creación de entidades

Cree entidades en la tabla:

from azure.data.tables import TableServiceClient
from datetime import datetime

PRODUCT_ID = u'001234'
PRODUCT_NAME = u'RedMarker'

my_entity = {
    u'PartitionKey': PRODUCT_NAME,
    u'RowKey': PRODUCT_ID,
    u'Stock': 15,
    u'Price': 9.99,
    u'Comments': u"great product",
    u'OnSale': True,
    u'ReducedPrice': 7.99,
    u'PurchaseDate': datetime(1973, 10, 4),
    u'BinaryRepresentation': b'product_name'
}

table_service_client = TableServiceClient.from_connection_string(conn_str="<connection_string>")
table_client = table_service_client.get_table_client(table_name="myTable")

entity = table_client.create_entity(entity=my_entity)

Consulta de entidades

Consulta de entidades en la tabla:

from azure.data.tables import TableClient
my_filter = "PartitionKey eq 'RedMarker'"
table_client = TableClient.from_connection_string(conn_str="<connection_string>", table_name="myTable")
entities = table_client.query_entities(my_filter)
for entity in entities:
    for key in entity.keys():
        print("Key: {}, Value: {}".format(key, entity[key]))

Configuración opcional

Los argumentos de palabra clave opcionales se pueden pasar en el nivel de cliente y por operación. En la documentación de referencia de azure-core se describen las configuraciones disponibles para reintentos, registro, protocolos de transporte, etc.

Configuración de la directiva de reintento

Use los argumentos de palabra clave siguientes al crear una instancia de un cliente para configurar la directiva de reintento:

  • retry_total (int): número total de reintentos que se van a permitir. Tiene prioridad sobre otros recuentos. retry_total=0 Pase si no desea volver a intentarlo en las solicitudes. El valor predeterminado es 10.
  • retry_connect (int): cuántos errores relacionados con la conexión se reintentan. El valor predeterminado es 3.
  • retry_read (int): cuántas veces se reintenta en los errores de lectura. El valor predeterminado es 3.
  • retry_status (int): cuántas veces se reintenta en códigos de estado incorrectos. El valor predeterminado es 3.
  • retry_to_secondary (bool): indica si la solicitud se debe reintentar en la secundaria, si es posible. Esto solo debe habilitarse en las cuentas de RA-GRS y se pueden controlar los datos potencialmente obsoletos. Su valor predeterminado es False.

Otra configuración de cliente o por operación

Otros argumentos de palabra clave de configuración opcionales que se pueden especificar en el cliente o por operación.

Argumentos de palabra clave de cliente:

  • connection_timeout (int): opcionalmente, establece el valor de tiempo de espera de conexión y lectura, en segundos.
  • transport (Any): transporte proporcionado por el usuario para enviar la solicitud HTTP.

Argumentos de palabra clave por operación:

  • raw_response_hook (invocable): la devolución de llamada especificada usa la respuesta devuelta desde el servicio.
  • raw_request_hook (invocable): la devolución de llamada especificada usa la solicitud antes de enviarse al servicio.
  • client_request_id (str): el usuario opcional especificó la identificación de la solicitud.
  • user_agent (str): anexa el valor personalizado al encabezado user-agent que se enviará con la solicitud.
  • logging_enable (bool): habilita el registro en el nivel DEBUG. El valor predeterminado es False. También se puede pasar en el nivel de cliente para habilitarlo para todas las solicitudes.
  • encabezados (dict): pase encabezados personalizados como pares clave y valor. Por ejemplo headers={'CustomValue': value}

Solución de problemas

General

Los clientes de Azure Tables generan excepciones definidas en Azure Core. Al interactuar con la biblioteca de tablas de Azure mediante el SDK de Python, los errores devueltos por el servicio responden ot los mismos códigos de estado HTTP para las solicitudes de la API REST . Las operaciones de Table service producirán un HttpResponseError error con códigos de error útiles.

Por ejemplo, si intenta crear una tabla que ya existe, se devuelve un 409 error que indica "Conflicto".

from azure.data.tables import TableServiceClient
from azure.core.exceptions import HttpResponseError
table_name = 'YourTableName'

service_client = TableServiceClient.from_connection_string(connection_string)

# Create the table if it does not already exist
tc = service_client.create_table_if_not_exists(table_name)

try:
    service_client.create_table(table_name)
except HttpResponseError:
    print("Table with name {} already exists".format(table_name))

Registro

Esta biblioteca usa la biblioteca de registro estándar para el registro. La información básica sobre las sesiones HTTP (direcciones URL, encabezados, etc.) se registra en el nivel INFO.

El registro detallado de nivel DEBUG, incluidos los cuerpos de solicitud/respuesta y los encabezados no aprobados, se puede habilitar en un cliente con el logging_enable argumento :

import sys
import logging
from azure.data.tables import TableServiceClient
# Create a logger for the 'azure' SDK
logger = logging.getLogger('azure')
logger.setLevel(logging.DEBUG)

# Configure a console output
handler = logging.StreamHandler(stream=sys.stdout)
logger.addHandler(handler)

# This client will log detailed information about its HTTP sessions, at DEBUG level
service_client = TableServiceClient.from_connection_string("your_connection_string", logging_enable=True)

Del mismo modo, logging_enable puede habilitar el registro detallado para una sola operación, incluso cuando no está habilitado para el cliente:

service_client.create_entity(entity=my_entity, logging_enable=True)

Pasos siguientes

Empiece a trabajar con nuestros ejemplos de table.

Hay disponibles varios ejemplos del SDK de Python de Tablas de Azure en el repositorio de GitHub del SDK. Estos ejemplos proporcionan código de ejemplo para escenarios adicionales que se suelen encontrar al trabajar con tablas.

Escenarios comunes

Estos ejemplos de código muestran operaciones de escenario comunes con la biblioteca cliente de Azure Tables. Las versiones asincrónicas de los ejemplos (los archivos de ejemplo de Python anexados con _async) muestran operaciones asincrónicas.

Documentación adicional

Para obtener documentación más amplia sobre tablas de Azure, consulte la documentación de Azure Tables sobre docs.microsoft.com.

Problemas conocidos

Puede encontrar una lista de problemas conocidos actualmente relacionados con los puntos de conexión de tabla de Cosmos DB aquí.

Contribuciones

Este proyecto agradece las contribuciones y sugerencias. La mayoría de las contribuciones requieren que acepte un Contrato de licencia para el colaborador (CLA) que declara que tiene el derecho a concedernos y nos concede los derechos para usar su contribución. Para más detalles, visite https://cla.microsoft.com.

Cuando se envía una solicitud de incorporación de cambios, un bot de CLA determinará de forma automática si tiene que aportar un CLA y completar la PR adecuadamente (por ejemplo, la etiqueta, el comentario). Solo siga las instrucciones que le dará el bot. Solo será necesario que lo haga una vez en todos los repositorios con nuestro CLA.

Este proyecto ha adoptado el Código de conducta de Microsoft Open Source. Para más información, consulte las preguntas más frecuentes del código de conducta o póngase en contacto con opencode@microsoft.com si tiene cualquier otra pregunta o comentario.

Impresiones