Sdílet prostřednictvím

Klientská knihovna Azure Tables pro Python – verze 12.4.4

  • Článek

Azure Tables je služba úložiště dat NoSQL, ke které je možné přistupovat odkudkoli na světě prostřednictvím ověřených volání pomocí protokolu HTTP nebo HTTPS. Tabulky se podle potřeby škálují, aby podporovaly množství vložených dat, a umožňují ukládání dat s nesložitým přístupem. Klienta Azure Tables je možné použít pro přístup k účtům Azure Storage nebo Cosmos. Tento dokument se zabývá azure-data-tables.

Upozorňujeme, že tento balíček je náhradou, která azure-cosmosdb-tables je nyní zastaralá. Další podrobnosti najdete v průvodci migrací .

Zdrojový kód | Balíček (PyPI) | Balíček (Conda) | Referenční dokumentace k | rozhraní APIVzorky

Právní omezení

Podpora balíčků Azure SDK Python pro Python 2.7 skončila 1. ledna 2022. Další informace a dotazy najdete v tématu https://github.com/Azure/azure-sdk-for-python/issues/20691Použití tohoto balíčku vyžaduje Python 3.7 nebo novější. Další podrobnosti najdete v tématu Věnovaném zásadám podpory verzí sady Azure SDK pro Python.

Začínáme

Sada Azure Tables SDK má přístup k účtu Služby Azure Storage nebo CosmosDB.

Požadavky

Vytvoření účtu

Instalace balíčku

Nainstalujte klientskou knihovnu Azure Tables pro Python pomocí pipu:

pip install azure-data-tables

Vytvoření klienta

Knihovna Tabulek Azure umožňuje interakci se dvěma typy prostředků:

  • tabulky ve vašem účtu
  • entity v těchto tabulkách. Interakce s těmito prostředky začíná instancí klienta. K vytvoření objektu klienta budete potřebovat adresu URL koncového bodu služby tabulky účtu a přihlašovací údaje, které vám umožní přístup k účtu. Najdete endpoint ho na stránce pro váš účet úložiště na webu Azure Portal v části Přístupové klíče nebo spuštěním následujícího příkazu Azure CLI:
# Get the table service URL for the account
az storage account show -n mystorageaccount -g MyResourceGroup --query "primaryEndpoints.table"

Jakmile budete mít adresu URL účtu, můžete ji použít k vytvoření klienta služby:

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

Další informace o adresách URL služby Table Service a postupu při konfiguraci vlastních názvů domén pro Azure Storage najdete v oficiální dokumentaci.

Typy přihlašovacích údajů

Parametr credential může být poskytnut v několika různých formách v závislosti na typu autorizace, kterou chcete použít. Knihovna Tabulek podporuje následující autorizace:

  • Sdílený klíč
  • Connection String (Připojovací řetězec)
  • Token sdíleného přístupových podpisů
Vytvoření klienta ze sdíleného klíče

Pokud chcete použít sdílený klíč účtu (neboli klíč účtu nebo přístupový klíč), zadejte ho jako řetězec. Najdete ho v účtu úložiště na webu Azure Portal v části Přístupové klíče nebo spuštěním následujícího příkazu Azure CLI:

az storage account keys list -g MyResourceGroup -n MyStorageAccount

K ověření klienta použijte klíč jako parametr přihlašovacích údajů:

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)
Vytvoření klienta z připojovacího řetězce

V závislosti na vašem případu použití a metodě autorizace můžete dát přednost inicializaci instance klienta s připojovacím řetězcem místo zadání adresy URL účtu a přihlašovacích údajů samostatně. Provedete to tak, že předáte připojovací řetězec metodě třídy klienta from_connection_string . Připojovací řetězec najdete ve vašem účtu úložiště na webu Azure Portal v části Přístupové klíče nebo pomocí následujícího příkazu Azure CLI:

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)
Vytvoření klienta z tokenu SAS

Pokud chcete použít token sdíleného přístupového podpisu (SAS), zadejte ho jako řetězec. Pokud adresa URL vašeho účtu obsahuje token SAS, parametr credential vyněžte. Token SAS můžete vygenerovat z webu Azure Portal v části Sdílený přístupový podpis nebo pomocí některé z generate_*_sas() funkcí vytvořit token SAS pro účet nebo tabulku:

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

