Bibliothèque de client Tables Azure pour Java - version 12.3.16

  • Article

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

| Code sourcePackage (Maven) | Documentation de référence sur les | API | Documentation produitÉchantillons

Prise en main

Inclure le package

Inclure le fichier de nomenclature

Incluez azure-sdk-bom dans votre projet pour dépendre de la version de disponibilité générale de la bibliothèque. Dans l’extrait de code suivant, remplacez l’espace réservé {bom_version_to_target} par le numéro de version. Pour en savoir plus sur la nomenclature, consultez le README BOM du KIT DE DÉVELOPPEMENT LOGICIEL 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>

puis incluez la dépendance directe dans la section dépendances sans la balise de version, comme indiqué ci-dessous.

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

Inclure une dépendance directe

Si vous souhaitez dépendre d’une version particulière de la bibliothèque qui n’est pas présente dans la nomenclature, ajoutez la dépendance directe à votre projet comme suit.

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

Prérequis

Créer un compte de stockage

Pour créer un compte de stockage, vous pouvez utiliser le portail Azure ou Azure CLI.

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

L’URL de votre compte de stockage, identifiée par la suite comme <your-table-account-url>, serait mise en forme comme suit http(s)://<storage-account-name>.table.core.windows.net.

Créer un compte d’API Table Cosmos DB

Pour créer un compte d’API Table Cosmos DB, vous pouvez utiliser le portail Azure ou Azure CLI.

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

L’URL de votre compte d’API Table, identifiée par la suite comme <your-table-account-url>, serait mise en forme comme suit http(s)://<cosmosdb-account-name>.table.cosmosdb.azure.com.

Authentifier le client

Chaque demande adressée au service Tables doit être autorisée à l’aide d’un chaîne de connexion, d’informations d’identification de clé nommée, d’une signature d’accès partagé ou d’informations d’identification de jeton. Les exemples ci-dessous illustrent l’utilisation de ces méthodes.

Remarque : Seuls les points de terminaison de l’API Stockage Azure prennent actuellement en charge l’autorisation AAD via les informations d’identification de jeton.

Chaîne de connexion

Une chaîne de connexion inclut les informations d’authentification requises pour que votre application accède aux données d’une table Azure lors de l’exécution à l’aide de l’autorisation de clé partagée. Consultez Authentifier avec une chaîne de connexion pour obtenir un exemple d’utilisation d’un chaîne de connexion avec un TableServiceClient.

Vous pouvez obtenir votre chaîne de connexion à partir du portail Azure (cliquez sur Clés d’accès sous Paramètres dans le panneau Du compte de stockage du portail ou Chaîne de connexion sous Paramètres dans le panneau du compte Cosmos DB du portail) ou à l’aide d’Azure CLI :

# 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>

Informations d’identification de clé partagée

L’autorisation Clé partagée s’appuie sur les clés d’accès de votre compte et d’autres paramètres pour produire une chaîne de signature chiffrée qui est transmise à la demande dans l’en-tête Authorization. Consultez s’authentifier avec des informations d’identification de clé partagée pour obtenir un exemple d’utilisation de l’autorisation de clé nommée avec un TableServiceClient.

Pour utiliser l’autorisation de clé nommée, vous avez besoin du nom et de l’URL de votre compte, ainsi que d’une clé d’accès au compte. Vous pouvez obtenir votre clé d’accès principale à partir du portail Azure (cliquez sur Clés d’accès sous Paramètres dans le panneau Du compte de stockage du portail ou Chaîne de connexion sous Paramètres dans le panneau du compte Cosmos DB du portail) ou à l’aide d’Azure CLI :

# 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>

Signature d’accès partagé (SAS)

Une signature d’accès partagé permet aux administrateurs de déléguer l’accès granulaire à une table Azure sans partager directement la clé d’accès. Vous pouvez contrôler les ressources auxquelles le client peut accéder, les autorisations dont il dispose sur ces ressources et la durée de validité de la sap, entre autres paramètres. Il s’appuie sur les clés d’accès de votre compte et d’autres paramètres pour produire une chaîne de signature chiffrée qui est passée sur la requête dans la chaîne de requête. Consultez s’authentifier avec une signature d’accès partagé (SAP) pour obtenir un exemple d’utilisation des signatures d’accès partagé avec un TableServiceClient.

Pour utiliser l’autorisation de jeton SAS, vous avez besoin du nom et de l’URL de votre compte, ainsi que de la signature d’accès partagé. Vous pouvez obtenir votre signature d’accès partagé à partir du portail Azure (cliquez sur Signature d’accès partagé sous Paramètres dans le panneau Compte de stockage du portail) ou à l’aide d’Azure CLI :

# 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

Tables Azure fournit l’intégration à Azure Active Directory (AAD) 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 AAD, 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 LISEZ-MOI d’identité Azure.

Concepts clés

  • TableServiceClient : un TableServiceClient objet client qui vous permet d’interagir avec le service de table pour créer, répertorier et supprimer des tables.
  • TableClient : un TableClient objet client qui vous permet d’interagir avec une table spécifique pour créer, upsert, mettre à jour, obtenir, répertorier et supprimer des entités qu’elle contient.
  • Table : une table est une collection d’entités. Les tables n’appliquent pas de schéma sur les entités, ce qui signifie qu’une seule table peut contenir des entités ayant différents ensembles de propriétés.
  • Entité : une entité est un ensemble de propriétés similaires à une ligne de base de données. Une entité dans le stockage Azure peut avoir une taille maximale d’1 Mo. Une entité dans le stockage Azure Cosmos DB peut avoir une taille maximale de 2 Mo. Une entité a une clé de partition et une clé de ligne qui identifient de façon unique l’entité dans la table.
  • Propriétés : une propriété est une paire nom-valeur. Chaque entité peut inclure jusqu’à 252 propriétés pour stocker des données. Chaque entité dispose également de trois propriétés système qui spécifient une clé de partition, une clé de ligne et un horodatage.
  • Clé de partition : la clé de partition d’une entité identifie la partition dans la table à laquelle appartient l’entité. Les entités ayant la même clé de partition peuvent être interrogées plus rapidement et insérées ou mises à jour dans des opérations atomiques.
  • Clé de ligne : la clé de ligne d’une entité est son identificateur unique dans une partition.

