Bibliothèque cliente Tables Azure pour JavaScript - version 13.2.2

Article
04/10/2023

Azure Tables est un service cloud qui stocke des données NoSQL structurées, fournissant un magasin de clés/attributs avec une conception sans schéma. Le stockage tables offre aux développeurs flexibilité et scalabilité avec toutes les meilleures parties du cloud Azure.

Utilisez la bibliothèque cliente pour :

Créer/supprimer des tables
Interroger/créer/lire/mettre à jour/supprimer des entités

Azure Cosmos DB fournit une API Table pour les applications écrites pour le stockage Table Azure et qui nécessitent des fonctionnalités Premium telles que :

Distribution globale clé en main.
Un débit dédié partout dans le monde.
Des latences de quelques millisecondes au 99e centile.
Une haute disponibilité garantie.
Une indexation secondaire automatique.
La bibliothèque cliente Tables Azure peut cibler en toute transparence le stockage de tables Azure ou les points de terminaison de service de table Azure Cosmos DB sans modification du code.

Liens clés :

Prise en main

Prérequis

Environnements actuellement pris en charge :

Versions LTS de Node.js
Dernières versions de Safari, Chrome, Edge et Firefox

Vous devez disposer d’un abonnement Azure et d’un compte de stockage ou d’une base de données Azure CosmosDB pour utiliser ce package.

Installez le package `@azure/data-tables`

La méthode recommandée pour installer la bibliothèque cliente Tables Azure pour JavaScript consiste à utiliser le gestionnaire de package npm. Tapez ce qui suit dans une fenêtre de terminal :

npm install @azure/data-tables

Authentifier un `TableServiceClient`

Les tables Azure prennent en charge plusieurs façons de s’authentifier. Pour interagir avec le service Tables Azure, vous devez créer un instance d’un client Tables, TableServiceClient ou TableClient par exemple. Consultez des exemples pour créer pour en savoir plus sur l’authentification TableServiceClient .

Remarque : Azure Active Directory (AAD) est uniquement pris en charge pour les comptes de stockage Azure.

Client de service avec clé partagée
Client de service avec signatures d’accès partagé
Client de service avec TokenCredential (AAD)
Client de table avec clé partagée
Client de table avec signatures d’accès partagé
Client de table avec TokenCredential (AAD)

Les fonctionnalités, interfaces, classes ou fonctions suivantes sont disponibles uniquement dans Node.js

Autorisation de clé partagée en fonction du nom du compte et de la clé de compte
- AzureNamedKeyCredential
- Chaîne de connexion de compte.

Ensemble JavaScript

Pour utiliser cette bibliothèque cliente dans le navigateur, vous devez d’abord utiliser un bundler. Pour plus d’informations sur la procédure à suivre, reportez-vous à notre documentation sur le regroupement.

CORS

Vous devez configurer des règles CORS (Cross-Origin Resource Sharing) pour votre compte de stockage si vous devez développer pour les navigateurs. Accédez à Portail Azure et Explorateur Stockage Azure, recherchez votre compte de stockage, créez de nouvelles règles CORS pour le ou les services blob/file/table.

Par exemple, vous pouvez créer les paramètres CORS suivants pour le débogage. Mais personnalisez soigneusement les paramètres en fonction de vos besoins dans l’environnement de production.

Origines autorisées : *
Verbes autorisés : DELETE,GET,HEAD,MERGE,POST,OPTIONS,PUT
En-têtes autorisés : *
En-têtes exposés : *
Âge maximal (secondes) : 86400

Concepts clés

TableServiceClient - Client qui fournit des fonctions permettant d’interagir au niveau d’un service de table, comme créer, répertorier et supprimer des tables
TableClient - Client qui fournit des fonctions pour interagir au niveau de l’entité, telles que créer, répertorier et supprimer des entités dans une table.
Table - Les tables stockent les données sous forme de collections d’entités.
Entity - Les entités sont similaires aux lignes. Une entité possède une clé primaire et un ensemble de propriétés. Une propriété est un nom, une paire de valeur typée, semblable à une colonne.

Voici quelques utilisations courantes du service de table :

Stockage des téraoctets de données structurées capables de servir des applications Web
Stockage de jeux de données qui ne nécessitent pas de jointures complexes, de clés étrangères ou de procédures stockées et qui peuvent être dénormalisés pour un accès rapide
Interrogation rapide des données par requête à l’aide d’un index cluster
Accès aux données à l’aide des expressions de filtre du protocole OData

Exemples

Importation du package
Créer le client du service de table
- Répertorier les tables dans le compte
- Créer une table
Création du client de tables
- Répertorier les entités dans une table
- Créer une entité et l’ajouter à une table

Importation du package

Pour utiliser les clients, importez le package dans votre fichier :

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

Vous pouvez également importer de manière sélective uniquement les types dont vous avez besoin :

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

Création du client du service de Table

Nécessite TableServiceClient une URL vers le service de table et des informations d’identification d’accès. Il accepte également éventuellement certains paramètres dans le options paramètre .

