Hızlı Başlangıç: Node.js ve Azure Cosmos DB ile Tablo uygulaması için API oluşturma
ŞUNLAR IÇIN GEÇERLIDIR:
Tablo
Bu hızlı başlangıçta Tablo için Azure Cosmos DB hesabı oluşturacak ve tablolar ve varlıklar oluşturmak için github'dan kopyalanmış Veri Gezgini ve Node.js uygulamasını kullanacaksınız. Azure Cosmos DB, genel dağıtım ve yatay ölçek özelliklerine sahip belge, tablo, anahtar-değer ve grafik veritabanlarını hızla oluşturmanıza ve sorgulamanıza olanak tanıyan çok modelli bir veritabanı hizmetidir.
Önkoşullar
- Etkin aboneliği olan bir Azure hesabı. Ücretsiz bir tane oluşturun.
- Node.js 0.10.29+ .
- Git'i seçin.
Örnek uygulama
Bu öğretici için örnek uygulama depodan https://github.com/Azure-Samples/msdocs-azure-data-tables-sdk-jskopyalanabilir veya indirilebilir. Örnek depoya hem başlangıç hem de tamamlanan uygulama dahildir.
git clone https://github.com/Azure-Samples/msdocs-azure-data-tables-sdk-js
Örnek uygulama, Tablo api'sinin ö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.
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. Bu işlem Azure portal, Azure CLI veya Azure PowerShell kullanılarak yapılabilir.
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 veritabanından farklı olarak, tablodaki özellikleri (sütunları) değil, yalnızca tablonun adını belirtmeniz gerekir. Tablonuza veri yüklendiğinde, ö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. Üstteki 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. Genel bakış sayfasına gitmek için Azure Cosmos DB hesabınızın adını seçin. | 
|
| Genel bakış sayfasında +Tablo Ekle'yi seçin. Yeni Tablo iletişim kutusu sayfanın sağ tarafından dışarı kaydırılır. | 
|
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 CosmosDB 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ında Bağlantı Dizesi 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 - JS için Azure Veri Tabloları SDK'sını yükleme
Bir nodejs uygulamasından Tablo için Azure Cosmos DB'ye erişmek için Azure Veri Tabloları SDK paketini yükleyin.
npm install @azure/data-tables
5 - tablo istemcisini env.js dosyasında yapılandırma
Azure Cosmos DB veya Depolama hesabı bağlantı dizenizi Azure portal kopyalayın ve kopyaladığınız bağlantı dizesini kullanarak bir TableServiceClient nesnesi oluşturun. veya klasörüne 1-strater-app2-completed-appgeçin. Ardından, dosyaya karşılık gelen ortam değişkenlerinin configure/env.js değerini ekleyin.
const env = {
connectionString:"A connection string to an Azure Storage or Azure Cosmos DB account.",
tableName: "WeatherData",
};
Azure SDK, Azure'a karşı farklı işlemler yürütmek için istemci nesnelerini kullanarak Azure ile iletişim kurar. TableClient sınıfı, Tablo için Azure Cosmos DB ile iletişim kurmak için kullanılan sınıftır. Bir uygulama genellikle uygulama genelinde kullanılacak tablo başına tek serviceClient bir nesne oluşturur.
const { TableClient } = require("@azure/data-tables");
const env = require("../configure/env");
const serviceClient = TableClient.fromConnectionString(
env.connectionString,
env.tableName
);
6 - Azure Cosmos DB tablo işlemlerini uygulama
Örnek uygulama için tüm Azure Cosmos DB tablo işlemleri, hizmet dizini altındaki dosyada serviceClient bulunan nesneye tableClient.js uygulanır.
const { TableClient } = require("@azure/data-tables");
const env = require("../configure/env");
const serviceClient = TableClient.fromConnectionString(
env.connectionString,
env.tableName
);
Tablodan satır alma
nesnesi, serviceClient tablodan satır seçmenize olanak tanıyan adlı listEntities bir yöntem içerir. Bu örnekte yönteme hiçbir parametre geçirilmediğinden tablodan tüm satırlar seçilir.
const allRowsEntities = serviceClient.listEntities();
Tablodan döndürülen satırları filtreleme
Tablodan döndürülen satırları filtrelemek için yöntemine listEntities 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' and RowKey le '2021-07-02 12:00'
Tüm OData filtre işleçlerini OData web sitesinde Sistem Sorgu Seçeneğini Filtrele bölümünde görüntüleyebilirsiniz.
sınıfındaki listEntitiesserviceClient 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 listEntitiesserviceClient 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.
const filterEntities = async function (option) {
/*
You can query data according to existing fields
option provides some conditions to query,eg partitionKey, rowKeyDateTimeStart, rowKeyDateTimeEnd
minTemperature, maxTemperature, minPrecipitation, maxPrecipitation
*/
const filterEntitiesArray = [];
const filters = [];
if (option.partitionKey) {
filters.push(`PartitionKey eq '${option.partitionKey}'`);
}
if (option.rowKeyDateTimeStart) {
filters.push(`RowKey ge '${option.rowKeyDateTimeStart}'`);
}
if (option.rowKeyDateTimeEnd) {
filters.push(`RowKey le '${option.rowKeyDateTimeEnd}'`);
}
if (option.minTemperature !== null) {
filters.push(`Temperature ge ${option.minTemperature}`);
}
if (option.maxTemperature !== null) {
filters.push(`Temperature le ${option.maxTemperature}`);
}
if (option.minPrecipitation !== null) {
filters.push(`Precipitation ge ${option.minPrecipitation}`);
}
if (option.maxPrecipitation !== null) {
filters.push(`Precipitation le ${option.maxPrecipitation}`);
}
const res = serviceClient.listEntities({
queryOptions: {
filter: filters.join(" and "),
},
});
for await (const entity of res) {
filterEntitiesArray.push(entity);
}
return filterEntitiesArray;
};
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, tablodaki PartitionKey satır için benzersiz bir anahtar oluşturan ve RowKey özelliklerine sırasıyla eşlenir. Ardından giriş modeli nesnesinde ek özellikler TableEntity nesnesinde sözlük özellikleriyle eşlenir. Son olarak, tabloya createEntityserviceClient veri eklemek için nesnedeki yöntemi kullanılır.
insertEntity Örnek uygulamadaki işlevini aşağıdaki kodu içerecek şekilde değiştirin.
const insertEntity = async function (entity) {
await serviceClient.createEntity(entity);
};
TableEntity nesnesi kullanarak verileri upsert
Bu tabloda zaten var olan bir bölüm anahtarı/satır anahtarı bileşimiyle tabloya satır eklemeye çalışırsanız bir hata alırsınız. Bu nedenle, genellikle tabloya upsertEntity satır eklerken yöntemi yerine createEntity kullanmak tercih edilir. Verilen bölüm anahtarı/satır anahtarı bileşimi tabloda zaten varsa, upsertEntity yöntemi mevcut satırı güncelleştirir. Aksi takdirde satır tabloya eklenir.
const upsertEntity = async function (entity) {
await serviceClient.upsertEntity(entity, "Merge");
};
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ırmaya gerek yoktur.
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 benzetimini 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 serviceClient veya upsertEntity yöntemlerini uygun şekilde kullanıncreateEntity.
Örnek uygulamada işlev, upsertEntity değişken özellikleriyle veri ekleme veya yükseltme işlevini de uygulayabilir
const insertEntity = async function (entity) {
await serviceClient.createEntity(entity);
};
const upsertEntity = async function (entity) {
await serviceClient.upsertEntity(entity, "Merge");
};
Varlığı güncelleştirme
Varlıklar nesnesinde serviceClient yöntemi çağrılarak updateEntity güncelleştirilebilir.
Örnek uygulamada, bu nesne nesnedeki upsertEntity yöntemine serviceClient geçirilir. Bu varlık nesnesini güncelleştirir ve yöntemini kullanarak upsertEntity güncelleştirmeleri veritabanına kaydeder.
const updateEntity = async function (entity) {
await serviceClient.updateEntity(entity, "Replace");
};
7 - Kodu çalıştırma
Tablo için Azure Cosmos DB ile etkileşime geçmek için örnek uygulamayı çalıştırı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.
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. Bunu yapmak için kaynak grubunu silebilirsiniz.
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.