Partager via

Bibliothèque cliente Azure Tables pour Python - version 12.4.4

  • Article

Azure Tables est un service de stockage de données NoSQL accessible depuis n’importe où dans le monde via des appels authentifiés à l’aide de HTTP ou HTTPS. Les tables sont mises à l’échelle en fonction des besoins pour prendre en charge la quantité de données insérées et permettre le stockage des données avec un accès non complexe. Le client Tables Azure peut être utilisé pour accéder aux comptes Stockage Azure ou Cosmos. Ce document couvre azure-data-tables.

Notez que ce package est un remplacement pour azure-cosmosdb-tables lequel est désormais déconseillé. Pour plus d’informations, consultez le guide de migration .

| Code sourcePackage (PyPI) | Package (Conda) | Documentation de référence sur les | APIÉchantillons

Clause d’exclusion de responsabilité

La prise en charge des packages Python du SDK Azure pour Python 2.7 a pris fin le 1er janvier 2022. Pour plus d’informations et de questions, reportez-vous à https://github.com/Azure/azure-sdk-for-python/issues/20691Python 3.7 ou version ultérieure nécessaire pour utiliser ce package. Pour plus d’informations, reportez-vous à la stratégie de prise en charge des versions du Kit de développement logiciel (SDK) Azure pour Python.

Prise en main

Le Kit de développement logiciel (SDK) Tables Azure peut accéder à un compte Stockage Azure ou CosmosDB.

Prérequis

Créer un compte

Installer le package

Installez la bibliothèque cliente Azure Tables pour Python avec pip :

pip install azure-data-tables

Création du client

La bibliothèque Tables Azure vous permet d’interagir avec deux types de ressources :

  • les tables de votre compte
  • entités au sein de ces tables. L’interaction avec ces ressources commence par une instance d’un client. Pour créer un objet client, vous aurez besoin de l’URL du point de terminaison de service de table du compte et d’informations d’identification qui vous permettent d’accéder au compte. endpoint Le se trouve sur la page de votre compte de stockage dans le portail Azure sous la section « Clés d’accès » ou en exécutant la commande Azure CLI suivante :
# Get the table service URL for the account
az storage account show -n mystorageaccount -g MyResourceGroup --query "primaryEndpoints.table"

Une fois que vous avez l’URL du compte, vous pouvez l’utiliser pour créer le client de service :

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

Pour plus d’informations sur les URL du service de table et sur la configuration de noms de domaine personnalisés pour Stockage Azure case activée la documentation officielle

Types d’informations d’identification

Le credential paramètre peut être fourni sous plusieurs formes différentes, selon le type d’autorisation que vous souhaitez utiliser. La bibliothèque Tables prend en charge les autorisations suivantes :

  • Clé partagée
  • Chaîne de connexion
  • Jeton de signature d’accès partagé
Création du client à partir d’une clé partagée

Pour utiliser une clé partagée de compte (également appelée clé de compte ou clé d’accès), fournissez la clé sous forme de chaîne. Vous pouvez le trouver dans votre compte de stockage dans le portail Azure sous la section « Clés d’accès » ou en exécutant la commande Azure CLI suivante :

az storage account keys list -g MyResourceGroup -n MyStorageAccount

Utilisez la clé comme paramètre d’informations d’identification pour authentifier le client :

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)
Création du client à partir d’une chaîne de connexion

En fonction de votre cas d’usage et de votre méthode d’autorisation, vous pouvez préférer initialiser un instance client avec une chaîne de connexion au lieu de fournir l’URL et les informations d’identification du compte séparément. Pour ce faire, transmettez la chaîne de connexion à la méthode de classe du from_connection_string client. La chaîne de connexion se trouve dans votre compte de stockage dans le portail Azure , sous la section « Clés d’accès » ou avec la commande Azure CLI suivante :

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)
Création du client à partir d’un jeton SAP

Pour utiliser un jeton de signature d’accès partagé (SAP), fournissez le jeton sous forme de chaîne. Si l’URL de votre compte inclut le jeton SAS, omettez le paramètre des informations d’identification. Vous pouvez générer un jeton SAP à partir du portail Azure sous Signature d’accès partagé ou utiliser l’une generate_*_sas() des fonctions pour créer un jeton sap pour le compte ou la table :

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))

Concepts clés

