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. Diese Funktion ähnelt der Funktion auf dem Tab "Organisationen und Nutzer" in der Admin-Konsole. Die Hierarchie der Organisationseinheiten des Kunden ist auf 35 Tiefenebenen beschränkt. Weitere Informationen finden Sie in der Admin-Hilfe.

  • Ein Google Workspace-Konto hat nur eine Organisationsstruktur. Bei der anfänglichen Konfiguration dieses Kontos ist ihm eine Organisationseinheit auf Kontoebene zugewiesen. Dies ist die Organisation, die mit der primären Domain verknüpft ist. Weitere Informationen zur primären Domain finden Sie unter API-Limits.
  • Der Pfadname einer Organisationseinheit ist eindeutig. Der Name der Organisationseinheit ist innerhalb der Organisationshierarchie möglicherweise nicht eindeutig, aber innerhalb der gleichgeordneten Organisationseinheiten nur einmal. Beim Namen einer Organisationseinheit wird die Groß-/Kleinschreibung nicht berücksichtigt.
  • Eine Organisationseinheit übernimmt die Richtlinien von der Organisationshierarchie. Jede Organisationseinheit kann diese Vererbungskette blockieren, indem die übernommene Richtlinie überschrieben wird. Der Vorrang einer Richtlinie gegenüber einer anderen wird von der nächstgelegenen Organisationseinheit bestimmt. Das bedeutet, dass die Richtlinien einer niedrigeren Organisationseinheit Vorrang vor den Richtlinien der höheren übergeordneten Einheiten haben. Mit der Einstellung blockInheritance kann die Übernahme von Einstellungen für eine Organisationseinheit und ihre Unterorganisation blockiert werden. blockInheritance wurde verworfen. Die Festlegung auf „true“ wird nicht mehr unterstützt und kann unbeabsichtigte Folgen haben. Weitere Informationen zur Übernahme und zu Nutzern in einer Organisationsstruktur finden Sie in der Hilfe für Administratoren.
  • Eine Organisationseinheit kann in einer Hierarchie nach oben oder unten verschoben werden. Außerdem können die mit der Organisation verknüpften Nutzer einzeln oder in einem Batch verschoben werden, wenn eine neue Organisation befüllt wird oder ein Teil der Nutzer von einer Organisationseinheit in eine andere verschoben wird.
  • Die in den Eigenschaften einer Organisationseinheit gespeicherten Daten können sich ständig ändern. Wenn Sie eine Anfrage stellen, sind die für eine Entität zurückgegebenen Eigenschaften zum Zeitpunkt des Abrufs der Entität garantiert konsistent.Es gibt also keine „teilweise“ Aktualisierungen. Wenn bei einem Abrufvorgang mehr als eine Entität zurückgegeben wird, gibt es keine entitätsübergreifende Konsistenzgarantie.Dies gilt insbesondere, wenn eine Antwort mehrere Seiten umfasst.

Organisationseinheit erstellen

Verwenden Sie die folgende POST-Anfrage und fügen Sie die unter Anfragen autorisieren beschriebene Autorisierung hinzu, um eine Organisationseinheit zu erstellen.

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 eines Resellers erstellen, verwenden Sie customerId. Verwenden Sie den Vorgang Retrieve a user (Nutzer abrufen), um 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 Anfrage- und Antwortattributen finden Sie in der API-Referenz.

JSON-Anfrage

Das folgende JSON-Reseller-Beispiel zeigt einen Beispiel-Anfragetext, mit dem die Organisationseinheit „sales_support“ erstellt wird. 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",
    "blockInheritance": false
}

JSON-Antwort

Bei einer erfolgreichen Antwort wird der HTTP 201-Statuscode 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",
    "blockInheritance": false
  }

Organisationseinheit aktualisieren

