JavaScript için Azure Tabloları istemci kitaplığı - sürüm 13.2.2

  • Makale

Azure Tabloları , yapılandırılmış NoSQL verilerini depolayan ve şemasız tasarıma sahip bir anahtar/öznitelik deposu sağlayan bulut tabanlı bir hizmettir. Tablo depolama, geliştiricilere Azure bulutunun en iyi parçalarıyla esneklik ve ölçeklenebilirlik sağlar.

İstemci kitaplığını kullanarak:

  • Tablo Oluşturma/Silme
  • Varlıkları Sorgulama/Oluşturma/Okuma/Güncelleştirme/Silme

Azure Cosmos DB, Azure Tablo depolama için yazılmış ve aşağıdaki gibi premium özelliklere ihtiyaç duyan uygulamalar için bir Tablo API'sini sağlar:

  • Anahtar teslimi genel dağıtım.
  • Dünya genelinde adanmış aktarım hızı.
  • 99 yüzdebirlikte tek basamaklı milisaniyelik gecikme süresi.
  • Garantili yüksek kullanılabilirlik.
  • Otomatik ikincil dizin oluşturma.
  • Azure Tabloları istemci kitaplığı, kod değişikliği olmadan Azure tablo depolamasını veya Azure Cosmos DB tablo hizmeti uç noktalarını sorunsuz bir şekilde hedefleyebilir.

Önemli bağlantılar:

Başlarken

Önkoşullar

Şu anda desteklenen ortamlar:

  • Node.js LTS sürümleri
  • Safari, Chrome, Edge ve Firefox'un en son sürümleri

Bu paketi kullanmak için bir Azure aboneliğine ve Depolama Hesabına veya Azure CosmosDB veritabanına sahip olmanız gerekir.

@azure/data-tables paketini yükleyin

JavaScript için Azure Tabloları istemci kitaplığını yüklemenin tercih edilen yolu npm paket yöneticisini kullanmaktır. Terminal penceresine aşağıdakileri yazın:

npm install @azure/data-tables

Kimlik doğrulaması TableServiceClient

Azure Tabloları kimlik doğrulaması için çeşitli yolları destekler. Azure Tables hizmetiyle etkileşim kurmak için tablolar istemcisinin TableServiceClientTableClient örneğini oluşturmanız gerekir. Kimlik doğrulaması hakkında daha fazla bilgi edinmek için oluşturma TableServiceClientörneklerine bakın.

Not: Azure Active Directory (AAD) yalnızca Azure Depolama hesapları için desteklenir.

Aşağıdaki özellikler, arabirimler, sınıflar veya işlevler yalnızca Node.js

  • Hesap adına ve hesap anahtarına göre Paylaşılan Anahtar Yetkilendirmesi
    • AzureNamedKeyCredential
    • Hesap bağlantı dizesi.

JavaScript Paketi

Bu istemci kitaplığını tarayıcıda kullanmak için önce bir paketleyici kullanmanız gerekir. Bunun nasıl yapılacağının ayrıntıları için lütfen paketleme belgelerimize bakın.

CORS

Tarayıcılar için geliştirmeniz gerekiyorsa depolama hesabınız için Çıkış Noktaları Arası Kaynak Paylaşımı (CORS) kuralları ayarlamanız gerekir. Azure portal ve Azure Depolama Gezgini gidin, depolama hesabınızı bulun, blob/kuyruk/dosya/tablo hizmetleri için yeni CORS kuralları oluşturun.

Örneğin, hata ayıklama için aşağıdaki CORS ayarlarını oluşturabilirsiniz. Ancak lütfen üretim ortamındaki gereksinimlerinize göre ayarları dikkatli bir şekilde özelleştirin.

  • İzin verilen çıkış noktaları: *
  • İzin verilen fiiller: DELETE,GET,HEAD,MERGE,POST,OPTIONS,PUT
  • İzin verilen üst bilgiler: *
  • Kullanıma sunulan üst bilgiler: *
  • Maksimum yaş (saniye): 86400

Önemli kavramlar

  • TableServiceClient - Tablo oluşturma, listeleme ve silme gibi Tablo Hizmeti düzeyinde etkileşime geçmek için işlevler sağlayan istemci

  • TableClient - Tablo içindeki varlıkları oluşturma, listeleme ve silme gibi varlık düzeyinde etkileşime geçmek için işlevler sağlayan istemci.

  • Table - Tablolar verileri varlık koleksiyonları olarak depolar.

  • Entity - Varlıklar satırlara benzer. Bir varlığın birincil anahtarı ve bir özellik kümesi vardır. Özellik, sütuna benzer bir ad, türü yazılan değer çiftidir.

