<?xml version="1.0" encoding="UTF-8"?>
<!-- EN-Revision: 24249 -->
<!-- Reviewed: no -->
<sect1 id="zend.service.amazon.ec2.images">
    <title>Zend_Service_Amazon_Ec2: Amazon Maschinen Images (AMI)</title>

    <para>
        Amazon Maschinen Images (AMIs) sind mit einer bereits wachsenden Listen von
        Betriebssystemen vorkonfiguriert.
    </para>

    <sect2 id="zend.service.amazon.ec2.images.info">
        <title>AMI Informations Tools</title>

        <example id="zend.service.amazon.ec2.images.register">
            <title>Ein AMI mit EC2 registrieren</title>

            <para>
                <code>register</code> Jedes <acronym>AMI</acronym> ist mit einer eideutigen ID
                assoziiert welche vom Amazon EC2 Service über die RegisterImage Operation zur
                Verfügung gestellt wird. Wärend der Registrierung empfängt Amazon EC2 das
                spezifizierte Manifest des Images von Amazon S3 und überprüft ob das Image dem
                Benutzer gehört der das Image registriert.
            </para>

            <para>
                <code>register</code> gibt die imageId für das registrierte Image zurück.
            </para>

            <programlisting language="php"><![CDATA[
$ec2_img = new Zend_Service_Amazon_Ec2_Image('aws_key','aws_secret_key');
$ip = $ec2_img->register('imageLocation');
]]></programlisting>
        </example>

        <example id="zend.service.amazon.ec2.images.deregister">
            <title>De-Registrieren einer AMI von EC2</title>

            <para>
                <code>deregister</code>, de-registriert ein <acronym>AMI</acronym>. Einmal
                de-registriert können Instanzen dieses <acronym>AMI</acronym> nicht mehr gestartet
                werden.
            </para>

            <para>
                <code>deregister</code> gibt ein boolsches <constant>TRUE</constant> oder
                <constant>FALSE</constant> zurück.
            </para>

            <programlisting language="php"><![CDATA[
$ec2_img = new Zend_Service_Amazon_Ec2_Image('aws_key','aws_secret_key');
$ip = $ec2_img->deregister('imageId');
]]></programlisting>
        </example>

        <example id="zend.service.amazon.ec2.images.describe">
            <title>Beschreiben einer AMI</title>

            <para>
                <code>describe</code> gibt Informationen über <acronym>AMI</acronym>s, AKIs und ARIs
                zurück die für den Benutzer verfügbar sind. Die zurückgegebenen Informationen
                enthalten den Imagetyp, Produktcodes, Architektur, Kernel und <acronym>RAM</acronym>
                Disk IDs. Images die für den Benutzer verfügbar sind, enthalten öffentliche Images
                die zum Starten für jeden Benutzer vorhanden sind, private Images die dem Benutzer
                gehören der die Anfrage stellt, und private Images die anderen Benutzern gehören
                welche dem Benutzer explizit die Rechte zum Starten gegeben haben.
            </para>

            <para>
                <table id="zend.service.amazon.ec2.images.describe-table">
                    <title>Die Rechte für das Starten fallen in drei Kategorien</title>

                    <tgroup cols="2">
                        <thead>
                            <row>
                                <entry>Name</entry>
                                <entry>Beschreibung</entry>
                            </row>
                        </thead>

                        <tbody>
                            <row>
                                <entry><code>public</code></entry>

                                <entry>
                                    <para>
                                        Der Eigentümer des <acronym>AMI</acronym> gibt allen Gruppen
                                        das Recht das <acronym>AMI</acronym> zu starten. Alle
                                        Benutzer haben Startberechtigung für diese
                                        <acronym>AMIs</acronym>.
                                    </para>
                                </entry>
                            </row>

                            <row>
                                <entry><code>explicit</code></entry>

                                <entry>
                                    <para>
                                        Der Eigentümer des <acronym>AMI</acronym> gibt einem
                                        spezifischen Benutzer die Startberechtigung.
                                    </para>
                                </entry>
                            </row>

                            <row>
                                <entry><code>implicit</code></entry>

                                <entry>
                                    <para>
                                        Ein Benutzer hat implizit die Startberechtigung für alle
                                        <acronym>AMIs</acronym> die Ihm gehören.
                                    </para>
                                </entry>
                            </row>
                        </tbody>
                    </tgroup>
                </table>
            </para>

            <para>
                Die Liste der zurückgegebenen <acronym>AMI</acronym>s kann durch die Spezifikation
                von <acronym>AMI</acronym> IDs, <acronym>AMI</acronym> Eigentümer oder Benutzern mit
                Starterechtigung, geändert werden. Wenn keine Option spezifiziert wird, gibt Amazon
                EC2 alle <acronym>AMI</acronym>s zurück für die der Benutzer eine Startberechtigung
                hat.
            </para>

            <para>
                Wenn eine oder mehrere <acronym>AMI</acronym> IDs spezifiziert werden, werden nur
                die <acronym>AMI</acronym>s zurückgegeben welche die spezifizierten IDs besitzen.
                Wenn man eine ungültige <acronym>AMI</acronym> ID spezifiziert, wird ein Fehler
                zurückgegeben. Wenn man eine <acronym>AMI</acronym> ID spezifiziert für die man
                keinen Zugriff hat, wird diese nicht in den zurückgegebenen Ergebnissen enthalten
                sein.
            </para>

            <para>
                Wenn ein oder mehrere <acronym>AMI</acronym> Eigentümer spezifiziert werden, werden
                nur die <acronym>AMI</acronym>s der spezifizierten Eigentümer, für die man auch
                Zugriffsrechte hat, zurückgegeben. Die Ergebnisse können account für die Account IDs
                des spezifizierten Eigentümers enthalten, amazon für <acronym>AMI</acronym>s die
                Amazon selbst gehören oder self für <acronym>AMI</acronym>s die man selbst besitzt.
            </para>

            <para>
                Wenn man eine Liste von ausführbaren Benutzern spezifiziert, werden nur die
                Benutzer zurückgegeben die eine Startberechtigung für die <acronym>AMI</acronym>s
                haben. Man kann mit account, Account IDs spezifizieren (wenn man die
                <acronym>AMI</acronym>s besitzt), self für <acronym>AMI</acronym>s die man selbst
                besitzt oder explizite Zugriffsrechte hat, oder all für öffentliche
                <acronym>AMI</acronym>s.
            </para>

            <para>
                <code>describe</code> gibt ein Array für alle Images zurück die den übergebenen
                Kriterien entsprechen. Das Array enthält imageId, imageLocation, imageState,
                imageOwnerId, isPublic, architecture, imageType, kernedId, ramdiskId und platform.
            </para>

            <programlisting language="php"><![CDATA[
$ec2_img = new Zend_Service_Amazon_Ec2_Image('aws_key','aws_secret_key');
$ip = $ec2_img->describe();
]]></programlisting>
        </example>
    </sect2>

    <sect2 id="zend.service.amazon.ec2.images.attribute">
        <title>Utilities für AMI Attribute</title>

        <example id="zend.service.amazon.ec2.images.attribute.modify">
            <title>Image Attribute verändern</title>

            <para>Ein Attribut eines <acronym>AMI</acronym> verändern</para>

            <para>
                <table id="zend.service.amazon.ec2.images.attribute.modify-table">
                    <title>Gültige Attribute</title>

                    <tgroup cols="2">
                        <thead>
                            <row>
                                <entry>Name</entry>
                                <entry>Beschreibung</entry>
                            </row>
                        </thead>

                        <tbody>
                            <row>
                                <entry><code>launchPermission</code></entry>

                                <entry>
                                    <para>
                                        Kontrolliert wer die Berechtigung hat das
                                        <acronym>AMI</acronym> zu starten. Startberechtigung kann
                                        spezifischen Benutzern durch das hinzufügen von userIds
                                        gegeben werden.
                                    </para>

                                    <para>
                                        Um das <acronym>AMI</acronym> öffentlich zu machen, sollte
                                        man die add Gruppe hinzufügen.
                                    </para>
                                </entry>
                            </row>

                            <row>
                                <entry><code>productCodes</code></entry>

                                <entry>
                                    <para>
                                        Assoziiert einen Produktcode mit <acronym>AMIs</acronym>.
                                        Das erlaubt es Entwicklern Benutzer für die Verwendung von
                                        <acronym>AMIs</acronym> zu benennen. Der Benutzer muß für
                                        das Produkt angemeldet sein bevor er das
                                        <acronym>AMI</acronym> starten kann. <emphasis>Das ist ein
                                        Write-Once Attribut; nachdem es gesetzt wurde kann es nicht
                                        mehr geändert oder gelöscht werden.</emphasis>
                                    </para>
                                </entry>
                            </row>
                        </tbody>
                    </tgroup>
                </table>
            </para>

            <para>
                <code>modifyAttribute</code> gibt ein boolsches <constant>TRUE</constant> oder
                <constant>FALSE</constant> zurück.
            </para>

            <programlisting language="php"><![CDATA[
$ec2_img = new Zend_Service_Amazon_Ec2_Image('aws_key','aws_secret_key');
// Ändert die Startberechtigung (launchPermission) eines AMI
$return = $ec2_img->modifyAttribute('imageId',
                                    'launchPermission',
                                    'add',
                                    'userId',
                                    'userGroup');

// Setzt den Produktcode des AMI.
$return = $ec2_img->modifyAttribute('imageId',
                                    'productCodes',
                                    'add',
                                    null,
                                    null,
                                    'productCode');
]]></programlisting>
        </example>

        <example id="zend.service.amazon.ec2.images.attribute.reset">
            <title>Zurücksetzen eines AMI Attributes</title>

            <para>
                <code>resetAttribute</code> setzt die Attribute eines <acronym>AMI</acronym> auf
                dessen Standardwerte zurück.
                <emphasis>Das productCodes Attribut kann nicht zurückgesetzt werden.</emphasis>
            </para>

            <programlisting language="php"><![CDATA[
$ec2_img = new Zend_Service_Amazon_Ec2_Image('aws_key','aws_secret_key');
$return = $ec2_img->resetAttribute('imageId', 'launchPermission');
]]></programlisting>
        </example>

        <example id="zend.service.amazon.ec2.images.attribute.describe">
            <title>AMI Attribute beschreiben</title>

            <para>
                <code>describeAttribute</code> gibt Informationen über ein Attribut eines
                <acronym>AMI</acronym> zurück. Pro Aufruf kann nur ein Attribut spezifiziert werden.
                Aktuell werden nur launchPermission und productCodes unterstützt.
            </para>

            <para>
                <code>describeAttribute</code> gibt ein Array mit dem Wert des Attributes zurück
                das angefragt wurde.
            </para>

            <programlisting language="php"><![CDATA[
$ec2_img = new Zend_Service_Amazon_Ec2_Image('aws_key','aws_secret_key');
$return = $ec2_img->describeAttribute('imageId', 'launchPermission');
]]></programlisting>
        </example>
    </sect2>
</sect1>
