<?xml version="1.0" encoding="UTF-8"?>
<!-- EN-Revision: 24249 -->
<!-- Reviewed: no -->
<sect1 id="zend.service.windowsazure.storage.blob">
    <title>Zend_Service_WindowsAzure_Storage_Blob</title>

    <para>
        Blob Speicher speichert ein Set von Binären Daten. Blog Speicher bietet die folgenden drei
        Ressourcen an: den Speicher Account, Container und Blobs. Im eigenen Speicher Account bieten
        Container einen Weg um Sets von Blobs im Speicher Account zu organisieren.
    </para>

    <para>
        Blog Speicher wird von Windows Azure als <acronym>REST</acronym> <acronym>API</acronym>
        angeboten welcher von der Klasse
        <classname>Zend_Service_WindowsAzure_Storage_Blob</classname> umhüllt ist um ein natives
        <acronym>PHP</acronym> Interface zum Speicher Account zu bieten.
    </para>

    <sect2 id="zend.service.windowsazure.storage.blob.api">
        <title>API Beispiele</title>

        <para>
            Dieser Abschnitt zeigt einige Beispiele der Verwendung der Klasse
            <classname>Zend_Service_WindowsAzure_Storage_Blob</classname>. Andere Features sind im
            Download Paket vorhanden sowie in der detailierten <acronym>API</acronym> Dokumentation
            dieser Features.
        </para>

        <sect3 id="zend.service.windowsazure.storage.blob.api.create-container">
            <title>Erstellung einer Speicher Containers</title>

            <para>
                Bei Verwendung des folgenden Codes kann ein Speicher Container auf dem Development
                Speicher erstellt werden.
            </para>

            <example id="zend.service.windowsazure.storage.blob.api.create-container.example">
                <title>Erstellung eines Speicher Containers</title>

                <programlisting language="php"><![CDATA[
$storageClient = new Zend_Service_WindowsAzure_Storage_Blob();
$result = $storageClient->createContainer('testcontainer');

echo 'Der Name des Containers ist: ' . $result->Name;
]]></programlisting>
            </example>
        </sect3>

        <sect3 id="zend.service.windowsazure.storage.blob.api.delete-container">
            <title>Löschen eines Speicher Containers</title>

            <para>
                Bei Verwendung des folgenden Codes kann ein Blob Speicher Container vom Development
                Speicher entfernt werden.
            </para>

            <example id="zend.service.windowsazure.storage.blob.api.delete-container.example">
                <title>Löschen eines Speicher Containers</title>

                <programlisting language="php"><![CDATA[
$storageClient = new Zend_Service_WindowsAzure_Storage_Blob();
$storageClient->deleteContainer('testcontainer');
]]></programlisting>
            </example>
        </sect3>

        <sect3 id="zend.service.windowsazure.storage.blob.api.storing-blob">
            <title>Speichern eines Blobs</title>

            <para>
                Bei Verwendung des folgenden Codes kann ein Blob zu einem Blog Speicher Container
                auf dem Development Speichers hochgeladen werden. Es ist zu beachten das der
                Container hierfür bereits vorher erstellt worden sein muss.
            </para>

            <example id="zend.service.windowsazure.storage.blob.api.storing-blob.example">
                <title>Speichern eines Blobs</title>

                <programlisting language="php"><![CDATA[
$storageClient = new Zend_Service_WindowsAzure_Storage_Blob();

// /home/maarten/example.txt auf Azure hochladen
$result = $storageClient->putBlob(
    'testcontainer', 'example.txt', '/home/maarten/example.txt'
);

echo 'Der Name des Blobs ist: ' . $result->Name;
]]></programlisting>
            </example>
        </sect3>

        <sect3 id="zend.service.windowsazure.storage.blob.api.copy-blob">
            <title>Kopieren eines Blobs</title>

            <para>
                Bei Verwendung des folgenden Codes kann ein Blob von innerhalb des Speicher Accounts
                kopiert werden. Der Vorteil der Verwendung dieser Methode besteht darin das die
                Kopieroperation in der Azure Wolke stattfindet und kein Downloaden vom Blob
                stattfinden muss. Es ist zu beachten das in diesem Fall der Container bereits vorher
                erstellt worden sein muss.
            </para>

            <example id="zend.service.windowsazure.storage.blob.api.copy-blob.example">
                <title>Kopieren eines Blobs</title>

                <programlisting language="php"><![CDATA[
$storageClient = new Zend_Service_WindowsAzure_Storage_Blob();

// Kopiert example.txt auf example2.txt
$result = $storageClient->copyBlob(
    'testcontainer', 'example.txt', 'testcontainer', 'example2.txt'
);

echo 'Der Name des kopierten Blobs ist: ' . $result->Name;
]]></programlisting>
            </example>
        </sect3>

        <sect3 id="zend.service.windowsazure.storage.blob.api.download-blob">
            <title>Herunterladen eines Blobs</title>

            <para>
                Bei Verwendung des folgenden Codes kann ein Blob von einem Blob Speicher Container
                auf den Development Speicher heruntergeladen werden. Es ist zu beachten das der
                Container hierfür bereits vorher erstellt wurden sein und ein Blob darauf
                hochgeladen sein muss.
            </para>

            <example id="zend.service.windowsazure.storage.blob.api.download-blob.example">
                <title>Herunterladen eines Blobs</title>

                <programlisting language="php"><![CDATA[
$storageClient = new Zend_Service_WindowsAzure_Storage_Blob();

// Lädt die Datei /home/maarten/example.txt herunter
$storageClient->getBlob(
    'testcontainer', 'example.txt', '/home/maarten/example.txt'
);
]]></programlisting>
            </example>
        </sect3>

        <sect3 id="zend.service.windowsazure.storage.blob.api.public-blob">
            <title>Einen Blob öffentlich verfügbar machen</title>

            <para>
                Standardmäßig sind Blob Speicher Container in Windows Azure geschützt vor
                öffentlichem Zugriff. Wenn ein Benutzer im Internet Zugriff auf einen Blob Container
                haben soll, kann seine ACL auf öffentlich (public) gesetzt werden. Es ist zu
                beachten dass das auf den kompletten Container angewendet wird, und nicht auf einen
                einzelnen Blob!
            </para>

            <para>
                Bei Verwendung des folgenden Codes kann die ACL eines Blob Speicher Containers auf
                den Development Speicher gesetzt werden. Es ist zu beachten das der Container
                hierfür bereits vorher erstellt worden sein muss.
            </para>

            <example id="zend.service.windowsazure.storage.blob.api.public-blob.example">
                <title>Einen Blob öffentlich zugänglich machen</title>

                <programlisting language="php"><![CDATA[
$storageClient = new Zend_Service_WindowsAzure_Storage_Blob();

// Den Container öffentlich zugänglich machen
// (alle Blobs durchgehen und Blob Daten lesen)
$storageClient->setContainerAcl(
    'testcontainer',
    Zend_Service_WindowsAzure_Storage_Blob::ACL_PUBLIC_CONTAINER
);
]]></programlisting>
            </example>
        </sect3>
    </sect2>

    <sect2 id="zend.service.windowsazure.storage.blob.root">
        <title>Stamm Container</title>

        <para>
            Der Windows Azure Blob Speicher bietet Unterstützung für die Arbeit mit einem "Stamm
            Container" (root). Das bedeutet das ein Blob im Stamm des Speicher Containers
            gespeichert werden kann, z.B.
            <filename>http://myaccount.blob.core.windows.net/somefile.txt</filename>.
        </para>

        <para>
            Um mit dem Stamm Container zu arbieten sollte er zuerst durch Verwendung der
            <methodname>createContainer()</methodname> Methode erstellt worden sein, und der
            Container sollte <varname>$root</varname> heißen. Alle anderen Operationen auf dem
            Stamm Container sollten ausgeführt werden indem der Containernamen auf
            <varname>$root</varname> gesetzt wird.
        </para>
    </sect2>

    <sect2 id="zend.service.windowsazure.storage.blob.wrapper">
        <title>Blob Speicher Stream Wrapper</title>

        <para>
            Die Windows Azure <acronym>SDK</acronym> für <acronym>PHP</acronym> bietet Unterstützung
            für die Registrierung eines Blob Speicher Clients als <acronym>PHP</acronym> File Stream
            Wrapper. Der Blob Speicher Stream Wrapper bietet Unterstützung für die Verwendung von
            regulären Datei Operationen auf dem Windows Azure Blob Speicher. Zum Beispiel kann eine
            Datei vom Windows Azure Blob Speicher aus mit der Funktion
            <methodname>fopen()</methodname> geöffnet werden:
        </para>

        <example id="zend.service.windowsazure.storage.blob.wrapper.sample">
            <title>Beispiel der Verwendung des Blob Speicher Stream Wrappers</title>

            <programlisting language="php"><![CDATA[
$fileHandle = fopen('azure://mycontainer/myfile.txt', 'r');

// ...

fclose($fileHandle);
]]></programlisting>
        </example>

        <para>
            Um das zu tun muss die Windows Azure <acronym>SDK</acronym> für den
            <acronym>PHP</acronym> Blob Speicher Client als Stream Wrapper registriert werden. Das
            kann getan werden indem die Methode <methodname>registerStreamWrapper()</methodname>
            aufgerufen wird:
        </para>

        <example id="zend.service.windowsazure.storage.blob.wrapper.register">
            <title>Den Blob Speicher Stream Wrapper registrieren</title>

            <programlisting language="php"><![CDATA[
$storageClient = new Zend_Service_WindowsAzure_Storage_Blob();
// registriert azure:// auf diesem Speicher Client
$storageClient->registerStreamWrapper();

// oder:

// registriert blob:// auf diesem Speicher Client
$storageClient->registerStreamWrapper('blob://');
]]></programlisting>
        </example>

        <para>
            Um den Stream Wrapper zu deregistrieren kann die Methode
            <methodname>unregisterStreamWrapper()</methodname> verwendet werden.
        </para>
    </sect2>

    <sect2 id="zend.service.windowsazure.storage.blob.sharedaccesssig">
        <title>Shared Access Signaturen</title>

        <para>
            Der Windows Azure Bolb Speicher bietet ein Feature welches "Shared Access Signatures"
            genannt wird. Standardmäßig gibt es nur ein Level der Authorosierung welche in Windows
            Azure Blob Speicher möglich ist: entweder ist ein Container privat oder er ist
            öffentlich. Shared Access Signaturen bieten eine feinere Methode der Authorisierung:
            Lese-, Schreib-, Lösch- und Anzeigerechte können auf einem Container oder einem Blob
            für einen speziellen Client zugeordnet werden indem ein URL-basierendes Modell verwendet
            wird.
        </para>

        <para>
            Ein Beispiel würde die folgende Signatur sein:
        </para>

        <literallayout>
