Microsoft Azure Blob API

Aus RAD Studio
Wechseln zu: Navigation, Suche

Warnung: Die DSAzure-API ist veraltet und wurde durch die Data.Cloud.AzureAPI ersetzt. Es wird empfohlen, die neue API für die Entwicklung von Cloud-Computing-Anwendungen zu verwenden. Weitere Informationen finden Sie unter Cloud-Computing mit DataSnap.

Die Microsoft Azure Blob API befindet sich in der Unit Data.Cloud.AzureAPI in der Klasse Data.Cloud.AzureAPI.TAzureBlobService.

Zu den verfügbaren Hauptfunktionen zählen:

  • Ermitteln einer Container-Liste
  • Erstellen und Löschen eines Containers
  • Erstellen eines Block-Blobs
  • Erstellen eines Seiten-Blobs
  • Ändern des Inhalts eines Blobs
  • Kopieren eines Blobs
  • Löschen eines Blobs
  • Erstellen einer Momentaufnahme
  • Belegen eines Blobs mit einem Leasing, Erneuern, Abbrechen oder Auflösen des Leasings
  • Ermitteln der Eigenschaften und Metadaten eines Blobs oder eines Containers

Die folgenden Anweisungen setzen voraus, dass Sie bereits eine Instanz von TAzureBlobService erstellt haben. In den Codefragmenten wird diese Instanz mit FBlobService bezeichnet. Darüber hinaus wird vorausgesetzt, dass Sie über einen XML-Parser verfügen und dass dieser bereits entsprechend konfiguriert ist. Die API gibt in einigen Fällen XML-Code zurück. Sie müssen in der Lage sein, XML-Code zu analysieren.

Container-Aktionen

Container verfügen über Eigenschaften und Metadaten und können Eigentümer von Blobs sein. Im Folgenden finden Sie eine Übersicht über die mit einem Container verfügbaren Aktionen.

Erstellen eines Stamm-Containers

Mithilfe eines Stamm-Containers können Sie kürzere Container-Adressen ohne Container-Namen bereitstellen. Mit dem folgenden Code erstellen Sie einen Stamm-Container:


Success := FBlobService.CreateRootContainer(Access);

Access ist der Wert, der in dem Header "x-ms-blob-public-access" verwendet werden soll. Abhängig davon, ob oder wie Sie die Informationen öffentlich zugänglich machen wollen, kann dies ein leerer String, container oder blob sein. Wird Access weggelassen, wird der Vorgabewert blob verwendet. Alternativ können Sie einen Stamm-Container auch folgendermaßen erstellen:


Success := FBlobService.CreateContainer('$root', MetaData, Access);

MetaData ist ein TStringList-Objekt mit optionalen Metadaten für den Stamm-Container. Sie können den Parameter MetaData weglassen, da es eine überladene Funktion gibt, die ihn unterdrückt.

Nach dem Erstellen eines Stamm-Containers können Sie mit diesem genauso wie mit anderen Containern arbeiten.

Erstellen eines Containers

Zum Erstellen eines normalen Containers können Sie denselben Code wie zum Erstellen eines Stamm-Containers (das obige Beispiel, in dem CreateContainer mit Übergabe des Namens aufgerufen wird) verwenden, außer dass ein anderer Name als $root angegeben werden muss.

Für den Container-Namen gelten die folgende Namenskonventionen:

  • Der Name muss zwischen 3 und 65 Zeichen lang sein.
  • Es sind nur alphanumerische Zeichen und der Bindestrich zulässig.
  • Der Name darf nicht mit einem Bindestrich beginnen.
  • Es sind nur Kleinbuchstaben zulässig.

Löschen eines Containers

Rufen Sie zum Löschen eines Stamm-Containers Folgendes auf:


Success := FBlobService.DeleteRootContainer;

Rufen Sie zum Löschen eines anderen Containers Folgendes auf:


Success := FBlobService.DeleteContainer('container-name');

Hierbei übergeben Sie den Namen des Containers. Beide Funktionen geben True zurück, wenn das Löschen erfolgreich war, andernfalls False.

Ermitteln einer Liste aller Container

