API des tables Microsoft Azure
Remonter à Environnement Azure et Cloud avec DataSnap
Avertissement : L'API DSAzure est devenue obsolète et a été remplacée par Data.Cloud.AzureAPI. Nous vous encourageons à utiliser la nouvelle API lors du développement d'applications d'environnement cloud. Pour de plus amples informations, voir Environnement Cloud avec DataSnap.
L'API des tables Microsoft Azure est située dans l'unité DSAzure, dans la classe TAzureTableService. Pour obtenir un exemple de l'API utilisée, consultez la section implementation des unités DSAzureTable et DSAzureTableDialog. Il s'agit du composant visuel qui utilise l'API.
Sommaire
Les fonctions disponibles sont les suivantes : la création d'une table, la suppression d'une table, l'obtention des tables disponibles, l'obtention des lignes (entités) d'une table, l'ajout d'une ligne à une table, et la suppression de lignes d'une table. Il est important de noter que les lignes ne se conforment à aucun schéma, et que chaque ligne peut avoir un jeu différent de colonnes (propriétés). Il est aussi important de noter que toutes les lignes auront au moins deux colonnes, qui forment ensemble une clé unique pour cette ligne : PartitionKey et RowKey. Toutes les lignes auront également un Timestamp (horodatage), mais il n'est pas censé être exposé ou modifié par un utilisateur.
Les instructions suivantes supposent que vous avez déjà créé une instance de TAzureTableService. Dans les extraits de code, cette instance sera référencée comme FTableService. Il est aussi supposé que vous avez un analyseur XML à disposition et qu'il est déjà configuré de façon appropriée. L'API renvoie dans certains cas un XML, que vous devez savoir analyser.
Obtention d'une liste de tables
Pour obtenir la liste des tables disponibles, appelez :
xml := FTableService.QueryTables();
Ceci renvoie une chaîne XML, qui devrait ressembler à ceci :
<feed ...>
...
<entry>
<id>http://myaccount.tables.core.windows.net/Tables('mytable')</id>
...
<content type="application/xml">
<m:properties>
<d:TableName>mytable</d:TableName>
</m:properties>
</content>
</entry>
</feed>
Pour obtenir un exemple complet du XML renvoyé ainsi que d'autres informations, suivez le lien MSDN fourni ci-dessous.
Le XML contient des entrées, où chaque entrée est une table. La table a un ID et une liste de propriétés qui inclut le nom de la table.
Création d'une table
Pour créer une table, appelez simplement :
Success := FTableService.CreateTable('tablename');
CreateTable renvoie True si l'opération a réussi, False sinon. Le nom choisi pour une table doit suivre ces conventions de nommage :
- Doit être en minuscules
- Doit contenir seulement des caractères alphanumériques
- Ne doit pas commencer par un caractère numérique
- Doit avoir une longueur comprise entre 3 et 63
Suppression d'une table
Pour supprimer une table, utilisez le code suivant :
Success := FTableService.DeleteTable(FTableName);
Notez que la suppression sur le serveur peut prendre quelques instants. Même si la table semble disparue, si vous essayez de créer une nouvelle table avec le nom de la table supprimée, la création peut échouer. Si ceci se produit, choisissez un autre nom, ou patientez un moment et réessayez.
Listage des lignes d'une table
Pour obtenir les lignes (entités) d'une table, exécutez l'instruction suivante :
xml := FTableService.QueryEntities(FTableName, BuildFilterString);
Le XML renvoyé devrait ressembler à ceci :
<feed ...>
...
<entry ...>
<id>http://myaccount.tables.core.windows.net/Customers(PartitionKey='SomePKey',RowKey='SomeRKey')</id>
...
<content type="application/xml">
<m:properties>
<d:PartitionKey>SomePKey</d:PartitionKey>
<d:RowKey>SomeRKey</d:RowKey>
<d:Timestamp m:type="Edm.DateTime">2008-10-01T15:26:04.6812774Z</d:Timestamp>
<d:Address>221 Avenue Road, Hollywood CA 90027</d:Address>
<d:SomeNumber m:type="Edm.Int32">27</d:SomeNumber>
</m:properties>
</content>
</entry>
</feed>
Pour obtenir un exemple complet du XML renvoyé ainsi que toutes les informations qu'il contient, suivez la référence MSDN fournie ci-dessous.
Chaque ligne est représentée sous la forme d'une entrée dans le XML, et a son propre ID unique. A l'intérieur du noeud contenu se trouvent les propriétés qui représentent les colonnes de la table. Chaque colonne a un nom (la balise) et une valeur, mais peut aussi avoir un type. Ce type est l'un des types de données supportés (voir les types de données supportés dans le document MSDN référencé ci-dessous).
Ajout d'une ligne à une table
Pour créer une ligne sur une table existante, vous devez d'abord créer un objet TJSONObject (en utilisant l'unité DBXJSON) qui représente la ligne, avec toutes ses colonnes (à l'exception de timestamp). Si vous utilisez une notation JSON, l'objet devrait ressembler à l'un d'eux :
{"RowKey":"row1","PartitionKey":"Imported","AnyKeyName":"Hello World!"}
{"RowKey":"row2","PartitionKey":"Imported","OtherValue":["true","Edm.Boolean"]}
L'objet doit contenir un RowKey et un PartitionKey, puis toute autre paire colonne / valeur voulue. Si vous ne spécifiez pas un type de données pour la colonne, String sera pris par défaut. Pour spécifier un type de données pour la valeur de la colonne, définissez-la sur TJSONArray, où le premier élément du tableau est la représentation chaîne de la valeur de colonne (cellule), et le second élément du tableau est le type de données de la colonne. Notez que vous ne pouvez plus changer la valeur de PartitionKey ou de RowKey dès que vous avez créé la ligne.
Dès que l'objet TJSONObject est créé, appelez ce code (où RowObj est l'instance de TJSONObject que vous avez créée) :
xml := FTableService.InsertEntity('tablename', RowObj);
Ceci renvoie la représentation XML de la ligne que vous venez d'ajouter, et est au même format que lors de la demande de toutes les lignes de la table, sauf que l'élément de niveau supérieur est l'entrée, puisque le XML représente seulement cette ligne.
Modification d'une ligne existante
Si vous voulez modifier une ligne existante, vous créez l'objet TJSONObject de la même façon qu'une nouvelle ligne, mais remplissez RowKey et PartitionKey de façon appropriée. Au lieu d'appeler InsertEntry, vous appelez UpdateEntry (avec les mêmes paramètres). Ceci renvoie True ou False, selon la réussite ou l'échec de la mise à jour. Une mise à jour échouera, par exemple, si un type de données sélectionné pour une colonne n'est pas valide pour la valeur stockée dans la colonne.
Suppression d'une ligne
Pour supprimer une ligne d'une table existante, appelez :
Success := FTableService.DeleteEntity('tablename', PartitionKey, RowKey);
Vous devez seulement connaître la clé de partition et la clé de ligne relatives à la ligne que vous souhaitez supprimer, ainsi que le nom de la table dans laquelle se trouve la ligne. True est renvoyé si la suppression a réussi.