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
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 tabelleTableClient
: 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
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.
Azure SDK for JavaScript