Libreria client tabelle di Azure per JavaScript - versione 13.3.0

tabelle di Azure è un servizio basato sul cloud che archivia dati NoSQL strutturati, fornendo un archivio chiavi/attributi con una progettazione senza schema. L'archiviazione tabelle offre agli sviluppatori flessibilità e scalabilità con tutte le parti migliori del cloud di Azure.

Usare la libreria client per:

• Creare/eliminare tabelle
• Query/Creazione/Lettura/Aggiornamento/Eliminazione di entità

Azure Cosmos DB offre un'API Tabella per le applicazioni scritte per l'archiviazione tabelle di Azure e che richiedono funzionalità Premium come:

• Distribuzione globale chiavi in mano.
• Velocità effettiva dedicata in tutto il mondo.
• Latenze di millisecondi a cifra singola al 99° percentile.
• Disponibilità elevata garantita.
• Indicizzazione secondaria automatica.
• La libreria client tabelle di Azure può essere facilmente destinati all'archiviazione tabelle di Azure o agli endpoint del servizio tabelle di Azure Cosmos DB senza modifiche al codice.

Collegamenti chiave:

• codice sorgente
• del pacchetto
• documentazione di riferimento dell'API
• documentazione del prodotto
• esempi di

Introduttiva

Prerequisiti

Ambienti attualmente supportati:

• Versioni LTS di Node.js
• Versioni più recenti di Safari, Chrome, Edge e Firefox

Per usare questo pacchetto, è necessario disporre di una sottoscrizione di Azure e di un account di archiviazione o di un di database di Azure CosmosDB.

Installare il pacchetto @azure/data-tables

Il modo migliore per installare la libreria client tabelle di Azure per JavaScript consiste nell'usare la gestione pacchetti npm. Digitare quanto segue in una finestra del terminale:

npm install @azure/data-tables

Autenticare un TableServiceClient

Tabelle di Azure supporta diversi modi per l'autenticazione. Per interagire con il servizio Tabelle di Azure, è necessario creare un'istanza di un client Tabelle, ad esempio TableServiceClient o TableClient. Per altre informazioni sull'autenticazione, vedere esempi per la creazione del TableServiceClient.

Nota: Azure Active Directory (AAD) è supportato solo per gli account di archiviazione di Azure.

• client del servizio con chiave condivisa
• client del servizio con firme di accesso condiviso
• client del servizio con TokenCredential (AAD)
• client tabella con chiave condivisa
• client di tabella con firme di accesso condiviso
• client di tabella con TokenCredential (AAD)

Le funzionalità, le interfacce, le classi o le funzioni seguenti sono disponibili solo in Node.js

• Autorizzazione chiave condivisa basata sul nome dell'account e sulla chiave dell'account
  • AzureNamedKeyCredential
  • Stringa di connessione dell'account.

JavaScript Bundle

Per usare questa libreria client nel browser, è prima necessario usare un bundler. Per informazioni dettagliate su come eseguire questa operazione, vedere la documentazione di creazione di bundle .

CORS

È necessario configurare regole cors (Cross-Origin Resource Sharing) per l'account di archiviazione se è necessario sviluppare per i browser. Passare al portale di Azure e Azure Storage Explorer, trovare l'account di archiviazione, creare nuove regole CORS per i servizi BLOB/queue/file/table.

Ad esempio, è possibile creare le impostazioni CORS seguenti per il debug. Ma personalizzare attentamente le impostazioni in base ai requisiti nell'ambiente di produzione.

• Origini consentite: *
• Verbi consentiti: DELETE,GET,HEAD,MERGE,POST,OPTIONS,PUT
• Intestazioni consentite: *
• Intestazioni esposte: *
• Età massima (secondi): 86400

Concetti chiave

• TableServiceClient : client che fornisce funzioni per interagire a livello di servizio tabelle, ad esempio creare, elencare ed eliminare tabelle

• TableClient: client che fornisce funzioni per interagire a livello di entità, ad esempio creare, elencare ed eliminare entità all'interno di una tabella.

• Table : le tabelle archiviano i dati come raccolte di entità.

• Entity: le entità sono simili alle righe. Un'entità ha una chiave primaria e un set di proprietà. Una proprietà è un nome, una coppia di valori tipizzata, simile a una colonna.

Gli usi comuni del servizio tabelle includono:

