Bagikan melalui

Pustaka klien Azure Tables untuk Python - versi 12.4.4

  • Artikel

Azure Tables adalah layanan penyimpanan data NoSQL yang dapat diakses dari mana saja di dunia melalui panggilan terautentikasi menggunakan HTTP atau HTTPS. Tabel diskalakan sesuai kebutuhan untuk mendukung jumlah data yang disisipkan, dan memungkinkan penyimpanan data dengan akses non-kompleks. Klien Azure Tables dapat digunakan untuk mengakses akun Azure Storage atau Cosmos. Dokumen ini mencakup azure-data-tables.

Harap dicatat, paket ini adalah pengganti azure-cosmosdb-tables yang sekarang tidak digunakan lagi. Lihat panduan migrasi untuk detail selengkapnya.

Kode sumber | Paket (PyPI) | Paket (Conda) | Dokumentasi | referensi APISampel

Pengelakan

Dukungan paket Azure SDK Python untuk Python 2.7 telah berakhir 01 Januari 2022. Untuk informasi dan pertanyaan lebih lanjut, silakan merujuk ke https://github.com/Azure/azure-sdk-for-python/issues/20691Python 3.7 atau yang lebih baru diperlukan untuk menggunakan paket ini. Untuk detail selengkapnya, silakan lihat kebijakan dukungan versi Azure SDK for Python.

Memulai

Azure Tables SDK dapat mengakses akun Azure Storage atau CosmosDB.

Prasyarat

Buat akun

Instal paketnya

Instal pustaka klien Azure Tables untuk Python dengan pip:

pip install azure-data-tables

Membuat klien

Pustaka Tabel Azure memungkinkan Anda berinteraksi dengan dua jenis sumber daya:

  • tabel di akun Anda
  • entitas dalam tabel tersebut. Interaksi dengan sumber daya ini dimulai dengan instans klien. Untuk membuat objek klien, Anda memerlukan URL titik akhir layanan tabel akun dan kredensial yang memungkinkan Anda mengakses akun. endpoint dapat ditemukan di halaman untuk akun penyimpanan Anda di Portal Microsoft Azure di bawah bagian "Kunci Akses" atau dengan menjalankan perintah Azure CLI berikut:
# Get the table service URL for the account
az storage account show -n mystorageaccount -g MyResourceGroup --query "primaryEndpoints.table"

Setelah Anda memiliki URL akun, URL tersebut dapat digunakan untuk membuat klien layanan:

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

Untuk informasi selengkapnya tentang URL layanan tabel dan cara mengonfigurasi nama domain kustom untuk Azure Storage, lihat dokumentasi resmi

Jenis kredensial

Parameter credential dapat disediakan dalam sejumlah formulir yang berbeda, tergantung pada jenis otorisasi yang ingin Anda gunakan. Pustaka Tabel mendukung otorisasi berikut:

  • Kunci Bersama
  • String Koneksi
  • Token Tanda Tangan Akses Bersama
Membuat klien dari kunci bersama

Untuk menggunakan kunci bersama akun (kunci akun atau kunci akses), berikan kunci sebagai string. Ini dapat ditemukan di akun penyimpanan Anda di Portal Microsoft Azure di bagian "Kunci Akses" atau dengan menjalankan perintah Azure CLI berikut:

az storage account keys list -g MyResourceGroup -n MyStorageAccount

Gunakan kunci sebagai parameter kredensial untuk mengautentikasi klien:

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)
Membuat klien dari string koneksi

Bergantung pada kasus penggunaan dan metode otorisasi, Anda mungkin lebih suka menginisialisasi instans klien dengan string koneksi alih-alih memberikan URL akun dan kredensial secara terpisah. Untuk melakukan ini, teruskan string koneksi ke metode kelas klien from_connection_string . String koneksi dapat ditemukan di akun penyimpanan Anda di Portal Microsoft Azure di bagian "Kunci Akses" atau dengan perintah Azure CLI berikut:

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)
Membuat klien dari token SAS

Untuk menggunakan token tanda tangan akses bersama (SAS), berikan token sebagai string. Jika URL akun Anda menyertakan token SAS, hilangkan parameter kredensial. Anda dapat membuat token SAS dari Portal Microsoft Azure di bawah Tanda tangan akses bersama atau menggunakan salah generate_*_sas() satu fungsi untuk membuat token sas untuk akun atau tabel:

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

Konsep utama