http://phpstorage.blob.core.windows.net/phpazuretestshared1?st=2009-08-17T09%3A06%3A17Z&amp;se=2009-08-17T09%3A56%3A17Z&amp;sr=c&amp;sp=w&amp;sig=hscQ7Su1nqd91OfMTwTkxabhJSaspx%2BD%2Fz8UqZAgn9s%3D
        </literallayout>

        <para>
            Die obige Signatur gibt Schreibrechte auf den Container "phpazuretestshared1" des
            Accounts "phpstorage".
        </para>

        <sect3 id="zend.service.windowsazure.storage.blob.sharedaccesssig.generate">
            <title>Erstellen einer Shared Access Signature</title>

            <para>
                Wenn man Eigentümer eines Windows Azure Blob Speicher Accounts ist kann man einen
                geteilten Zugriffsschlüssel für jeden Typ einer Ressource im eigenen Account
                erstellen und teilen. Um das zu tun kann die Methode
                <methodname>generateSharedAccessUrl()</methodname> des
                <classname>Zend_Service_WindowsAzure_Storage_Blob</classname> Speicher Clients
                verwendet werden.
            </para>

            <para>
                Der folgende Beispielcode erzeugt eine Shared Access Signatur für den
                Schreibzugriff in einem Container der "container1" heißt, in einem Zeitrahmen von
                3000 Sekunden.
            </para>

            <example id="zend.service.windowsazure.storage.blob.sharedaccesssig.generate-2">
                <title>Erstellung einer Shared Access Signatur für einen Container</title>

                <programlisting language="php"><![CDATA[
$storageClient   = new Zend_Service_WindowsAzure_Storage_Blob();
$sharedAccessUrl = $storageClient->generateSharedAccessUrl(
    'container1',
    '',
    'c',
    'w',
    $storageClient ->isoDate(time() - 500),
    $storageClient ->isoDate(time() + 3000)
);
]]></programlisting>
            </example>

            <para>
                Der folgende Beispielcode erzeugt eine Shared Access Signatur für den Lesezugriff in
                einem Blob der <filename>test.txt</filename> heißt und einem Container der
                "container1" heißt, in einem Zeitrahmen von 3000 Sekunden.
            </para>

            <example id="zend.service.windowsazure.storage.blob.sharedaccesssig-generate-3">
                <title>Erzeugen einer Shared Access Signatur für einen Blob</title>

                <programlisting language="php"><![CDATA[
$storageClient   = new Zend_Service_WindowsAzure_Storage_Blob();
$sharedAccessUrl = $storageClient->generateSharedAccessUrl(
    'container1',
    'test.txt',
    'b',
    'r',
    $storageClient ->isoDate(time() - 500),
    $storageClient ->isoDate(time() + 3000)
);
]]></programlisting>
            </example>
        </sect3>

        <sect3 id="zend.service.windowsazure.storage.blob.sharedaccesssig.consume">
            <title>Arbeiten mit Shared Access Signaturen von anderen</title>

            <para>
                Wenn  man eine Shared Access Signatur von jemandem anderen erhält kann man die
                Windows Azure <acronym>SDK</acronym> für <acronym>PHP</acronym> verwenden um mit der
                adressierten Ressource zu arbeiten. Zum Beispiel kann man die folgende Signatur vom
                Eigentümer eines Speicher Accounts erhalten:
            </para>

            <literallayout>
