Aracılığıyla paylaş

Python için Azure Tabloları istemci kitaplığı - sürüm 12.4.4

  • Makale

Azure Tabloları, HTTP veya HTTPS kullanarak kimliği doğrulanmış çağrılar aracılığıyla dünyanın her yerinden erişilebilen bir NoSQL veri depolama hizmetidir. Tablolar, eklenen veri miktarını desteklemek için gerektiğinde ölçeklendirilir ve karmaşık olmayan erişimle verilerin depolanmasına olanak sağlar. Azure Tabloları istemcisi, Azure Depolama veya Cosmos hesaplarına erişmek için kullanılabilir. Bu belge öğesini kapsar azure-data-tables.

Bu paketin artık kullanımdan kaldırılmış olan bir paketin yerini azure-cosmosdb-tables aldığına dikkat edin. Diğer ayrıntılar için bkz. geçiş kılavuzu .

Kaynak kodu | Paket (PyPI) | Paket (Conda) | API başvuru belgeleri | Örnekleri

Bildirim

Python 2.7 için Azure SDK Python paketleri desteği 01 Ocak 2022'de sona erdi. Daha fazla bilgi ve soru için lütfen bu paketi kullanmak için https://github.com/Azure/azure-sdk-for-python/issues/20691Python 3.7 veya üzeri gereklidir konusuna bakın. Daha fazla ayrıntı için bkz. Python için Azure SDK sürüm desteği ilkesi.

Başlarken

Azure Tabloları SDK'sı bir Azure Depolama veya CosmosDB hesabına erişebilir.

Önkoşullar

Hesap oluşturma

Paketi yükleme

Python için Azure Tabloları istemci kitaplığını pip ile yükleyin:

pip install azure-data-tables

İstemci oluşturma

Azure Tabloları kitaplığı iki tür kaynakla etkileşim kurmanızı sağlar:

  • hesabınızdaki tablolar
  • bu tabloların içindeki varlıklar. Bu kaynaklarla etkileşim bir istemci örneğiyle başlar. İstemci nesnesi oluşturmak için hesabın tablo hizmeti uç noktası URL'sine ve hesaba erişmenizi sağlayan bir kimlik bilgilerine ihtiyacınız olacaktır. , endpoint Depolama hesabınızın sayfasında Azure Portal'da "Erişim Anahtarları" bölümünün altında veya aşağıdaki Azure CLI komutunu çalıştırarak bulunabilir:
# Get the table service URL for the account
az storage account show -n mystorageaccount -g MyResourceGroup --query "primaryEndpoints.table"

Hesap URL'sini aldıktan sonra, hizmet istemcisini oluşturmak için kullanılabilir:

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

Tablo hizmeti URL'leri ve Azure Depolama için özel etki alanı adlarını yapılandırma hakkında daha fazla bilgi için resmi belgeleri gözden geçirin

Kimlik bilgisi türleri

Parametre credential , kullanmak istediğiniz yetkilendirme türüne bağlı olarak bir dizi farklı biçimde sağlanabilir. Tablolar kitaplığı aşağıdaki yetkilendirmeleri destekler:

  • Paylaşılan Anahtar
  • Bağlantı Dizesi
  • Paylaşılan Erişim İmza Belirteci
Paylaşılan anahtardan istemci oluşturma

Hesap paylaşılan anahtarı (diğer adıyla hesap anahtarı veya erişim anahtarı) kullanmak için anahtarı dize olarak sağlayın. Bu, Azure Portal'daki depolama hesabınızda "Erişim Anahtarları" bölümünün altında veya aşağıdaki Azure CLI komutunu çalıştırarak bulunabilir:

az storage account keys list -g MyResourceGroup -n MyStorageAccount

İstemcinin kimliğini doğrulamak için kimlik bilgisi parametresi olarak anahtarını kullanın:

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)
İstemciyi bir bağlantı dizesinden oluşturma

Kullanım örneğinize ve yetkilendirme yönteminize bağlı olarak, hesap URL'sini ve kimlik bilgilerini ayrı olarak sağlamak yerine bağlantı dizesiyle bir istemci örneği başlatmayı tercih edebilirsiniz. Bunu yapmak için bağlantı dizesini istemcinin from_connection_string sınıf yöntemine geçirin. Bağlantı dizesi Azure Portal'daki depolama hesabınızda "Erişim Anahtarları" bölümünde veya aşağıdaki Azure CLI komutuyla bulunabilir:

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)
SAS belirtecinden istemci oluşturma

Paylaşılan erişim imzası (SAS) belirteci kullanmak için belirteci dize olarak sağlayın. Hesap URL'niz SAS belirtecini içeriyorsa kimlik bilgisi parametresini atayın. Azure Portal'dan Paylaşılan erişim imzası altında bir SAS belirteci oluşturabilir veya işlevlerden birini generate_*_sas() kullanarak hesap veya tablo için sas belirteci oluşturabilirsiniz:

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

Önemli kavramlar