Tablo hizmetinin genel kullanımları şunları içerir:

  • Web ölçekli uygulamalara hizmet verebilen yapılandırılmış verilerin TB depolaması
  • Karmaşık birleşimler, yabancı anahtarlar veya saklı yordamlar gerektirmeyen ve hızlı erişim için normalleştirilebilen veri kümelerini depolama
  • Kümelenmiş dizin kullanarak hızlı veri sorgulaması
  • OData protokolü filtre ifadelerini kullanarak verilere erişme

Örnekler

Paketi içeri aktarma

İstemcileri kullanmak için paketi dosyanıza aktarın:

const AzureTables = require("@azure/data-tables");

Alternatif olarak, yalnızca ihtiyacınız olan türleri seçmeli olarak içeri aktarın:

const { TableServiceClient, AzureNamedKeyCredential } = require("@azure/data-tables");

Tablo hizmeti istemcisi oluşturma

, TableServiceClient tablo hizmetinin URL'sini ve erişim kimlik bilgilerini gerektirir. Ayrıca isteğe bağlı olarak parametresindeki options bazı ayarları kabul eder.

TableServiceClient AzureNamedKeyCredential ile

hesap adını ve hesap anahtarını bağımsız değişken olarak geçirerek ile AzureNamedKeyCredential bir örneği TableServiceClient oluşturabilirsiniz. (Hesap adı ve hesap anahtarı azure portalından alınabilir.) [YALNıZCA NODE.JS ÇALıŞMA ZAMANıNDA KULLANıLABILIR]

const { TableServiceClient, AzureNamedKeyCredential } = require("@azure/data-tables");

const account = "<account>";
const accountKey = "<accountkey>";

const credential = new AzureNamedKeyCredential(account, accountKey);
const serviceClient = new TableServiceClient(
  `https://${account}.table.core.windows.net`,
  credential
);

TableServiceClient TokenCredential (AAD) ile

Azure Tabloları, Depolama uç noktasını hedeflerken Tablo hizmetine yönelik isteklerin kimlik tabanlı kimlik doğrulaması için Azure Active Directory (Azure AD) ile tümleştirme sağlar. Azure AD ile rol tabanlı erişim denetimini (RBAC) kullanarak Azure Tablo kaynaklarınıza kullanıcılara, gruplara veya uygulamalara erişim verebilirim.

ile TokenCredentialbir tablo kaynağına erişmek için kimliği doğrulanmış kimliğin "Depolama Tablosu Veri Katkıda Bulunanı" veya "Depolama Tablosu Veri Okuyucusu" rolü olmalıdır.

Paketiyle @azure/identity , hem geliştirme hem de üretim ortamlarında istekleri sorunsuz bir şekilde yetkilendirebilirsiniz. Azure Depolama'da Azure AD tümleştirmesi hakkında daha fazla bilgi edinmek için bkz. Azure.Identity README

const { TableServiceClient } = require("@azure/data-tables");
const { DefaultAzureCredential } = require("@azure/identity");

// DefaultAzureCredential expects the following three environment variables:
// - AZURE_TENANT_ID: The tenant ID in Azure Active Directory
// - AZURE_CLIENT_ID: The application (client) ID registered in the AAD tenant
// - AZURE_CLIENT_SECRET: The client secret for the registered application
const credential = new DefaultAzureCredential();
const account = "<account name>";

const clientWithAAD = new TableServiceClient(
  `https://${account}.table.core.windows.net`,
  credential
);

TableServiceClient SAS Belirteci ile

Ayrıca, paylaşılan erişim imzalarıyla (SAS) bir TableServiceClient örneği oluşturabilirsiniz. SAS belirtecini Azure Portal'dan alabilirsiniz.

const { TableServiceClient, AzureSASCredential } = require("@azure/data-tables");

const account = "<account name>";
const sas = "<service Shared Access Signature Token>";

const serviceClientWithSAS = new TableServiceClient(
  `https://${account}.table.core.windows.net`,
  new AzureSASCredential(sas)
);

Hesaptaki tabloları listeleme

bir hesap içindeki tabloları işlevi çağıran listTables bir TableServiceClient örnek aracılığıyla listeleyebilirsiniz. Bu işlev kullanarak kullanabileceğiniz bir PageableAsyncIterator döndürür for-await-of

