Directory API: jednostki organizacyjne

Zarządzaj jednostkami organizacyjnymi

Drzewo organizacyjne konta Google Workspace składa się z jednostek organizacyjnych, które umożliwiają zarządzanie użytkownikami w logicznej strukturze hierarchicznej. Jest to funkcja podobna do tej, która znajduje się na karcie „Organizacje i użytkownicy” w konsoli administracyjnej. Hierarchia jednostek organizacyjnych klienta jest ograniczona do 35 poziomów. Więcej informacji znajdziesz w Centrum pomocy dla administratorów.

• Na koncie Google Workspace jest tylko jedno drzewo organizacji. Gdy to konto jest początkowo konfigurowane, ma jednostkę organizacyjną na poziomie konta. Jest to organizacja powiązana z domeną podstawową. Więcej informacji o domenie głównej znajdziesz w artykule Informacje o ograniczeniach interfejsu API.
• Ścieżka do jednostki organizacyjnej jest unikalna. Nazwa jednostki organizacyjnej może nie być niepowtarzalna w obrębie hierarchii organizacyjnej, ale jej nazwa jest niepowtarzalna w stosunku do jej jednostek organizacyjnych. Wielkość liter w nazwie jednostki organizacyjnej nie ma znaczenia.
• Jednostka organizacyjna dziedziczy zasady z hierarchii organizacyjnej. Każda jednostka organizacyjna może zablokować ten łańcuch dziedziczenia nadrzędnego, zastępując odziedziczoną zasadę. Pierwszeństwo jednej zasady nad inną jest określane przez najbliższą jednostkę organizacyjną. Oznacza to, że zasady jednostki niższego poziomu mogą mieć pierwszeństwo przed zasadami jednostek nadrzędnych. Więcej informacji o dziedziczeniu i użytkownikach w strukturze organizacji znajdziesz w Centrum pomocy administracji.
• Jednostkę organizacyjną można przesuwać w górę lub w dół w hierarchicznym drzewie. Powiązanych z nią użytkowników można przenosić pojedynczo lub zbiorczo podczas wypełniania nowej organizacji lub przenoszenia podzbioru użytkowników z jednej jednostki organizacyjnej do innej.
• Dane przechowywane w właściwościach jednostki organizacyjnej mogą się stale zmieniać. Gdy wysyłasz żądanie, właściwości zwracane dla danego elementu są spójne w momencie jego pobrania.Oznacza to, że nie zobaczysz „częściowych” aktualizacji. Jeśli operacja wyszukiwania zwraca więcej niż 1 element, nie ma gwarancji spójności między elementami.Dotyczy to zwłaszcza sytuacji, gdy odpowiedź obejmuje wiele stron w ramach podziału na strony.

Tworzenie jednostki organizacyjnej

Aby utworzyć jednostkę organizacyjną, użyj tego żądania POST i dołącz autoryzację opisaną w sekcji Autoryzowanie żądań.

Jeśli jesteś administratorem i tworzysz jednostkę organizacyjną, użyj my_customer.

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

Jeśli jesteś sprzedawcą i tworzysz jednostkę organizacyjną dla klienta, którego usługi sprzedajesz, użyj wartości customerId. Aby pobrać customerId, użyj operacji Pobierz użytkownika.

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

Aby poznać strukturę organizacyjną konta, odwiedź Centrum pomocy dla administratorów. Informacje o właściwościach żądań i odpowiedzi znajdziesz w dokumentacji interfejsu API.

Żądanie JSON

Poniższy przykład danych w formacie JSON dla resellera pokazuje przykładowy tekst żądania, który tworzy jednostkę organizacyjną sales_support. name i parentOrgUnitPath są wymagane:

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

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

Odpowiedź JSON

Pomyślna odpowiedź zwraca kod stanu HTTP 201. Wraz z kodem stanu odpowiedź zwróci właściwości nowej grupy:

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

Aktualizowanie jednostki organizacyjnej

Aby zaktualizować jednostkę organizacyjną, użyj podanego poniżej żądania PUT i dołącz autoryzację opisaną w sekcji Autoryzowanie żądań. Informacje o właściwościach żądania i odpowiedzi znajdziesz w dokumentacji interfejsu API:

Jeśli jesteś administratorem jednostki organizacyjnej, która aktualizuje jednostkę, użyj funkcji my_customer.

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

Jeśli jesteś sprzedawcą i aktualizujesz jednostkę organizacyjną dla klienta, którego dane zostały przez Ciebie przetworzone, użyj wartości customerId. Aby pobrać customerId, użyj operacji Pobierz użytkownika.

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

Żądanie JSON

W przykładzie poniżej opis jednostki organizacyjnej został zaktualizowany:

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

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

Uwagi dotyczące prośby o aktualizację:

