Share via

Biblioteca cliente de Azure Tables para JavaScript: versión 13.2.2

  • Artículo

Azure Tables es un servicio basado en la nube que almacena datos NoSQL estructurados, lo que proporciona un almacén de claves y atributos con un diseño sin esquemas. El almacenamiento de tablas proporciona a los desarrolladores flexibilidad y escalabilidad con todas las mejores partes de la nube de Azure.

Use la biblioteca cliente para:

  • Crear o eliminar tablas
  • Consulta, creación, lectura, actualización y eliminación de entidades

Azure Cosmos DB proporciona table API para aplicaciones escritas para Azure Table Storage y que necesitan funcionalidades premium como:

  • Distribución global llave en mano.
  • Rendimiento dedicado en todo el mundo.
  • Latencias en milisegundos de un solo dígito en el percentil 99.
  • Alta disponibilidad garantizada.
  • Indexación secundaria automática.
  • La biblioteca cliente de Tablas de Azure puede tener como destino sin problemas los puntos de conexión de Azure Table Storage o Table Service de Azure Cosmos DB sin cambios de código.

Vínculos principales:

Introducción

Requisitos previos

Entornos admitidos actualmente:

  • Versiones LTS de Node.js
  • Versiones más recientes de Safari, Chrome, Edge y Firefox

Debe tener una suscripción de Azure y una cuenta de almacenamiento o una base de datos de Azure CosmosDB para usar este paquete.

Instalar el paquete @azure/data-tables

La manera preferida de instalar la biblioteca cliente de Azure Tables para JavaScript es usar el administrador de paquetes npm. Escriba lo siguiente en una ventana de terminal:

npm install @azure/data-tables

Autenticación de un TableServiceClient

Azure Tables admite varias maneras de autenticarse. Para interactuar con el servicio Tablas de Azure, deberá crear una instancia de un cliente de Tables, TableServiceClient o TableClient por ejemplo. Consulte ejemplos para crear para TableServiceClient obtener más información sobre la autenticación.

Nota: Azure Active Directory (AAD) solo se admite para las cuentas de Azure Storage.

Las siguientes características, interfaces, clases o funciones solo están disponibles en Node.js

  • Autorización de clave compartida basada en el nombre de cuenta y la clave de cuenta
    • AzureNamedKeyCredential
    • Cadena de conexión de la cuenta.

Paquete de JavaScript

Para usar esta biblioteca cliente en el explorador, primero debe usar un empaquetador. Para más información sobre cómo hacerlo, consulte nuestra documentación de agrupación.

CORS

Debe configurar reglas de uso compartido de recursos entre orígenes (CORS) para la cuenta de almacenamiento si necesita desarrollar para exploradores. Vaya a Azure Portal y Explorador de Azure Storage, busque la cuenta de almacenamiento, cree nuevas reglas de CORS para blob/queue/file/table service(s).

Por ejemplo, puede crear la siguiente configuración de CORS para la depuración. Pero personalice cuidadosamente la configuración según sus requisitos en el entorno de producción.

  • Orígenes permitidos: *
  • Verbos permitidos: DELETE,GET,HEAD,MERGE,POST,OPTIONS,PUT
  • Encabezados permitidos: *
  • Encabezados expuestos: *
  • Antigüedad máxima (segundos): 86400

Conceptos clave

  • TableServiceClient - Cliente que proporciona funciones para interactuar en un nivel de Table Service, como crear, enumerar y eliminar tablas

  • TableClient - Cliente que proporciona funciones para interactuar en un nivel de entidad, como crear, enumerar y eliminar entidades dentro de una tabla.

  • Table - Las tablas almacenan datos como colecciones de entidades.

  • Entity - Las entidades son similares a las filas. Una entidad tiene una clave principal y un conjunto de propiedades. Una propiedad es un nombre, un par de valor con tipo, que es similar a una columna.