Penggunaan umum layanan Tabel meliputi:

  • Menyimpan TB data terstruktur yang mampu melayani aplikasi skala web
  • Menyimpan himpunan data yang tidak memerlukan gabungan kompleks, kunci asing, atau prosedur tersimpan dan dapat dinormalisasi untuk akses cepat
  • Mengkueri data dengan cepat menggunakan indeks berkluster
  • Mengakses data menggunakan protokol OData dan ekspresi filter LINQ

Komponen berikut membentuk Azure Tables Service:

  • Akun
  • Tabel dalam akun, yang berisi sekumpulan entitas
  • Entitas dalam tabel, sebagai kamus

Pustaka klien Azure Tables untuk Python memungkinkan Anda berinteraksi dengan masing-masing komponen ini melalui penggunaan objek klien khusus.

Klien

Dua klien yang berbeda disediakan untuk berinteraksi dengan berbagai komponen Layanan Tabel:

  1. TableServiceClient -
    • Mendapatkan dan mengatur pengaturan akun
    • Mengkueri, membuat, dan menghapus tabel di dalam akun.
    • TableClient Dapatkan untuk mengakses tabel tertentu menggunakan get_table_client metode .
  2. TableClient -
    • Berinteraksi dengan tabel tertentu (yang belum ada).
    • Buat, hapus, kueri, dan upsert entitas dalam tabel yang ditentukan.
    • Membuat atau menghapus tabel yang ditentukan itu sendiri.

Entitas

Entitas mirip dengan baris. Entitas memiliki PartitionKey, , RowKeydan sekumpulan properti. Properti adalah pasangan nilai nama, mirip dengan kolom. Setiap entitas dalam tabel tidak perlu memiliki properti yang sama. Entitas dapat direpresentasikan sebagai kamus seperti ini sebagai contoh:

entity = {
    'PartitionKey': 'color',
    'RowKey': 'brand',
    'text': 'Marker',
    'color': 'Purple',
    'price': '5'
}
  • create_entity - Tambahkan entitas ke tabel.
  • delete_entity - Menghapus entitas dari tabel.
  • update_entity - Perbarui informasi entitas dengan menggabungkan atau mengganti entitas yang ada.
    • UpdateMode.MERGE akan menambahkan properti baru ke entitas yang sudah ada, properti yang sudah ada tidak akan dihapus
    • UpdateMode.REPLACE akan mengganti entitas yang ada dengan yang diberikan, menghapus properti yang ada yang tidak disertakan dalam entitas yang dikirimkan
  • query_entities - Mengkueri entitas yang sudah ada dalam tabel menggunakan filter OData.
  • get_entity - Dapatkan entitas tertentu dari tabel menurut partisi dan kunci baris.
  • upsert_entity - Menggabungkan atau mengganti entitas dalam tabel, atau jika entitas tidak ada, menyisipkan entitas.
    • UpdateMode.MERGE akan menambahkan properti baru ke entitas yang sudah ada, properti yang sudah ada tidak akan dihapus
    • UpdateMode.REPLACE akan mengganti entitas yang ada dengan yang diberikan, menghapus properti yang ada yang tidak disertakan dalam entitas yang dikirimkan

Contoh

Bagian berikut ini menyediakan beberapa cuplikan kode yang mencakup beberapa tugas Tabel yang paling umum, termasuk:

Membuat tabel

Buat tabel di akun Anda dan dapatkan TableClient untuk melakukan operasi pada tabel yang baru dibuat:

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)

Membuat entitas

Buat entitas dalam tabel:

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)

Membuat kueri entitas

Mengkueri entitas dalam tabel:

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

Konfigurasi Opsional

Argumen kata kunci opsional dapat diteruskan di tingkat klien dan per operasi. Dokumentasi referensi azure-core menjelaskan konfigurasi yang tersedia untuk percobaan ulang, pengelogan, protokol transportasi, dan banyak lagi.

Konfigurasi Kebijakan Coba Lagi

Gunakan argumen kata kunci berikut saat membuat instans klien untuk mengonfigurasi kebijakan coba lagi:

  • retry_total (int): Jumlah total percobaan ulang yang diizinkan. Lebih diutamakan daripada hitungan lain. retry_total=0 Teruskan jika Anda tidak ingin mencoba kembali permintaan. Default ke 10.
  • retry_connect (int): Berapa banyak kesalahan terkait koneksi yang akan diulang. Default ke 3.
  • retry_read (int): Berapa kali untuk mencoba kembali kesalahan baca. Default ke 3.
  • retry_status (int): Berapa kali untuk mencoba kembali kode status yang buruk. Default ke 3.
  • retry_to_secondary (bool): Apakah permintaan harus dicoba kembali ke sekunder, jika dapat. Ini hanya boleh diaktifkan dari akun RA-GRS yang digunakan dan data yang berpotensi kedaluarsa dapat ditangani. Default ke False.

