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 einige Beispiele für grundlegende Nutzeraktionen.

Nutzerkonto erstellen

Sie können ein Nutzerkonto zu einer beliebigen Domain Ihres Google Workspace-Kontos hinzufügen. Bestätigen Sie vor dem Hinzufügen eines Nutzerkontos die Inhaberschaft der Domain.

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 freigeschaltet haben. Weitere Informationen finden Sie unter Google Workspace-Geschäfts-E‑Mail-Konten wurden aktualisiert.

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 Abfragestrings der Anfrage finden Sie unter der users.insert Methode.

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

Für alle 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. Die 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 Abfragerate für Erstellungsanfragen zu hoch ist, erhalten Sie möglicherweise 503-Antworten vom API-Server, die darauf hinweisen, dass Ihr Kontingent überschritten wurde. Verwenden Sie in diesem Fall einen Algorithmus für exponentiellen Backoff, um Ihre Anfragen noch einmal zu senden.

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 das Postfach aktiviert ist.
  • Das Bearbeiten eines schreibgeschützten Felds in einer Anfrage, z. B. isAdmin, wird vom API-Dienst ignoriert.
  • Die maximale Anzahl der in einem Konto zulässigen Domains beträgt 600 (1 primäre Domain + 599 zusätzliche Domains).
  • Wenn ein Nutzer beim Erstellen 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 Organisations strukturen finden Sie in der Admin-Hilfe. Weitere Informationen zum Verschieben eines Nutzers in eine andere Organisation finden Sie unter Nutzer aktualisieren.
  • Für neue Nutzerkonten ist ein password erforderlich. Wenn eine hashFunction angegeben ist, muss das Passwort ein gültiger Hash-Schlüssel sein. Wenn keine `hashFunction` angegeben ist, muss das Passwort im Klartext vorliegen und zwischen 8 und 100 ASCII-Zeichen lang sein. Weitere Informationen finden Sie in der API-Referenz.
  • Für Nutzer mit einem flexiblen Abo für Google Workspace hat das Erstellen von Nutzern mit dieser API finanzielle Auswirkungen und führt zu Gebühren für Ihr Abrechnungskonto. Weitere Informationen finden Sie unter den Abrechnungsinformationen für die API.
  • Ein Google Workspace-Konto kann jede Ihrer Domains enthalten. In einem Konto mit mehreren Domains können Nutzer in einer Domain Dienste mit Nutzern in anderen Kontodomains gemeinsam nutzen. Weitere Informationen zu Nutzern in mehreren Domains finden Sie unter den Informationen zu mehreren Domains für die API.
  • 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 Besucherkonten. Wenn Nutzer Personen außerhalb Ihrer Organisation, die keine Google-Konten haben, zur Zusammenarbeit in Google Drive einladen, erhalten sie Besucherkonten im Format visitor's_username@your_domain.com. Wenn Sie einen Nutzer mit demselben Nutzernamen wie ein Besucherkonto 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 unter 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 Attribute 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. Der userKey kann die primäre E‑Mail-Adresse des Nutzers, die eindeutige id des Nutzers 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 Patch-Semantik. Daher müssen Sie in Ihrer Anfrage nur die aktualisierten Felder angeben.

Beispielanfrage

Im folgenden Beispiel war der givenName des Nutzers beim Erstellen des Nutzerkontos „Elizabeth“ 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 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"
    }
  ]
}

Bei einer erfolgreichen Antwort wird der HTTP 200 Statuscode und eine User Ressource mit den aktualisierten Feldern zurückgegeben.

Beachten Sie beim Aktualisieren des Kontonamens eines Nutzers Folgendes:

  • 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 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 wird auch davon abgeraten, die E‑Mail-Adresse des Nutzers 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 Admin-Hilfe.

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. Der userKey kann die primäre E‑Mail-Adresse des Nutzers, die eindeutige id des Nutzers oder eine der Alias-E‑Mail-Adressen des Nutzers sein. Informationen zu den Anfrage- und Antwortattributen finden Sie unter siehe API-Referenz. Weitere Informationen zu Super Admins finden Sie in der Admin-Hilfe.

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 Nutzer nicht zu Administratorrollen befördern. Informationen zum Ändern der Rolle eines Administrators über die Google Admin-Konsole finden Sie in der Admin-Hilfe.

JSON-Anfrage

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

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

Die Directory API verwendet das Feld relations, um verschiedene Arten von Beziehungen zwischen Nutzern zu definieren. In einem geschäftlichen Umfeld wird dieses Feld häufig für Beziehungen zwischen Vorgesetzten und Mitarbeitern sowie zwischen Assistenten verwendet. Das Feld unterstützt aber auch viele andere Arten von Beziehungen. Die Beziehung wird auf der Karte „Verwandte 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 einer Richtung definieren, beginnend mit dem „Inhaber“-Nutzer, dessen Eintrag das Feld relations enthält. Der type beschreibt die Beziehung der anderen Person zum Inhaber-Nutzer. Bei einer Beziehung zwischen Vorgesetztem und Mitarbeiter ist der Mitarbeiter beispielsweise der Inhaber-Nutzer. Sie fügen seinem Konto ein Feld relations mit dem Typ manager hinzu. Die zulässigen Typen finden Sie in der Referenz zum Objekt User.

