Hızlı Başlangıç: Python SDK ve Azure Cosmos DB ile Tablo uygulaması için API oluşturma
ŞUNLAR IÇIN GEÇERLIDIR:
Tablo
Bu hızlı başlangıçta, Python uygulamasından Tablo için Azure Cosmos DB API'sine nasıl erişeceğimiz gösterilmektedir. Tablo için Azure Cosmos DB, uygulamaların yapılandırılmış NoSQL verilerini bulutta depolamasına olanak sağlayan şemasız bir veri deposudur. Veriler şemasız bir tasarımda depolandığından, tabloya yeni özniteliği olan bir nesne eklendiğinde yeni özellikler (sütunlar) tabloya otomatik olarak eklenir. Python uygulamaları, Python için Azure Veri Tabloları SDK'sını kullanarak Tablo için Azure Cosmos DB'ye erişebilir.
Önkoşullar
İlkeler tüm Python 3.7+ uygulamaları için geçerli olsa da örnek uygulama Python 3.7 veya sonraki sürümlerde yazılmıştır. Visual Studio Code IDE olarak kullanabilirsiniz.
Azure aboneliğiniz yoksa başlamadan önce ücretsiz bir hesap oluşturun.
Örnek uygulama
Bu öğreticinin örnek uygulaması depodan https://github.com/Azure-Samples/msdocs-azure-tables-sdk-python-flaskkopyalanabilir veya indirilebilir.
git clone https://github.com/Azure-Samples/msdocs-azure-tables-sdk-python-flask.git
1-starter-app ve 2-completed-app örnek klasörü örnek depoya eklenir. 1-starter-app, "#TODO" işaretli satırlarla tamamlamanız için bazı işlevlere sahiptir. Bu makalede gösterilen kod parçacıkları , 1-starter-app'i tamamlamak için önerilen eklemelerdir.
Tamamlanan örnek uygulama, Tablo için API'nin özelliklerini göstermek için örnek olarak hava durumu verilerini kullanır. Hava durumu gözlemlerini temsil eden nesneler, Tablo API'si kullanılarak depolanır ve alınır; tablo için API'nin şemasız özelliklerini göstermek için ek özelliklere sahip nesneler depolama da dahil olmak üzere. Aşağıdaki görüntüde tarayıcıda çalışan yerel uygulama gösterilir ve Tablo için Azure Cosmos DB'de depolanan hava durumu verileri görüntülenir.
1 - Azure Cosmos DB hesabı oluşturma
İlk olarak, uygulamanızda kullanılan tabloları içerecek bir Azure Cosmos DB Tabloları API hesabı oluşturmanız gerekir. Azure portal, Azure CLI veya Azure PowerShell ile bir hesap oluşturun.
Azure portal oturum açın ve bir Azure Cosmos DB hesabı oluşturmak için bu adımları izleyin.
| Yönergeler | Ekran görüntüsü |
|---|---|
Azure portalında:
|
|
| Azure Cosmos DB sayfasında +Oluştur'u seçin. | 
|
| API seç seçeneği sayfasında Azure Tablosu seçeneğini belirleyin. | 
|
Azure Cosmos DB Hesabı - Azure Tablosu Oluştur sayfasında formu aşağıdaki gibi doldurun.
|
|
2 - Tablo oluşturma
Ardından, uygulamanızın kullanabilmesi için Azure Cosmos DB hesabınızda bir tablo oluşturmanız gerekir. Geleneksel bir veritabanından farklı olarak, tablodaki özellikleri (sütunları) değil, yalnızca tablonun adını belirtmeniz gerekir. Tablonuza veri yüklendiğinden, özellikler (sütunlar) gerektiğinde otomatik olarak oluşturulur.
Azure portal, Azure Cosmos DB hesabınızın içinde bir tablo oluşturmak için aşağıdaki adımları tamamlayın.
| Yönergeler | Ekran görüntüsü |
|---|---|
Azure portal Azure Cosmos DB hesabının genel bakış sayfasına gidin.
|
|
| Genel Bakış sayfasında +Tablo Ekle'yi seçin. Yeni Tablo iletişim kutusu sayfanın sağ tarafından dışarı kayar. | 
|
Yeni Tablo iletişim kutusunda formu aşağıdaki gibi doldurun.
|
|
3 - Azure Cosmos DB bağlantı dizesini alma
Azure Cosmos DB'deki tablolarınıza erişmek için uygulamanız Cosmos DB Depolama hesabının tablo bağlantı dizesine ihtiyaç duyar. Bağlantı dizesi Azure portal, Azure CLI veya Azure PowerShell kullanılarak alınabilir.
| Yönergeler | Ekran görüntüsü |
|---|---|
| Azure Cosmos DB hesap sayfasının sol tarafında, Ayarlar üst bilgisinin altındaki Bağlantı dizeleri adlı menü öğesini bulun ve seçin. Azure Cosmos DB hesabının bağlantı dizesini alabildiğiniz bir sayfaya yönlendirilirsiniz. | 
|
| Uygulamanızda kullanmak için BİRİnCİl BAĞLANTI DIZESİ değerini kopyalayın. | 
|
4 - Python için Azure Veri Tabloları SDK'sını yükleme
Bir Azure Cosmos DB hesabı oluşturduktan sonra, sonraki adımınız Python için Microsoft Azure Veri Tabloları SDK'sını yüklemektir. SDK'yı yükleme hakkında ayrıntılı bilgi için GitHub'daki Python için Veri Tabloları SDK'sı deposundaki README.md dosyasına bakın.
Pip ile Python için Azure Tabloları istemci kitaplığını yükleyin:
pip install azure-data-tables
ayrıcarequirements.txt1-starter-app veya 2-completed-app klasörlerine yüklemeyi unutmayın.
5 - Tablo istemcisini bir .env dosyasında yapılandırma
Azure Cosmos DB hesabı bağlantı dizenizi Azure portal kopyalayın ve kopyaladığınız bağlantı dizesini kullanarak bir TableServiceClient nesnesi oluşturun. 1-starter-app veya 2-completed-app klasörüne geçin. Hangi uygulamayla başladığınıza bakılmaksızın, bir .env dosyada ortam değişkenleri tanımlamanız gerekir.
# Configuration Parameters
conn_str = "A connection string to an Azure Cosmos DB account."
table_name = "WeatherData"
project_root_path = "Project abs path"
Azure SDK, Azure'a karşı farklı işlemler yürütmek için istemci nesnelerini kullanarak Azure ile iletişim kurar. TableServiceClient nesnesi, Tablo için Azure Cosmos DB ile iletişim kurmak için kullanılan nesnedir. Bir uygulamanın genellikle tek TableServiceClient bir geneli ve tablo başına bir TableClient tablosu olur.
Örneğin, aşağıdaki kod ortam değişkeninden bağlantı dizesini kullanarak bir TableServiceClient nesne oluşturur.
self.conn_str = os.getenv("conn_str")
self.table_service = TableServiceClient.from_connection_string(self.conn_str)
6 - Azure Cosmos DB tablo işlemlerini uygulama
Örnek uygulama için tüm Azure Cosmos DB tablo işlemleri, webapp dizininin TableServiceHelper altındaki yardımcı dosyada bulunan sınıfında uygulanır. Python için azure.data.tables istemci kitaplığındaki nesnelerle çalışmak için bu dosyanın en üstündeki sınıfı içeri aktarmanız TableServiceClient gerekir.
from azure.data.tables import TableServiceClient
sınıfının başında bir oluşturucu oluşturun ve nesnenin TableServiceHelper sınıfına TableClient eklenmesine izin vermek TableClient için nesnesi için bir üye değişkeni ekleyin.
def __init__(self, table_name=None, conn_str=None):
self.table_name = table_name if table_name else os.getenv("table_name")
self.conn_str = conn_str if conn_str else os.getenv("conn_str")
self.table_service = TableServiceClient.from_connection_string(self.conn_str)
self.table_client = self.table_service.get_table_client(self.table_name)
Tablodan döndürülen satırları filtreleme
Tablodan döndürülen satırları filtrelemek için yöntemine query_entities bir OData stili filtre dizesi geçirebilirsiniz. Örneğin, 1 Temmuz 2021 ile 2 Temmuz 2021 (dahil) gece yarısı arasında Chicago için tüm hava durumu okumalarını almak isterseniz aşağıdaki filtre dizesini geçirirsiniz.
PartitionKey eq 'Chicago' and RowKey ge '2021-07-01 12:00 AM' and RowKey le '2021-07-02 12:00 AM'
İlgili OData filtre işleçlerini Azure-data-tables web sitesinde Filtreler Yazma bölümünde görüntüleyebilirsiniz.
sınıfındaki query_entityTableServiceHelper yöntemine request.args parametresi geçirildiğinde, null olmayan her özellik değeri için bir filtre dizesi oluşturur. Ardından tüm değerleri bir "and" yan tümcesiyle birleştirerek birleştirilmiş bir filtre dizesi oluşturur. Bu birleştirilmiş filtre dizesi nesnedeki query_entitiesTableClient yöntemine geçirilir ve yalnızca filtre dizesiyle eşleşen satırlar döndürülür. Uygulamanızın gerektirdiği şekilde uygun filtre dizeleri oluşturmak için kodunuzda benzer bir yöntem kullanabilirsiniz.
def query_entity(self, params):
filters = []
if params.get("partitionKey"):
filters.append("PartitionKey eq '{}'".format(params.get("partitionKey")))
if params.get("rowKeyDateStart") and params.get("rowKeyTimeStart"):
filters.append("RowKey ge '{} {}'".format(params.get("rowKeyDateStart"), params.get("rowKeyTimeStart")))
if params.get("rowKeyDateEnd") and params.get("rowKeyTimeEnd"):
filters.append("RowKey le '{} {}'".format(params.get("rowKeyDateEnd"), params.get("rowKeyTimeEnd")))
if params.get("minTemperature"):
filters.append("Temperature ge {}".format(params.get("minTemperature")))
if params.get("maxTemperature"):
filters.append("Temperature le {}".format(params.get("maxTemperature")))
if params.get("minPrecipitation"):
filters.append("Precipitation ge {}".format(params.get("minPrecipitation")))
if params.get("maxPrecipitation"):
filters.append("Precipitation le {}".format(params.get("maxPrecipitation")))
return list(self.table_client.query_entities(" and ".join(filters)))
TableEntity nesnesi kullanarak veri ekleme
Tabloya veri eklemenin en basit yolu nesne TableEntity kullanmaktır. Bu örnekte veriler bir giriş modeli nesnesinden bir TableEntity nesneye eşlenir. Hava durumu istasyonu adını ve gözlem tarih/saatini temsil eden giriş nesnesindeki özellikler sırasıyla ve özellikleriyle PartitionKey eşlenir ve RowKey birlikte tablodaki satır için benzersiz bir anahtar oluşturur. Ardından giriş modeli nesnesinde ek özellikler TableEntity nesnesinde sözlük özellikleriyle eşlenir. Son olarak, tabloya create_entityTableClient veri eklemek için nesnedeki yöntemi kullanılır.
insert_entity Örnek uygulamadaki işlevini aşağıdaki kodu içerecek şekilde değiştirin.
def insert_entity(self):
entity = self.deserialize()
return self.table_client.create_entity(entity)
@staticmethod
def deserialize():
params = {key: request.form.get(key) for key in request.form.keys()}
params["PartitionKey"] = params.pop("StationName")
params["RowKey"] = "{} {}".format(params.pop("ObservationDate"), params.pop("ObservationTime"))
return params
TableEntity nesnesi kullanarak verileri upsert
Bu tabloda zaten var olan bir bölüm anahtarı/satır anahtarı birleşimiyle tabloya satır eklemeye çalışırsanız bir hata alırsınız. Bu nedenle, genellikle tabloya satır eklerken yöntemi yerine create_entity öğesinin kullanılması upsert_entity tercih edilir. Verilen bölüm anahtarı/satır anahtarı bileşimi tabloda zaten varsa, upsert_entity yöntemi mevcut satırı güncelleştirir. Aksi takdirde, satır tabloya eklenir.
def upsert_entity(self):
entity = self.deserialize()
return self.table_client.upsert_entity(entity)
@staticmethod
def deserialize():
params = {key: request.form.get(key) for key in request.form.keys()}
params["PartitionKey"] = params.pop("StationName")
params["RowKey"] = "{} {}".format(params.pop("ObservationDate"), params.pop("ObservationTime"))
return params
Değişken özellikleriyle veri ekleme veya ekleme
Tablo için Azure Cosmos DB kullanmanın avantajlarından biri, tabloya yüklenen bir nesne yeni özellikler içeriyorsa bu özelliklerin tabloya otomatik olarak eklenmesi ve Azure Cosmos DB'de depolanan değerlerdir. Geleneksel veritabanında olduğu gibi sütun eklemek için ALTER TABLE gibi DDL deyimlerini çalıştırmanız gerekmez.
Bu model, uygulamanıza zaman içinde hangi verilerin yakalanması gerektiğini ekleyebilecek veya değiştirebilecek veri kaynaklarıyla ilgilenirken veya farklı girişler uygulamanıza farklı veriler sağladığında esneklik sağlar. Örnek uygulamada, yalnızca temel hava durumu verilerini değil bazı ek değerleri de gönderen bir hava durumu istasyonunun simülasyonunu yapabiliriz. Bu yeni özelliklere sahip bir nesne tabloda ilk kez depolandığında, ilgili özellikler (sütunlar) tabloya otomatik olarak eklenir.
Tablo API'sini kullanarak böyle bir nesne eklemek veya eklemek için, genişletilebilir nesnenin özelliklerini bir TableEntity nesneye eşleyin ve nesnedeki TableClient veya upsert_entity yöntemlerini uygun şekilde kullanıncreate_entity.
Örnek uygulamada işlev, upsert_entity değişken özellikleriyle veri ekleme veya yükseltme işlevini de uygulayabilir
def insert_entity(self):
entity = self.deserialize()
return self.table_client.create_entity(entity)
def upsert_entity(self):
entity = self.deserialize()
return self.table_client.upsert_entity(entity)
@staticmethod
def deserialize():
params = {key: request.form.get(key) for key in request.form.keys()}
params["PartitionKey"] = params.pop("StationName")
params["RowKey"] = "{} {}".format(params.pop("ObservationDate"), params.pop("ObservationTime"))
return params
Varlığı güncelleştirme
Varlıklar nesnesinde TableClient yöntemi çağrılarak update_entity güncelleştirilebilir.
Örnek uygulamada, bu nesne sınıfındaki upsert_entity yöntemine TableClient geçirilir. Bu varlık nesnesini güncelleştirir ve yöntemini kullanarak upsert_entity güncelleştirmeleri veritabanına kaydeder.
def update_entity(self):
entity = self.update_deserialize()
return self.table_client.update_entity(entity)
@staticmethod
def update_deserialize():
params = {key: request.form.get(key) for key in request.form.keys()}
params["PartitionKey"] = params.pop("StationName")
params["RowKey"] = params.pop("ObservationDate")
return params
Varlığı kaldırma
Tablodan bir varlığı kaldırmak için nesnenin delete_entityTableClient bölüm anahtarı ve satır anahtarıyla nesnede yöntemini çağırın.
def delete_entity(self):
partition_key = request.form.get("StationName")
row_key = request.form.get("ObservationDate")
return self.table_client.delete_entity(partition_key, row_key)
7 - Kodu çalıştırma
Tablo için Azure Cosmos DB ile etkileşime geçmek için örnek uygulamayı çalıştırın. Örneğin, gereksinimlerin yüklü olduğu 2-completed-app klasöründen başlayarak şunları kullanabilirsiniz:
python3 run.py webapp
Örnek uygulamayı çalıştırma hakkında daha fazla bilgi için örnek depo kökündekiREADME.md dosyasına bakın.
Uygulamayı ilk kez çalıştırdığınızda, tablo boş olduğundan veri olmaz. Tabloya veri eklemek için uygulamanın üst kısmındaki düğmelerden herhangi birini kullanın.
Tablo Varlığını Kullanarak Ekle düğmesini seçtiğinizde, nesne kullanarak yeni bir satır eklemenize veya eklemenize olanak sağlayan bir TableEntity iletişim kutusu açılır.
Genişletilebilir Verileri Kullanarak Ekle düğmesini seçtiğinizde özel özelliklere sahip bir nesne eklemenize olanak tanıyan bir iletişim kutusu açılır ve Tablo için Azure Cosmos DB'nin gerektiğinde tabloya özellikleri (sütunları) otomatik olarak nasıl eklediğini gösterir. Bir veya daha fazla yeni özellik eklemek ve bu özelliği göstermek için Özel Alan Ekle düğmesini kullanın.
Azure Cosmos DB Tablonuza örnek veriler yüklemek için Örnek Veri Ekle düğmesini kullanın.
1-starter-app örnek klasörü için, en azından örnek veri ekleme işlevinin
submit_transactionçalışmasının kodunu tamamlamanız gerekir.Örnek veriler bir sample_data.json dosyasından yüklenir. .env değişkeni
project_root_path, uygulamaya bu dosyayı nerede bulacağını söyler. Örneğin, uygulamayı 1-starter-app veya 2-completed-app klasöründen çalıştırıyorsanız, "" (boş) olarak ayarlayınproject_root_path.
Sonuçları Filtrele sayfasına gitmek için üstteki menüden Sonuçları Filtrele öğesini seçin. Bu sayfada, filtre yan tümcesinin nasıl derlenip Tablo için Azure Cosmos DB'ye geçirilebileceğini göstermek için filtre ölçütlerini doldurun.
Kaynakları temizleme
Örnek uygulamayı tamamladığınızda, bu makaleyle ilgili tüm Azure kaynaklarını Azure hesabınızdan kaldırmanız gerekir. Kaynak grubunu silerek tüm kaynakları kaldırabilirsiniz.
Kaynak grubu, aşağıdakiler yapılarak Azure portal kullanılarak silinebilir.
| Yönergeler | Ekran görüntüsü |
|---|---|
| Kaynak grubuna gitmek için, arama çubuğuna kaynak grubunun adını yazın. Ardından Kaynak Grupları sekmesinde kaynak grubunun adını seçin. | 
|
| Kaynak grubu sayfasının üst kısmındaki araç çubuğundan Kaynak grubunu sil'i seçin. | 
|
Ekranın sağ tarafından kaynak grubunun silinmesini onaylamanızı isteyen bir iletişim kutusu açılır.
|
|
Sonraki adımlar
Bu hızlı başlangıçta Azure Cosmos DB hesabı oluşturmayı, Veri Gezgini'ni kullanarak tablo oluşturmayı ve bir uygulamayı çalıştırmayı öğrendiniz. Artık Tablo API'sini kullanarak verilerinizi sorgulayabilirsiniz.