repo_zf1Php7/documentation/manual/de/module_specs/Zend_Service_Amazon_S3.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- EN-Revision: 15617 -->
<!-- Reviewed: no -->
<sect1 id="zend.service.amazon.s3">
    <title>Zend_Service_Amazon_S3</title>

    <sect2 id="zend.service.amazon.s3.introduction">
        <title>Einführung</title>

        <para>
            Amazon S3 bietet ein einfaches Webservice Interface das verwendet werden kann um
            beliebige Mengen an Daten, jederzeit und von überall her aus dem Web, zu Speichern und
            erhalten. Es gibt Entwicklern den Zugriff auf die gleiche, hoch skalierbare,
            verfügbare, schnelle und kostengünstige Datenspeicher Infrastruktur die Amazon
            verwendet um sein eigenes globales Netzwerk an Websites zu betreiben. Der Service
            zielt darauf ab den Nutzen der Skalierbarkeit zu erhöhen und diese Vorteile an
            Entwickler weiterzugeben.
        </para>
    </sect2>

    <sect2 id="zend.service.amazon.s3.registering">
        <title>Registrierung mit Amazon S3</title>

        <para>
            Bevor man mit <classname>Zend_Service_Amazon_S3</classname> beginnen kann, muß man einen
            Account registrieren. Sehen Sie bitte auf die Amazon Website
            <ulink url="http://aws.amazon.com/s3/faqs/">S3 FAQ</ulink> für weitere Informationen.
        </para>

        <para>
            Nach der Registrierung erhält man einen Anwendungsschlüssel und einen geheimen
            Schlüssel. Man benötigt beide um auf den S3 Service zugreifen zu können.
        </para>
    </sect2>

    <sect2 id="zend.service.amazon.s3.apiDocumentation">
        <title>API Dokumentation</title>

        <para>
            Die Klasse <classname>Zend_Service_Amazon_S3</classname> bietet einen PHP Wrapper zum
            Amazon S3 REST Interface. Schauen Sie bitte in die <ulink
                url="http://developer.amazonwebservices.com/connect/kbcategory.jspa?categoryID=48">Amazon
                S3 Dokumentation</ulink> für eine detailierte Beschreibung des Services. Man muß mit
            dem grundsätzlichen Konzept vertraut sein um dieses Service nutzen zu können.
        </para>

    </sect2>

    <sect2 id="zend.service.amazon.s3.features">
        <title>Features</title>

        <para>
            <classname>Zend_Service_Amazon_S3</classname> bietet die folgenden Funktionalitäten:

            <itemizedlist>
                <listitem>
                    <para>
                        Einen einzelnen Punkt für die Konfiguration der eigenen amazon.s3
                        Zugangsdaten der über dem kompletten amazon.s3 Namespace verwendet werden
                        kann.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        Ein Proxy Objekt das bequemer zu verwenden ist als ein HTTP Client alleine,
                        da er hauptsächlich die Notwendigkeit eliminiert manuell eine HTTP POST
                        Anfrage über den REST Service zu erstellen.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        Ein Antwort-Wrapper der jede Antwort erhebt und eine Exception wirft wenn
                        ein Fehler aufgetreten ist, was die Notwendigkeit eliminiert den Erfolg
                        vieler Kommandos wiederholt zu prüfen.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        Zusätzliche bequeme Methoden für einige der üblicheren Operationen.
                    </para>
                </listitem>
            </itemizedlist>
        </para>
    </sect2>

    <sect2 id="zend.service.amazon.s3.storing-your-first">
        <title>Beginnen wir</title>

        <para>
            Sobald man sich mit Amazon S3 registriert hat, ist man bereit sein erstes Objekt auf
            S3 zu speichern. Die Objekte werden auf S3 in Containern gespeichert, die "Buckets"
            genannt werden. Der Name der Buckets ist auf S3 eindeutig, und jeder Benutzer kann
            nicht mehr als 100 Buckets simultan besitzen. Jeder Bucket kann eine unlimitierte
            Anzahl an Objekten enthalten, die durch den Namen identifiziert werden.
        </para>

        <para>
            Das folgende Beispiel demonstriert die Erstellung eines Buckets, und das Speichern und
            Empfangen von Daten.
        </para>

        <example id="zend.service.amazon.s3.storing-your-first.example">
            <title>Beispiel der Verwendung von Zend_Service_Amazon_S3</title>
             <programlisting language="php"><![CDATA[
require_once 'Zend/Service/Amazon/S3.php';

$s3 = new Zend_Service_Amazon_S3($my_aws_key, $my_aws_secret_key);

$s3->createBucket("my-own-bucket");

$s3->putObject("my-own-bucket/myobject", "somedata");

echo $s3->getObject("my-own-bucket/myobject");
]]></programlisting>
        </example>

        <para>
            Da der <classname>Zend_Service_Amazon_S3</classname> Service eine Authentifizierung
            benötigt, sollte man seine Zugangsdaten (AWS Schlüssel und Geheimschlüssel) an den
            Konstruktor übergeben.

            Wenn man nur einen Account verwendet, kann man Standard-Zugangsdaten für das Service
            setzen:
        </para>

        <programlisting language="php"><![CDATA[
require_once 'Zend/Service/Amazon/S3.php';

Zend_Service_Amazon_S3::setKeys($my_aws_key, $my_aws_secret_key);
$s3 = new Zend_Service_Amazon_S3();
]]></programlisting>
    </sect2>

    <sect2 id="zend.service.amazon.s3.buckets">
        <title>Bucket Operationen</title>

        <para>
            Alle Objekte im S3 System werden in Buckets gespeichert. Buckets müssen erstellt werden
            bevor Speicheroperationen durchgeführt werden. Der Name des Buckets ist im System
            eindeutig, so das man den Bucket nicht so benennen kann wie den Bucket einer anderen
            Person.
        </para>

        <para>
            Namen von Buckets können Kleinbuchstaben, Ziffern, Punkte (.), Unterstriche (_), und
            Bindestriche (-) enthalten. Es sind keine anderen Symbole erlaubt. Bucketnamen sollten
            mit einem Buchstaben oder einer Ziffer beginnen, und 3 bis 255 Zeichen lang sein.
            Namen die wie eine IP Adresse aussehen (z.B. "192.168.16.255") sind nicht erlaubt.
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    <code>createBucket()</code> erstellt einen neuen Bucket.
                </para>
            </listitem>

            <listitem>
                <para>
                    <code>cleanBucket()</code> entfernt alle Objekte die in einem Bucket enthalten
                    sind.
                </para>
            </listitem>

            <listitem>
                <para>
                    <code>removeBucket()</code> entfernt den Bucket vom System. Der Bucket sollte
                    leer sein damit er entfernt werden kann.
                </para>

                <example id="zend.service.amazon.s3.buckets.remove.example">
                    <title>
                        Beispiel für das Entfernen eines Buckets in Zend_Service_Amazon_S3
                    </title>
                    <programlisting language="php"><![CDATA[
require_once 'Zend/Service/Amazon/S3.php';

$s3 = new Zend_Service_Amazon_S3($my_aws_key, $my_aws_secret_key);

$s3->cleanBucket("my-own-bucket");
$s3->removeBucket("my-own-bucket");
]]></programlisting>
                </example>
            </listitem>

            <listitem>
                <para>
                    <code>getBuckets()</code> gibt eine Liste der Namen aller Buckets zurück die
                    einem Benutzer gehören.
                </para>

                <example id="zend.service.amazon.s3.buckets.list.example">
                    <title>Beispiel für das Auflisten der Buckets in Zend_Service_Amazon_S3</title>
                    <programlisting language="php"><![CDATA[
require_once 'Zend/Service/Amazon/S3.php';

$s3 = new Zend_Service_Amazon_S3($my_aws_key, $my_aws_secret_key);

$list = $s3->getBuckets();
foreach($list as $bucket) {
  echo "Ich habe das Bucket $bucket\n";
}
]]></programlisting>
                </example>
            </listitem>

            <listitem>
                <para>
                    <code>isBucketAvailable()</code> prüft ob das Bucket existiert und gibt
                    true zurück wenn das der Fall ist.
                </para>
            </listitem>
        </itemizedlist>
    </sect2>

    <sect2 id="zend.service.amazon.s3.objects">
        <title>Operationen am Objekt</title>

        <para>
            Das Objekte ist die grundsätzliche Speichereinheit in S3. Objekte speichern nicht
            strukturierte Daten, welche jede Größe, bis zu 4 Gigabyte, haben können. Es gibt kein
            Limit in der Anzahl der Objekte die auf dem System gespeichert werden können.
        </para>

        <para>
            Objekte werden in Buckets abgelegt. Sie werden durch den Namen identifiziert, der
            jeder UTF-8 String sein kann. Es ist üblich hierarchische Namen zu verwenden (wie z.B.
            <code>Pictures/Myself/CodingInPHP.jpg</code> um Objektnamen zu organisieren.
            Objektnamen wird der Bucketname vorangestellt wenn Objektfunktionen verwendet werden,
            so dass das Objekt "mydata" im Bucket "my-own-bucket" den Namen
            <code>my-own-bucket/mydata</code> haben würde.
        </para>

        <para>
            Objekte können ersetzt (durch Überschreiben neuer Daten mit dem gleichen Schlüssel)
            oder gelöscht werden, aber nicht geändert, angefügt, usw. Objekte werden immer als
            Ganzes gespeichert.
        </para>

        <para>
            Standardmäßig sind alle Objekte privat und es kann nur durch Ihren Besitzer auf Sie
            zugegriffen werden. Trotzdem ist es möglich Objekte mit öffentlichem Zugriff zu
            spezifizieren, wodurch man auf Sie mit der folgenden URL zugreifen kann:
            <code>http://s3.amazonaws.com/[bucket-name]/[object-name]</code>.
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    <code>putObject($object, $data, $meta)</code> erstellt ein Objekt mit dem Namen
                    <code>$object</code> (Sollte den Bucketnamen als Präfix enthalten!) das
                    <code>$data</code> als seinen Inhalt besitzt.
                </para>

                <para>
                    Der optionale <code>$meta</code> Parameter ist das Array von Metadaten,
                    welches aktuell die folgenden Schlüssel enthalten kann:
                </para>

                <variablelist>
                    <varlistentry>
                        <term><code>S3_CONTENT_TYPE_HEADER</code></term>
                        <listitem>
                            <para>
                                MIME Content Type der Daten. Wenn nicht angegeben, wird der Typ
                                anhand der Dateiextension des Objektnamens geschätzt.
                            </para>
                        </listitem>
                    </varlistentry>

                    <varlistentry>
                        <term><code>S3_ACL_HEADER</code></term>
                        <listitem>
                            <para>
                                Der Zugriff auf das Element. Folgende Zugriffskonstanten können
                                verwendet werden:

                                <variablelist>
                                    <varlistentry>
                                        <term><code>S3_ACL_PRIVATE</code></term>
                                        <listitem>
                                            <para>
                                                Nur der Besitzer hat auf das Element Zugriff.
                                            </para>
                                        </listitem>
                                    </varlistentry>

                                    <varlistentry>
                                        <term><code>S3_ACL_PUBLIC_READ</code></term>
                                        <listitem>
                                            <para>
                                                Jeder kann das Objekt lesen, aber nur der Besitzer
                                                kann schreiben. Diese Eigenschaft kann verwendet
                                                werden um öffentlich zugängliche Inhalte zu
                                                speichern.
                                            </para>
                                        </listitem>
                                    </varlistentry>

                                    <varlistentry>
                                        <term><code>S3_ACL_PUBLIC_WRITE</code></term>
                                        <listitem>
                                            <para>
                                                Jeder kann das Objekt schreiben oder lesen. Diese
                                                Eigenschaft sollte sehr spärlich verwendet werden.
                                            </para>
                                        </listitem>
                                    </varlistentry>

                                    <varlistentry>
                                        <term><code>S3_ACL_AUTH_READ</code></term>
                                        <listitem>
                                            <para>
                                                Nur der Besitzer hat Schreibzugriff auf das
                                                Element, und andere authentifizierte S3 Benutzer
                                                haben Leserechte. Das ist nützlich um Daten
                                                zwischen S3 Accounts zu teilen ohne Sie der
                                                Öffentlichkeit zugänglich zu machen.
                                            </para>
                                        </listitem>
                                    </varlistentry>
                                </variablelist>

                                Standardmäßig sind alle diese Elemente privat.
                            </para>

                            <example id="zend.service.amazon.s3.objects.public.example">
                                <title>
                                    Beispiel für ein öffentliches Objekt in Zend_Service_Amazon_S3
                                </title>
                                <programlisting language="php"><![CDATA[
require_once 'Zend/Service/Amazon/S3.php';

$s3 = new Zend_Service_Amazon_S3($my_aws_key, $my_aws_secret_key);

$s3->putObject("my-own-bucket/Pictures/Me.png", file_get_contents("me.png"),
    array(Zend_Service_Amazon_S3::S3_ACL_HEADER =>
          Zend_Service_Amazon_S3::S3_ACL_PUBLIC_READ));
// oder:
$s3->putFile("me.png", "my-own-bucket/Pictures/Me.png",
    array(Zend_Service_Amazon_S3::S3_ACL_HEADER =>
          Zend_Service_Amazon_S3::S3_ACL_PUBLIC_READ));
echo "Go to http://s3.amazonaws.com/my-own-bucket/Pictures/Me.png to see me!\n";
]]></programlisting>
                            </example>
                        </listitem>
                    </varlistentry>
                </variablelist>
            </listitem>

            <listitem>
                <para>
                    <code>getObject($object)</code> empfängt Objektdaten vom Speicher anhand des
                    Namens.
                </para>
            </listitem>

            <listitem>
                <para>
                    <code>removeObject($object)</code> entfernt das Objekt vom Speicher.
                </para>
            </listitem>

            <listitem>
                <para>
                    <code>getInfo($object)</code> empfängt die Metadaten des Objekts. Diese
                    Funktion gibt ein Array mit Metadaten zurück. Einige der nützlichen Schlüssel
                    sind:

                    <variablelist>
                        <varlistentry>
                            <term><code>type</code></term>
                            <listitem>
                                <para>Der MIME Typ des Elements.</para>
                            </listitem>
                        </varlistentry>

                        <varlistentry>
                            <term><code>size</code></term>
                            <listitem>
                                <para>Die Größe der Objektdaten.</para>
                            </listitem>
                        </varlistentry>

                        <varlistentry>
                            <term><code>mtime</code></term>
                            <listitem>
                                <para>
                                    UNIX-artiger Zeitstempel der letzten Änderung für das Objekt.
                                </para>
                            </listitem>
                        </varlistentry>

                        <varlistentry>
                            <term><code>etag</code></term>
                            <listitem>
                                <para>
                                    Das ETag der Daten, welches ein MD5 Hash der Daten ist,
                                    eingeklammert von Hochkomma (").
                                </para>
                            </listitem>
                        </varlistentry>
                    </variablelist>

                    Die Funktion gibt false zurück wenn der Schlüssel keinem der existierenden
                    Objekte entspricht.
                </para>
            </listitem>

            <listitem>
                <para>
                    <code>getObjectsByBucket($bucket)</code> gibt eine Liste der Objektschlüssel
                    zurüc, die im Bucket enthalten sind.
                </para>

                <example id="zend.service.amazon.s3.objects.list.example">
                    <title>Beispiel für die Auflistung eines Zend_Service_Amazon_S3 Objekts</title>
                    <programlisting language="php"><![CDATA[
require_once 'Zend/Service/Amazon/S3.php';

$s3 = new Zend_Service_Amazon_S3($my_aws_key, $my_aws_secret_key);

$list = $s3->getObjectsByBucket("my-own-bucket");
foreach($list as $name) {
  echo "Ich habe $name Schlüssel:\n";
  $data = $s3->getObject("my-own-bucket/$name");
  echo "with data: $data\n";
}
]]></programlisting>
                </example>
            </listitem>

            <listitem>
                <para>
                    <code>isObjectAvailable($object)</code> prüft ob das Objekt mit dem angegebenen
                    Namen existiert.
                </para>
            </listitem>

            <listitem>
                <para>
                    <code>putFile($path, $object, $meta)</code> fügt den Inhalt der Datei unter
                    <code>$path</code> in das Objekt mit dem Namen <code>$object</code> ein.
                </para>

                <para>
                    Das optionale Argument <code>$meta</code> ist das gleiche wie für
                    <code>putObject</code>. Wenn der Content-Typ nicht angegeben wird, wird er
                    anhand des Dateinamens vermutet.
                </para>
            </listitem>
       </itemizedlist>
    </sect2>

    <sect2 id="zend.service.amazon.s3.streams">
        <title>Stream wrapper</title>

        <para>
            Zusätzlich zum oben beschriebenen Interface unterstützt
            <classname>Zend_Service_Amazon_S3</classname> das Arbeiten als Stream Wrapper. Hierfür
            muß das Client-Objekt als Stream Wrapper registriert werden:
        </para>

        <example id="zend.service.amazon.s3.streams.example">
            <title>Beispiel für Streams mit Zend_Service_Amazon_S3</title>
             <programlisting language="php"><![CDATA[
require_once 'Zend/Service/Amazon/S3.php';

$s3 = new Zend_Service_Amazon_S3($my_aws_key, $my_aws_secret_key);

$s3->registerStreamWrapper("s3");

mkdir("s3://my-own-bucket");
file_put_contents("s3://my-own-bucket/testdata", "mydata");

echo file_get_contents("s3://my-own-bucket/testdata");
]]></programlisting>
        </example>

        <para>
            Die Verzeichnis-Operationen (<code>mkdir</code>, <code>rmdir</code>,
            <code>opendir</code>, usw.) werden an Buckets ausgeführt und deshalb sollten deren
            Argumente in der Form <code>s3://bucketname</code> angegeben werden. Dateioperationen
            werden an Objekten ausgeführt. Objekt Erstellung, Lesen, Schreiben, Löschen, Stat und
            Anzeigen von Verzeichnissen wird unterstützt.
        </para>
    </sect2>
</sect1>