Condividi tramite

Libreria client tabelle di Azure per Python - versione 12.4.4

  • Articolo

Tabelle di Azure è un servizio di archiviazione dati NoSQL accessibile da qualsiasi parte del mondo tramite chiamate autenticate tramite HTTP o HTTPS. Le tabelle vengono ridimensionate in base alle esigenze per supportare la quantità di dati inseriti e consentono l'archiviazione dei dati con accesso non complesso. Il client tabelle di Azure può essere usato per accedere agli account di Archiviazione di Azure o Cosmos. In questo documento viene illustrato azure-data-tables.

Si noti che questo pacchetto è una sostituzione per azure-cosmosdb-tables il quale è ora deprecato. Per altri dettagli, vedere la guida alla migrazione .

Codice | sorgentePacchetto (PyPI) | Pacchetto (Conda) | Documentazione | di riferimento sulle APICampioni

Dichiarazione di non responsabilità

Il supporto dei pacchetti Python di Azure SDK per Python 2.7 è terminato il 01 gennaio 2022. Per altre informazioni e domande, vedere https://github.com/Azure/azure-sdk-for-python/issues/20691Python 3.7 o versione successiva per usare questo pacchetto. Per altre informazioni, vedere Criteri di supporto per la versione di Azure SDK per Python.

Introduzione

Azure Tables SDK può accedere a un account di Archiviazione di Azure o CosmosDB.

Prerequisiti

Creare un account

Installare il pacchetto

Installare la libreria client tabelle di Azure per Python con pip:

pip install azure-data-tables

Creare il client

La libreria tabelle di Azure consente di interagire con due tipi di risorse:

  • le tabelle nell'account
  • le entità all'interno di tali tabelle. L'interazione con queste risorse inizia con un'istanza di un client. Per creare un oggetto client, è necessario l'URL dell'endpoint del servizio tabelle dell'account e una credenziale che consenta di accedere all'account. È endpoint possibile trovare nella pagina dell'account di archiviazione nel portale di Azure nella sezione "Chiavi di accesso" o eseguendo il comando dell'interfaccia della riga di comando di Azure seguente:
# Get the table service URL for the account
az storage account show -n mystorageaccount -g MyResourceGroup --query "primaryEndpoints.table"

Dopo aver ottenuto l'URL dell'account, può essere usato per creare il client del servizio:

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

Per altre informazioni sull'URL del servizio tabelle e su come configurare i nomi di dominio personalizzati per Archiviazione di Azure, vedere la documentazione ufficiale

Tipi di credenziali

Il credential parametro può essere fornito in diversi formati, a seconda del tipo di autorizzazione che si desidera utilizzare. La libreria Tables supporta le autorizzazioni seguenti:

  • Chiave condivisa
  • Connection String (Stringa di connessione)
  • Token di firma di accesso condiviso
Creazione del client da una chiave condivisa

Per usare una chiave condivisa dell'account (nota anche come chiave dell'account o chiave di accesso), specificare la chiave come stringa. Questo è disponibile nell'account di archiviazione nel portale di Azure nella sezione "Chiavi di accesso" o eseguendo il comando seguente dell'interfaccia della riga di comando di Azure:

az storage account keys list -g MyResourceGroup -n MyStorageAccount

Usare la chiave come parametro delle credenziali per autenticare il 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)
Creazione del client da una stringa di connessione

A seconda del caso d'uso e del metodo di autorizzazione, può essere preferibile inizializzare un'istanza client con una stringa di connessione anziché specificare separatamente l'URL e le credenziali dell'account. A tale scopo, passare la stringa di connessione al metodo di classe del from_connection_string client. La stringa di connessione è disponibile nell'account di archiviazione nel portale di Azure nella sezione "Chiavi di accesso" o con il comando dell'interfaccia della riga di comando di Azure seguente:

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)
Creazione del client da un token di firma di accesso condiviso

Per usare un token di firma di accesso condiviso (SAS), specificare il token come stringa. Se l'URL dell'account include il token di firma di accesso condiviso, omettere il parametro credential. È possibile generare un token di firma di accesso condiviso dal portale di Azure in Firma di accesso condiviso o usare una delle funzioni per creare un token di firma di generate_*_sas() accesso condiviso per l'account o la tabella:

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

Concetti chiave