• Archiviazione di TBS di dati strutturati in grado di gestire applicazioni su scala Web
• Archiviazione di set di dati che non richiedono join complessi, chiavi esterne o stored procedure e possono essere de normalizzati per l'accesso rapido
• Eseguire rapidamente query sui dati usando un indice cluster
• Accesso ai dati tramite le espressioni di filtro del protocollo OData

Esempi

• Importare il pacchetto
• Creare il client del servizio tabelle
  • elencare le tabelle nell'account
  • Creare una nuova tabella
• Creare il client di tabella
  • elencare le entità in una tabella
  • Creare una nuova entità e aggiungerla a una tabella

Importare il pacchetto

Per usare i client, importare il pacchetto nel file:

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

In alternativa, importare in modo selettivo solo i tipi necessari:

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

Creare il client del servizio tabelle

Il TableServiceClient richiede un URL per il servizio tabelle e una credenziale di accesso. Facoltativamente accetta anche alcune impostazioni nel parametro options.

TableServiceClient con AzureNamedKeyCredential

È possibile creare un'istanza di un TableServiceClient con un AzureNamedKeyCredential passando il nome dell'account e la chiave dell'account come argomenti. È possibile ottenere il nome dell'account e la chiave dell'account dal portale di Azure. [DISPONIBILE SOLO 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 con TokenCredential (AAD)

Tabelle di Azure offre l'integrazione con Azure Active Directory (Azure AD) per l'autenticazione basata su identità delle richieste al servizio tabelle quando è destinata a un endpoint di archiviazione. Con Azure AD, è possibile usare il controllo degli accessi in base al ruolo per concedere l'accesso alle risorse tabelle di Azure a utenti, gruppi o applicazioni.

Per accedere a una risorsa tabella con un TokenCredential, l'identità autenticata deve avere il ruolo "Collaboratore dati tabella di archiviazione" o "Lettore dati tabella di archiviazione".

Con il pacchetto @azure/identity, è possibile autorizzare facilmente le richieste in ambienti di sviluppo e produzione. Per altre informazioni sull'integrazione di Azure AD in Archiviazione di Azure, vedere 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 con token di firma di accesso condiviso

È anche possibile creare un'istanza di un TableServiceClient con firme di accesso condiviso. È possibile ottenere il token di firma di accesso condiviso dal portale di Azure.

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

Elencare le tabelle nell'account

È possibile elencare le tabelle all'interno di un account tramite un'istanza di TableServiceClient che chiama la funzione listTables. Questa funzione restituisce un PageableAsyncIterator che è possibile utilizzare usando 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();

Creare una nuova tabella

È possibile creare una tabella tramite un'istanza di TableServiceClient che chiama la funzione createTable. Questa funzione accetta il nome della tabella da creare come parametro. Si noti che createTable non genererà un errore quando la tabella esiste già.

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

Di seguito è riportato un esempio che illustra come verificare se la tabella esiste già durante il tentativo di crearla:

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

Creare il client di tabella

Il TableClient viene creato in modo analogo al TableServiceClient con la differenza che TableClient accetta un nome di tabella come parametro

TableClient con AzureNamedKeyCredential

È possibile creare un'istanza di un TableClient con un AzureNamedKeyCredential passando il nome dell'account e la chiave dell'account come argomenti. È possibile ottenere il nome dell'account e la chiave dell'account dal portale di Azure. [DISPONIBILE SOLO 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 con TokenCredential (Azure Active Directory)

Tabelle di Azure offre l'integrazione con Azure Active Directory (Azure AD) per l'autenticazione basata su identità delle richieste al servizio tabelle quando è destinata a un endpoint di archiviazione. Con Azure AD, è possibile usare il controllo degli accessi in base al ruolo per concedere l'accesso alle risorse tabelle di Azure a utenti, gruppi o applicazioni.

Per accedere a una risorsa tabella con un TokenCredential, l'identità autenticata deve avere il ruolo "Collaboratore dati tabella di archiviazione" o "Lettore dati tabella di archiviazione".

Con il pacchetto @azure/identity, è possibile autorizzare facilmente le richieste in ambienti di sviluppo e produzione. Per altre informazioni sull'integrazione di Azure AD in Archiviazione di Azure, vedere 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 con token di firma di accesso condiviso

È possibile creare un'istanza di un TableClient con firme di accesso condiviso.You can instantiate a TableClient with a shared access signatures (SAS). È possibile ottenere il token di firma di accesso condiviso dal portale di Azure.

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