Verwenden Sie zum Ermitteln einer Liste aller verfügbaren Container den folgenden Code:


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

Die Parameter sind zwei Arrays:

  • Ein Array mit Parametern, die mit der Anforderung an die Cloud übergeben werden sollen.
  • Ein Array mit Werten für das erste Array.

Diese beiden Arrays müssen dieselbe Länge haben, da ein Eintrag im ersten Array direkt dem Eintrag mit demselben Index des anderen Arrays zugeordnet wird. Im obigen Code wird der Parameter include mit dem Wert "metadata" übergeben, was bedeutet, dass die Metadaten jedes Containers in den zurückgegebenen XML-Code aufgenommen werden sollen. Dieser Aufruf kann auch ohne Parameter erfolgen, dann werden keine Metadaten zurückgegeben. In diesen Arrays können Sie einen weiteren Parameter, nämlich maxresults, angeben. Damit begrenzen Sie die Anzahl der Container, die von dieser Abfrage zurückgegeben werden.

Der zurückgegebene XML-Code sieht folgendermaßen aus:


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

Ein vollständiges Beispiel mit dem zurückgegebenen XML-Code finden Sie über den Link zur MSDN-Dokumentation im Abschnitt "Siehe auch".

Der obige XML-Code enthält ein Containers-Element, das alle Container-Einträge beinhaltet. Jeder Container hat einen Namen, einen URL, Eigenschaften und Metadaten (wenn Sie die Metadaten gefüllt haben).

Ermitteln der Eigenschaften eines Containers

Aus dem obigen XML-Code können Sie entnehmen, dass jedem Container Eigenschaften zugeordnet sind. Diese Eigenschaften können beim Abrufen der Liste aller Container gefüllt werden, aber Sie können die Eigenschaften auch unabhängig davon mit dem folgenden Code neu füllen:


Success := FBlobService.GetContainerProperties('container-name');
Props := TStringList.Create;
if Success then
  FBlobService.PopulateContainerProperties(Props);

Mit dem obigen Code wird ein TStringList-Objekt mit den Schlüssel/Wert-Eigenschaftspaaren gefüllt, vorausgesetzt die erste Anforderung war erfolgreich.

Ermitteln der Metadaten eines Containers

Aus dem obigen XML-Code ist auch ersichtlich, dass beim Abrufen der Container-Liste (durch Setzen der Eigenschaft "include" auf "metadata") eine Sammlung von Schlüssel/Wert-Metadatenpaaren zurückgegeben wird. Der Knotenname (im obigen Beispiel metadata-name) ist der tatsächliche Metadatenschlüssel. Der Wert ist der zu dem Metadatenschlüssel gehörende Wert.

Sie können auch nur die Metadaten für einen bestimmten Container ermitteln. Verwenden Sie dazu den folgenden Code:


Success := FBlobService.GetContainerMetadata('container-name');
Meta := TStringList.Create;
if Success then
  FBlobService.PopulateContainer('x-ms-meta-', Meta);

Der erste Aufruf von GetContainerMetadata gibt bei Erfolg True zurück. PopulateContainer füllt dann mit den Daten aus dem vorherigen Aufruf das angegebene TStringList-Objekt mit den Schlüssel/Wert-Metadatenpaaren. Die Metadaten werden in dem Header der Antwort vom Server zurückgegeben, und jedem Metadatenschlüssel wird x-ms-meta- vorangestellt. Der Rest des Schlüsselnamens ist der eigentliche Name des Metadatenschlüssels. Die Prozedur PopulateContainer kann ein beliebiges Präfix übernehmen und ein TStringList-Objekt auf der Basis von Headern füllen, die mit diesem angegebenen String als Präfix die Header-Schlüssel/Wertepaare herausfiltern, die der Liste hinzugefügt werden.

Ändern von Metadaten eines Containers

Zum Ändern der für einen Container gespeicherten Metadaten können Sie zunächst mit dem obigen Code ein TStringList-Objekt abrufen, das mit den neuesten Metadaten gefüllt ist, dann diesem TStringList-Objekt neue Metadaten-Schlüssel/Wertepaare hinzufügen und/oder vorhandene Paare ändern oder löschen. Mit dem folgenden Code können Sie diese Änderungen in die Cloud zurückschreiben:


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

