Directory API: Gruppen

Mit Sammlungen den Überblick behalten Sie können Inhalte basierend auf Ihren Einstellungen speichern und kategorisieren.

Gruppe erstellen

Verwenden Sie zum Erstellen einer Gruppe die folgende POST-Anfrage und fügen Sie die unter Anfragen autorisieren beschriebene Autorisierung hinzu. Eine Gruppe kann für jede mit dem Konto verknüpfte Domain erstellt werden. Informationen zu den Abfragestrings, Anfrage- und Antwortattributen finden Sie in der API-Referenz:

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

JSON-Anfrage

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

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

Eine erfolgreiche Antwort gibt einen HTTP 201-Statuscode zurück. Zusammen mit dem Statuscode gibt die Antwort die Properties für die neue Gruppe zurück.

Gruppe aktualisieren

Um die Einstellungen einer Gruppe zu aktualisieren, verwenden Sie die folgende PUT-Anfrage und fügen Sie die unter Anfragen autorisieren beschriebene Autorisierung hinzu. groupKey ist die E-Mail-Adresse der Gruppe, eine der E-Mail-Adressen des Gruppenalias oder die eindeutige id der Gruppe. Informationen zu den Abfragestrings, Anfrage- und Antwortattributen finden Sie in der API-Referenz:

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

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

JSON-Anfrage

Im folgenden Beispiel lautet die eindeutige groupKey 'nnn& der Name der Gruppe wurde in die APAC-Vertriebsgruppe geändert:

PUT https://admin.googleapis.com/admin/directory/v1/groups/nnn
{
    "email": "sales_group@example.com",
    "name": "APAC Sales Group"
}

Wenn Sie eine Aktualisierung beantragen möchten, müssen Sie lediglich die aktualisierten Informationen einreichen. Sie müssen nicht alle Eigenschaften der Gruppe in der Anfrage eingeben.

JSON-Antwort

Eine erfolgreiche Antwort gibt einen HTTP 201-Statuscode zurück. Zusammen mit dem Statuscode gibt die Antwort die Properties für die neue Gruppe zurück.

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

Verwenden Sie zum Hinzufügen eines Gruppenalias die folgende POST-Anfrage und fügen Sie die unter Anfragen autorisieren beschriebene Autorisierung hinzu. groupKey ist die E-Mail-Adresse der Gruppe, eine der E-Mail-Adressen des Gruppenalias oder der eindeutige id der Gruppe. Informationen zu den Abfragestrings, Anfrage- und Antwortattributen finden Sie in der API-Referenz:

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

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

JSON-Anfrage

Die folgende JSON-Anfrage zeigt eine Beispielanfrage zum Erstellen eines Gruppenalias. groupKey ist der eindeutige id einer Gruppe, dargestellt durch NNNN
POST https://admin.googleapis.com/admin/directory/v1/groups/NNNN/aliases
{
    "alias": "best_sales_group@example.com"
}

JSON-Antwort

Eine erfolgreiche Antwort gibt einen HTTP 201-Statuscode zurück. Zusammen mit dem Statuscode gibt die Antwort die Eigenschaften für den neuen Gruppenalias zurück.

Gruppe abrufen

Verwenden Sie zum Abrufen einer Gruppe die folgende GET-Anfrage und fügen Sie die unter Anfragen autorisieren beschriebene Autorisierung hinzu. groupKey ist die E-Mail-Adresse der Gruppe, eine der E-Mail-Adressen des Gruppenalias oder der eindeutige id der Gruppe. Informationen zu den Abfragestrings, Anfrage- und Antwortattributen finden Sie in der API-Referenz:
GET https://admin.googleapis.com/admin/directory/v1/groups/groupKey

Google empfiehlt, die E-Mail-Adresse der Gruppe nicht als Schlüssel für dauerhafte 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

JSON-Antwort

Eine erfolgreiche Antwort gibt einen HTTP 200-Statuscode zurück. Zusammen mit dem Statuscode gibt die Antwort die Einstellungen der Gruppe zurück:

{
    "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 ein bestimmtes Konto abrufen möchten, verwenden Sie die folgende GET-Anfrage und fügen Sie die unter Anfragen autorisieren beschriebene Autorisierung hinzu. Informationen zu den Abfragestrings, Anfrage- und Antwortattributen finden Sie in der API-Referenz. Zur besseren Lesbarkeit werden in diesem Beispiel Zeilen zurückgegeben:

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

Beim Abrufen:

  • 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 dem Wert my_customer oder dem Wert customerId für das Konto. Als Kontoadministrator verwenden Sie den String my_customer, um das customerId Ihres Kontos darzustellen. Wenn Sie ein Reseller sind und auf das Konto eines Reseller-Kunden zugreifen, verwenden Sie das customerId des Reseller-Kontos. Verwenden Sie für den Wert customerId den primären Domainnamen des Kontos aus der Anfrage Alle Nutzer in einer Domain abrufen. Die resultierende Antwort hat den Wert customerId.
  • Verwendung der Argumente domain und customer: Die API gibt alle Gruppen für domain zurück.
  • Ohne die Argumente domain und customer: Die 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 API-Anfrage stellt.

In diesem Beispiel fordert ein Kontoadministrator mit my_customer eine Liste aller Gruppen eines Kontos an:

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

In diesem Beispiel gibt die Anfrage eines Reseller-Administrators alle Gruppen für das weiterverkaufte Konto mit dem customerId C03az79cb zurück. Pro Antwortseite werden maximal 2 Ergebnisse zurückgegeben. Für die folgende 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

JSON-Antwort

Eine erfolgreiche Antwort gibt einen HTTP 200-Statuscode zurück. Zusammen mit dem Statuscode gibt die Antwort die Gruppen in alphabetischer Reihenfolge der Gruppen-E-Mail zurück. Die Groß- und Kleinschreibung spielt dabei keine Rolle:

{
"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 unter Anfragen autorisieren beschriebene Autorisierung hinzu. Zur besseren Lesbarkeit werden in diesem Beispiel Zeilen zurückgegeben:

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.
  • Die userKey kann die primäre E-Mail-Adresse des Nutzers, die Alias-E-Mail-Adresse des Nutzers, eine primäre E-Mail-Adresse einer Gruppe, der Gruppen-E-Mail-Alias oder die eindeutige id des Nutzers sein, die sich über den Nutzerabruf finden lässt.
  • Der in userKey angegebene Nutzer oder die angegebene Gruppe muss zu Ihrer Domain gehören.
  • Verwenden Sie den Abfragestring pageToken für Antworten mit einer großen Anzahl von Gruppen. Bei einer Paginierung gibt die Antwort das Attribut nextPageToken zurück. Dieses gibt ein Token für die nächste Seite mit Antwortergebnissen an. In Ihrer nächsten Anfrage wird dieses Token als Abfragestringwert pageToken verwendet.

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

JSON-Antwort

Eine erfolgreiche Antwort liefert einen HTTP 200-Statuscode und die Liste der Mitgliedsinformationen:

  • Alle Gruppen, für die ein Mitglied ein Abo hat, werden zurückgegeben, einschließlich Gruppen außerhalb der Domain des Nutzers
  • Die Gruppen werden in alphabetischer Reihenfolge der E-Mail-Adressen der einzelnen Gruppen zurückgegeben.
  • Im Text der Antwort ist id die eindeutige ID der Gruppe:
  • In der Antwort enthält die Liste einer Gruppe außerhalb der Domain des Nutzers die Aliasse der externen Gruppe nicht.
{
    "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"
     }
  ],
   "nextPakeToken": "NNNNN"
}

Alle Gruppenaliasse abrufen

Wenn Sie alle Aliasse einer Gruppe abrufen möchten, verwenden Sie die folgende GET-Anfrage und fügen Sie die unter Anfragen autorisieren beschriebene Autorisierung hinzu. groupKey kann die primäre E-Mail-Adresse der Gruppe, der eindeutige id der Gruppe oder ein beliebiger E-Mail-Alias der Gruppe sein. Informationen zu den Anfrage- und Antwortattributen finden Sie in der API-Referenz:

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

Eine erfolgreiche Antwort gibt einen HTTP 201-Statuscode zurück. Zusammen mit dem Statuscode gibt die Antwort eine Liste der Aliasse der Gruppe zurück.

Gruppenalias löschen

Um den Alias einer Gruppe zu löschen, verwenden Sie die folgende DELETE-Anfrage und fügen Sie die unter Anfragen autorisieren beschriebene Autorisierung hinzu. groupKey kann die primäre E-Mail-Adresse der Gruppe, der eindeutige id der Gruppe oder ein beliebiger E-Mail-Alias der Gruppe sein. aliasId ist der zu löschende Alias. Informationen zu den Anfrage- und Antwortattributen finden Sie in der API-Referenz:

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

Eine erfolgreiche Antwort gibt einen HTTP 201-Statuscode zurück.

Gruppe löschen

Verwenden Sie zum Löschen einer Gruppe die folgende DELETE-Anfrage und fügen Sie die unter Anfragen autorisieren beschriebene Autorisierung hinzu. groupKey ist der eindeutige id einer Gruppe:

DELETE https://admin.googleapis.com/admin/directory/v1/groups/groupKey
Diese DELETE-Anfrage löscht beispielsweise die Gruppe mit der nnnn-Gruppe id:
DELETE https://admin.googleapis.com/admin/directory/v1/group/nnnn

Eine erfolgreiche Antwort gibt einen HTTP 200-Statuscode zurück.

Wenn eine Gruppe gelöscht wird, gilt Folgendes:

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