Les utilisations courantes du service Table sont les suivantes :

  • Stockage des téraoctets de données structurées capables de servir des applications Web
  • Stockage de jeux de données qui ne nécessitent pas de jointures complexes, de clés étrangères ou de procédures stockées et qui peuvent être dénormalisés pour un accès rapide
  • Interrogation rapide des données par requête à l’aide d’un index cluster
  • Accès aux données à l’aide du protocole OData et des expressions de filtre LINQ

Les composants suivants composent le service Tables Azure :

  • Compte
  • Table dans le compte, qui contient un ensemble d’entités
  • Entité au sein d’une table, en tant que dictionnaire

La bibliothèque cliente Azure Tables pour Python vous permet d’interagir avec chacun de ces composants via l’utilisation d’un objet client dédié.

Clients

Deux clients différents sont fournis pour interagir avec les différents composants du service de table :

  1. TableServiceClient -
    • Obtenir et définir le paramètre de compte
    • Interroger, créer et supprimer des tables dans le compte.
    • Obtenez un TableClient pour accéder à une table spécifique à l’aide de la get_table_client méthode .
  2. TableClient -
    • Interagit avec une table spécifique (qui n’a pas besoin d’exister encore).
    • Créez, supprimez, interrogez et upsert des entités dans la table spécifiée.
    • Créez ou supprimez la table spécifiée elle-même.

Entities

Les entités sont similaires aux lignes. Une entité a un PartitionKey, un RowKeyet un ensemble de propriétés. Une propriété est une paire de valeur de nom, similaire à une colonne. Chaque entité d’une table n’a pas besoin d’avoir les mêmes propriétés. Les entités peuvent être représentées sous la forme de dictionnaires comme ceci à titre d’exemple :

entity = {
    'PartitionKey': 'color',
    'RowKey': 'brand',
    'text': 'Marker',
    'color': 'Purple',
    'price': '5'
}
  • create_entity : ajoutez une entité à la table.
  • delete_entity : supprime une entité de la table.
  • update_entity : Mettez à jour les informations d’une entité en fusionnant ou en remplaçant l’entité existante.
    • UpdateMode.MERGE ajoutera de nouvelles propriétés à une entité existante, il ne supprimera pas de propriétés existantes
    • UpdateMode.REPLACE remplace l’entité existante par l’entité donnée, en supprimant toutes les propriétés existantes qui ne sont pas incluses dans l’entité soumise
  • query_entities : interroger des entités existantes dans une table à l’aide de filtres OData.
  • get_entity : obtenir une entité spécifique à partir d’une table par partition et clé de ligne.
  • upsert_entity - Fusionner ou remplacer une entité dans une table, ou, si l’entité n’existe pas, insère l’entité.
    • UpdateMode.MERGE ajoutera de nouvelles propriétés à une entité existante, il ne supprimera pas de propriétés existantes
    • UpdateMode.REPLACE remplace l’entité existante par l’entité donnée, en supprimant toutes les propriétés existantes qui ne sont pas incluses dans l’entité soumise

Exemples

Les sections suivantes fournissent plusieurs extraits de code couvrant certaines des tâches table les plus courantes, notamment :

Création d’une table

Créez une table dans votre compte et obtenez un pour effectuer des TableClient opérations sur la table nouvellement créée :

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)

Créer des entités

Créez des entités dans la table :

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)

Exécution d’une requête sur les entités

Interrogation des entités dans la table :

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]))

Configuration facultative

Les arguments facultatifs mot clé peuvent être transmis au niveau du client et par opération. La documentation de référence azure-core décrit les configurations disponibles pour les nouvelles tentatives, la journalisation, les protocoles de transport, etc.

Configuration de la stratégie de nouvelle tentative

Utilisez les arguments mot clé suivants lors de l’instanciation d’un client pour configurer la stratégie de nouvelle tentative :

  • retry_total (int) : nombre total de nouvelles tentatives à autoriser. Est prioritaire sur d’autres nombres. Transmettez retry_total=0 si vous ne souhaitez pas réessayer sur les demandes. La valeur par défaut est 10.
  • retry_connect (int) : nombre d’erreurs liées à la connexion à retenter. La valeur par défaut est 3.
  • retry_read (int) : nombre de nouvelles tentatives en cas d’erreurs de lecture. La valeur par défaut est 3.
  • retry_status (int) : nombre de nouvelles tentatives sur des codes de status incorrects. La valeur par défaut est 3.
  • retry_to_secondary (bool) : indique si la demande doit être retentée au niveau secondaire, si possible. Cela ne doit être activé que si les comptes RA-GRS sont utilisés et que les données potentiellement obsolètes peuvent être gérées. La valeur par défaut est False.

