Directory API: Organisationseinheiten

Organisationseinheiten verwalten

Die Organisationsstruktur eines Google Workspace-Kontos besteht aus Organisationseinheiten, mit denen Sie Ihre Nutzer in einer logischen und hierarchischen Struktur verwalten können. Das ist ähnlich wie die Funktion auf dem Tab „Organisationen und Nutzer“ in der Google Admin-Konsole. Die Hierarchie der Organisationseinheiten des Kunden ist auf 35 Ebenen begrenzt. Weitere Informationen finden Sie in der Admin-Hilfe.

Für ein Google Workspace-Konto gibt es nur einen Organisationsbaum. Wenn dieses Konto zum ersten Mal konfiguriert wird, hat es eine Organisationseinheit auf Kontoebene. Das ist die Organisation, die der primären Domain zugeordnet ist. Weitere Informationen zur primären Domain finden Sie unter API-Limits.
Der Pfadname einer Organisationseinheit ist eindeutig. Der Name der Organisationseinheit ist möglicherweise nicht eindeutig innerhalb der Organisationshierarchie, aber er ist eindeutig unter den zugehörigen Organisationseinheiten. Bei Namen von Organisationseinheiten wird die Groß-/Kleinschreibung nicht berücksichtigt.
Eine Organisationseinheit übernimmt Richtlinien aus der Organisationshierarchie. Jede Organisationseinheit kann diese Kette der Elternvererbung blockieren, indem sie die übernommene Richtlinie überschreibt. Die Priorität einer Richtlinie gegenüber einer anderen wird durch die nächstgelegene Organisationseinheit bestimmt. Das bedeutet, dass die Richtlinien einer untergeordneten Organisationseinheit Vorrang vor den Richtlinien der übergeordneten Organisationseinheiten haben können. Weitere Informationen zur Vererbung und zu Nutzern in einer Organisationsstruktur finden Sie in der Administratorhilfe.
Eine Organisationseinheit kann in einer hierarchischen Struktur nach oben oder unten verschoben werden. Die zugehörigen Nutzer der Organisation können einzeln oder in einem Batch verschoben werden, wenn eine neue Organisation erstellt oder eine Teilmenge von Nutzern von einer Organisationseinheit in eine andere verschoben wird.
Die in Properties von Organisationseinheiten gespeicherten Daten können sich ständig ändern. Wenn Sie eine Anfrage stellen, sind die für eine Entität zurückgegebenen Attribute zum Zeitpunkt des Abrufs der Entität garantiert konsistent.Das heißt, Sie sehen keine „teilweisen“ Aktualisierungen. Wenn bei einem Abrufvorgang mehr als eine Entität zurückgegeben wird, gibt es keine Konsistenzgarantie für die Entitäten.Das gilt insbesondere, wenn sich eine Antwort über mehrere Seiten erstreckt.

Organisationseinheit erstellen

Wenn Sie eine Organisationseinheit erstellen möchten, verwenden Sie die folgende POST-Anfrage und fügen Sie die in Anfragen autorisieren beschriebene Autorisierung ein.

Wenn Sie als Administrator eine Organisationseinheit erstellen, verwenden Sie my_customer.

POST https://admin.googleapis.com/admin/directory/v1/customer/my_customer/orgunits

Wenn Sie als Reseller eine Organisationseinheit für einen Kunden erstellen, für den Sie Produkte weiterverkauft haben, verwenden Sie customerId. Verwenden Sie die Aktion Retrieve a user (Nutzer abrufen), um die customerId abzurufen.

POST https://admin.googleapis.com/admin/directory/v1/customer/customerId/orgunits

Informationen zur Organisationsstruktur Ihres Kontos finden Sie in der Admin-Hilfe. Informationen zu den Anfrage- und Antwortattributen finden Sie in der API-Referenz.

JSON-Anfrage

Das folgende JSON-Beispiel für Reseller zeigt einen Beispielanfragetext, mit dem die Organisationseinheit „sales_support“ erstellt wird. Die folgenden name und parentOrgUnitPath sind erforderlich:

POST https://admin.googleapis.com/admin/directory/v1/customer/C03az79cb/orgunits

{
    "name": "sales_support",
    "description": "The sales support team",
    "parentOrgUnitPath": "/corp/support",
}

JSON-Antwort

Bei einer erfolgreichen Antwort wird der HTTP-Statuscode 201 zurückgegeben. Zusammen mit dem Statuscode werden in der Antwort die Eigenschaften der neuen Gruppe zurückgegeben:

{
    "kind": "directory#orgUnit",
    "name": "sales_support",
    "description": "The sales support team",
    "orgUnitPath": "/corp/support/sales_support",
    "parentOrgUnitPath": "/corp/support"
  }

Organisationseinheit aktualisieren