Les utilisations courantes du service Tables sont les suivantes :

  • 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 du protocole OData

Exemples

Authentifier un client

S’authentifier avec un chaîne de connexion

Pour utiliser un chaîne de connexion pour autoriser votre client, appelez la méthode du connectionString générateur avec votre chaîne de connexion.

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

S’authentifier avec une clé partagée

Pour utiliser une clé partagée afin d’autoriser votre client, créez un instance de avec le nom et la clé d’accès de AzureNamedKeyCredential votre compte. Appelez la méthode du générateur avec l’URL de endpoint votre compte et la credential méthode avec l’objet que AzureNamedKeyCredential vous avez créé.

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

S’authentifier avec une signature d’accès partagé (SAP)

Pour utiliser une signature d’accès partagé pour autoriser votre client, appelez la méthode du générateur avec l’URL de endpoint votre compte et la sasToken méthode avec votre SAP.

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

S’authentifier avec des informations d’identification de jeton

Pour autoriser votre client via AAD, créez un instance d’une classe d’informations d’identification qui implémente TokenCredential. Appelez la méthode du générateur avec l’URL de endpoint votre compte et la credential méthode avec l’objet que TokenCredential vous avez créé.

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

Créer, répertorier et supprimer des tables Azure

Construire un TableServiceClient

Construisez un TableServiceClient en créant un instance deTableServiceClientBuilder, puis en appelant les méthodes ou buildAsyncClient du buildClient générateur.

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

Créer une table

Créez une table en appelant la TableServiceClientméthode de createTable . Un TableClient sera retourné, ce client permet d’effectuer des opérations sur la table. Une exception est levée si une table portant le nom fourni existe.

TableClient tableClient = tableServiceClient.createTable(tableName);

Vous pouvez également appeler la createTableIfNotExists méthode qui crée la table uniquement si cette table n’existe pas et ne lève pas d’exception. Un TableClient sera également retourné.

TableClient tableClient = tableServiceClient.createTableIfNotExists(tableName);

Affichage de la liste des tables

Répertoriez ou interrogez l’ensemble des tables existantes en appelant la TableServiceClientméthode de listTables , en passant éventuellement un ListTablesOptions instance pour filtrer ou limiter les résultats de la requête. Pour plus d’informations sur les options de requête prises en charge, consultez Options de requête prises en charge.

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

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

Suppression d’une table

Supprimez une table en appelant la TableServiceClientméthode de deleteTable .

tableServiceClient.deleteTable(tableName);

Créer, répertorier et supprimer des entités de table

Construire un TableClient

Construisez un TableClient en créant un instance de TableClientBuilder, en appelant la méthode du tableName générateur avec le nom de la table, puis en appelant ses buildClient méthodes ou buildAsyncClient .

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

Vous pouvez également récupérer un TableClient à partir d’un existant TableServiceClient en appelant sa getTableClient méthode .

TableClient tableClient = tableServiceClient.getTableClient(tableName);

Créer une entité

Créez un TableEntity instance en fournissant la clé de partition et la clé de ligne de l’entité à créer, en ajoutant éventuellement des propriétés à l’objet créé. Passez ensuite l’objet à la TableClientméthode de createEntity . Une exception est levée si une entité avec la clé de partition et la clé de ligne fournies existe dans la table.

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

tableClient.createEntity(entity);

Lister les entités

Répertoriez ou interrogez l’ensemble d’entités dans la table en appelant la TableClientméthode de listEntities , en passant éventuellement un ListEntitiesOptions instance pour filtrer, sélectionner ou limiter les résultats de la requête. Pour plus d’informations sur les options de requête prises en charge, consultez Options de requête prises en charge.

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

Suppression d’une entité

Supprimez une entité en appelant la TableClientméthode de deleteEntity .

tableClient.deleteEntity(partitionKey, rowKey);

Dépannage

Général

Lorsque vous interagissez avec le service Tables à l’aide de la bibliothèque Tables Azure pour Java, les erreurs retournées par le service correspondent aux mêmes codes de status HTTP retournés pour les demandes d’API REST.

Par exemple, si vous essayez de créer une table qui existe déjà, une 409 erreur est retournée, indiquant « Conflit ».

// 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
}

Journalisation

L’activation de la journalisation peut vous aider à mieux comprendre les échecs. Pour afficher un journal des requêtes et réponses HTTP, définissez la AZURE_LOG_LEVEL variable d’environnement sur le niveau de détail souhaité. Pour obtenir une description des niveaux de journal disponibles, consultez LogLevel .

Étapes suivantes

Prise en main de nos exemples de table.

Contribution

Ce projet accepte les contributions et les suggestions. La plupart des contributions vous demandent d’accepter un contrat de licence de contribution (CLA) spécifiant que vous avez le droit de nous accorder les droits d’utiliser votre contribution, et que vous nous les accordez.

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.

Impressions