Die Directory API bietet programmatische Methoden zum Erstellen, Aktualisieren und Löschen von Nutzern. Sie können auch Informationen zu einzelnen Nutzern oder Listen von Nutzern abrufen, die bestimmte Kriterien erfüllen. Im Folgenden finden Sie Beispiele für einige grundlegende Nutzeraktionen.
Nutzerkonto erstellen
Sie können einer beliebigen Domain Ihres Google Workspace-Kontos ein Nutzerkonto hinzufügen. Bevor Sie ein Nutzerkonto hinzufügen, müssen Sie die Domaininhaberschaft bestätigen.
Wenn Sie Ihr privates Gmail-Konto auf ein geschäftliches E-Mail-Konto mit Ihrem eigenen Domainnamen umgestellt haben, können Sie erst dann neue Nutzerkonten erstellen, wenn Sie zusätzliche Google Workspace-Einstellungen freischalten. Weitere Informationen finden Sie unter G Suite-Konten für geschäftliche E-Mail-Adressen wurden auf G Suite Basic umgestellt.
Wenn Sie ein Nutzerkonto mit einer Ihrer Domains erstellen möchten, verwenden Sie die folgende POST-Anfrage und fügen Sie die in Authentifizierung und Autorisierung beschriebene Autorisierung ein. Die verfügbaren Bereiche für die Directory API finden Sie in der Liste der OAuth 2.0-Bereiche. Informationen zu den Eigenschaften des Anfrage-Suchstrings findest du in der Methode users.insert().
POST https://admin.googleapis.com/admin/directory/v1/users
Bei allen Erstellungsanfragen müssen Sie die Informationen einreichen, die zur Bearbeitung der Anfrage erforderlich sind. Wenn Sie Clientbibliotheken verwenden, werden die Datenobjekte aus der von Ihnen ausgewählten Sprache in JSON-Datenformate konvertiert.
JSON-Anfrage
Die folgende JSON-Datei zeigt eine Beispielanfrage zum Erstellen eines Nutzers. Eine vollständige Liste der Anfrage- und Antworteigenschaften finden Sie in der API-Referenz.
{ "primaryEmail": "liz@example.com", "name": { "givenName": "Elizabeth", "familyName": "Smith" }, "suspended": false, "password": "new user password", "hashFunction": "SHA-1", "changePasswordAtNextLogin": false, "ipWhitelisted": false, "ims": [ { "type": "work", "protocol": "gtalk", "im": "liz_im@talk.example.com", "primary": true } ], "emails": [ { "address": "liz@example.com", "type": "home", "customType": "", "primary": true } ], "addresses": [ { "type": "work", "customType": "", "streetAddress": "1600 Amphitheatre Parkway", "locality": "Mountain View", "region": "CA", "postalCode": "94043" } ], "externalIds": [ { "value": "12345", "type": "custom", "customType": "employee" } ], "organizations": [ { "name": "Google Inc.", "title": "SWE", "primary": true, "type": "work", "description": "Software engineer" } ], "phones": [ { "value": "+1 nnn nnn nnnn", "type": "work" } ], "orgUnitPath": "/corp/engineering", "includeInGlobalAddressList": true }
Wenn die Abfragerate für Erstellungsanfragen zu hoch ist, erhalten Sie möglicherweise HTTP-503-Antworten vom API-Server, die darauf hinweisen, dass Ihr Kontingent überschritten wurde. Wenn Sie diese Antworten erhalten, verwenden Sie einen exponentiellen Backoff-Algorithmus, um Ihre Anfragen zu wiederholen.
Beachten Sie Folgendes, wenn Sie ein neues Konto erstellen:
- Wenn für das Google-Konto E-Mail-Lizenzen erworben wurden, wird dem neuen Nutzerkonto automatisch ein Postfach zugewiesen. Es kann einige Minuten dauern, bis die Zuweisung abgeschlossen und aktiviert ist.
- Das Bearbeiten eines schreibgeschützten Felds in einer Anfrage, z. B.
isAdmin, wird vom API-Dienst ignoriert. - Die maximale Anzahl von Domains in einem Konto beträgt 600 (1 primäre Domain + 599 zusätzliche Domains).
- Wenn einem Nutzer beim Erstellen des Nutzerkontos keine bestimmte Organisationseinheit zugewiesen wurde, befindet sich das Konto in der übergeordneten Organisationseinheit. Die Organisationseinheit eines Nutzers bestimmt, auf welche Google Workspace-Dienste der Nutzer Zugriff hat. Wenn der Nutzer zu einer neuen Organisation verschoben wird, ändert sich sein Zugriff. Weitere Informationen zu Organisationsstrukturen finden Sie in der Verwaltungshilfe. Weitere Informationen zum Verschieben eines Nutzers in eine andere Organisation finden Sie unter Nutzer aktualisieren.
- Für neue Nutzerkonten ist ein
passworderforderlich. WennhashFunctionangegeben ist, muss das Passwort ein gültiger Hash-Schlüssel sein. Wenn dies nicht angegeben ist, sollte das Passwort im Klartext und zwischen 8 und 100 ASCII-Zeichen lang sein. Weitere Informationen finden Sie in der API-Referenz. - Wenn Sie einen flexiblen Google Workspace-Tarif haben, hat das Erstellen von Nutzern mit dieser API finanzielle Auswirkungen und führt zu Abbuchungen von Ihrem Kundenrechnungskonto. Weitere Informationen finden Sie in den Abrechnungsinformationen für APIs.
- Ein Google Workspace-Konto kann beliebige Domains enthalten. In einem Konto mit mehreren Domains können Nutzer in einer Domain Dienste mit Nutzern in anderen Kontodomains teilen. Weitere Informationen zu Nutzern in mehreren Domains finden Sie unter Informationen zur API für mehrere Domains.
- Möglicherweise gibt es in Konflikt stehende Konten. Prüfen Sie, ob die Personen, die Sie hinzufügen möchten, bereits ein Google-Konto haben. Führen Sie dann die folgenden Schritte aus, um Konflikte mit diesen Konten zu vermeiden. Weitere Informationen finden Sie unter In Konflikt stehende Konten.
- Es kann Besucherkonten geben. Wenn Nutzer Personen außerhalb Ihrer Organisation, die kein Google-Konto haben, zu einer Gruppenarbeit in Drive einladen, erhalten diese Besucherkonten im Format „Nutzername_des_Besucherkontos@Ihre_Domain.de“. Wenn Sie einen Nutzer mit demselben Nutzernamen wie ein Besucherkonto hinzufügen, wird das Konto in ein vollwertiges Google Workspace-Konto umgewandelt. Die aktuellen Berechtigungen des Kontos für Drive-Dateien bleiben erhalten. Weitere Informationen finden Sie im Hilfeartikel Dokumente für Besucher freigeben.
Bei einer erfolgreichen Antwort wird der HTTP-Statuscode 200 zurückgegeben. Zusammen mit dem Statuscode werden in der Antwort die Eigenschaften für das neue Nutzerkonto zurückgegeben.
Nutzerkonto aktualisieren
Wenn Sie ein Nutzerkonto aktualisieren möchten, verwenden Sie die folgende PUT-Anfrage und fügen Sie die in Anfragen autorisieren beschriebene Autorisierung ein. userKey kann die primäre E-Mail-Adresse des Nutzers, die eindeutige Nutzer-ID id oder eine der Alias-E-Mail-Adressen des Nutzers sein.
PUT https://admin.googleapis.com/admin/directory/v1/users/userKey
Sowohl der Anfrage- als auch der Antworttext enthalten eine Instanz von User. Die Directory API unterstützt jedoch Patch-Semantik. Sie müssen also nur die aktualisierten Felder in Ihrer Anfrage einreichen.
Beispielanfrage
Im folgenden Beispiel lautete die givenName des Nutzers „Elisabeth“, als das Nutzerkonto erstellt wurde, und es wurde nur eine geschäftliche E-Mail-Adresse angegeben.
{
"name": {
"givenName": "Elizabeth",
"familyName": "Smith"
},
"emails": [
{
"address": "liz@example.com",
"type": "work",
"primary": true
}
}
Mit der folgenden Anfrage wird givenName von „Elizabeth“ in „Liz“ geändert und es wird eine private E-Mail-Adresse hinzugefügt. Da es sich bei dem Feld um ein Array handelt, werden beide E-Mail-Adressen vollständig angegeben.
PUT https://admin.googleapis.com/admin/directory/v1/users/liz@example.com
{
"name": {
"givenName": "Liz",
},
"emails": [
{
"address": "liz@example.com",
"type": "work",
"primary": true
},
{
"address": "liz@home.com",
"type": "home"
}
]
}
Eine erfolgreiche Antwort gibt den Statuscode HTTP 200 und die Ressource User mit den aktualisierten Feldern zurück.
Beachten Sie Folgendes, wenn Sie den Kontonamen eines Nutzers aktualisieren:
- Wenn Sie ein Nutzerkonto umbenennen, ändert sich die primäre E-Mail-Adresse des Nutzers und die Domain, die beim Abrufen der Informationen dieses Nutzers verwendet wird. Bevor Sie einen Nutzer umbenennen, sollten Sie ihn von allen Browsersitzungen und ‑diensten abmelden.
- Es kann bis zu 10 Minuten dauern, bis die Umbenennung eines Nutzerkontos für alle Dienste übernommen wurde.
- Wenn Sie einen Nutzer umbenennen, wird der alte Nutzername als Alias beibehalten, um bei E-Mail-Weiterleitungseinstellungen eine unterbrechungsfreie E-Mail-Zustellung zu gewährleisten. Er ist nicht als neuer Nutzername verfügbar.
- Im Allgemeinen empfehlen wir auch, die E-Mail-Adresse des Nutzers nicht als Schlüssel für persistente Daten zu verwenden, da sich die E-Mail-Adresse ändern kann.
- Eine vollständige Liste der Auswirkungen der Umbenennung eines Nutzers in Google Workspace-Apps finden Sie in der Administrator-Hilfe.
Nutzer als Administrator festlegen
Wenn Sie einen Nutzer zum Super Admin machen möchten, verwenden Sie die folgende POST-Anfrage und fügen Sie die in Anfragen autorisieren beschriebene Autorisierung ein. userKey kann die primäre E-Mail-Adresse des Nutzers, die eindeutige Nutzer-ID id oder eine der Alias-E-Mail-Adressen des Nutzers sein. Informationen zu den Anfrage- und Antworteigenschaften finden Sie in der API-Referenz. Weitere Informationen zu Super Admins finden Sie in der Hilfe zur Verwaltung.
POST https://admin.googleapis.com/admin/directory/v1/users/userKey/makeAdminJSON-Anfrage
In diesem Beispiel ist der Nutzer mit der userKey liz@beispiel.de zum Super Admin geworden:
POST https://admin.googleapis.com/admin/directory/v1/users/liz@example.com/makeAdmin
{
"status": true
}Bei einer erfolgreichen Antwort wird der HTTP-Statuscode 200 zurückgegeben.
Nutzerbeziehungen verwalten
In der Directory API wird das Feld relations verwendet, um verschiedene Arten von Beziehungen zwischen Nutzern zu definieren. In einem geschäftlichen Umfeld wird dieses Feld häufig für die Beziehung zwischen Vorgesetzten und Mitarbeitern oder Assistenten verwendet, es unterstützt aber auch viele andere Arten. Die Beziehung wird in der Karte „Verwandte Personen“ des Nutzers in jeder Google Workspace-Anwendung angezeigt, die die Karte unterstützt. Beispiele dafür, wo die Karte zu sehen ist, finden Sie im Hilfeartikel Dem Verzeichnisprofil eines Nutzers Informationen hinzufügen.
Eine Beziehung zwischen Nutzern aufbauen
Sie können eine Beziehung nur in eine Richtung definieren, beginnend mit dem „zugehörigen“ Nutzer, dessen Datensatz das Feld relations enthält. Mit type wird die Beziehung der anderen Person zum Inhaber des Kontos beschrieben. Angenommen, in einem Verhältnis zwischen Vorgesetzten und Mitarbeitern ist der Mitarbeiter der Inhaber des Kontos und Sie fügen seinem Konto ein relations-Feld vom Typ manager hinzu. Zulässige Typen finden Sie in der Objektreferenz für User.
Richten Sie die Beziehung ein, indem Sie den Eigentümer erstellen oder aktualisieren. Verwenden Sie dazu einen JSON-Anfragetext mit dem Feld relations.
Sie können in einer Anfrage mehrere Beziehungen erstellen.
{
"relations": [
{
"value": "EMAIL_ADDRESS_RELATION_1",
"type": "manager"
},
{
"value": "EMAIL_ADDRESS_RELATION_2",
"type": "dotted_line_manager"
}
]
}
Beziehung aktualisieren oder löschen
Das Feld relations kann nur als Ganzes aktualisiert werden. Sie können nicht auf die einzelnen Personen zugreifen, um den Beziehungstyp zu ändern oder sie zu entfernen. Wenn Sie im Beispiel oben die bestehende Verwaltungsbeziehung entfernen und das Verwaltungskonto mit der gestrichelten Linie zum Verwaltungskonto des Inhabers machen möchten, aktualisieren Sie das Konto des Inhabers mit allen gewünschten Werten für das Feld.
{
"relations": [
{
"value": "EMAIL_ADDRESS_RELATION_2",
"type": "manager"
}
]
}
Wenn Sie alle Beziehungen des Inhabers entfernen möchten, lassen Sie relations leer:
{
"relations": []
}
Nutzer abrufen
Wenn Sie einen Nutzer abrufen möchten, verwenden Sie die folgende GET-Anfrage und fügen Sie die in Anfragen autorisieren beschriebene Autorisierung ein. userKey kann die primäre E-Mail-Adresse des Nutzers, die eindeutige Nutzer-ID id oder eine der Alias-E-Mail-Adressen des Nutzers sein. Informationen zu den Anfrage- und Antworteigenschaften finden Sie in der API-Referenz.
GET https://admin.googleapis.com/admin/directory/v1/users/userKeyIn diesem Beispiel werden die Nutzerkontoeigenschaften für den Nutzer zurückgegeben, dessen primäre oder Alias-E-Mail-Adresse liz@beispiel.de lautet:
GET https://admin.googleapis.com/admin/directory/v1/users/liz@example.com
JSON-Antwort
Bei einer erfolgreichen Antwort wird der HTTP-Statuscode 200 zurückgegeben. Zusammen mit dem Statuscode werden in der Antwort die Eigenschaften für das Nutzerkonto zurückgegeben.
{ "kind": "directory#user", "id": "the unique user id", "primaryEmail": "liz@example.com", "name": { "givenName": "Liz", "familyName": "Smith", "fullName": "Liz Smith" }, "isAdmin": true, "isDelegatedAdmin": false, "lastLoginTime": "2013-02-05T10:30:03.325Z", "creationTime": "2010-04-05T17:30:04.325Z", "agreedToTerms": true, "hashFunction": "SHA-1", "suspended": false, "changePasswordAtNextLogin": false, "ipWhitelisted": false, "ims": [ { "type": "work", "protocol": "gtalk", "im": "lizim@talk.example.com", "primary": true } ], "emails": [ { "address": "liz@example.com", "type": "home", "customType": "", "primary": true } ], "addresses": [ { "type": "work", "customType": "", "streetAddress": "1600 Amphitheatre Parkway", "locality": "Mountain View", "region": "CA", "postalCode": "94043" } ], "externalIds": [ { "value": "employee number", "type": "custom", "customType": "office" } ], "organizations": [ { "name": "Google Inc.", "title": "SWE", "primary": true, "customType": "", "description": "Software engineer" } ], "phones": [ { "value": "+1 nnn nnn nnnn", "type": "work" } ], "aliases": [ "lizsmith@example.com", "lsmith@example.com" ], "nonEditableAliases": [ "liz@test.com" ], "customerId": "C03az79cb", "orgUnitPath": "corp/engineering", "isMailboxSetup": true, "includeInGlobalAddressList": true }
Alle Nutzer in einer Domain abrufen
Wenn Sie alle Nutzer in derselben Domain abrufen möchten, verwenden Sie die folgende GET-Anfrage und fügen Sie die in Anfragen autorisieren beschriebene Autorisierung ein. Zur besseren Lesbarkeit enthält dieses Beispiel Zeilenumbrüche:
GET https://admin.googleapis.com/admin/directory/v1/users ?domain=primary domain name&pageToken=token for next results page &maxResults=max number of results per page &orderBy=email, givenName, or familyName &sortOrder=ascending or descending &query=email, givenName, or familyName:the query's value*
Informationen zu den Anfrage- und Antworteigenschaften finden Sie in der API-Referenz.
JSON-Antwort
In diesem Beispiel werden alle Nutzer in der Domain beispiel.de zurückgegeben, wobei maximal zwei Nutzerdomains pro Antwortseite zurückgegeben werden. In dieser Antwort gibt es eine nextPageToken für die nachfolgende Liste der Nutzer. Standardmäßig gibt das System eine Liste mit 100 Nutzern in alphabetischer Reihenfolge der E-Mail-Adresse des Nutzers zurück:
GET https://admin.googleapis.com/admin/directory/v1/users?domain=example.com&maxResults=2
Bei einer erfolgreichen Antwort wird der HTTP-Statuscode 200 zurückgegeben. Neben dem Statuscode gibt die Antwort zwei Nutzerkonten in der Domain beispiel.de (maxResults=2) zurück:
{ "kind": "directory#users", "users": [ { "kind": "directory#user", "id": "the unique user id", "primaryEmail": "liz@example.com", "name": { "givenName": "Liz", "familyName": "Smith", "fullName": "Liz Smith" }, "isAdmin": true, "isDelegatedAdmin": false, "lastLoginTime": "2013-02-05T10:30:03.325Z", "creationTime": "2010-04-05T17:30:04.325Z", "agreedToTerms": true, "hashFunction": "SHA-1", "suspended": false, "changePasswordAtNextLogin": false, "ipWhitelisted": false, "ims": [ { "type": "work", "protocol": "gtalk", "im": "lizim@talk.example.com", "primary": true } ], "emails": [ { "address": "liz@example.com", "type": "work", "customType": "", "primary": true } ], "addresses": [ { "type": "work", "customType": "", "streetAddress": "1600 Amphitheatre Parkway", "locality": "Mountain View", "region": "CA", "postalCode": "94043" } ], "externalIds": [ { "value": "employee number", "type": "custom", "customType": "office" } ], "organizations": [ { "name": "Google Inc.", "title": "SWE", "primary": true, "customType": "", "description": "Software engineer" } ], "phones": [ { "value": "+1 nnn nnn nnnn", "type": "work" } ], "aliases": [ "lizsmith@example.com", "lsmith@example.com" ], "nonEditableAliases": [ "liz@test.com" ], "customerId": "C03az79cb", "orgUnitPath": "corp/engineering", "isMailboxSetup": true, "includeInGlobalAddressList": true }, { "kind": "directory#user", "id": "user unique ID", "primaryEmail": "admin2@example.com", "name": { "givenName": "admin", "familyName": "two", "fullName": "admin two" }, "isAdmin": true, "isDelegatedAdmin": true, "lastLoginTime": "2013-02-05T10:30:03.325Z", "creationTime": "2010-04-05T17:30:04.325Z", "agreedToTerms": true, "hashFunction": "SHA-1", "suspended": true, "suspensionReason": "ADMIN", "changePasswordAtNextLogin": false, "ipWhitelisted": false, "emails": [ { "address": "admin2@example.com", "type": "work", "customType": "", "primary": true } ], "externalIds": [ { "value": "contractor license number", "type": "custom", "customType": "work" } ], "aliases": [ "second_admin@example.com" ], "nonEditableAliases": [ "admin@test.com" ], "customerId": "C03az79cb", "orgUnitPath": "corp/engineering", "isMailboxSetup": true, "includeInGlobalAddressList": true } ], "nextPageToken": "next page token" }
Alle Kontonutzer abrufen
Wenn Sie alle Nutzer in einem Konto abrufen möchten, das aus mehreren Domains bestehen kann, verwenden Sie die folgende GET-Anfrage und fügen Sie die in Anfragen autorisieren beschriebene Autorisierung ein. Zur besseren Lesbarkeit enthält dieses Beispiel Zeilenumbrüche:
GET https://admin.googleapis.com/admin/directory/v1/users ?customer=my_customer or customerId&pageToken=token for next results page &maxResults=max number of results per page &orderBy=email, givenName, or familyName &sortOrder=ascending or descending &query=user attributes
- Der
customer-Suchstring ist dermy_customer- odercustomerId-Wert. - Verwenden Sie den String
my_customerfür diecustomerIdIhres Kontos. - Verwenden Sie als Reseller-Administrator die
customerIddes Kunden, dem Sie das Produkt weiterverkauft haben. Verwenden Sie für diecustomerIdden primären Domainnamen des Kontos in der Anfrage des Vorgangs Alle Nutzer in einer Domain abrufen. Die resultierende Antwort enthält den WertcustomerId. - Mit dem optionalen Abfragestring
orderBywird festgelegt, ob die Liste nach der primären E-Mail-Adresse, dem Nachnamen oder dem Vornamen des Nutzers sortiert wird. Wenn SieorderByverwenden, können Sie auch den AbfragestringsortOrderverwenden, um die Ergebnisse in aufsteigender oder absteigender Reihenfolge aufzulisten. - Mit dem optionalen Abfragestring
querykönnen Sie in vielen Feldern in einem Nutzerprofil suchen, einschließlich Kern- und benutzerdefinierter Felder. Beispiele finden Sie unter Nach Nutzern suchen.
Informationen zu den Anfrage- und Antworteigenschaften finden Sie in der API-Referenz.
In diesem Beispiel fordert ein Kontoadministrator an, dass alle Nutzer im Konto mit einem Nutzereintrag auf jeder Antwortseite zurückgegeben werden. Über die nextPageToken gelangen Sie zur nächsten Ergebnisseite:
GET https://admin.googleapis.com/admin/directory/v1/users?customer=my_customer&maxResults=1
In diesem Beispiel fordert ein Reseller-Administrator alle Nutzer in einem Reseller-Konto an, für das customerId den Wert C03az79cb hat.
GET https://admin.googleapis.com/admin/directory/v1/users?customer=C03az79cb&maxResults=1
JSON-Antwort
Bei einer erfolgreichen Antwort wird der HTTP-Statuscode 200 zurückgegeben. Zusammen mit dem Statuscode werden in der Antwort alle Nutzer in diesem Konto zurückgegeben:
{ "kind": "directory#users", "users": [ { "kind": "directory#user", "id": "the unique user id", "username": "admin2@example.com", "name": { "givenName": "admin", "familyName": "two", "fullName": "admin two" }, "isAdmin": true, "isDelegatedAdmin": true, "lastLoginTime": "2013-02-05T10:30:03.325Z", "creationTime": "2010-04-05T17:30:04.325Z", "agreedToTerms": true, "hashFunction": "SHA-1", "suspended": false, "changePasswordAtNextLogin": false, "ipWhitelisted": false, "emails": [ { "address": "admin2@example.com", "type": "work", "customType": "", "primary": true } ], "externalIds": [ { "value": "employee number", "type": "custom", "customType": "office" } ], "aliases": [ "second_admin@example.com" ], "nonEditableAliases": [ "another_admin@test.com" ], "customerId": "C03az79cb", "orgUnitPath": "/", "isMailboxSetup": true, "includeInGlobalAddressList": true }, { "kind": "directory#user", "id": "the unique user id", "username": "liz@example.com", "name": { "givenName": "Elizabeth", "familyName": "Smith", "fullName": "Elizabeth Smith" }, "isAdmin": false, "isDelegatedAdmin": false, "lastLoginTime": "1336509883546", "creationTime": "1404802800000", "agreedToTerms": false, "hashFunction": "SHA-1", "suspended": false, "changePasswordAtNextLogin": false, "ipWhitelisted": false, "emails": [ { "address": "liz@example.com", "type": "home", "customType": "", "primary": true } ], "externalIds": [ { "value": "employee number", "type": "custom", "customType": "bank" } ], "relations": [ { "value": "liz", "type": "friend", "customType": "" } ], "aliases": [ "lizsmith@example.com", "lsmith@example.com" ], "nonEditableAliases": [ "liz@test.com" ], "customerId": "C03az79cb", "orgUnitPath": "/", "isMailboxSetup": true, "includeInGlobalAddressList": true }, { "kind": "directory#user", "id": "the unique user id", "username": "test3@example.com", "name": { "givenName": "Tester", "familyName": "Three", "fullName": "Tester Three" }, "isAdmin": false, "isDelegatedAdmin": false, "lastLoginTime": "1336509883546", "creationTime": "1404802800000", "agreedToTerms": true, "hashFunction": "SHA-1", "suspended": false, "changePasswordAtNextLogin": false, "ipWhitelisted": false, "emails": [ { "address": "test@example.com", "type": "work", "customType": "", "primary": true } ], "externalIds": [ { "value": "employee number", "type": "custom", "customType": "office" } ], "aliases": [ "tester3@example.com" ], "nonEditableAliases": [ "third@test.com" ], "customerId": "C03az79cb", "orgUnitPath": "/", "isMailboxSetup": true, "includeInGlobalAddressList": true }, { "kind": "directory#user", "id": "the unique user id", "username": "work_admin@example.com", "name": { "givenName": "Admin", "familyName": "Work", "fullName": "Admin Work" }, "isAdmin": true, "isDelegatedAdmin": true, "lastLoginTime": "1336509883546", "creationTime": "1404802800000", "agreedToTerms": true, "hashFunction": "SHA-1", "suspended": false, "changePasswordAtNextLogin": false, "ipWhitelisted": false, "emails": [ { "address": "work_admin@example.com", "type": "work", "customType": "", "primary": true } ], "externalIds": [ { "value": "employee number", "type": "custom", "customType": "office" } ], "aliases": [ "my_alias@example.com" ], "nonEditableAliases": [ "other_alias@test.com" ], "customerId": "C03az79cb", "orgUnitPath": "/", "isMailboxSetup": true, "includeInGlobalAddressList": true } ], "nextPageToken": "NNNNN" }
Kürzlich gelöschte Nutzer wiederherstellen
Wenn Sie alle Nutzer abrufen möchten, die innerhalb der letzten 20 Tage aus einem Konto oder aus einer der Domains des Kontos gelöscht wurden, verwenden Sie die folgenden GET-Anfragen und fügen Sie die in Anfragen autorisieren beschriebene Autorisierung ein. Informationen zum Wiederherstellen eines Nutzers finden Sie unter Nutzer wiederherstellen.
Wenn Sie Nutzer abrufen möchten, die innerhalb der letzten 20 Tage aus der Hauptdomain oder einer Subdomain des Kontos gelöscht wurden, verwenden Sie die folgende GET-Anfrage. Der domain-Suchstring ist der primäre Domainname der Domain. Informationen zu den Eigenschaften für Nutzeranfragen und ‑antworten finden Sie in der API-Referenz. Zur besseren Lesbarkeit enthält dieses Beispiel Zeilenumbrüche:
GET https://admin.googleapis.com/admin/directory/v1/users ?domain=primary domain name&pageToken=token for next results page &maxResults=max number of results per page &showDeleted=true
GET-Anfrage abrufen. Zur besseren Lesbarkeit enthält dieses Beispiel Zeilenumbrüche:
GET https://admin.googleapis.com/admin/directory/v1/users ?customer=my_customer or customerId&pageToken=token for next results page &maxResults=max number of results per page&showDeleted=true
- Der
customer-Suchstring ist dermy_customer- odercustomerId-Wert. - Als Kontoadministrator können Sie den String
my_customerverwenden, um diecustomerIdIhres Kontos anzugeben. - Verwenden Sie als Reseller-Administrator die
customerIddes Kunden, dem Sie das Produkt weiterverkauft haben. Verwenden Sie für diecustomerIdden primären Domainnamen des Kontos in der Anfrage des Vorgangs Alle Nutzer in einer Domain abrufen. Die resultierende Antwort enthält den WertcustomerId.
Informationen zu den Anfrage- und Antworteigenschaften finden Sie in der API-Referenz.
In diesem Beispiel fordert ein Kontoadministrator alle gelöschten Nutzer im Konto an:
GET https://admin.googleapis.com/admin/directory/v1/users?customer=my_customer&showDeleted=true
JSON-Antwort
Bei einer erfolgreichen Antwort wird der HTTP-Statuscode 200 zurückgegeben. Neben dem Statuscode werden in der Antwort alle Nutzer zurückgegeben, die innerhalb der letzten 20 Tage gelöscht wurden:
{ "kind": "directory#users", "users": [ { "kind": "directory#user", "id": "the unique user id", "primaryEmail": "user1@example.com" }, { "kind": "directory#user", "id": "the unique user id", "primaryEmail": "user3@example.com" } ], "nextPageToken": "token for next page of deleted users" }
Profilbild eines Nutzers abrufen
Die API ruft eine Fotominiaturansicht ab, das aktuelle Google-Profilbild. Wenn Sie das aktuelle Foto des Nutzers abrufen möchten, verwenden Sie die folgende GET-Anfrage und fügen Sie die in Anfragen autorisieren beschriebene Autorisierung ein. userKey kann die primäre E-Mail-Adresse des Nutzers, der Nutzer id oder einer der E-Mail-Aliasse des Nutzers sein. Informationen zu den Anfrage- und Antworteigenschaften finden Sie in der API-Referenz.
GET https://admin.googleapis.com/admin/directory/v1/users/userKey/photos/thumbnailIn diesem Beispiel wird das neueste Foto von liz@beispiel.de zurückgegeben:
GET https://admin.googleapis.com/admin/directory/v1/users/liz@example.com/photos/thumbnail
JSON-Antwort
Bei einer erfolgreichen Antwort wird der HTTP-Statuscode 200 zurückgegeben.
{ "kind": "directory#user#photo", "id": "the unique user id", "primaryEmail": "liz@example.com", "mimeType": "the photo mime type", "height": "the photo height in pixels", "width": "the photo width in pixels", "photoData": "web safe base64 encoded photo data" }
Die websichere Base64-Codierung Ihrer Fotos durch die API ähnelt der Base64url-Codierung gemäß RFC 4648. Das bedeutet:
- Der Schrägstrich (/) wird durch den Unterstrich (_) ersetzt.
- Das Pluszeichen (+) wird durch den Bindestrich (-) ersetzt.
- Das Gleichheitszeichen (=) wird durch das Sternchen (*) ersetzt.
- Für das Padding wird das Punktzeichen (.) anstelle des Gleichheitszeichens (=) verwendet, das in der RFC-4648-Definition für die baseURL verwendet wird. Das vereinfacht das URL-Parsen.
- Unabhängig von der Größe des hochgeladenen Fotos wird es von der API proportional auf 96 × 96 Pixel verkleinert.
Wenn Sie kompatible Links aus JavaScript erstellen möchten, enthält die Google Closure Library Base64-Codierungs- und Dekodierungsfunktionen, die unter der Apache-Lizenz veröffentlicht werden.
Nutzer als Nutzer mit eingeschränkten Zugriff abrufen
Nutzerkonten können nur von Administratoren geändert werden, Nutzerprofile jedoch von allen Nutzern in der Domain gelesen werden. Nicht-Administratoren können eine users.get- oder users.list-Anfrage mit dem Parameter viewType = domain_public senden, um das öffentliche Profil eines Nutzers abzurufen. Der Umfang https://www.googleapis.com/auth/admin.directory.user.readonly ist für diesen Anwendungsfall ideal.
In der Ansicht domain_public können Nutzer, die keine Administratoren sind, auf einen Standardsatz von Kernfeldern zugreifen. Bei einem benutzerdefinierten Feld können Sie beim Definieren des Schemas auswählen, ob es öffentlich oder privat sein soll.
Foto eines Nutzers aktualisieren
Wenn Sie das Foto eines Nutzers aktualisieren möchten, verwenden Sie die folgende PUT-Anfrage und fügen Sie die in Anfragen autorisieren beschriebene Autorisierung ein. userKey kann die primäre E-Mail-Adresse des Nutzers, die E-Mail-Adresse des Nutzers id oder eine der E-Mail-Adressen der Nutzeraliasse sein. Informationen zu den Anfrage- und Antworteigenschaften finden Sie in der API-Referenz.
PUT https://admin.googleapis.com/admin/directory/v1/users/userKey/photos/thumbnailIn diesem Beispiel wird das Foto von liz@beispiel.de aktualisiert:
PUT https://admin.googleapis.com/admin/directory/v1/users/liz@example.com/photos/thumbnail
{
"photoData": "web safe base64 encoded photo data"
}Beim Aktualisieren eines Fotos werden height und width von der API ignoriert.
JSON-Antwort
Bei einer erfolgreichen Antwort wird der HTTP-Statuscode 200 zurückgegeben.
{ "kind": "directory#user#photo", "id": "the unique user id", "primaryEmail": "liz@example.com", "mimeType": "the photo mime type", "height": "the photo height in pixels", "width": "the photo width in pixels", "photoData": "web safe base64 encoded photo data" }
Foto eines Nutzers löschen
Wenn Sie das Foto eines Nutzers löschen möchten, verwenden Sie die folgende DELETE-Anfrage und fügen Sie die in Anfragen autorisieren beschriebene Autorisierung ein. userKey kann die primäre E-Mail-Adresse des Nutzers, die E-Mail-Adresse des Nutzers id oder eine der E-Mail-Adressen der Nutzeraliasse sein. Informationen zu den Anfrage- und Antworteigenschaften finden Sie in der API-Referenz.
DELETE https://admin.googleapis.com/admin/directory/v1/users/userKey/photos/thumbnailNach dem Löschen wird das Foto des Nutzers nicht mehr angezeigt. Wo immer ein Nutzerbild erforderlich ist, wird stattdessen eine Silhouette angezeigt.
Nutzerkonto löschen
Wenn Sie ein Nutzerkonto löschen möchten, verwenden Sie die folgende DELETE-Anfrage und fügen Sie die in Anfragen autorisieren beschriebene Autorisierung ein. userKey kann die primäre E-Mail-Adresse des Nutzers, die eindeutige Nutzer-ID id oder eine der Alias-E-Mail-Adressen des Nutzers sein. Informationen zu den Anfrage- und Antworteigenschaften finden Sie in der API-Referenz.
DELETE https://admin.googleapis.com/admin/directory/v1/users/userKeyIn diesem Beispiel wird das Nutzerkonto liz@beispiel.de gelöscht:
DELETE https://admin.googleapis.com/admin/directory/v1/users/liz@example.com
Bei einer erfolgreichen Antwort wird nur der HTTP-Statuscode 200 zurückgegeben.
Wichtige Hinweise vor dem Löschen eines Nutzers:
- Der gelöschte Nutzer kann sich nicht mehr anmelden.
- Weitere Informationen zum Löschen von Nutzerkonten finden Sie in der Verwaltungshilfe.
Nutzerkonto wiederherstellen
Bei einem Nutzer, der in den letzten 20 Tagen gelöscht wurde, müssen bestimmte Voraussetzungen erfüllt sein, damit das Konto wiederhergestellt werden kann.
Wenn Sie die Wiederherstellung eines Nutzerkontos aufheben möchten, verwenden Sie die folgende POST-Anfrage und fügen Sie die in Anfragen autorisieren beschriebene Autorisierung ein. userKey ist der eindeutige Nutzer id, der in der Antwort der Operation In den letzten 20 Tagen gelöschte Nutzer abrufen gefunden wurde. Die primäre E-Mail-Adresse des Nutzers oder eine seiner Alias-E-Mail-Adressen kann für diesen Vorgang nicht in der userKey verwendet werden. Informationen zu den Anfrage- und Antworteigenschaften finden Sie in der API-Referenz.
POST https://admin.googleapis.com/admin/directory/v1/users/userKey/undeleteIn diesem Beispiel wird der Nutzer liz@beispiel.de wiederhergestellt. Alle vorherigen Kontoeigenschaften dieses Nutzers werden wiederhergestellt:
POST https://admin.googleapis.com/admin/directory/v1/users/12309329403209438205/undelete
Bei einer erfolgreichen Antwort wird nur der HTTP-Statuscode 204 zurückgegeben. Wenn Sie das Konto des nicht gelöschten Nutzers aufrufen möchten, verwenden Sie den Vorgang Nutzer abrufen.