`TableServiceClient` avec AzureNamedKeyCredential

Vous pouvez instancier un TableServiceClient avec un AzureNamedKeyCredential en passant account-name et account-key en tant qu’arguments. (Vous pouvez obtenir le nom du compte et la clé de compte à partir du portail Azure.) [DISPONIBLE UNIQUEMENT DANS 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` avec TokenCredential (AAD)

Azure Tables fournit l’intégration à Azure Active Directory (Azure AD) pour l’authentification basée sur l’identité des demandes adressées au service Table lors du ciblage d’un point de terminaison de stockage. Avec Azure AD, vous pouvez utiliser le contrôle d’accès en fonction du rôle (RBAC) pour accorder l’accès à vos ressources de table Azure à des utilisateurs, des groupes ou des applications.

Pour accéder à une ressource de table avec un TokenCredential, l’identité authentifiée doit avoir le rôle « Contributeur aux données de table de stockage » ou « Lecteur de données de table de stockage ».

Avec le @azure/identity package, vous pouvez autoriser en toute transparence les demandes dans les environnements de développement et de production. Pour en savoir plus sur l’intégration d’Azure AD dans stockage Azure, consultez le fichier README Azure.Identity.

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` avec jeton SAS

En outre, vous pouvez instancier un TableServiceClient avec une signature d’accès partagé (SAP). Vous pouvez obtenir le jeton SAS à partir du portail 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)
);

Répertorier les tables dans le compte

