Node.js'dan Azure Tablo depolamayı veya Tablo için Azure Cosmos DB'yi kullanma
ŞUNLAR IÇIN GEÇERLIDIR: Masa
İpucu
Bu makaledeki içerik, Azure Tablo depolama ve Tablo için Azure Cosmos DB için geçerlidir. Tablo için API, aktarım hızı için iyileştirilmiş tablolar, genel dağıtım ve otomatik ikincil dizinler sunan, tablo depolamaya yönelik premium bir tekliftir.
Bu makalede tablo oluşturma, verilerinizi depolama ve söz konusu veriler üzerinde CRUD işlemleri gerçekleştirme işlemleri gösterilmektedir. Örnekler Node.js yazılır.
Azure hizmet hesabı oluşturma
Azure Tablo depolama alanını veya Azure Cosmos DB'yi kullanarak tablolarla çalışabilirsiniz. Bu iki hizmetteki tablo teklifleri arasındaki farklar hakkında daha fazla bilgi edinmek için Tabloya genel bakış API'sine bakın. Kullanacağınız hizmet için bir hesap oluşturmanız gerekir. Aşağıdaki bölümlerde hem Azure Tablo depolamanın hem de Azure Cosmos DB hesabının nasıl oluşturulacağı gösterilmektedir, ancak bunlardan yalnızca birini kullanabilirsiniz.
Azure depolama hesabı oluşturma
Azure depolama hesabı oluşturmanın en kolay yolu Azure portalını kullanmaktır. Daha fazla bilgi almak için bkz. Depolama hesabı oluşturma.
Azure PowerShell veya Azure CLI kullanarak da bir Azure depolama hesabı oluşturabilirsiniz.
Şu anda bir depolama hesabı oluşturmak istemiyorsanız, kodunuzu yerel bir ortamda çalıştırmak ve test etmek için Azure Depolama Öykünücüsü'ni de kullanabilirsiniz. Daha fazla bilgi için bkz . Geliştirme ve test için Azure Depolama Öykünücüsü'ni kullanma.
Tablo hesabı için Azure Cosmos DB oluşturma
Tablo hesabı için Azure Cosmos DB oluşturma yönergeleri için bkz . Veritabanı hesabı oluşturma.
Uygulamanızı Tablo Depolama'ya erişecek şekilde yapılandırma
Azure Depolama'yı veya Azure Cosmos DB'yi kullanmak için Depolama REST hizmetleriyle iletişim kuran bir dizi kolaylık kitaplığı içeren Node.js için Azure Tabloları SDK'sına ihtiyacınız vardır.
Paketi yüklemek için Düğüm Paket Yöneticisi’ni (NPM) kullanma
- PowerShell (Windows), Terminal (Mac) veya Bash (Unix) gibi bir komut satırı arabirimi kullanın ve uygulamanızı oluşturduğunuz klasöre gidin.
- Komut penceresine aşağıdakileri yazın:
npm install @azure/data-tables
- Bir node_modules klasörünün oluşturulduğunu doğrulamak için ls komutunu kendiniz çalıştırabilirsiniz. Bu klasörün içinde, tablolara erişmek için ihtiyacınız olan kitaplıkları içeren @azure/data-tables paketini bulacaksınız.
Paketi içeri aktarma
Uygulamanızda server.js dosyasının üst kısmına aşağıdaki kodu ekleyin:
const { TableServiceClient, TableClient, AzureNamedKeyCredential, odata } = require("@azure/data-tables");
Azure Tablo Depolama hizmetine bağlanma
Azure depolama hesabına veya Tablo için Azure Cosmos DB hesabına bağlanabilirsiniz. Kullandığınız hesabın türüne göre paylaşılan anahtarı veya bağlantı dizesi alın.
Paylaşılan anahtardan Tablo hizmeti istemcisi oluşturma
Azure modülü, Azure Depolama hesabınıza veya Azure Cosmos DB'ye bağlanmak için gereken bilgiler için AZURE_ACCOUNT, AZURE_ACCESS_KEY ve AZURE_TABLES_ENDPOINT ortam değişkenlerini okur. Bu ortam değişkenleri ayarlanmadıysa, çağrısı TableServiceClient
yaparken hesap bilgilerini belirtmeniz gerekir. Örneğin, aşağıdaki kod bir TableServiceClient
nesne oluşturur:
const endpoint = "<table-endpoint-uri>";
const credential = new AzureNamedKeyCredential(
"<account-name>",
"<account-key>"
);
const tableService = new TableServiceClient(
endpoint,
credential
);
Bir bağlantı dizesi Tablo hizmeti istemcisi oluşturma
Azure Cosmos DB veya Depolama hesabı bağlantısı eklemek için bir TableServiceClient
nesne oluşturun ve hesap adınızı, birincil anahtarınızı ve uç noktanızı belirtin. Bu değerleri Azure Cosmos DB hesabınız veya Depolama hesabınız için Azure portalındaki Ayarlar>Bağlantı Dizesi'nden kopyalayabilirsiniz. Örneğin:
const tableService = TableServiceClient.fromConnectionString("<connection-string>");
Tablo oluştur
çağrısı createTable
, henüz yoksa belirtilen ada sahip yeni bir tablo oluşturur. Aşağıdaki örnek, henüz yoksa, 'mytable' adlı yeni bir tablo oluşturur:
await tableService.createTable('<table-name>');
Tablo istemcisi oluşturma
Bir tabloyla etkileşim kurmak için, oluşturmak için kullandığınız kimlik bilgilerini kullanarak bir TableClient
nesne oluşturmanız TableServiceClient
gerekir. ayrıca TableClient
hedef tablonun adını gerektirir.
const tableClient = new TableClient(
endpoint,
'<table-name>',
credential
);
Tabloya bir varlık ekleme
Bir varlık eklemek için ilk olarak varlık özelliklerinizi tanımlayan bir nesne oluşturun. Tüm varlıklar, varlığın benzersiz tanımlayıcıları olan partitionKey ve rowKey içermelidir.
- partitionKey - Varlığın depolandığı bölümü belirler.
- rowKey - Bölümün içindeki varlığı benzersiz olarak tanımlar.
Hem partitionKey hem de rowKey dize değerleri olmalıdır.
Aşağıda, bir varlığın tanımlanmasına örnek verilmiştir. dueDate türü Date
olarak tanımlanır. Tür belirtme isteğe bağlıdır ve türler belirtilmezse çıkarsanır.
const task = {
partitionKey: "hometasks",
rowKey: "1",
description: "take out the trash",
dueDate: new Date(2015, 6, 20)
};
Not
Ayrıca her kayıt için bir Timestamp
varlık eklendiğinde veya güncelleştirildiğinde Azure tarafından ayarlanan bir alan vardır.
Tablonuza varlık eklemek için entity nesnesini yöntemine createEntity
geçirin.
let result = await tableClient.createEntity(task);
// Entity create
İşlem başarılı olursa, result
ETag'i ve işlemle ilgili bilgileri içerir.
Örnek yanıt:
{
clientRequestId: '94d8e2aa-5e02-47e7-830c-258e050c4c63',
requestId: '08963b85-1002-001b-6d8c-12ae5d000000',
version: '2019-02-02',
date: 2022-01-26T08:12:32.000Z,
etag: `W/"datetime'2022-01-26T08%3A12%3A33.0180348Z'"`,
preferenceApplied: 'return-no-content',
'cache-control': 'no-cache',
'content-length': '0'
}
Varlığı güncelleştirme
ve upsertEntity
yöntemleri için updateEntity
farklı modlar
- Birleştirme: Var olan varlığı değiştirmeden varlığın özelliklerini güncelleştirerek varlığı güncelleştirir.
- Değiştir: Varlığın tamamını değiştirerek var olan bir varlığı güncelleştirir.
Aşağıdaki örnekte kullanılarak upsertEntity
bir varlığın güncelleştirilmesi gösterilmektedir:
// Entity doesn't exist in table, so calling upsertEntity will simply insert the entity.
let result = await tableClient.upsertEntity(task, "Replace");
Güncelleştirilmekte olan varlık yoksa güncelleştirme işlemi başarısız olur; bu nedenle, var olup olmamasına bakılmaksızın bir varlığı depolamak istiyorsanız kullanın upsertEntity
.
Başarılı güncelleştirme işlemleri için result
, güncelleştirilen varlığın Etag değerini içerir.
Varlık gruplarıyla çalışma
Bazen, sunucu tarafından atomik olarak işlenmelerini sağlamak için birden fazla işlemin toplu bir işte bir arada gönderilmesi mantıklıdır. Bunu yapmak için bir işlem dizisi oluşturun ve üzerinde TableClient
yöntemine submitTransaction
geçirin.
Aşağıdaki örnekte, bir toplu işte iki varlığın gönderilmesi gösterilmektedir:
const task1 = {
partitionKey: "hometasks",
rowKey: "1",
description: "Take out the trash",
dueDate: new Date(2015, 6, 20)
};
const task2 = {
partitionKey: "hometasks",
rowKey: "2",
description: "Wash the dishes",
dueDate: new Date(2015, 6, 20)
};
const tableActions = [
["create", task1],
["create", task2]
];
let result = await tableClient.submitTransaction(tableActions);
// Batch completed
Başarılı toplu işlemler için result
, toplu işteki her bir işlemin bilgilerini içerir.
Anahtara göre bir varlık alma
PartitionKey ve RowKey tabanlı belirli bir varlığı döndürmek için getEntity yöntemini kullanın.
let result = await tableClient.getEntity("hometasks", "1")
.catch((error) => {
// handle any errors
});
// result contains the entity
Bu işlem tamamlandıktan sonra result
, varlığı içerir.
Varlık kümesi sorgulama
Aşağıdaki örnek, 'hometasks' PartitionKey değeriyle ilk beş öğeyi döndüren ve tablodaki tüm varlıkları listeleyen bir sorgu oluşturur.
const topN = 5;
const partitionKey = "hometasks";
const entities = tableClient.listEntities({
queryOptions: { filter: odata`PartitionKey eq ${partitionKey}` }
});
let topEntities = [];
const iterator = entities.byPage({ maxPageSize: topN });
for await (const page of iterator) {
topEntities = page;
break;
}
// Top entities: 5
console.log(`Top entities: ${topEntities.length}`);
// List all the entities in the table
for await (const entity of entities) {
console.log(entity);
}
Giriş özellikleri alt kümesi sorgulama
Bir tabloya yapılan sorgu, bir varlıktan yalnızca birkaç alan alabilir. Bu, bant genişliğini azaltır ve özellikle büyük varlıklar için sorgu performansını iyileştirebilir. select yan tümcesini kullanın ve döndürülecek alanların adlarını geçirin. Örneğin, aşağıdaki sorgu yalnızca description ve dueDate alanlarını döndürür.
const topN = 5;
const partitionKey = "hometasks";
const entities = tableClient.listEntities({
queryOptions: { filter: odata`PartitionKey eq ${partitionKey}`,
select: ["description", "dueDate"] }
});
let topEntities = [];
const iterator = entities.byPage({ maxPageSize: topN });
for await (const page of iterator) {
topEntities = page;
break;
}
Varlığı silme
Bölüm ve satır anahtarlarını kullanarak bir varlığı silebilirsiniz. Bu örnekte task1 nesnesi silinecek varlığın rowKey ve partitionKey değerlerini içerir. Daha sonra nesne, deleteEntity yöntemine geçirilir.
const tableClient = new TableClient(
tablesEndpoint,
tableName,
new AzureNamedKeyCredential("<accountName>", "<accountKey>")
);
await tableClient.deleteEntity("hometasks", "1");
// Entity deleted
Not
Öğeleri silerken, öğenin başka bir işlem tarafından değiştirilmediğinden emin olmak için ETag’leri kullanın. ETag’leri kullanma hakkında bilgi için bkz. Varlığı güncelleştirme.
Tablo silme
Aşağıdaki kod, bir depolama hesabından tabloyu siler.
await tableClient.deleteTable(mytable);
// Table deleted
Devamlılık belirteçlerini kullanma
Büyük miktarda sonuçlar için tabloları sorguluyorsanız devamlılık belirteçlerine bakın. Bir devamlılık belirtecinin mevcut olup olmadığını belirlemek için derleme yapmıyorsanız, sorgunuz için fark etmeyebileceğiniz büyük miktarlarda veriler olabilir.
Varlıkları sorgulama sırasında döndürülen results nesnesi, böyle bir belirteç mevcut olduğunda bir continuationToken
özelliği ayarlar. Daha sonra bölüm ve tablo varlıkları arasında hareket etmeye devam etmek için bir sorgu gerçekleştirirken bunu kullanabilirsiniz.
Sorgulama sırasında, sorgu nesnesi örneği ile geri çağrı işlevi arasında bir continuationToken
parametresi sağlayabilirsiniz:
let iterator = tableClient.listEntities().byPage({ maxPageSize: 2 });
let interestingPage;
const page = await tableClient
.listEntities()
.byPage({ maxPageSize: 2, continuationToken: interestingPage })
.next();
if (!page.done) {
for (const entity of page.value) {
console.log(entity.rowKey);
}
}
Paylaşılan erişim imzaları ile çalışma
Paylaşılan erişim imzaları (SAS), Depolama hesabı adınızı veya anahtarlarınızı sağlamadan tablolara ayrıntılı erişim sağlamanın güvenli bir yoludur. SAS çoğu zaman verilerinize sınırlı erişim sağlamak (örneğin, bir mobil uygulamanın kayıtları sorgulamasına izin verme) için kullanılır.
Bulut tabanlı hizmet gibi güvenilir bir uygulama, TableClient'ın generateTableSas'ını kullanarak bir SAS oluşturur ve bunu mobil uygulama gibi güvenilmeyen veya yarı güvenilir bir uygulamaya sağlar. SAS’ın geçerli olduğu başlangıç ve bitiş tarihlerini ve SAS sahibine verilen erişim düzeyini açıklayan bir ilke kullanılarak SAS oluşturulur.
Aşağıdaki örnek, SAS sahibinin tabloyu sorgulamasını ('r') sağlayacak yeni bir paylaşılan erişim ilkesi oluşturur.
const tablePermissions = {
query: true
// Allows querying entities
};
// Create the table SAS token
const tableSAS = generateTableSas('mytable', cred, {
expiresOn: new Date("2022-12-12"),
permissions: tablePermissions
});
ardından istemci uygulaması, tabloda işlem gerçekleştirmek için AzureSASCredential ile SAS kullanır. Aşağıdaki örnek, tabloya bağlanır ve bir sorgu gerçekleştirir. tableSAS biçimi için paylaşılan erişim imzalarını (SAS) kullanarak Azure Depolama kaynaklarına sınırlı erişim verme makalesine bakın.
// Note in the following command, tablesUrl is in the format: `https://<your_storage_account_name>.table.core.windows.net` and the tableSAS is in the format: `sv=2018-03-28&si=saspolicy&tn=mytable&sig=9aCzs76n0E7y5BpEi2GvsSv433BZa22leDOZXX%2BXXIU%3D`;
const tableService = new TableServiceClient(tablesUrl, new AzureSASCredential(tableSAS));
const partitionKey = "hometasks";
const entities = tableService.listTables({
queryOptions: { filter: odata`PartitionKey eq ${partitionKey}` }
});
SAS yalnızca sorgu erişimiyle oluşturulduğundan, varlıklar eklemeye, güncelleştirmeye veya silmeye çalışırsanız bir hata döndürülür.
Erişim Denetim Listeleri
Ayrıca SAS için erişim ilkesini ayarlamak istediğinizde de bir Erişim Denetim Listesi (ACL) kullanabilirsiniz. Birden çok istemcinin tabloya erişmesini, ancak her istemci için farklı erişim ilkeleri sağlamak istiyorsanız bu yararlıdır.
Her politikayla ilişkilendirilmiş bir kimlik ile, bir erişim ilkeleri dizisi kullanılarak ACL uygulanır. Aşağıdaki örnekte, biri 'user1' için ve biri de 'user2' için olmak üzere iki ilke tanımlanmaktadır:
var sharedAccessPolicy = [{
id:"user1",
accessPolicy:{
permission: "r" ,
Start: startsOn,
Expiry: expiresOn,
}},
{
id:"user2",
accessPolicy:{
permissions: "a",
Start: startsOn,
Expiry: expiresOn,
}},
]
Aşağıdaki örnek, hometasks tablosunun geçerli ACL'sini alır ve ardından setAccessPolicy kullanarak yeni ilkeleri ekler. Bu yaklaşım aşağıdakilere olanak sağlar:
tableClient.getAccessPolicy();
tableClient.setAccessPolicy(sharedAccessPolicy);
ACL ayarlandıktan sonra, bir ilke için kimliğe dayalı bir SAS oluşturabilirsiniz. Aşağıdaki örnek, 'user2' için yeni bir SAS oluşturur:
tableSAS = generateTableSas("hometasks",cred,{identifier:'user2'});
Sonraki adımlar
Daha fazla bilgi için aşağıdaki kaynaklara bakın.
- Microsoft Azure Depolama Gezgini, Microsoft’un Windows, macOS ve Linux üzerinde Azure Depolama verileriyle görsel olarak çalışmanızı sağlayan ücretsiz ve tek başına uygulamasıdır.
- GitHub'daki Node.js deposu için Azure Veri Tabloları SDK'sı.
- Azure’da Node.js web uygulaması oluşturma
- Bir Node.js uygulaması derleme ve Azure Cloud Service’e dağıtma (Windows PowerShell kullanarak)
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