Azure Tables-klientbibliotek för JavaScript – version 13.3.0

Azure Tables är en molnbaserad tjänst som lagrar strukturerade NoSQL-data, vilket ger ett nyckel-/attributarkiv med en schemalös design. Lagring av tabeller ger utvecklare flexibilitet och skalbarhet med alla de bästa delarna i Azure-molnet.

Använd klientbiblioteket för att:

• Skapa/ta bort tabeller
• Fråga/skapa/läsa/uppdatera/ta bort entiteter

Azure Cosmos DB tillhandahåller ett tabell-API för program som är skrivna för Azure Table Storage och som behöver premiumfunktioner som:

• Nyckelfärdig global distribution.
• Dedikerat dataflöde över hela världen.
• Svarstider med ensiffrig millisekunder i den 99:e percentilen.
• Garanterad hög tillgänglighet.
• Automatisk sekundär indexering.
• Azure Tables-klientbiblioteket kan sömlöst rikta in sig på azure-tabelllagring eller Azure Cosmos DB-tabelltjänstslutpunkter utan kodändringar.

Nyckellänkar:

• Källkod
• Package (NPM)
• API-referensdokumentation
• Produktdokumentation
• exempel

Komma igång

Förutsättningar

Miljöer som stöds för närvarande:

• LTS-versioner av Node.js
• De senaste versionerna av Safari, Chrome, Edge och Firefox

Du måste ha en Azure-prenumeration och ett Storage-konto eller en Azure CosmosDB-databas för att kunna använda det här paketet.

Installera @azure/data-tables-paketet

Det bästa sättet att installera Azure Tables-klientbiblioteket för JavaScript är att använda npm-pakethanteraren. Skriv följande i ett terminalfönster:

npm install @azure/data-tables

Autentisera en TableServiceClient

Azure Tables stöder flera sätt att autentisera. För att kunna interagera med Azure Tables-tjänsten måste du skapa en instans av en Tables-klient – TableServiceClient eller TableClient till exempel. Mer information om autentisering finns i exempel för att skapa TableServiceClient.

Obs! Azure Active Directory (AAD) stöds endast för Azure Storage-konton.

• -tjänstklient med delad nyckel
• Service-klient med signaturer för delad åtkomst
• Service-klienten med TokenCredential (AAD)
• tabellklient med delad nyckel
• tabellklient med signaturer för delad åtkomst
• tabellklient med TokenCredential (AAD)

Följande funktioner, gränssnitt, klasser eller funktioner är endast tillgängliga i Node.js

• Auktorisering av delad nyckel baserat på kontonamn och kontonyckel
  • AzureNamedKeyCredential
  • Kontoanslutningssträng.

JavaScript-paket

Om du vill använda det här klientbiblioteket i webbläsaren måste du först använda en bundler. Mer information om hur du gör detta finns i vår paketeringsdokumentation.

CORS

Du måste konfigurera CORS (Cross-Origin Resource Sharing) regler för ditt lagringskonto om du behöver utveckla för webbläsare. Gå till Azure-portalen och Azure Storage Explorer, leta reda på ditt lagringskonto, skapa nya CORS-regler för blob/kö/fil/tabelltjänster.

Du kan till exempel skapa följande CORS-inställningar för felsökning. Men anpassa inställningarna noggrant enligt dina krav i produktionsmiljön.

• Tillåtet ursprung: *
• Tillåtna verb: DELETE,GET,HEAD,MERGE,POST,OPTIONS,PUT
• Tillåtna rubriker: *
• Synliga rubriker: *
• Maximal ålder (sekunder): 86400

Viktiga begrepp

• TableServiceClient – Klient som tillhandahåller funktioner för att interagera på tabelltjänstnivå, till exempel skapa, lista och ta bort tabeller

• TableClient – Klient som tillhandahåller funktioner för att interagera på en entitetsnivå, till exempel skapa, lista och ta bort entiteter i en tabell.

• Table – Tabeller lagrar data som samlingar av entiteter.

• Entity – Entiteter liknar rader. En entitet har en primärnyckel och en uppsättning egenskaper. En egenskap är ett namn, typat värdepar, som liknar en kolumn.