Tablo hizmetinin yaygın kullanımları:

  • Web ölçekli uygulamalara hizmet verebilen yapılandırılmış verilerin TB depolaması
  • Karmaşık birleşimler, yabancı anahtarlar veya saklı yordamlar gerektirmeyen ve hızlı erişim için normalleştirilebilen veri kümelerini depolama
  • Kümelenmiş dizin kullanarak hızlı veri sorgulaması
  • OData protokolü ve LINQ filtre ifadelerini kullanarak verilere erişme

Aşağıdaki bileşenler Azure Tablolar Hizmeti'ni oluşturur:

  • Hesap
  • Hesap içinde bir varlık kümesi içeren bir tablo
  • Tablo içindeki bir varlık, sözlük olarak

Python için Azure Tabloları istemci kitaplığı, ayrılmış bir istemci nesnesi kullanarak bu bileşenlerin her biriyle etkileşim kurmanızı sağlar.

İstemciler

Tablo Hizmeti'nin çeşitli bileşenleriyle etkileşime geçmek için iki farklı istemci sağlanır:

  1. TableServiceClient -
    • Hesap ayarını alma ve ayarlama
    • Hesap içindeki tabloları sorgular, oluşturur ve siler.
    • TableClient yöntemini kullanarak belirli bir tabloya erişmek için bir get_table_client alın.
  2. TableClient -
    • Belirli bir tabloyla etkileşim kurar (henüz mevcut olması gerekmez).
    • Belirtilen tabloda varlık oluşturma, silme, sorgulama ve upsert varlıkları oluşturma.
    • Belirtilen tablonun kendisini oluşturun veya silin.

Varlıklar

Varlıklar satırlara benzer. Bir varlığın bir PartitionKey, ve RowKeybir özellik kümesi vardır. Özellik, sütuna benzer bir ad değer çiftidir. Tablodaki her varlığın aynı özelliklere sahip olması gerekmez. Varlıklar örnek olarak aşağıdaki gibi sözlükler olarak gösterilebilir:

entity = {
    'PartitionKey': 'color',
    'RowKey': 'brand',
    'text': 'Marker',
    'color': 'Purple',
    'price': '5'
}
  • create_entity - Tabloya varlık ekleyin.
  • delete_entity - Tablodan bir varlığı silin.
  • update_entity - Var olan varlığı birleştirerek veya değiştirerek varlığın bilgilerini güncelleştirin.
    • UpdateMode.MERGE var olan bir varlığa yeni özellikler ekler ve var olan özellikleri silmez
    • UpdateMode.REPLACE , gönderilen varlığa dahil olmayan mevcut özellikleri silerek mevcut varlığı verilen varlıkla değiştirir
  • query_entities - OData filtrelerini kullanarak bir tablodaki mevcut varlıkları sorgular.
  • get_entity - Bölüm ve satır anahtarına göre bir tablodan belirli bir varlığı alın.
  • upsert_entity - Tablodaki bir varlığı birleştirin veya değiştirin ya da varlık yoksa varlığı ekler.
    • UpdateMode.MERGE var olan bir varlığa yeni özellikler ekler ve var olan özellikleri silmez
    • UpdateMode.REPLACE , gönderilen varlığa dahil olmayan mevcut özellikleri silerek mevcut varlığı verilen varlıkla değiştirir

Örnekler

Aşağıdaki bölümlerde, aşağıdakiler dahil olmak üzere en yaygın Tablo görevlerinden bazılarını kapsayan çeşitli kod parçacıkları sağlanır:

Tablo oluşturma

Hesabınızda bir tablo oluşturun ve yeni oluşturulan tabloda işlem gerçekleştirmek için bir TableClient alı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)

Varlıkları oluşturma

Tabloda varlık oluşturma:

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)

Varlıkları sorgulama

Tablodaki varlıkları sorgulama:

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

İsteğe Bağlı Yapılandırma

İsteğe bağlı anahtar sözcük bağımsız değişkenleri istemci ve işlem başına düzeyinde geçirilebilir. Azure-core başvuru belgelerinde yeniden denemeler, günlüğe kaydetme, aktarım protokolleri ve daha fazlası için kullanılabilir yapılandırmalar açıklanmaktadır.

İlke yapılandırmasını yeniden deneme

Yeniden deneme ilkesini yapılandırmak için bir istemci örneği oluştururken aşağıdaki anahtar sözcük bağımsız değişkenlerini kullanın:

  • retry_total (int): İzin vermek için toplam yeniden deneme sayısı. Diğer sayılardan önceliklidir. İstekleri retry_total=0 yeniden denemek istemiyorsanız geçiş yapın. Varsayılan değer 10'dır.
  • retry_connect (int): Bağlantıyla ilgili kaç hatanın yeniden denenebileceği. Varsayılan değer 3'tir.
  • retry_read (int): Okuma hatalarında yeniden deneme sayısı. Varsayılan değer 3'tir.
  • retry_status (int): Hatalı durum kodları üzerinde yeniden deneme sayısı. Varsayılan değer 3'tir.
  • retry_to_secondary (bool): mümkünse isteğin ikincil olarak yeniden denenip denenmeyeceği. Bu yalnızca RA-GRS hesaplarının etkinleştirilmesi gerekir ve eski olabilecek veriler işlenebilir. Varsayılan olarak olarak Falsegösterilir.