Meta ist hier das TStringList-Objekt mit den Schlüssel/Wertepaaren, die Sie zurückschreiben möchten. Wenn die Aktualisierung erfolgreich war, wird True, ansonsten False zurückgegeben. Beachten Sie bitte, dass Sie für den Stamm-Container "$root" als Name angeben müssen.

Hinweis: Sie können auch Seiten-Blobs und Block-Blobs zum Speichern in Containern erstellen. Diese werden in den Abschnitten Aktionen für Seiten-Blobs und Aktionen für Block-Blobs behandelt.

Hinweis: Die Eigenschaften eines Containers können nicht geändert werden.

Allgemeine Blob-Aktionen

Die folgenden Aktionen stehen für Seiten-Blobs und Block-Blobs zur Verfügung. Block-Blobs sind für das Streaming und Seiten-Blobs für direkte Lese-/Schreibvorgänge optimiert.


Löschen eines Blobs

Mit dem folgenden Code können Sie ein Blob löschen:


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

DeleteBlob hat die folgenden drei optionalen Parameter: Snapshot, LeaseId und DeleteSnapshots. DeleteSnapshots kann entweder leer gelassen (nur wenn das Blob keine zugeordneten Momentaufnahmen hat) oder auf include oder only gesetzt werden. Bei include wird das Blob und alle Momentaufnahmen gelöscht, bei only werden nur die Momentaufnahmen des Blobs, nicht aber das Blob selbst gelöscht.

Sie können für Snapshot einen Wert angeben, wenn Sie eine bestimmte Momentaufnahme des Blobs löschen möchten. Wenn das Blob mit einem Leasing belegt wurde, das noch nicht abgelaufen ist, müssen Sie eine LeaseId angeben, um das Blob erfolgreich zu löschen.

Kopieren eines Blobs

Sie können ein Blob in einen beliebigen Container auf demselben Speicherkonto wie das zu kopierende Blob kopieren. Wenn Sie das Blob in denselben Container wie die Quelle kopieren, dann müssen Sie selbstverständlich einen anderen Namen für das Ziel-Blob angeben.

Zum Kopieren eines Blobs können Sie den folgenden Code verwenden:


Success := FBlobService.CopyBlob('destination-container', 'destination-blob-name', 'source-container', 'source-blob-name');

Für das Kopieren können Sie auch Folgendes angeben: eine bestimmte Momentaufnahme des Blobs, einen Datums-/Zeitwert zur Überprüfung des letzten Änderungsdatums des Quell-Blobs, sodass nur kopiert wird, wenn das Blob seit diesem Datum geändert wurde, ein "Nicht-Änderungsdatum", wobei nur kopiert wird, wenn das Quell-Blob seit diesem Datum nicht geändert wurde, und mehrere andere optionale Parameter. Eine Übersicht aller optionalen Parameter finden Sie in der Dokumentation zu TAzureBlobService oder im Code in der Unit DSAzure. Bitte beachten Sie auch, dass einer dieser optionalen Parameter LeaseId ist, der für das Ziel-Blob für den Fall gilt, dass bereits eines vorhanden ist, und es mit einem Leasing belegt ist.

Erstellen einer Momentaufnahme

Mit dem folgenden Code können Sie eine Momentaufnahme des Blobs erstellen:


snapshot := FBlobService.SnapshotBlob('container-name', 'blob-name');

SnapshotBlob übernimmt weitere optionale Parameter (in dieser Reihenfolge): IfModifiedSince, IfUnmodifiedSince, IfMatch, IfNoneMatch, LeaseId, MetaHeaders.

Wenn Sie eine XML-Repräsentation des vollständigen Blobs, einschließlich aller Momentaufnahmen-Informationen, abrufen möchten, können Sie diesen modifizierten Aufruf von ListBlobs verwenden:


xml := FBlobService.ListBlobs('container-name', ['prefix', 'include', 'include'], ['blob-name', 'metadata', 'snapshots']);

