# Google Apps Provisionierung verwenden

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

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

Für weitere Information zur Google Apps Provisionierungs API, inklusive Anleitungen für das einschalten des API Zugriffs, kann in die Provisionierungs API V2.0 Referenz gesehen werden.

## Authentifizierung

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

## Die aktuelle Domain setzen

Um die Provisionierungs API zu verwenden muß die Domain, die administriert werden soll, in allen Anfrage URIs 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.

### Setzen der Domain für die Serviceklasse

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

    $domain = "example.com";
    $gdata = new Zend_Gdata_Gapps($client, $domain);

### Die Domain für die Abfrageklasse setzen

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

    $domain = "example.com";
    $query = new Zend_Gdata_Gapps_UserQuery($domain, $arg);

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.

    $domain = "example.com";
    $gdata = new Zend_Gdata_Gapps($client, $domain);
    $query = $gdata->newUserQuery($arg);

## Interaktion mit Benutzern

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

### Erstellen eines Benutzerzugangs

Benutzerzugänge können durch den Aufruf der einfachen `createUser()` Methode erstellt werden:

    $gdata->createUser('foo', 'Random', 'User', '••••••••');

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 `insertUser()` am Serviceobjekt aufgerufen wird um den Eintrag zum Server zu laden.

    $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);

Das Passwort den Benutzers sollte normalerweise als Klartext angegeben werden. Operional kann das Passwort als SHA-1 Schlüssel angegeben werden wenn `login->passwordHashFunction` auf 'SHA-1' gesetzt ist.

### Einen Benutzerzugang erhalten

Individuelle Benutzerzugänge kann man erhalten indem die einfache `retrieveUser()` Methode aufgerufen wird. Wenn der Benutzer nicht gefunden wird, wird `NULL` zurückgegeben.

    $user = $gdata->retrieveUser('foo');

    echo 'Benutzername: ' . $user->login->userName . "\n";
    echo 'Name: ' . $user->login->givenName . "\n";
    echo 'Familienname: ' . $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";

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

    $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";

Wenn der spezifizierte Benutzer nicht gefunden werden kann wird eine ServiceException mit einem Fehlercode von `Zend_Gdata_Gapps_Error::ENTITY_DOES_NOT_EXIST` geworfen. ServiceExceptions werden in behandelt.

### Alle Benutzer in einer Domain erhalten

Um alle Benutzer in einer Domäne zu erhalten kann die einfache `retrieveAllUsers()` Methode aufgerufen werden.

    $feed = $gdata->retrieveAllUsers();

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

Das wird ein `Zend_Gdata_Gapps_UserFeed` Objekt erstellen welches jeden Benutzer dieser Domain enthält.

Alternativ kann `getUserFeed()` 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 .

    $feed = $gdata->getUserFeed();

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

### Einen Benutzerzugang aktualisieren

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 `save()` auf diesem Benutzer aufzurufen. Jede gemachte Änderung wird an den Server weitergegeben.

    $user = $gdata->retrieveUser('foo');
    $user->name->givenName = 'Foo';
    $user->name->familyName = 'Bar';
    $user = $user->save();

#### Ein Benutzerpasswort resetieren

Ein Benutzerpasswort kann zu einem neuen Wert resetiert werden indem die `login->password` Eigenschaft aktualisiert wird.

    $user = $gdata->retrieveUser('foo');
    $user->login->password = '••••••••';
    $user = $user->save();

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 API verfügbar gemacht werden.

#### Einen Benutzer zwingen sein Passwort zu ändern

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

    $user = $gdata->retrieveUser('foo');
    $user->login->changePasswordAtNextLogin = true;
    $user = $user->save();

Genauso kann das rückgängig gemacht werden indem die `login->changePasswordAtNextLogin` Eigenschaft auf `FALSE` gesetzt wird.

#### Einen Benutzerzugang unterbrechen

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

    $gdata->suspendUser('foo');
    $gdata->restoreUser('foo');

Alternativ kann die Eigenschaft `login->suspended` des Benutzerzugangs auf `TRUE` gesetzt werden.

    $user = $gdata->retrieveUser('foo');
    $user->login->suspended = true;
    $user = $user->save();

Um den Benutzerzugang wiederherzustellen muß die `login->suspended` Eigenschaft auf `FALSE` gesetzt werden.

#### Administrative Rechte vergeben

Benutzern kann die Möglichkeit gegeben werden die Domain zu verwalten durch das setzen Ihrer `login->admin` Eigenschaft auf `TRUE`.

    $user = $gdata->retrieveUser('foo');
    $user->login->admin = true;
    $user = $user->save();

Und wie erwartet, entfernt das Setzen der Eigenschaft `login->admin`, des Benutzers auf `FALSE`, dessen administrative Rechte.

### Löschen eines Benutzerzugangs

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

    $user = $gdata->retrieveUser('foo');
    $user->delete();

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

    $gdata->deleteUser('foo');

## Mit Spitznamen interagieren

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.

Spitznamen werden repräsentiert als Instanz von `Zend_Gdata_Gapps_NicknameEntry`.

### Erstellen eines Spitznamens

Spitznamen können durch den Aufruf der einfachen `createNickname()` Methode erstellt werden:

    $gdata->createNickname('foo', 'bar');

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 `insertNickname()` auf einem Service Objekt aufgerufen wird, um den Eintrag zu einem Server hochzuladen.

    $nickname = $gdata->newNicknameEntry();
    $nickname->login = $gdata->newLogin('foo');
    $nickname->nickname = $gdata->newNickname('bar');
    $nickname = $gdata->insertNickname($nickname);

