Sdílet prostřednictvím

Jak používat Azure Table Storage nebo Azure Cosmos DB pro tabulku z Node.js

  • Článek

PLATÍ PRO: Stůl

Tip

Obsah v tomto článku se týká služby Azure Table Storage a Azure Cosmos DB for Table. Rozhraní API pro tabulku je prémiová nabídka pro úložiště tabulek, která nabízí tabulky optimalizované pro propustnost, globální distribuci a automatické sekundární indexy.

V tomto článku se dozvíte, jak vytvářet tabulky, ukládat data a provádět operace CRUD na uvedených datech. Ukázky jsou napsané v Node.js.

Vytvoření účtu služby Azure

S tabulkami můžete pracovat pomocí služby Azure Table Storage nebo Azure Cosmos DB. Další informace o rozdílech mezi nabídkami tabulek v těchto dvou službách najdete v přehledu rozhraní API pro tabulky. U služby, kterou budete používat, si budete muset vytvořit účet. Následující části ukazují, jak vytvořit úložiště Azure Table Storage i účet služby Azure Cosmos DB, ale můžete použít jenom jednu z nich.

Vytvoření účtu úložiště Azure

Nejjednodušší způsob, jak vytvořit účet úložiště Azure, je použití webu Azure Portal. Další informace naleznete v tématu Vytvoření účtu úložiště

Účet úložiště Azure můžete vytvořit také pomocí Azure PowerShellu nebo Azure CLI.

Pokud v tuto chvíli nechcete vytvořit účet úložiště, můžete také pomocí emulátoru úložiště Azure spustit a otestovat kód v místním prostředí. Další informace najdete v tématu Použití emulátoru úložiště Azure pro vývoj a testování.

Vytvoření účtu služby Azure Cosmos DB for Table

Pokyny k vytvoření účtu tabulky služby Azure Cosmos DB najdete v tématu Vytvoření databázového účtu.

Konfigurace aplikace pro přístup ke službě Table Storage

Pokud chcete používat Službu Azure Storage nebo Azure Cosmos DB, potřebujete sadu Azure Tables SDK pro Node.js, která obsahuje sadu praktických knihoven, které komunikují se službami REST služby Storage.

Instalace balíčku pomocí Node Package Manageru (NPM)

  1. Použijte rozhraní příkazového řádku, jako je PowerShell (Windows), Terminál (Mac) nebo Bash (Unix), a přejděte do složky, ve které jste vytvořili svou aplikaci.
  2. Do příkazového okna zadejte následující:
   npm install @azure/data-tables
  1. Můžete ručně spustit příkaz ls a ověřit, že se vytvořila složka node_modules. Uvnitř této složky najdete balíček @azure/tabulky dat , který obsahuje knihovny, které potřebujete pro přístup k tabulkám.

Import balíčku

Na začátek souboru server.js ve vaší aplikaci přidejte následující kód:

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

Připojení ke službě Azure Table Storage

Můžete se buď připojit k účtu úložiště Azure, nebo k účtu služby Azure Cosmos DB for Table. Získejte sdílený klíč nebo připojovací řetězec na základě typu účtu, který používáte.

Vytvoření klienta služby Table Service ze sdíleného klíče

Modul Azure čte proměnné prostředí AZURE_ACCOUNT a AZURE_ACCESS_KEY a AZURE_TABLES_ENDPOINT, kde najdete informace potřebné pro připojení k účtu služby Azure Storage nebo ke službě Azure Cosmos DB. Pokud tyto proměnné prostředí nejsou nastaveny, je nutné při volání TableServiceClientzadat informace o účtu . Například následující kód vytvoří TableServiceClient objekt:

const endpoint = "<table-endpoint-uri>";
const credential = new AzureNamedKeyCredential(
  "<account-name>",
  "<account-key>"
);

const tableService = new TableServiceClient(
  endpoint,
  credential
);

Vytvoření klienta služby Table Service z připojovací řetězec

Pokud chcete přidat připojení účtu služby Azure Cosmos DB nebo úložiště, vytvořte TableServiceClient objekt a zadejte název účtu, primární klíč a koncový bod. Tyto hodnoty můžete zkopírovat z připojovacího řetězce nastavení>na webu Azure Portal pro účet služby Azure Cosmos DB nebo účet úložiště. Příklad:

const tableService = TableServiceClient.fromConnectionString("<connection-string>");

Vytvoření tabulky

Volání pro createTable vytvoření nové tabulky se zadaným názvem, pokud ještě neexistuje. Následující příklad vytvoří novou tabulku mytable, pokud ještě neexistuje:

await tableService.createTable('<table-name>');

Vytvoření klienta tabulky

Pokud chcete pracovat s tabulkou, měli byste vytvořit TableClient objekt pomocí stejných přihlašovacích údajů, které jste použili TableServiceClientk vytvoření . Vyžaduje TableClient také název cílové tabulky.

const tableClient = new TableClient(
  endpoint,
  '<table-name>',
  credential
);

Přidání entity do tabulky

Pokud chcete přidat entitu, nejprve vytvořte objekt definující vlastnosti entity. Všechny entity musí obsahovat partitionKey a rowKey, což jsou jedinečné identifikátory entity.

  • partitionKey – určuje oddíl, ve kterém je entita uložená.
  • rowKey – jedinečně identifikuje entitu v rámci oddílu.

PartitionKey i rowKey musí být řetězcové hodnoty.

Následuje příklad definice entity. DueDate je definován jako typ Date. Zadání typu je volitelné. Pokud typ není zadaný, odvodí se.

const task = {
  partitionKey: "hometasks",
  rowKey: "1",
  description: "take out the trash",
  dueDate: new Date(2015, 6, 20)
};

Poznámka:

Pro každý záznam je také Timestamp pole, které azure nastaví při vložení nebo aktualizaci entity.

Pokud chcete do tabulky přidat entitu, předejte objekt entity metodě createEntity .

let result = await tableClient.createEntity(task);
    // Entity create

Pokud je operace úspěšná, result obsahuje značku ETag a informace o operaci.

Příklad odpovědi:

{ 
  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'
}

Aktualizace entity

Různé režimy a updateEntityupsertEntity metody

  • Sloučení: Aktualizuje entitu aktualizací vlastností entity bez nahrazení existující entity.
  • Nahradit: Aktualizuje existující entitu nahrazením celé entity.

Následující příklad ukazuje aktualizaci entity pomocí upsertEntity:

// Entity doesn't exist in table, so calling upsertEntity will simply insert the entity.
let result = await tableClient.upsertEntity(task, "Replace");

Pokud entita, která se aktualizuje, neexistuje, operace aktualizace selže. proto pokud chcete uložit entitu bez ohledu na to, zda již existuje, použijte upsertEntity.

result pro úspěšné operace aktualizace obsahuje značku entity aktualizované entity.

Práce se skupinami entit

Někdy má smysl odeslat více operací společně v dávce, aby se zajistilo jejich atomické zpracování serverem. Chcete-li toho dosáhnout, vytvořte pole operací a předejte ji submitTransaction metodě on TableClient.

Následující příklad ukazuje odeslání dvou entit v dávce:

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

V případě úspěšných dávkových operací obsahuje result informace o jednotlivých operacích v dávce.

Načtení entity podle klíče

Pokud chcete vrátit konkrétní entitu založenou na PartitionKey a RowKey, použijte metodu getEntity .

let result = await tableClient.getEntity("hometasks", "1")
  .catch((error) => {
    // handle any errors
  });
  // result contains the entity

Po dokončení operace bude result obsahovat příslušnou entitu.

Dotaz na sadu entit

Následující příklad vytvoří dotaz, který vrátí prvních pět položek s PartitionKey "hometasks" a zobrazí seznam všech entit v tabulce.

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

Dotaz na podmnožinu vlastností entity

Dotaz na tabulku dokáže z entity načíst pouze několik polí. Díky tomu se snižuje šířka pásma a může se zlepšit výkon dotazů, zejména u velkých entit. Použijte klauzuli select a předejte názvy polí, které se mají vrátit. Například následující dotaz vrátí pouze pole description a dueDate.

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

Odstranění entity