Tabelle di Azure offre l'integrazione con Azure Active Directory (Azure AD) per l'autenticazione basata su identità delle richieste al servizio tabelle quando è destinata a un endpoint di archiviazione. Con Azure AD, è possibile usare il controllo degli accessi in base al ruolo per concedere l'accesso alle risorse tabelle di Azure a utenti, gruppi o applicazioni.

Per accedere a una risorsa tabella con un TokenCredential, l'identità autenticata deve avere il ruolo "Collaboratore dati tabella di archiviazione" o "Lettore dati tabella di archiviazione".

Con il pacchetto @azure/identity, è possibile autorizzare facilmente le richieste in ambienti di sviluppo e produzione. Per altre informazioni sull'integrazione di Azure AD in Archiviazione di Azure, vedere 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
);

Elencare le entità in una tabella

È possibile elencare le entità all'interno di una tabella tramite un'istanza di TableClient che chiama la funzione listEntities. Questa funzione restituisce un PageableAsyncIterator che è possibile utilizzare usando 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();

Creare una nuova entità e aggiungerla a una tabella

È possibile creare una nuova entità in una tabella tramite un'istanza di TableClient che chiama la funzione createEntity. Questa funzione accetta l'entità da inserire come parametro. L'entità deve contenere partitionKey e 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();

Emulatore di archiviazione e Azurite

Azure Tables Client SDK funziona anche con Azurite, un emulatore di server compatibile con l'API Archiviazione di Azure e tabelle. Fare riferimento al repository (Azurite) su come iniziare a usarlo.

Connessione a Azurite con collegamento stringa di connessione

Il modo più semplice per connettersi a Azurite dall'applicazione consiste nel configurare una stringa di connessione che fa riferimento al collegamento UseDevelopmentStorage=true. Il collegamento è equivalente alla stringa di connessione completa per l'emulatore, che specifica il nome dell'account, la chiave dell'account e gli endpoint dell'emulatore per ognuno dei servizi di archiviazione di Azure: (vedere altre). Usando questo collegamento, Azure Tables Client SDK configura la stringa di connessione predefinita e allowInsecureConnection nelle opzioni client.

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

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

Connessione a Azurite senza collegamento stringa di connessione

È possibile connettersi manualmente a azurite senza usare il collegamento alla stringa di connessione specificando l'URL del servizio e AzureNamedKeyCredential o una stringa di connessione personalizzata. Tuttavia, allowInsecureConnection dovrà essere impostato manualmente nel caso in cui La Costa Azzurra venga eseguita in un endpoint http.

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

Risoluzione dei problemi

Generale

Quando si interagisce con il servizio Tabelle usando Javascript/Typescript SDK, gli errori restituiti dal servizio corrispondono agli stessi codici di stato HTTP restituiti per le richieste dell'API REST: codici di errore del servizio tabelle di archiviazione

Registrazione

L'abilitazione della registrazione può aiutare a individuare informazioni utili sugli errori. Per visualizzare un log di richieste e risposte HTTP, impostare la variabile di ambiente AZURE_LOG_LEVEL su info. In alternativa, la registrazione può essere abilitata in fase di esecuzione chiamando setLogLevel nel @azure/logger:

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

setLogLevel("info");

Passaggi successivi

Altri esempi di codice saranno presto disponibili issue#10531

Contribuire

Questo progetto accoglie contributi e suggerimenti. La maggior parte dei contributi richiede l'accettazione di un Contratto di licenza collaboratore (CLA) che dichiara di avere il diritto e, in realtà, concedere a Microsoft i diritti per l'uso del contributo. Per informazioni dettagliate, visitare https://cla.microsoft.com.

Quando si invia una richiesta pull, un bot CLA determinerà automaticamente se è necessario fornire un cla e decorare la richiesta pull in modo appropriato (ad esempio, etichetta, commento). Seguire semplicemente le istruzioni fornite dal bot. Dovrai eseguire questa operazione una sola volta in tutti i repository usando la nostra cla.

Questo progetto ha adottato la codice di comportamento Microsoft Open Source. Per altre informazioni, vedere domande frequenti sul codice di comportamento o contattare opencode@microsoft.com con eventuali domande o commenti aggiuntivi.

Per contribuire a questa libreria, leggere la guida contribuire per altre informazioni su come compilare e testare il codice.