Share via

Azure Tables-klientbibliotek för Python – version 12.4.4

  • Artikel

Azure Tables är en NoSQL-datalagringstjänst som kan nås var som helst i världen via autentiserade anrop med HTTP eller HTTPS. Tabeller skalar efter behov för att stödja mängden data som infogas och möjliggör lagring av data med icke-komplex åtkomst. Azure Tables-klienten kan användas för att komma åt Azure Storage- eller Cosmos-konton. Det här dokumentet beskriver azure-data-tables.

Observera att det här paketet är en ersättning azure-cosmosdb-tables som nu är inaktuell. Mer information finns i migreringsguiden .

| KällkodPaket (PyPI) | Paket (Conda) | API-referensdokumentation | Prover

Friskrivning

Stöd för Azure SDK Python-paket för Python 2.7 upphörde den 1 januari 2022. Mer information och frågor finns i https://github.com/Azure/azure-sdk-for-python/issues/20691Python 3.7 eller senare som krävs för att använda det här paketet. Mer information finns i Supportprincip för Azure SDK för Python-version.

Komma igång

Azure Tables SDK har åtkomst till ett Azure Storage- eller CosmosDB-konto.

Förutsättningar

Skapa ett konto

Installera paketet

Installera Azure Tables-klientbiblioteket för Python med pip:

pip install azure-data-tables

Skapa klienten

Med Azure Tables-biblioteket kan du interagera med två typer av resurser:

  • tabellerna i ditt konto
  • entiteterna i dessa tabeller. Interaktionen med dessa resurser börjar med en instans av en klient. Om du vill skapa ett klientobjekt behöver du kontots tabelltjänstslutpunkts-URL och en autentiseringsuppgift som gör att du kan komma åt kontot. endpoint Finns på sidan för ditt lagringskonto i Azure-portalen under avsnittet "Åtkomstnycklar" eller genom att köra följande Azure CLI-kommando:
# Get the table service URL for the account
az storage account show -n mystorageaccount -g MyResourceGroup --query "primaryEndpoints.table"

När du har konto-URL:en kan den användas för att skapa tjänstklienten:

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

Mer information om URL:er för tabelltjänster och hur du konfigurerar anpassade domännamn för Azure Storage finns i den officiella dokumentationen

Typer av autentiseringsuppgifter

Parametern credential kan anges i ett antal olika formulär, beroende på vilken typ av auktorisering du vill använda. Tabellbiblioteket stöder följande auktoriseringar:

  • Delad nyckel
  • Connection String (Anslutningssträng)
  • Signaturtoken för delad åtkomst
Skapa klienten från en delad nyckel

Om du vill använda en delad kontonyckel (även kallad kontonyckel eller åtkomstnyckel) anger du nyckeln som en sträng. Du hittar detta i ditt lagringskonto i Azure-portalen under avsnittet "Åtkomstnycklar" eller genom att köra följande Azure CLI-kommando:

az storage account keys list -g MyResourceGroup -n MyStorageAccount

Använd nyckeln som parameter för autentiseringsuppgifter för att autentisera klienten:

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)
Skapa klienten från en anslutningssträng

Beroende på ditt användningsfall och din auktoriseringsmetod kanske du föredrar att initiera en klientinstans med en anslutningssträng i stället för att ange konto-URL:en och autentiseringsuppgifterna separat. Det gör du genom att skicka anslutningssträngen till klientens from_connection_string klassmetod. Anslutningssträngen finns i ditt lagringskonto i Azure-portalen under avsnittet "Åtkomstnycklar" eller med följande Azure CLI-kommando:

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)
Skapa klienten från en SAS-token

Om du vill använda en SAS-token (signatur för delad åtkomst) anger du token som en sträng. Om din konto-URL innehåller SAS-token utelämnar du parametern för autentiseringsuppgifter. Du kan generera en SAS-token från Azure-portalen under Signatur för delad åtkomst eller använda en av generate_*_sas() funktionerna för att skapa en SAS-token för kontot eller tabellen:

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

Viktiga begrepp