Vanliga användningsområden för tabelltjänsten är:

• Lagra TB för strukturerade data som kan hantera webbskalningsprogram
• Lagra datauppsättningar som inte kräver komplexa kopplingar, sekundärnycklar eller lagrade procedurer och kan avnormaliseras för snabb åtkomst
• Köra snabba frågor mot data med hjälp av ett klustrade index
• Komma åt data med hjälp av OData-protokollfilteruttryck

Exempel

• Importera paketet
• Skapa tabelltjänstklienten
  • Lista tabeller i kontot
  • Skapa en ny tabell
• Skapa tabellklienten
  • lista entiteter i en tabell
  • Skapa en ny entitet och lägg till den i en tabell

Importera paketet

Om du vill använda klienterna importerar du paketet i filen:

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

Alternativt kan du selektivt importera endast de typer som du behöver:

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

Skapa Table Service-klienten

TableServiceClient kräver en URL till tabelltjänsten och en åtkomstautentiseringsuppgift. Du kan också välja att acceptera vissa inställningar i parametern options.

TableServiceClient med AzureNamedKeyCredential

Du kan instansiera en TableServiceClient med en AzureNamedKeyCredential genom att skicka kontonamn och kontonyckel som argument. (Kontonamnet och kontonyckeln kan hämtas från Azure-portalen.) [ENDAST TILLGÄNGLIGT I 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 med TokenCredential (AAD)

Azure Tables tillhandahåller integrering med Azure Active Directory (Azure AD) för identitetsbaserad autentisering av begäranden till table-tjänsten när du riktar in dig på en lagringsslutpunkt. Med Azure AD kan du använda rollbaserad åtkomstkontroll (RBAC) för att ge åtkomst till dina Azure Table-resurser till användare, grupper eller program.

För att få åtkomst till en tabellresurs med en TokenCredentialska den autentiserade identiteten ha rollen "Storage Table Data Contributor" eller "Storage Table Data Reader".

Med @azure/identity-paketet kan du smidigt auktorisera begäranden i både utvecklings- och produktionsmiljöer. Mer information om Azure AD-integrering i Azure Storage finns i 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 med SAS-token

Du kan också instansiera en TableServiceClient med en signatur för delad åtkomst (SAS). Du kan hämta SAS-token från Azure-portalen.

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

Lista tabeller i kontot

Du kan lista tabeller i ett konto via en TableServiceClient instans som anropar funktionen listTables. Den här funktionen returnerar en PageableAsyncIterator som du kan använda med hjälp av 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();

Skapa en ny tabell

Du kan skapa en tabell via en TableServiceClient instans som anropar funktionen createTable. Den här funktionen tar namnet på tabellen för att skapa som en parameter. Observera att createTable inte utlöser något fel när tabellen redan finns.

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

Här är ett exempel som visar hur du testar om tabellen redan finns när du försöker skapa den:

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

Skapa tabellklienten

TableClient skapas på ett liknande sätt som TableServiceClient med skillnaden att TableClient tar ett tabellnamn som en parameter

TableClient med AzureNamedKeyCredential

Du kan instansiera en TableClient med en AzureNamedKeyCredential genom att skicka kontonamn och kontonyckel som argument. (Kontonamnet och kontonyckeln kan hämtas från Azure-portalen.) [ENDAST TILLGÄNGLIGT I 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 med TokenCredential (Azure Active Directory)

Azure Tables tillhandahåller integrering med Azure Active Directory (Azure AD) för identitetsbaserad autentisering av begäranden till table-tjänsten när du riktar in dig på en lagringsslutpunkt. Med Azure AD kan du använda rollbaserad åtkomstkontroll (RBAC) för att ge åtkomst till dina Azure Table-resurser till användare, grupper eller program.

För att få åtkomst till en tabellresurs med en TokenCredentialska den autentiserade identiteten ha rollen "Storage Table Data Contributor" eller "Storage Table Data Reader".

Med @azure/identity-paketet kan du smidigt auktorisera begäranden i både utvecklings- och produktionsmiljöer. Mer information om Azure AD-integrering i Azure Storage finns i 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 med SAS-token

Du kan instansiera en TableClient med en signatur för delad åtkomst (SAS). Du kan hämta SAS-token från Azure-portalen.

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 med TokenCredential (AAD)

Azure Tables tillhandahåller integrering med Azure Active Directory (Azure AD) för identitetsbaserad autentisering av begäranden till table-tjänsten när du riktar in dig på en lagringsslutpunkt. Med Azure AD kan du använda rollbaserad åtkomstkontroll (RBAC) för att ge åtkomst till dina Azure Table-resurser till användare, grupper eller program.

För att få åtkomst till en tabellresurs med en TokenCredentialska den autentiserade identiteten ha rollen "Storage Table Data Contributor" eller "Storage Table Data Reader".

Med @azure/identity-paketet kan du smidigt auktorisera begäranden i både utvecklings- och produktionsmiljöer. Mer information om Azure AD-integrering i Azure Storage finns i 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
);

Lista entiteter i en tabell

Du kan visa entiteter i en tabell via en TableClient instans som anropar funktionen listEntities. Den här funktionen returnerar en PageableAsyncIterator som du kan använda med hjälp av 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();

Skapa en ny entitet och lägg till den i en tabell

Du kan skapa en ny entitet i en tabell via en TableClient instans som anropar funktionen createEntity. Den här funktionen tar entiteten att infoga som en parameter. Entiteten måste innehålla partitionKey och 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 och Storage Emulator

Azure Tables Client SDK fungerar också med Azurite, en Azure Storage- och Tables API-kompatibel serveremulator. Se lagringsplatsen (Azurite) om hur du kommer igång med den.

Ansluta till Azurite med genväg till anslutningssträng

Det enklaste sättet att ansluta till Azurite från ditt program är att konfigurera en anslutningssträng som refererar till genvägen UseDevelopmentStorage=true. Genvägen motsvarar den fullständiga anslutningssträngen för emulatorn, som anger kontonamnet, kontonyckeln och emulatorns slutpunkter för var och en av Azure Storage-tjänsterna: (se mer). Med den här genvägen konfigurerar Azure Tables Client SDK standardanslutningssträngen och allowInsecureConnection i klientalternativen.

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

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

Ansluta till Azurite utan genväg till anslutningssträng

Du kan ansluta till azurite manuellt utan att använda genvägen till anslutningssträngen genom att ange tjänstens URL och AzureNamedKeyCredential eller en anpassad anslutningssträng. Men allowInsecureConnection måste anges manuellt om Azurite körs i en http slutpunkt.

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

Felsökning

Allmänt

När du interagerar med tables-tjänsten med Javascript/Typescript SDK motsvarar fel som returneras av tjänsten samma HTTP-statuskoder som returneras för REST API-begäranden: Felkoder för Storage Table Service

Skogsavverkning

Aktivering av loggning kan hjälpa dig att hitta användbar information om fel. Om du vill se en logg med HTTP-begäranden och svar anger du AZURE_LOG_LEVEL miljövariabeln till info. Du kan också aktivera loggning vid körning genom att anropa setLogLevel i @azure/logger:

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

setLogLevel("info");

Nästa steg

Fler kodexempel kommer snart Problem#10531

Bidragande

Det här projektet välkomnar bidrag och förslag. De flesta bidrag kräver att du godkänner ett licensavtal för deltagare (CLA) som förklarar att du har rätt att, och faktiskt gör det, ge oss rätten att använda ditt bidrag. Mer information finns i https://cla.microsoft.com.

När du skickar en pull-begäran avgör en CLA-robot automatiskt om du behöver tillhandahålla ett CLA och dekorera PR på rätt sätt (t.ex. etikett, kommentar). Följ bara anvisningarna från roboten. Du behöver bara göra detta en gång för alla lagringsplatser med vår CLA.

Det här projektet har antagit Microsoft Open Source Code of Conduct. Mer information finns i vanliga frågor och svar om uppförandekod eller kontakta opencode@microsoft.com med ytterligare frågor eller kommentarer.

Om du vill bidra till det här biblioteket kan du läsa bidragsguide för att lära dig mer om hur du skapar och testar koden.