Hızlı Başlangıç: Python SDK ve Azure Cosmos DB ile Tablo uygulaması için API oluşturma
ŞUNLAR IÇIN GEÇERLIDIR: Masa
Bu hızlı başlangıçta, Python uygulamasından Tablo için Azure Cosmos DB API'sine nasıl erişin olduğu 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ı paketini kullanarak Tablo için Azure Cosmos DB'ye erişebilir.
Önkoşullar
Örnek uygulama Python 3.7 veya üzeri sürümlerde yazılmıştır ancak ilkeler tüm Python 3.7+ uygulamaları için geçerlidir. Visual Studio Code'yu IDE olarak kullanabilirsiniz.
Azure aboneliğiniz yoksa başlamadan önce ücretsiz bir hesap oluşturun.
Örnek uygulama
Bu öğretici için örnek uygulama 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.
Tamamlanmış örnek uygulama, Tablo için API'nin özelliklerini göstermek için örnek olarak hava durumu verilerini kullanır. Tablo için API'nin şemasız özelliklerini göstermek üzere ek özelliklere sahip nesneleri depolama da dahil olmak üzere, hava durumu gözlemlerini temsil eden nesneler Tablo API'si kullanılarak depolanır ve alınır. Aşağıdaki görüntüde tarayıcıda çalışan ve Tablo için Azure Cosmos DB'de depolanan hava durumu verilerini görüntüleyen yerel uygulama gösterilmektedir.
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ında oturum açın ve bir Azure Cosmos DB hesabı oluşturmak için bu adımları izleyin.
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. Veriler tablonuza yüklendikçe, özellikler (sütunlar) gerektiğinde otomatik olarak oluşturulur.
Azure portalında aşağıdaki adımları tamamlayarak Azure Cosmos DB hesabınızın içinde bir tablo oluşturun.
3 - Azure Cosmos DB bağlantı dizesi alma
Azure Cosmos DB'deki tablolarınıza erişmek için uygulamanızın Cosmos DB Depolama hesabı için tablo bağlantı dizesi ihtiyacı vardır. bağlantı dizesi Azure portalı, Azure CLI veya Azure PowerShell kullanılarak alınabilir.
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.
Python için Azure Tabloları istemci kitaplığını pip ile yükleyin:
pip install azure-data-tables
1-starter-app veya 2-completed-app klasörlerine de requirements.txt yüklemeyi unutmayın.
5 - Tablo istemcisini bir .env dosyasında yapılandırma
Azure portalından Azure Cosmos DB hesabınızı bağlantı dizesi kopyalayın ve kopyaladığınız bağlantı dizesi 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 olur ve tablo başına bir TableClient
uygulaması olur.
Örneğin, aşağıdaki kod ortam değişkeninden bağlantı dizesi 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ıfta 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 TableServiceHelper
bir oluşturucu oluşturun ve nesnenin TableClient
sınıfına 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 istiyorsanız 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_entity
TableServiceHelper
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 "ve" yan tümcesiyle birleştirerek birleştirilmiş bir filtre dizesi oluşturur. Bu birleşik filtre dizesi nesnedeki query_entities
TableClient
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 RowKey
özelliklerine PartitionKey
eşlenir ve bu da 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, create_entity
nesnedeki TableClient
yöntemi tabloya veri eklemek için kullanılır.
insert_entity
Örnek uygulamadaki işlevi 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 yukarı ekleme
Bir tabloya, o tabloda zaten var olan bir bölüm anahtarı/satır anahtarı bileşimine sahip bir satır eklemeyi denerseniz bir hata alırsınız. Bu nedenle, genellikle tabloya satır eklerken yöntemi yerine create_entity
öğesini kullanmak 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, zaman içinde yakalanması gereken verileri ekleyebilen veya değiştirebilen veri kaynaklarıyla ilgilenirken veya farklı girişler uygulamanıza farklı veriler sağladığında uygulamanıza 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 oluşturabiliriz. 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
nesneyle 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 yukarı ekleme 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 güncelleştirmeleri upsert_entity
veritabanına kaydetme yöntemini kullanır.
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_entity
TableClient
bölüm anahtarı ve satır anahtarıyla nesne üzerinde 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ündeki README.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üğmesinin seçilmesi, nesne kullanarak yeni satır eklemenize veya eklemenize olanak sağlayan bir TableEntity
iletişim kutusu açar.
Genişletilebilir Veri Kullanarak Ekle düğmesinin seçilmesi, özel özelliklere sahip bir nesne eklemenize olanak tanıyan bir iletişim kutusu getirir ve Tablo için Azure Cosmos DB'nin gerektiğinde tabloya otomatik olarak özellikler (sütunlar) eklendiğ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, örnek veri ekleme işlevinin
submit_transaction
çalışması için en azından kodu 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, bir 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.
Aşağıdakiler yapılarak Azure portalı kullanılarak bir kaynak grubu silinebilir.
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.
Geri Bildirim
https://aka.ms/ContentUserFeedback.
Çok yakında: 2024 boyunca, içerik için geri bildirim mekanizması olarak GitHub Sorunları’nı kullanımdan kaldıracak ve yeni bir geri bildirim sistemiyle değiştireceğiz. Daha fazla bilgi için bkz.Gönderin ve geri bildirimi görüntüleyin