Uso comune del servizio tabelle incluso:

  • Archiviazione di terabyte di dati strutturati in grado di servire applicazioni su scala Web
  • L'archiviazione di set di dati che non richiedono join complessi, chiavi esterne o stored procedure e può essere de normalizzata per l'accesso rapido
  • Esecuzione rapida di query sui dati mediante un indice cluster
  • Accesso ai dati tramite il protocollo OData e le espressioni di filtro LINQ

I componenti seguenti costituiscono il servizio tabelle di Azure:

  • Account
  • Tabella all'interno dell'account, che contiene un set di entità
  • Entità all'interno di una tabella, come dizionario

La libreria client tabelle di Azure per Python consente di interagire con ognuno di questi componenti tramite l'uso di un oggetto client dedicato.

Client

Vengono forniti due client diversi per interagire con i vari componenti del servizio tabelle:

  1. TableServiceClient -
    • Ottenere e impostare l'impostazione dell'account
    • Eseguire query, creare ed eliminare tabelle all'interno dell'account.
    • Ottenere un TableClient oggetto per accedere a una tabella specifica usando il get_table_client metodo .
  2. TableClient -
    • Interagisce con una tabella specifica (che non è ancora presente).
    • Creare, eliminare, eseguire query e upsert entità all'interno della tabella specificata.
    • Creare o eliminare la tabella specificata.

Entità

Le entità sono simili alle righe. Un'entità ha un PartitionKeyoggetto , un RowKeye un set di proprietà. Una proprietà è una coppia nome-valore, simile a una colonna. Ogni entità in una tabella non deve avere le stesse proprietà. Le entità possono essere rappresentate come dizionari come nell'esempio seguente:

entity = {
    'PartitionKey': 'color',
    'RowKey': 'brand',
    'text': 'Marker',
    'color': 'Purple',
    'price': '5'
}
  • create_entity : aggiungere un'entità alla tabella.
  • delete_entity : eliminare un'entità dalla tabella.
  • update_entity : aggiornare le informazioni di un'entità mediante l'unione o la sostituzione dell'entità esistente.
    • UpdateMode.MERGE aggiungerà nuove proprietà a un'entità esistente che non eliminerà le proprietà esistenti
    • UpdateMode.REPLACE sostituirà l'entità esistente con quella specificata, eliminando eventuali proprietà esistenti non incluse nell'entità inviata
  • query_entities : eseguire query sulle entità esistenti in una tabella usando filtri OData.
  • get_entity : ottenere un'entità specifica da una tabella per chiave di partizione e riga.
  • upsert_entity : consente di unire o sostituire un'entità in una tabella oppure, se l'entità non esiste, inserisce l'entità.
    • UpdateMode.MERGE aggiungerà nuove proprietà a un'entità esistente che non eliminerà le proprietà esistenti
    • UpdateMode.REPLACE sostituirà l'entità esistente con quella specificata, eliminando eventuali proprietà esistenti non incluse nell'entità inviata

Esempio

Le sezioni seguenti forniscono diversi frammenti di codice che illustrano alcune delle attività di tabella più comuni, tra cui:

Creazione di una tabella

Creare una tabella nell'account e ottenere un TableClient oggetto per eseguire operazioni sulla tabella appena creata:

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)

Creazione di entità

Creare entità nella tabella:

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 di entità

Esecuzione di query sulle entità nella tabella:

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

Configurazione facoltativa

Gli argomenti di parole chiave facoltativi possono essere passati al client e al livello di operazione. La documentazione di riferimento di azure-core descrive le configurazioni disponibili per tentativi, registrazione, protocolli di trasporto e altro ancora.

Configurazione dei criteri di ripetizione

Usare gli argomenti della parola chiave seguenti quando si crea un'istanza di un client per configurare i criteri di ripetizione dei tentativi:

  • retry_total (int): numero totale di tentativi consentiti. Ha la precedenza su altri conteggi. retry_total=0 Passare se non si vuole riprovare alle richieste. Il valore predefinito è 10.
  • retry_connect (int): numero di errori relativi alla connessione da ritentare. Il valore predefinito è 3.
  • retry_read (int): numero di tentativi di ripetizione degli errori di lettura. Il valore predefinito è 3.
  • retry_status (int): numero di tentativi per i codici di stato non corretti. Il valore predefinito è 3.
  • retry_to_secondary (bool): indica se la richiesta deve essere ritentata a secondaria, se possibile. Questa opzione deve essere abilitata solo per gli account RA-GRS e i dati potenzialmente non aggiornati possono essere gestiti. Il valore predefinito è False.