const { TableServiceClient, AzureNamedKeyCredential } = require("@azure/data-tables");

const account = "<account>";
const accountKey = "<accountkey>";

const credential = new AzureNamedKeyCredential(account, accountKey);
const serviceClient = new TableServiceClient(
  `https://${account}.table.core.windows.net`,
  credential
);

async function main() {
  let tablesIter = serviceClient.listTables();
  let i = 1;
  for await (const table of tablesIter) {
    console.log(`Table${i}: ${table.name}`);
    i++;
    // Output:
    // Table1: testTable1
    // Table1: testTable2
    // Table1: testTable3
    // Table1: testTable4
    // Table1: testTable5
  }
}

main();

Yeni tablo oluşturma

İşlevi çağıran createTable bir TableServiceClient örnek aracılığıyla tablo oluşturabilirsiniz. Bu işlev, parametre olarak oluşturulacak tablonun adını alır. createTable Tablo zaten mevcut olduğunda hata oluşturmayacağını unutmayın.

const { TableServiceClient, AzureNamedKeyCredential } = require("@azure/data-tables");

const account = "<account>";
const accountKey = "<accountkey>";

const credential = new AzureNamedKeyCredential(account, accountKey);
const serviceClient = new TableServiceClient(
  `https://${account}.table.core.windows.net`,
  credential
);

async function main() {
  const tableName = `newtable`;
  // If the table 'newTable' already exists, createTable doesn't throw
  await serviceClient.createTable(tableName);
}

main();

Aşağıda, tablo oluşturulmaya çalışılırken tablonun zaten var olup olmadığını test etme işlemini gösteren bir örnek verilmiştir:

const { TableServiceClient, AzureNamedKeyCredential } = require("@azure/data-tables");

const account = "<account>";
const accountKey = "<accountkey>";

const credential = new AzureNamedKeyCredential(account, accountKey);
const serviceClient = new TableServiceClient(
  `https://${account}.table.core.windows.net`,
  credential
);

async function main() {
  const tableName = `newtable${new Date().getTime()}`;
  await serviceClient.createTable(tableName, {
    onResponse: (response) => {
      if (response.status === 409) {
        console.log(`Table ${tableName} already exists`);
      }
    }
  });
}

main();

Tablo istemcisi oluşturma

, TableClient tablo adını parametre olarak TableServiceClient alan farkla TableClient benzer bir şekilde oluşturulur

TableClient Ile AzureNamedKeyCredential

Hesap adını ve hesap anahtarını bağımsız değişken olarak geçirerek ile AzureNamedKeyCredential bir örneği TableClient oluşturabilirsiniz. (Hesap adı ve hesap anahtarı azure portalından alınabilir.) [YALNıZCA NODE.JS ÇALıŞMA ZAMANıNDA KULLANıLABILIR]

const { TableClient, AzureNamedKeyCredential } = require("@azure/data-tables");

// Enter your storage account name and shared key
const account = "<account>";
const accountKey = "<accountkey>";
const tableName = "<tableName>";

// Use AzureNamedKeyCredential with storage account and account key
// AzureNamedKeyCredential is only available in Node.js runtime, not in browsers
const credential = new AzureNamedKeyCredential(account, accountKey);
const client = new TableClient(`https://${account}.table.core.windows.net`, tableName, credential);

TableClient ile TokenCredential (Azure Active Directory)

Azure Tabloları, Depolama uç noktasını hedeflerken Tablo hizmetine yönelik isteklerin kimlik tabanlı kimlik doğrulaması için Azure Active Directory (Azure AD) ile tümleştirme sağlar. Azure AD ile azure tablo kaynaklarınıza kullanıcılara, gruplara veya uygulamalara erişim vermek için rol tabanlı erişim denetimini (RBAC) kullanabilirsiniz.

ile TokenCredentialbir tablo kaynağına erişmek için kimliği doğrulanmış kimliğin "Depolama Tablosu Veri Katkıda Bulunanı" veya "Depolama Tablosu Veri Okuyucusu" rolü olmalıdır.

Paketle @azure/identity , hem geliştirme hem de üretim ortamlarında istekleri sorunsuz bir şekilde yetkilendirebilirsiniz. Azure Depolama'da Azure AD tümleştirmesi hakkında daha fazla bilgi edinmek için bkz. Azure.Identity README

const { TableClient } = require("@azure/data-tables");
const { DefaultAzureCredential } = require("@azure/identity");

