API des blobs Microsoft Azure

Remonter à Environnement Azure et Cloud avec DataSnap

Remonter à Environnement 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 blobs Microsoft Azure est située dans l'unité Data.Cloud.AzureAPI, dans la classe Data.Cloud.AzureAPI.TAzureBlobService.

Les fonctions disponibles principales sont les suivantes :

• Obtention d'une liste de conteneurs
• Création d'un conteneur, suppression d'un conteneur
• Création d'un blob de blocs
• Création d'un blob de pages
• Modification du contenu d'un blob
• Copie d'un blob
• Suppression d'un blob
• Création d'un instantané
• Acquisition, renouvellement, rupture ou libération d'un bail sur un blob
• 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 comme 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 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 autre conteneur.

Création d'un conteneur

Pour créer un conteneur normal, utilisez le code de 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 conteneur doit suivre ces conventions de nommage :

• Longueur comprise entre 3 et 65 caractères
• Caractères alphanumériques et traits d'union seulement
• Ne pas commencer par un trait d'union
• Minuscules seulement

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 de la liste de tous les conteneurs

Pour obtenir la liste de tous les conteneurs disponibles, utilisez le code suivant :

xmlStr := ListContainers(['include'], ['metadata']);

Les paramètres sont deux tableaux :

• Un tableau de paramètres à transmettre avec la requête au cloud.
• Un tableau des valeurs du premier tableau.

Ces deux tableaux doivent être de même longueur, étant donné qu'un élément du premier tableau correspond directement à l'élément de même index de l'autre tableau. Dans le code ci-dessus, la transmission 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é ressemble à 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é, voir 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 également les remplir de façon indépendante en utilisant 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 également 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 (metadata-name dans l'exemple ci-dessus) est la clé de métadonnée réelle. La valeur est, 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ées à la liste.

Modification des métadonnées sur 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 blobs sont décrits dans #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. DeleteSnapshots peut être laissé vide (seulement si aucun instantané n'est associé au blob), ou défini sur include ou only. S'il est défini sur include, le blob et tous les instantanés sont supprimés, s'il est défini sur only, seuls les instantanés du blob sont 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 un 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 devez 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 où 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 pouvez 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);

Cet appel est similaire à l'appel utilisé lors de 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 (LeaseId) 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 (LeaseId) 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 depuis FBlobService.ResponseText.

Obtention des propriétés d'un blob

L'obtention des propriétés d'un blob est similaire à l'obtention des propriétés d'un conteneur. Le code ressemble à ceci :

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 d'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

La modification des métadonnées stockées sur un blob est assez similaire à la modification des métadonnées d'un conteneur. Voici un exemple de code :

Success := FBlobService.SetBlobMetadata('container-name', 'blob-name', Meta);

Le paramètre Meta représente 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 dans la documentation MSDN ci-dessous. Notez que application/octet-stream est utilisé en tant que type de contenu, si rien n'est spécifié.

• Mise à jour du contenu d'un blob de blocs

Dès qu'un blob de blocs est 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'avez pas besoin d'un ID de bail (LeaseId) pour un blob qui n'a pas é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 Data.Cloud.AzureAPI.TAzureBlobService.PutPageBlob comme dans le code suivant :

Success := FBlobService.PutPageBlob('container-name', 'blob-name', BlobSize);

Les paramètres facultatifs sont dans l'ordre : ContainerName, BlobName, MaximumSize, LeaseID, OptionalHeaders, MetaData, ResponseInfo. Pour mieux comprendre ces paramètres facultatifs, voir la documentation MSDN ci-dessous. Notez que application/octet-stream est utilisé en tant que type de contenu, si rien n'est spécifié.

Voir aussi

• TAzureBlobManagement
• API REST du service BLOB (MSDN)
• Data.Cloud