Diğer istemci /işlem başına yapılandırma

İstemcide veya işlem başına belirtilebilen diğer isteğe bağlı yapılandırma anahtar sözcük bağımsız değişkenleri.

İstemci anahtar sözcük bağımsız değişkenleri:

  • connection_timeout (int): İsteğe bağlı olarak bağlanma ve okuma zaman aşımı değerini saniye olarak ayarlar.
  • transport (Any): HTTP isteğini göndermek için kullanıcı tarafından sağlanan aktarım.

İşlem başına anahtar sözcük bağımsız değişkenleri:

  • raw_response_hook (çağrılabilir): Verilen geri arama, hizmetten döndürülen yanıtı kullanır.
  • raw_request_hook (çağrılabilir): Verilen geri arama, hizmete gönderilmeden önce isteği kullanır.
  • client_request_id (str): İsteğin kullanıcı tarafından belirtilen isteğe bağlı kimliği.
  • user_agent (str): İstekle birlikte gönderilecek kullanıcı aracısı üst bilgisine özel değeri ekler.
  • logging_enable (bool): HATA AYıKLAMA düzeyinde günlüğe kaydetmeyi etkinleştirir. Varsayılan değer False'tur. Tüm istekler için etkinleştirmek üzere istemci düzeyinde de geçirilebilir.
  • headers (dict): Özel üst bilgileri anahtar, değer çiftleri olarak geçirin. Örneğin. headers={'CustomValue': value}

Sorun giderme

Genel

Azure Tabloları istemcileri , Azure Core'da tanımlanan özel durumları tetikler. Python SDK'sını kullanarak Azure tablo kitaplığıyla etkileşime geçtiğiniz zaman, hizmet tarafından döndürülen hatalar REST API istekleri için aynı HTTP durum kodlarıyla yanıt verir. Tablo hizmeti işlemleri yararlı hata kodlarıyla bir HttpResponseError hata oluşturur.

Örnekler için, zaten var olan bir tablo oluşturmaya çalışırsanız, "Çakışma" belirten bir 409 hata döndürülür.

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

Günlüğe Kaydetme

Bu kitaplık , günlüğe kaydetme için standart günlük kitaplığını kullanır. HTTP oturumları (URL'ler, üst bilgiler vb.) hakkındaki temel bilgiler BİlGİ düzeyinde günlüğe kaydedilir.

İstek/yanıt gövdeleri ve kaydedilmemiş üst bilgiler de dahil olmak üzere ayrıntılı HATA AYıKLAMA düzeyi günlüğü, bir istemcide şu bağımsız değişkenle logging_enable etkinleştirilebilir:

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)

Benzer şekilde, logging_enable istemci için etkinleştirilmemiş olsa bile tek bir işlem için ayrıntılı günlüğe kaydetmeyi etkinleştirebilir:

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

Sonraki adımlar

Tablo örneklerimizi kullanmaya başlayın.

SDK'nın GitHub deposunda kullanabileceğiniz çeşitli Azure Tabloları Python SDK örnekleri vardır. Bu örnekler, Tablolar ile çalışırken yaygın olarak karşılaşılan ek senaryolar için örnek kod sağlar.

Genel Senaryolar

Bu kod örnekleri, Azure Tabloları istemci kitaplığıyla yapılan yaygın senaryo işlemlerini gösterir. Örneklerin zaman uyumsuz sürümleri (_async ekli Python örnek dosyaları) zaman uyumsuz işlemleri gösterir.

Diğer belgeler

Azure Tabloları hakkında daha kapsamlı belgeler için docs.microsoft.com ile ilgili Azure Tabloları belgelerine bakın.

Bilinen Sorunlar

Cosmos DB tablo uç noktalarıyla ilgili bilinen sorunların listesi burada bulunabilir.

Katkıda bulunma

Bu proje, katkı ve önerilere açıktır. Çoğu durumda, sağladığınız katkıyı kullanmamız için bize hak tanıma hakkına sahip olduğunuzu ve bu hakkı bize tanıdığınızı bildiren bir Katkıda Bulunan Lisans Sözleşmesi’ni (CLA) kabul etmeniz gerekir. Ayrıntılar için bkz. https://cla.microsoft.com.

Bir çekme isteği gönderdiğinizde, CLA robotu bir CLA sağlamanız gerekip gerekmediğini otomatik olarak belirler ve çekme isteğini uygun şekilde donatır (örn. etiket, açıklama). Robot tarafından sağlanan yönergeleri izlemeniz yeterlidir. Bu işlemi, CLA’mızı kullanarak tüm depolarda yalnızca bir kere yapmanız gerekir.

Bu proje Microsoft Open Source Code of Conduct (Microsoft Açık Kaynak Kullanım Kuralları) belgesinde listelenen kurallara uygundur. Daha fazla bilgi için Kullanım Kuralları SSS bölümüne bakın veya ek sorularınız veya yorumlarınızla iletişime geçin opencode@microsoft.com .

İzlenimler