Klientská knihovna Azure Tables pro JavaScript – verze 13.3.0

tabulky Azure je cloudová služba, která ukládá strukturovaná data NoSQL a poskytuje úložiště klíčů a atributů s návrhem bez schématu. Table Storage poskytuje vývojářům flexibilitu a škálovatelnost se všemi nejlepšími částmi cloudu Azure.

Klientskou knihovnu použijte k:

• Vytvoření nebo odstranění tabulek
• Dotaz, vytvoření, čtení, aktualizace, odstranění entit

Azure Cosmos DB poskytuje rozhraní API pro tabulky pro aplikace napsané pro Azure Table Storage a potřebují prémiové funkce, jako jsou:

• Globální distribuce na klíč
• Vyhrazená propustnost po celém světě.
• Latence v řádu milisekund na 99. percentilu
• Zaručená vysoká dostupnost.
• Automatické sekundární indexování.
• Klientská knihovna Azure Tables může bez problémů cílit na úložiště tabulek Azure nebo koncové body tabulkové služby Azure Cosmos DB beze změn kódu.

Klíčové odkazy:

• zdrojového kódu
• balíčku (NPM)
• Referenční dokumentace k rozhraní API
• dokumentace k produktu
• ukázky

Začínáme

Požadavky

Aktuálně podporovaná prostředí:

• Verze LTS Node.js
• Nejnovější verze Safari, Chrome, Edge a Firefox

Abyste mohli tento balíček používat, musíte mít předplatné Azure a účet úložiště nebo databázi Azure CosmosDB.

Instalace balíčku @azure/data-tables

Upřednostňovaným způsobem instalace klientské knihovny Azure Tables pro JavaScript je použití správce balíčků npm. Do okna terminálu zadejte následující:

npm install @azure/data-tables

Ověření TableServiceClient

Tabulky Azure podporují několik způsobů ověřování. Abyste mohli pracovat se službou Azure Tables Service, budete muset vytvořit instanci klienta Tabulky – například TableServiceClient nebo TableClient. Další informace o ověřování najdete v ukázkách pro vytvoření TableServiceClient.

Poznámka: Azure Active Directory (AAD) se podporuje jenom pro účty Azure Storage.

• klient služby se sdíleným klíčem
• klient služby se sdílenými přístupovými podpisy
• klient služby s TokenCredential (AAD)
• klient tabulky se sdíleným klíčem
• klient Table se sdílenými přístupovými podpisy
• klient tabulky s TokenCredential (AAD)

Následující funkce, rozhraní, třídy nebo funkce jsou k dispozici pouze v Node.js

• Autorizace sdíleného klíče na základě názvu účtu a klíče účtu
  • AzureNamedKeyCredential
  • Připojovací řetězec účtu

JavaScript Bundle

Pokud chcete tuto klientskou knihovnu použít v prohlížeči, musíte nejprve použít bundler. Podrobnosti o tom, jak to udělat, najdete v naší dokumentaci sdružování.

CORS

Pokud potřebujete vyvíjet prohlížeče, musíte pro svůj účet úložiště nastavit sdílení prostředků mezi zdroji (CORS) pravidla. Přejděte na Azure Portal a Průzkumníka služby Azure Storage, vyhledejte svůj účet úložiště, vytvořte nová pravidla CORS pro služby blob, queue, file/table service.

Můžete například vytvořit následující nastavení CORS pro ladění. Přizpůsobte si ale nastavení pečlivě podle svých požadavků v produkčním prostředí.

• Povolené původy: *
• Povolené příkazy: DELETE, GET, HEAD, MERGE, POST, OPTIONS, PUT
• Povolené hlavičky: *
• Vystavené hlavičky: *
• Maximální stáří (sekundy): 86400

Klíčové koncepty

• TableServiceClient – Klient, který poskytuje funkce pro interakci na úrovni služby Table Service, jako jsou vytváření, výpis a odstraňování tabulek

• TableClient – klient, který poskytuje funkce pro interakci na úrovni entity, jako je vytvoření, výpis a odstranění entit v tabulce.

• Table – Tabulky ukládají data jako kolekce entit.

• Entity – Entity jsou podobné řádkům. Entita má primární klíč a sadu vlastností. Vlastnost je název, páry typ-hodnota, podobně jako sloupec.

Mezi běžné použití služby Table Service patří:

• Ukládání databází strukturovaných dat schopných obsluhovat aplikace s webovým škálováním
• Ukládání datových sad, které nevyžadují složitá spojení, cizí klíče nebo uložené procedury, a je možné je zrušit normalizaci pro rychlý přístup.
• Rychlé dotazování dat pomocí clusterovaného indexu
• Přístup k datům pomocí výrazů filtru protokolu OData

Příklady

• Import balíčku
• Vytvoření klienta služby Table Service
  • Výpis tabulek v účtu
  • Vytvoření nové tabulky
• Vytvoření klienta tabulky
  • Seznam entit v tabulce
  • Vytvoření nové entity a jeho přidání do tabulky

Import balíčku

Pokud chcete použít klienty, naimportujte balíček do souboru:

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

Alternativně selektivně importujte jenom ty typy, které potřebujete:

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

Vytvoření klienta služby Table Service

TableServiceClient vyžaduje adresu URL služby Table Service a přihlašovací údaje pro přístup. Volitelně také přijímá některá nastavení v parametru options.

TableServiceClient s využitím AzureNamedKeyCredential

Instanci TableServiceClient s AzureNamedKeyCredential můžete vytvořit předáním názvu účtu a klíče účtu jako argumentů. (Název účtu a klíč účtu je možné získat z webu Azure Portal.) [K DISPOZICI POUZE V NODE.JS RUNTIME]

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 s tokenCredential (AAD)

Tabulky Azure poskytují integraci se službou Azure Active Directory (Azure AD) pro ověřování na základě identit požadavků na službu Table Service při cílení na koncový bod úložiště. Pomocí Azure AD můžete pomocí řízení přístupu na základě role (RBAC) udělit přístup k prostředkům tabulky Azure uživatelům, skupinám nebo aplikacím.

Pro přístup k prostředku tabulky s TokenCredentialby ověřená identita měla mít roli Přispěvatel dat tabulky úložiště nebo Čtenář dat tabulky úložiště.

S balíčkem @azure/identity můžete bez problémů autorizovat požadavky v vývojových i produkčních prostředích. Další informace o integraci Azure AD ve službě Azure Storage najdete v 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 s tokenem SAS

Můžete také vytvořit instanci TableServiceClient se sdílenými přístupovými podpisy (SAS). Token SAS můžete získat z webu Azure Portal.

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)
);

Výpis tabulek v účtu

Tabulky v rámci účtu můžete vypsat prostřednictvím instance TableServiceClient, která volá funkci listTables. Tato funkce vrátí PageableAsyncIterator, kterou můžete využívat pomocí 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() {
  const 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();

Vytvoření nové tabulky

Tabulku můžete vytvořit prostřednictvím instance TableServiceClient, která volá funkci createTable. Tato funkce přebírá název tabulky, která se vytvoří jako parametr. Mějte na paměti, že createTable nevyvolá chybu, pokud tabulka již existuje.

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();

Tady je ukázka, která ukazuje, jak otestovat, jestli tabulka již existuje při pokusu o jeho vytvoření:

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();

Vytvoření klienta tabulky

TableClient se vytvoří podobným způsobem jako TableServiceClient s rozdílem, že TableClient jako parametr přebírá název tabulky.

TableClient s AzureNamedKeyCredential

Instanci TableClient s AzureNamedKeyCredential můžete vytvořit předáním názvu účtu a klíče účtu jako argumentů. (Název účtu a klíč účtu je možné získat z webu Azure Portal.) [K DISPOZICI POUZE V NODE.JS RUNTIME]

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 s TokenCredential (Azure Active Directory)

Tabulky Azure poskytují integraci se službou Azure Active Directory (Azure AD) pro ověřování na základě identit požadavků na službu Table Service při cílení na koncový bod úložiště. Pomocí Azure AD můžete pomocí řízení přístupu na základě role (RBAC) udělit přístup k prostředkům tabulky Azure uživatelům, skupinám nebo aplikacím.

Pro přístup k prostředku tabulky s TokenCredentialby ověřená identita měla mít roli Přispěvatel dat tabulky úložiště nebo Čtenář dat tabulky úložiště.

S balíčkem @azure/identity můžete bez problémů autorizovat požadavky v vývojových i produkčních prostředích. Další informace o integraci Azure AD ve službě Azure Storage najdete v 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 s tokenem SAS

Můžete vytvořit instanci TableClient se sdílenými přístupovými podpisy (SAS). Token SAS můžete získat z webu Azure Portal.

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 s tokenCredential (AAD)

Tabulky Azure poskytují integraci se službou Azure Active Directory (Azure AD) pro ověřování na základě identit požadavků na službu Table Service při cílení na koncový bod úložiště. Pomocí Azure AD můžete pomocí řízení přístupu na základě role (RBAC) udělit přístup k prostředkům tabulky Azure uživatelům, skupinám nebo aplikacím.

Pro přístup k prostředku tabulky s TokenCredentialby ověřená identita měla mít roli Přispěvatel dat tabulky úložiště nebo Čtenář dat tabulky úložiště.

S balíčkem @azure/identity můžete bez problémů autorizovat požadavky v vývojových i produkčních prostředích. Další informace o integraci Azure AD ve službě Azure Storage najdete v 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
);