Vanliga användningsområden för tabelltjänsten är:

  • Lagring av flera TB med strukturerade data som kan serva webbaserade skalningsbara program
  • Lagring av datauppsättningar som inte kräver komplexa kopplingar, sekundärnycklar eller lagrade procedurer och kan avnormaliseras för snabb åtkomst
  • Ställa snabba datafrågor med hjälp av ett klustrat index
  • Komma åt data med hjälp av OData-protokollet och LINQ-filteruttryck

Följande komponenter utgör Tjänsten Azure Tables:

  • Kontot
  • En tabell i kontot, som innehåller en uppsättning entiteter
  • En entitet i en tabell som en ordlista

Med Azure Tables-klientbiblioteket för Python kan du interagera med var och en av dessa komponenter genom att använda ett dedikerat klientobjekt.

Klienter

Två olika klienter tillhandahålls för att interagera med de olika komponenterna i tabelltjänsten:

  1. TableServiceClient -
    • Hämta och ange kontoinställning
    • Fråga, skapa och ta bort tabeller i kontot.
    • Hämta en TableClient för att komma åt en specifik tabell med hjälp av get_table_client metoden .
  2. TableClient -
    • Interagerar med en specifik tabell (som inte behöver finnas ännu).
    • Skapa, ta bort, fråga och upsert-entiteter i den angivna tabellen.
    • Skapa eller ta bort själva den angivna tabellen.

Entiteter

Entiteter liknar rader. En entitet har en PartitionKey, en RowKeyoch en uppsättning egenskaper. En egenskap är ett namnvärdepar som liknar en kolumn. Varje entitet i en tabell behöver inte ha samma egenskaper. Entiteter kan representeras som ordlistor som detta som exempel:

entity = {
    'PartitionKey': 'color',
    'RowKey': 'brand',
    'text': 'Marker',
    'color': 'Purple',
    'price': '5'
}
  • create_entity – Lägg till en entitet i tabellen.
  • delete_entity – Ta bort en entitet från tabellen.
  • update_entity – Uppdatera en entitetsinformation genom att antingen slå samman eller ersätta den befintliga entiteten.
    • UpdateMode.MERGE lägger till nya egenskaper i en befintlig entitet och tar inte bort befintliga egenskaper
    • UpdateMode.REPLACE ersätter den befintliga entiteten med den angivna och tar bort befintliga egenskaper som inte ingår i den skickade entiteten
  • query_entities – Fråga befintliga entiteter i en tabell med OData-filter.
  • get_entity – Hämta en specifik entitet från en tabell efter partition och radnyckel.
  • upsert_entity – Sammanfoga eller ersätta en entitet i en tabell, eller om entiteten inte finns infogar entiteten.
    • UpdateMode.MERGE lägger till nya egenskaper i en befintlig entitet och tar inte bort befintliga egenskaper
    • UpdateMode.REPLACE ersätter den befintliga entiteten med den angivna och tar bort befintliga egenskaper som inte ingår i den skickade entiteten

Exempel

Följande avsnitt innehåller flera kodfragment som täcker några av de vanligaste tabelluppgifterna, inklusive:

Skapa en tabell

Skapa en tabell i ditt konto och hämta en TableClient för att utföra åtgärder i den nyligen skapade tabellen:

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)

Skapa entiteter

Skapa entiteter i tabellen:

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)

Fråga entiteter

Fråga entiteter i tabellen:

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

Valfri konfiguration

Valfria nyckelordsargument kan skickas in på klient- och åtgärdsnivå. Referensdokumentationen för azure-core beskriver tillgängliga konfigurationer för återförsök, loggning, transportprotokoll med mera.

Konfiguration av återförsöksprincip

Använd följande nyckelordsargument när du instansierar en klient för att konfigurera återförsöksprincipen:

  • retry_total (int): Totalt antal återförsök som ska tillåtas. Har företräde framför andra antal. Skicka in retry_total=0 om du inte vill försöka igen på begäranden. Standardvärdet är 10.
  • retry_connect (int): Hur många anslutningsrelaterade fel som ska försökas igen. Standardvärdet är 3.
  • retry_read (int): Hur många gånger läsfel ska försöka igen. Standardvärdet är 3.
  • retry_status (int): Hur många gånger du försöker igen med felaktiga statuskoder. Standardvärdet är 3.
  • retry_to_secondary (bool): Om begäran ska göras om till sekundär, om det går. Detta bör endast aktiveras för RA-GRS-konton som används och potentiellt inaktuella data kan hanteras. Standardvärdet är False.

