Megosztás a következőn keresztül:

Azure Tables ügyfélkódtár Pythonhoz – 12.4.4-es verzió

  • Cikk

Az Azure Tables egy NoSQL-adattárolási szolgáltatás, amely a világ bármely pontjáról elérhető http- vagy HTTPS-alapú hitelesített hívásokon keresztül. A táblák szükség szerint méretezhetők a beszúrt adatok mennyiségének támogatásához, és lehetővé teszik az adatok tárolását nem összetett hozzáféréssel. Az Azure Tables-ügyfél használható az Azure Storage- vagy Cosmos-fiókok eléréséhez. Ez a dokumentum a következőt ismerteti azure-data-tables: .

Felhívjuk figyelmét, hogy ez a csomag egy csere azure-cosmosdb-tables , amelynek már elavult. További részletekért tekintse meg a migrálási útmutatót .

Forráskód | Csomag (PyPI) | Csomag (Conda) | API-referenciadokumentáció | Minták

Felelősséget kizáró nyilatkozat

Az Azure SDK Python-csomagok támogatása a Python 2.7-hez 2022. január 01-én véget ért. További információkért és kérdésekért tekintse meg a https://github.com/Azure/azure-sdk-for-python/issues/20691Csomag használatához szükséges Python 3.7-et vagy újabb verziót. További részletekért tekintse meg a Pythonhoz készült Azure SDK verziótámogatási szabályzatát.

Első lépések

Az Azure Tables SDK hozzáférhet egy Azure Storage- vagy CosmosDB-fiókhoz.

Előfeltételek

Fiók létrehozása

A csomag telepítése

Telepítse a Pythonhoz készült Azure Tables ügyfélkódtárat a pip használatával:

pip install azure-data-tables

Az ügyfél létrehozása

Az Azure Tables-kódtár két típusú erőforrás használatát teszi lehetővé:

  • a fiók táblái
  • a táblákon belüli entitások. Ezekkel az erőforrásokkal való interakció az ügyfél egy példányával kezdődik. Ügyfélobjektum létrehozásához szüksége lesz a fiók táblaszolgáltatás-végpontjának URL-címére és egy hitelesítő adatra, amely lehetővé teszi a fiók elérését. Ez endpoint a tárfiók oldalán található az Azure Portal "Hozzáférési kulcsok" szakaszában, vagy az alábbi Azure CLI-parancs futtatásával:
# Get the table service URL for the account
az storage account show -n mystorageaccount -g MyResourceGroup --query "primaryEndpoints.table"

Ha már rendelkezik a fiók URL-címével, az a szolgáltatásügyfél létrehozásához használható:

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

A Table Service URL-címeiről és az egyéni tartománynevek Azure Storage-hoz való konfigurálásáról a hivatalos dokumentációban talál további információt.

Hitelesítő adatok típusai

A credential paraméter többféle formában is megadható a használni kívánt engedély típusától függően. A Táblák kódtár a következő engedélyeket támogatja:

  • Megosztott kulcsos
  • Kapcsolati sztring
  • Közös hozzáférésű jogosultságkód jogkivonata
Az ügyfél létrehozása megosztott kulcsból

Ha megosztott fiókkulcsot (más néven fiókkulcsot vagy hozzáférési kulcsot) szeretne használni, sztringként adja meg a kulcsot. Ez a tárfiókban található az Azure Portal "Hozzáférési kulcsok" szakaszában, vagy az alábbi Azure CLI-parancs futtatásával:

az storage account keys list -g MyResourceGroup -n MyStorageAccount

Használja a kulcsot hitelesítőadat-paraméterként az ügyfél hitelesítéséhez:

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)
Ügyfél létrehozása kapcsolati sztring

A használati esettől és az engedélyezési módszertől függően érdemes lehet inicializálni egy ügyfélpéldányt egy kapcsolati sztring a fiók URL-címének és hitelesítő adatainak külön megadása helyett. Ehhez adja át a kapcsolati sztring az ügyfél osztálymetódusánakfrom_connection_string. A kapcsolati sztring a tárfiókban található az Azure Portal "Hozzáférési kulcsok" szakaszában, vagy a következő Azure CLI-paranccsal:

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)
Az ügyfél létrehozása SAS-jogkivonatból

Ha közös hozzáférésű jogosultságkód (SAS) jogkivonatot szeretne használni, sztringként adja meg a jogkivonatot. Ha a fiók URL-címe tartalmazza az SAS-jogkivonatot, hagyja ki a hitelesítőadat-paramétert. Sas-jogkivonatot létrehozhat az Azure Portalon a Közös hozzáférésű jogosultságkód területen, vagy az generate_*_sas() egyik függvény használatával sas-jogkivonatot hozhat létre a fiókhoz vagy a táblához:

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

Fő fogalmak