Výpis entit v tabulce

Entity v tabulce můžete vypsat prostřednictvím instance TableClient, která volá funkci listEntities. Tato funkce vrátí PageableAsyncIterator, kterou můžete využívat pomocí 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() {
  const 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();

Vytvoření nové entity a jeho přidání do tabulky

Novou entitu v tabulce můžete vytvořit prostřednictvím instance TableClient, která volá funkci createEntity. Tato funkce vezme entitu, která se vloží jako parametr. Entita musí obsahovat partitionKey a rowKey.

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 a emulátor úložiště

Klientská sada SDK pro tabulky Azure také funguje s emulátorem serveru kompatibilním s Azurite, rozhraním AZURE Storage a Table API. Informace o tom, jak začít používat, najdete v úložišti (Azurite).

Připojení k Azurite pomocí zástupce připojovacího řetězce

Nejjednodušší způsob, jak se připojit k Azurite z vaší aplikace, je nakonfigurovat připojovací řetězec, který odkazuje na zástupce UseDevelopmentStorage=true. Zástupce odpovídá úplnému připojovacímu řetězci emulátoru, který určuje název účtu, klíč účtu a koncové body emulátoru pro každou službu Azure Storage: (zobrazit další). Pomocí této klávesové zkratky by klientská sada AZURE Tables SDK nastavovala výchozí připojovací řetězec a allowInsecureConnection v možnostech klienta.

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

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

Připojení k Azurite bez zástupce připojovacího řetězce

K azurite se můžete připojit ručně bez použití zástupce připojovacího řetězce zadáním adresy URL služby a AzureNamedKeyCredential nebo vlastního připojovacího řetězce. V případě, že se Azurite spouští v koncovém bodu http, je však potřeba allowInsecureConnection nastavit ručně.

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 }
);

Řešení problémů

Obecné

Při interakci se službou Tables pomocí sady JavaScript/TypeScript SDK odpovídají chyby vrácené službou stejným stavovým kódům HTTP vráceným pro požadavky REST API: kódy chyb služby Table Service služby storage

Protokolování

Povolení protokolování může pomoct odhalit užitečné informace o chybách. Pokud chcete zobrazit protokol požadavků a odpovědí HTTP, nastavte proměnnou prostředí AZURE_LOG_LEVEL na info. Případně můžete protokolování povolit za běhu voláním setLogLevel v @azure/logger:

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

setLogLevel("info");

Další kroky

Připravujeme další ukázky kódu – Problém č. 10531

Přispívající

Tento projekt vítá příspěvky a návrhy. Většina příspěvků vyžaduje souhlas s licenční smlouvou s přispěvatelem (CLA), která deklaruje, že máte právo a ve skutečnosti nám udělíte práva k používání vašeho příspěvku. Podrobnosti najdete v https://cla.microsoft.com.

Když odešlete žádost o přijetí změn, robot CLA automaticky určí, jestli potřebujete poskytnout CLA, a odpovídajícím způsobem vyzdobit žádost o přijetí změn (např. popisek, komentář). Stačí postupovat podle pokynů poskytovaných robotem. Stačí to udělat jen jednou napříč všemi úložištěmi pomocí naší cla.

Tento projekt přijal pravidla chování microsoftu open source . Další informace najdete v nejčastějších dotazech k kodexu chování nebo kontaktujte opencode@microsoft.com s dalšími dotazy nebo komentáři.

Pokud chcete přispívat do této knihovny, přečtěte si průvodce přispívání a přečtěte si další informace o vytváření a testování kódu.