Wenn Sie eine Organisationseinheit aktualisieren möchten, verwenden Sie die folgende PUT-Anfrage und fügen Sie die in Anfragen autorisieren beschriebene Autorisierung ein. Informationen zu den Anfrage- und Antwortattributen finden Sie in der API-Referenz:

Wenn Sie als Administrator eine Organisationseinheit aktualisieren, verwenden Sie my_customer.

 PUT https://admin.googleapis.com/admin/directory/v1/customer/my_customer/orgunits/orgUnitPath

Wenn Sie als Reseller eine Organisationseinheit für einen Kunden aktualisieren, für den Sie Produkte weiterverkauft haben, verwenden Sie customerId. Verwenden Sie die Aktion Retrieve a user (Nutzer abrufen), um die customerId abzurufen.

PUT https://admin.googleapis.com/admin/directory/v1/customer/customerId/orgunits/orgUnitPath

JSON-Anfrage

Im folgenden Beispiel wurde die Beschreibung der Organisationseinheit aktualisiert:

PUT https://admin.googleapis.com/admin/directory/v1/customer/my_customer/orgunits/corp/support/sales_support

{
    "description": "The BEST sales support team"
}

Hinweise zu einer Aktualisierungsanfrage:

Sie müssen nur die aktualisierten Informationen in Ihrem Antrag angeben. Sie müssen nicht alle Attribute der Gruppe in die Anfrage aufnehmen.
Wenn ein Nutzer bei der Erstellung des Nutzerkontos keiner bestimmten Organisationseinheit zugewiesen wurde, befindet sich das Konto in der Organisationseinheit der obersten Ebene.
Sie können eine Organisationseinheit in einen anderen Teil der Organisationsstruktur Ihres Kontos verschieben, indem Sie die Property parentOrgUnitPath im Antrag festlegen. Wenn Sie eine Organisationseinheit verschieben, können sich die Dienste und Einstellungen für die Nutzer in der verschobenen Organisationseinheit ändern.

JSON-Antwort

Bei einer erfolgreichen Antwort wird der HTTP-Statuscode 201 zurückgegeben. Zusammen mit dem Statuscode werden in der Antwort die Eigenschaften der aktualisierten Organisationseinheit zurückgegeben.

{
    "kind": "directory#orgUnit",
    "name": "sales_support",
    "description": "The BEST sales support team",
    "orgUnitPath": "/corp/support/sales_support",
    "parentOrgUnitPath": "/corp/support"
}

Wenn ein Nutzer bei der Erstellung 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 Organisationsstrukturen finden Sie in der Administratorhilfe. Weitere Informationen zum Verschieben eines Nutzers in eine andere Organisation finden Sie unter Nutzer aktualisieren.

Organisationseinheit abrufen

Wenn Sie eine Organisationseinheit abrufen möchten, verwenden Sie die folgende GET-Anfrage und fügen Sie die in Anfragen autorisieren beschriebene Autorisierung ein. Der orgUnitPath-Suchstring ist der vollständige Pfad für diese Organisationseinheit. Informationen zu den Anfrage- und Antwortattributen finden Sie in der API-Referenz:

Wenn Sie als Administrator eine Organisationseinheit abrufen, verwenden Sie my_customer.

GET https://admin.googleapis.com/admin/directory/v1/customer/my_customer/orgunits/orgUnitPath

Wenn Sie als Reseller eine Organisationseinheit für einen weiterverkauften Kunden abrufen, verwenden Sie customerId. Verwenden Sie die Aktion Retrieve a user (Nutzer abrufen), um die customerId zu erhalten.

GET https://admin.googleapis.com/admin/directory/v1/customer/customerId/orgunits/orgUnitPath

JSON-Antwort

Im folgenden Beispiel wird die Organisationseinheit „Frontline Sales“ abgerufen. Beachten Sie die HTTP-Codierung „frontline+sales“ im URI der Anfrage:

GET https://admin.googleapis.com/admin/directory/v1/customer/my_customer/orgunits/corp/sales/frontline+sales

Bei einer erfolgreichen Antwort wird der HTTP-Statuscode 200 zurückgegeben. Zusammen mit dem Statuscode werden in der Antwort die Einstellungen der Organisationseinheit zurückgegeben:

{
    "kind": "directory#orgUnit",
    "name": "frontline sales",
    "description": "The frontline sales team",
    "orgUnitPath": "/corp/sales/frontline sales",
    "parentOrgUnitPath": "/corp/sales"
}

Organisationseinheiten abrufen

