Azure Tables-clientbibliotheek voor JavaScript - versie 13.3.0

Azure Tables is een cloudservice waarin gestructureerde NoSQL-gegevens worden opgeslagen en een sleutel-/kenmerkarchief wordt geboden met een schemaloos ontwerp. Tabellenopslag biedt ontwikkelaars flexibiliteit en schaalbaarheid met alle beste onderdelen van de Azure-cloud.

Gebruik de clientbibliotheek voor het volgende:

• Tabellen maken/verwijderen
• Entiteiten opvragen/maken/lezen/bijwerken/verwijderen

Azure Cosmos DB biedt een Table-API voor toepassingen die zijn geschreven voor Azure Table Storage en die premium-mogelijkheden nodig hebben, zoals:

• Kant-en-klare wereldwijde distributie.
• Toegewezen doorvoer wereldwijd.
• Latenties van één milliseconden op het 99e percentiel.
• Gegarandeerde hoge beschikbaarheid.
• Automatische secundaire indexering.
• De Azure Tables-clientbibliotheek kan naadloos worden gericht op Azure Table Storage of Azure Cosmos DB Table Service-eindpunten zonder codewijzigingen.

Sleutelkoppelingen:

• broncode
• Package (NPM)
• API-referentiedocumentatie
• productdocumentatie
• voorbeelden

Slag

Voorwaarden

Momenteel ondersteunde omgevingen:

• LTS-versies van Node.js
• Nieuwste versies van Safari, Chrome, Edge en Firefox

U moet een Azure-abonnement hebben en een opslagaccount of een Azure CosmosDB-database om dit pakket te kunnen gebruiken.

Het @azure/data-tables-pakket installeren

De voorkeursmethode voor het installeren van de Azure Tables-clientbibliotheek voor JavaScript is het gebruik van npm-pakketbeheer. Typ het volgende in een terminalvenster:

npm install @azure/data-tables

Een TableServiceClient verifiëren

Azure Tables ondersteunt verschillende manieren om te verifiëren. Als u wilt communiceren met de Azure Tables-service, moet u bijvoorbeeld een exemplaar van een Tables-client maken: TableServiceClient of TableClient. Zie voorbeelden voor het maken van de TableServiceClient voor meer informatie over verificatie.

Opmerking: Azure Active Directory (AAD) wordt alleen ondersteund voor Azure Storage-accounts.

• -serviceclient met gedeelde sleutel
• Service-client met Shared Access Signatures
• Service-client met TokenCredential (AAD)
• Tabelclient met gedeelde sleutel
• Table-client met Shared Access Signatures
• Table-client met AAD- (TokenCredential)

De volgende functies, interfaces, klassen of functies zijn alleen beschikbaar in Node.js

• Autorisatie van gedeelde sleutels op basis van accountnaam en accountsleutel
  • AzureNamedKeyCredential
  • Verbindingsreeks voor account.

JavaScript-bundel

Als u deze clientbibliotheek in de browser wilt gebruiken, moet u eerst een bundelaar gebruiken. Raadpleeg onze bundeldocumentatievoor meer informatie over hoe u dit doet.

CORS

U moet CORS-regels (Cross-Origin Resource Sharing) instellen regels voor uw opslagaccount als u voor browsers moet ontwikkelen. Ga naar Azure Portal en Azure Storage Explorer, zoek uw opslagaccount, maak nieuwe CORS-regels voor blob/queue/file/table-service(s).

U kunt bijvoorbeeld de volgende CORS-instellingen maken voor foutopsporing. Maar pas de instellingen zorgvuldig aan op basis van uw vereisten in de productieomgeving.

• Toegestane oorsprongen: *
• Toegestane werkwoorden: DELETE,GET,HEAD,MERGE,POST,OPTIONS,PUT
• Toegestane headers: *
• Weergegeven headers: *
• Maximale leeftijd (seconden): 86400

Sleutelbegrippen

• TableServiceClient - Client die functies biedt om te communiceren op tabelserviceniveau, zoals tabellen maken, weergeven en verwijderen

• TableClient - Client die functies biedt voor interactie op entiteitsniveau, zoals het maken, weergeven en verwijderen van entiteiten in een tabel.

• Table : tabellen slaan gegevens op als verzamelingen entiteiten.

• Entity - Entiteiten zijn vergelijkbaar met rijen. Een entiteit heeft een primaire sleutel en een set eigenschappen. Een eigenschap is een naam, typed-waardepaar, vergelijkbaar met een kolom.

Veelvoorkomende toepassingen van de Table-service zijn:

