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 Nutzervorgänge.

Nutzerkonto erstellen

Sie können jeder 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 aktivieren. Weitere Informationen finden Sie im Hilfeartikel Geschäftliche G Suite-E-Mail-Konten auf G Suite Basic aktualisiert.

Verwenden Sie zum Erstellen eines Nutzerkontos mit einer Ihrer Domains die folgende POST-Anfrage und fügen Sie die unter Informationen zur Authentifizierung und Autorisierung beschriebene Autorisierung hinzu. Die verfügbaren Bereiche für die Directory API sind in der Liste der OAuth 2.0-Bereiche aufgeführt. Informationen zu den Attributen des Anfrageabfragestrings finden Sie in der Methode users.insert().

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

Bei allen Erstellungsanfragen müssen Sie die zur Ausführung der Anfrage erforderlichen Informationen angeben. Wenn Sie Clientbibliotheken verwenden, werden die Datenobjekte aus der ausgewählten Sprache in JSON-Datenformate konvertiert.

JSON-Anfrage

Die folgende JSON-Datei zeigt eine Beispielanfrage zum Erstellen eines Nutzers. Eine vollständige Liste der Anfrage- und 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 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 noch einmal zu senden.

Wichtige 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 diese Aufgabe abgeschlossen und aktiviert ist.
  • Das Bearbeiten eines schreibgeschützten Felds in einer Anfrage wie isAdmin wird vom API-Dienst automatisch ignoriert.
  • Pro Konto sind maximal 600 Domains zulässig (eine 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. Mit der Organisationseinheit eines Nutzers wird festgelegt, auf welche Google Workspace-Dienste der Nutzer zugreifen kann. Wenn der Nutzer in eine neue Organisation verschoben wird, ändert sich der Zugriff des Nutzers. Weitere Informationen zu Organisationsstrukturen finden Sie in der Hilfe für Administratoren. 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 sie nicht festgelegt ist, muss das Passwort in Klartext vorliegen und zwischen 8 und 100 ASCII-Zeichen lang sein. Weitere Informationen finden Sie in der API-Referenz.
  • Wenn Sie Nutzer mit einem flexiblen Tarif für Google Workspace erstellen, hat das Erstellen von Nutzern, die diese API verwenden, Auswirkungen auf die Einnahmen. Dadurch fallen Gebühren für das Rechnungskonto des Kunden an. Weitere Informationen finden Sie unter API-Zahlungsinformationen.
  • Ein Google Workspace-Konto kann jede Ihrer Domains enthalten. In einem Konto mit mehreren Domains können Nutzer in einer Domain Dienste für Nutzer in anderen Kontodomains freigeben. Weitere Informationen zu Nutzern in mehreren Domains finden Sie im Hilfeartikel API-Informationen zu Nutzern in mehreren Domains.
  • Möglicherweise gibt es in Konflikt stehende Konten. Prüfen Sie, ob jemand, den Sie hinzufügen möchten, bereits ein Google-Konto hat. Führen Sie dann die entsprechenden Schritte aus, um Konflikte mit diesen Konten zu vermeiden. Weitere Informationen finden Sie im Hilfeartikel In Konflikt stehende Konten.
  • Möglicherweise gibt es Besucherkonten. Wenn Nutzer Personen außerhalb Ihrer Organisation zur Zusammenarbeit in Drive einladen, erhalten sie Besucherkonten im Format „besuchername@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 für Drive-Dateien bleiben für das Konto 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 des neuen Nutzerkontos zurückgegeben.

Nutzerkonto aktualisieren

Verwenden Sie zum Aktualisieren eines Nutzerkontos die folgende PUT-Anfrage und fügen Sie die unter Anfragen autorisieren beschriebene Autorisierung ein. Bei userKey kann es sich um die primäre E-Mail-Adresse des Nutzers, den eindeutigen Nutzer id oder eine Alias-E-Mail-Adresse des Nutzers handeln.

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 die Patch-Semantik, sodass Sie in Ihrer Anfrage nur die aktualisierten Felder senden müssen.

Beispielanfrage

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

{
  "name": {
    "givenName": "Elizabeth",
    "familyName": "Smith"
   },
  "emails": [
    {
      "address": "liz@example.com",
      "type": "work",
      "primary": true
    }
}

In der folgenden Anfrage wird givenName von „Elizabeth“ in „Liz“ geändert und außerdem eine private E-Mail-Adresse hinzugefügt. Beide E-Mail-Adressen werden vollständig angegeben, 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 werden der Statuscode HTTP 200 und eine User-Ressource mit den aktualisierten Feldern zurückgegeben.

Beachten Sie beim Aktualisieren des Kontonamens eines Nutzers Folgendes:

  • Wenn Sie ein Nutzerkonto umbenennen, werden sowohl die primäre E-Mail-Adresse des Nutzers als auch die Domain geändert, die beim Abrufen der Informationen dieses Nutzers verwendet wird. Bevor Sie einen Nutzer umbenennen, sollten Sie ihn aus 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, damit in den Einstellungen für die E-Mail-Weiterleitung eine kontinuierliche E-Mail-Zustellung gewährleistet ist. Der alte Nutzername ist nicht als neuer Nutzername verfügbar.
  • Generell empfehlen wir außerdem, die E-Mail-Adresse des Nutzers nicht als Schlüssel für nichtflüchtige Daten zu verwenden, da sich die E-Mail-Adresse ändern kann.
  • Eine vollständige Liste der Auswirkungen der Umbenennung eines Nutzers in Google Workspace-Anwendungen 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 unter Anfragen autorisieren beschriebene Autorisierung hinzu. Bei userKey kann es sich um die primäre E-Mail-Adresse des Nutzers, den einzelnen Nutzer id oder eine Alias-E-Mail-Adresse des Nutzers handeln. Informationen zu den Anfrage- und Antwortattributen finden Sie in der API-Referenz. Weitere Informationen zu Super Admins finden Sie in der Hilfe für Administratoren.

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

JSON-Anfrage

In diesem Beispiel ist der Nutzer mit der userKey-Adresse liz@beispiel.de ein Super Admin:

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 werden mithilfe des Felds relations verschiedene Arten von Beziehungen zwischen Nutzern definiert. Im geschäftlichen Umfeld wird dieses Feld üblicherweise für Management-Mitarbeiter-Beziehungen und Assistenten verwendet, aber das Feld unterstützt auch viele andere Arten. Die Beziehung wird in jeder Google Workspace-Anwendung, die die Karte unterstützt, auf der Karte „Verbundene Personen“ des Nutzers angezeigt. Beispiele dafür, wo die Karte sichtbar ist, findest du unter Informationen zum Verzeichnisprofil eines Nutzers hinzufügen.

Eine Beziehung zwischen Nutzern aufbauen

Sie können eine Beziehung nur in einer Richtung definieren, beginnend mit dem „Inhaber“-Nutzer, dessen Datensatz das Feld relations enthält. Die type beschreibt die Beziehung der anderen Person zum Eigentümer. In einer Beziehung zwischen einem Manager und einem Mitarbeiter ist der Mitarbeiter beispielsweise der Eigentümer und Sie fügen seinem Konto das Feld relations mit dem Typ manager hinzu. Die zulässigen Typen finden Sie in der User-Objektreferenz.

Erstellen oder aktualisieren Sie den Eigentümer des Nutzers mit einem JSON-Anfragetext, der das Feld relations enthält, um die Beziehung einzurichten. Du kannst 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 aktualisieren, aber nur insgesamt. Sie können also nicht die aufgeführten Personen ansprechen, um den Beziehungstyp zu ändern oder zu entfernen. Um im obigen Beispiel die vorhandene Verwaltungskontobeziehung zu entfernen und den Manager mit der gepunkteten Linie zum Administrator des Nutzers zu machen, aktualisieren Sie das Konto des Eigentümers mit allen Feldwerten wie gewünscht.

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

Um alle Beziehungen des Eigentümers zu entfernen, setzen Sie relations auf einen leeren Wert:

{
  "relations": []
}

Nutzer abrufen

Verwenden Sie zum Abrufen eines Nutzers die folgende GET-Anfrage und fügen Sie die unter Anfragen autorisieren beschriebene Autorisierung ein. Bei userKey kann es sich um die primäre E-Mail-Adresse des Nutzers, den einzelnen Nutzer id oder eine Alias-E-Mail-Adresse des Nutzers handeln. 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 Kontoeigenschaften für den Nutzer zurückgegeben, dessen primäre oder Alias-E-Mail-Adresse liz@beispiel.de ist:

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 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 unter Anfragen autorisieren beschriebene Autorisierung ein. Zur besseren Lesbarkeit werden in diesem Beispiel Zeilenumsätze verwendet:

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. Es gibt eine nextPageToken für die Folgeliste der Nutzer in dieser Antwort. 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 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 unter Anfragen autorisieren beschriebene Autorisierung ein. Zur besseren Lesbarkeit werden in diesem Beispiel Zeilenumsätze verwendet:

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 für customerId Ihres Kontos.
  • Verwenden Sie als Reseller-Administrator die customerId des Kunden eines Resellers. Verwenden Sie für customerId in der Anfrage des Vorgangs Alle Nutzer in einer Domain abrufen den primären Domainnamen des Kontos. 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 Familiennamen oder dem Vornamen des Nutzers sortiert wird. Bei Verwendung von orderBy können Sie auch den Abfragestring sortOrder verwenden, um die Ergebnisse in aufsteigender oder absteigender Reihenfolge aufzulisten.
  • Mit dem optionalen Abfragestring query können viele Felder in einem Nutzerprofil durchsucht werden, einschließlich zentraler und benutzerdefinierter Felder. Beispiele finden Sie unter Suche nach Nutzern.

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

In diesem Beispiel fordert ein Kontoadministrator auf, dass alle Nutzer im Konto mit einem Nutzereintrag auf jeder Antwortseite zurückgegeben werden. nextPageToken ruft die Folgeseite mit Ergebnissen auf:

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-Wert C03az79cb lautet.

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

JSON-Antwort

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

{
 "kind": "directory#users",
 "users": [
  {
   "kind": "directory#user",
   "id": "the unique user id",
   "username": "admin2@example.com",
   "name": {
    "givenName": "admin",
    "familyName": "two",
    "fullName": "admin two"
   },
   "isAdmin": true,
   "isDelegatedAdmin": true,
   "lastLoginTime": "2013-02-05T10:30:03.325Z",
   "creationTime": "2010-04-05T17:30:04.325Z",
   "agreedToTerms": true,
   "hashFunction": "SHA-1",
   "suspended": false,
   "changePasswordAtNextLogin": false,
   "ipWhitelisted": false,
   "emails": [
    {
     "address": "admin2@example.com",
     "type": "work",
     "customType": "",
     "primary": true
    }
   ],
   "externalIds": [
    {
     "value": "employee number",
     "type": "custom",
     "customType": "office"
    }
   ],
   "aliases": [
     "second_admin@example.com"
   ],
   "nonEditableAliases": [
     "another_admin@test.com"
   ],
   "customerId": "C03az79cb",
   "orgUnitPath": "/",
   "isMailboxSetup": true,
   "includeInGlobalAddressList": true
  },
  {
   "kind": "directory#user",
   "id": "the unique user id",
   "username": "liz@example.com",
   "name": {
    "givenName": "Elizabeth",
    "familyName": "Smith",
    "fullName": "Elizabeth Smith"
   },
   "isAdmin": false,
   "isDelegatedAdmin": false,
   "lastLoginTime": "1336509883546",
   "creationTime": "1404802800000",
   "agreedToTerms": false,
   "hashFunction": "SHA-1",
   "suspended": false,
   "changePasswordAtNextLogin": false,
   "ipWhitelisted": false,
   "emails": [
    {
     "address": "liz@example.com",
     "type": "home",
     "customType": "",
     "primary": true
    }
   ],
   "externalIds": [
    {
     "value": "employee number",
     "type": "custom",
     "customType": "bank"
    }
   ],
   "relations": [
    {
     "value": "liz",
     "type": "friend",
     "customType": ""
    }
   ],
   "aliases": [
    "lizsmith@example.com",
    "lsmith@example.com"
   ],
   "nonEditableAliases": [
    "liz@test.com"
   ],
   "customerId": "C03az79cb",
   "orgUnitPath": "/",
   "isMailboxSetup": true,
   "includeInGlobalAddressList": true
  },
  {
   "kind": "directory#user",
   "id": "the unique user id",
   "username": "test3@example.com",
   "name": {
    "givenName": "Tester",
    "familyName": "Three",
    "fullName": "Tester Three"
   },
   "isAdmin": false,
   "isDelegatedAdmin": false,
   "lastLoginTime": "1336509883546",
   "creationTime": "1404802800000",
   "agreedToTerms": true,
   "hashFunction": "SHA-1",
   "suspended": false,
   "changePasswordAtNextLogin": false,
   "ipWhitelisted": false,
   "emails": [
    {
     "address": "test@example.com",
     "type": "work",
     "customType": "",
     "primary": true
    }
   ],
   "externalIds": [
    {
     "value": "employee number",
     "type": "custom",
     "customType": "office"
    }
   ],
   "aliases": [
    "tester3@example.com"
   ],
   "nonEditableAliases": [
    "third@test.com"
   ],
   "customerId": "C03az79cb",
   "orgUnitPath": "/",
   "isMailboxSetup": true,
   "includeInGlobalAddressList": true
  },
  {
   "kind": "directory#user",
   "id": "the unique user id",
   "username": "work_admin@example.com",
   "name": {
    "givenName": "Admin",
    "familyName": "Work",
    "fullName": "Admin Work"
   },
   "isAdmin": true,
   "isDelegatedAdmin": true,
   "lastLoginTime": "1336509883546",
   "creationTime": "1404802800000",
   "agreedToTerms": true,
   "hashFunction": "SHA-1",
   "suspended": false,
   "changePasswordAtNextLogin": false,
   "ipWhitelisted": false,
   "emails": [
    {
     "address": "work_admin@example.com",
     "type": "work",
     "customType": "",
     "primary": true
    }
   ],
   "externalIds": [
    {
     "value": "employee number",
     "type": "custom",
     "customType": "office"
    }
   ],
   "aliases": [
    "my_alias@example.com"
   ],
   "nonEditableAliases": [
    "other_alias@test.com"
   ],
   "customerId": "C03az79cb",
   "orgUnitPath": "/",
   "isMailboxSetup": true,
   "includeInGlobalAddressList": true
  }
 ],
 "nextPageToken": "NNNNN"
}

Kürzlich gelöschte Nutzer wiederherstellen

Wenn Sie alle Nutzer, die innerhalb der letzten 20 Tage gelöscht wurden, aus einem Konto oder aus einer der Domains des Kontos abrufen möchten, verwenden Sie die folgenden GET-Anfragen und fügen Sie die unter Anfragen autorisieren beschriebene Autorisierung ein. Weitere Informationen finden Sie unter Nutzer wiederherstellen.

Mit der folgenden GET-Anfrage können Sie Nutzer wiederherstellen, die innerhalb der letzten 20 Tage von der primären Domain des Kontos oder einer Subdomain gelöscht wurden. Der Abfragestring domain ist der primäre Domainname der Domain. Informationen zu den Anfrage- und Antwortattributen von Nutzern finden Sie in der API-Referenz. Zur besseren Lesbarkeit werden in diesem Beispiel Zeilenumsätze verwendet:

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 mit der folgenden GET-Anfrage Nutzer, die innerhalb der letzten 20 Tage gelöscht wurden, aus dem gesamten Konto wiederherstellen. Zur besseren Lesbarkeit werden in diesem Beispiel Zeilenumsätze verwendet:
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.
  • Verwenden Sie als Kontoadministrator den String my_customer für die customerId Ihres Kontos.
  • Verwenden Sie als Reseller-Administrator die customerId des Kunden eines Resellers. Verwenden Sie für customerId in der Anfrage des Vorgangs Alle Nutzer in einer Domain abrufen den primären Domainnamen des Kontos. 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 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

Die API ruft eine Miniaturansicht eines Fotos ab, also das neueste Google-Profilbild. Verwenden Sie die folgende GET-Anfrage und fügen Sie die unter Anfragen autorisieren beschriebene Autorisierung ein, um das neueste Foto des Nutzers abzurufen. Bei userKey kann es sich um die primäre E-Mail-Adresse des Nutzers, den Nutzer id oder eine Alias-E-Mail-Adresse des Nutzers handeln. 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 neueste Foto von liz@beispiel.de zurückgegeben:

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

JSON-Antwort

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

{
 "kind": "directory#user#photo",
 "id": "the unique user id",
 "primaryEmail": "liz@example.com",
 "mimeType": "the photo mime type",
 "height": "the photo height in pixels",
 "width": "the photo width in pixels",
 "photoData": "web safe base64 encoded photo data"
}

Die websichere Base64-Codierung Ihrer Fotos durch die API ähnelt RFC 4648 „base64url“. Das bedeutet:

  • Der Schrägstrich (/) wird durch den Unterstrich (_) ersetzt.
  • Das Pluszeichen (+) wird durch einen Bindestrich (-) ersetzt.
  • Das Gleichheitszeichen (=) wird durch das Sternchen (*) ersetzt.
  • Für das Auffüllen wird der Punkt (.) anstelle der RFC-4648-baseURL-Definition verwendet, bei der das Gleichheitszeichen (=) für den Abstand verwendet wird. Dies geschieht, um die URL-Analyse zu vereinfachen.
  • Unabhängig von der Größe des hochgeladenen Fotos wird es vom API proportional auf 96 x 96 Pixel verkleinert.

Wenn Sie kompatible Links aus JavaScript erstellen müssen, enthält die Google Closure Library Base64-Codierungs- und -Decodierungsfunktionen, die im Rahmen der Apache-Lizenz veröffentlicht werden.

Nutzer als Nicht-Administrator abrufen

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

Die Ansicht domain_public ermöglicht einem Nutzer ohne Administratorberechtigungen, auf einen Standardsatz von Kernfeldern zuzugreifen. 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 Bild eines Nutzers aktualisieren möchten, verwenden Sie die folgende PUT-Anfrage und fügen Sie die unter Anfragen autorisieren beschriebene Autorisierung hinzu. Bei userKey kann es sich um die primäre E-Mail-Adresse des Nutzers, den Nutzer id oder eine beliebige E-Mail-Adresse des Nutzeralias handeln. 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 liz@beispiel.de aktualisiert:

PUT https://admin.googleapis.com/admin/directory/v1/users/liz@example.com/photos/thumbnail
{
"photoData": "web safe base64 encoded photo data"
}

Beim Aktualisieren eines Fotos werden height und width von der API ignoriert.

JSON-Antwort

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

{
 "kind": "directory#user#photo",
 "id": "the unique user id",
 "primaryEmail": "liz@example.com",
 "mimeType": "the photo mime type",
 "height": "the photo height in pixels",
 "width": "the photo width in pixels",
 "photoData": "web safe base64 encoded photo data"
}

Foto eines Nutzers löschen

Wenn Sie das Foto eines Nutzers löschen möchten, verwenden Sie die folgende DELETE-Anfrage und fügen Sie die unter Anfragen autorisieren beschriebene Autorisierung hinzu. Bei userKey kann es sich um die primäre E-Mail-Adresse des Nutzers, den Nutzer id oder eine beliebige E-Mail-Adresse des Nutzeralias handeln. 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, wo ein Foto eines Nutzers erforderlich ist, wird stattdessen eine Silhouette angezeigt.

Nutzerkonto löschen

Verwenden Sie zum Löschen eines Nutzerkontos die folgende DELETE-Anfrage und fügen Sie die unter Anfragen autorisieren beschriebene Autorisierung ein. Bei userKey kann es sich um die primäre E-Mail-Adresse des Nutzers, den einzelnen Nutzer id oder eine Alias-E-Mail-Adresse des Nutzers handeln. 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@beispiel.de gelöscht:

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

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

Wichtige Punkte, die vor dem Löschen eines Nutzers zu beachten sind:

  • 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 in den letzten 20 Tagen gelöschter Nutzer muss bestimmte Bedingungen erfüllen, bevor das Konto des Nutzers wiederhergestellt werden kann.

Verwenden Sie die folgende POST-Anfrage und fügen Sie die unter Anfragen autorisieren beschriebene Autorisierung ein, um ein Nutzerkonto wiederherzustellen. userKey ist der id des einzelnen Nutzers, der in der Antwort des Vorgangs In den letzten 20 Tagen gelöschte Nutzer abrufen gefunden wurde. Die primäre E-Mail-Adresse des Nutzers oder eine der Alias-E-Mail-Adressen des Nutzers kann nicht im userKey für diesen Vorgang 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@beispiel.de wiederhergestellt. Alle vorherigen Kontoeigenschaften des 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. Mit dem Vorgang Nutzer abrufen können Sie das Konto des wiederhergestellten Nutzers aufrufen.