Gruppenverwaltung

Auf dieser Seite wird beschrieben, wie Sie Google-Gruppen mit der Directory API verwalten:

  • Gruppe erstellen
  • Gruppe aktualisieren
  • Gruppenalias hinzufügen
  • Gruppe abrufen
  • Alle Gruppen für eine Domain oder das Konto abrufen
  • Alle Gruppen für ein Mitglied abrufen
  • Alle Gruppenaliasse abrufen
  • Gruppenalias löschen
  • Gruppe löschen

Gruppe erstellen

Wenn Sie eine Gruppe erstellen möchten, verwenden Sie die folgende POST-Anfrage und fügen Sie die in Anfragen autorisieren beschriebene Autorisierung ein. Sie können eine Gruppe für jede Domain erstellen, die mit dem Konto verknüpft ist. Informationen zu den Abfragestrings, Anfrage- und Antwortattributen finden Sie unter der Methode groups.insert. 

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

Die folgende JSON-Anfrage zeigt einen Beispielanfragetext, mit dem eine Gruppe erstellt wird. Die E‑Mail-Adresse der Gruppe ist vertriebsgruppe@beispiel.de: 

{
   "email": "sales_group@example.com",
   "name": "Sales Group",
   "description": "This is the Sales group."
}

Bei einer erfolgreichen Antwort wird der HTTP-Statuscode 201 und die Attribute für die neue Gruppe zurückgegeben.

Gruppe aktualisieren

Wenn Sie die Einstellungen einer Gruppe aktualisieren möchten, verwenden Sie die folgende PUT-Anfrage und fügen Sie die in Anfragen autorisieren beschriebene Autorisierung ein. groupKey ist die E-Mail-Adresse der Gruppe, die E-Mail-Adresse eines der Gruppenaliasse oder die eindeutige id der Gruppe. Informationen zu den Abfragestrings, Anfrage- und Antwortattributen finden Sie in der Methode groups.update.

PUT https://admin.googleapis.com/admin/directory/v1/groups/groupKey

Im Allgemeinen empfehlen wir, die E-Mail-Adresse der Gruppe nicht als Schlüssel für persistente Daten zu verwenden, da sich die E-Mail-Adresse ändern kann.

Im Allgemeinen empfehlen wir, die E-Mail-Adresse der Gruppe nicht als Schlüssel für persistente Daten zu verwenden, da sich die E-Mail-Adresse ändern kann.

Im folgenden Beispiel ist die eindeutige groupKey nnn und der Name der Gruppe ist „APAC Sales Group“: 

PUT https://admin.googleapis.com/admin/directory/v1/groups/nnn

{
    "email": "sales_group@example.com",
    "name": "APAC Sales Group"
}

Bei einer Aktualisierungsanfrage müssen Sie nur die aktualisierten Informationen in Ihrer Anfrage einreichen. Sie müssen nicht alle Eigenschaften der Gruppe in die Anfrage aufnehmen.

Bei einer erfolgreichen Antwort wird der HTTP-Statuscode 201 und die Attribute für die neue Gruppe zurückgegeben: 

{
    "kind": "directory#groups",
    "id": "group's unique ID",
    "etag": "group's unique ETag",
    "email": "sales_group@example.com",
    "name": "APAC Sales Group",
    "directMembersCount": "5",
    "description": "This is the APAC sales group.",
    "adminCreated": true,
    "aliases": [
     {
        "alias": "best_sales_group@example.com"
     }
    ],
    "nonEditableAliases": [
     {
        "alias": "liz@test.com"
     }
    ]
}

Gruppenalias hinzufügen

Wenn Sie einen Gruppenalias hinzufügen möchten, verwenden Sie die folgende POST-Anfrage und fügen Sie die in Anfragen autorisieren beschriebene Autorisierung ein. groupKey ist die E-Mail-Adresse der Gruppe, die E-Mail-Adresse eines der Gruppenaliase oder die eindeutige id der Gruppe. Informationen zu den Abfragestrings, Anfrage- und Antwortattributen finden Sie in der groups-Ressource.

POST https://admin.googleapis.com/admin/directory/v1/groups/groupKey/aliases

Im Allgemeinen empfiehlt Google, die E-Mail-Adresse der Gruppe nicht als Schlüssel für persistente Daten zu verwenden, da sich die E-Mail-Adresse ändern kann.

Die folgende JSON-Anfrage zeigt eine Beispielanfrage zum Erstellen eines Alias für eine Gruppe. Die groupKey ist die eindeutige id der Gruppe, die durch NNNN dargestellt wird.

POST https://admin.googleapis.com/admin/directory/v1/groups/NNNN/aliases

{
    "alias": "best_sales_group@example.com"
}

Bei einer erfolgreichen Antwort wird der HTTP-Statuscode 201 und die Attribute für den neuen Gruppenalias zurückgegeben.

Gruppe abrufen

Wenn Sie eine Gruppe abrufen möchten, verwenden Sie die folgende GET-Anfrage und fügen Sie die in Anfragen autorisieren beschriebene Autorisierung ein. groupKey ist die E-Mail-Adresse der Gruppe, die E-Mail-Adresse eines der Gruppenaliase oder die eindeutige id der Gruppe. Informationen zu den Abfragestrings, Anfrage- und Antwortattributen finden Sie unter der Methode groups.get. 

