Node.js'dan Azure Tablo depolamayı veya Tablo için Azure Cosmos DB'yi kullanma

ŞUNLAR IÇIN GEÇERLIDIR: Tablo

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 depolama hesabı oluşturmamak isterseniz, 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 erişecek şekilde yapılandırma

Azure Depolama 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

1. PowerShell (Windows), Terminal (Mac) veya Bash (Unix) gibi bir komut satırı arabirimi kullanın ve uygulamanızı oluşturduğunuz klasöre gidin.
2. Komut penceresine aşağıdakileri yazın:

   npm install @azure/data-tables

3. 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'nize 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ı TableServiceClientyaparken 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 hesap 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ğlan ion Dizesinden 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 TableServiceClientgerekir. 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ü Dateolarak 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)
};

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 bir varlığı Güncelleştirmeler.
• Değiştir: Varlığın tamamını değiştirerek var olan bir varlığı Güncelleştirmeler.

Aşağıdaki örnekte kullanılarak upsertEntitybir 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 TableClientyö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

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)