Sie müssen container-name und blob-name durch die tatsächlichen Werte ersetzen.

Arbeiten mit Leasings

Alle Blobs können Sie mit Leasings belegen, Leasings dafür erneuern, Leasings auflösen und Leasings abbrechen. Wenn ein Blob erfolgreich mit einem Leasing belegt wurde, haben Sie eine Minute lang einen exklusiven Schreibzugriff auf dieses Blob und auf dessen Eigenschaften/Metadaten. Vor Ablauf der Minute können Sie das Leasing auflösen, wenn Sie es nicht mehr benötigen, oder das Leasing erneuern, wenn Sie es weitere 60 Sekunden benötigen. Das Leasing kann kontinuierlich erneuert werden, bis jemand das Leasing für dieses Blob abbricht. Wird der Abbruch eines Leasings angefordert, wird der Ablauf der aktuellen Minute abgewartet, danach kann aber keine weitere Erneuerung des Leasings für diese Leasing-ID ausgeführt werden.

Belegen eines Blobs mit einem Leasing

Um ein Blob mit einem Leasing zu belegen, können Sie den folgenden Code verwenden:


LeaseId := FBlobService.LeaseBlob('container-name', 'blob-name');

Mit der zurückgegebenen Leasing-ID können Sie ein Leasing ändern, erneuern und auflösen, da all diese Aktionen über den "optionalen" Parameter LeaseID verfügen, der zu einem erforderlichen Parameter wird, wenn das Blob mit einem Leasing belegt ist.

Erneuern eines Leasings

Verwenden Sie zum Erneuern eines Leasings den folgenden Code:


FBlobService.LeaseBlob('container-name', 'blob-name', 'renew', LeaseId);

Dieser Aufruf entspricht dem Aufruf beim ersten Erstellen des Leasings, hat aber zwei zusätzliche Parameter. Der erste Parameter gibt an, dass es sich bei dem Aktionstyp um Erneuern handelt, und der zweite Parameter ist die LeaseId, die Sie beim Belegen des Blobs mit dem Leasing erhalten haben. Wenn dieser Aufruf erfolgreich ausgeführt werden konnte, erhalten Sie weitere 60 Sekunden geschützten Schreibzugriff auf das Blob und seine Daten.

Abbrechen eines Leasings

Um ein Leasing abzubrechen, mit dem jemand anderes das Blob belegt hat, (oder Sie selbst, wenn Sie aus irgendwelchen Gründen das Leasing nicht einfach auflösen möchten), können Sie den folgenden Code verwenden:


FBlobService.LeaseBlob('container-name', 'blob-name', 'break');
duration := StrToInt(FBlobService.ResponseHeader['x-ms-lease-time']);

Damit wird das Leasing abgebrochen, und das Blob verbleibt nach Ablauf der in duration angegebenen Sekunden in einem ungesperrten Zustand.

Auflösen eines Leasings

Wenn Sie ein Blob mit einem Leasing belegt haben, dann können Sie das Leasing auflösen, bevor es abläuft. Verwenden Sie dazu den folgenden Code:


FBlobService.LeaseBlob('container-name', 'blob-name', 'release', LeaseId);

Damit wird das Leasing für das angegebene Blob aufgelöst, vorausgesetzt die LeaseId ist korrekt.

Herunterladen des Blob-Inhalts

Mit dem folgenden Code können Sie den Inhalt des Blobs herunterladen:


stream := TFileStream.Create(location, fmCreate);
Success := FBlobService.GetBlob('container-name', 'blob-name', stream); 

Sie können einen weiteren vierten Parameter der herunterzuladenden Blob-Momentaufnahme angeben. Wenn der GetBlob-Aufruf False zurückgibt, können Sie die vom Server zurückgegebene Nachricht mit FBlobService.ResponseText ermitteln.

Ermitteln der Blob-Eigenschaften

Das Ermitteln der Eigenschaften eines Blobs entspricht dem Ermitteln der Eigenschaften eines Containers. Die Code sieht folgendermaßen aus:


Success := FBlobService.GetBlobProperties('container-name', 'blob-name');
Props := TStringList.Create;
if Success then
  FBlobService.PopulateContainerProperties(Props);

