| blob | c411c28a2a2545642b090dab0ecbe02dc9b557cd |
1 <?xml version="1.0" encoding="UTF-8"?>
2 <!-- EN-Revision: 21740 -->
3 <!-- Reviewed: no -->
4 <sect1 id="zend.service.amazon.s3">
5 <title>Zend_Service_Amazon_S3</title>
7 <sect2 id="zend.service.amazon.s3.introduction">
8 <title>Einführung</title>
10 <para>
11 Amazon S3 bietet ein einfaches Webservice Interface das verwendet werden kann um
12 beliebige Mengen an Daten, jederzeit und von überall her aus dem Web, zu Speichern und
13 erhalten. Es gibt Entwicklern den Zugriff auf die gleiche, hoch skalierbare,
14 verfügbare, schnelle und kostengünstige Datenspeicher Infrastruktur die Amazon
15 verwendet um sein eigenes globales Netzwerk an Websites zu betreiben. Der Service
16 zielt darauf ab den Nutzen der Skalierbarkeit zu erhöhen und diese Vorteile an
17 Entwickler weiterzugeben.
18 </para>
19 </sect2>
21 <sect2 id="zend.service.amazon.s3.registering">
22 <title>Registrierung mit Amazon S3</title>
24 <para>
25 Bevor man mit <classname>Zend_Service_Amazon_S3</classname> beginnen kann, muß man einen
26 Account registrieren. Sehen Sie bitte auf die Amazon Website
27 <ulink url="http://aws.amazon.com/s3/faqs/">S3 FAQ</ulink> für weitere Informationen.
28 </para>
30 <para>
31 Nach der Registrierung erhält man einen Anwendungsschlüssel und einen geheimen
32 Schlüssel. Man benötigt beide um auf den S3 Service zugreifen zu können.
33 </para>
34 </sect2>
36 <sect2 id="zend.service.amazon.s3.apiDocumentation">
37 <title>API Dokumentation</title>
39 <para>
40 Die Klasse <classname>Zend_Service_Amazon_S3</classname> bietet einen
41 <acronym>PHP</acronym> Wrapper zum Amazon S3 REST Interface. Schauen Sie bitte in die
42 <ulink
43 url="http://developer.amazonwebservices.com/connect/kbcategory.jspa?categoryID=48">Amazon
44 S3 Dokumentation</ulink> für eine detailierte Beschreibung des Services. Man muß mit
45 dem grundsätzlichen Konzept vertraut sein um dieses Service nutzen zu können.
46 </para>
48 </sect2>
50 <sect2 id="zend.service.amazon.s3.features">
51 <title>Features</title>
53 <para>
54 <classname>Zend_Service_Amazon_S3</classname> bietet die folgenden Funktionalitäten:
56 <itemizedlist>
57 <listitem>
58 <para>
59 Einen einzelnen Punkt für die Konfiguration der eigenen amazon.s3
60 Zugangsdaten der über dem kompletten amazon.s3 Namespace verwendet werden
61 kann.
62 </para>
63 </listitem>
65 <listitem>
66 <para>
67 Ein Proxy Objekt das bequemer zu verwenden ist als ein
68 <acronym>HTTP</acronym> Client alleine, da er hauptsächlich die
69 Notwendigkeit eliminiert manuell eine <acronym>HTTP</acronym> POST Anfrage
70 über den REST Service zu erstellen.
71 </para>
72 </listitem>
74 <listitem>
75 <para>
76 Ein Antwort-Wrapper der jede Antwort erhebt und eine Exception wirft wenn
77 ein Fehler aufgetreten ist, was die Notwendigkeit eliminiert den Erfolg
78 vieler Kommandos wiederholt zu prüfen.
79 </para>
80 </listitem>
82 <listitem>
83 <para>
84 Zusätzliche bequeme Methoden für einige der üblicheren Operationen.
85 </para>
86 </listitem>
87 </itemizedlist>
88 </para>
89 </sect2>
91 <sect2 id="zend.service.amazon.s3.storing-your-first">
92 <title>Beginnen wir</title>
94 <para>
95 Sobald man sich mit Amazon S3 registriert hat, ist man bereit sein erstes Objekt auf
96 S3 zu speichern. Die Objekte werden auf S3 in Containern gespeichert, die "Buckets"
97 genannt werden. Der Name der Buckets ist auf S3 eindeutig, und jeder Benutzer kann
98 nicht mehr als 100 Buckets simultan besitzen. Jeder Bucket kann eine unlimitierte
99 Anzahl an Objekten enthalten, die durch den Namen identifiziert werden.
100 </para>
102 <para>
103 Das folgende Beispiel demonstriert die Erstellung eines Buckets, und das Speichern und
104 Empfangen von Daten.
105 </para>
107 <example id="zend.service.amazon.s3.storing-your-first.example">
108 <title>Beispiel der Verwendung von Zend_Service_Amazon_S3</title>
110 <programlisting language="php"><![CDATA[
111 require_once 'Zend/Service/Amazon/S3.php';
113 $s3 = new Zend_Service_Amazon_S3($my_aws_key, $my_aws_secret_key);
115 $s3->createBucket("my-own-bucket");
117 $s3->putObject("my-own-bucket/myobject", "somedata");
119 echo $s3->getObject("my-own-bucket/myobject");
120 ]]></programlisting>
121 </example>
123 <para>
124 Da der <classname>Zend_Service_Amazon_S3</classname> Service eine Authentifizierung
125 benötigt, sollte man seine Zugangsdaten (AWS Schlüssel und Geheimschlüssel) an den
126 Konstruktor übergeben. Wenn man nur einen Account verwendet, kann man
127 Standard-Zugangsdaten für das Service setzen:
128 </para>
130 <programlisting language="php"><![CDATA[
131 require_once 'Zend/Service/Amazon/S3.php';
133 Zend_Service_Amazon_S3::setKeys($my_aws_key, $my_aws_secret_key);
134 $s3 = new Zend_Service_Amazon_S3();
135 ]]></programlisting>
136 </sect2>
138 <sect2 id="zend.service.amazon.s3.buckets">
139 <title>Bucket Operationen</title>
141 <para>
142 Alle Objekte im S3 System werden in Buckets gespeichert. Buckets müssen erstellt werden
143 bevor Speicheroperationen durchgeführt werden. Der Name des Buckets ist im System
144 eindeutig, so das man den Bucket nicht so benennen kann wie den Bucket einer anderen
145 Person.
146 </para>
148 <para>
149 Namen von Buckets können Kleinbuchstaben, Ziffern, Punkte (.), Unterstriche (_), und
150 Bindestriche (-) enthalten. Es sind keine anderen Symbole erlaubt. Bucketnamen sollten
151 mit einem Buchstaben oder einer Ziffer beginnen, und 3 bis 255 Zeichen lang sein.
152 Namen die wie eine IP Adresse aussehen (z.B. "192.168.16.255") sind nicht erlaubt.
153 </para>
155 <itemizedlist>
156 <listitem>
157 <para>
158 <methodname>createBucket()</methodname> erstellt einen neuen Bucket.
159 </para>
160 </listitem>
162 <listitem>
163 <para>
164 <methodname>cleanBucket()</methodname> entfernt alle Objekte die in einem Bucket
165 enthalten sind.
166 </para>
167 </listitem>
169 <listitem>
170 <para>
171 <methodname>removeBucket()</methodname> entfernt den Bucket vom System. Der
172 Bucket sollte leer sein damit er entfernt werden kann.
173 </para>
175 <example id="zend.service.amazon.s3.buckets.remove.example">
176 <title>
177 Beispiel für das Entfernen eines Buckets in Zend_Service_Amazon_S3
178 </title>
180 <programlisting language="php"><![CDATA[
181 require_once 'Zend/Service/Amazon/S3.php';
183 $s3 = new Zend_Service_Amazon_S3($my_aws_key, $my_aws_secret_key);
185 $s3->cleanBucket("my-own-bucket");
186 $s3->removeBucket("my-own-bucket");
187 ]]></programlisting>
188 </example>
189 </listitem>
191 <listitem>
192 <para>
193 <methodname>getBuckets()</methodname> gibt eine Liste der Namen aller Buckets
194 zurück die einem Benutzer gehören.
195 </para>
197 <example id="zend.service.amazon.s3.buckets.list.example">
198 <title>Beispiel für das Auflisten der Buckets in Zend_Service_Amazon_S3</title>
200 <programlisting language="php"><![CDATA[
201 require_once 'Zend/Service/Amazon/S3.php';
203 $s3 = new Zend_Service_Amazon_S3($my_aws_key, $my_aws_secret_key);
205 $list = $s3->getBuckets();
206 foreach($list as $bucket) {
207 echo "Ich habe das Bucket $bucket\n";
208 }
209 ]]></programlisting>
210 </example>
211 </listitem>
213 <listitem>
214 <para>
215 <methodname>isBucketAvailable()</methodname> prüft ob das Bucket existiert und
216 gibt <constant>TRUE</constant> zurück wenn das der Fall ist.
217 </para>
218 </listitem>
219 </itemizedlist>
220 </sect2>
222 <sect2 id="zend.service.amazon.s3.objects">
223 <title>Operationen am Objekt</title>
225 <para>
226 Das Objekte ist die grundsätzliche Speichereinheit in S3. Objekte speichern nicht
227 strukturierte Daten, welche jede Größe, bis zu 4 Gigabyte, haben können. Es gibt kein
228 Limit in der Anzahl der Objekte die auf dem System gespeichert werden können.
229 </para>
231 <para>
232 Objekte werden in Buckets abgelegt. Sie werden durch den Namen identifiziert, der
233 jeder UTF-8 String sein kann. Es ist üblich hierarchische Namen zu verwenden (wie z.B.
234 <code>Pictures/Myself/CodingInPHP.jpg</code> um Objektnamen zu organisieren.
235 Objektnamen wird der Bucketname vorangestellt wenn Objektfunktionen verwendet werden,
236 so dass das Objekt "mydata" im Bucket "my-own-bucket" den Namen
237 <code>my-own-bucket/mydata</code> haben würde.
238 </para>
240 <para>
241 Objekte können ersetzt (durch Überschreiben neuer Daten mit dem gleichen Schlüssel)
242 oder gelöscht werden, aber nicht geändert, angefügt, usw. Objekte werden immer als
243 Ganzes gespeichert.
244 </para>
246 <para>
247 Standardmäßig sind alle Objekte privat und es kann nur durch Ihren Besitzer auf Sie
248 zugegriffen werden. Trotzdem ist es möglich Objekte mit öffentlichem Zugriff zu
249 spezifizieren, wodurch man auf Sie mit der folgenden <acronym>URL</acronym> zugreifen
250 kann: <code>http://s3.amazonaws.com/[bucket-name]/[object-name]</code>.
251 </para>
253 <itemizedlist>
254 <listitem>
255 <para>
256 <methodname>putObject($object, $data, $meta)</methodname> erstellt ein Objekt
257 mit dem Namen <varname>$object</varname> (Sollte den Bucketnamen als Präfix
258 enthalten!) das <varname>$data</varname> als seinen Inhalt besitzt.
259 </para>
261 <para>
262 Der optionale <varname>$meta</varname> Parameter ist das Array von Metadaten,
263 welches aktuell die folgenden Schlüssel enthalten kann:
264 </para>
266 <variablelist>
267 <varlistentry>
268 <term><constant>S3_CONTENT_TYPE_HEADER</constant></term>
270 <listitem>
271 <para>
272 <acronym>MIME</acronym> Content Type der Daten. Wenn nicht
273 angegeben, wird der Typ anhand der Dateiextension des Objektnamens
274 geschätzt.
275 </para>
276 </listitem>
277 </varlistentry>
279 <varlistentry>
280 <term><constant>S3_ACL_HEADER</constant></term>
282 <listitem>
283 <para>
284 Der Zugriff auf das Element. Folgende Zugriffskonstanten können
285 verwendet werden:
287 <variablelist>
288 <varlistentry>
289 <term><constant>S3_ACL_PRIVATE</constant></term>
291 <listitem>
292 <para>
293 Nur der Besitzer hat auf das Element Zugriff.
294 </para>
295 </listitem>
296 </varlistentry>
298 <varlistentry>
299 <term><constant>S3_ACL_PUBLIC_READ</constant></term>
301 <listitem>
302 <para>
303 Jeder kann das Objekt lesen, aber nur der Besitzer
304 kann schreiben. Diese Eigenschaft kann verwendet
305 werden um öffentlich zugängliche Inhalte zu
306 speichern.
307 </para>
308 </listitem>
309 </varlistentry>
311 <varlistentry>
312 <term><constant>S3_ACL_PUBLIC_WRITE</constant></term>
314 <listitem>
315 <para>
316 Jeder kann das Objekt schreiben oder lesen. Diese
317 Eigenschaft sollte sehr spärlich verwendet werden.
318 </para>
319 </listitem>
320 </varlistentry>
322 <varlistentry>
323 <term><constant>S3_ACL_AUTH_READ</constant></term>
325 <listitem>
326 <para>
327 Nur der Besitzer hat Schreibzugriff auf das
328 Element, und andere authentifizierte S3 Benutzer
329 haben Leserechte. Das ist nützlich um Daten
330 zwischen S3 Accounts zu teilen ohne Sie der
331 Öffentlichkeit zugänglich zu machen.
332 </para>
333 </listitem>
334 </varlistentry>
335 </variablelist>
337 Standardmäßig sind alle diese Elemente privat.
338 </para>
340 <example id="zend.service.amazon.s3.objects.public.example">
341 <title>
342 Beispiel für ein öffentliches Objekt in Zend_Service_Amazon_S3
343 </title>
345 <programlisting language="php"><![CDATA[
346 require_once 'Zend/Service/Amazon/S3.php';
348 $s3 = new Zend_Service_Amazon_S3($my_aws_key, $my_aws_secret_key);
350 $s3->putObject("my-own-bucket/Pictures/Me.png", file_get_contents("me.png"),
351 array(Zend_Service_Amazon_S3::S3_ACL_HEADER =>
352 Zend_Service_Amazon_S3::S3_ACL_PUBLIC_READ));
353 // oder:
354 $s3->putFile("me.png", "my-own-bucket/Pictures/Me.png",
355 array(Zend_Service_Amazon_S3::S3_ACL_HEADER =>
356 Zend_Service_Amazon_S3::S3_ACL_PUBLIC_READ));
357 echo "Go to http://s3.amazonaws.com/my-own-bucket/Pictures/Me.png to see me!\n";
358 ]]></programlisting>
359 </example>
360 </listitem>
361 </varlistentry>
362 </variablelist>
363 </listitem>
365 <listitem>
366 <para>
367 <methodname>getObject($object)</methodname> empfängt Objektdaten vom Speicher
368 anhand des Namens.
369 </para>
370 </listitem>
372 <listitem>
373 <para>
374 <methodname>removeObject($object)</methodname> entfernt das Objekt vom Speicher.
375 </para>
376 </listitem>
378 <listitem>
379 <para>
380 <methodname>getInfo($object)</methodname> empfängt die Metadaten des Objekts.
381 Diese Funktion gibt ein Array mit Metadaten zurück. Einige der nützlichen
382 Schlüssel sind:
384 <variablelist>
385 <varlistentry>
386 <term><code>type</code></term>
388 <listitem>
389 <para>Der <acronym>MIME</acronym> Typ des Elements.</para>
390 </listitem>
391 </varlistentry>
393 <varlistentry>
394 <term><code>size</code></term>
395 <listitem><para>Die Größe der Objektdaten.</para></listitem>
396 </varlistentry>
398 <varlistentry>
399 <term><code>mtime</code></term>
401 <listitem>
402 <para>
403 UNIX-artiger Zeitstempel der letzten Änderung für das Objekt.
404 </para>
405 </listitem>
406 </varlistentry>
408 <varlistentry>
409 <term><code>etag</code></term>
411 <listitem>
412 <para>
413 Das ETag der Daten, welches ein MD5 Hash der Daten ist,
414 eingeklammert von Hochkomma (").
415 </para>
416 </listitem>
417 </varlistentry>
418 </variablelist>
420 Die Funktion gibt <constant>FALSE</constant> zurück wenn der Schlüssel keinem
421 der existierenden Objekte entspricht.
422 </para>
423 </listitem>
425 <listitem>
426 <para>
427 <methodname>getObjectsByBucket($bucket)</methodname> gibt eine Liste der
428 Objektschlüssel zurüc, die im Bucket enthalten sind.
429 </para>
431 <example id="zend.service.amazon.s3.objects.list.example">
432 <title>Beispiel für die Auflistung eines Zend_Service_Amazon_S3 Objekts</title>
434 <programlisting language="php"><![CDATA[
435 require_once 'Zend/Service/Amazon/S3.php';
437 $s3 = new Zend_Service_Amazon_S3($my_aws_key, $my_aws_secret_key);
439 $list = $s3->getObjectsByBucket("my-own-bucket");
440 foreach($list as $name) {
441 echo "Ich habe $name Schlüssel:\n";
442 $data = $s3->getObject("my-own-bucket/$name");
443 echo "with data: $data\n";
444 }
445 ]]></programlisting>
446 </example>
447 </listitem>
449 <listitem>
450 <para>
451 <methodname>isObjectAvailable($object)</methodname> prüft ob das Objekt mit dem
452 angegebenen Namen existiert.
453 </para>
454 </listitem>
456 <listitem>
457 <para>
458 <methodname>putFile($path, $object, $meta)</methodname> fügt den Inhalt der
459 Datei unter <varname>$path</varname> in das Objekt mit dem Namen
460 <varname>$object</varname> ein.
461 </para>
463 <para>
464 Das optionale Argument <varname>$meta</varname> ist das gleiche wie für
465 <code>putObject</code>. Wenn der Content-Typ nicht angegeben wird, wird er
466 anhand des Dateinamens vermutet.
467 </para>
468 </listitem>
469 </itemizedlist>
470 </sect2>
472 <sect2 id="zend.service.amazon.s3.streaming">
473 <title>Daten Streamen</title>
475 <para>
476 Es ist möglich Objekte zu Holen und Setzen wobei keine Stream Daten verwendet werden die
477 im Speicher sind, sondern Dateien oder <acronym>PHP</acronym> Streams. Das ist Speziell
478 dann nützlich wenn Dateien sehr groß sind um nicht über Speichergrenzen zu kommen.
479 </para>
481 <para>
482 Um ein Objekt mit Streaming zu Empfangen muss die Methode
483 <methodname>getObjectStream($object, $filename)</methodname> verwendet werden. Diese
484 Methode gibt einen <classname>Zend_Http_Response_Stream</classname> zurück, welcher wie
485 im Kapitel <link linkend="zend.http.client.streaming">HTTP Client Daten Streaming</link>
486 verwendet werden kann.
488 <example id="zend.service.amazon.s3.streaming.example1">
489 <title>Beispiel für das Streamen von Daten mit Zend_Service_Amazon_S3</title>
491 <programlisting language="php"><![CDATA[
492 $response = $amazon->getObjectStream("mybycket/zftest");
493 // Datei kopieren
494 copy($response->getStreamName(), "my/downloads/file");
495 // Hinauf Streamen
496 $fp = fopen("my/downloads/file2", "w");
497 stream_copy_to_stream($response->getStream(), $fp);
498 ]]></programlisting>
499 </example>
500 </para>
502 <para>
503 Der zweite Parameter für <methodname>getObjectStream()</methodname> ist optional und
504 spezifiziert die Zieldatei in welche die dAten geschrieben werden. Wenn er nicht
505 spezifiziert ist, wird eine temporäre Datei verwendet. Diese wird gelöscht nachdem das
506 Antwort-Objekt gelöscht wurde.
507 </para>
509 <para>
510 Um ein Objekt mit Streaming zu Senden kann <methodname>putFileStream()</methodname>
511 verwendet werden. Es hat die gleiche Signatur wie <methodname>putFile()</methodname>
512 verwendet aber Streaming und liest die Datei nicht in den Speicher ein.
513 </para>
515 <para>
516 Man kann auch eine Stream Ressource an die <methodname>putObject()</methodname> Methode
517 als Daten Parameter übergeben. In diesem Fall werden die Daten vom Stream gelesen wenn
518 die Anfrage an den Server gesendet wird.
519 </para>
520 </sect2>
522 <sect2 id="zend.service.amazon.s3.streams">
523 <title>Stream wrapper</title>
525 <para>
526 Zusätzlich zum oben beschriebenen Interface unterstützt
527 <classname>Zend_Service_Amazon_S3</classname> das Arbeiten als Stream Wrapper. Hierfür
528 muß das Client-Objekt als Stream Wrapper registriert werden:
529 </para>
531 <example id="zend.service.amazon.s3.streams.example">
532 <title>Beispiel für Streams mit Zend_Service_Amazon_S3</title>
534 <programlisting language="php"><![CDATA[
535 require_once 'Zend/Service/Amazon/S3.php';
537 $s3 = new Zend_Service_Amazon_S3($my_aws_key, $my_aws_secret_key);
539 $s3->registerStreamWrapper("s3");
541 mkdir("s3://my-own-bucket");
542 file_put_contents("s3://my-own-bucket/testdata", "mydata");
544 echo file_get_contents("s3://my-own-bucket/testdata");
545 ]]></programlisting>
546 </example>
548 <para>
549 Die Verzeichnis-Operationen (<code>mkdir</code>, <code>rmdir</code>,
550 <code>opendir</code>, usw.) werden an Buckets ausgeführt und deshalb sollten deren
551 Argumente in der Form <code>s3://bucketname</code> angegeben werden. Dateioperationen
552 werden an Objekten ausgeführt. Objekt Erstellung, Lesen, Schreiben, Löschen, Stat und
553 Anzeigen von Verzeichnissen wird unterstützt.
554 </para>
555 </sect2>
556 </sect1>