• Het opslaan van TB's van gestructureerde gegevens die geschikt zijn voor webschaaltoepassingen
• Het opslaan van gegevenssets waarvoor geen complexe joins, refererende sleutels of opgeslagen procedures zijn vereist en die kunnen worden gedenormaliseerd voor snelle toegang
• Snel query's uitvoeren op gegevens met behulp van een geclusterde index
• Toegang tot gegevens met behulp van de OData-protocolfilterexpressies

Voorbeelden

• het pakket importeren
• De tabelserviceclient maken
  • Lijsttabellen in het account
  • Een nieuwe tabel maken
• De tabelclient maken
  • Lijstentiteiten in een tabel
  • Een nieuwe entiteit maken en toevoegen aan een tabel

Het pakket importeren

Als u de clients wilt gebruiken, importeert u het pakket in uw bestand:

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

U kunt ook selectief alleen de typen importeren die u nodig hebt:

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

De Table-serviceclient maken

De TableServiceClient vereist een URL naar de tabelservice en een toegangsreferentie. Het accepteert desgewenst ook bepaalde instellingen in de parameter options.

TableServiceClient met AzureNamedKeyCredential

U kunt een TableServiceClient instantiëren met een AzureNamedKeyCredential door accountnaam en accountsleutel door te geven als argumenten. (De accountnaam en accountsleutel kunnen worden verkregen via de Azure-portal.) [ALLEEN BESCHIKBAAR IN 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 met TokenCredential (AAD)

Azure Tables biedt integratie met Azure Active Directory (Azure AD) voor verificatie op basis van identiteiten van aanvragen voor de Table-service bij het richten van een opslageindpunt. Met Azure AD kunt u op rollen gebaseerd toegangsbeheer (RBAC) gebruiken om toegang te verlenen tot uw Azure Table-resources aan gebruikers, groepen of toepassingen.

Als u toegang wilt krijgen tot een tabelresource met een TokenCredential, moet de geverifieerde identiteit de rol 'Inzender voor opslagtabelgegevens' of 'Opslagtabelgegevenslezer' hebben.

Met het @azure/identity-pakket kunt u aanvragen naadloos autoriseren in zowel ontwikkel- als productieomgevingen. Zie de Azure.Identity README- voor meer informatie over Azure AD-integratie in Azure Storage

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 met SAS-token

U kunt ook een TableServiceClient maken met shared access signatures (SAS). U kunt het SAS-token ophalen uit de 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)
);

Tabellen in het account weergeven

U kunt tabellen in een account weergeven via een TableServiceClient exemplaar dat de functie listTables aanroept. Met deze functie wordt een PageableAsyncIterator geretourneerd die u kunt gebruiken met behulp van 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();

Een nieuwe tabel maken

U kunt een tabel maken via een TableServiceClient exemplaar dat de functie createTable aanroept. Met deze functie wordt de naam van de tabel gebruikt om als parameter te maken. Houd er rekening mee dat createTable geen fout genereert wanneer de tabel al bestaat.

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

Hier volgt een voorbeeld dat laat zien hoe u kunt testen of de tabel al bestaat wanneer u deze probeert te maken:

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

De tabelclient maken

De TableClient wordt op een vergelijkbare manier gemaakt als de TableServiceClient met het verschil dat TableClient een tabelnaam als parameter gebruikt

TableClient met AzureNamedKeyCredential

