Udostępnij za pośrednictwem

Biblioteka klienta usługi Azure Tables dla języka Python — wersja 12.4.4

  • Artykuł

Azure Tables to usługa magazynu danych NoSQL, do którego można uzyskać dostęp z dowolnego miejsca na świecie za pośrednictwem uwierzytelnionych wywołań przy użyciu protokołu HTTP lub HTTPS. Tabele są skalowane zgodnie z potrzebami, aby obsługiwać ilość wstawionych danych i umożliwiają przechowywanie danych przy użyciu nieskomplikowanego dostępu. Klient tabel platformy Azure może służyć do uzyskiwania dostępu do kont usługi Azure Storage lub Cosmos. W tym dokumencie opisano azure-data-tables.

Należy pamiętać, że ten pakiet jest zamiennikiem, dla azure-cosmosdb-tables którego jest już przestarzałe. Aby uzyskać więcej informacji, zobacz przewodnik migracji .

Kod | źródłowyPakiet (PyPI) | Pakiet (Conda) | Dokumentacja referencyjna interfejsu | APIPróbki

Zrzeczenie odpowiedzialności

Obsługa pakietów języka Python dla zestawu Azure SDK dla języka Python 2.7 zakończyła się 1 stycznia 2022 r. Aby uzyskać więcej informacji i pytań, zobacz https://github.com/Azure/azure-sdk-for-python/issues/20691Python 3.7 lub nowszy jest wymagany do korzystania z tego pakietu. Aby uzyskać więcej informacji, zapoznaj się z zasadami obsługi wersji zestawu Azure SDK dla języka Python.

Wprowadzenie

Zestaw AZURE Tables SDK może uzyskiwać dostęp do konta usługi Azure Storage lub CosmosDB.

Wymagania wstępne

Tworzenie konta

Instalowanie pakietu

Zainstaluj bibliotekę klienta usługi Azure Tables dla języka Python za pomocą narzędzia pip:

pip install azure-data-tables

Tworzenie klienta

Biblioteka tabel platformy Azure umożliwia interakcję z dwoma typami zasobów:

  • tabele na koncie
  • jednostki w tych tabelach. Interakcja z tymi zasobami rozpoczyna się od wystąpienia klienta. Aby utworzyć obiekt klienta, potrzebny będzie adres URL punktu końcowego usługi tabel konta oraz poświadczenia umożliwiające dostęp do konta. Plik endpoint można znaleźć na stronie konta magazynu w witrynie Azure Portal w sekcji "Klucze dostępu" lub uruchamiając następujące polecenie interfejsu wiersza polecenia platformy Azure:
# Get the table service URL for the account
az storage account show -n mystorageaccount -g MyResourceGroup --query "primaryEndpoints.table"

Po utworzeniu adresu URL konta można go użyć do utworzenia klienta usługi:

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

Aby uzyskać więcej informacji na temat adresów URL usługi Table Service i sposobu konfigurowania niestandardowych nazw domen dla usługi Azure Storage, zapoznaj się z oficjalną dokumentacją

Typy poświadczeń

Parametr credential może być podany w wielu różnych formularzach, w zależności od typu autoryzacji, której chcesz użyć. Biblioteka Tables obsługuje następujące autoryzacje:

  • Klucz wspólny
  • Parametry połączenia
  • Token sygnatury dostępu współdzielonego
Tworzenie klienta na podstawie klucza współużytkowanego

Aby użyć klucza współużytkowanego konta (czyli klucza konta lub klucza dostępu), podaj klucz jako ciąg. Można to znaleźć na koncie magazynu w witrynie Azure Portal w sekcji "Klucze dostępu" lub uruchamiając następujące polecenie interfejsu wiersza polecenia platformy Azure:

az storage account keys list -g MyResourceGroup -n MyStorageAccount

Użyj klucza jako parametru poświadczeń, aby uwierzytelnić klienta:

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)
Tworzenie klienta na podstawie parametrów połączenia

W zależności od przypadku użycia i metody autoryzacji można zainicjować wystąpienie klienta przy użyciu parametrów połączenia zamiast oddzielnie podać adres URL konta i poświadczenia. W tym celu przekaż parametry połączenia do metody klasy klienta from_connection_string . Parametry połączenia można znaleźć na koncie magazynu w witrynie Azure Portal w sekcji "Klucze dostępu" lub za pomocą następującego polecenia interfejsu wiersza polecenia platformy Azure:

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)
Tworzenie klienta na podstawie tokenu SAS

Aby użyć tokenu sygnatury dostępu współdzielonego (SAS), podaj token jako ciąg. Jeśli adres URL konta zawiera token SAS, pomiń parametr poświadczeń. Token SAS można wygenerować w witrynie Azure Portal w obszarze Sygnatura dostępu współdzielonego lub użyć jednej z generate_*_sas() funkcji do utworzenia tokenu sas dla konta lub tabeli:

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

Kluczowe pojęcia