Entre los usos frecuentes de Table service se encuentran los siguientes:

  • Almacenamiento de TB de datos estructurados capaces de ofrecer servicio a aplicaciones de escalado web
  • Almacenamiento de conjuntos de datos que no requieren combinaciones complejas, claves externas o procedimientos almacenados y se pueden des normalizar para un acceso rápido
  • Consulta rápida de datos mediante un índice agrupado
  • Acceso a datos mediante las expresiones de filtro del protocolo OData

Ejemplos

Importación del paquete

Para usar los clientes, importe el paquete en el archivo:

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

Como alternativa, importe de forma selectiva solo los tipos que necesita:

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

Creación del cliente de Table service

TableServiceClient requiere una dirección URL para Table Service y una credencial de acceso. También acepta algunas opciones de configuración en el options parámetro .

TableServiceClient con AzureNamedKeyCredential

Puede crear una instancia de con TableServiceClient un AzureNamedKeyCredential si pasa el nombre de cuenta y la clave de cuenta como argumentos. (El nombre de cuenta y la clave de cuenta se pueden obtener en Azure Portal). [SOLO DISPONIBLE EN 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)

Azure Tables proporciona integración con Azure Active Directory (Azure AD) para la autenticación basada en identidades de las solicitudes a Table service cuando el destino es un punto de conexión de Storage. Con Azure AD, puede usar el control de acceso basado en rol (RBAC) para conceder acceso a los recursos de Azure Table a usuarios, grupos o aplicaciones.

Para acceder a un recurso de tabla con , TokenCredentialla identidad autenticada debe tener el rol "Colaborador de datos de tabla de almacenamiento" o "Lector de datos de tabla de almacenamiento".

Con el @azure/identity paquete, puede autorizar sin problemas las solicitudes en entornos de desarrollo y producción. Para más información sobre la integración de Azure AD en Azure Storage, consulte el archivo Léame de 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 con token de SAS

Además, puede crear TableServiceClient una instancia de con una firma de acceso compartido (SAS). Puede obtener el token de SAS desde 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)
);

Enumerar tablas de la cuenta

Puede enumerar tablas dentro de una cuenta a través de una TableServiceClient instancia que llama a la listTables función . Esta función devuelve un PageableAsyncIterator objeto que se puede consumir mediante 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();

Creación de una nueva tabla

Puede crear una tabla a través de una TableServiceClient instancia de que llame a la createTable función . Esta función toma el nombre de la tabla que se va a crear como parámetro. Tenga en cuenta que createTable no producirá un error cuando la tabla ya exista.

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

Este es un ejemplo que muestra cómo probar si la tabla ya existe al intentar 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();

Creación del cliente de Table

TableClient se crea de forma similar a con la TableServiceClient diferencia que TableClient toma un nombre de tabla como parámetro

TableClient con AzureNamedKeyCredential

Puede crear una instancia de con TableClient un AzureNamedKeyCredential si pasa el nombre de cuenta y la clave de cuenta como argumentos. (El nombre de cuenta y la clave de cuenta se pueden obtener en Azure Portal). [SOLO DISPONIBLE EN 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 with TokenCredential (Azure Active Directory)

Azure Tables proporciona integración con Azure Active Directory (Azure AD) para la autenticación basada en identidades de las solicitudes a Table service cuando el destino es un punto de conexión de Storage. Con Azure AD, puede usar el control de acceso basado en rol (RBAC) para conceder acceso a los recursos de Azure Table a usuarios, grupos o aplicaciones.

Para acceder a un recurso de tabla con , TokenCredentialla identidad autenticada debe tener el rol "Colaborador de datos de tabla de almacenamiento" o "Lector de datos de tabla de almacenamiento".

Con el @azure/identity paquete, puede autorizar sin problemas las solicitudes en entornos de desarrollo y producción. Para más información sobre la integración de Azure AD en Azure Storage, consulte el archivo Léame de 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 con token de SAS

Puede crear una instancia de con TableClient una firma de acceso compartido (SAS). Puede obtener el token de SAS desde 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 con TokenCredential (AAD)

Azure Tables proporciona integración con Azure Active Directory (Azure AD) para la autenticación basada en identidades de las solicitudes a Table service cuando el destino es un punto de conexión de Storage. Con Azure AD, puede usar el control de acceso basado en rol (RBAC) para conceder acceso a los recursos de Azure Table a usuarios, grupos o aplicaciones.

Para acceder a un recurso de tabla con , TokenCredentialla identidad autenticada debe tener el rol "Colaborador de datos de tabla de almacenamiento" o "Lector de datos de tabla de almacenamiento".

Con el @azure/identity paquete, puede autorizar sin problemas las solicitudes en entornos de desarrollo y producción. Para más información sobre la integración de Azure AD en Azure Storage, consulte el archivo Léame de 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
);

