Biblioteca cliente de Azure Tables para Java: versión 12.3.16

  • Artículo

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

Código | fuentePaquete (Maven) | Documentación | de referencia de API | Documentación del productoMuestras

Introducción

Inclusión del paquete

Inclusión del archivo BOM

Incluya azure-sdk-bom en el proyecto para depender de la versión de disponibilidad general (GA) de la biblioteca. En el fragmento de código siguiente, reemplace el marcador de posición {bom_version_to_target} por el número de versión. Para más información sobre la lista de materiales, consulte el archivo Léame bom del SDK de AZURE.

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>com.azure</groupId>
            <artifactId>azure-sdk-bom</artifactId>
            <version>{bom_version_to_target}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

y, a continuación, incluya la dependencia directa en la sección de dependencias sin la etiqueta de versión, como se muestra a continuación.

<dependencies>
    <dependency>
        <groupId>com.azure</groupId>
        <artifactId>azure-data-tables</artifactId>
    </dependency>
</dependencies>

Inclusión de dependencias directas

Si desea depender de una versión determinada de la biblioteca que no está presente en la lista de materiales, agregue la dependencia directa al proyecto como se indica a continuación.

<dependency>
  <groupId>com.azure</groupId>
  <artifactId>azure-data-tables</artifactId>
  <version>12.3.16</version>
</dependency>

Requisitos previos

Creación de una cuenta de almacenamiento

Para crear una cuenta de almacenamiento, puede usar Azure Portal o la CLI de Azure.

az storage account create \
    --resource-group <resource-group-name> \
    --name <storage-account-name> \
    --location <location>

La dirección URL de la cuenta de almacenamiento, identificada posteriormente como <your-table-account-url>, tendría el formato siguiente http(s)://<storage-account-name>.table.core.windows.net.

Creación de una cuenta de Table API de Cosmos DB

Para crear una cuenta de Table API de Cosmos DB, puede usar Azure Portal o la CLI de Azure.

az cosmosdb create \
    --resource-group <resource-group-name> \
    --name <cosmosdb-account-name> \
    --capabilities EnableTable

La dirección URL de la cuenta de Table API, identificada posteriormente como <your-table-account-url>, tendría el formato siguiente http(s)://<cosmosdb-account-name>.table.cosmosdb.azure.com.

Autenticar el cliente

Todas las solicitudes realizadas al servicio Tables deben autorizarse mediante una cadena de conexión, credenciales de clave con nombre, firma de acceso compartido o credenciales de token. Los ejemplos siguientes muestran el uso de estos métodos.

Nota: Actualmente, solo los puntos de conexión de la API de Azure Storage admiten la autorización de AAD mediante credenciales de token.

Cadena de conexión

Un cadena de conexión incluye la información de autenticación necesaria para que la aplicación acceda a los datos de una tabla de Azure en tiempo de ejecución mediante la autorización de clave compartida. Consulte Autenticación con una cadena de conexión para obtener un ejemplo de cómo usar un cadena de conexión con .TableServiceClient

Puede obtener el cadena de conexión desde Azure Portal (haga clic en Claves de acceso en Configuración en la hoja Cuenta de almacenamiento del portal o Cadena de conexión en Configuración en la hoja Cuenta de Cosmos DB del portal) o mediante la CLI de Azure:

# Storage account
az storage account show-connection-string \
    --resource-group <resource-group-name> \
    --name <storage-account-name>

# Cosmos DB Table API account
az cosmosdb list-connection-strings \
    --resource-group <resource-group-name> \
    --name <cosmosdb-account-name>

Credencial de clave compartida

La autorización de clave compartida se basa en las claves de acceso de la cuenta y otros parámetros para generar una cadena de firma cifrada que se pasará en la solicitud en el encabezado de autorización. Consulte Autenticación con una credencial de clave compartida para obtener un ejemplo de cómo usar la autorización de clave con nombre con .TableServiceClient

Para usar la autorización de clave con nombre, necesitará el nombre y la dirección URL de la cuenta, así como una clave de acceso de la cuenta. Puede obtener la clave de acceso principal desde Azure Portal (haga clic en Claves de acceso en Configuración en la hoja Cuenta de almacenamiento del portal o Cadena de conexión en Configuración en la hoja Cuenta de Cosmos DB del portal) o mediante la CLI de Azure:

# Storage account
az storage account keys list \
    --resource-group <resource-group-name> \
    --account-name <storage-account-name>

# Cosmos DB Table API account
az cosmosdb list-keys \
    --resource-group <resource-group-name> \
    --name <cosmosdb-account-name>

Firma de acceso compartido (SAS)

