Klientská knihovna Azure Tables pro JavaScript – verze 13.2.2

  • Článek

Azure Tables 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 součástmi cloudu Azure.

Klientská knihovna slouží k:

  • Vytváření a odstraňování tabulek
  • Dotazování, vytvoření, čtení, aktualizace nebo odstranění entit

Azure Cosmos DB poskytuje rozhraní TABLE API pro aplikace, které jsou napsané pro Azure Table Storage a které vyžadují prémiové funkce, jako jsou:

  • Globální distribuci na klíč
  • Vyhrazená propustnost po celém světě.
  • Latence v řádu milisekund na 99. percentilu.
  • Záruka vysoké dostupnosti.
  • Automatické sekundární indexování.
  • Klientská knihovna Azure Tables může beze změn kódu bezproblémově cílit buď na azure table storage, nebo na koncové body tabulkové služby Azure Cosmos DB.

Klíčové odkazy:

Začínáme

Požadavky

Aktuálně podporovaná prostředí:

  • LtS verze Node.js
  • Nejnovější verze prohlížečů 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 .

Nainstalujte balíček @azure/data-tables.

Upřednostňovaným způsobem, jak nainstalovat klientskou knihovnu Azure Tables pro JavaScript, je použít 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, budete muset vytvořit instanci klienta Tabulky – TableServiceClient nebo TableClient například. Další informace o ověřování najdete v TableServiceClientukázkách pro vytvoření.

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

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žívat v prohlížeči, musíte nejprve použít bundler. Podrobnosti o tom, jak to udělat, najdete v naší dokumentaci k sdružování.

CORS

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

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é zdroje: *
  • Povolené operace: DELETE,GET,HEAD,MERGE,POST,OPTIONS,PUT
  • Povolené hlavičky: *
  • Vystavené hlavičky: *
  • Maximální věk (sekundy): 86400

Klíčové koncepty

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

  • TableClient – Klient, který poskytuje funkce pro interakci na úrovni entity, jako je vytváření, výpis a odstraňová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 pár název, typ-hodnota, který se podobá sloupci.

Mezi běžná použití služby Table service patří:

  • Ukládání terabajtů strukturovaných dat, která můžou obsluhovat škálované webové aplikace
  • Ukládání datových sad, které nevyžadují složitá spojení, cizí klíče nebo uložené procedury a je možné je denormalizoval pro rychlý přístup.
  • Rychle dotazování na data pomocí clusterovaného indexu
  • Přístup k datům pomocí výrazů filtru protokolu OData

Příklady

Import balíčku

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

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

Případně můžete selektivně importovat jenom typy, které potřebujete:

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

Vytvoření klienta služby Table service

Vyžaduje TableServiceClient 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 AzureNamedKeyCredential

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

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)

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

Pro přístup k prostředku tabulky pomocí TokenCredentialnástroje by ověřená identita měla mít buď 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 ve vývojovém i produkčním prostředí. Další informace o integraci Azure AD ve službě Azure Storage najdete v souboru README pro Azure.Identity.

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 TableServiceClient instanci 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

Seznam tabulek v rámci účtu můžete zobrazit prostřednictvím TableServiceClient instance volající funkci listTables . Tato funkce vrátí hodnotu PageableAsyncIterator , kterou můžete použít 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();

Vytvoření nové tabulky

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

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 už tabulka při pokusu o vytvoření 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${new Date().getTime()}`;
  await serviceClient.createTable(tableName, {
    onResponse: (response) => {
      if (response.status === 409) {
        console.log(`Table ${tableName} already exists`);
      }
    }
  });
}

main();

Vytvoření klienta tabulky

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

TableClient S AzureNamedKeyCredential

Instanci můžete vytvořit TableClient tak, že AzureNamedKeyCredential jako argumenty předáte název účtu a klíč účtu. (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 pomocí TokenCredential (Azure Active Directory)

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

Pokud chcete získat přístup k prostředku tabulky pomocí TokenCredential, ověřená identita by měla mít roli Přispěvatel tabulkových dat služby Storage nebo Čtenář dat tabulek služby Storage.

@azure/identity Balíček umožňuje bezproblémovou autorizaci požadavků ve vývojovém i produkčním prostředí. Další informace o integraci Azure AD ve službě Azure Storage najdete v souboru README Azure.Identity.

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 TableClient instanci 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)

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

Pokud chcete získat přístup k prostředku tabulky pomocí TokenCredential, ověřená identita by měla mít roli Přispěvatel tabulkových dat služby Storage nebo Čtenář dat tabulek služby Storage.

@azure/identity Balíček umožňuje bezproblémovou autorizaci požadavků ve vývojovém i produkčním prostředí. Další informace o integraci Azure AD ve službě Azure Storage najdete v souboru README Azure.Identity.

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

Zobrazení seznamu entit v tabulce

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

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

Novou entitu v tabulce můžete vytvořit prostřednictvím instance, která TableClient volá createEntity funkci. Tato funkce přebírá entitu, která se má vložit 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 funguje také s emulátorem serveru kompatibilním s Azurite, což je kompatibilní serverový emulátor azure storage a rozhraní Table API. Informace o tom, jak ho začít používat, najdete v úložišti Azurite.

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

Nejjednodušším způsobem, jak se připojit k Azurite z vaší aplikace, je nakonfigurovat připojovací řetězec, který odkazuje na zástupce UseDevelopmentStorage=true. Zástupce je ekvivalentem úplného připojovacího řetězce pro emulátor, který určuje název účtu, klíč účtu a koncové body emulátoru pro každou službu Azure Storage: (viz další informace). Pomocí této zkratky nastaví klientská sada SDK služby Azure Tables 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 nebo AzureNamedKeyCredential vlastního připojovacího řetězce. Pokud ale Azurite běží v koncovém http bodu, allowInsecureConnection bude ho potřeba 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í potíží

Obecné

Při interakci se službou Table pomocí sady JavaScript/TypeScript SDK chyby vrácené službou odpovídají stejným stavovým kódům HTTP vráceným pro požadavky rozhraní 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 selháních. Pokud chcete zobrazit protokol požadavků a odpovědí HTTP, nastavte proměnnou AZURE_LOG_LEVEL prostředí na info. Případně je možné 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ívání

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á stanoví, že máte právo udělit nám práva k používání vašeho příspěvku a skutečně tak činíte. Podrobnosti najdete tady: https://cla.microsoft.com

Při odesílání žádosti o přijetí změn robot CLA automaticky určí, jestli je potřeba poskytnout smlouvu CLA, a příslušným způsobem žádost o přijetí změn upraví (např. přidáním jmenovky nebo komentáře). Stačí postupovat podle pokynů robota. Pro všechna úložiště používající naši smlouvu CLA to stačí udělat jenom jednou.

Tento projekt přijal pravidla chování pro Microsoft Open Source. Další informace najdete v nejčastějších dotazech k pravidlům chování nebo kontaktujte s opencode@microsoft.com případnými dalšími dotazy nebo připomínkami.

Pokud chcete přispívat do této knihovny, přečtěte si příručku pro přispívání , kde najdete další informace o tom, jak sestavit a otestovat kód.

Imprese