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 ein Nutzerkonto einer beliebigen Domain Ihres Google Workspace-Kontos 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 aktualisiert haben, können Sie erst dann neue Nutzerkonten erstellen, wenn Sie zusätzliche Google Workspace-Einstellungen freigeschaltet haben. 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-Query-Strings finden Sie in der Methode users.insert().
POST https://admin.googleapis.com/admin/directory/v1/users
Bei allen Erstellungsanfragen müssen Sie die Informationen angeben, die zur Bearbeitung der Anfrage erforderlich sind. Wenn Sie Clientbibliotheken verwenden, werden die Datenobjekte aus der von Ihnen ausgewählten Sprache in formatierte JSON-Datenobjekte konvertiert.
JSON-Anfrage
Das folgende JSON zeigt eine Beispielanfrage zum Erstellen eines Nutzers. Eine vollständige Liste der Anfrage- und Antwortattribute 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 Ihre Anfragerate 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.
Hinweise zu einem neuen Konto:
- 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 stillschweigend ignoriert. - In einem Konto sind maximal 600 Domains zulässig (1 primäre Domain + 599 zusätzliche Domains).
- Wenn ein Nutzer bei der Erstellung des Nutzerkontos keiner bestimmten Organisationseinheit zugewiesen wurde, befindet sich das Konto in der Organisationseinheit der obersten Ebene. Die Organisationseinheit eines Nutzers bestimmt, auf welche Google Workspace-Dienste der Nutzer Zugriff hat. Wenn der Nutzer in eine neue Organisation verschoben wird, ändert sich sein Zugriff. Weitere Informationen zu Organisationsstrukturen finden Sie in der Administratorhilfe. Weitere Informationen zum Verschieben eines Nutzers in eine andere Organisation finden Sie unter Nutzer aktualisieren.
- Für neue Nutzerkonten ist eine
passworderforderlich. Wenn einhashFunctionangegeben ist, muss das Passwort ein gültiger Hash-Schlüssel sein. Wenn es 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 Nutzer mit dieser API für Google Workspace-Nutzer mit einem flexiblen Tarif erstellen, hat dies finanzielle Auswirkungen und führt zu Gebühren für das Abrechnungskonto Ihres Kunden. Weitere Informationen finden Sie unter Abrechnungsinformationen für APIs.
- Ein Google Workspace-Konto kann alle Ihre 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 eine der Personen, die Sie hinzufügen möchten, bereits ein Google-Konto hat. Führen Sie dann die folgenden Schritte aus, um Konflikte mit diesen Konten zu vermeiden. Weitere Informationen finden Sie unter In Konflikt stehende Konten.
- Möglicherweise gibt es Gastkonten. Wenn Nutzer Personen außerhalb Ihrer Organisation, die keine Google-Konten haben, zur Zusammenarbeit in Drive einladen, erhalten diese Gastkonten im Format „nutzername_des_gasts@Ihre_Domain.de“. Wenn Sie einen Nutzer mit demselben Nutzernamen wie ein Gastkonto hinzufügen, wird das Konto in ein vollständiges 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 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 Beispiel unten war der givenName des Nutzers bei der Erstellung des Nutzerkontos „Elizabeth“ und es wurde nur eine Arbeits-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“ zu „Liz“ aktualisiert und eine private E‑Mail-Adresse hinzugefügt. Beachten Sie, dass beide E-Mail-Adressen vollständig angegeben werden, da das Feld ein Array ist.
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 HTTP 200-Statuscode und eine User-Ressource 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, empfehlen wir, ihn von allen Browsersitzungen und Diensten abzumelden.
- Es kann bis zu 10 Minuten dauern, bis die Umbenennung eines Nutzerkontos in allen Diensten wirksam wird.
- Wenn Sie einen Nutzer umbenennen, wird der alte Nutzername als Alias beibehalten, um eine unterbrechungsfreie E-Mail-Zustellung bei E-Mail-Weiterleitungseinstellungen 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.
Einen Nutzer zum Administrator machen
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 oder eine der Alias-E-Mail-Adressen des Nutzers sein. Informationen zu den Anfrage- und Antwortattributen finden Sie in der API-Referenz. Weitere Informationen zu Super-Administratoren finden Sie in der Hilfe für Administratoren.
POST https://admin.googleapis.com/admin/directory/v1/users/userKey/makeAdminJSON-Anfrage
In diesem Beispiel ist der Nutzer mit der userKey liz@example.com 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. Im geschäftlichen Umfeld wird dieses Feld häufig für Beziehungen zwischen Vorgesetzten und Mitarbeitern sowie zwischen Assistenten und Vorgesetzten verwendet. Das Feld unterstützt jedoch auch viele andere Arten von Beziehungen. Die Beziehung wird in der Karte „Verwandte Personen“ des Nutzers in allen Google Workspace-Anwendungen angezeigt, die die Karte unterstützen. Beispiele dafür, wo die Karte sichtbar ist, finden Sie unter Dem Verzeichnisprofil eines Nutzers Informationen hinzufügen.
Beziehung zwischen Nutzern erstellen
Sie können eine Beziehung nur in eine Richtung definieren, beginnend mit dem „besitzenden“ Nutzer, dessen Datensatz das Feld relations enthält. Im Feld type wird die Beziehung der anderen Person zum Inhabernutzer beschrieben. In einem Verhältnis zwischen Manager und Mitarbeiter ist der Mitarbeiter beispielsweise der Inhaber und Sie fügen seinem Konto ein relations-Feld mit dem Typ manager hinzu. Informationen zu zulässigen Typen finden Sie in der Objektreferenz für User.
Richten Sie die Beziehung ein, indem Sie den Inhabernutzer mit einem JSON-Anfragetext, der das Feld relations enthält, erstellen oder aktualisieren.
Sie können mehrere Beziehungen in einer Anfrage 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 die einzelnen aufgeführten Personen nicht ansprechen, um den Beziehungstyp zu ändern oder sie zu entfernen. Wenn Sie im obigen Beispiel die vorhandene Beziehung zum Verwaltungskonto entfernen und das Verwaltungskonto mit der gestrichelten Linie zum Verwaltungskonto des Inhabers machen möchten, aktualisieren Sie das Konto des Inhabers mit allen Feldwerten, die Sie jetzt wünschen.
{
"relations": [
{
"value": "EMAIL_ADDRESS_RELATION_2",
"type": "manager"
}
]
}
Wenn Sie alle Beziehungen des Inhabernutzers 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 oder eine der Alias-E-Mail-Adressen des Nutzers sein. Informationen zu den Anfrage- und Antwortattributen finden Sie in der API-Referenz.
GET https://admin.googleapis.com/admin/directory/v1/users/userKeyIn diesem Beispiel werden die Nutzerkontoattribute für den Nutzer zurückgegeben, dessen primäre E‑Mail-Adresse 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 Antwortattributen finden Sie in der API-Referenz.
JSON-Antwort
In diesem Beispiel werden alle Nutzer in der Domain „example.com“ mit maximal zwei Nutzerdomains pro Antwortseite zurückgegeben. In dieser Antwort gibt es ein nextPageToken für die Follow-up-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. Zusammen mit dem Statuscode werden in der Antwort zwei Nutzerkonten in der Domain „beispiel.de“ (maxResults=2) zurückgegeben:
{ "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- oder dercustomerId-Wert. - Verwenden Sie den String
my_customer, um diecustomerIdIhres Kontos darzustellen. - Als Reseller-Administrator verwenden Sie die
customerIddes weiterverkauften Kunden. Verwenden Sie fürcustomerIdden primären Domainnamen des Kontos in der Anfrage des Vorgangs Alle Nutzer in einer Domain abrufen. Die resultierende Antwort hat den WertcustomerId. - Mit dem optionalen Abfragestring
orderBywird festgelegt, ob die Liste nach der primären E-Mail-Adresse, dem Familiennamen oder dem Vornamen des Nutzers sortiert wird. Wenn SieorderByverwenden, können Sie die Ergebnisse auch mit dem AbfragestringsortOrderin aufsteigender oder absteigender Reihenfolge auflisten. - Mit dem optionalen Abfragestring
querykönnen Sie in vielen Feldern eines Nutzerprofils suchen, einschließlich der Kernfelder und benutzerdefinierten Felder. Beispiele finden Sie unter Nutzer suchen.
Informationen zu den Anfrage- und Antwortattributen 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 nextPageToken gelangen Sie zur Folgeseite mit Ergebnissen:
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 weiterverkauften Konto mit dem customerId-Wert C03az79cb an.
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 abrufen
Wenn Sie alle Nutzer abrufen möchten, die in den letzten 20 Tagen aus einem Konto oder 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 in den letzten 20 Tagen aus der primären Domain 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 Attributen 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. 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- oder dercustomerId-Wert. - Als Kontoadministrator können Sie den String
my_customerverwenden, um diecustomerIdIhres Kontos darzustellen. - Als Reseller-Administrator verwenden Sie die
customerIddes weiterverkauften Kunden. Verwenden Sie fürcustomerIdden primären Domainnamen des Kontos in der Anfrage des Vorgangs Alle Nutzer in einer Domain abrufen. Die resultierende Antwort hat den WertcustomerId.
Informationen zu den Anfrage- und Antwortattributen 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. Zusammen mit dem Statuscode werden in der Antwort alle Kontonutzer zurückgegeben, die in den letzten 20 Tagen 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" }
Foto eines Nutzers abrufen
Über die API wird eine Miniaturansicht des Fotos abgerufen, das zuletzt als Google-Profilfoto verwendet wurde. Wenn Sie das letzte 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 eine der Alias-E-Mail-Adressen des Nutzers sein. Informationen zu den Anfrage- und Antwortattributen finden Sie in der API-Referenz.
GET https://admin.googleapis.com/admin/directory/v1/users/userKey/photos/thumbnailIn diesem Beispiel wird das letzte Foto von liz@example.com 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 RFC 4648 „base64url“. Das bedeutet:
- Der Schrägstrich (/) wird durch den Unterstrich (_) ersetzt.
- Das Pluszeichen (+) wird durch das Minuszeichen (-) ersetzt.
- Das Gleichheitszeichen (=) wird durch das Sternchen (*) ersetzt.
- Für das Padding wird der Punkt (.) anstelle der RFC-4648-Definition für „baseURL“ verwendet, bei der das Gleichheitszeichen (=) für das Padding verwendet wird. Dies dient zur Vereinfachung des URL-Parsings.
- 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üssen, enthält die Google Closure Library Funktionen für die Base64-Codierung und -Decodierung, die unter der Apache-Lizenz veröffentlicht werden.
Nutzer als Nutzer ohne Administratorzugriff abrufen
Nutzerkonten können nur von Administratoren geändert werden, Nutzerprofile können jedoch von allen Nutzern der Domain gelesen werden. Ein Nutzer, der kein Administrator ist, kann eine users.get- oder users.list-Anfrage mit dem Parameter viewType gleich domain_public senden, um das öffentliche Profil eines Nutzers abzurufen. Der Bereich https://www.googleapis.com/auth/admin.directory.user.readonly ist für diesen Anwendungsfall ideal.
Mit der Ansicht domain_public kann ein Nutzer ohne Administratorberechtigungen auf eine Reihe von Standard-Kernfeldern zugreifen. Bei einem benutzerdefinierten Feld können Sie beim Definieren des Schemas festlegen, 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, der Nutzer id oder eine der E-Mail-Adressen der Nutzer-Aliasse sein. Informationen zu den Anfrage- und Antwortattributen 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@example.com 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, der Nutzer id oder eine der E-Mail-Adressen der Nutzer-Aliasse sein. Informationen zu den Anfrage- und Antwortattributen 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. Überall dort, wo das Bild eines Nutzers 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 oder eine der Alias-E-Mail-Adressen des Nutzers sein. Informationen zu den Anfrage- und Antwortattributen 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, bevor Sie einen Nutzer löschen:
- Der gelöschte Nutzer kann sich nicht mehr anmelden.
- Weitere Informationen zum Löschen von Nutzerkonten finden Sie in der Hilfe für Administratoren.
Nutzerkonto wiederherstellen
Ein Nutzer, der in den letzten 20 Tagen gelöscht wurde, muss bestimmte Bedingungen erfüllen, bevor sein Konto wiederhergestellt werden kann.
Wenn Sie ein Nutzerkonto wiederherstellen möchten, verwenden Sie die folgende POST-Anfrage und fügen Sie die in Anfragen autorisieren beschriebene Autorisierung ein. Die userKey ist die eindeutige Nutzer-id, die in der Antwort des Vorgangs Nutzer abrufen, die in den letzten 20 Tagen gelöscht wurden enthalten ist. Die primäre E-Mail-Adresse oder eine der Alias-E-Mail-Adressen des Nutzers kann für diesen Vorgang nicht in userKey verwendet werden. Informationen zu den Anfrage- und Antwortattributen 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 Kontoattribute 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 wiederhergestellten Nutzers aufrufen möchten, verwenden Sie den Vorgang Nutzer abrufen.