Annan klient/per åtgärd-konfiguration

Andra valfria nyckelordsargument för konfiguration som kan anges på klienten eller per åtgärd.

Argument för klientnyckelord:

  • connection_timeout (int): Om du vill kan du ange timeout-värdet för anslutning och läsning i sekunder.
  • transport (alla): Transport som tillhandahålls av användaren för att skicka HTTP-begäran.

Nyckelordsargument per åtgärd:

  • raw_response_hook (anropsbar): Det angivna återanropet använder svaret som returneras från tjänsten.
  • raw_request_hook (anropsbar): Det angivna återanropet använder begäran innan den skickas till tjänsten.
  • client_request_id (str): Valfri användare har angett identifiering av begäran.
  • user_agent (str): Lägger till det anpassade värdet i user-agent-huvudet som ska skickas med begäran.
  • logging_enable (bool): Aktiverar loggning på felsökningsnivå. Standardvärdet är False. Kan också skickas in på klientnivå för att aktivera det för alla begäranden.
  • headers (dict): Skicka in anpassade rubriker som nyckel, värdepar. E.g. headers={'CustomValue': value}

Felsökning

Allmänt

Azure Tables-klienter genererar undantag som definierats i Azure Core. När du interagerar med Azure-tabellbiblioteket med hjälp av Python SDK svarar fel som returneras av tjänsten med samma HTTP-statuskoder för REST API-begäranden . Tabelltjänståtgärderna utlöser ett HttpResponseError fel med användbara felkoder.

Om du till exempel försöker skapa en tabell som redan finns returneras ett 409 fel som anger "Konflikt".

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

Loggning

Det här biblioteket använder standardloggningsbiblioteket för loggning. Grundläggande information om HTTP-sessioner (URL:er, rubriker osv.) loggas på INFO-nivå.

Detaljerad loggning på FELSÖKNINGsnivå, inklusive begärande-/svarskroppar och oredigerade huvuden, kan aktiveras på en klient med logging_enable argumentet :

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)

logging_enable På samma sätt kan aktivera detaljerad loggning för en enda åtgärd, även om den inte är aktiverad för klienten:

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

Nästa steg

Kom igång med våra tabellexempel.

Flera Azure Tables Python SDK-exempel är tillgängliga för dig på SDK:s GitHub-lagringsplats. De här exemplen innehåller exempelkod för ytterligare scenarier som ofta påträffas när du arbetar med tabeller.

Vanliga scenarier

Dessa kodexempel visar vanliga scenarioåtgärder med Azure Tables-klientbiblioteket. De asynkrona versionerna av exemplen (python-exempelfilerna som läggs till med _async) visar asynkrona åtgärder.

Ytterligare dokumentation

Mer omfattande dokumentation om Azure-tabeller finns i Dokumentation om Azure-tabeller på docs.microsoft.com.

Kända problem

En lista över kända problem som rör Cosmos DB-tabellslutpunkter finns här.

Bidra

Det här projektet välkomnar bidrag och förslag. Merparten av bidragen kräver att du godkänner ett licensavtal för bidrag, där du deklarerar att du har behörighet att bevilja oss rättigheten att använda ditt bidrag, och att du dessutom uttryckligen gör så. Mer information finns på https://cla.microsoft.com.

När du skickar en pull-förfrågan avgör en CLA-robot automatiskt om du måste tillhandahålla ett licensavtal för bidrag med lämplig PR (t.ex. etikett eller kommentar). Följ bara robotens anvisningar. Du behöver bara göra detta en gång för alla repor som använder vårt licensavtal för bidrag.

Det här projektet använder sig av Microsofts uppförandekod för öppen källkod. Mer information finns i Vanliga frågor och svar om uppförandekoden eller kontakta opencode@microsoft.com med ytterligare frågor eller kommentarer.

Visningar