Wenn Sie alle untergeordneten Organisationseinheiten unter einer Organisationseinheit, die direkten untergeordneten Elemente einer Organisationseinheit oder alle untergeordneten Organisationseinheiten plus die angegebene Organisationseinheit abrufen möchten, verwenden Sie die folgende GET-Anfrage und fügen Sie die in Anfragen autorisieren beschriebene Autorisierung ein. Informationen zu den Anfrage- und Antwortattributen finden Sie in der API-Referenz.

Wenn Sie als Kontoadministrator alle untergeordneten Organisationseinheiten abrufen, verwenden Sie my_customer. Zur besseren Lesbarkeit enthält dieses Beispiel Zeilenumbrüche:

GET https://admin.googleapis.com/admin/directory/v1/customer/my_customer
/orgunits?orgUnitPath=full org unit path&type=all or children or all_including_parent

Wenn Sie als Reseller Organisationseinheiten für einen weiterverkauften Kunden abrufen, verwenden Sie customerId. So rufen Sie die customerId ab:

GET https://admin.googleapis.com/admin/directory/v1/customer/customerId
/orgunits?orgUnitPath=full org unit path&type=all or children or all_including_parent

Der get-Suchstring gibt entweder all Unterorganisationseinheiten unter der orgUnitPath, die unmittelbaren children der orgUnitPath oder alle Unterorganisationseinheiten und die angegebene orgUnitPath für all_including_parent zurück. Der Standardwert ist type=children.

JSON-Antwort

Mit dieser Anfrage werden beispielsweise alle Organisationseinheiten zurückgegeben, die mit der Organisationseinheit /corp beginnen:

GET https://admin.googleapis.com/admin/directory/v1/customer/my_customer/orgunits?orgUnitPath=/corp&type=all

Bei einer erfolgreichen Antwort wird der HTTP-Statuscode 200 zurückgegeben. Zusammen mit dem Statuscode werden in der Antwort die Organisationseinheiten des Kontos zurückgegeben:

{
"kind": "directory#orgUnits",
    "organizationUnits": [
     {
    "kind": "directory#orgUnit",
    "name": "sales",
    "description": "The corporate sales team",
    "orgUnitPath": "/corp/sales",
    "parentOrgUnitPath": "/corp"
     },
     {
    "kind": "directory#orgUnit",
    "name": "frontline sales",
    "description": "The frontline sales team",
    "orgUnitPath": "/corp/sales/frontline sales",
    "parentOrgUnitPath": "/corp/sales"
     },
     {
    "kind": "directory#orgUnit",
    "name": "support",
    "description": "The corporate support team",
    "orgUnitPath": "/corp/support",
    "parentOrgUnitPath": "/corp"
     },
     {
    "kind": "directory#orgUnit",
    "name": "sales_support",
    "description": "The BEST support team",
    "orgUnitPath": "/corp/support/sales_support",
    "parentOrgUnitPath": "/corp/support"
     }
  ]
  }

Organisationseinheit löschen

Wenn Sie eine Organisationseinheit löschen möchten, verwenden Sie die folgende DELETE-Anfrage und fügen Sie die in Anfragen autorisieren beschriebene Autorisierung ein. Verwenden Sie die Aktion Retrieve a user (Nutzer abrufen), um die customerId abzurufen. Informationen zu den Anfrage- und Antwortattributen finden Sie in der API-Referenz:

Wenn Sie ein Kontoadministrator sind und eine Organisationseinheit löschen, verwenden Sie my_customer.

DELETE https://admin.googleapis.com/admin/directory/v1/customer/my_customer/orgunits/orgUnitPath

Wenn Sie als Reseller eine Organisationseinheit für einen Kunden löschen, für den Sie Produkte weiterverkauft haben, verwenden Sie customerId. Verwenden Sie die Aktion Retrieve a user (Nutzer abrufen), um die customerId zu erhalten.

DELETE https://admin.googleapis.com/admin/directory/v1/customer/customerId/orgunits/orgUnitPath

Mit der folgenden DELETE-Anfrage dieses Reseller-Administrators wird beispielsweise die Organisationseinheit „backend_tests“ gelöscht:

DELETE https://admin.googleapis.com/admin/directory/v1/customer/C03az79cb/orgunits/corp/sales/backend_tests

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

Sie können nur Organisationseinheiten löschen, denen keine untergeordneten Organisationseinheiten oder Nutzer zugewiesen sind. Sie müssen Nutzer anderen Organisationseinheiten zuweisen und alle untergeordneten Organisationseinheiten entfernen, bevor Sie die Organisationseinheit löschen können.

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

Organisationseinheiten verwalten

Organisationseinheit erstellen

JSON-Anfrage

JSON-Antwort

Organisationseinheit aktualisieren

JSON-Anfrage

JSON-Antwort

Organisationseinheit abrufen

JSON-Antwort

Organisationseinheiten abrufen

JSON-Antwort

Organisationseinheit löschen

Directory API: Organisationseinheiten