A Table szolgáltatás gyakori felhasználási területei:

  • Több TB-nyi, webes méretű alkalmazások kiszolgálására alkalmas strukturált adat tárolása
  • Olyan adathalmazok tárolása, amelyekhez nincs szükség összetett illesztésekre, idegen kulcsokra vagy tárolt eljárásokra, és amelyek a gyors hozzáférés érdekében normalizálhatók
  • Adatok gyors lekérdezése fürtözött indexszel
  • Adatok elérése az OData protokoll és a LINQ szűrőkifejezések használatával

Az Azure Tables Service-t a következő összetevők alkotják:

  • A fiók
  • A fiókon belüli tábla, amely entitások készletét tartalmazza
  • Egy táblán belüli entitás szótárként

A Pythonhoz készült Azure Tables ügyfélkódtár lehetővé teszi ezen összetevők használatát egy dedikált ügyfélobjektum használatával.

Ügyfelek

A Table Service különböző összetevőinek használatához két különböző ügyfél érhető el:

  1. TableServiceClient -
    • Fiókbeállítás beolvasása és beállítása
    • Táblák lekérdezése, létrehozása és törlése a fiókban.
    • Lekérhet egy TableClient adott táblát a get_table_client metódussal.
  2. TableClient -
    • Egy adott táblával kommunikál (amelynek még nem kell léteznie).
    • Entitásokat hozhat létre, törölhet, kérdezhet le és állíthat be a megadott táblán belül.
    • Hozza létre vagy törölje magát a megadott táblát.

Entitások

Az entitások hasonlóak a sorokhoz. Egy entitás rendelkezik egy PartitionKey, egy RowKeyés egy tulajdonságkészlettel. A tulajdonság egy oszlophoz hasonló névértékpár. A tábla minden entitásának nem kell ugyanazokkal a tulajdonságokkal rendelkeznie. Az entitások például az alábbihoz hasonló szótárakként ábrázolhatók:

entity = {
    'PartitionKey': 'color',
    'RowKey': 'brand',
    'text': 'Marker',
    'color': 'Purple',
    'price': '5'
}
  • create_entity – Entitás hozzáadása a táblához.
  • delete_entity – Entitás törlése a táblából.
  • update_entity – Egy entitás adatainak frissítése a meglévő entitás egyesítésével vagy cseréjével.
    • UpdateMode.MERGE új tulajdonságokat ad hozzá egy meglévő entitáshoz, amely nem törli a meglévő tulajdonságokat
    • UpdateMode.REPLACE lecseréli a meglévő entitást az adott entitásra, és törli az elküldött entitásban nem szereplő meglévő tulajdonságokat
  • query_entities – Egy tábla meglévő entitásainak lekérdezése OData-szűrőkkel.
  • get_entity – Adott entitás lekérése egy táblából partíció és sorkulcs alapján.
  • upsert_entity – Egy tábla egy entitásának egyesítése vagy cseréje, vagy ha az entitás nem létezik, beszúrja az entitást.
    • UpdateMode.MERGE új tulajdonságokat ad hozzá egy meglévő entitáshoz, amely nem törli a meglévő tulajdonságokat
    • UpdateMode.REPLACE lecseréli a meglévő entitást az adott entitásra, és törli az elküldött entitásban nem szereplő meglévő tulajdonságokat

Példák

A következő szakaszok számos kódrészletet biztosítanak, amelyek a leggyakoribb Table-feladatokat fedik le, többek között az alábbiakat:

Tábla létrehozása

Hozzon létre egy táblát a fiókjában, és szerezzen be egy TableClient műveletet az újonnan létrehozott táblán:

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)

Entitások létrehozása

Entitások létrehozása a táblában:

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)

Entitások lekérdezése

Entitások lekérdezése a táblában:

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

Választható konfiguráció

Az opcionális kulcsszóargumentumok az ügyfél és a művelet szintjén is átadhatók. Az Azure-Core referenciadokumentációja többek között az újrapróbálkozásokhoz, a naplózáshoz, az átviteli protokollokhoz és egyebekhez elérhető konfigurációkat ismerteti.

Szabályzatkonfiguráció újrapróbálkozásának megkísérlése

Az újrapróbálkozási szabályzat konfigurálásához használja az alábbi kulcsszóargumentumokat az ügyfél példányosításakor:

  • retry_total (int): Az engedélyezni kívánt újrapróbálkozások teljes száma. Elsőbbséget élvez a többi számlálóval szemben. Adja meg, retry_total=0 ha nem szeretne újrapróbálkolni a kérésekkel. Alapértelmezés szerint 10.
  • retry_connect (int): Hány, kapcsolattal kapcsolatos hibát kell újrapróbálkoznia. Alapértelmezés szerint 3.
  • retry_read (int): Hányszor kell újrapróbálkoznia az olvasási hibákon. Alapértelmezés szerint 3.
  • retry_status (int): Hányszor kell újrapróbálkoznia a hibás állapotkódokkal. Alapértelmezés szerint 3.
  • retry_to_secondary (bool): Azt jelzi, hogy a kérést újra meg kell-e próbálni másodlagosra, ha lehet. Ezt csak az RA-GRS-fiókok esetében szabad engedélyezni, és az esetlegesen elavult adatok kezelhetők. Az alapértelmezett érték: False.