Una firma de acceso compartido permite a los administradores delegar acceso granular a una tabla de Azure sin compartir la clave de acceso directamente. Puede controlar qué recursos puede tener acceso el cliente, qué permisos tiene en esos recursos y cuánto tiempo es válido la SAS, entre otros parámetros. Se basa en las claves de acceso de la cuenta y otros parámetros para generar una cadena de firma cifrada que se pasa en la solicitud en la cadena de consulta. Consulte Autenticación con una firma de acceso compartido (SAS) para obtener un ejemplo de cómo usar firmas de acceso compartido con .TableServiceClient

Para usar la autorización del token de SAS, necesitará el nombre y la dirección URL de la cuenta, así como la SAS. Puede obtener la SAS desde Azure Portal (haga clic en Firma de acceso compartido en Configuración en la hoja Cuenta de almacenamiento del portal) o mediante la CLI de Azure:

# Account-level SAS
az storage account generate-sas \
    --account-name <storage-or-cosmosdb-account-name> \
    --services t \
    --resource-types <resource-types> \
    --permissions <permissions> \
    --expiry <expiry-date>

# Table-level SAS
az storage table generate-sas \
    --name <table-name>

TokenCredential

Azure Tables proporciona integración con Azure Active Directory (AAD) para la autenticación basada en identidades de las solicitudes en Table service cuando el destino es un punto de conexión de Storage. Con AAD, 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 identidad de Azure.

Conceptos clave

  • TableServiceClient : TableServiceClient es un objeto de cliente que permite interactuar con Table Service para crear, enumerar y eliminar tablas.
  • TableClient : es TableClient un objeto de cliente que permite interactuar con una tabla específica para crear, upsert, actualizar, obtener, enumerar y eliminar entidades dentro de ella.
  • Tabla : una tabla es una colección de entidades. Las tablas no exigen un esquema sobre entidades, lo que significa que una única tabla puede contener entidades que dispongan de diferentes conjuntos de propiedades.
  • Entidad : una entidad es un conjunto de propiedades, similar a una fila de base de datos. Una entidad en Azure Storage puede tener hasta 1 MB. Una entidad en Azure Cosmos DB puede tener hasta 2 MB. Una entidad tiene una clave de partición y una clave de fila que identifican de forma única la entidad dentro de la tabla.
  • Propiedades : una propiedad es un par nombre-valor. Cada entidad puede incluir hasta 252 propiedades para almacenar datos. Cada entidad dispone también de tres propiedades del sistema que especifican una clave de partición, una clave de fila y una marca de tiempo.
  • Clave de partición : la clave de partición de una entidad identifica la partición dentro de la tabla a la que pertenece la entidad. Pueden realizarse consultas en las entidades con la misma partición de manera más rápida e insertarse o actualizarse en operaciones atómicas.
  • Clave de fila: la clave de fila de una entidad es su identificador único dentro de una partición.

Entre los usos comunes del servicio Tables se incluyen:

  • 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 el protocolo OData

Ejemplos

Autenticación de un cliente

Autenticación con un cadena de conexión

Para usar un cadena de conexión para autorizar al cliente, llame al método del connectionString generador con el cadena de conexión.

TableServiceClient tableServiceClient = new TableServiceClientBuilder()
    .connectionString("<your-connection-string>")
    .buildClient();

Autenticación con una clave compartida

Para usar una clave compartida para autorizar al cliente, cree una instancia de con el nombre de la cuenta y la clave de AzureNamedKeyCredential acceso. Llame al método del generador con la dirección URL de endpoint la cuenta y el credential método con el AzureNamedKeyCredential objeto que creó.

AzureNamedKeyCredential credential = new AzureNamedKeyCredential("<your-account-name>", "<account-access-key>");
TableServiceClient tableServiceClient = new TableServiceClientBuilder()
    .endpoint("<your-table-account-url>")
    .credential(credential)
    .buildClient();

Autenticación con una firma de acceso compartido (SAS)

Para usar una SAS para autorizar al cliente, llame al método del generador con la dirección URL de endpoint la cuenta y el método con la sasToken SAS.

TableServiceClient tableServiceClient = new TableServiceClientBuilder()
    .endpoint("<your-table-account-url>")
    .sasToken("<sas-token-string>")
    .buildClient();

Autenticación con credenciales de token

Para autorizar al cliente a través de AAD, cree una instancia de una clase de credenciales que implemente TokenCredential. Llame al método del generador con la dirección URL de endpoint la cuenta y el credential método con el TokenCredential objeto que creó.

TokenCredential tokenCredential = new DefaultAzureCredentialBuilder().build();
TableServiceClient tableServiceClient = new TableServiceClientBuilder()
    .endpoint("<your-table-account-url>")
    .credential(tokenCredential)
    .buildClient();

Creación, enumeración y eliminación de tablas de Azure

Cree un elemento TableServiceClient

