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 einer beliebigen Domain Ihres Google Workspace-Kontos ein Nutzerkonto hinzufügen. Bevor Sie ein Nutzerkonto hinzufügen, müssen Sie die Domaininhaberschaft bestätigen.

Wenn Sie Ihr privates Gmail-Konto auf ein geschäftliches E-Mail-Konto mit Ihrem eigenen Domainnamen umgestellt haben, können Sie erst dann neue Nutzerkonten erstellen, wenn Sie zusätzliche Google Workspace-Einstellungen freischalten. Weitere Informationen finden Sie unter G Suite-Konten für geschäftliche E-Mail-Adressen wurden auf G Suite Basic umgestellt.

Wenn Sie ein Nutzerkonto mit einer Ihrer Domains erstellen möchten, verwenden Sie die folgende POST-Anfrage und fügen Sie die in Authentifizierung und Autorisierung beschriebene Autorisierung ein. Die verfügbaren Bereiche für die Directory API finden Sie in der Liste der OAuth 2.0-Bereiche. Informationen zu den Eigenschaften des Anfrage-Suchstrings findest du in der Methode users.insert(). 

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

Bei allen Erstellungsanfragen müssen Sie die Informationen einreichen, die zur Bearbeitung der Anfrage erforderlich sind. Wenn Sie Clientbibliotheken verwenden, werden die Datenobjekte aus der von Ihnen ausgewählten Sprache in JSON-Objekte konvertiert.

JSON-Anfrage

Die folgende JSON-Datei zeigt eine Beispielanfrage zum Erstellen eines Nutzers. Eine vollständige Liste der Anfrage- und Antworteigenschaften finden Sie in der API-Referenz. 

{
"primaryEmail": "[email protected]",
"name": {
 "givenName": "Elizabeth",
 "familyName": "Smith"
},
"suspended": false,
"password": "new user password",
"hashFunction": "SHA-1",
"changePasswordAtNextLogin": false,
"ipWhitelisted": false,
"ims": [
 {
  "type": "work",
  "protocol": "gtalk",
  "im": "[email protected]",
  "primary": true
 }
],
"emails": [
 {
  "address": "[email protected]",
  "type": "home",
  "customType": "",
  "primary": true
 }
],
"addresses": [
 {
  "type": "work",
  "customType": "",
  "streetAddress": "1600 Amphitheatre Parkway",
  "locality": "Mountain View",
  "region": "CA",
  "postalCode": "94043"
 }
],
"externalIds": [
 {
  "value": "12345",
  "type": "custom",
  "customType": "employee"
 }
],
"organizations": [
 {
  "name": "Google Inc.",
  "title": "SWE",
  "primary": true,
  "type": "work",
  "description": "Software engineer"
 }
],
"phones": [
 {
  "value": "+1 nnn nnn nnnn",
  "type": "work"
 }
],
"orgUnitPath": "/corp/engineering",
"includeInGlobalAddressList": true
}

Wenn die Abfragerate für Erstellungsanfragen zu hoch ist, erhalten Sie möglicherweise HTTP-503-Antworten vom API-Server, die darauf hinweisen, dass Ihr Kontingent überschritten wurde. Wenn Sie diese Antworten erhalten, verwenden Sie einen exponentiellen Backoff-Algorithmus, um Ihre Anfragen zu wiederholen.