Altra configurazione client/per operazione

Altri argomenti di parole chiave di configurazione facoltativi che possono essere specificati nel client o per ogni operazione.

Argomenti di parole chiave client:

  • connection_timeout (int): imposta facoltativamente il valore di timeout di connessione e lettura, espresso in secondi.
  • transport (Any): trasporto fornito dall'utente per inviare la richiesta HTTP.

Argomenti per parola chiave per operazione:

  • raw_response_hook (chiamabile): il callback specificato usa la risposta restituita dal servizio.
  • raw_request_hook (chiamabile): il callback specificato usa la richiesta prima di essere inviata al servizio.
  • client_request_id (str): identificazione specificata dall'utente facoltativo della richiesta.
  • user_agent (str): aggiunge il valore personalizzato all'intestazione user-agent da inviare con la richiesta.
  • logging_enable (bool): abilita la registrazione a livello DI DEBUG. Il valore predefinito è False. Può anche essere passato a livello di client per abilitarlo per tutte le richieste.
  • intestazioni (dict): passare intestazioni personalizzate come coppie chiave-valore. Ad esempio headers={'CustomValue': value}

Risoluzione dei problemi

Generale

I client tabelle di Azure generano eccezioni definite in Azure Core. Quando si interagisce con la libreria tabelle di Azure con Python SDK, gli errori restituiti dal servizio rispondono agli stessi codici di stato HTTP per le richieste dell'API REST . Le operazioni del servizio tabelle genereranno un errore HttpResponseError con codici di errore utili.

Ad esempio, se si tenta di creare una tabella già esistente, viene restituito un 409 errore che indica "Conflitto".

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

Registrazione

Questa libreria usa la libreria di registrazione standard per la registrazione. Le informazioni di base sulle sessioni HTTP (URL, intestazioni e così via) vengono registrate a livello di INFO.

La registrazione dettagliata a livello di DEBUG, inclusi i corpi di richiesta/risposta e le intestazioni non contrassegnate, può essere abilitata in un client con l'argomento 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)

Analogamente, logging_enable può abilitare la registrazione dettagliata per una singola operazione, anche quando non è abilitata per il client:

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

Passaggi successivi

Introduzione agli esempi di tabella.

Sono disponibili diversi esempi di Python SDK per tabelle di Azure nel repository GitHub dell'SDK. Questi esempi forniscono codice di esempio per scenari aggiuntivi comunemente rilevati durante l'uso delle tabelle.

Scenari comuni

Questi esempi di codice mostrano operazioni comuni sullo scenario con la libreria client tabelle di Azure. Le versioni asincrone degli esempi (i file di esempio Python aggiunti con _async) mostrano operazioni asincrone.

Documentazione aggiuntiva

Per una documentazione più completa sulle tabelle di Azure, vedere la documentazione sulle tabelle di Azure in docs.microsoft.com.

Problemi noti

Un elenco dei problemi attualmente noti relativi agli endpoint di tabella di Cosmos DB è disponibile qui.

Contributo

In questo progetto sono benvenuti i contributi e i suggerimenti. Per la maggior parte dei contenuti è necessario sottoscrivere un contratto di licenza di collaborazione (CLA, Contributor License Agreement) che stabilisce che l'utente ha il diritto di concedere, e di fatto concede a Microsoft i diritti d'uso del suo contributo. Per informazioni dettagliate, vedere https://cla.microsoft.com.

Quando si invia una richiesta pull, un bot CLA determina automaticamente se è necessario specificare un contratto CLA e completare la richiesta pull in modo appropriato (ad esempio con un'etichetta e un commento). Seguire le istruzioni specificate dal bot. È sufficiente eseguire questa operazione una sola volta per tutti i repository che usano il contratto CLA Microsoft.

Questo progetto ha adottato il Codice di comportamento di Microsoft per l'open source. Per altre informazioni, vedere Code of Conduct FAQ (Domande frequenti sul Codice di comportamento Open Source di Microsoft) oppure contattare opencode@microsoft.com per eventuali altre domande o commenti.

Impression