Aracılığıyla paylaş


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.

Tablo api'sini kullanarak Azure Cosmos DB tablosunda depolanan verileri gösteren tamamlanmış uygulamanın ekran görüntüsü.

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.

Yönergeler Ekran görüntüsü
Azure portalında:
  1. Azure portalının üst kısmındaki arama çubuğuna "cosmos db" yazın.
  2. Arama çubuğunun altında görüntülenen menüde, Hizmetler'in altında Azure Cosmos DB etiketli öğeyi seçin.
Azure'da Azure Cosmos DB hesaplarını bulmak için üst araç çubuğundaki arama kutusunun nasıl kullanılacağını gösteren ekran görüntüsü.
Azure Cosmos DB sayfasında +Oluştur'u seçin. Azure'da Azure Cosmos DB hesapları sayfasındaki Oluştur düğmesi konumunu gösteren ekran görüntüsü.
API seç seçeneği sayfasında Azure Tablosu seçeneğini belirleyin. Seçecek doğru seçenek olarak Azure Tablo seçeneğini gösteren ekran görüntüsü.
Azure Cosmos DB Hesabı - Azure Tablosu Oluştur sayfasında formu aşağıdaki gibi doldurun.
  1. Kaynak grubu altındaki Yeni oluştur bağlantısını seçerek adlı rg-msdocs-tables-sdk-demo depolama hesabı için yeni bir kaynak grubu oluşturun.
  2. Benzersiz bir hesap adı oluşturmak için depolama hesabınıza XYZ'nin cosmos-msdocs-tables-sdk-demo-XYZ rastgele üç karakter olduğu bir ad verin. Azure Cosmos DB hesap adlarının uzunluğu 3 ile 44 karakter arasında olmalıdır ve yalnızca küçük harfler, sayılar veya kısa çizgi (-) karakteri içerebilir.
  3. Depolama hesabınız için bölge seçin.
  4. Standart performans'ı seçin.
  5. Bu örnek için Kapasite modu altında Sağlanan aktarım hızı'nu seçin.
  6. Bu örnek için Ücretsiz Katman İndirimi Uygula altında Uygula'yı seçin.
  7. Azure Cosmos DB hesabınızı oluşturmak için ekranın alt kısmındaki Gözden Geçir + oluştur düğmesini ve ardından özet ekranında Oluştur'u seçin. Bu işlem birkaç dakika sürebilir.
Azure Cosmos DB Hesabı oluşturma sayfasındaki alanların nasıl doldurulduğunu gösteren ekran görüntüsü.

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.

Yönergeler Ekran görüntüsü
Azure portalında Azure Cosmos DB hesabının genel bakış sayfasına gidin.
  1. Üst arama çubuğuna Azure Cosmos DB hesabınızın adını (cosmos-msdocs-tables-sdk-demo-XYZ) yazarak ve kaynaklar başlığının altına bakarak Azure Cosmos DB hesabınızın genel bakış sayfasına gidebilirsiniz.

  2. Genel Bakış sayfasına gitmek için Azure Cosmos DB hesabınızın adını seçin.

Azure Cosmos DB hesabınızı bulmak için üst araç çubuğundaki arama kutusunun nasıl kullanılacağını gösteren ekran görüntüsü.
Genel Bakış sayfasında +Tablo Ekle'yi seçin. Yeni Tablo iletişim kutusu sayfanın sağ tarafından dışarı doğru kaydırır. Tablo Ekle düğmesinin konumunu gösteren ekran görüntüsü.
Yeni Tablo iletişim kutusunda formu aşağıdaki gibi doldurun.
  1. Tablo Kimliği için WeatherData adını girin. Bu değer tablonun adıdır.
  2. Bu örnek için Tablo aktarım hızı altında El ile'yi seçin.
  3. Tahmini RU/sn değerinizin altında varsayılan 400 değerini kullanın.
  4. Tabloyu oluşturmak için Tamam düğmesini seçin.
Azure Cosmos DB tablosu için Yeni Tablo iletişim kutusunun nasıl yapıldığını gösteren ekran görüntüsü.

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.

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ı için bağlantı dizesi alabildiğiniz bir sayfaya yönlendirilirsiniz. Azure Cosmos DB sayfasındaki bağlantı dizesi bağlantısının konumunu gösteren ekran görüntüsü.
Uygulamanızda kullanmak için BİRİnCİl BAĞLANTI DIZESİ değerini kopyalayın. Uygulamanızda hangi bağlantı dizesi seçilip kullanılacağını gösteren ekran görüntüsü.

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_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 "ve" yan tümcesiyle birleştirerek birleştirilmiş bir filtre dizesi oluşturur. Bu birleşik 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 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_entityTableClient 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 API'sini kullanarak Azure Cosmos DB'ye veri eklemek için kullanılan düğmelerin konumunu gösteren uygulamanın ekran görüntüsü.

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.

TableEntity nesnesi kullanarak veri eklemek için kullanılan iletişim kutusunu gösteren uygulamanın ekran görüntüsü.

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.

Özel alanlara sahip bir nesne kullanarak veri eklemek için kullanılan iletişim kutusunu gösteren uygulamanın ekran görüntüsü.

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şkeniproject_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ın project_root_path.

Örnek veri ekleme düğmesinin konumunu gösteren uygulamanın ekran görüntüsü.

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.

Filtre sonuçları sayfasını gösteren ve sayfaya gitmek için kullanılan menü öğesini vurgulayan uygulamanın ekran görüntüsü.

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.

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 arama işlemini gösteren ekran görüntüsü.
Kaynak grubu sayfasının üst kısmındaki araç çubuğundan Kaynak grubunu sil'i seçin. Kaynak grubunu sil düğmesinin konumunu gösteren ekran görüntüsü.
Ekranın sağından kaynak grubunun silinmesini onaylamanızı isteyen bir iletişim kutusu açılır.
  1. Silme işleminin açıklandığı gibi onaylanması için metin kutusuna kaynak grubunun tam adını yazın.
  2. Sayfanın en altındaki Sil düğmesini seçin.
Kaynak grubunu silmeye yönelik onay iletişim kutusunu gösteren ekran görüntüsü.

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.