• Wystarczy, że w prośbie podasz zaktualizowane informacje. Nie musisz podawać w żądaniu wszystkich właściwości grupy.
• Jeśli podczas tworzenia konta użytkownika nie został on przypisany do konkretnej jednostki organizacyjnej, konto znajduje się w jednostce organizacyjnej najwyższego poziomu.
• Jednostkę organizacyjną możesz przenieść do innej części struktury organizacyjnej konta, ustawiając w prośbie właściwość parentOrgUnitPath. Pamiętaj, że przeniesienie jednostki organizacyjnej może zmienić usługi i ustawienia użytkowników w tej jednostce.

Odpowiedź JSON

Pomyślna odpowiedź zwraca kod stanu HTTP 201. Oprócz kodu stanu odpowiedź zawiera też właściwości zaktualizowanej jednostki organizacyjnej.

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

Jeśli podczas tworzenia konta użytkownika nie został on przypisany do konkretnej jednostki organizacyjnej, konto znajduje się w jednostce organizacyjnej najwyższego poziomu. Jednostka organizacyjna użytkownika określa, do których usług Google Workspace ma on dostęp. Jeśli użytkownik zostanie przeniesiony do nowej organizacji, jego dostęp się zmieni. Więcej informacji o strukturach organizacyjnych znajdziesz w Centrum pomocy administracji. Więcej informacji o przenoszeniu użytkownika do innej organizacji znajdziesz w artykule Aktualizowanie użytkownika.

Pobieranie jednostki organizacyjnej

Jeśli jesteś administratorem i pobierasz dane jednostki organizacyjnej, użyj my_customer.

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

Jeśli jesteś sprzedawcą i pobierasz dane jednostki organizacyjnej dla klienta, którego dane są sprzedawane, użyj customerId. Aby uzyskać wartość customerId, użyj operacji Pobierz użytkownika.

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

Odpowiedź JSON

W przykładzie poniżej pobierana jest jednostka organizacyjna „frontline sales”. Zwróć uwagę na kodowanie HTTP „frontline+sales” w URI żądania:

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

Pomyślna odpowiedź zwraca kod stanu HTTP 200. Oprócz kodu stanu odpowiedź zawiera też ustawienia jednostki organizacyjnej:

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

Pobieranie jednostek organizacyjnych

Aby pobrać wszystkie podrzędne jednostki organizacyjne w jednostce organizacyjnej, jej podrzędne jednostki podrzędne lub wszystkie podrzędne jednostki organizacyjne wraz z określoną jednostką organizacyjną, użyj tego żądania GET i dołącz autoryzację opisaną w sekcji Autoryzowanie żądań. Właściwości żądań i odpowiedzi znajdziesz w dokumentacji API.

Jeśli jesteś administratorem konta i chcesz pobrać wszystkie podrzędne jednostki organizacyjne, użyj parametru my_customer. Aby ułatwić czytanie, przykład zawiera łamania wierszy:

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

Jeśli jesteś sprzedawcą pobierającym jednostki organizacyjne dla klienta sprzedawcy, użyj customerId. Aby uzyskać wartość customerId, użyj operacji Pobierz użytkownika:

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

Parametr ciągu zapytania get zwraca albo all podjednostki organizacyjne w ramach orgUnitPath, albo bezpośrednie children jednostki orgUnitPath, albo wszystkie podjednostki organizacyjne i wybrany orgUnitPath dla all_including_parent. Wartość domyślna to type=children.

Odpowiedź JSON

Na przykład to żądanie zwraca wszystkie jednostki organizacyjne, zaczynając od jednostki /corp:

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

Pomyślna odpowiedź zwraca kod stanu HTTP 200. Oprócz kodu stanu odpowiedź zawiera też jednostki organizacyjne konta:

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

Usuwanie jednostki organizacyjnej

Aby usunąć jednostkę organizacyjną, użyj poniższego żądania DELETE i dołącz autoryzację opisaną w sekcji Autoryzowanie żądań. Aby pobrać customerId, użyj operacji Pobierz użytkownika. Informacje o właściwościach żądania i odpowiedzi znajdziesz w dokumentacji interfejsu API:

Jeśli jesteś administratorem konta i usuwasz jednostkę organizacyjną, użyj opcji my_customer.

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

Jeśli jesteś sprzedawcą i usuwasz jednostkę organizacyjną dla klienta, którego dane przetwarzasz, użyj opcji customerId. Aby uzyskać wartość customerId, użyj operacji Pobierz użytkownika.

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

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

Pomyślna odpowiedź zwraca kod stanu HTTP 200.

Możesz usuwać tylko te jednostki organizacyjne, które nie mają żadnych podrzędnych jednostek organizacyjnych ani nie są do nich przypisanych żadnych użytkowników. Zanim usuniesz jednostkę, musisz przypisać użytkowników do innych jednostek organizacyjnych i usunąć podrzędne jednostki organizacyjne.