API des blobs Windows Azure
Remonter à Environnement Azure et Cloud avec DataSnap
L'API des blobs Windows Azure est située dans l'unité DSAzure, dans la classe DSAzure.TAzureBlobService. Pour obtenir un exemple de l'api utilisée, consultez la section implementation de l'unité DSAzureBlob. Il s'agit du composant visuel qui utilise l'API.
Les fonctions disponibles sont les suivantes :
- L'obtention de la liste des conteneurs
- La création et la suppression d'un conteneur
- La création d'un blob de blocs
- La création d'un blob de pages
- La modification du contenu d'un blob
- La copie d'un blob
- La suppression d'un blob
- La création d'un instantané
- L'acquisition, le renouvellement, la rupture ou la libération d'un bail sur un blob
- L'obtention des propriétés et des métadonnées d'un blob ou d'un conteneur
Les instructions suivantes supposent que vous avez déjà créé une instance de TAzureBlobService. Dans les extraits de code, cette instance est référencée sous FBlobService. 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 comment analyser.
Actions d'un conteneur
Les conteneurs ont des propriétés et des métadonnées, et ils peuvent posséder des blobs. Ce qui suit est un résumé des actions disponibles avec un conteneur.
Création d'un conteneur racine
Un conteneur racine vous permet de fournir une adresse de conteneur qui est plus courte, étant donné que le nom du conteneur n'y est pas inclus. Vous pouvez créer un conteneur racine avec le code suivant :
Success := FBlobService.CreateRootContainer(Access);
Où Access est la valeur à utiliser dans l'en-tête 'x-ms-blob-public-access', qui peut être une chaîne vide, un conteneur ou un blob, selon la façon dont vous voulez que les informations soient accessibles publiquement, ou si elles ne doivent pas l'être. Si Access n'est pas définie, la valeur par défaut du blob est utilisée. Vous pouvez aussi créer un conteneur racine comme suit :
Success := FBlobService.CreateContainer('$root', MetaData, Access);
Où MetaData est une liste TStringList de métadonnées facultatives pour le conteneur racine. Vous pouvez omettre le paramètre MetaData, étant donné qu'il existe une fonction surchargée qui l'omet.
Dès qu'un conteneur racine est créé, vous pouvez travailler avec celui-ci, comme vous le faites avec n'importe quel conteneur.
Création d'un conteneur
Pour créer un conteneur normal, utilisez le code relatif à la création d'un conteneur racine (l'exemple ci-dessus utilisant l'appel à CreateContainer, avec un nom en paramètre), en spécifiant un nom de conteneur au lieu de $root. Le nom doit suivre ces conventions de nommage :
- Doit avoir une longueur comprise entre 3 et 65
- Caractères alphanumériques et traits d'union seulement
- Ne doit pas commencer par un trait d'union
- Minuscules
Suppression d'un conteneur
Pour supprimer le conteneur racine, appelez :
Success := FBlobService.DeleteRootContainer;
Pour supprimer un autre conteneur, appelez :
Success := FBlobService.DeleteContainer('container-name');
Où vous passez le nom réel du conteneur. Ces deux fonctions renvoient true si la suppression a réussi, false sinon.
Obtention d'une liste de conteneurs
Pour obtenir la liste des conteneurs disponibles, utilisez le code suivant :
xmlStr := ListContainers(['include'], ['metadata']);
Les paramètres pris sont deux tableaux, où le premier est un tableau de paramètres à passer avec la requête adressée au cloud, et le second tableau contient les valeurs du premier tableau. Ces tableaux doivent être de même longueur, du fait qu'un élément du premier tableau est mappé directement sur l'élément de même index de l'autre tableau. Dans le code ci-dessus, le passage s'effectue dans le paramètre include avec la valeur "metadata" qui indique d'inclure chaque métadonnée de conteneur dans le XML renvoyé. Si aucun paramètre n'est spécifié dans l'appel, aucune métadonnée n'est renvoyée. Vous pouvez spécifier un autre paramètre dans ces tableaux, maxresults, qui vous permet de limiter le nombre de conteneurs à renvoyer depuis cette requête.
Le XML renvoyé devrait ressembler à ceci :
<?xml version="1.0" encoding="utf-8"?>
<EnumerationResults ...>
...
<Containers>
<Container>
<Name>container-name</Name>
<URL>container-address</URL>
<Properties>
<Last-Modified>date/time-value</Last-Modified>
<Etag>etag</Etag>
</Properties>
<Metadata>
<metadata-name>value</metadata-name>
</Metadata>
</Container>
</Containers>
...
</EnumerationResults>
Pour obtenir un exemple complet du XML renvoyé, suivez le lien de la documentation MSDN dans la section Voir aussi.
Dans le XML ci-dessus, l'élément Containers contient tous les éléments Container. Chaque conteneur a un nom, une url, des propriétés et des métadonnées (si vous avez choisi de remplir les métadonnées).
Obtention des propriétés d'un conteneur
Vous pouvez voir dans le XML ci-dessus que des propriétés sont associées à chaque conteneur. Ces propriétés peuvent être remplies lors de la récupération de la liste de tous les conteneurs, mais vous pouvez aussi les remplir de façon indépendante. Pour ce faire, utilisez le code suivant :
Success := FBlobService.GetContainerProperties('container-name');
Props := TStringList.Create;
if Success then
FBlobService.PopulateContainerProperties(Props);
Avec le code ci-dessus, vous obtenez maintenant une liste TStringList remplie par des paires de propriétés clé / valeur, à condition que la requête initiale se soit déroulée avec succès.
Obtention des métadonnées d'un conteneur
Vous pouvez aussi voir dans le XML ci-dessus, que lorsque vous récupérez la liste des conteneurs (en définissant la propriété 'include' sur 'metadata'), vous obtenez une collection de paires de métadonnées clé / valeur. Le nom du noeud (qui dans l'exemple ci-dessus est metadata-name) serait la clé de métadonnée réelle. La valeur serait, contrairement à toute attente, la valeur correspondante de la clé de métadonnée.
Vous pouvez aussi obtenir les métadonnées par elles-mêmes pour un conteneur spécifique. Pour ce faire, utilisez le code suivant :
Success := FBlobService.GetContainerMetadata('container-name');
Meta := TStringList.Create;
if Success then
FBlobService.PopulateContainer('x-ms-meta-', Meta);
L'appel initial à GetContainerMetadata renvoie True si l'appel a réussi. PopulateContainer utilise ensuite les données collectées depuis l'appel précédent pour remplir la liste TStringList donnée avec les paires clé / valeur de métadonnées. Les métadonnées sont renvoyées dans l'en-tête de la réponse depuis le serveur, et chaque clé de métadonnée est préfixée avec x-ms-meta-. Le reste du nom de la clé est le nom de la clé de métadonnée réelle. La procédure PopulateContainer peut prendre n'importe quel préfixe et remplir une liste TStringList basée sur les en-têtes en utilisant cette chaîne spécifiée en tant que préfixe pour filtrer les paires clé / valeur d'en-tête qui sont ajoutés à la liste.
Modification des métadonnées d'un conteneur
Pour modifier les métadonnées stockées sur un conteneur, vous pouvez utiliser d'abord le code ci-dessus pour obtenir une liste TStringList remplie par les dernières métadonnées, puis modifier cette liste TStringList pour ajouter de nouvelles paires clé / valeur de métadonnée et / ou modifier / supprimer des paires existantes. Vous pouvez ensuite utiliser le code suivant pour valider ces modifications sur le cloud :
Success := FBlobService.SetContainerMetadata('container-name', Meta);
Où Meta est la liste TStringList avec les paires clé / valeur que vous souhaitez valider. True est renvoyé si la mise à jour a réussi, False sinon. Notez que pour le conteneur racine, vous devez spécifier '$root' pour le nom.
Remarque : Vous pouvez aussi créer des blobs de pages et des blobs de blocs à stocker dans les conteneurs. Ces sujets seront traités plus loin dans ce document, sous les sections #Actions sur les blobs de pages et #Actions sur les blobs de blocs.
Remarque : Vous ne pouvez pas modifier les propriétés d'un conteneur.
Actions générales sur les blobs
Les actions suivantes sont disponibles sur les blobs de pages et les blobs de blocs. Les blobs de blocs sont optimisés pour les opérations sur les flux, tandis que les blobs de pages sont optimisés pour les opérations de lecture / écriture aléatoire.
Suppression d'un blob
Vous pouvez supprimer un blob avec le code suivant :
Success := FBlobService.DeleteBlob('container-name', 'blob-name');
DeleteBlob a aussi les trois paramètres facultatifs suivants : Snapshot, LeaseId et DeleteSnapshots. Le paramètre DeleteSnapshots peut être laissé vide (seulement si aucun instantané n'est associé au blob), défini sur include ou sur only S'il est défini sur include, le blob et tous les instantanés seront supprimés, s'il est défini sur only, seuls les instantanés du blob seront supprimés, mais pas le blob lui-même.
Vous pouvez spécifier une valeur pour Snapshot si vous voulez seulement supprimer un instantané spécifique du blob. Vous devez spécifier le paramètre LeaseId pour supprimer avec succès le blob si un bail a été acquis et n'a pas encore expiré.
Copie d'un blob
Vous pouvez copier un blob dans un conteneur dans le même compte de stockage que le blob en cours de copie. Si vous effectuez la copie dans le même conteneur que la source, vous devrez bien sûr spécifier un nom différent pour le blob cible.
Pour copier un blob, vous pouvez utiliser le code suivant :
Success := FBlobService.CopyBlob('destination-container', 'destination-blob-name', 'source-container', 'source-blob-name');
Vous pouvez aussi spécifier un instantané spécifique du blob à copier, une valeur date-heure utilisée pour vérifier la date de la dernière modification par rapport au blob source de façon que la copie soit seulement effectuée si le blob a été modifié depuis cette date, une date de 'non modification' où la copie se produit seulement si le blob source n'a pas été modifié depuis cette date, et plusieurs autres paramètres facultatifs. Voir la documentation sur TAzureBlobService, ou visualisez le code de l'unité DSAzure pour voir tous les paramètres facultatifs. Notez aussi le paramètre facultatif LeaseId, applicable au blob cible, au cas ou un blob existe déjà et qu'il a fait l'objet d'une acquisition de bail.
Création d'un instantané
Vous pouvez créer un instantané d'un blob avec le code suivant :
snapshot := FBlobService.SnapshotBlob('container-name', 'blob-name');
SnapshotBlob prend les paramètres facultatifs supplémentaires suivants (dans cet ordre) : IfModifiedSince, IfUnmodifiedSince, IfMatch, IfNoneMatch, LeaseId, MetaHeaders.
Si vous voulez obtenir une représentation XML du blob complet, notamment des informations d'instantané, utilisez cet appel modifié à ListBlobs :
xml := FBlobService.ListBlobs('container-name', ['prefix', 'include', 'include'], ['blob-name', 'metadata', 'snapshots']);
Où vous remplacez 'container-name' et 'blob-name' par leurs valeurs réelles.
Utilisation des baux
Avec tous les blobs, vous pouvez acquérir, renouveler, libérer et rompre des baux. Quand vous avez acquis avec succès un bail sur un blob, vous obtenez un accès en écriture exclusif sur ce blob et ses propriétés / métadonnées pour une minute. Avant que la minute ne se termine, vous pouvez choisir de libérer le bail si vous n'en avez plus besoin, ou de le renouveler si vous avez besoin de 60 secondes supplémentaires. Vous pouvez sans cesse renouveler le bail jusqu'à ce que quelqu'un choisisse de rompre le bail sur le blob. Quand une rupture de bail est demandée, il est possible de terminer la minute en cours, mais aucun autre renouvellement de bail pour cet ID de bail ne peut s'effectuer.
Acquisition d'un bail
Pour acquérir un bail sur un blob, utilisez le code suivant :
LeaseId := FBlobService.LeaseBlob('container-name', 'blob-name');
Avec l'ID de bail renvoyé, vous pourrez modifier, renouveler et libérer un bail, étant donné que toutes ces actions ont un paramètre 'facultatif' LeaseID qui devient un paramètre obligatoire quand le blob est libéré.
Renouvellement d'un bail
Pour renouveler un bail, utilisez le code suivant :
FBlobService.LeaseBlob('container-name', 'blob-name', 'renew', LeaseId);
C'est un appel similaire à la création initiale du bail, mais avec deux paramètres supplémentaires. Le premier paramètre indique que le type d'action est un renouvellement et que le second paramètre est l'ID du bail que vous avez obtenu lors de l'acquisition du bail. En cas de réussite, vous obtiendrez un accès en écriture protégée de 60 secondes supplémentaires sur le blob et ses données.
Rupture d'un bail
Pour rompre un bail acquis par un autre utilisateur (ou vous-même, si pour une quelconque raison, vous ne voulez pas seulement libérer le bail), vous pouvez utiliser le code suivant :
FBlobService.LeaseBlob('container-name', 'blob-name', 'break');
duration := StrToInt(FBlobService.ResponseHeader['x-ms-lease-time']);
Ce code rompt le bail, en laissant le blob dans un état non verrouillé après le nombre de secondes spécifié par duration.
Libération d'un bail
Si vous avez acquis un bail sur un blob, vous pouvez alors choisir de le libérer avant l'expiration du bail. Pour ce faire, utilisez le code suivant :
FBlobService.LeaseBlob('container-name', 'blob-name', 'release', LeaseId);
Ce code libère le bail sur le blob spécifié, à condition que l'ID de bail soit correct.
Téléchargement du contenu d'un blob
Vous pouvez télécharger le contenu d'un blob avec le code suivant :
stream := TFileStream.Create(location, fmCreate);
Success := FBlobService.GetBlob('container-name', 'blob-name', stream);
Vous pouvez aussi spécifier un quatrième paramètre facultatif concernant l'instantané de blob à télécharger. Notez que si l'appel à GetBlob renvoie false, vous pouvez obtenir le message renvoyé par le serveur dans FBlobService.ResponseText.
Obtention des propriétés d'un blob
Vous pouvez obtenir les propriétés d'un blob de la même façon que celles d'un conteneur. Le code est semblable à celui-ci :
Success := FBlobService.GetBlobProperties('container-name', 'blob-name');
Props := TStringList.Create;
if Success then
FBlobService.PopulateContainerProperties(Props);
L'appel à GetBlobProperties peut prendre un troisième paramètre facultatif, qui spécifie un instantané afin d'obtenir les propriétés de l'instantané au lieu des propriétés du blob lui-même. L'appel à GetBlobProperties renvoie True en cas de succès. Vous pouvez ensuite appeler PopulateContainerProperties pour remplir les propriétés réelles.
Obtention des métadonnées d'un blob
Le remplissage des métadonnées pour un blob est aussi similaire à la même action effectuée sur un conteneur. Vous pouvez accomplir cette action avec le code suivant :
Success := FBlobService.GetBlobMetadata('container-name', 'blob-name');
Meta := TStringList.Create;
if Success then
FBlobService.PopulateContainer('x-ms-meta-', Meta);
GetBlobMetadata a aussi la troisième option facultative, qui spécifie un instantané afin d'obtenir les métadonnées de l'instantané au lieu des propriétés du blob lui-même.
Définition des propriétés d'un blob
Vous pouvez définir les propriétés système d'un blob avec le code suivant :
Success := FBlobService.SetBlobProperties('container-name', 'blob-name', cache, contentType, encoding, language, md5, LeaseId);
Toutes les propriétés sont facultatives à l'exception des deux premières, et ce sont toutes des chaînes. LeaseId doit être spécifié si un bail a été acquis sur le blob, et ne doit pas être spécifié si le blob n'a pas de bail actif.
Modification des métadonnées d'un blob
Pour modifier les métadonnées stockées sur un blob, la procédure à suivre est similaire à la même action effectuée pour un conteneur. Voici un exemple de code :
Success := FBlobService.SetBlobMetadata('container-name', 'blob-name', Meta);
Le paramètre Meta doit contenir les paires clé / valeur de métadonnées. LeaseId est le quatrième paramètre facultatif. Il doit être spécifié en présence d'un bail acquis et actif sur le blob.
Actions sur les blobs de blocs
Les actions suivantes sont spécifiques aux blobs de blocs.
- Création d'un blob de blocs
Pour créer un nouveau blob de blocs, utilisez le code suivant :
Success := FBlobService.PutBlockBlob('container-name', 'blob-name', ContentBytes);
Où ContentBytes est une instance de TBytes qui sera utilisée en tant que contenu du blob. Les paramètres facultatifs de PutBlockBlob sont dans l'ordre : LeaseId, UserHeaders, ContentType, ContentEncoding, ContentLanguage, ContentMD5. Vous trouverez des informations sur ces paramètres facultatifs en suivant le lien de la documentation MSDN ci-dessous. Notez que application/octet-stream est utilisé en tant que type de contenu, si aucun n'est spécifié.
- Mise à jour du contenu d'un blob de blocs
Dès qu'un blob de blocs a été créé, vous pouvez modifier ses valeurs. Pour ce faire, utilisez le même code que celui utilisé pour la création du blob. LeaseId devient un paramètre utile dans ce cas, étant donné que vous n'aviez pas besoin d'un ID de bail pour un blob qui n'avait pas encore été créé.
Actions sur les blobs de pages
L'action suivante est spécifique aux blobs de pages.
- Création d'un blob de pages
Pour créer un nouveau blob de pages, utilisez le code suivant :
Success := FBlobService.PutPageBlob('container-name', 'blob-name', BlobSize);
Les paramètres facultatifs sont dans l'ordre : BlobSeqNb, UserHeaders, ContentType, ContentEncoding, ContentLanguage, ContentMD5, CacheControl. Pour mieux comprendre ces paramètres facultatifs, suivez le lien de la documentation MSDN ci-dessous. Notez que application/octet-stream est utilisé en tant que type de contenu, si aucun n'est spécifié.