Entitu můžete odstranit pomocí jejího klíče oddílu a řádku. V tomto příkladu obsahuje objekt task1 hodnoty rowKey a partitionKey entity k odstranění. Objekt se pak předá do metody deleteEntity.

const tableClient = new TableClient(
  tablesEndpoint,
  tableName,
  new AzureNamedKeyCredential("<accountName>", "<accountKey>")
);

await tableClient.deleteEntity("hometasks", "1");
    // Entity deleted

Poznámka:

Při odstraňování položek zvažte použití značek entit, abyste zajistili, že položku neupravil jiný proces. Informace o použití značek entit najdete v části Aktualizace entity.

Odstraní tabulku

Následující kód odstraní tabulku z účtu úložiště.

await tableClient.deleteTable(mytable);
        // Table deleted

Použití tokenů pro pokračování

Pokud z tabulek dotazujete velké množství výsledků, hledejte tokeny pro pokračování. Pro váš dotaz může být k dispozici velké množství dat, kterých si nemusíte všimnout, pokud v rámci sestavování nezajistíte rozpoznání, jestli je přítomný token pro pokračování.

Pokud je takový token přítomný, v objektu results vraceném během dotazování entit se nastaví vlastnost continuationToken. Tuto vlastnost pak můžete při provádění dotazu použít k pohybu mezi oddíly a entitami tabulky.

Při dotazování můžete zadat parametr continuationToken mezi instanci objektu dotazu a funkci zpětného volání:

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

Práce se sdílenými přístupovými podpisy

Sdílené přístupové podpisy (SAS) představují bezpečný způsob zajištění podrobného přístupu k tabulkám bez nutnosti zadávat název nebo klíče vašeho účtu služby Storage. SAS se často používá k zajištění omezeného přístupu k datům, jako je například povolení dotazování záznamů pro mobilní aplikaci.

Důvěryhodná aplikace, jako je cloudová služba, generuje SAS pomocí generateTableSastableClient a poskytuje ji nedůvěryhodné nebo částečně důvěryhodné aplikaci, jako je mobilní aplikace. SAS se generuje pomocí zásady, která popisuje počáteční a koncové datum platnosti SAS a také úroveň přístupu udělenou držiteli SAS.

Následující příklad vygeneruje novou zásadu sdíleného přístupu, která umožní držiteli SAS dotazovat ('r') tabulku.

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

Klientská aplikace pak použije SAS s AzureSASCredential k provádění operací s tabulkou. Následující příklad se připojí k tabulce a provede dotaz. Informace o formátu tableSAS najdete v článku Udělení omezeného přístupu k prostředkům Azure Storage pomocí sdílených přístupových podpisů (SAS ).

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

Vzhledem k tomu, že se SAS vygeneroval pouze s přístupem k dotazům, při pokusu o vložení, aktualizaci nebo odstranění entit se vrátí chyba.

Seznamy řízení přístupu

K nastavení zásad přístupu pro SAS můžete použít také seznam řízení přístupu (ACL). To je užitečné, pokud chcete umožnit přístup k tabulce několika klientům, ale pro každého klienta chcete zajistit jiné zásady přístupu.

Seznam ACL se implementuje pomocí pole zásad přístupu, z nichž každá zásada má přidružené ID. Následující příklad definuje dvě zásady, jednu pro uživatele user1 a druhou pro uživatele user2:

var sharedAccessPolicy = [{
  id:"user1",
  accessPolicy:{
    permission: "r" ,
    Start: startsOn,
    Expiry: expiresOn,
  }},
  {
  id:"user2",
  accessPolicy:{
    permissions: "a",
    Start: startsOn,
    Expiry: expiresOn,
  }},
]

Následující příklad získá aktuální seznam ACL pro tabulku hometasks a pak přidá nové zásady pomocí setAccessPolicy. Tento přístup umožňuje:

tableClient.getAccessPolicy();
tableClient.setAccessPolicy(sharedAccessPolicy);

Po nastavení seznamu ACL pak můžete pro zásadu vytvořit SAS založený na ID. Následující příklad vytvoří nový SAS pro uživatele user2:

tableSAS = generateTableSas("hometasks",cred,{identifier:'user2'});

Další kroky

Další informace najdete v následujících materiálech.