http://phpstorage.blob.core.windows.net/phpazuretestshared1?st=2009-08-17T09%3A06%3A17Z&amp;se=2009-08-17T09%3A56%3A17Z&amp;sr=c&amp;sp=w&amp;sig=hscQ7Su1nqd91OfMTwTkxabhJSaspx%2BD%2Fz8UqZAgn9s%3D
            </literallayout>

            <para>
                Die obige Signatur gibt Schreibzugriff auf "phpazuretestshared1" "container" des
                PhpSpeicher Accounts. Da der geteilte Schlüssel für den Account nicht bekannt ist,
                kann die Shared Access Signatur verwendet werden um mit der authorisierten Ressource
                zu arbeiten.
            </para>

            <example id="zend.service.windowsazure.storage.blob.sharedaccesssig.consuming">
                <title>Verwenden einer Shared Access Signatur für einen Container</title>

                <programlisting language="php"><![CDATA[
$storageClient = new Zend_Service_WindowsAzure_Storage_Blob(
    'blob.core.windows.net', 'phpstorage', ''
);
$storageClient->setCredentials(
    new Zend_Service_WindowsAzure_Credentials_SharedAccessSignature()
);
$storageClient->getCredentials()->setPermissionSet(array(
    'http://phpstorage.blob.core.windows.net/phpazuretestshared1?st=2009-08-17T09%3A06%3A17Z&se=2009-08-17T09%3A56%3A17Z&sr=c&sp=w&sig=hscQ7Su1nqd91OfMTwTkxabhJSaspx%2BD%2Fz8UqZAgn9s%3D'
));
$storageClient->putBlob(
    'phpazuretestshared1', 'NewBlob.txt', 'C:\Files\dataforazure.txt'
);
]]></programlisting>
            </example>

            <para>
                Es ist zu beachten das es keine explizite Erlaubnis für das Schreiben eines
                spezifischen Blobs gab. Stattdessen hat die Windows Azure <acronym>SDK</acronym> für
                <acronym>PHP</acronym> festgestellt das eine Erlaubnis benötigt wurde um entweder an
                den spezifischen Blob zu schreiben, oder an seinen Container zu schreiben. Da nur
                eine Signatur für das letztere vorhanden war, hat die Windows Azure
                <acronym>SDK</acronym> für <acronym>PHP</acronym> diese Zugriffsrechte ausgewählt um
                die Anfrage auf den Windows Azure Blob Speicher durchzuführen.
            </para>
        </sect3>
    </sect2>
</sect1>