Richten Sie die Beziehung ein, indem Sie den Inhaber-Nutzer mit einem JSON-Anfragetext erstellen oder aktualisieren , der das Feld relations enthält. 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 das Feld relations nur als Ganzes aktualisieren. Sie können die einzelnen aufgeführten Personen nicht ansprechen, um den Beziehungstyp zu ändern oder sie zu entfernen. Wenn Sie im vorherigen Beispiel die bestehende Beziehung zum Vorgesetzten entfernen und den Vorgesetzten mit der gestrichelten Linie zum Vorgesetzten des Inhaber-Nutzers machen möchten, aktualisieren Sie das Konto des Inhaber-Nutzers mit allen Werten des Felds, wie Sie sie jetzt haben möchten.

{
  "relations": [
    {
      "value": "EMAIL_ADDRESS_RELATION_2",
      "type": "manager"
    }
  ]
}

Wenn Sie alle Beziehungen des Inhaber-Nutzers entfernen möchten, legen Sie für relations einen leeren Wert fest:

{
  "relations": []
}

Nutzer abrufen

Wenn Sie einen Nutzer abrufen möchten, verwenden Sie die folgende GET Anfrage und fügen Sie die Autorisierung ein, die in Anfragen autorisieren beschrieben ist. Der userKey kann die primäre E‑Mail-Adresse des Nutzers, die eindeutige id des Nutzers 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 Eigenschaften des Nutzerkontos 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 Attribute 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 zurückgegeben, mit maximal zwei Nutzerdomains pro Antwortseite. Diese Antwort enthält ein nextPageToken für die nachfolgende Liste der Nutzer. Standardmäßig gibt das System eine Liste von 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 zurückgegeben (maxResults=2):

{
 "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",
   "suspensionTime": "2013-02-05T10:30:03.325Z",
   "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 Abfragestring customer ist der Wert my_customer oder customerId.
  • 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 die customerId, den primären Domainnamen des Kontos in der Anfrage des Vorgangs „Alle Nutzer in einer Domain abrufen“. Die resultierende Antwort enthält den Wert customerId.
  • Der optionale Abfragestring orderBy bestimmt, ob die Liste nach der primären E‑Mail-Adresse, dem Nachnamen 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 Kernfelder und benutzerdefinierten Felder. Beispiele finden Sie unter Nach Nutzern suchen für.

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. Das nextPageToken führt zur nächsten Seite 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 an, dessen 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 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 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 Abfragestring domain ist der primäre Domainname der Domain. Informationen zu den Anfrage- und Antwortattributen für Nutzer 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 abrufen, die in den letzten 20 Tagen aus dem gesamten Konto gelöscht wurden. 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 Abfragestring customer ist der Wert my_customer oder customerId.
  • Als Kontoadministrator 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 die customerId, den primären Domainnamen des Kontos in der Anfrage des Vorgangs „Alle Nutzer in einer Domain abrufen“. Die resultierende Antwort enthält 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

Die API ruft eine Miniaturansicht des Fotos ab, das aktuelle Google-Profilfoto. 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. Der userKey kann die primäre E‑Mail-Adresse des Nutzers, die id des Nutzers 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 aktuelle 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:

  • Das Schrägstrichzeichen (/) wird durch das Unterstrichzeichen (_) ersetzt.
  • Das Pluszeichen (+) wird durch das Minuszeichen (-) ersetzt.
  • Das Gleichheitszeichen (=) wird durch das Sternchen (*) ersetzt.
  • Für die Auffüllung wird das Punktzeichen (.) anstelle der RFC 4648-Definition für die Basis-URL verwendet, bei der das Gleichheitszeichen (=) für die Auffüllung verwendet wird. Dies vereinfacht das URL-Parsing.
  • 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 Base64-Codierungs- und ‑Decodierungsfunktionen , die unter der Apache-Lizenz veröffentlicht werden.

Nutzer als Nicht-Administrator abrufen

Nutzerkonten können nur von Administratoren geändert werden. Nutzer in der Domain können jedoch Nutzerprofile lesen. Ein Nutzer ohne Administratorberechtigungen kann eine users.get oder users.list Anfrage mit dem viewType Parameter gleich domain_public senden, um das öffentliche Profil eines Nutzers abzurufen. Der Bereich https://www.googleapis.com/auth/admin.directory.user.readonly ist ideal für diesen Anwendungsfall.

Die Ansicht domain_public ermöglicht einem Nutzer ohne Administratorberechtigungen den Zugriff auf einen Standardsatz von Kernfeldern. Für ein benutzerdefiniertes 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. Der userKey kann die primäre E‑Mail-Adresse des Nutzers, die id des Nutzers oder eine der Alias-E‑Mail-Adressen des Nutzers 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 die Parameter 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 Autorisierung ein, die in Anfragen autorisieren beschrieben ist. Der userKey kann die primäre E‑Mail-Adresse des Nutzers, die id des Nutzers 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/photos/thumbnail

Nach dem Löschen wird das Foto des Nutzers nicht mehr angezeigt. Wo immer 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 Anfragen autorisieren beschriebene Autorisierung ein. Der userKey kann die primäre E‑Mail-Adresse des Nutzers, die eindeutige id des Nutzers 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.

Beachten Sie Folgendes, 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 Admin-Hilfe.

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. Das userKey ist die eindeutige Nutzer-id, die in der Antwort des Vorgangs „In den letzten 20 Tagen gelöschte Nutzer abrufen“ enthalten ist. Die primäre E‑Mail-Adresse des Nutzers oder eine der Alias-E‑Mail-Adressen des Nutzers kann für diese Aktion nicht im 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 vorherigen Kontoattribute dieses Nutzers werden wiederhergestellt:

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

Bei einer erfolgreichen Antwort wird der Statuscode „HTTP 204“ zurückgegeben. Wenn Sie das Konto des wiederhergestellten Nutzers sehen möchten, verwenden Sie den Vorgang „Nutzer abrufen“.