Egyéb ügyfél-/műveletenkénti konfiguráció

Egyéb választható konfigurációs kulcsszóargumentumok, amelyek megadhatók az ügyfélen vagy műveletenként.

Ügyfél kulcsszóargumentumai:

  • connection_timeout (int): Igény szerint másodpercben beállítja a kapcsolódási és olvasási időtúllépési értéket.
  • transport (Any): Felhasználó által biztosított átvitel a HTTP-kérés elküldéséhez.

Műveletenkénti kulcsszóargumentumok:

  • raw_response_hook (hívható): A megadott visszahívás a szolgáltatástól kapott választ használja.
  • raw_request_hook (hívható): A megadott visszahívás a kérést használja a szolgáltatásba való küldés előtt.
  • client_request_id (str): Nem kötelező, hogy a felhasználó meghatározta a kérést.
  • user_agent (str): Hozzáfűzi az egyéni értéket a kéréssel elküldendő felhasználói ügynök fejlécéhez.
  • logging_enable (bool): Engedélyezi a naplózást a HIBAKERESÉS szintjén. Alapértelmezés szerint Hamis. Ügyfélszinten is átadható, hogy minden kéréshez engedélyezve legyen.
  • headers (dict): Adja meg az egyéni fejléceket kulcsként, értékpárként. Pl. headers={'CustomValue': value}

Hibaelhárítás

Általános kérdések

Az Azure Tables-ügyfelek kivételeket emelnek ki az Azure Core-ban. Amikor a Python SDK-val használja az Azure-táblakódtárat, a szolgáltatás által visszaadott hibák ugyanazon a HTTP-állapotkódon keresztül válaszolnak a REST API-kérésekre . A Table Service műveletei HttpResponseError hasznos hibakódokkal jeleznek hibát.

Ha például olyan táblát próbál létrehozni, amely már létezik, a rendszer "Ütközés" hibaüzenetet 409 ad vissza.

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

Naplózás

Ez a kódtár a szabványos naplózási kódtárat használja a naplózáshoz. A HTTP-munkamenetekkel (URL-címekkel, fejlécekkel stb.) kapcsolatos alapvető információkat az INFO szinten naplózza a rendszer.

A hibakeresési szint részletes naplózása, beleértve a kérelem-/választörzseket és a nem felügyelt fejléceket, engedélyezhető az ügyfélen a logging_enable következő argumentummal:

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)

Hasonlóképpen logging_enable engedélyezheti a részletes naplózást egyetlen művelethez, még akkor is, ha nincs engedélyezve az ügyfél számára:

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

Következő lépések

Ismerkedés a táblázatmintákkal.

Számos Azure Tables Python SDK-minta érhető el az SDK GitHub-adattárában. Ezek a minták példakódot biztosítanak a táblák használata során gyakran előforduló további forgatókönyvekhez.

Gyakori forgatókönyvek

Ezek a kódminták az Azure Tables ügyfélkódtárával kapcsolatos gyakori forgatókönyvműveleteket mutatják be. A minták aszinkron verziói (a _async hozzáfűzött Python-mintafájlok) aszinkron műveleteket mutatnak.

További dokumentáció

Az Azure Tables részletesebb dokumentációját a docs.microsoft.com azure tables dokumentációjában találja.

Ismert problémák

A Cosmos DB-táblavégpontokhoz kapcsolódó, jelenleg ismert problémák listáját itt találja.

Közreműködés

A projektben szívesen fogadjuk a hozzájárulásokat és a javaslatokat. A legtöbb hozzájáruláshoz el kell fogadnia egy Közreműködői licencszerződést (CLA-t), amelyben kijelenti, hogy jogosult arra, hogy ránk ruházza hozzájárulása felhasználási jogát, és ezt ténylegesen meg is teszi. További részletekért lásd: https://cla.microsoft.com.

A lekéréses kérelmek elküldésekor egy CLA-robot automatikusan meghatározza, hogy kell-e biztosítania CLA-t, és megfelelően kitölti a lekéréses kérelmet (például címke, megjegyzés). Egyszerűen csak kövesse a robot által megadott utasításokat. Ezt csak egyszer kell elvégeznie az összes olyan tárházban, amely a CLA-t használja.

A projekt a Microsoft nyílt forráskódú projekteket szabályozó etikai kódexe, a Microsoft Open Source Code of Conduct hatálya alá esik. További információkért lásd a viselkedési szabályzattal kapcsolatos gyakori kérdéseket , vagy vegye fel a kapcsolatot opencode@microsoft.com az esetleges további kérdésekkel vagy megjegyzésekkel.

Megjelenések