Wenn Sie eine Organisationseinheit aktualisieren möchten, verwenden Sie die folgende PUT-Anfrage und fügen Sie die unter Anfragen autorisieren beschriebene Autorisierung hinzu. 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 eines Resellers aktualisieren, verwenden Sie customerId. Verwenden Sie den Vorgang Retrieve a user (Nutzer abrufen), um das 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 in Ihrem Antrag nur die aktualisierten Informationen einreichen. Sie müssen nicht alle Eigenschaften der Gruppe in der Anfrage eingeben.
  • Wenn ein Nutzer bei der Erstellung des Nutzerkontos keiner bestimmten Organisationseinheit zugewiesen wurde, befindet sich das Konto in der obersten Organisationseinheit.
  • Sie können eine Organisationseinheit in einen anderen Teil der Organisationsstruktur Ihres Kontos verschieben, indem Sie die Property parentOrgUnitPath in der Anfrage festlegen. Beachten Sie, dass sich durch das Verschieben einer Organisationseinheit die Dienste und Einstellungen für die Nutzer in der zu verschiebenden Organisationseinheit ändern können.

JSON-Antwort

Bei einer erfolgreichen Antwort wird der HTTP 201-Statuscode 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",
    "blockInheritance": false
}

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.

Organisationseinheit abrufen

Wenn Sie eine Organisationseinheit abrufen möchten, verwenden Sie die folgende GET-Anfrage und fügen Sie die unter Anfragen autorisieren beschriebene Autorisierung hinzu. Der Abfragestring „orgUnitPath“ 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 Kunden eines Resellers abrufen, verwenden Sie die customerId. Verwenden Sie den Vorgang Retrieve a user (Nutzer abrufen), um den customerId abzurufen.

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

JSON-Antwort

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

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",
    "blockInheritance": false
}

Organisationseinheiten abrufen

Wenn Sie alle untergeordneten Organisationseinheiten einer Organisationseinheit, die direkt untergeordneten Organisationseinheiten oder alle untergeordneten Organisationseinheiten plus die angegebene Organisationseinheit abrufen möchten, verwenden Sie die folgende GET-Anfrage und fügen Sie die unter 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 werden in diesem Beispiel Zeilenumsätze verwendet:

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 Kunden eines Resellers abrufen, verwenden Sie die customerId. Verwenden Sie den Vorgang Retrieve a user (Nutzer abrufen), um das customerId abzurufen:

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 Abfragestring get gibt entweder all untergeordnete Organisationseinheiten unter der orgUnitPath, die unmittelbare children der orgUnitPath oder alle untergeordneten Organisationseinheiten und die angegebene orgUnitPath für all_including_parent zurück. Der Standardwert ist type=children.

JSON-Antwort

Diese Anfrage gibt beispielsweise alle Organisationseinheiten beginnend bei der Organisationseinheit /corp zurück:

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",
    "blockInheritance": false
     },
     {
    "kind": "directory#orgUnit",
    "name": "frontline sales",
    "description": "The frontline sales team",
    "orgUnitPath": "/corp/sales/frontline sales",
    "parentOrgUnitPath": "/corp/sales",
    "blockInheritance": false
     },
     {
    "kind": "directory#orgUnit",
    "name": "support",
    "description": "The corporate support team",
    "orgUnitPath": "/corp/support",
    "parentOrgUnitPath": "/corp",
    "blockInheritance": false
     },
     {
    "kind": "directory#orgUnit",
    "name": "sales_support",
    "description": "The BEST support team",
    "orgUnitPath": "/corp/support/sales_support",
    "parentOrgUnitPath": "/corp/support",
    "blockInheritance": false
     }
  ]
  }

Organisationseinheit löschen

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

Wenn Sie als Kontoadministrator 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 eines Resellers löschen, verwenden Sie die customerId. Verwenden Sie den Vorgang Retrieve a user (Nutzer abrufen), um den customerId abzurufen.

DELETE https://admin.googleapis.com/admin/directory/v1/customer/customerId/orgunits/orgUnitPath
Beispiel: Die DELETE-Anfrage dieses Reseller-Administrators löscht die Organisationseinheit „backend_tests“:
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 vor dem Löschen Nutzer anderen Organisationseinheiten zuweisen und alle untergeordneten Organisationseinheiten entfernen.