Delen via

Azure Tables-clientbibliotheek voor Python - versie 12.4.4

  • Artikel

Azure Tables is een NoSQL-gegevensopslagservice die overal ter wereld toegankelijk is via geverifieerde aanroepen via HTTP of HTTPS. Tabellen kunnen naar behoefte worden geschaald om de hoeveelheid ingevoegde gegevens te ondersteunen en het opslaan van gegevens met niet-complexe toegang mogelijk te maken. De Azure Tables-client kan worden gebruikt voor toegang tot Azure Storage- of Cosmos-accounts. In dit document wordt beschreven azure-data-tables.

Houd er rekening mee dat dit pakket een vervanging is die azure-cosmosdb-tables nu is afgeschaft. Zie de migratiehandleiding voor meer informatie.

Broncode | Pakket (PyPI) | Pakket (Conda) | API-referentiedocumentatie | Monsters

Disclaimer

Ondersteuning voor Azure SDK Python-pakketten voor Python 2.7 is beëindigd op 1 januari 2022. Raadpleeg Python 3.7 of hoger is vereist om https://github.com/Azure/azure-sdk-for-python/issues/20691dit pakket te gebruiken voor meer informatie en vragen. Raadpleeg het ondersteuningsbeleid voor Azure SDK voor Python-versies voor meer informatie.

Aan de slag

De Azure Tables SDK heeft toegang tot een Azure Storage- of CosmosDB-account.

Vereisten

Account maken

Het pakket installeren

Installeer de Azure Tables-clientbibliotheek voor Python met pip:

pip install azure-data-tables

De client maken

Met de Azure Tables-bibliotheek kunt u werken met twee typen resources:

  • de tabellen in uw account
  • de entiteiten in deze tabellen. Interactie met deze resources begint met een exemplaar van een client. Als u een clientobject wilt maken, hebt u de eindpunt-URL van de tabelservice van het account en een referentie nodig waarmee u toegang hebt tot het account. De endpoint vindt u op de pagina voor uw opslagaccount in de Azure-portal onder de sectie Toegangssleutels of door de volgende Azure CLI-opdracht uit te voeren:
# Get the table service URL for the account
az storage account show -n mystorageaccount -g MyResourceGroup --query "primaryEndpoints.table"

Zodra u de account-URL hebt, kan deze worden gebruikt om de serviceclient te maken:

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

Raadpleeg de officiële documentatie voor meer informatie over url's van tabelservices en het configureren van aangepaste domeinnamen voor Azure Storage

Typen referenties

De credential parameter kan in verschillende vormen worden opgegeven, afhankelijk van het type autorisatie dat u wilt gebruiken. De bibliotheek Tabellen ondersteunt de volgende autorisaties:

  • Gedeelde sleutel
  • Verbindingsreeks
  • Shared Access Signature-token
De client maken op basis van een gedeelde sleutel

Als u een gedeelde accountsleutel (ook wel accountsleutel of toegangssleutel genoemd) wilt gebruiken, geeft u de sleutel op als een tekenreeks. U vindt dit in uw opslagaccount in Azure Portal onder de sectie Toegangssleutels of door de volgende Azure CLI-opdracht uit te voeren:

az storage account keys list -g MyResourceGroup -n MyStorageAccount

Gebruik de sleutel als referentieparameter om de client te verifiëren:

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)
De client maken op basis van een connection string

Afhankelijk van uw use-case en autorisatiemethode kunt u een clientexemplaren initialiseren met een connection string in plaats van de account-URL en referenties afzonderlijk op te geven. Hiervoor geeft u de connection string door aan de klassemethode van from_connection_string de client. De connection string vindt u in uw opslagaccount in Azure Portal onder de sectie Toegangssleutels of met de volgende Azure CLI-opdracht:

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)
De client maken op basis van een SAS-token

Als u een SAS-token (Shared Access Signature) wilt gebruiken, geeft u het token op als een tekenreeks. Als uw account-URL het SAS-token bevat, laat u de referentieparameter weg. U kunt een SAS-token genereren vanuit Azure Portal onder Shared Access Signature of een van de generate_*_sas() functies gebruiken om een SAS-token voor het account of de tabel te maken:

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

Belangrijkste concepten

Veelvoorkomende toepassingen van de Table-service zijn onder andere:

  • Opslaan van terabytes aan gestructureerde gegevens die kunnen worden geleverd aan webschaaltoepassingen
  • Het opslaan van gegevenssets waarvoor geen complexe joins, refererende sleutels of opgeslagen procedures zijn vereist en die kunnen worden gedenormaliseerd voor snelle toegang
  • Snel een query voor gegevens uitvoeren met een geclusterde index
  • Toegang tot gegevens met behulp van het OData-protocol en LINQ-filterexpressies