Der Aufruf GetBlobProperties kann einen optionalen dritten Parameter enthalten, der eine Momentaufnahme (nicht das Blob selbst) angibt, dessen Eigenschaften ermittelt werden sollen. Der Aufruf von GetBlobProperties gibt bei Erfolg True zurück. Sie können dann mit PopulateContainerProperties die eigentlichen Eigenschaften füllen.

Ermitteln der Blob-Metadaten

Das Füllen der Metadaten für ein Blob entspricht ebenfalls derselben Aktion für einen Container. Verwenden Sie dazu den folgenden Code:


Success := FBlobService.GetBlobMetadata('container-name', 'blob-name');
Meta := TStringList.Create;
if Success then
  FBlobService.PopulateContainer('x-ms-meta-', Meta);

GetBlobMetadata verfügt über eine optionale dritte Option (Snapshot). Damit ermitteln Sie die Metadaten der Momentaufnahme anstatt der des Blobs.

Festlegen der Blob-Eigenschaften

Mit dem folgenden Code können Sie die Systemeigenschaften für ein Blob festlegen:


Success := FBlobService.SetBlobProperties('container-name', 'blob-name', cache, contentType, encoding, language, md5, LeaseId);

Alle Eigenschaften – außer der ersten beiden – sind optional, und alle Eigenschaften sind Strings. (LeaseId muss angegeben werden, wenn das Blob mit einem Leasing belegt ist, und darf nicht angegeben werden, wenn das Blob kein aktives Leasing hat.)

Ändern der Blob-Metadaten

Das Ändern der für ein Blob gespeicherten Metadaten entspricht ebenfalls weitgehend derselben Aktion wie für einen Container. Hier ist ein Beispiel des Codes:


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

Der Parameter Meta entspricht den Schlüssel/Wertepaaren der Metadaten. Es gibt einen optionalen vierten Parameter, die LeaseId. Dieser Parameter muss angegeben werden, wenn das Blob mit einem aktiven Leasing belegt ist.

Aktionen für Block-Blobs

Die folgenden Aktionen sind für Block-Blobs spezifisch:

  • Erstellen eines Block-Blobs

Zum Erstellen eines neuen Block-Blobs können Sie den folgenden Code verwenden:


Success := FBlobService.PutBlockBlob('container-name', 'blob-name', ContentBytes);

ContentBytes ist eine TBytes-Instanz, die als Blob-Inhalt verwendet wird. Folgende optionale Parameter (in dieser Reihenfolge) sind für PutBlobBlob möglich: LeaseId, UserHeaders, ContentType, ContentEncoding, ContentLanguage, ContentMD5. Informationen über diese optionalen Parameter finden Sie über den Link zur MSDN-Dokumentation am Ende dieses Themas. Beachten Sie bitte, dass application/octet-stream als Inhaltstyp verwendet wird, wenn kein anderer Typ angegeben ist.

  • Aktualisieren des Block-Blob-Inhalts

Nach dem Erstellen eines Block-Blobs können Sie dessen Werte ändern. Verwenden Sie dazu genau denselben Code wie für das Erstellen des Blobs. In diesem Fall wird LeaseId zu einem wichtigen Parameter, weil Sie keine LeaseId für ein Blob benötigen, das noch nicht erstellt wurde.

Aktionen für Seiten-Blobs

Die folgende Aktion ist für Seiten-Blobs spezifisch:

  • Erstellen eines Seiten-Blobs

Zum Erstellen eines neuen Seiten-Blobs können Sie Data.Cloud.AzureAPI.TAzureBlobService.PutPageBlob wie im folgenden Code verwenden:


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

Zu den optionalen Parametern zählen (in dieser Reihenfolge): ContainerName, BlobName, MaximumSize, LeaseID, OptionalHeaders, MetaData, ResponseInfo. In der MSDN-Dokumentation (siehe den Link am Ende dieses Themas) finden Sie Erläuterungen zu diesen optionalen Parametern. Beachten Sie bitte, dass application/octet-stream als Inhaltstyp verwendet wird, wenn kein anderer Typ angegeben ist.

Siehe auch