Konfigurasi klien/per operasi lainnya

Argumen kata kunci konfigurasi opsional lainnya yang dapat ditentukan pada klien atau per operasi.

Argumen kata kunci klien:

  • connection_timeout (int): Secara opsional mengatur nilai batas waktu sambungkan dan baca, dalam hitungan detik.
  • transport (Any): Transportasi yang disediakan pengguna untuk mengirim permintaan HTTP.

Argumen kata kunci per operasi:

  • raw_response_hook (dapat dipanggil): Panggilan balik yang diberikan menggunakan respons yang dikembalikan dari layanan.
  • raw_request_hook (dapat dipanggil): Panggilan balik yang diberikan menggunakan permintaan sebelum dikirim ke layanan.
  • client_request_id (str): Identifikasi permintaan yang ditentukan pengguna opsional.
  • user_agent (str): Menambahkan nilai kustom ke header agen pengguna untuk dikirim dengan permintaan.
  • logging_enable (bool): Memungkinkan pengelogan di tingkat DEBUG. Default ke False. Juga dapat diteruskan di tingkat klien untuk mengaktifkannya untuk semua permintaan.
  • header (dict): Meneruskan header kustom sebagai kunci, pasangan nilai. Misalnya headers={'CustomValue': value}

Pemecahan Masalah

Umum

Klien Azure Tables menaikkan pengecualian yang ditentukan di Azure Core. Saat Anda berinteraksi dengan pustaka tabel Azure menggunakan Python SDK, kesalahan yang dikembalikan oleh layanan merespons kode status HTTP yang sama untuk permintaan REST API . Operasi layanan Tabel akan melempar HttpResponseError kegagalan dengan kode kesalahan yang bermanfaat.

Misalnya, jika Anda mencoba membuat tabel yang sudah ada, kesalahan 409 dikembalikan yang menunjukkan "Konflik".

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

Pembuatan Log

Pustaka ini menggunakan pustaka pengelogan standar untuk pengelogan. Informasi dasar tentang sesi HTTP (URL, header, dll.) dicatat di tingkat INFO.

Pengelogan tingkat DEBUG terperinci, termasuk isi permintaan/respons dan header yang tidak diredaksikan, dapat diaktifkan pada klien dengan logging_enable argumen :

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)

Demikian pula, logging_enable dapat mengaktifkan pengelogan terperinci untuk satu operasi, bahkan ketika tidak diaktifkan untuk klien:

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

Langkah berikutnya

Mulai menggunakan sampel Tabel kami.

Beberapa sampel Azure Tables Python SDK tersedia untuk Anda di repositori GitHub SDK. Sampel ini menyediakan kode contoh untuk skenario tambahan yang biasa ditemui saat bekerja dengan Tabel.

Skenario Umum

Sampel kode ini menunjukkan operasi skenario umum dengan pustaka klien Azure Tables. Versi asinkron sampel (file sampel python yang ditambahkan dengan _async) menunjukkan operasi asinkron.

Dokumentasi tambahan

Untuk dokumentasi yang lebih luas tentang Azure Tables, lihat dokumentasi Azure Tables di docs.microsoft.com.

Masalah Umum

Daftar masalah yang saat ini diketahui yang berkaitan dengan titik akhir tabel Cosmos DB dapat ditemukan di sini.

Berkontribusi

Proyek ini menyambut baik kontribusi dan saran. Sebagian besar kontribusi mengharuskan Anda menyetujui Perjanjian Lisensi Kontributor (CLA) yang menyatakan bahwa Anda memiliki hak untuk, dan benar-benar melakukannya, memberi kami hak untuk menggunakan kontribusi Anda. Untuk detailnya, kunjungi https://cla.microsoft.com.

Ketika Anda mengirimkan permintaan tarik, CLA-bot akan secara otomatis menentukan apakah Anda perlu memberikan CLA dan menghias PR dengan tepat (misalnya, label, komentar). Cukup ikuti instruksi yang diberikan oleh bot. Anda hanya perlu melakukan ini sekali di semua repos menggunakan CLA kami.

Proyek ini telah mengadopsi Kode Etik Sumber Terbuka Microsoft. Untuk informasi selengkapnya, lihat Tanya Jawab Umum Tata Tertib atau hubungi opencode@microsoft.com untuk pertanyaan atau komentar lainnya.

Tayangan