Typowe zastosowania usługi Table Service obejmują:

  • Przechowywanie tabel danych strukturalnych umożliwiających obsługę aplikacji w skali sieci Web
  • Przechowywanie zestawów danych, które nie wymagają złożonych sprzężeń, kluczy obcych lub procedur składowanych i można je znormalizować w celu zapewnienia szybkiego dostępu
  • Szybkie wykonywanie zapytań o dane przy użyciu indeksu klastrowanego
  • Uzyskiwanie dostępu do danych przy użyciu protokołu OData i wyrażeń filtru LINQ

Następujące składniki składają się na usługę Azure Tables Service:

  • Konto
  • Tabela w ramach konta, która zawiera zestaw jednostek
  • Jednostka w tabeli jako słownik

Biblioteka klienta tabel platformy Azure dla języka Python umożliwia interakcję z każdym z tych składników za pomocą dedykowanego obiektu klienta.

Klienci

Dwóch różnych klientów jest dostarczanych do interakcji z różnymi składnikami usługi Table Service:

  1. TableServiceClient -
    • Pobieranie i ustawianie ustawienia konta
    • Wykonywanie zapytań, tworzenie i usuwanie tabel w ramach konta.
    • Uzyskaj element , TableClient aby uzyskać dostęp do określonej tabeli przy użyciu get_table_client metody .
  2. TableClient -
    • Wchodzi w interakcję z określoną tabelą (która nie musi jeszcze istnieć).
    • Tworzenie, usuwanie, wykonywanie zapytań i upsert jednostek w określonej tabeli.
    • Utwórz lub usuń określoną tabelę.

Jednostki

Jednostki są podobne do wierszy. Jednostka ma PartitionKeywłaściwość , , RowKeyi zestaw właściwości. Właściwość jest parą wartości nazwy, podobną do kolumny. Każda jednostka w tabeli nie musi mieć tych samych właściwości. Jednostki mogą być reprezentowane jako słowniki, takie jak na przykład:

entity = {
    'PartitionKey': 'color',
    'RowKey': 'brand',
    'text': 'Marker',
    'color': 'Purple',
    'price': '5'
}
  • create_entity — dodawanie jednostki do tabeli.
  • delete_entity — usuwanie jednostki z tabeli.
  • update_entity — zaktualizuj informacje jednostki przez scalenie lub zastąpienie istniejącej jednostki.
    • UpdateMode.MERGE Spowoduje dodanie nowych właściwości do istniejącej jednostki, która nie spowoduje usunięcia istniejących właściwości
    • UpdateMode.REPLACE zastąpi istniejącą jednostkę daną, usuwając wszystkie istniejące właściwości, które nie zostały uwzględnione w przesłanej jednostce
  • query_entities — wykonywanie zapytań o istniejące jednostki w tabeli przy użyciu filtrów OData.
  • get_entity — pobierz konkretną jednostkę z tabeli według partycji i klucza wiersza.
  • upsert_entity — scal lub zastąp jednostkę w tabeli albo jeśli jednostka nie istnieje, wstawia jednostkę.
    • UpdateMode.MERGE Spowoduje dodanie nowych właściwości do istniejącej jednostki, która nie spowoduje usunięcia istniejących właściwości
    • UpdateMode.REPLACE zastąpi istniejącą jednostkę daną, usuwając wszystkie istniejące właściwości, które nie zostały uwzględnione w przesłanej jednostce

Przykłady

Poniższe sekcje zawierają kilka fragmentów kodu obejmujących niektóre z najbardziej typowych zadań tabeli, w tym:

Tworzenie tabeli

Utwórz tabelę na koncie i pobierz element TableClient , aby wykonać operacje na nowo utworzonej tabeli:

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)

Tworzenie jednostek

Utwórz jednostki w tabeli:

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)

Wykonywanie zapytań o jednostki

Wykonywanie zapytań o jednostki w tabeli:

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

Konfiguracja opcjonalna

Opcjonalne argumenty słów kluczowych można przekazać na poziomie klienta i na poziomie operacji. W dokumentacji referencyjnej platformy Azure opisano dostępne konfiguracje ponownych prób, rejestrowania, protokołów transportowych i nie tylko.

Konfiguracja zasad ponawiania prób

Użyj następujących argumentów słów kluczowych podczas tworzenia wystąpienia klienta, aby skonfigurować zasady ponawiania prób:

  • retry_total (int): całkowita liczba ponownych prób do zezwolenia. Ma pierwszeństwo przed innymi liczbami. Przekaż polecenie , retry_total=0 jeśli nie chcesz ponowić próby na żądaniach. Wartość domyślna to 10.
  • retry_connect (int): ile błędów związanych z połączeniem należy ponowić próbę. Wartość domyślna to 3.
  • retry_read (int): ile razy należy ponowić próbę w przypadku błędów odczytu. Wartość domyślna to 3.
  • retry_status (int): ile razy należy ponowić próbę w przypadku nieprawidłowych kodów stanu. Wartość domyślna to 3.
  • retry_to_secondary (bool): czy żądanie powinno zostać ponowione do pomocniczej, jeśli jest możliwe. Należy włączyć tylko konta RA-GRS, a potencjalnie nieaktualne dane mogą być obsługiwane. Wartość domyślna to False.

