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

<?xml version="1.0" encoding="UTF-8"?>
<!-- EN-Revision: 24249 -->
<!-- Reviewed: no -->
<sect1 id="zend.gdata.gapps">
    <title>Google Apps Provisionierung verwenden</title>

    <para>
        Google Apps ist ein Service der es Domain Administratoren erlaubt Ihren Benutzern einen
        gemanagten Zugriff auf Google Services wie Mail, Kalender und Dokumente &amp;
        Tabellenkalkulationen zu bieten. Die Provisionierungs <acronym>API</acronym> bietet ein
        programmmäßiges Interface um dieses Service zu konfigurieren. Im speziellen erlaubt es diese
        <acronym>API</acronym> den Administratoren Benutzerzugänge, Nicknamen, Gruppen und Email
        Listen zu erstellen, zu empfangen, zu verändern und zu löschen.
    </para>

    <para>
        Diese Bibliothek implementiert die Version 2.0 der Provisionierungs <acronym>API</acronym>.
        Zugriff zum eigenen Konto über die Provisionierungs <acronym>API</acronym> muß manuell für
        jede Domain aktiviert werden die das Google Apps Kontrollpanel verwendet. Nur bestimmte
        Kontotpen sind fähig dieses Feature einzuschalten.
    </para>

    <para>
        Für weitere Information zur Google Apps Provisionierungs <acronym>API</acronym>, inklusive
        Anleitungen für das Einschalten des <acronym>API</acronym> Zugriffs, kann in die <ulink
            url="http://code.google.com/apis/apps/gdata_provisioning_api_v2.0_reference.html">Provisionierungs
            <acronym>API</acronym> V2.0 Referenz</ulink> gesehen werden.
    </para>

    <note>
        <title>Authentifizierung</title>

        <para>
            Die Provisionierungs <acronym>API</acronym> unterstützt keine Authentifizierung über
            AuthSub und anonymer Zugriff ist nicht gestattet. Alle <acronym>HTTP</acronym>
            Verbindungen müssen mit Hilfe der ClientAuth Authentifizierung authentifiziert werden.
        </para>
    </note>

    <sect2 id="zend.gdata.gapps.domain">
        <title>Die aktuelle Domain setzen</title>

        <para>
            Um die Provisionierungs <acronym>API</acronym> zu verwenden muß die Domain, die
            administriert werden soll, in allen Anfrage <acronym>URI</acronym>s spezifiziert werden.
            Um die Entwicklung zu vereinfachen, wird diese Information sowohl im Gapps Service und
            den Abfrageklassen gespeichert um Sie zu verwenden wenn Abfragen erstellt werden.
        </para>

        <sect3 id="zend.gdata.gapps.domain.service">
            <title>Setzen der Domain für die Serviceklasse</title>

            <para>
                Um die Domain für die von der Serviceklasse durchgeführten Anfragen zu setzen kann
                entweder <methodname>setDomain()</methodname> aufgerufen oder die Domain bei der
                Instanzierung der Serviceklasse spezifiziert werden. Zum Beispiel:
            </para>

            <programlisting language="php"><![CDATA[
$domain = "example.com";
$gdata = new Zend_Gdata_Gapps($client, $domain);
]]></programlisting>
        </sect3>

        <sect3 id="zend.gdata.gapps.domain.query">
            <title>Die Domain für die Abfrageklasse setzen</title>

            <para>
                Das Setzen der Domain für Anfrage die durch die Abfrageklasse durchgeführt werden
                ist ähnlich dem setzen für die Serviceklasse-entweder wird
                <methodname>setDomain()</methodname> aufgerufen, oder die Domain wird bei der
                Erstellung der Abfrage angegeben. Zum Beispiel:
            </para>

            <programlisting language="php"><![CDATA[
$domain = "example.com";
$query = new Zend_Gdata_Gapps_UserQuery($domain, $arg);
]]></programlisting>

            <para>
                Wenn eine Serviceklassen Factorymethode verwendet wird um eine Abfrage zu erstellen,
                setzt die Serviceklasse die Domain der Abfrage automatisch so das Sie ihrer eigenen
                Domain entspricht. Als Ergebnis ist es nicht notwendig die Domain als Teil der
                Konstruktorargumente zu spezifizieren.
            </para>

            <programlisting language="php"><![CDATA[
$domain = "example.com";
$gdata = new Zend_Gdata_Gapps($client, $domain);
$query = $gdata->newUserQuery($arg);
]]></programlisting>
        </sect3>
    </sect2>

    <sect2 id="zend.gdata.gapps.users">
        <title>Interaktion mit Benutzern</title>

        <para>
            Jeder Benutzerzugang zu einer Google Apps gehosteten Domain wird als Instanz von
            <classname>Zend_Gdata_Gapps_UserEntry</classname> repräsentiert. Diese Klasse bietet
            Zugriff zu allen Zugangseigenschaften inklusive Name, Benutzername, Passwort,
            Zugriffsrechte und aktuellen Quoten.
        </para>

        <sect3 id="zend.gdata.gapps.users.creating">
            <title>Erstellen eines Benutzerzugangs</title>

            <para>
                Benutzerzugänge können durch den Aufruf der einfachen
                <methodname>createUser()</methodname> Methode erstellt werden:
            </para>

            <programlisting language="php"><![CDATA[
$gdata->createUser('foo', 'Random', 'User', '••••••••');
]]></programlisting>

            <para>
                Benutzer können durch das Instanzieren eines UserEntry erstellt werden, indem ein
                Benutzername, ein Name, ein Familienname und ein Passwort angegeben werden und
                anschließend <methodname>insertUser()</methodname> am Serviceobjekt aufgerufen wird
                um den Eintrag zum Server zu laden.
            </para>

            <programlisting language="php"><![CDATA[
$user = $gdata->newUserEntry();
$user->login = $gdata->newLogin();
$user->login->username = 'foo';
$user->login->password = '••••••••';
$user->name = $gdata->newName();
$user->name->givenName = 'Irgendwer';
$user->name->familyName = 'Benutzer';
$user = $gdata->insertUser($user);
]]></programlisting>

            <para>
                Das Passwort den Benutzers sollte normalerweise als Klartext angegeben werden.
                Operional kann das Passwort als <acronym>SHA-1</acronym> Schlüssel angegeben werden
                wenn <command>login->passwordHashFunction</command> auf '<property>SHA-1</property>'
                gesetzt ist.
            </para>
        </sect3>

        <sect3 id="zend.gdata.gapps.users.retrieving">
            <title>Einen Benutzerzugang erhalten</title>

            <para>
                Individuelle Benutzerzugänge kann man erhalten indem die einfache
                <methodname>retrieveUser()</methodname> Methode aufgerufen wird. Wenn der Benutzer
                nicht gefunden wird, wird <constant>NULL</constant> zurückgegeben.
            </para>

            <programlisting language="php"><![CDATA[
$user = $gdata->retrieveUser('foo');

echo 'Benutzername: ' . $user->login->userName . "\n";
echo 'Name: ' . $user->name->givenName . "\n";
echo 'Familienname: ' . $user->name->familyName . "\n";
echo 'Unterbrochen: ' . ($user->login->suspended ? 'Ja' : 'Nein') . "\n";
echo 'Administrator: ' . ($user->login->admin ? 'Ja' : 'Nein') . "\n"
echo 'Muss das Passwort ändern: ' .
     ($user->login->changePasswordAtNextLogin ? 'Ja' : 'Nein') . "\n";
echo 'Hat den Regeln zugestimmt: ' .
     ($user->login->agreedToTerms ? 'Ja' : 'Nein') . "\n";
]]></programlisting>

            <para>
                Benutzer kann man auch erhalten indem eine Instanz von
                <classname>Zend_Gdata_Gapps_UserQuery</classname> erstellt wird, und dessen username
                Eigenschaft dem Benutzernamen des Benutzers entspricht den man erhalten will und
                <methodname>getUserEntry()</methodname> auf einem Serviceobjekt mit dieser Abfrage
                aufruft.
            </para>

            <programlisting language="php"><![CDATA[
$query = $gdata->newUserQuery('foo');
$user = $gdata->getUserEntry($query);

echo 'Benutzername: ' . $user->login->userName . "\n";
echo 'Name: ' . $user->login->givenName . "\n";
echo 'Familien Name: ' . $user->login->familyName . "\n";
echo 'Unterbrochen: ' . ($user->login->suspended ? 'Ja' : 'Nein') . "\n";
echo 'Administrator: ' . ($user->login->admin ? 'Ja' : 'Nein') . "\n"
echo 'Muss das Passwort ändern: ' .
     ($user->login->changePasswordAtNextLogin ? 'Ja' : 'Nein') . "\n";
echo 'Hat den Regeln zugestimmt: ' .
     ($user->login->agreedToTerms ? 'Ja' : 'Nein') . "\n";
]]></programlisting>

            <para>
                Wenn der spezifizierte Benutzer nicht gefunden werden kann wird eine
                ServiceException mit einem Fehlercode von
                <constant>Zend_Gdata_Gapps_Error::ENTITY_DOES_NOT_EXIST</constant> geworfen.
                ServiceExceptions werden in <link
                    linkend="zend.gdata.gapps.exceptions">dem Kapitel über Exceptions</link>
                behandelt.
            </para>
        </sect3>

        <sect3 id="zend.gdata.gapps.users.retrievingAll">
            <title>Alle Benutzer in einer Domain erhalten</title>

            <para>
                Um alle Benutzer in einer Domäne zu erhalten kann die einfache
                <methodname>retrieveAllUsers()</methodname> Methode aufgerufen werden.
            </para>

            <programlisting language="php"><![CDATA[
$feed = $gdata->retrieveAllUsers();

foreach ($feed as $user) {
    echo "  * " . $user->login->username . ' (' . $user->name->givenName .
        ' ' . $user->name->familyName . ")\n";
}
]]></programlisting>

            <para>
                Das wird ein <classname>Zend_Gdata_Gapps_UserFeed</classname> Objekt erstellen
                welches jeden Benutzer dieser Domain enthält.
            </para>

            <para>
                Alternativ kann <methodname>getUserFeed()</methodname> ohne Optionen aufgerufen
                werden. Es ist zu beachten das dieser Feed bei größeren Domains durch den Server in
                Seiten ausgegeben werden kann. Über weitere Informationen der Ausgabe in Seiten
                siehe <link linkend="zend.gdata.introduction.paging">das Kapitel über Seiten</link>.
            </para>

            <programlisting language="php"><![CDATA[
$feed = $gdata->getUserFeed();

foreach ($feed as $user) {
    echo "  * " . $user->login->username . ' (' . $user->name->givenName .
        ' ' . $user->name->familyName . ")\n";
}
]]></programlisting>
        </sect3>

        <sect3 id="zend.gdata.gapps.users.updating">
            <title>Einen Benutzerzugang aktualisieren</title>

            <para>
                Der einfachste Weg um einen Benutzerzugang zu aktualisieren ist es den Benutzer wie
                in der vorherigen Sektion beschrieben zu empfangen, jegliche gewünschte Änderungen
                durchzuführen und anschließend <methodname>save()</methodname> auf diesem Benutzer
                aufzurufen. Jede gemachte Änderung wird an den Server weitergegeben.
            </para>

            <programlisting language="php"><![CDATA[
$user = $gdata->retrieveUser('foo');
$user->name->givenName = 'Foo';
$user->name->familyName = 'Bar';
$user = $user->save();
]]></programlisting>

            <sect4 id="zend.gdata.gapps.users.updating.resettingPassword">
                <title>Ein Benutzerpasswort zurücksetzen</title>

                <para>
                    Ein Benutzerpasswort kann auf einen neuen Wert zurückgesetzt werden indem die
                    <command>login->password</command> Eigenschaft aktualisiert wird.
                </para>

                <programlisting language="php"><![CDATA[
$user = $gdata->retrieveUser('foo');
$user->login->password = '••••••••';
$user = $user->save();
]]></programlisting>

                <para>
                    Es ist zu beachten das es nicht möglich ist ein Passwort auf diesem Weg
                    wiederherzustellen da gespeicherte Passwörter aus Sicherheitsgründern nicht über
                    die Provisionierungs <acronym>API</acronym> verfügbar gemacht werden.
                </para>
            </sect4>

            <sect4 id="zend.gdata.gapps.users.updating.forcingPasswordChange">
                <title>Einen Benutzer zwingen sein Passwort zu ändern</title>

                <para>
                    Ein Benutzer kann dazu gezwungen werden sein Passwort bei seinem nächsten Login
                    zu ändern, indem die <command>login->changePasswordAtNextLogin</command>
                    Eigenschaft auf <constant>TRUE</constant> gesetzt wird.
                </para>

                <programlisting language="php"><![CDATA[
$user = $gdata->retrieveUser('foo');
$user->login->changePasswordAtNextLogin = true;
$user = $user->save();
]]></programlisting>

                <para>
                    Genauso kann das rückgängig gemacht werden indem die
                    <command>login->changePasswordAtNextLogin</command> Eigenschaft auf
                    <constant>FALSE</constant> gesetzt wird.
                </para>
            </sect4>

            <sect4 id="zend.gdata.gapps.users.updating.suspendingAccount">
                <title>Einen Benutzerzugang unterbrechen</title>

                <para>
                    Benutzer können daran gehindert werden sich anzumelden ohne das Ihr
                    Benutzerzugang gelöscht wird indem Ihr Benutzerzugang
                    <emphasis>unterbrochen</emphasis> wird. Zugänge können unterbrochen oder
                    wiederhergestellt werden indem die einfachen
                    <methodname>suspendUser()</methodname> und
                    <methodname>restoreUser()</methodname> Methoden verwendet werden:
                </para>

                <programlisting language="php"><![CDATA[
$gdata->suspendUser('foo');
$gdata->restoreUser('foo');
]]></programlisting>

                <para>
                    Alternativ kann die Eigenschaft <command>login->suspended</command> des
                    Benutzerzugangs auf <constant>TRUE</constant> gesetzt werden.
                </para>

                <programlisting language="php"><![CDATA[
$user = $gdata->retrieveUser('foo');
$user->login->suspended = true;
$user = $user->save();
]]></programlisting>

                <para>
                    Um den Benutzerzugang wiederherzustellen muß die
                    <command>login->suspended</command> Eigenschaft auf <constant>FALSE</constant>
                    gesetzt werden.
                </para>
            </sect4>

            <sect4 id="zend.gdata.gapps.users.updating.grantingAdminRights">
                <title>Administrative Rechte vergeben</title>

                <para>
                    Benutzern kann die Möglichkeit gegeben werden die Domain zu verwalten durch das
                    setzen Ihrer <command>login->admin</command> Eigenschaft auf
                    <constant>TRUE</constant>.
                </para>

                <programlisting language="php"><![CDATA[
$user = $gdata->retrieveUser('foo');
$user->login->admin = true;
$user = $user->save();
]]></programlisting>

                <para>
                    Und wie erwartet, entfernt das Setzen der Eigenschaft
                    <command>login->admin</command>, des Benutzers auf <constant>FALSE</constant>,
                    dessen administrative Rechte.
                </para>
            </sect4>
        </sect3>

        <sect3 id="zend.gdata.gapps.users.deleting">
            <title>Löschen eines Benutzerzugangs</title>

            <para>
                Einen Benutzerzugang zu löschen zu dem man bereits ein UserEntry hat, ist so einfach
                wie der Aufruf von <methodname>delete()</methodname> auf diesem Eintrag.
            </para>

            <programlisting language="php"><![CDATA[
$user = $gdata->retrieveUser('foo');
$user->delete();
]]></programlisting>

            <para>
                Wenn man keinen Zugriff auf ein UserEntry Objekt für einen Zugang hat, kann die
                einfache <methodname>deleteUser()</methodname> Methode verwendet werden.
            </para>

            <programlisting language="php"><![CDATA[
$gdata->deleteUser('foo');
]]></programlisting>
        </sect3>
    </sect2>

    <sect2 id="zend.gdata.gapps.nicknames">
        <title>Mit Spitznamen interagieren</title>

        <para>
            Spitznamen arbeiten als Email Aliase für bestehende Benutzer. Jeder Spitzname enthält
            genau zwei Schlüsseleigenschaften: Seinen Namen und seinen Eigentümer. Jede Email die zu
            einem Spitznamen adressiert wurde wird zu dem Benutzer weitergeleitet der diesen
            Spitznamen besitzt.
        </para>

        <para>
            Spitznamen werden repräsentiert als Instanz von
            <classname>Zend_Gdata_Gapps_NicknameEntry</classname>.
        </para>

        <sect3 id="zend.gdata.gapps.nicknames.creating">
            <title>Erstellen eines Spitznamens</title>

            <para>
                Spitznamen können durch den Aufruf der einfachen
                <methodname>createNickname()</methodname> Methode erstellt werden:
            </para>

            <programlisting language="php"><![CDATA[
$gdata->createNickname('foo', 'bar');
]]></programlisting>

            <para>
                Spitznamen können auch durch das instanzieren eines NichnameEntry erstellt werden,
                wobei der Spitzname mit einem Namen und einem Eigentümer ausgestattet wird, und dann
                <methodname>insertNickname()</methodname> auf einem Service Objekt aufgerufen wird,
                um den Eintrag zu einem Server hochzuladen.
            </para>

            <programlisting language="php"><![CDATA[
$nickname = $gdata->newNicknameEntry();
$nickname->login = $gdata->newLogin('foo');
$nickname->nickname = $gdata->newNickname('bar');
$nickname = $gdata->insertNickname($nickname);
]]></programlisting>
        </sect3>

        <sect3 id="zend.gdata.gapps.nicknames.retrieving">
            <title>Einen Spitznamen empfangen</title>

            <para>
                Spitznamen können durch den Aufruf der bequemen
                <methodname>retrieveNickname()</methodname> Methode empfangen werden. Sie gibt
                <constant>NULL</constant> zurück wenn der Benutzer nicht gefunden wurde.
            </para>

            <programlisting language="php"><![CDATA[
$nickname = $gdata->retrieveNickname('bar');

echo 'Spitzname: ' . $nickname->nickname->name . "\n";
echo 'Eigentümer: ' . $nickname->login->username . "\n";
]]></programlisting>

            <para>
                Individuelle Spitznamen können durch Erstellung einer
                <classname>Zend_Gdata_Gapps_NicknameQuery</classname> Instanz erhalten werden, indem
                dessen nickname Eigenschaft dem Spitznamen gleichgesetzt wird der empfangen werden
                soll, und <methodname>getNicknameEntry()</methodname> auf einem Server Objekt mit
                dieser Abfrage aufgerufen wird.
            </para>

            <programlisting language="php"><![CDATA[
$query = $gdata->newNicknameQuery('bar');
$nickname = $gdata->getNicknameEntry($query);

echo 'Spitzname: ' . $nickname->nickname->name . "\n";
echo 'Eigentümer: ' . $nickname->login->username . "\n";
]]></programlisting>

            <para>
                Genau wie bei den Benutzern wird eine ServiceException geworfen wenn kein
                entsprechender Spitzname gefunden wurde und ein Fehlercode von
                <constant>Zend_Gdata_Gapps_Error::ENTITY_DOES_NOT_EXIST</constant> zurückgegeben.
                Auch das wird in <link linkend="zend.gdata.gapps.exceptions">dem Kapitel über
                    Exceptions</link> beschrieben.
            </para>
        </sect3>

        <sect3 id="zend.gdata.gapps.nicknames.retrievingUser">
            <title>Alle Spitznamen eines Benutzers erhalten</title>

            <para>
                Um alle Spitznamen zu erhalten die einem angegebenen Benutzer assoziiert sind, kann
                die bequeme <methodname>retrieveNicknames()</methodname> Methode aufgerufen werden.
            </para>

            <programlisting language="php"><![CDATA[
$feed = $gdata->retrieveNicknames('foo');

foreach ($feed as $nickname) {
    echo '  * ' . $nickname->nickname->name . "\n";
}
]]></programlisting>

            <para>
                Das erzeugt ein <classname>Zend_Gdata_Gapps_NicknameFeed</classname> Objekt welches
                jeden mit dem spezifizierten Benutzer assoziierten Spitznamen enthält.
            </para>

            <para>
                Alternativ setzt das Erstellen einer neuen
                <classname>Zend_Gdata_Gapps_NicknameQuery</classname> dessen username Eigenschaft
                auf den gewünschten Benutzer, und überträgt die Abfrage durch den Aufruf von
                <methodname>getNicknameFeed()</methodname> auf dem Service Objekt.
            </para>

            <programlisting language="php"><![CDATA[
$query = $gdata->newNicknameQuery();
$query->setUsername('foo');
$feed = $gdata->getNicknameFeed($query);

foreach ($feed as $nickname) {
    echo '  * ' . $nickname->nickname->name . "\n";
}
]]></programlisting>
        </sect3>

        <sect3 id="zend.gdata.gapps.nicknames.retrievingAll">
            <title>Empfangen aller Spitznamen in einer Domain</title>

            <para>
                Um alle Spitznamen in einerm Feed zu empfangen, muß einfach die bequeme Methode
                <methodname>retrieveAllNicknames()</methodname> aufgerufen werden.
            </para>

            <programlisting language="php"><![CDATA[
$feed = $gdata->retrieveAllNicknames();

foreach ($feed as $nickname) {
    echo '  * ' . $nickname->nickname->name . ' => ' .
        $nickname->login->username . "\n";
}
]]></programlisting>

            <para>
                Das wird ein <classname>Zend_Gdata_Gapps_NicknameFeed</classname> Objekt erstellen
                welches jeden Spitznamen in der Domain enthält.
            </para>

            <para>
                Alternativ kann <methodname>getNicknameFeed()</methodname> auf einem Service Objekt
                ohne Argumente aufgerufen werden.
            </para>

            <programlisting language="php"><![CDATA[
$feed = $gdata->getNicknameFeed();

foreach ($feed as $nickname) {
    echo '  * ' . $nickname->nickname->name . ' => ' .
        $nickname->login->username . "\n";
}
]]></programlisting>
        </sect3>

        <sect3 id="zend.gdata.gapps.nicknames.deleting">
            <title>Löschen eines Spitznamens</title>

            <para>
                Um einen Spitznamen zu löschen zu dem man bereits einen NicknameEntry hält muß
                einfach nur <methodname>delete()</methodname> auf diesem Eintrag aufgerufen werden.
            </para>

            <programlisting language="php"><![CDATA[
$nickname = $gdata->retrieveNickname('bar');
$nickname->delete();
]]></programlisting>

            <para>
                Für Spitznamen zu denen man keinen NicknameEntry hält, kann die bequeme
                <methodname>deleteNickname()</methodname> Methode verwendet werden.
            </para>

            <programlisting language="php"><![CDATA[
$gdata->deleteNickname('bar');
]]></programlisting>
        </sect3>
    </sect2>

    <sect2 id="zend.gdata.gapps.groups">
        <title>Mit Gruppen interagieren</title>

        <para>
            Google Gruppen erlauben es Personen Nachrichten zu senden so wie eine Email Liste.
            Google missbilligt die <acronym>API</acronym> der Email Listen. Google Gruppen bieten
            einige nette Features wie verschachtelte Gruppen und Gruppen Besitzer. Wenn man mit
            einer neuen Email Liste beginnen will, ist es empfehlenswert statt dessen Google Gruppen
            zu verwenden. Google's Email Liste ist nicht mit Google Gruppen kompatibel. Wenn man
            also eine Email Liste erstellt, scheint Sie nicht als Gruppe auf. Das Gegenteil ist
            natürlich genauso wahr.
        </para>

        <para>
            Jede Gruppe an einer Domain wird als Instanz von
            <classname>Zend_Gdata_Gapps_GroupEntry</classname> repräsentiert.
        </para>

        <sect3 id="zend.gdata.gapps.groups.creating">
            <title>Erstellen einer Gruppe</title>

            <para>
                Gruppen können erstellt werden indem die bequeme Methode
                <methodname>createGroup()</methodname> aufgerufen wird:
            </para>

            <programlisting language="php"><![CDATA[
$gdata->createGroup('friends', 'Freundeskreis');
]]></programlisting>

            <para>
                Gruppen können erstellt werden indem GroupEntry instanziert wird, eine Gruppen ID
                und ein Name für die Gruppe angegeben wird, und dann
                <methodname>insertGroup()</methodname> auf dem Service Objekt aufgerufen wird um den
                Eintrag zum Server hochzuladen.
            </para>

            <programlisting language="php"><![CDATA[
$group = $gdata->newGroupEntry();

$properties[0] = $this->newProperty();
$properties[0]->name = 'groupId';
$properties[0]->value = 'friends';
$properties[1] = $this->newProperty();
$properties[1]->name = 'groupName';
$properties[1]->value = 'Freundeskreis';

$group->property = $properties;

$group = $gdata->insertGroup($group);
]]></programlisting>
        </sect3>

        <sect3 id="zend.gdata.gapps.groups.retrieveGroup">
            <title>Eine individuelle Gruppe empfangen</title>

            <para>
                Um eine individuelle Gruppe zu erhalten, muss die bequeme Methode
                <methodname>retrieveGroup()</methodname> aufgerufen werden:
            </para>

            <programlisting language="php"><![CDATA[
$entry = $gdata->retrieveGroup('friends');

foreach ($entry->property as $p) {
    echo "Name der Eigenschaft: " . $p->name;
    echo "\nWert der Eigenschaft: " . $p->value . "\n\n";
}
]]></programlisting>

            <para>
                Das erstellt ein <classname>Zend_Gdata_Gapps_GroupEntry</classname> Objekt welches
                die Eigenschaften der Gruppe enthält.
            </para>

            <para>
                Alternativ kann ein neuer <classname>Zend_Gdata_Gapps_GroupQuery</classname>
                erstellt, seine groupId Eigenschaft auf die gewünschte Gruppen Id gesetzt werden,
                und die Abfrage übermittelt werden indem <methodname>getGroupEntry()</methodname>
                auf dem Service Objekt aufgerufen wird.
            </para>

            <programlisting language="php"><![CDATA[
$query = $gdata->newGroupQuery();
$query->setGroupId('friends');
$entry = $gdata->getGroupEntry($query);

foreach ($entry->property as $p) {
    echo "Name der Eigenschaft: " . $p->name;
    echo "\nWert der Eigenschaft: " . $p->value . "\n\n";
}
]]></programlisting>
        </sect3>

        <sect3 id="zend.gdata.gapps.groups.retrievingAll">
            <title>Alle Gruppen einer Domäne empfangen</title>

            <para>
                Um alle Gruppen in einer Domäne zu erhalten muss die bequeme Methode
                <methodname>retrieveAllGroups()</methodname> aufgerufen werden.
            </para>

            <programlisting language="php"><![CDATA[
$feed = $gdata->retrieveAllGroups();

foreach ($feed->entry as $entry) {
    foreach ($entry->property as $p) {
        echo "Name der Eigenschaft: " . $p->name;
        echo "\nWert der Eigenschaft: " . $p->value . "\n\n";
    }
    echo "\n\n";
}
]]></programlisting>

            <para>
                Dies erstellt ein <classname>Zend_Gdata_Gapps_GroupFeed</classname> Objekt welches
                jede Gruppe der Domain enthält.
            </para>

            <para>
                Alternativ kann <methodname>getGroupFeed()</methodname> auf einem Service Objekt
                ohne Argumente aufgerufen werden.
            </para>

            <programlisting language="php"><![CDATA[
$feed = $gdata->getGroupFeed();

foreach ($feed->entry as $entry) {
    foreach ($entry->property as $p) {
        echo "Name der Eigenschaft: " . $p->name;
        echo "\nWert der Eigenschaft: " . $p->value . "\n\n";
    }
    echo "\n\n";
}
]]></programlisting>
        </sect3>

        <sect3 id="zend.gdata.gapps.groups.deleting">
            <title>Eine Gruppe löschen</title>

            <para>
                Um eine Gruppe zu löschen kann die bequeme Methode
                <methodname>deleteGroup()</methodname> aufgerufen werden:
            </para>

            <programlisting language="php"><![CDATA[
$gdata->deleteGroup('friends');
]]></programlisting>
        </sect3>

        <sect3 id="zend.gdata.gapps.groups.updating">
            <title>Eine Gruppe aktualisieren</title>

            <para>
                Gruppen können aktualisiert werden indem die bequeme Methode
                <methodname>updateGroup()</methodname> aufgerufen wird:
            </para>

            <programlisting language="php"><![CDATA[
$gdata->updateGroup('group-id-here', 'Name der Gruppe hier');
]]></programlisting>

            <para>
                Der erste Parameter wird benötigt. Der zweite, dritte und vierte Parameter welche
                den Namen der Gruppe, die Beschreibung der Gruppe und die Email Erlaubnis
                repräsentieren, sind alle Optional. Wenn eine dieser optionalen Parameter auf null
                gesetzt wird, dann wird dieses Element nicht aktualisiert.
            </para>
        </sect3>

        <sect3 id="zend.gdata.gapps.groups.retrieve">
            <title>Empfangen aller Gruppen bei denen eine Person Mitglied ist</title>

            <para>
                Um alle Gruppen zu erhalten bei denen eine Spezielle Person Mitglied ist, kann die
                bequeme Methode <methodname>retrieveGroups()</methodname> aufgerufen werden:
            </para>

            <programlisting language="php"><![CDATA[
$feed = $gdata->retrieveGroups('baz@somewhere.com');

foreach ($feed->entry as $entry) {
    foreach ($entry->property as $p) {
        echo "Name der Eigenschaft: " . $p->name;
        echo "\nWert der Eigenschaft: " . $p->value . "\n\n";
    }
    echo "\n\n";
}
]]></programlisting>

            <para>
                Dies erstellt ein <classname>Zend_Gdata_Gapps_GroupFeed</classname> Objekt welches
                jede Gruppe enthält die mit dem spezifizierten Mitglied assoziiert ist.
            </para>

            <para>
                Alternativ kann eine neue <classname>Zend_Gdata_Gapps_GroupQuery</classname>
                erstellt werden, die Eigenschaft member auf die gewünschte Email Adresse gesetzt,
                und die Abfrage durch Aufruf von <methodname>getGroupFeed()</methodname> auf dem
                Service Objekt übermittelt werden.
            </para>

            <programlisting language="php"><![CDATA[
$query = $gdata->newGroupQuery();
$query->setMember('baz@somewhere.com');
$feed = $gdata->getGroupFeed($query);

foreach ($feed->entry as $entry) {
    foreach ($entry->property as $p) {
        echo "Name der Eigenschaft: " . $p->name;
        echo "\nWert der Eigenschaft: " . $p->value . "\n\n";
    }
    echo "\n\n";
}
]]></programlisting>
        </sect3>
    </sect2>

    <sect2 id="zend.gdata.gapps.groupMembers">
        <title>Mit Gruppenmitgliedern interagieren</title>

        <para>
            Jedes Mitglied welches bei einer Gruppe eingeschrieben ist wird durch eine Instanz von
            <classname>Zend_Gdata_Gapps_MemberEntry</classname> repräsentiert. Durch diese Klasse
            können individuelle Empfänger bei Gruppen hinzugefügt und gelöscht werden.
        </para>

        <sect3 id="zend.gdata.gapps.groupMembers.adding">
            <title>Ein Mitglied zu einer Gruppe hinzufügen</title>

            <para>
                Um ein Mitglied zu einer Gruppe hinzuzufügen muss einfach die bequeme Methode
                <methodname>addMemberToGroup()</methodname> aufgerufen werden:
            </para>

            <programlisting language="php"><![CDATA[
$gdata->addMemberToGroup('bar@somewhere.com', 'friends');
]]></programlisting>
        </sect3>

        <sect3 id="zend.gdata.gapps.groupMembers.check">
            <title>Prüfen um zu sehen ob ein Mitglied einer Gruppe angehört</title>

            <para>
                Um zu prüfen ob ein Mitglied einer Gruppe angehört, muss einfach die bequeme
                Methode <methodname>isMember()</methodname> aufgerufen werden:
            </para>

            <programlisting language="php"><![CDATA[
$isMember = $gdata->isMember('bar@somewhere.com', 'friends');
var_dump($isMember);
]]></programlisting>

            <para>
                Die Methode gibt einen Boolschen Wert zurück. Wenn das Mitglied der spezifizierten
                Gruppe angehört, gibt die Methode ein true zurück, andernfalls gibt Sie ein false
                zurück.
            </para>
        </sect3>

        <sect3 id="zend.gdata.gapps.groupMembers.removing">
            <title>Ein Mitglied von einer Gruppe entfernen</title>

            <para>
                Um ein Mitglied von einer Gruppe zu entfernen muss die bequeme Methode
                <methodname>removeMemberFromGroup()</methodname> aufgerufen werden:
            </para>

            <programlisting language="php"><![CDATA[
$gdata->removeMemberFromGroup('baz', 'friends');
]]></programlisting>
        </sect3>

        <sect3 id="zend.gdata.gapps.groupMembers.retrieving">
            <title>Die Liste der Mitglieder einer Gruppe erhalten</title>

            <para>
                Die bequeme Methode <methodname>retrieveAllMembers()</methodname> kann verwendet
                werden um die Liste der Mitglieder einer Gruppe zu erhalten:
            </para>

            <programlisting language="php"><![CDATA[
$feed = $gdata->retrieveAllMembers('friends');

foreach ($feed as $member) {
    foreach ($member->property as $p) {
        echo "Name der Eigenschaft: " . $p->name;
        echo "\nWert der Eigenschaft: " . $p->value . "\n\n";
    }
}
]]></programlisting>

            <para>
                Alternativ kann ein neuer MemberQuery erstellt, dessen Eigenschaft groupId auf die
                passende und gewünschte Gruppen Id gesetzt und
                <methodname>getMemberFeed()</methodname> auf einem Service Objekt aufgerufen werden.
            </para>

            <programlisting language="php"><![CDATA[
$query = $gdata->newMemberQuery();
$query->setGroupId('friends');
$feed = $gdata->getMemberFeed($query);

foreach ($feed as $member) {
    foreach ($member->property as $p) {
        echo "Name der Eigenschaft: " . $p->name;
        echo "\nWert der Eigenschaft: " . $p->value . "\n\n";
    }
}
]]></programlisting>

            <para>
                Das erstellt ein <classname>Zend_Gdata_Gapps_MemberFeed</classname> Objekt welches
                jedes Mitglied der ausgewählten Gruppe enthält.
            </para>
        </sect3>
    </sect2>

    <sect2 id="zend.gdata.gapps.groupOwners">
        <title>Mit Gruppen Eigentümern interagieren</title>

        <para>
            Jeder Eigentümer der mit einer Gruppe assoziiert ist wird durch eine Instanz von
            <classname>Zend_Gdata_Gapps_OwnerEntry</classname> repräsentiert. Durch diese Klasse
            können individuelle Eigentümer hinzugefügt und von Gruppen entfernt werden.
        </para>

        <sect3 id="zend.gdata.gapps.groupOwners.adding">
            <title>Einen Eigentümer einer Gruppe hinzufügen</title>

            <para>
                Um einer Gruppe einen Eigentümer hinzuzufügen muss einfach die bequeme Methode
                <methodname>addOwnerToGroup()</methodname> aufgerufen werden:
            </para>

            <programlisting language="php"><![CDATA[
$gdata->addOwnerToGroup('bar@somewhere.com', 'friends');
]]></programlisting>
        </sect3>

        <sect3 id="zend.gdata.gapps.groupOwners.retrieving">
            <title>Die Liste der Eigentümer einer Gruppe erhalten</title>

            <para>
                Die bequeme Methode <methodname>retrieveGroupOwners()</methodname> kann verwendet
                werden um die Liste der Eigentümer einer Gruppe zu erhalten:
            </para>

            <programlisting language="php"><![CDATA[
$feed = $gdata->retrieveGroupOwners('friends');

foreach ($feed as $owner) {
    foreach ($owner->property as $p) {
        echo "Name der Eigenschaft: " . $p->name;
        echo "\nWert der Eigenschaft: " . $p->value . "\n\n";
    }
}
]]></programlisting>

            <para>
                Alternativ kann ein neuer OwnerQuery erstellt, seine Eigenschaft groupId auf die
                passende und gewünschte Gruppen Id gesetzt und
                <methodname>getOwnerFeed()</methodname> auf einem Service Objekt aufgerufen werden.
            </para>

            <programlisting language="php"><![CDATA[
$query = $gdata->newOwnerQuery();
$query->setGroupId('friends');
$feed = $gdata->getOwnerFeed($query);

foreach ($feed as $owner) {
    foreach ($owner->property as $p) {
        echo "Name der Eigenschaft: " . $p->name;
        echo "\nWert der Eigenschaft: " . $p->value . "\n\n";
    }
}
]]></programlisting>

            <para>
                Das erstelle ein <classname>Zend_Gdata_Gapps_OwnerFeed</classname> Objekt welches
                jedes Mitglied der ausgewählten Gruppe enthält.
            </para>
        </sect3>

        <sect3 id="zend.gdata.gapps.groupOwners.check">
            <title>Prüfen um zu sehen ob ein Email der Eigentümer einer Gruppe ist</title>

            <para>
                Um zu prüfen ob ein Email der Eigentümer einer Gruppe ist, kann einfach die
                bequeme Methode <methodname>isOwner()</methodname> aufgerufen werden:
            </para>

            <programlisting language="php"><![CDATA[
$isOwner = $gdata->isOwner('bar@somewhere.com', 'friends');
var_dump($isOwner);
]]></programlisting>

            <para>
                Die Methode gibt einen boolschen Wert zurück. Wenn die Email der Eigentümer der
                spezifizierten Gruppe ist, gibt die Methode true zurück, andernfalls gibt sie false
                zurück.
            </para>
        </sect3>

        <sect3 id="zend.gdata.gapps.groupOwners.removing">
            <title>Einen Eigentümer von einer Gruppe entfernen</title>

            <para>
                Um einen Eigentümer von einer Gruppe zu entfernen kann die bequeme Methode
                <methodname>removeOwnerFromGroup()</methodname> aufgerufen werden:
            </para>

            <programlisting language="php"><![CDATA[
$gdata->removeOwnerFromGroup('baz@somewhere.com', 'friends');
]]></programlisting>
        </sect3>
    </sect2>

    <sect2 id="zend.gdata.gapps.emailLists">
        <title>Mit Email Listen interagieren</title>

        <para>
            Email Listen erlauben verschiedenen Benutzern Emails zu empfangen die zu einer einzelnen
            Email Adresse adressiert sind. Benutzer müssen keine Teilnehmer dieser Domain sein um
            sich in eine Email Liste einzuschreiben, wen deren komplette Email Adresse (inklusive
            Domain) verwendet wird.
        </para>

        <para>
            Jede Email Liste einer Domain wird als Instanz von
            <classname>Zend_Gdata_Gapps_EmailListEntry</classname> repräsentiert.
        </para>

        <sect3 id="zend.gdata.gapps.emailLists.creating">
            <title>Erstellen einer Email Liste</title>

            <para>
                Email Listen können durch den Aufruf der bequemen
                <methodname>createEmailList()</methodname> Methode erstellt werden:
            </para>

            <programlisting language="php"><![CDATA[
$gdata->createEmailList('friends');
]]></programlisting>

            <para>
                Email Listen können auch durch die Instanzierung von EmailListEntry erstellt werden,
                indem ein Name für die Liste angegeben wird, und anschließend
                <methodname>insertEmailList()</methodname> auf dem Service Objekt aufgerufen wird um
                den Eintrag zum Server hochzuladen.
            </para>

            <programlisting language="php"><![CDATA[
$list = $gdata->newEmailListEntry();
$list->emailList = $gdata->newEmailList('friends');
$list = $gdata->insertEmailList($list);
]]></programlisting>
        </sect3>

        <sect3 id="zend.gdata.gapps.emailList.retrieve">
            <title>Empfangen aller Email Listen bei denen ein Empfänger eingeschrieben ist</title>

            <para>
                Um alle Email Lsiten zu denen ein spezieller Empfänger eingeschrieben ist zu
                empfangen, muß die bequeme <methodname>retrieveEmailLists()</methodname> Methode
                aufgerufen werden:
            </para>

            <programlisting language="php"><![CDATA[
$feed = $gdata->retrieveEmailLists('baz@somewhere.com');

foreach ($feed as $list) {
    echo '  * ' . $list->emailList->name . "\n";
}
]]></programlisting>

            <para>
                Das erstellt ein <classname>Zend_Gdata_Gapps_EmailListFeed</classname> Objekt
                welches jede Email Liste enthält die mit dem speziellen Empfänger assoziiert ist.
            </para>

            <para>
                Alternativ kann ein neues <classname>Zend_Gdata_Gapps_EmailListQuery</classname>
                erstellt werden, dessen recipient Eigenschaft auf die gewünschte Email Adresse
                gesetzt werden, und die Abfrage durch den Aufruf von
                <methodname>getEmailListFeed()</methodname> auf dem Service Objekt übermittelt
                werden.
            </para>

            <programlisting language="php"><![CDATA[
$query = $gdata->newEmailListQuery();
$query->setRecipient('baz@somewhere.com');
$feed = $gdata->getEmailListFeed($query);

foreach ($feed as $list) {
    echo '  * ' . $list->emailList->name . "\n";
}
]]></programlisting>
        </sect3>

        <sect3 id="zend.gdata.gapps.emailLists.retrievingAll">
            <title>Empfangen aller Email Listen in einer Domain</title>

            <para>
                Um alle Email Listen in einer Domain zu erhalten, muß die bequeme
                <methodname>retrieveAllEmailLists()</methodname> Methode aufgerufen werden.
            </para>

            <programlisting language="php"><![CDATA[
$feed = $gdata->retrieveAllEmailLists();

foreach ($feed as $list) {
    echo '  * ' . $list->emailList->name . "\n";
}
]]></programlisting>

            <para>
                Das erzeugt ein <classname>Zend_Gdata_Gapps_EmailListFeed</classname> Objekt welches
                jede Email Liste der Domain enthält.
            </para>

            <para>
                Alternativ kann <methodname>getEmailListFeed()</methodname> auf dem Service Objekt
                ohne Argumente aufgerufen werden.
            </para>

            <programlisting language="php"><![CDATA[
$feed = $gdata->getEmailListFeed();

foreach ($feed as $list) {
    echo '  * ' . $list->emailList->name . "\n";
}
]]></programlisting>
        </sect3>

        <sect3 id="zend.gdata.gapps.emailList.deleting">
            <title>Löschen einer Email Liste</title>

            <para>
                Um eine Email Liste zu löschen, muß die bequeme
                <methodname>deleteEmailList()</methodname> Methode aufgerufen werden:
            </para>

            <programlisting language="php"><![CDATA[
$gdata->deleteEmailList('friends');
]]></programlisting>
        </sect3>
    </sect2>

    <sect2 id="zend.gdata.gapps.emailListRecipients">
        <title>Mit den Empfängern von Email Listen interagieren</title>

        <para>
            Jeder Empfänger der bei einer Email Liste eingeschrieben ist, wird durch eine Instanz
            von <classname>Zend_Gdata_Gapps_EmailListRecipient</classname> repräsentiert. Durch
            diese Klasse können individuelle Empfänger hinzugefügt und von Email Listen entfernt
            werden.
        </para>

        <sect3 id="zend.gdata.gapps.emailListRecipients.adding">
            <title>Einen Empfängern zu einer Email Liste hinzufügen</title>

            <para>
                Um einen Empfänger zu einer Email Liste hinzuzufügen, muß einfach die bequeme
                <methodname>addRecipientToEmailList()</methodname> Methode aufgerufen werden:
            </para>

            <programlisting language="php"><![CDATA[
$gdata->addRecipientToEmailList('bar@somewhere.com', 'friends');
]]></programlisting>
        </sect3>

        <sect3 id="zend.gdata.gapps.emailListRecipients.retrieving">
            <title>Eine Liste von Empfängern einer Email Liste erhalten</title>

            <para>
                Die bequeme <methodname>retrieveAllRecipients()</methodname> Methode kann verwendet
                werden um die Liste der Empfänger einer Email Liste zu erhalten:
            </para>

            <programlisting language="php"><![CDATA[
$feed = $gdata->retrieveAllRecipients('friends');

foreach ($feed as $recipient) {
    echo '  * ' . $recipient->who->email . "\n";
}
]]></programlisting>

            <para>
                Alternativ kann ein neuer EmailListRecipientQuery erstellt werdne, dessen
                emailListName Eigenschaft auf die gewünschte Email Liste gesetzt werden, und
                <methodname>getEmailListRecipientFeed()</methodname> auf dem Service Objekt
                aufgerufen werden.
            </para>

            <programlisting language="php"><![CDATA[
$query = $gdata->newEmailListRecipientQuery();
$query->setEmailListName('friends');
$feed = $gdata->getEmailListRecipientFeed($query);

foreach ($feed as $recipient) {
    echo '  * ' . $recipient->who->email . "\n";
}
]]></programlisting>

            <para>
                Das Erstellt ein <classname>Zend_Gdata_Gapps_EmailListRecipientFeed</classname>
                Objekt welche jeden Empfänger für die ausgewählte Email Liste enthält.
            </para>
        </sect3>

        <sect3 id="zend.gdata.gapps.emailListRecipients.removing">
            <title>Einen Empfänger von einer Email Liste entfernen</title>

            <para>
                Um einen Empfänger von einer Email Liste zu entfernen, muß die bequeme
                <methodname>removeRecipientFromEmailList()</methodname> Methode aufgerufen werden:
            </para>

            <programlisting language="php"><![CDATA[
$gdata->removeRecipientFromEmailList('baz@somewhere.com', 'friends');
]]></programlisting>
        </sect3>
    </sect2>

    <sect2 id="zend.gdata.gapps.exceptions">
        <title>Fehler handhaben</title>

        <para>
            Zusätzlich zur Standardsuite von Ausnahmen die von <classname>Zend_Gdata</classname>
            geworfen werden, können Anfragen welche die Provisionierungs <acronym>API</acronym>
            verwenden auch eine <classname>Zend_Gdata_Gapps_ServiceException</classname> werfen.
            Diese Ausnahme zeigt das ein <acronym>API</acronym> spezieller Fehler aufgetreten ist
            welche verhindert das die Anfrage fertiggestellt werden kann.
        </para>

        <para>
            Jede ServiceException Instanz kann einen oder mehrere Fehler Objekte enthalten. Jedes
            dieser Objekte enthalten einen Fehlercode, Grund und (optional) die Eingave welche die
            Ausnahme getriggert hat. Eine komplette Liste von bekannten Fehlercodes wird in der Zend
            Framework <acronym>API</acronym> Dokumentation unter
            <classname>Zend_Gdata_Gapps_Error</classname> angeboten. Zusätzlich ist die maßgebliche
            Fehlerliste online unter <ulink
                url="http://code.google.com/apis/apps/gdata_provisioning_api_v2.0_reference.html#appendix_d">Google
                Apps Provisioning <acronym>API</acronym> V2.0 Reference: Appendix D</ulink>
            vorhanden.
        </para>

        <para>
            Wärend die komplette Liste von Fehler die empfangen wurden in ServiceException als Array
            vorhanden sind das man durch den Aufruf von <methodname>getErrors()</methodname>
            erhalten kann, ist es oft bequemer zu wissen ob ein spezieller Fehler aufgetreten ist.
            Für diese Fälle kann das Vorhandensein eines Fehler durch den Aufruf von
            <methodname>hasError()</methodname> erkannt werden.
        </para>

        <para>
            Das folgende Beispiel demonstriert wie erkannt werden kann ob eine angefragte Ressource
            nicht existiert und der Fehler korrekt behandelt werden kann:
        </para>

        <programlisting language="php"><![CDATA[
function retrieveUser ($username) {
    $query = $gdata->newUserQuery($username);
    try {
        $user = $gdata->getUserEntry($query);
    } catch (Zend_Gdata_Gapps_ServiceException $e) {
        // Den Benutzer auf null setzen wen er nicht gefunden wurde
        if ($e->hasError(Zend_Gdata_Gapps_Error::ENTITY_DOES_NOT_EXIST)) {
            $user = null;
        } else {
            throw $e;
        }
    }
    return $user;
}
]]></programlisting>
    </sect2>
</sect1>