### Einen Spitznamen empfangen

Spitznamen können durch den Aufruf der bequemen `retrieveNickname()` Methode empfangen werden. Sie gibt `NULL` zurück wenn der Benutzer nicht gefunden wurde.

    $nickname = $gdata->retrieveNickname('bar');

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

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

    $query = $gdata->newNicknameQuery('bar');
    $nickname = $gdata->getNicknameEntry($query);

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

Genau wie bei den Benutzern wird eine ServiceException geworfen wenn kein entsprechender Spitzname gefunden wurde und ein Fehlercode von `Zend_Gdata_Gapps_Error::ENTITY_DOES_NOT_EXIST` zurückgegeben. Auch das wird in beschrieben.

### Alle Spitznamen eines Benutzers erhalten

Um alle Spitznamen zu erhalten die einem angegebenen Benutzer assoziiert sind, kann die bequeme `retrieveNicknames()` Methode aufgerufen werden.

    $feed = $gdata->retrieveNicknames('foo');

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

Das erzeugt ein `Zend_Gdata_Gapps_NicknameFeed` Objekt welches jeden mit dem spezifizierten Benutzer assoziierten Spitznamen enthält.

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

    $query = $gdata->newNicknameQuery();
    $query->setUsername('foo');
    $feed = $gdata->getNicknameFeed($query);

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

### Empfangen aller Spitznamen in einer Domain

Um alle Spitznamen in einerm Feed zu empfangen, muß einfach die bequeme Methode `retrieveAllNicknames()` aufgerufen werden.

    $feed = $gdata->retrieveAllNicknames();

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

Das wird ein `Zend_Gdata_Gapps_NicknameFeed` Objekt erstellen welches jeden Spitznamen in der Domain enthält.

Alternativ kann `getNicknameFeed()` auf einem Service Objekt ohne Argumente aufgerufen werden.

    $feed = $gdata->getNicknameFeed();

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

### Löschen eines Spitznamens

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

    $nickname = $gdata->retrieveNickname('bar');
    $nickname->delete();

Für Spitznamen zu denen man keinen NicknameEntry hält, kann die bequeme `deleteNickname()` Methode verwendet werden.

    $gdata->deleteNickname('bar');

## Mit Email Listen interagieren

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.

Jede Email Liste einer Domain wird als Instanz von `Zend_Gdata_Gapps_EmailListEntry` repräsentiert.

### Erstellen einer Email Liste

Email Listen können durch den Aufruf der bequemen `createEmailList()` Methode erstellt werden:

    $gdata->createEmailList('friends');

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

    $list = $gdata->newEmailListEntry();
    $list->emailList = $gdata->newEmailList('friends');
    $list = $gdata->insertEmailList($list);

### Empfangen aller Email Listen bei denen ein Empfänger eingeschrieben ist

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

    $feed = $gdata->retrieveEmailLists('baz@somewhere.com');

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

Das erstellt ein `Zend_Gdata_Gapps_EmailListFeed` Objekt welches jede Email Liste enthält die mit dem speziellen Empfänger assoziiert ist.

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

    $query = $gdata->newEmailListQuery();
    $query->setRecipient('baz@somewhere.com');
    $feed = $gdata->getEmailListFeed($query);

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

### Empfangen aller Email Listen in einer Domain

Um alle Email Listen in einer Domain zu erhalten, muß die bequeme `retrieveAllEmailLists()` Methode aufgerufen werden.

    $feed = $gdata->retrieveAllEmailLists();

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

Das erzeugt ein `Zend_Gdata_Gapps_EmailListFeed` Objekt welches jede Email Liste der Domain enthält.

Alternativ kann `getEmailListFeed()` auf dem Service Objekt ohne Argumente aufgerufen werden.

    $feed = $gdata->getEmailListFeed();

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

### Löschen einer Email Liste

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

    $gdata->deleteEmailList('friends');

## Mit den Empfängern von Email Listen interagieren

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

### Einen Empfängern zu einer Email Liste hinzufügen

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

    $gdata->addRecipientToEmailList('bar@somewhere.com', 'friends');

### Eine Liste von Empfängern einer Email Liste erhalten

Die bequeme `retrieveAllRecipients()` Methode kann verwendet werden um die Liste der Empfänger einer Email Liste zu erhalten:

    $feed = $gdata->retrieveAllRecipients('friends');

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

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

    $query = $gdata->newEmailListRecipientQuery();
    $query->setEmailListName('friends');
    $feed = $gdata->getEmailListRecipientFeed($query);

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

Das Erstellt ein `Zend_Gdata_Gapps_EmailListRecipientFeed` Objekt welche jeden Empfänger für die ausgewählte Email Liste enthält.

### Einen Empfänger von einer Email Liste entfernen

Um einen Empfänger von einer Email Liste zu entfernen, muß die bequeme `removeRecipientFromEmailList()` Methode aufgerufen werden: method:

    $gdata->removeRecipientFromEmailList('baz@somewhere.com', 'friends');

## Fehler handhaben

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

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 API Dokumentation unter `Zend_Gdata_Gapps_Error` angeboten. Zusätzlich ist die maßgebliche Fehlerliste online unter Google Apps Provisioning API V2.0 Reference: Appendix D vorhanden.

Wärend die komplette Liste von Fehler die empfangen wurden in ServiceException als Array vorhanden sind das man durch den Aufruf von `getErrors()` 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 `hasError()` erkannt werden.

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

    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;
    }