Inna konfiguracja klienta /na operację

Inne opcjonalne argumenty słowa kluczowego konfiguracji, które można określić na kliencie lub na operację.

Argumenty słów kluczowych klienta:

  • connection_timeout (int): opcjonalnie ustawia wartość limitu czasu połączenia i odczytu w sekundach.
  • transport (dowolny): transport dostarczony przez użytkownika w celu wysłania żądania HTTP.

Argumenty słów kluczowych dla operacji:

  • raw_response_hook (możliwe do wywołania): Podane wywołanie zwrotne używa odpowiedzi zwróconej z usługi.
  • raw_request_hook (możliwe do wywołania): podane wywołanie zwrotne używa żądania przed wysłaniem do usługi.
  • client_request_id (str): opcjonalna identyfikacja żądania przez użytkownika opcjonalnego.
  • user_agent (str): dołącza wartość niestandardową do nagłówka user-agent, który ma zostać wysłany za pomocą żądania.
  • logging_enable (bool): włącza rejestrowanie na poziomie DEBUG. Wartość domyślna to False. Można również przekazać na poziomie klienta, aby włączyć je dla wszystkich żądań.
  • nagłówki (dict): przekazuj niestandardowe nagłówki jako pary klucz, wartość. Przykład. headers={'CustomValue': value}

Rozwiązywanie problemów

Ogólne

Klienci tabel platformy Azure zgłaszają wyjątki zdefiniowane w usłudze Azure Core. Podczas interakcji z biblioteką tabel platformy Azure przy użyciu zestawu SDK języka Python błędy zwracane przez usługę odpowiadają na te same kody stanu HTTP dla żądań interfejsu API REST . Operacje usługi Table Service będą zgłaszać HttpResponseError błąd z przydatnymi kodami błędów.

Jeśli na przykład spróbujesz utworzyć tabelę, która już istnieje, 409 zostanie zwrócony błąd wskazujący "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))

Rejestrowanie

Ta biblioteka używa standardowej biblioteki rejestrowania do rejestrowania. Podstawowe informacje o sesjach HTTP (adresach URL, nagłówkach itp.) są rejestrowane na poziomie INFORMACJI.

Szczegółowe rejestrowanie na poziomie DEBUG, w tym treści żądań/odpowiedzi i nieredagowanych nagłówków, można włączyć na kliencie z 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)

Podobnie może logging_enable włączyć szczegółowe rejestrowanie dla pojedynczej operacji, nawet jeśli nie jest włączone dla klienta:

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

Następne kroki

Rozpocznij pracę z naszymi przykładami tabel.

Kilka przykładów zestawu Sdk języka Python tabel platformy Azure jest dostępnych w repozytorium GitHub zestawu SDK. Te przykłady zawierają przykładowy kod dla dodatkowych scenariuszy często napotykanych podczas pracy z tabelami.

Typowe scenariusze

Te przykłady kodu pokazują typowe operacje scenariuszy w bibliotece klienta tabel platformy Azure. Asynchroniczne wersje przykładów (przykładowe pliki języka Python dołączone _async) pokazują operacje asynchroniczne.

Dodatkowa dokumentacja

Aby uzyskać bardziej obszerną dokumentację dotyczącą tabel platformy Azure, zobacz dokumentację dotyczącą tabel platformy Azure w docs.microsoft.com.

Znane problemy

Listę obecnie znanych problemów związanych z punktami końcowymi tabeli usługi Cosmos DB można znaleźć tutaj.

Współtworzenie

W tym projekcie zachęcamy do współtworzenia i zgłaszania sugestii. Współtworzenie w większości przypadków wymaga zgody na umowę licencyjną dotyczącą współautorów (CLA, Contributor License Agreement), zgodnie z którą współautor ma prawo udzielić i faktycznie udziela nam praw do używania wytworzonej przez siebie zawartości. Aby uzyskać szczegółowe informacje, odwiedź stronę https://cla.microsoft.com.

Po przesłaniu żądania ściągnięcia robot CLA automatycznie określi, czy musisz przekazać umowę CLA, i doda odpowiednie informacje do tego żądania (na przykład etykietę czy komentarz). Po prostu postępuj zgodnie z instrukcjami robota. Wystarczy zrobić to raz dla wszystkich repozytoriów, w przypadku których jest używana nasza umowa CLA.

W tym projekcie przyjęto Kodeks postępowania oprogramowania Open Source firmy Microsoft. Aby uzyskać więcej informacji, zobacz Często zadawane pytania dotyczące kodeksu postępowania lub skontaktuj się z opencode@microsoft.com dodatkowymi pytaniami lub komentarzami.

Wrażenia