Enumerar entidades en una tabla

Puede enumerar entidades dentro de una tabla mediante una TableClient instancia de que llama a la listEntities función . Esta función devuelve un PageableAsyncIterator objeto que se puede consumir mediante 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();

Crear una nueva entidad y agregarla a una tabla

Puede crear una nueva entidad en una tabla mediante una TableClient instancia de que llame a la createEntity función . Esta función toma la entidad para insertarla como parámetro. La entidad debe contener partitionKey y 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();

Emulador de Azurite y Storage

El SDK de cliente de Azure Tables también funciona con Azurite, un emulador de servidor compatible con Azure Storage y Tables API. Consulte el repositorio (Azurite) sobre cómo empezar a usarlo.

Conexión a Azurite con acceso directo de cadena de conexión

La manera más fácil de conectarse a Azurite desde la aplicación es configurar una cadena de conexión que haga referencia al acceso directo UseDevelopmentStorage=true. El acceso directo es equivalente a la cadena de conexión completa del emulador, que especifica el nombre de la cuenta, la clave de cuenta y los puntos de conexión del emulador para cada uno de los servicios de Azure Storage: (consulte más). Con este acceso directo, el SDK de cliente de Tablas de Azure configuraría la cadena de conexión predeterminada y allowInsecureConnection en las opciones de cliente.

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

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

Conexión a Azurite sin acceso directo de cadena de conexión

Puede conectarse a azurite manualmente sin usar el acceso directo de la cadena de conexión especificando la dirección URL del servicio o AzureNamedKeyCredential una cadena de conexión personalizada. Sin embargo, allowInsecureConnection deberá establecerse manualmente en caso de que Azurite se ejecute en un http punto de conexión.

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

Solución de problemas

General

Al interactuar con el servicio Tables mediante el SDK de Javascript/Typescript, los errores devueltos por el servicio corresponden a los mismos códigos de estado HTTP devueltos para las solicitudes de la API REST: Códigos de error de Storage Table Service

Registro

La habilitación del registro puede ayudar a descubrir información útil sobre los errores. Para ver un registro de solicitudes y respuestas HTTP, establezca la variable de entorno AZURE_LOG_LEVEL en info. Como alternativa, el registro se puede habilitar en tiempo de ejecución llamando a setLogLevel en @azure/logger:

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

setLogLevel("info");

Pasos siguientes

Próximamente se emitirán más ejemplos de código# 10531

Contribuciones

Este proyecto agradece las contribuciones y sugerencias. La mayoría de las contribuciones requieren que acepte un Contrato de licencia para el colaborador (CLA) que declara que tiene el derecho a concedernos y nos concede los derechos para usar su contribución. Para más detalles, visite https://cla.microsoft.com.

Cuando se envía una solicitud de incorporación de cambios, un bot de CLA determinará de forma automática si tiene que aportar un CLA y completar la PR adecuadamente (por ejemplo, la etiqueta, el comentario). Solo siga las instrucciones que le dará el bot. Solo será necesario que lo haga una vez en todos los repositorios con nuestro CLA.

Este proyecto ha adoptado el Código de conducta de Microsoft Open Source. Para más información, consulte las preguntas más frecuentes del código de conducta o póngase en contacto con opencode@microsoft.com si tiene cualquier otra pregunta o comentario.

Si desea contribuir a esta biblioteca, lea la guía de contribución para obtener más información sobre cómo compilar y probar el código.

Impresiones