Comment utiliser le Stockage Table Azure et Azure Cosmos DB for Table avec Ruby

  • Article

S’APPLIQUE À : Table

Avertissement

Ce projet est à l’étape du support communautaire de son cycle de vie. À terme, toutes les bibliothèques clientes associées seront définitivement mises hors service. Pour plus d’informations sur la mise hors service et les alternatives à l’utilisation de ce projet, consultez Avis de mise hors service : bibliothèques clientes PHP stockage Azure.

Conseil

Le contenu de cet article s’applique au stockage Table Azure et à Azure Cosmos DB for Table. L’API pour Table est une offre Premium pour le stockage de tables qui offre des tables optimisées en débit, une distribution globale et des index secondaires automatiques.

Cet article vous montre comment créer des tables, stocker vos données et effectuer des opérations CRUD sur les données. Choisissez le service Table Azure ou Azure Cosmos DB for Table. Les exemples décrits dans cet article sont écrits en Ruby et utilisent la Bibliothèque de client du service de Table du Stockage Azure pour Ruby. Les scénarios traités incluent la création d’une table, la suppression d’une table, l’insertion d’entités et l’interrogation d’entités à partir de la table.

Créer un compte de service Azure

Vous pouvez travailler avec des tables à l’aide du Stockage Table Azure ou d’Azure Cosmos DB. Pour en savoir plus sur les différences entre les offres de table dans ces deux services, consultez la Vue d’ensemble de l’API pour Table. Vous devez créer un compte pour le service que vous allez utiliser. Les sections suivantes montrent comment créer un stockage Table Azure et le compte Azure Cosmos DB, mais vous pouvez simplement utiliser l’un d’eux.

Stockage Table Azure

Le moyen le plus simple de créer un compte de stockage Azure est d’utiliser le portail Azure. Pour plus d’informations, consultez la page Créer un compte de stockage.

Il est également possible de créer un compte de stockage Azure avec Azure PowerShell ou Azure CLI.

Si vous préférez ne pas créer de compte de stockage pour le moment, vous avez la possibilité d’utiliser l’émulateur de stockage Azure pour exécuter et tester votre code dans un environnement local. Pour plus d’informations, consultez Utiliser l’émulateur de stockage Azure pour le développement et le test.

Azure Cosmos DB for Table

Pour obtenir des instructions sur la création d’un compte Azure Cosmos DB for Table, consultez Créer un compte de base de données.

Ajouter un accès au stockage Azure ou à Azure Cosmos DB

Pour utiliser Stockage Azure ou Azure Cosmos DB, téléchargez et utilisez le package Ruby Azure. Ce package comprend un ensemble de bibliothèques pratiques qui communiquent avec les services REST de table.

Utilisation de RubyGems pour obtenir le package

  1. Ouvrez une interface de ligne de commande, telle que PowerShell (Windows), Terminal (Mac) ou Bash (Unix).
  2. Tapez gem install azure-storage-table dans la fenêtre de commande pour installer gem et les dépendances.

Importation du package

À l’aide de votre éditeur de texte, ajoutez la commande suivante au début du fichier Ruby où vous comptez utiliser Azure Storage :

require "azure/storage/table"

Ajouter votre chaîne de connexion

Vous pouvez vous connecter au compte de stockage Azure ou au compte Azure Cosmos DB for Table. Obtenez les chaîne de connexion en fonction du type de compte que vous utilisez.

Ajout d’une connexion au stockage Azure

Le module de Stockage Azure lit les variables d’environnement AZURE_STORAGE_ACCOUNT et AZURE_STORAGE_ACCESS_KEY pour obtenir les informations nécessaires à la connexion à votre compte de Stockage Azure. Si ces variables d’environnement ne sont pas définies, vous devez spécifier les informations de compte avant d’utiliser Azure ::Storage ::TableService avec le code suivant :

Azure.config.storage_account_name = "<your Azure Storage account>"
Azure.config.storage_access_key = "<your Azure Storage access key>"

Pour obtenir ces valeurs à partir d’un compte de stockage classique ou Resource Manager sur le portail Azure :

  1. Connectez-vous au portail Azure.
  2. Accédez au compte de Stockage que vous souhaitez utiliser.
  3. Dans la page Paramètres, sélectionnez Clés d’accès.
  4. Dans la page Clés d’accès, observez la clé d’accès 1 et la clé d’accès 2. Vous pouvez utiliser l’une de ces clés.
  5. Sélectionnez l’icône de copie pour copier la clé dans le Presse-papiers.

Ajouter une connexion à Azure Cosmos DB

Pour vous connecter à Azure Cosmos DB, copiez votre chaîne de connexion principale à partir du portail Azure, puis utilisez-la pour créer un objet Client. Vous pouvez transmettre l’objet Client lorsque vous créez un objet TableService :

common_client = Azure::Storage::Common::Client.create(storage_account_name:'myaccount', storage_access_key:'mykey', storage_table_host:'mycosmosdb_endpoint')
table_client = Azure::Storage::Table::TableService.new(client: common_client)