// DefaultAzureCredential expects the following three environment variables:
// - AZURE_TENANT_ID: The tenant ID in Azure Active Directory
// - AZURE_CLIENT_ID: The application (client) ID registered in the AAD tenant
// - AZURE_CLIENT_SECRET: The client secret for the registered application
const credential = new DefaultAzureCredential();
const account = "<account name>";
const tableName = "<tableName>";

const clientWithAAD = new TableClient(
  `https://${account}.table.core.windows.net`,
  tableName,
  credential
);

TableClient SAS Belirteci ile

Paylaşılan erişim imzalarıyla (SAS) örneğini TableClient oluşturabilirsiniz. SAS belirtecini Azure Portal'dan alabilirsiniz.

const { TableClient, AzureSASCredential } = require("@azure/data-tables");

const account = "<account name>";
const sas = "<service Shared Access Signature Token>";
const tableName = "<tableName>";

const clientWithSAS = new TableClient(
  `https://${account}.table.core.windows.net`,
  tableName,
  new AzureSASCredential(sas)
);

TableClient TokenCredential (AAD) ile

Azure Tabloları, Depolama uç noktasını hedeflerken Tablo hizmetine yönelik isteklerin kimlik tabanlı kimlik doğrulaması için Azure Active Directory (Azure AD) ile tümleştirme sağlar. Azure AD ile azure tablo kaynaklarınıza kullanıcılara, gruplara veya uygulamalara erişim vermek için rol tabanlı erişim denetimini (RBAC) kullanabilirsiniz.

ile TokenCredentialbir tablo kaynağına erişmek için kimliği doğrulanmış kimliğin "Depolama Tablosu Veri Katkıda Bulunanı" veya "Depolama Tablosu Veri Okuyucusu" rolü olmalıdır.

Paketle @azure/identity , hem geliştirme hem de üretim ortamlarında istekleri sorunsuz bir şekilde yetkilendirebilirsiniz. Azure Depolama'da Azure AD tümleştirmesi hakkında daha fazla bilgi edinmek için bkz. Azure.Identity README

const { TableClient } = require("@azure/data-tables");
const { DefaultAzureCredential } = require("@azure/identity");

// DefaultAzureCredential expects the following three environment variables:
// - AZURE_TENANT_ID: The tenant ID in Azure Active Directory
// - AZURE_CLIENT_ID: The application (client) ID registered in the AAD tenant
// - AZURE_CLIENT_SECRET: The client secret for the registered application
const credential = new DefaultAzureCredential();
const account = "<account name>";
const tableName = "<tableName>";

const clientWithAAD = new TableClient(
  `https://${account}.table.core.windows.net`,
  tableName,
  credential
);

Tablodaki Varlıkları Listeleme

İşlevi çağıran listEntities bir TableClient örnek aracılığıyla tablo içindeki varlıkları listeleyebilirsiniz. Bu işlev kullanarak kullanabileceğiniz bir PageableAsyncIterator döndürür for-await-of

const { TableClient, AzureNamedKeyCredential } = require("@azure/data-tables");

const account = "<account>";
const accountKey = "<accountkey>";
const tableName = "<tableName>";

const credential = new AzureNamedKeyCredential(account, accountKey);
const client = new TableClient(`https://${account}.table.core.windows.net`, tableName, credential);

async function main() {
  let entitiesIter = client.listEntities();
  let i = 1;
  for await (const entity of entitiesIter) {
    console.log(`Entity${i}: PartitionKey: ${entity.partitionKey} RowKey: ${entity.rowKey}`);
    i++;
    // Output:
    // Entity1: PartitionKey: P1 RowKey: R1
    // Entity2: PartitionKey: P2 RowKey: R2
    // Entity3: PartitionKey: P3 RowKey: R3
    // Entity4: PartitionKey: P4 RowKey: R4
  }
}

main();

Yeni varlık oluşturma ve tabloya ekleme

İşlevi çağıran createEntity bir örnek aracılığıyla tabloda yeni bir TableClient Varlık oluşturabilirsiniz. Bu işlev parametre olarak eklemek için varlığı alır. Varlığın ve rowKeyiçermesi partitionKey gerekir.

const { TableClient, AzureNamedKeyCredential } = require("@azure/data-tables");

const account = "<account>";
const accountKey = "<accountkey>";
const tableName = "<tableName>";

const credential = new AzureNamedKeyCredential(account, accountKey);
const client = new TableClient(`https://${account}.table.core.windows.net`, tableName, credential);