Vous pouvez répertorier des tables au sein d’un compte via une TableServiceClient instance appelant la listTables fonction . Cette fonction retourne un PageableAsyncIterator que vous pouvez consommer à l’aide de 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() {
  let 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();

Créer une table

Vous pouvez créer une table par le biais d’une TableServiceClient instance appelant la createTable fonction . Cette fonction prend le nom de la table à créer en tant que paramètre. Notez que createTable ne génère pas d’erreur lorsque la table existe déjà.

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

Voici un exemple qui montre comment tester si la table existe déjà lorsque vous tentez de la créer :

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

Création du client de tables

est TableClient créé de la même manière que le TableServiceClient avec la différence qui TableClient prend un nom de table comme paramètre

`TableClient` avec `AzureNamedKeyCredential`

Vous pouvez instancier un TableClient avec un AzureNamedKeyCredential en passant account-name et account-key comme arguments. (Le nom du compte et la clé de compte peuvent être obtenus à partir du portail Azure.) [DISPONIBLE UNIQUEMENT DANS 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` avec `TokenCredential` (Azure Active Directory)

Azure Tables fournit l’intégration à Azure Active Directory (Azure AD) pour l’authentification basée sur l’identité des requêtes adressées au service Table lors du ciblage d’un point de terminaison de stockage. Avec Azure AD, vous pouvez utiliser le contrôle d’accès en fonction du rôle (RBAC) pour accorder l’accès à vos ressources Table Azure à des utilisateurs, des groupes ou des applications.

Avec le @azure/identity package, vous pouvez autoriser en toute transparence les demandes dans les environnements de développement et de production. Pour en savoir plus sur l’intégration d’Azure AD dans Stockage Azure, consultez le FICHIER README Azure.Identity.

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` avec jeton SAS

Vous pouvez instancier un TableClient avec une signature d’accès partagé (SAP). Vous pouvez obtenir le jeton SAP à partir du portail 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` avec TokenCredential (AAD)

Avec le @azure/identity package, vous pouvez autoriser en toute transparence les demandes dans les environnements de développement et de production. Pour en savoir plus sur l’intégration d’Azure AD dans Stockage Azure, consultez le FICHIER README Azure.Identity.

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

Lister des entités dans une table

Vous pouvez répertorier des entités au sein d’une table par le biais d’un TableClient instance appelant la listEntities fonction. Cette fonction retourne un PageableAsyncIterator que vous pouvez consommer à l’aide de 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() {
  let 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();

Créer une entité et l’ajouter à une table

Vous pouvez créer une entité dans une table par le biais d’un TableClient instance appelant la createEntity fonction. Cette fonction prend l’entité à insérer en tant que paramètre. L’entité doit contenir partitionKey et 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 et émulateur de stockage

Le Kit de développement logiciel (SDK) du client Azure Tables fonctionne également avec Azurite, un émulateur de serveur compatible avec stockage Azure et l’API Tables. Reportez-vous au (référentiel Azurite) pour savoir comment commencer à l’utiliser.

Connexion à Azurite avec le raccourci chaîne de connexion

Le moyen le plus simple de se connecter à Azurite à partir de votre application consiste à configurer une chaîne de connexion qui fait référence au raccourci UseDevelopmentStorage=true. Le raccourci équivaut à la chaîne de connexion complète de l’émulateur, qui spécifie le nom du compte, la clé de compte et les points de terminaison de l’émulateur pour chacun des services de stockage Azure : (voir plus). À l’aide de ce raccourci, le KIT de développement logiciel (SDK) du client Tables Azure configure la chaîne de connexion par défaut et allowInsecureConnection dans les options du client.

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

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

Connexion à Azurite sans raccourci chaîne de connexion

Vous pouvez vous connecter manuellement à azurite sans utiliser le raccourci de chaîne de connexion en spécifiant l’URL du service et AzureNamedKeyCredential ou une chaîne de connexion personnalisée. Toutefois, allowInsecureConnection doit être défini manuellement dans le cas où Azurite s’exécute dans un point de http terminaison.

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

Dépannage

Général

Lorsque vous interagissez avec le service Tables à l’aide du Kit de développement logiciel (SDK) Javascript/Typescript, les erreurs retournées par le service correspondent aux mêmes codes de status HTTP retournés pour les demandes d’API REST : Codes d’erreur du service Table de stockage

Journalisation

L’activation de la journalisation peut vous aider à mieux comprendre les échecs. Pour avoir un journal des requêtes et réponses HTTP, définissez la variable d’environnement AZURE_LOG_LEVEL sur info. Vous pouvez également activer la journalisation au moment de l’exécution en appelant setLogLevel dans @azure/logger :

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

setLogLevel("info");

Étapes suivantes

D’autres exemples de code bientôt disponibles Issue#10531

Contribution

Ce projet accepte les contributions et les suggestions. La plupart des contributions vous demandent d’accepter un contrat de licence de contribution (CLA) déclarant que vous avez le droit de nous accorder, et que vous nous accordez réellement, les droits d’utilisation de votre contribution. Pour plus d’informations, visitez https://cla.microsoft.com.

Quand vous envoyez une demande de tirage (pull request), un bot CLA détermine automatiquement si vous devez fournir un contrat CLA et agrémenter la demande de tirage de façon appropriée (par exemple, avec une étiquette ou un commentaire). Suivez simplement les instructions fournies par le bot. Vous ne devez effectuer cette opération qu’une seule fois sur tous les dépôts utilisant notre contrat CLA.

Ce projet a adopté le Code de conduite Open Source de Microsoft. Pour plus d’informations, consultez les Questions fréquentes (FAQ) sur le code de conduite ou envoyez vos questions ou vos commentaires à opencode@microsoft.com.

Si vous souhaitez contribuer à cette bibliothèque, lisez le guide de contribution pour en savoir plus sur la génération et le test du code.

Impressions

Bibliothèque cliente Tables Azure pour JavaScript - version 13.2.2

Prise en main

Prérequis

Installez le package `@azure/data-tables`

Authentifier un `TableServiceClient`

Les fonctionnalités, interfaces, classes ou fonctions suivantes sont disponibles uniquement dans Node.js

Ensemble JavaScript

CORS

Concepts clés

Exemples

Importation du package

Création du client du service de Table

`TableServiceClient` avec AzureNamedKeyCredential

`TableServiceClient` avec TokenCredential (AAD)

`TableServiceClient` avec jeton SAS

Répertorier les tables dans le compte

Créer une table

Création du client de tables

`TableClient` avec `AzureNamedKeyCredential`

`TableClient` avec `TokenCredential` (Azure Active Directory)

`TableClient` avec jeton SAS

`TableClient` avec TokenCredential (AAD)

Lister des entités dans une table

Créer une entité et l’ajouter à une table

Azurite et émulateur de stockage

Connexion à Azurite avec le raccourci chaîne de connexion

Connexion à Azurite sans raccourci chaîne de connexion

Dépannage

Général

Journalisation

Étapes suivantes

Contribution

Commentaires

Ressources supplémentaires

Bibliothèque cliente Tables Azure pour JavaScript - version 13.2.2

Prise en main

Prérequis

Installez le package @azure/data-tables

Authentifier un TableServiceClient

Les fonctionnalités, interfaces, classes ou fonctions suivantes sont disponibles uniquement dans Node.js

Ensemble JavaScript

CORS

Concepts clés

Exemples

Importation du package

Création du client du service de Table

TableServiceClient avec AzureNamedKeyCredential

TableServiceClient avec TokenCredential (AAD)

TableServiceClient avec jeton SAS

Répertorier les tables dans le compte

Créer une table

Création du client de tables

TableClient avec AzureNamedKeyCredential

TableClient avec TokenCredential (Azure Active Directory)

TableClient avec jeton SAS

TableClient avec TokenCredential (AAD)

Lister des entités dans une table

Créer une entité et l’ajouter à une table

Azurite et émulateur de stockage

Connexion à Azurite avec le raccourci chaîne de connexion

Connexion à Azurite sans raccourci chaîne de connexion

Dépannage

Général

Journalisation

Étapes suivantes

Contribution

Commentaires

Ressources supplémentaires

Installez le package `@azure/data-tables`

Authentifier un `TableServiceClient`

`TableServiceClient` avec AzureNamedKeyCredential

`TableServiceClient` avec TokenCredential (AAD)

`TableServiceClient` avec jeton SAS

`TableClient` avec `AzureNamedKeyCredential`

`TableClient` avec `TokenCredential` (Azure Active Directory)

`TableClient` avec jeton SAS

`TableClient` avec TokenCredential (AAD)