GET https://admin.googleapis.com/admin/directory/v1/groups/groupKey

Im Allgemeinen empfiehlt Google, die E-Mail-Adresse der Gruppe nicht als Schlüssel für persistente Daten zu verwenden, da sich die E-Mail-Adresse ändern kann.

Im folgenden Beispiel lautet die eindeutige groupKey-ID nnnn: 

GET https://admin.googleapis.com/admin/directory/v1/groups/nnnn

Bei einer erfolgreichen Antwort wird der HTTP-Statuscode 200 und die Einstellungen der Gruppe zurückgegeben: 

{
    "kind": "directory#groups",
    "id": "group's unique ID",
    "etag": "group's unique ETag",
    "email": "sales_group@example.com",
    "name": "APAC Sales Group",
    "directMembersCount": "5",
    "description": "This is the APAC sales group.",
    "adminCreated": true,
    "aliases": [
     {
        "alias": "best_sales_group@example.com"
     }
    ],
    "nonEditableAliases": [
     {
        "alias": "liz@test.com"
     }
    ]
}

Alle Gruppen für eine Domain oder das Konto abrufen

Wenn Sie alle Gruppen für eine bestimmte Domain oder das Konto abrufen möchten, verwenden Sie die folgende GET-Anfrage und fügen Sie die in Anfragen autorisieren beschriebene Autorisierung ein. Informationen zu den Abfragestrings, Anfrage- und Antwortattributen finden Sie in der Methode groups.list. Zur besseren Lesbarkeit enthält dieses Beispiel Zeilenumbrüche: 

GET https://admin.googleapis.com/admin/directory/v1/groups?domain=domain name
&customer=my_customer or customerId&pageToken=pagination token
&maxResults=max results

Beachten Sie beim Abrufen aller Gruppen für eine Domain oder das Konto Folgendes:

  • Alle Gruppen für eine Subdomain: Verwenden Sie das Argument domain mit dem Namen der Domain.
  • Alle Gruppen für das Konto: Verwenden Sie das Argument customer mit my_customer oder dem customerId-Wert des Kontos. Als Kontoadministrator können Sie den String my_customer verwenden, um die customerId Ihres Kontos darzustellen. Wenn Sie als Reseller auf das Konto eines Kunden zugreifen, der über Sie gekauft hat, verwenden Sie die customerId des Kontos. Verwenden Sie für den customerId-Wert den primären Domainnamen des Kontos in der Anfrage des Vorgangs Alle Nutzer in einer Domain abrufen. Die resultierende Antwort hat den Wert customerId.
  • domain- und customer-Argumente verwenden: Die Directory API gibt alle Gruppen für die domain zurück.
  • Die Argumente domain und customer werden nicht verwendet: Die Directory API gibt alle Gruppen für das Konto zurück, das mit my_customer verknüpft ist. Dies ist das Konto customerId des Administrators, der die Anfrage stellt.
  • Wenn Sie sowohl das Argument customer als auch das Argument userKey verwenden, gibt die Directory API einen Fehler zurück. Sie müssen zwei separate Anfragen mit diesen Argumenten stellen.

Im folgenden Beispiel verwendet ein Kontoadministrator my_customer, um eine Liste aller Gruppen eines Kontos anzufordern:

GET https://admin.googleapis.com/admin/directory/v1/groups?domain=sales.com&customer=my_customer&maxResults=2

Im folgenden Beispiel gibt die Anfrage eines Reseller-Administrators alle Gruppen für das weiterverkaufte Konto mit der customerId C03az79cb zurück. Die maximale Anzahl von Ergebnissen, die pro Antwortseite zurückgegeben werden, beträgt 2. Für die nachfolgende Liste der Nutzer in dieser Antwort gibt es ein nextPageToken: 

GET https://admin.googleapis.com/admin/directory/v1/groups?domain=sales.com&customer=C03az79cb&maxResults=2

Bei einer erfolgreichen Antwort wird der HTTP-Statuscode 200 und die Gruppen in alphabetischer Reihenfolge der Gruppen-E-Mail-Adresse zurückgegeben: 