De Azure Tables-service bestaat uit de volgende onderdelen:

  • Het account
  • Een tabel in het account, die een set entiteiten bevat
  • Een entiteit in een tabel, als een woordenlijst

Met de Azure Tables-clientbibliotheek voor Python kunt u met elk van deze onderdelen communiceren via het gebruik van een toegewezen clientobject.

Clients

Er worden twee verschillende clients geleverd voor interactie met de verschillende onderdelen van de tabelservice:

  1. TableServiceClient -
    • Accountinstelling ophalen en instellen
    • Tabellen in het account opvragen, maken en verwijderen.
    • Haal een TableClient op om toegang te krijgen tot een specifieke tabel met behulp van de get_table_client -methode.
  2. TableClient -
    • Communiceert met een specifieke tabel (die nog niet hoeft te bestaan).
    • Entiteiten maken, verwijderen, opvragen en upsertentiteiten binnen de opgegeven tabel.
    • Maak of verwijder de opgegeven tabel zelf.

Entiteiten

Entiteiten zijn vergelijkbaar met rijen. Een entiteit heeft een PartitionKey, een RowKeyen een set eigenschappen. Een eigenschap is een naamwaardepaar, vergelijkbaar met een kolom. Niet elke entiteit in een tabel hoeft dezelfde eigenschappen te hebben. Entiteiten kunnen als voorbeeld als woordenlijsten worden weergegeven:

entity = {
    'PartitionKey': 'color',
    'RowKey': 'brand',
    'text': 'Marker',
    'color': 'Purple',
    'price': '5'
}
  • create_entity : voeg een entiteit toe aan de tabel.
  • delete_entity : verwijder een entiteit uit de tabel.
  • update_entity : werk de gegevens van een entiteit bij door de bestaande entiteit samen te voegen of te vervangen.
    • UpdateMode.MERGE voegt nieuwe eigenschappen toe aan een bestaande entiteit. Er worden geen bestaande eigenschappen verwijderd
    • UpdateMode.REPLACE vervangt de bestaande entiteit door de opgegeven entiteit, waarbij bestaande eigenschappen worden verwijderd die niet zijn opgenomen in de ingediende entiteit
  • query_entities : query's uitvoeren op bestaande entiteiten in een tabel met behulp van OData-filters.
  • get_entity : haal een specifieke entiteit op uit een tabel op basis van partitie en rijsleutel.
  • upsert_entity : een entiteit in een tabel samenvoegen of vervangen. Als de entiteit niet bestaat, voegt u de entiteit in.
    • UpdateMode.MERGE voegt nieuwe eigenschappen toe aan een bestaande entiteit. Er worden geen bestaande eigenschappen verwijderd
    • UpdateMode.REPLACE vervangt de bestaande entiteit door de opgegeven entiteit, waarbij bestaande eigenschappen worden verwijderd die niet zijn opgenomen in de ingediende entiteit

Voorbeelden

De volgende secties bevatten verschillende codefragmenten voor enkele van de meest voorkomende tabeltaken, waaronder:

Een tabel maken

Maak een tabel in uw account en haal een TableClient op om bewerkingen uit te voeren op de zojuist gemaakte tabel:

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)

Entiteiten maken

Entiteiten maken in de tabel:

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)

Query's uitvoeren op entiteiten

Query's uitvoeren op entiteiten in de tabel:

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

Optionele configuratie

Optionele trefwoordargumenten kunnen worden doorgegeven op het niveau van de client en per bewerking. In de naslagdocumentatie van Azure Core worden de beschikbare configuraties beschreven voor nieuwe pogingen, logboekregistratie, transportprotocollen en meer.

Configuratie van beleid voor opnieuw proberen

Gebruik de volgende trefwoordargumenten bij het instantiëren van een client om het beleid voor opnieuw proberen te configureren:

  • retry_total (int): het totale aantal nieuwe pogingen dat moet worden toegestaan. Heeft voorrang op andere aantallen. Geef door retry_total=0 als u aanvragen niet opnieuw wilt proberen. De standaardwaarde is 10.
  • retry_connect (int): hoeveel verbindingsfouten u opnieuw wilt proberen. Standaardwaarde is 3.
  • retry_read (int): hoe vaak moet u het opnieuw proberen bij leesfouten. Standaardwaarde is 3.
  • retry_status (int): hoe vaak moet u ongeldige statuscodes opnieuw proberen. Standaardwaarde is 3.
  • retry_to_secondary (bool): of de aanvraag opnieuw moet worden geprobeerd naar secundaire, indien mogelijk. Dit mag alleen worden ingeschakeld als RA-GRS-accounts worden gebruikt en mogelijk verouderde gegevens kunnen worden verwerkt. De standaardwaarde is False.