Klíčové koncepty

Mezi běžná použití služby Table patří:

  • Ukládání terabajtů strukturovaných dat, která můžou obsluhovat škálované webové aplikace
  • Ukládání datových sad, které nevyžadují složitá spojení, cizí klíče nebo uložené procedury a je možné je zrušit normalizaci pro rychlý přístup
  • Rychle dotazování na data pomocí clusterovaného indexu
  • Přístup k datům pomocí protokolu OData a výrazů filtru LINQ

Službu Azure Tables Service tvoří následující komponenty:

  • Účet
  • Tabulka v rámci účtu, která obsahuje sadu entit.
  • Entita v tabulce jako slovník

Klientská knihovna Azure Tables pro Python umožňuje interakci s každou z těchto komponent pomocí vyhrazeného objektu klienta.

Klienti

Pro interakci s různými komponentami služby Table Service jsou k dispozici dva různí klienti:

  1. TableServiceClient -
    • Získání a nastavení účtu
    • Dotazování, vytváření a odstraňování tabulek v rámci účtu
    • TableClient Získání přístupu ke konkrétní tabulce pomocí get_table_client metody
  2. TableClient -
    • Pracuje s konkrétní tabulkou (která ještě nemusí existovat).
    • Vytváření, odstraňování, dotazování a upsert entit v zadané tabulce
    • Vytvořte nebo odstraňte samotnou zadanou tabulku.

Entity

Entity jsou podobné řádkům. Entita má PartitionKey, RowKeya sadu vlastností. Vlastnost je pár hodnot názvu, který se podobá sloupci. Každá entita v tabulce nemusí mít stejné vlastnosti. Entity mohou být reprezentovány jako slovníky, jako je tento příklad:

entity = {
    'PartitionKey': 'color',
    'RowKey': 'brand',
    'text': 'Marker',
    'color': 'Purple',
    'price': '5'
}
  • create_entity – Přidejte do tabulky entitu.
  • delete_entity – Odstraní entitu z tabulky.
  • update_entity – Aktualizujte informace o entitě sloučením nebo nahrazením existující entity.
    • UpdateMode.MERGE přidá nové vlastnosti do existující entity, neodstraní existující vlastnosti.
    • UpdateMode.REPLACE nahradí existující entitu danou entitou a odstraní všechny existující vlastnosti, které nejsou zahrnuté v odeslané entitě.
  • query_entities – dotazování existujících entit v tabulce pomocí filtrů OData
  • get_entity – Získejte konkrétní entitu z tabulky podle oddílu a klíče řádku.
  • upsert_entity – Sloučí nebo nahradí entitu v tabulce. Pokud entita neexistuje, vloží entitu.
    • UpdateMode.MERGE přidá nové vlastnosti do existující entity, neodstraní existující vlastnosti.
    • UpdateMode.REPLACE nahradí existující entitu danou entitou a odstraní všechny existující vlastnosti, které nejsou zahrnuté v odeslané entitě.

Příklady

V následujících částech najdete několik fragmentů kódu, které pokrývají některé nejběžnější úlohy tabulky, mezi které patří:

Vytvoření tabulky

Vytvořte ve svém účtu tabulku a získejte příkaz k TableClient provádění operací s nově vytvořenou tabulkou:

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)

Vytváření entit

Vytvoření entit v tabulce:

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)

Dotazování entit

Dotazování entit v tabulce:

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

Volitelná konfigurace

Volitelné argumenty klíčových slov je možné předat na úrovni klienta a na úrovni jednotlivých operací. Referenční dokumentace azure-core popisuje dostupné konfigurace pro opakování, protokolování, přenosové protokoly a další.

Konfigurace zásad opakování

Při vytváření instance klienta ke konfiguraci zásad opakování použijte následující argumenty klíčových slov:

  • retry_total (int): Celkový počet opakovaných pokusů, které se mají povolit. Má přednost před ostatními počty. retry_total=0 Pokud nechcete opakovat pokusy o žádosti, předejte je. Výchozí hodnota je 10.
  • retry_connect (int): Kolik chyb souvisejících s připojením se má opakovat. Výchozí hodnota je 3.
  • retry_read (int): Kolikrát se má opakovat pokus o chyby čtení. Výchozí hodnota je 3.
  • retry_status (int): Kolikrát se má opakovat chybný stavový kód. Výchozí hodnota je 3.
  • retry_to_secondary (bool): Jestli se má žádost opakovat na sekundární, pokud je to možné. Tato možnost by měla být povolená jenom u účtů RA-GRS a je možné zpracovávat potenciálně zastaralá data. Výchozí hodnota je False.