Autre configuration client/ par opération

D’autres configurations facultatives mot clé arguments qui peuvent être spécifiés sur le client ou par opération.

Arguments de mot clé client :

  • connection_timeout (int) : définit éventuellement la valeur de délai d’attente de connexion et de lecture, en secondes.
  • transport (Any) : transport fourni par l’utilisateur pour envoyer la requête HTTP.

Arguments de mot clé par opération :

  • raw_response_hook (appelable) : le rappel donné utilise la réponse retournée par le service.
  • raw_request_hook (appelable) : le rappel donné utilise la requête avant d’être envoyé au service.
  • client_request_id (str) : identification facultative spécifiée par l’utilisateur de la demande.
  • user_agent (str) : ajoute la valeur personnalisée à l’en-tête user-agent à envoyer avec la demande.
  • logging_enable (bool) : active la journalisation au niveau DEBUG. Valeur par défaut False. Peut également être transmis au niveau du client pour l’activer pour toutes les demandes.
  • en-têtes (dict) : passez des en-têtes personnalisés en tant que paires de clés et de valeurs. Par exemple, headers={'CustomValue': value}

Dépannage

Général

Les clients Tables Azure déclenchent des exceptions définies dans Azure Core. Lorsque vous interagissez avec la bibliothèque de tables Azure à l’aide du Kit de développement logiciel (SDK) Python, les erreurs retournées par le service répondent aux mêmes codes status HTTP pour les demandes d’API REST. Les opérations du service Table lèvent un en cas d’échec HttpResponseError avec des codes d’erreur utiles.

Par exemple, si vous essayez de créer une table qui existe déjà, une 409 erreur est renvoyée indiquant « Conflit ».

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))

Journalisation

Cette bibliothèque utilise la bibliothèque de journalisation standard pour la journalisation. Les informations de base sur les sessions HTTP (URL, en-têtes, etc.) sont enregistrées au niveau INFO.

La journalisation détaillée au niveau DEBUG, y compris les corps de requête/réponse et les en-têtes non expurgés, peut être activée sur un client avec l’argument logging_enable :

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)

De même, logging_enable peut activer la journalisation détaillée pour une seule opération, même si elle n’est pas activée pour le client :

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

Étapes suivantes

Prise en main de nos exemples de table.

Plusieurs exemples de KIT de développement logiciel (SDK) Python Azure Tables sont disponibles dans le dépôt GitHub du SDK. Ces exemples fournissent un exemple de code pour d’autres scénarios couramment rencontrés lors de l’utilisation de tables.

Scénarios courants

Ces exemples de code illustrent les opérations de scénario courantes avec la bibliothèque cliente Tables Azure. Les versions asynchrones des exemples (les exemples de fichiers Python ajoutés avec _async) affichent les opérations asynchrones.

Documentation complémentaire

Pour obtenir une documentation plus complète sur les tables Azure, consultez la documentation sur les tables Azure sur docs.microsoft.com.

Problèmes connus

Vous trouverez ici la liste des problèmes actuellement connus liés aux points de terminaison de table Cosmos DB.

Contribution

Ce projet accepte les contributions et les suggestions. La plupart des contributions vous demandent d’accepter un contrat de licence de contribution (CLA) déclarant que vous avez le droit de nous accorder, et que vous nous accordez réellement, les droits d’utilisation de votre contribution. Pour plus d’informations, visitez https://cla.microsoft.com.

Quand vous envoyez une demande de tirage (pull request), un bot CLA détermine automatiquement si vous devez fournir un contrat CLA et agrémenter la demande de tirage de façon appropriée (par exemple, avec une étiquette ou un commentaire). Suivez simplement les instructions fournies par le bot. Vous ne devez effectuer cette opération qu’une seule fois sur tous les dépôts utilisant notre contrat CLA.

Ce projet a adopté le Code de conduite Open Source de Microsoft. Pour plus d’informations, consultez les Questions fréquentes (FAQ) sur le code de conduite ou envoyez vos questions ou vos commentaires à opencode@microsoft.com.

Impressions