Andere client/configuratie per bewerking

Andere optionele trefwoordargumenten voor configuratie die kunnen worden opgegeven op de client of per bewerking.

Argumenten voor clientwoorden:

  • connection_timeout (int): stelt optioneel de time-outwaarde voor verbinding maken en lezen in seconden in.
  • transport (alle): door de gebruiker opgegeven transport om de HTTP-aanvraag te verzenden.

Trefwoordargumenten per bewerking:

  • raw_response_hook (aanroepbaar): de opgegeven callback maakt gebruik van het antwoord dat is geretourneerd door de service.
  • raw_request_hook (aanroepbaar): de opgegeven callback maakt gebruik van de aanvraag voordat deze naar de service wordt verzonden.
  • client_request_id (str): optioneel door de gebruiker opgegeven identificatie van de aanvraag.
  • user_agent (str): voegt de aangepaste waarde toe aan de header user-agent die met de aanvraag moet worden verzonden.
  • logging_enable (bool): hiermee schakelt u logboekregistratie in op het niveau VAN FOUTOPSPORING. Standaard ingesteld op False. Kan ook worden doorgegeven op clientniveau om deze in te schakelen voor alle aanvragen.
  • headers (dict): geef aangepaste headers door als sleutel, waardeparen. Bijvoorbeeld. headers={'CustomValue': value}

Problemen oplossen

Algemeen

Azure Tables-clients genereren uitzonderingen die zijn gedefinieerd in Azure Core. Wanneer u communiceert met de Azure-tabelbibliotheek met behulp van de Python SDK, reageren fouten die door de service worden geretourneerd op dezelfde HTTP-statuscodes voor REST API-aanvragen . De tabelservicebewerkingen genereren een HttpResponseError fout met nuttige foutcodes.

Als u bijvoorbeeld een tabel probeert te maken die al bestaat, wordt er een 409 fout geretourneerd die 'Conflict' aangeeft.

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

Logboekregistratie

Deze bibliotheek maakt gebruik van de standaardbibliotheek voor logboekregistratie voor logboekregistratie. Basisinformatie over HTTP-sessies (URL's, headers, enzovoort) wordt geregistreerd op INFO-niveau.

Gedetailleerde logboekregistratie op foutopsporingsniveau, inclusief aanvraag-/antwoordteksten en niet-bewerkte headers, kan worden ingeschakeld op een client met het logging_enable argument:

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)

Op dezelfde manier logging_enable kan gedetailleerde logboekregistratie voor één bewerking worden ingeschakeld, zelfs wanneer deze niet is ingeschakeld voor de client:

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

Volgende stappen

Ga aan de slag met onze tabelvoorbeelden.

Er zijn verschillende Python SDK-voorbeelden voor Azure Tables beschikbaar in de GitHub-opslagplaats van de SDK. Deze voorbeelden bieden voorbeeldcode voor aanvullende scenario's die vaak voorkomen tijdens het werken met tabellen.

Gangbare scenario's

Deze codevoorbeelden tonen veelvoorkomende scenariobewerkingen met de clientbibliotheek van Azure Tables. De asynchrone versies van de voorbeelden (de Python-voorbeeldbestanden toegevoegd met _async) tonen asynchrone bewerkingen.

Aanvullende documentatie

Zie de documentatie over Azure Tables op docs.microsoft.com voor uitgebreidere documentatie over Azure-tabellen .

Bekende problemen

Een lijst met momenteel bekende problemen met betrekking tot Cosmos DB-tabeleindpunten vindt u hier.

Bijdragen

Wij verwelkomen bijdragen en suggesties voor dit project. Voor de meeste bijdragen moet u instemmen met een licentieovereenkomst voor bijdragers (CLA: Contributor License Agreement) waarin u verklaart dat u gerechtigd bent ons het recht te geven uw bijdrage te gebruiken, en dat u dit ook doet. Ga naar https://cla.microsoft.com voor meer informatie.

Wanneer u een pull-aanvraag indient, wordt met een CLA-bot automatisch bepaald of u een CLA moet verschaffen en wordt de pull-aanvraag dienovereenkomstig opgemaakt (bijvoorbeeld met een label of commentaar). Volg gewoon de instructies van de bot. U hoeft dit maar eenmaal te doen voor alle repo's waar gebruik wordt gemaakt van onze CLA.

Op dit project is de Microsoft Open Source Code of Conduct (Microsoft Open Source-gedragscode) van toepassing. Zie de Veelgestelde vragen over de gedragscode voor meer informatie of neem contact op opencode@microsoft.com met eventuele aanvullende vragen of opmerkingen.

Weergaven