Créer une table

L’objet Azure::Storage::Table::TableService permet d’utiliser des tables et des entités. Pour créer une table, utilisez la méthode create_table() . L’exemple suivant crée une table ou imprime l’erreur le cas échéant.

azure_table_service = Azure::Storage::Table::TableService.new
begin
    azure_table_service.create_table("testtable")
rescue
    puts $!
end

Ajout d'une entité à une table

Pour ajouter une entité, créez tout d'abord un objet de hachage qui définit les propriétés de votre entité. Pour chaque entité, vous devez spécifier une PartitionKey et une RowKey. Ces entités sont les identificateurs uniques de vos entités et sont des valeurs qui peuvent être interrogées plus rapidement que vos autres propriétés. Azure Storage utilise PartitionKey pour distribuer automatiquement les entités de la table sur plusieurs nœuds de stockage. Les entités partageant la même clé PartitionKey sont stockées sur le même nœud. RowKey est l'identifiant unique de l'entité dans sa partition.

entity = { "content" => "test entity",
    :PartitionKey => "test-partition-key", :RowKey => "1" }
azure_table_service.insert_entity("testtable", entity)

Mise à jour d'une entité

Plusieurs méthodes permettent de mettre à jour une entité existante :

Description
update_entity() met à jour une entité existante en la remplaçant.
merge_entity() met à jour une entité existante en fusionnant les nouvelles valeurs des propriétés avec l’entité existante.
insert_or_merge_entity() met à jour une entité existante en la remplaçant. Si aucune entité n’existe, une nouvelle entité est insérée.
insert_or_replace_entity() met à jour une entité existante en fusionnant les nouvelles valeurs des propriétés avec l’entité existante. Si aucune entité n’existe, une nouvelle entité est insérée.

L’exemple suivant illustre la mise à jour d’une entité avec update_entity() :

entity = { "content" => "test entity with updated content",
    :PartitionKey => "test-partition-key", :RowKey => "1" }
azure_table_service.update_entity("testtable", entity)

Avec update_entity() et merge_entity(), si l’entité que vous mettez à jour n’existe pas, l’opération de mise à jour échoue. Si vous voulez stocker une entité, qu’elle existe déjà ou non, utilisez plutôt insert_or_replace_entity() ou insert_or_merge_entity() .

Utilisation des groupes d'entités

Il est parfois intéressant de soumettre un lot d'opérations simultanément pour assurer un traitement atomique par le serveur. Pour cela, vous devez d’abord créer un objet Batch, puis utiliser la méthode execute_batch() sur TableService. L'exemple ci-dessous présente l'envoi de deux entités avec RowKey 2 et 3 dans un lot. Notez qu'il ne s'applique qu'aux entités possédant le même élément PartitionKey.

azure_table_service = Azure::TableService.new
batch = Azure::Storage::Table::Batch.new("testtable",
    "test-partition-key") do
    insert "2", { "content" => "new content 2" }
    insert "3", { "content" => "new content 3" }
end
results = azure_table_service.execute_batch(batch)

Interrogation d’une entité

Pour interroger une entité dans une table, utilisez la méthode get_entity() en transmettant le nom de la table, PartitionKey et RowKey.

result = azure_table_service.get_entity("testtable", "test-partition-key",
    "1")

Interrogation d’un ensemble d’entités

Pour interroger un ensemble d’entités dans une table, créez un objet de hachage de requête et utilisez la méthode query_entities() . L'exemple ci-dessous présente l'obtention de toutes les identités avec le même élément PartitionKey:

query = { :filter => "PartitionKey eq 'test-partition-key'" }
result, token = azure_table_service.query_entities("testtable", query)

Notes

Si le jeu de résultats est trop grand pour être renvoyé par une seule requête, un jeton de liaison est renvoyé. Vous pouvez l’utiliser pour récupérer les pages suivantes.

Interrogation d'un sous-ensemble de propriétés d'entité

Vous pouvez utiliser une requête de table pour extraire uniquement quelques propriétés d’une entité. Cette technique de « projection » réduit la bande passante et peut améliorer les performances des requêtes, en particulier pour les grandes entités. Utilisez la clause select et transmettez le nom des propriétés à soumettre au client.

query = { :filter => "PartitionKey eq 'test-partition-key'",
    :select => ["content"] }
result, token = azure_table_service.query_entities("testtable", query)

Suppression d’une entité

Pour supprimer une entité, utilisez la méthodedelete_entity() . Transmettez le nom de la table qui contient l’entité, ainsi que les éléments PartitionKey et RowKey de l’entité.

azure_table_service.delete_entity("testtable", "test-partition-key", "1")

Suppression d’une table

Pour supprimer une table, utilisez la méthode delete_table() et transmettez le nom de la table que vous souhaitez supprimer.

azure_table_service.delete_table("testtable")

Contenu connexe