Beachten Sie Folgendes, wenn Sie ein neues Konto erstellen:

  • Wenn für das Google-Konto E-Mail-Lizenzen erworben wurden, wird dem neuen Nutzerkonto automatisch ein Postfach zugewiesen. Es kann einige Minuten dauern, bis die Zuweisung abgeschlossen und aktiviert ist.
  • Das Bearbeiten eines schreibgeschützten Felds in einer Anfrage, z. B. isAdmin, wird vom API-Dienst ignoriert.
  • Pro Konto sind maximal 600 Domains zulässig (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 übergeordneten Organisationseinheit. Die Organisationseinheit eines Nutzers bestimmt, auf welche Google Workspace-Dienste der Nutzer Zugriff hat. Wenn der Nutzer zu einer neuen Organisation verschoben wird, ändert sich sein Zugriff. Weitere Informationen zu Organisationsstrukturen finden Sie in der Verwaltungshilfe. Weitere Informationen zum Verschieben eines Nutzers in eine andere Organisation finden Sie unter Nutzer aktualisieren.
  • Für neue Nutzerkonten ist eine password erforderlich. Wenn hashFunction angegeben ist, muss das Passwort ein gültiger Hash-Schlüssel sein. Wenn dies nicht angegeben ist, sollte das Passwort im Klartext und zwischen 8 und 100 ASCII-Zeichen lang sein. Weitere Informationen finden Sie in der API-Referenz.
  • Wenn Sie einen flexiblen Google Workspace-Tarif haben, hat das Erstellen von Nutzern mit dieser API finanzielle Auswirkungen und führt zu Abbuchungen von Ihrem Kundenrechnungskonto. Weitere Informationen finden Sie in den Abrechnungsinformationen für APIs.
  • Ein Google Workspace-Konto kann beliebige Domains enthalten. In einem Konto mit mehreren Domains können Nutzer in einer Domain Dienste mit Nutzern in anderen Kontodomains teilen. Weitere Informationen zu Nutzern in mehreren Domains finden Sie unter Informationen zur API für mehrere Domains.
  • Möglicherweise gibt es in Konflikt stehende Konten. Prüfen Sie, ob die Personen, die Sie hinzufügen möchten, bereits ein Google-Konto haben. Führen Sie dann die folgenden Schritte aus, um Konflikte mit diesen Konten zu vermeiden. Weitere Informationen finden Sie unter In Konflikt stehende Konten.
  • Es kann Besucherkonten geben. Wenn Nutzer Personen außerhalb Ihrer Organisation, die kein Google-Konto haben, zu einer Gruppenarbeit in Drive einladen, erhalten diese Besucherkonten im Format „Nutzername_des_Besucherkontos@Ihre_Domain.de“. Wenn Sie einen Nutzer mit demselben Nutzernamen wie ein Besucherkonto hinzufügen, wird das Konto in ein vollwertiges Google Workspace-Konto umgewandelt. Die aktuellen Berechtigungen des Kontos für Drive-Dateien bleiben erhalten. Weitere Informationen finden Sie im Hilfeartikel Dokumente für Besucher freigeben.

Bei einer erfolgreichen Antwort wird der HTTP-Statuscode 200 zurückgegeben. Zusammen mit dem Statuscode werden in der Antwort die Eigenschaften für das neue Nutzerkonto zurückgegeben.

Nutzerkonto aktualisieren

Wenn Sie ein Nutzerkonto aktualisieren möchten, verwenden Sie die folgende PUT-Anfrage und fügen Sie die in Anfragen autorisieren beschriebene Autorisierung ein. userKey kann die primäre E-Mail-Adresse des Nutzers, die eindeutige Nutzer-ID id oder eine der Alias-E-Mail-Adressen des Nutzers sein.

PUT https://admin.googleapis.com/admin/directory/v1/users/userKey

Sowohl der Anfrage- als auch der Antworttext enthalten eine Instanz von User. Die Directory API unterstützt jedoch Patch-Semantik. Sie müssen also nur die aktualisierten Felder in Ihrer Anfrage einreichen.

Beispielanfrage

Im folgenden Beispiel lautete die givenName des Nutzers „Elisabeth“, als das Nutzerkonto erstellt wurde, und es wurde nur eine geschäftliche E-Mail-Adresse angegeben.

{
  "name": {
    "givenName": "Elizabeth",
    "familyName": "Smith"
   },
  "emails": [
    {
      "address": "[email protected]",
      "type": "work",
      "primary": true
    }
  ]
}

Mit der folgenden Anfrage wird givenName von „Elizabeth“ in „Liz“ geändert und es wird eine private E-Mail-Adresse hinzugefügt. Da es sich bei dem Feld um ein Array handelt, werden beide E-Mail-Adressen vollständig angegeben.

PUT https://admin.googleapis.com/admin/directory/v1/users/[email protected]

{
  "name": {
    "givenName": "Liz",
   },
  "emails": [
    {
      "address": "[email protected]",
      "type": "work",
      "primary": true
    },
    {
      "address": "[email protected]",
      "type": "home"
    }
  ]
}

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

Beachten Sie Folgendes, wenn Sie den Kontonamen eines Nutzers aktualisieren:

  • Wenn Sie ein Nutzerkonto umbenennen, ändert sich die primäre E-Mail-Adresse des Nutzers und die Domain, die beim Abrufen der Informationen dieses Nutzers verwendet wird. Bevor Sie einen Nutzer umbenennen, sollten Sie ihn von allen Browsersitzungen und ‑diensten abmelden.
  • Es kann bis zu 10 Minuten dauern, bis die Umbenennung eines Nutzerkontos für alle Dienste übernommen wird.
  • Wenn Sie einen Nutzer umbenennen, wird der alte Nutzername als Alias beibehalten, um bei E-Mail-Weiterleitungseinstellungen eine unterbrechungsfreie E-Mail-Zustellung zu gewährleisten. Er ist nicht als neuer Nutzername verfügbar.
  • Im Allgemeinen empfehlen wir auch, die E-Mail-Adresse des Nutzers nicht als Schlüssel für persistente Daten zu verwenden, da sich die E-Mail-Adresse ändern kann.
  • Eine vollständige Liste der Auswirkungen der Umbenennung eines Nutzers in Google Workspace-Apps finden Sie in der Administrator-Hilfe.

Nutzer zum Administrator machen

Wenn Sie den Nutzer zum Super Admin machen möchten, verwenden Sie die folgende POST-Anfrage und fügen Sie die in Anfragen autorisieren beschriebene Autorisierung ein. userKey kann die primäre E-Mail-Adresse des Nutzers, die eindeutige Nutzer-ID id oder eine der Alias-E-Mail-Adressen des Nutzers sein. Informationen zu den Anfrage- und Antworteigenschaften finden Sie in der API-Referenz. Weitere Informationen zu Superadministratoren finden Sie in der Hilfe zur Verwaltung. 

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

JSON-Anfrage

In diesem Beispiel ist der Nutzer mit der userKey [email protected] zum Super Admin geworden: 

POST https://admin.googleapis.com/admin/directory/v1/users/[email protected]/makeAdmin

{
 "status": true
}

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

Nutzerbeziehungen verwalten

In der Directory API wird das Feld relations verwendet, um verschiedene Arten von Beziehungen zwischen Nutzern zu definieren. In einem geschäftlichen Umfeld wird dieses Feld häufig für die Beziehung zwischen Vorgesetzten und Mitarbeitern oder Assistenten verwendet, es unterstützt aber auch viele andere Arten. Die Beziehung wird in der Karte „Verwandte Personen“ des Nutzers in allen Google Workspace-Anwendungen angezeigt, die die Karte unterstützen. Beispiele dafür, wo die Karte zu sehen ist, finden Sie im Hilfeartikel Dem Verzeichnisprofil eines Nutzers Informationen hinzufügen.

Eine Beziehung zwischen Nutzern herstellen

Sie können eine Beziehung nur in eine Richtung definieren, beginnend mit dem „zugehörigen“ Nutzer, dessen Datensatz das Feld relations enthält. Mit type wird die Beziehung der anderen Person zum Inhaber des Kontos beschrieben. Angenommen, in einem Verhältnis zwischen Vorgesetzten und Mitarbeitern ist der Mitarbeiter der Inhaber des Kontos und Sie fügen seinem Konto ein relations-Feld vom Typ manager hinzu. Zulässige Typen finden Sie in der Objektreferenz für User.

Richten Sie die Beziehung ein, indem Sie den Inhaber erstellen oder aktualisieren. Verwenden Sie dazu einen JSON-Anfragetext mit dem Feld relations. Sie können in einer Anfrage mehrere Beziehungen erstellen.

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

Beziehung aktualisieren oder löschen

Das Feld relations kann nur als Ganzes aktualisiert werden. Sie können nicht auf die einzelnen Personen zugreifen, um den Beziehungstyp zu ändern oder sie zu entfernen. Wenn Sie im Beispiel oben die bestehende Verwaltungsbeziehung entfernen und das Verwaltungskonto mit der gestrichelten Linie zum Verwaltungskonto des Eigentümers machen möchten, aktualisieren Sie das Konto des Eigentümers mit den gewünschten Werten für alle Felder.

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

Wenn Sie alle Beziehungen des Inhabers entfernen möchten, lassen Sie relations leer:

{
  "relations": []
}

Nutzer abrufen

Wenn Sie einen Nutzer abrufen möchten, verwenden Sie die folgende GET-Anfrage und fügen Sie die in Anfragen autorisieren beschriebene Autorisierung ein. userKey kann die primäre E-Mail-Adresse des Nutzers, die eindeutige Nutzer-ID id oder eine der Alias-E-Mail-Adressen des Nutzers sein. Informationen zu den Anfrage- und Antworteigenschaften finden Sie in der API-Referenz. 

GET https://admin.googleapis.com/admin/directory/v1/users/userKey

In diesem Beispiel werden die Nutzerkontoeigenschaften für den Nutzer zurückgegeben, dessen primäre oder Alias-E-Mail-Adresse [email protected] lautet: 

GET https://admin.googleapis.com/admin/directory/v1/users/[email protected]

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": "[email protected]",
 "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": "[email protected]",
   "primary": true
  }
 ],
 "emails": [
  {
   "address": "[email protected]",
   "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": [
  "[email protected]",
  "[email protected]"
 ],
 "nonEditableAliases": [
  "[email protected]"
 ],
 "customerId": "C03az79cb",
 "orgUnitPath": "corp/engineering",
 "isMailboxSetup": true,
 "includeInGlobalAddressList": true
}

Alle Nutzer in einer Domain abrufen

Wenn Sie alle Nutzer in derselben Domain abrufen möchten, verwenden Sie die folgende GET-Anfrage und fügen Sie die in Anfragen autorisieren beschriebene Autorisierung ein. Zur besseren Lesbarkeit enthält dieses Beispiel Zeilenumbrüche: 

GET https://admin.googleapis.com/admin/directory/v1/users
?domain=primary domain name&pageToken=token for next results page
&maxResults=max number of results per page
&orderBy=email, givenName, or familyName
&sortOrder=ascending or descending
&query=email, givenName, or familyName:the query's value*

Informationen zu den Anfrage- und Antworteigenschaften finden Sie in der API-Referenz.

JSON-Antwort

In diesem Beispiel werden alle Nutzer in der Domain beispiel.de zurückgegeben, wobei maximal zwei Nutzerdomains pro Antwortseite zurückgegeben werden. In dieser Antwort gibt es eine nextPageToken für die nachfolgende Liste der Nutzer. Standardmäßig gibt das System eine Liste mit 100 Nutzern in alphabetischer Reihenfolge der E-Mail-Adresse des Nutzers zurück: 

GET https://admin.googleapis.com/admin/directory/v1/users?domain=example.com&maxResults=2

Bei einer erfolgreichen Antwort wird der HTTP-Statuscode 200 zurückgegeben. 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": "[email protected]",
   "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": "[email protected]",
     "primary": true
    }
   ],
   "emails": [
    {
     "address": "[email protected]",
     "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": [
    "[email protected]",
    "[email protected]"
   ],
   "nonEditableAliases": [
    "[email protected]"
   ],
   "customerId": "C03az79cb",
   "orgUnitPath": "corp/engineering",
   "isMailboxSetup": true,
   "includeInGlobalAddressList": true
  },
  {
   "kind": "directory#user",
   "id": "user unique ID",
   "primaryEmail": "[email protected]",
   "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": "[email protected]",
     "type": "work",
     "customType": "",
     "primary": true
    }
   ],
   "externalIds": [
    {
     "value": "contractor license number",
     "type": "custom",
     "customType": "work"
    }
   ],
   "aliases": [
    "[email protected]"
   ],
   "nonEditableAliases": [
    "[email protected]"
   ],
   "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 customerId-Wert.
  • Verwenden Sie den String my_customer für die customerId Ihres Kontos.
  • Verwenden Sie als Reseller-Administrator die customerId des Kunden, dem Sie das Produkt weiterverkauft haben. 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.
  • Mit dem optionalen Abfragestring orderBy wird festgelegt, 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 in einem Nutzerprofil suchen, sowohl in Kern- als auch in benutzerdefinierten Feldern. Beispiele finden Sie unter Nach Nutzern suchen.