{
"kind": "directory#groups",
    "groups": [
     {
      "kind": "directory#groups",
      "id": "group's unique ID",
      "etag": "group's unique ETag",
      "email": "support@sales.com",
      "name": "Sales support",
      "directMembersCount": "6",
      "description": "The sales support group",
      "adminCreated": true
     },
     {
      "kind": "directory#groups",
      "id": "group's unique ID",
      "etag": "group's unique ETag",
      "email": "travel@sales.com",
      "name": "Sales travel",
      "directMembersCount": "2",
      "description": "The travel group supporting sales",
      "adminCreated": false,
      "aliases": [
       {
         "alias": "best_sales_group@example.com"
       }
      ],
      "nonEditableAliases": [
       {
         "alias": "liz@test.com"
       }
      ]
     },
  "nextPageToken": "NNNN"
  }

Alle Gruppen für ein Mitglied abrufen

Wenn Sie alle Gruppen abrufen möchten, für die ein Mitglied ein Abo hat, 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/groups?userKey=user key
&pageToken=pagination token
&maxResults=maximum results per response page
  • Ein Mitglied kann entweder ein Nutzer oder eine Gruppe sein.
  • userKey kann die primäre E-Mail-Adresse des Nutzers, die Alias-E-Mail-Adresse des Nutzers, die primäre E-Mail-Adresse einer Gruppe, der E-Mail-Alias einer Gruppe oder die eindeutige id des Nutzers sein, die mit dem Vorgang zum Abrufen eines Nutzers abgerufen werden kann.
  • Der in userKey angegebene Nutzer oder die Gruppe muss zu Ihrer Domain gehören.
  • Verwenden Sie den Abfragestring pageToken für Antworten mit einer großen Anzahl von Gruppen. Bei der Paginierung wird in der Antwort die Eigenschaft nextPageToken zurückgegeben, die ein Token für die nächste Seite mit Antwort-Ergebnissen enthält. In Ihrer nächsten Anfrage wird dieses Token als Wert des Abfragestrings pageToken verwendet.
  • Wenn Sie sowohl das Argument customer als auch das Argument userKey verwenden, gibt die Directory API einen Fehler zurück. Sie müssen zwei separate Anfragen mit diesen Argumenten stellen.

Informationen zu den Anfrage- und Antwortattributen finden Sie in der Methode groups.list.

Bei einer erfolgreichen Antwort wird der HTTP-Statuscode 200 und die Liste der Mitgliedsinformationen zurückgegeben:

  • Es werden alle Gruppen zurückgegeben, für die ein Mitglied ein Abo hat, einschließlich Gruppen außerhalb der Domain des Nutzers.
  • Die Gruppen werden in alphabetischer Reihenfolge der E-Mail-Adresse jeder Gruppe zurückgegeben.
  • Im Antworttext ist id die eindeutige ID der Gruppe.
  • In der Antwort werden die Aliase einer Gruppe außerhalb der Domain des Nutzers nicht aufgeführt. 
{
    "kind": "directory#groups",
    "groups": [
     {
      "kind": "directory#group",
      "id": "group's unique ID",
      "etag": "group's unique ETag",
      "email": "sales_group@example.com",
      "name": "sale group",
      "directMembersCount": "5",
      "description": "Sales group"
     },
     {
      "kind": "directory#group",
      "id": "group's unique ID",
      "etag": "group's unique ETag",
      "email": "support_group.com",
      "name": "support group",
      "directMembersCount": "5",
      "description": "Support group"
     }
  ],
   "nextPageToken": "NNNNN"
}

Alle Gruppenaliasse abrufen

Wenn Sie alle Aliase einer Gruppe abrufen möchten, verwenden Sie die folgende GET-Anfrage und fügen Sie die in Anfragen autorisieren beschriebene Autorisierung ein. Die groupKey kann die primäre E-Mail-Adresse der Gruppe, die eindeutige id der Gruppe oder eine der E-Mail-Adressen der Gruppenaliasse sein. Informationen zu den Anfrage- und Antwortattributen finden Sie in der groups-Ressource. 

GET https://admin.googleapis.com/admin/directory/v1/groups/groupKey/aliases

Bei einer erfolgreichen Antwort wird der HTTP-Statuscode 201 und eine Liste der Aliasse der Gruppe zurückgegeben.

Gruppenalias löschen

Wenn Sie den Alias einer Gruppe löschen möchten, verwenden Sie die folgende DELETE-Anfrage und fügen Sie die in Anfragen autorisieren beschriebene Autorisierung ein. Die groupKey kann die primäre E-Mail-Adresse der Gruppe, die eindeutige id der Gruppe oder eine der E-Mail-Adressen der Gruppenaliasse sein. aliasId ist der Alias, der gelöscht wird. Informationen zu den Anfrage- und Antwortattributen finden Sie in der groups-Ressource: 

DELETE https://admin.googleapis.com/admin/directory/v1/groups/groupKey/aliases/aliasId

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

Gruppe löschen

Wenn Sie eine Gruppe löschen möchten, verwenden Sie die folgende DELETE-Anfrage und fügen Sie die in Anfragen autorisieren beschriebene Autorisierung ein. Die groupKey ist die eindeutige id der Gruppe: 

DELETE https://admin.googleapis.com/admin/directory/v1/groups/groupKey

Mit dieser DELETE-Anfrage wird beispielsweise die Gruppe mit der nnnn-Gruppe id gelöscht:

DELETE https://admin.googleapis.com/admin/directory/v1/group/nnnn

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

Wenn eine Gruppe gelöscht wird, passiert Folgendes:

  • Alle Mitglieder der Gruppe werden gelöscht. Die Nutzerkonten des Mitglieds werden nicht gelöscht.
  • Das Gruppenarchiv wird gelöscht.
  • Nachrichten, die an die Adresse der gelöschten Gruppe gesendet werden, werden nicht zugestellt. Stattdessen erhält der Absender eine Unzustellbarkeitsnachricht.