Construya un TableServiceClient mediante la creación de una instancia de TableServiceClientBuilder y, a continuación, llame a los métodos o buildAsyncClient del buildClient generador.

TableServiceClient tableServiceClient = new TableServiceClientBuilder()
    .connectionString("<your-connection-string>") // or use any of the other authentication methods
    .buildClient();

Creación de una tabla

Cree una tabla llamando al TableServiceClientmétodo de createTable . Se devolverá un TableClient , este cliente permite realizar operaciones en la tabla. Se producirá una excepción si existe una tabla con el nombre proporcionado.

TableClient tableClient = tableServiceClient.createTable(tableName);

Como alternativa, puede llamar al createTableIfNotExists método que creará la tabla solo si no existe dicha tabla y no produce una excepción. TableClient También se devolverá un elemento .

TableClient tableClient = tableServiceClient.createTableIfNotExists(tableName);

Enumeración de tablas

Enumere o consulte el conjunto de tablas existentes llamando al TableServiceClientmétodo del listTables , pasando opcionalmente una ListTablesOptions instancia para filtrar o limitar los resultados de la consulta. Consulte Opciones de consulta admitidas para obtener más información sobre las opciones de consulta admitidas.

ListTablesOptions options = new ListTablesOptions()
    .setFilter(String.format("TableName eq '%s'", tableName));

for (TableItem tableItem : tableServiceClient.listTables(options, null, null)) {
    System.out.println(tableItem.getName());
}

Eliminar una tabla

Elimine una tabla llamando al TableServiceClientmétodo de deleteTable .

tableServiceClient.deleteTable(tableName);

Crear, enumerar y eliminar entidades de tabla

Cree un elemento TableClient

Construya un TableClient mediante la creación de una instancia de TableClientBuilder, llamando al método del tableName generador con el nombre de la tabla y, a continuación, llamando a sus buildClient métodos o buildAsyncClient .

TableClient tableClient = new TableClientBuilder()
    .connectionString("<your-connection-string>") // or use any of the other authentication methods
    .tableName(tableName)
    .buildClient();

Como alternativa, TableClient se puede recuperar de un existente TableServiceClient mediante una llamada a su getTableClient método .

TableClient tableClient = tableServiceClient.getTableClient(tableName);

Crear una entidad

Cree una nueva TableEntity instancia, proporcionando la clave de partición y la clave de fila de la entidad que se va a crear, agregando opcionalmente propiedades al objeto creado. A continuación, pase el objeto al TableClientmétodo de .createEntity Se producirá una excepción si existe una entidad con la clave de partición y la clave de fila proporcionadas dentro de la tabla.

TableEntity entity = new TableEntity(partitionKey, rowKey)
    .addProperty("Product", "Marker Set")
    .addProperty("Price", 5.00)
    .addProperty("Quantity", 21);

tableClient.createEntity(entity);

Entidades de lista

Enumere o consulte el conjunto de entidades dentro de la tabla llamando al TableClientmétodo de listEntities , pasando opcionalmente una ListEntitiesOptions instancia para filtrar, seleccionar o limitar los resultados de la consulta. Consulte Opciones de consulta admitidas para obtener más información sobre las opciones de consulta admitidas.

List<String> propertiesToSelect = new ArrayList<>();
propertiesToSelect.add("Product");
propertiesToSelect.add("Price");

ListEntitiesOptions options = new ListEntitiesOptions()
    .setFilter(String.format("PartitionKey eq '%s'", partitionKey))
    .setSelect(propertiesToSelect);

for (TableEntity entity : tableClient.listEntities(options, null, null)) {
    Map<String, Object> properties = entity.getProperties();
    System.out.printf("%s: %.2f%n", properties.get("Product"), properties.get("Price"));
}

Eliminación de una entidad

Elimine una entidad llamando al TableClientmétodo de .deleteEntity

tableClient.deleteEntity(partitionKey, rowKey);

Solución de problemas

General

Al interactuar con el servicio Tables mediante la biblioteca de Tablas de Azure para Java, los errores devueltos por el servicio corresponden a los mismos códigos de estado HTTP devueltos para las solicitudes de API REST .

Por ejemplo, si intenta crear una tabla que ya existe, se devuelve un 409 error, que indica "Conflicto".

// Create the table if it doesn't already exist.
tableServiceClient.createTableIfNotExists(tableName);

// Now attempt to create the same table unconditionally.
try {
    tableServiceClient.createTable(tableName);
} catch (TableServiceException e) {
    System.out.println(e.getResponse().getStatusCode()); // 409
}

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 AZURE_LOG_LEVEL variable de entorno en el nivel de detalle deseado. Consulte LogLevel para obtener una descripción de los niveles de registro disponibles.

Pasos siguientes

Empiece a trabajar con nuestros ejemplos de table.

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.

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.

Impresiones