Informationen zu den Anfrage- und Antworteigenschaften finden Sie in der API-Referenz.

In diesem Beispiel fordert ein Kontoadministrator an, dass alle Nutzer im Konto mit einem Nutzereintrag auf jeder Antwortseite zurückgegeben werden. Über die nextPageToken wird die nächste Ergebnisseite aufgerufen: 

GET https://admin.googleapis.com/admin/directory/v1/users?customer=my_customer&maxResults=1

In diesem Beispiel fordert ein Reseller-Administrator alle Nutzer in einem Reseller-Konto an, für das customerId den Wert C03az79cb hat. 

GET https://admin.googleapis.com/admin/directory/v1/users?customer=C03az79cb&maxResults=1

JSON-Antwort

Bei einer erfolgreichen Antwort wird der HTTP-Statuscode 200 zurückgegeben. Zusammen mit dem Statuscode werden in der Antwort alle Nutzer in diesem Konto zurückgegeben: 

{
 "kind": "directory#users",
 "users": [
  {
   "kind": "directory#user",
   "id": "the unique user id",
   "username": "[email protected]",
   "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": "[email protected]",
     "type": "work",
     "customType": "",
     "primary": true
    }
   ],
   "externalIds": [
    {
     "value": "employee number",
     "type": "custom",
     "customType": "office"
    }
   ],
   "aliases": [
     "[email protected]"
   ],
   "nonEditableAliases": [
     "