async function main() {
  const testEntity = {
    partitionKey: "P1",
    rowKey: "R1",
    foo: "foo",
    bar: 123
  };
  await client.createEntity(testEntity);
}

main();

Azurite ve Depolama Öykünücüsü

Azure Tablolar İstemci SDK'sı, Azure Depolama ve Tablolar API'siyle uyumlu bir sunucu öykünücüsü olan Azurite ile de çalışır. Kullanmaya başlamak için lütfen (Azurite deposu) bölümüne bakın.

Bağlantı Dizesi kısayoluyla Azurite'ye bağlanma

Uygulamanızdan Azurite'ye bağlanmanın en kolay yolu, kısayola UseDevelopmentStorage=truebaşvuran bir bağlantı dizesi yapılandırmaktır. Kısayol, öykünücünün hesap adını, hesap anahtarını ve Azure Depolama hizmetlerinin her biri için öykünücü uç noktalarını belirten tam bağlantı dizesine eşdeğerdir: (daha fazla bilgi için bkz. Azure Tablolar İstemci SDK'sı bu kısayolu kullanarak varsayılan bağlantı dizesini ve allowInsecureConnection istemci seçeneklerinde ayarlayabilir.

import { TableClient } from "@azure/data-tables";

const connectionString = "UseDevelopmentStorage=true";
const client = TableClient.fromConnectionString(connectionString, "myTable");

Bağlantı Dizesi kısayolu olmadan Azurite'ye bağlanma

Hizmet URL'sini ve AzureNamedKeyCredential özel bir bağlantı dizesini belirterek bağlantı dizesi kısayolunu kullanmadan azurite'ye el ile bağlanabilirsiniz. Ancak, allowInsecureConnection Azurite'nin bir http uç noktada çalışması durumunda el ile ayarlanması gerekir.

import { TableClient, AzureNamedKeyCredential } from "@azure/data-tables";

const client = new TableClient(
  "<Azurite-http-table-endpoint>",
  "myTable",
  new AzureNamedKeyCredential("<Azurite-account-name>", "<Azurite-account-key>"),
  { allowInsecureConnection: true }
);

Sorun giderme

Genel

Javascript/Typescript SDK'sını kullanarak Tablolar hizmetiyle etkileşim kurarken, hizmet tarafından döndürülen hatalar REST API istekleri için döndürülen http durum kodlarıyla aynı olur: Depolama Tablo Hizmeti Hata Kodları

Günlüğe Kaydetme

Günlüğün etkinleştirilmesi hatalarla ilgili yararlı bilgilerin ortaya çıkarılmasına yardımcı olabilir. HTTP isteklerinin ve yanıtlarının günlüğünü görmek için ortam değişkenini AZURE_LOG_LEVEL olarak infoayarlayın. Alternatif olarak, günlüğü çalışma zamanında içinde çağrılarak setLogLevel@azure/loggeretkinleştirilebilir:

const { setLogLevel } = require("@azure/logger");

setLogLevel("info");

Sonraki adımlar

Yakında daha fazla kod örneği geliyor Sorun#10531

Katkıda bulunma

Bu proje, katkı ve önerilere açıktır. Çoğu durumda, sağladığınız katkıyı kullanmamız için bize hak tanıma hakkına sahip olduğunuzu ve bu hakkı bize tanıdığınızı bildiren bir Katkıda Bulunan Lisans Sözleşmesi’ni (CLA) kabul etmeniz gerekir. Ayrıntılar için bkz. https://cla.microsoft.com.

Bir çekme isteği gönderdiğinizde, CLA robotu bir CLA sağlamanız gerekip gerekmediğini otomatik olarak belirler ve çekme isteğini uygun şekilde donatır (örn. etiket, açıklama). Robot tarafından sağlanan yönergeleri izlemeniz yeterlidir. Bu işlemi, CLA’mızı kullanarak tüm depolarda yalnızca bir kere yapmanız gerekir.

Bu proje Microsoft Open Source Code of Conduct (Microsoft Açık Kaynak Kullanım Kuralları) belgesinde listelenen kurallara uygundur. Daha fazla bilgi için Kullanım Kuralları SSS bölümüne bakın veya ek sorular veya yorumlarla iletişime geçin opencode@microsoft.com .

Bu kitaplığa katkıda bulunmak isterseniz, kodu derleme ve test etme hakkında daha fazla bilgi edinmek için lütfen katkıda bulunma kılavuzunu okuyun.

İzlenimler