U kunt een TableClient instantiëren met een AzureNamedKeyCredential door accountnaam en accountsleutel door te geven als argumenten. (De accountnaam en accountsleutel kunnen worden verkregen via de Azure-portal.) [ALLEEN BESCHIKBAAR IN 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 met TokenCredential (Azure Active Directory)

Azure Tables biedt integratie met Azure Active Directory (Azure AD) voor verificatie op basis van identiteiten van aanvragen voor de Table-service bij het richten van een opslageindpunt. Met Azure AD kunt u op rollen gebaseerd toegangsbeheer (RBAC) gebruiken om toegang te verlenen tot uw Azure Table-resources aan gebruikers, groepen of toepassingen.

Als u toegang wilt krijgen tot een tabelresource met een TokenCredential, moet de geverifieerde identiteit de rol 'Inzender voor opslagtabelgegevens' of 'Opslagtabelgegevenslezer' hebben.

Met het @azure/identity-pakket kunt u aanvragen naadloos autoriseren in zowel ontwikkel- als productieomgevingen. Zie de Azure.Identity README- voor meer informatie over Azure AD-integratie in Azure Storage

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 met SAS-token

U kunt een TableClient instantiëren met shared access signatures (SAS). U kunt het SAS-token ophalen uit de 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 met TokenCredential (AAD)

Azure Tables biedt integratie met Azure Active Directory (Azure AD) voor verificatie op basis van identiteiten van aanvragen voor de Table-service bij het richten van een opslageindpunt. Met Azure AD kunt u op rollen gebaseerd toegangsbeheer (RBAC) gebruiken om toegang te verlenen tot uw Azure Table-resources aan gebruikers, groepen of toepassingen.

Als u toegang wilt krijgen tot een tabelresource met een TokenCredential, moet de geverifieerde identiteit de rol 'Inzender voor opslagtabelgegevens' of 'Opslagtabelgegevenslezer' hebben.

Met het @azure/identity-pakket kunt u aanvragen naadloos autoriseren in zowel ontwikkel- als productieomgevingen. Zie de Azure.Identity README- voor meer informatie over Azure AD-integratie in Azure Storage

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

Entiteiten in een tabel vermelden

U kunt entiteiten in een tabel weergeven door een TableClient exemplaar dat de listEntities-functie aanroept. Met deze functie wordt een PageableAsyncIterator geretourneerd die u kunt gebruiken met behulp van 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();

Een nieuwe entiteit maken en toevoegen aan een tabel

U kunt een nieuwe entiteit in een tabel maken door een TableClient exemplaar dat de createEntity-functie aanroept. Met deze functie wordt de entiteit als parameter ingevoegd. De entiteit moet partitionKey en rowKeybevatten.

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 en Opslagemulator

De Client-SDK voor Azure Tables werkt ook met Azurite, een met Azure Storage en Tables API compatibele serveremulator. Raadpleeg de (Azure-opslagplaats) over het gebruik ervan.

Verbinding maken met Azurite met snelkoppeling verbindingsreeks

De eenvoudigste manier om vanuit uw toepassing verbinding te maken met Azurite is door een verbindingsreeks te configureren die verwijst naar de snelkoppeling UseDevelopmentStorage=true. De snelkoppeling is gelijk aan de volledige verbindingsreeks voor de emulator, waarmee de accountnaam, de accountsleutel en de emulatoreindpunten voor elk van de Azure Storage-services worden opgegeven: (meer). Met deze snelkoppeling zou de Client-SDK van Azure Tables de standaardverbindingsreeks en allowInsecureConnection in de clientopties instellen.

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

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

Verbinding maken met Azurite zonder snelkoppeling verbindingsreeks

U kunt handmatig verbinding maken met azurite zonder de snelkoppeling naar de verbindingsreeks te gebruiken door de service-URL en AzureNamedKeyCredential of een aangepaste verbindingsreeks op te geven. Echter, allowInsecureConnection moet handmatig worden ingesteld voor het geval Azurite wordt uitgevoerd in een http eindpunt.

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

Probleemoplossing

Algemeen

Wanneer u communiceert met de Tables-service met behulp van de Javascript-/Typescript-SDK, komen fouten die door de service worden geretourneerd overeen met dezelfde HTTP-statuscodes die zijn geretourneerd voor REST API-aanvragen: Foutcodes voor Storage Table Service

Logboekregistratie

Het inschakelen van logboekregistratie kan helpen nuttige informatie over fouten te ontdekken. Als u een logboek met HTTP-aanvragen en -antwoorden wilt zien, stelt u de omgevingsvariabele AZURE_LOG_LEVEL in op info. U kunt logboekregistratie ook tijdens runtime inschakelen door setLogLevel aan te roepen in de @azure/logger:

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

setLogLevel("info");

Volgende stappen

Meer codevoorbeelden komen binnenkort voor probleem#10531

Bijdragen

Dit project verwelkomt bijdragen en suggesties. Voor de meeste bijdragen moet u akkoord gaan met een Licentieovereenkomst voor inzenders (CLA) waarin wordt aangegeven dat u het recht hebt om, en daadwerkelijk, ons de rechten te verlenen om uw bijdrage te gebruiken. Ga naar https://cla.microsoft.comvoor meer informatie.

Wanneer u een pull-aanvraag indient, bepaalt een CLA-bot automatisch of u een CLA moet opgeven en de pull-aanvraag op de juiste wijze moet inrichten (bijvoorbeeld label, opmerking). Volg gewoon de instructies van de bot. U hoeft dit slechts eenmaal te doen voor alle opslagplaatsen met behulp van onze CLA.

Dit project heeft de Microsoft Open Source-gedragscodeaangenomen. Zie de Veelgestelde vragen over gedragscodes voor meer informatie of neem contact op met opencode@microsoft.com met eventuele aanvullende vragen of opmerkingen.

Als u een bijdrage wilt leveren aan deze bibliotheek, leest u de gids voor bijdragen voor meer informatie over het bouwen en testen van de code.