Compartir a través de

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

  • 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
  • Query/Create/Read/Update/Delete Entities

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 de milisegundos de un solo dígito en el percentil 99.
  • Alta disponibilidad garantizada.
  • Indexación secundaria automática.
  • La biblioteca cliente de Azure Tables 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 clave:

  • código fuente
  • paquete de (NPM)
  • documentación de referencia de api de
  • documentación del producto de
  • ejemplos de

Empezar

Prerrequisitos

Entornos admitidos actualmente:

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

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

Instalación del paquete @azure/data-tables

La manera preferida de instalar la biblioteca cliente de Tablas de Azure 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 Tablas, TableServiceClient o TableClient, por ejemplo. Consulte ejemplos para crear el TableServiceClient para 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 agrupador. Para obtener más información sobre cómo hacerlo, consulte nuestra documentación de agrupación de .

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 al Explorador de Azure Storage, busque la cuenta de almacenamiento y 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 par nombre, tipo-valor, similar a una columna.

Entre los usos comunes de Table service se incluyen:

  • Almacenamiento de bases de datos estructurados capaces de atender 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 expresiones de filtro de 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

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

TableServiceClient con AzureNamedKeyCredential

Puede crear una instancia de un TableServiceClient con un AzureNamedKeyCredential pasando 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 identidad de las solicitudes a Table service al dirigirse a 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 un TokenCredential, la identidad autenticada debe tener el rol "Colaborador de datos de tabla de almacenamiento" o "Lector de datos de tabla de almacenamiento".

Con el paquete @azure/identity, 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 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 instancias de un TableServiceClient con firmas 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 instancia de TableServiceClient que llama a la función listTables. Esta función devuelve un PageableAsyncIterator que 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() {
  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();

Creación de una nueva tabla

Puede crear una tabla a través de una instancia de TableServiceClient que llame a la función createTable. 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 tabla

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

TableClient con AzureNamedKeyCredential

Puede crear una instancia de un TableClient con un AzureNamedKeyCredential pasando 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 con TokenCredential (Azure Active Directory)

Azure Tables proporciona integración con Azure Active Directory (Azure AD) para la autenticación basada en identidad de las solicitudes a Table service al dirigirse a 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 un TokenCredential, la identidad autenticada debe tener el rol "Colaborador de datos de tabla de almacenamiento" o "Lector de datos de tabla de almacenamiento".

Con el paquete @azure/identity, 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 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 instancias de un TableClient con firmas 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 identidad de las solicitudes a Table service al dirigirse a 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 un TokenCredential, la identidad autenticada debe tener el rol "Colaborador de datos de tabla de almacenamiento" o "Lector de datos de tabla de almacenamiento".

Con el paquete @azure/identity, 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 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 de una tabla

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

Crear una nueva entidad y agregarla a una tabla

Puede crear una nueva entidad en una tabla mediante una instancia de TableClient que llame a la función createEntity. 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 (repositorio de 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 para el 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: (ver 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 manualmente a azurite sin usar el acceso directo de la cadena de conexión especificando la dirección URL del servicio y AzureNamedKeyCredential o una cadena de conexión personalizada. Sin embargo, allowInsecureConnection tendrá que establecerse manualmente en caso de que Azurite se ejecute en un punto de conexión de 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 }
);

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 API REST: códigos de error de Table Service de almacenamiento

Registro

Habilitar el registro puede ayudar a descubrir información útil sobre 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 el @azure/logger:

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

setLogLevel("info");

Pasos siguientes

Más ejemplos de código próximamente Problema 10531

Contribuyendo

Este proyecto da la bienvenida a las contribuciones y sugerencias. La mayoría de las contribuciones requieren que acepte un Contrato de licencia de colaborador (CLA) declarando que tiene derecho a, y en realidad, concedanos los derechos para usar su contribución. Para obtener más información, visite https://cla.microsoft.com.

Al enviar una solicitud de incorporación de cambios, un bot CLA determinará automáticamente si necesita proporcionar un CLA y decorar la solicitud de incorporación de cambios de forma adecuada (por ejemplo, etiqueta, comentario). Solo tiene que seguir las instrucciones proporcionadas por el bot. Solo tendrá que hacerlo una vez en todos los repositorios mediante nuestro CLA.

Este proyecto ha adoptado el código abierto de conducta de Microsoft. Para obtener más información, consulte el de preguntas más frecuentes sobre el código de conducta de o póngase en contacto con con preguntas o comentarios adicionales.

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

impresiones