Nutzerkonten verwalten

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 zu einem geschäftlichen 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 Aktualisierung von geschäftlichen E-Mail-Konten für Google Workspace.

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 Attributen 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 JSON-formatierte Objekte 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.

Beachten Sie beim Erstellen eines neuen Kontos Folgendes:

  • 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.
  • 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 obersten Organisationseinheit. 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 password erforderlich. Wenn ein hashFunction angegeben 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.
  • Für Nutzer mit einem flexiblen Tarif für Google Workspace hat das Erstellen von Nutzern über diese API finanzielle Auswirkungen und führt zu Belastungen Ihres Kundenabrechnungskontos. 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 API-Informationen zu mehreren 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 kein Google-Konto haben, zur Zusammenarbeit in Drive einladen, erhalten diese Besucherkonten im Format visitor's_username@your_domain.com. 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 Statuscode „HTTP 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“ in „Liz“ geändert 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/makeAdmin

Der Nutzer muss zuerst vorhanden sein, bevor er zum Super Admin gemacht werden kann. Diese Aktion kann nur vom Super Admin eines Kontos ausgeführt werden. Delegierte Administratoren können Nutzern keine Administratorrollen zuweisen. Informationen zum Ändern der Rolle eines Administrators über die Google Admin-Konsole finden Sie in der Admin-Hilfe.

JSON-Anfrage

In diesem Beispiel ist der Nutzer, dessen userKey liz@example.com ist, Super Admin geworden:

POST https://admin.googleapis.com/admin/directory/v1/users/liz@example.com/makeAdmin

{
 "status": true
}

Bei einer erfolgreichen Antwort wird der Statuscode „HTTP 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 „Zugehörige Personen“ des Nutzers in jeder Google Workspace-Anwendung angezeigt, die die Karte unterstützt. 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 das Verhältnis der anderen Person zum Inhaber des Geräts beschrieben. Beispiel: In einem Verhältnis zwischen Manager und Mitarbeiter ist der Mitarbeiter der Inhabernutzer und Sie fügen seinem Konto ein relations-Feld mit dem Typ manager hinzu. Zulässige Typen finden Sie in der User-Objektreferenz.

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

Sie können nur das Feld relations als Ganzes aktualisieren. Sie können die einzelnen aufgeführten Personen nicht bearbeiten, um den Beziehungstyp zu ändern oder sie zu entfernen. Wenn Sie im vorherigen Beispiel die bestehende Managerbeziehung entfernen und den Manager mit gestrichelter Linie zum Manager des Inhabers machen möchten, aktualisieren Sie das Konto des Inhabers mit allen Feldwerten, wie Sie sie jetzt haben möchten.

{
  "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/userKey

In diesem Beispiel werden die Nutzerkontoattribute für den Nutzer zurückgegeben, dessen primäre E-Mail-Adresse oder Alias-E-Mail-Adresse liz@example.com ist:

GET https://admin.googleapis.com/admin/directory/v1/users/liz@example.com

JSON-Antwort

Bei einer erfolgreichen Antwort wird der Statuscode „HTTP 200“ zurückgegeben. Zusammen mit dem Statuscode werden in der Antwort die Eigenschaften des Nutzerkontos 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 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 Statuscode „HTTP 200“ zurückgegeben. Zusammen mit dem Statuscode werden in der Antwort zwei Nutzerkonten in der Domain example.com (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 der my_customer- oder der customerId-Wert.
  • Verwenden Sie den String my_customer, um die customerId Ihres Kontos darzustellen.
  • Als Reseller-Administrator verwenden Sie die customerId des weiterverkauften Kunden. Verwenden Sie für customerId den primären Domainnamen des Kontos in der Anfrage des Vorgangs Alle Nutzer in einer Domain abrufen. Die resultierende Antwort hat den Wert customerId.
  • Mit dem optionalen orderBy-Suchstring wird festgelegt, ob die Liste nach der primären E-Mail-Adresse, dem Familiennamen oder dem Vornamen des Nutzers sortiert wird. Wenn Sie orderBy verwenden, können Sie auch den Abfragestring sortOrder verwenden, um die Ergebnisse in aufsteigender oder absteigender Reihenfolge aufzulisten.
  • Mit dem optionalen Abfragestring query können Sie in vielen Feldern eines Nutzerprofils suchen, einschließlich der Standard- und benutzerdefinierten Felder. Beispiele finden Sie unter Nach Nutzern 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. Die nextPageToken führt 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 Statuscode „HTTP 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 zugehörigen Domains 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 Eigenschaften von 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

Wenn ein Konto mehrere Domains hat, können Sie Nutzer, die innerhalb der letzten 20 Tage gelöscht wurden, aus dem gesamten Konto abrufen. Verwenden Sie dazu die folgende 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 der my_customer- oder der customerId-Wert.
  • Als Kontoadministrator können Sie den String my_customer verwenden, um die customerId Ihres Kontos darzustellen.
  • Als Reseller-Administrator verwenden Sie die customerId des weiterverkauften Kunden. Verwenden Sie für customerId den primären Domainnamen des Kontos in der Anfrage des Vorgangs Alle Nutzer in einer Domain abrufen. Die resultierende Antwort hat den Wert customerId.

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 Statuscode „HTTP 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/thumbnail

In 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 Statuscode „HTTP 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 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 die baseURL verwendet, bei der das Gleichheitszeichen (=) für das Padding verwendet wird. Dies dient dazu, das Parsen von URLs zu vereinfachen.
  • 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 zum Base64-Codieren und -Decodieren, 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 in 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 stellen, um das öffentliche Profil eines Nutzers abzurufen. Der Bereich https://www.googleapis.com/auth/admin.directory.user.readonly ist ideal für diesen Anwendungsfall.

Mit der Ansicht domain_public kann ein Nutzer ohne Administratorberechtigungen auf eine Standardgruppe von 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/thumbnail

In diesem Beispiel wird das Foto für 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 Statuscode „HTTP 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/thumbnail

Nach dem Löschen wird das Foto des Nutzers nicht mehr angezeigt. Überall dort, wo das Foto 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 Abfragen 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/userKey

In diesem Beispiel wird das Nutzerkonto liz@example.com gelöscht:

DELETE https://admin.googleapis.com/admin/directory/v1/users/liz@example.com

Bei einer erfolgreichen Antwort wird der Statuscode „HTTP 200“ zurückgegeben.

Bevor Sie einen Nutzer löschen, sollten Sie Folgendes berücksichtigen:

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 id des Nutzers, die in der Antwort des Vorgangs In den letzten 20 Tagen gelöschte Nutzer abrufen 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/undelete

In diesem Beispiel wird der Nutzer liz@example.com wiederhergestellt. Alle bisherigen Konto-Properties dieses Nutzers werden wiederhergestellt:

POST https://admin.googleapis.com/admin/directory/v1/users/12309329403209438205/undelete

Bei einer erfolgreichen Antwort wird der HTTP-Statuscode 204 zurückgegeben. Wenn Sie das Konto des nicht gelöschten Nutzers aufrufen möchten, verwenden Sie den Vorgang Nutzer abrufen.