repo_zf1/documentation/manual/de/module_specs/Zend_Service_WindowsAzure_Blob.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- EN-Revision: 19991 -->
<!-- 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> API angeboten welcher von
        der Klasse <classname>Zend_Service_WindowsAzure_Storage_Blob</classname> umhüllt ist um ein
        natives PHP 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 API 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">
                <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">
                <title>Löschen eines Speicher Containers</title>

                <programlisting role="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">
                <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">
                <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">
                <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>
                By default, blob storage containers on Windows Azure are protected from public
                viewing. If any user on the Internet should have access to a blob container, its ACL
                can be set to public. Note that this applies to a complete container and not to a
                single blob!
            </para>

            <para>
                Using the following code, blob storage container ACL can be set on development
                storage. Note that the container has already been created before.
            </para>

            <example id="zend.service.windowsazure.storage.blob.api.public-blob">
                <title>Making a blob publicly available</title>

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

// make container publicly available
$storageClient->setContainerAcl('testcontainer', Zend_Service_WindowsAzure_Storage_Blob::ACL_PUBLIC);
]]></programlisting>
            </example>
        </sect3>
    </sect2>

    <sect2 id="zend.service.windowsazure.storage.blob.root">
        <title>Root container</title>

        <para>
            Windows Azure Blob Storage provides support to work with a "root container".
            This means that a blob can be stored in the root of your storage account,
            i.e. <code>http://myaccount.blob.core.windows.net/somefile.txt</code>.
        </para>

        <para>
            In order to work with the root container, it should first be created using the
            <methodname>createContainer()</methodname> method, naming the container
            <varname>$root</varname>.  All other operations on the root container should be issued
            with the container name set to <varname>$root</varname>.
        </para>
    </sect2>

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

        <para>
            The Windows Azure SDK for PHP provides support for registering a blob storage
            client as a PHP file stream wrapper. The blob storage stream wrapper provides
            support for using regular file operations on Windows Azure Blob Storage.
            For example, one can open a file from Windows Azure Blob Storage with
            the <functionname>fopen()</functionname> function:
        </para>

        <example id="zend.service.windowsazure.storage.blob.wrapper.sample">
            <title>Example usage of blob storage stream wrapper</title>

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

// ...

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

        <para>
            In order to do this, the Windows Azure SDK for PHP blob storage client
            must be registered as a stream wrapper. This can be done by calling the
            <methodname>registerStreamWrapper()</methodname> method:
        </para>

        <example id="zend.service.windowsazure.storage.blob.wrapper.register">
            <title>Registering the blob storage stream wrapper</title>

            <programlisting language="php"><![CDATA[
$storageClient = new Zend_Service_WindowsAzure_Storage_Blob();
$storageClient->registerStreamWrapper(); // registers azure:// on this storage client

// or:

$storageClient->registerStreamWrapper('blob://'); // regiters blob:// on this storage client
]]></programlisting>
        </example>

        <para>
            To unregister the stream wrapper, the <methodname>unregisterStreamWrapper()</methodname>
            method can be used.
        </para>
    </sect2>

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

        <para>
            Windows Azure Bob Storage provides a feature called "Shared Access Signatures". By
            default, there is only one level of authorization possible in Windows Azure Blob
            Storage: either a container is private or it is public. Shared Access Signatures provide
            a more granular method of authorization: read, write, delete and list permissions can be
            assigned on a container or a blob and given to a specific client using an URL-based
            model.
        </para>

        <para>
            An example would be the following signature:
        </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>
            The above signature gives write access to the "phpazuretestshared1"
            container of the "phpstorage" account.
        </para>

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

            <para>
                When you are the owner of a Windows Azure Bob Storage account, you can create and
                distribute a shared access key for any type of resource in your account. To do this,
                the <methodname>generateSharedAccessUrl()</methodname> method of the
                <classname>Zend_Service_WindowsAzure_Storage_Blob</classname> storage client can be
                used.
            </para>

            <para>
                The following example code will generate a Shared Access Signature for write access
                in a container named "container1", within a timeframe of 3000 seconds.
            </para>

            <example id="zend.service.windowsazure.storage.blob.sharedaccesssig.generate-2">
                <title>Generating a Shared Access Signature for a 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>
                The following example code will generate a Shared Access Signature for read access
                in a blob named <filename>test.txt</filename> in a container named "container1"
                within a time frame of 3000 seconds.
            </para>

            <example id="zend.service.windowsazure.storage.blob.sharedaccesssig-generate-3">
                <title>Generating a Shared Access Signature for a 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>Working with Shared Access Signatures from others</title>

            <para>
                When you receive a Shared Access Signature from someone else, you can use the
                Windows Azure SDK for PHP to work with the addressed resource.  For example, the
                following signature can be retrieved from the owner of a storage account:
            </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>
                The above signature gives write access to the "phpazuretestshared1" "container" of
                the phpstorage account. Since the shared key for the account is not known, the
                Shared Access Signature can be used to work with the authorized resource.
            </para>

            <example id="zend.service.windowsazure.storage.blob.sharedaccesssig.consuming">
                <title>Consuming a Shared Access Signature for a 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>
                Note that there was no explicit permission to write to a specific blob. Instead, the
                Windows Azure SDK for PHP determined that a permission was required to either write
                to that specific blob, or to write to its container. Since only a signature was
                available for the latter, the Windows Azure SDK for PHP chose those credentials to
                perform the request on Windows Azure blob storage.
            </para>
        </sect3>
    </sect2>
</sect1>