Konfigurace jiného klienta nebo operace

Další volitelné argumenty klíčového slova konfigurace, které lze zadat v klientovi nebo pro každou operaci.

Argumenty klíčových slov klienta:

  • connection_timeout (int): Volitelně nastaví hodnotu časového limitu připojení a čtení v sekundách.
  • transport (Any): Přenos poskytnutý uživatelem k odeslání požadavku HTTP.

Argumenty klíčových slov pro jednotlivé operace:

  • raw_response_hook (volatelné): Dané zpětné volání použije odpověď vrácenou službou.
  • raw_request_hook (volatelné): Dané zpětné volání použije požadavek před odesláním do služby.
  • client_request_id (str): Nepovinný uživatel zadal identifikaci požadavku.
  • user_agent (str): Připojí vlastní hodnotu k hlavičce uživatelského agenta, která se má odeslat spolu s požadavkem.
  • logging_enable (bool): Povolí protokolování na úrovni LADĚNÍ. Výchozí hodnota je False. Můžete ho také předat na úrovni klienta, abyste ho povolili pro všechny požadavky.
  • headers (dict): Předejte vlastní hlavičky jako klíče a páry hodnot. Např. headers={'CustomValue': value}

Poradce při potížích

Obecné

Klienti Azure Tables vyvolávají výjimky definované v Azure Core. Při interakci s knihovnou tabulek Azure pomocí sady Python SDK budou chyby vrácené službou odpovídat stejným stavovým kódům HTTP pro požadavky rozhraní REST API . Operace služby Table Service způsobí HttpResponseError selhání s užitečnými kódy chyb.

Pokud se například pokusíte vytvořit tabulku, která již existuje, 409 vrátí se chyba označující 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))

protokolování

Tato knihovna používá pro protokolování standardní knihovnu protokolování . Základní informace o relacích HTTP (adresy URL, hlavičky atd.) se protokolují na úrovni INFO.

Podrobné protokolování úrovně LADĚNÍ, včetně těl požadavků/odpovědí a nereagovaných hlaviček, je možné povolit na klientovi s argumentem 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)

Podobně logging_enable může povolit podrobné protokolování pro jednu operaci, i když není povolené pro klienta:

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

Další kroky

Začněte s našimi ukázkami tabulek.

V úložišti GitHubu sady SDK pro tabulky Azure máte k dispozici několik ukázek sady Python SDK. Tyto ukázky poskytují ukázkový kód pro další scénáře, se kterými se při práci s tabulkami běžně setkáváme.

Obvyklé situace

Tyto ukázky kódu ukazují běžné operace scénářů s klientskou knihovnou Azure Tables. Asynchronní verze ukázek (ukázkové soubory Pythonu připojené s _async) zobrazují asynchronní operace.

Další dokumentace

Rozsáhlejší dokumentaci k tabulkám Azure najdete v dokumentaci ke službě Azure Tables na docs.microsoft.com.

Známé problémy

Seznam aktuálně známých problémů souvisejících s koncovými body tabulky Cosmos DB najdete tady.

Přispívání

Tento projekt vítá příspěvky a návrhy. Většina příspěvků vyžaduje souhlas s licenční smlouvou s přispěvatelem (CLA), která stanoví, že máte právo udělit nám práva k používání vašeho příspěvku a skutečně tak činíte. Podrobnosti najdete tady: https://cla.microsoft.com

Při odesílání žádosti o přijetí změn robot CLA automaticky určí, jestli je potřeba poskytnout smlouvu CLA, a příslušným způsobem žádost o přijetí změn upraví (např. přidáním jmenovky nebo komentáře). Stačí postupovat podle pokynů robota. Pro všechna úložiště používající naši smlouvu CLA to stačí udělat jenom jednou.

Tento projekt přijal pravidla chování pro Microsoft Open Source. Další informace najdete v nejčastějších dotazech k pravidlům chování nebo se obraťte na opencode@microsoft.com případné další dotazy nebo komentáře.

Imprese