API Directory: unità organizzative

Gestisci unità organizzative

La struttura organizzativa di un account Google Workspace è composta da unità organizzative che consentono di gestire gli utenti in una struttura logica e gerarchica. Si tratta di una funzionalità simile a quella della scheda "Organizzazioni e utenti" della Console di amministrazione. La gerarchia delle unità organizzative del cliente è limitata a 35 livelli di profondità. Per ulteriori informazioni, consulta il Centro assistenza per amministratori.

  • Esiste una sola struttura dell'organizzazione per un account Google Workspace. Quando questo account viene configurato per la prima volta, è associato a un'unità organizzativa a livello di account. Questa è l'organizzazione associata al dominio principale. Per saperne di più sul dominio principale, consulta le informazioni sui limiti API.
  • Il percorso di un'unità organizzativa è univoco. Il nome dell'unità organizzativa potrebbe non essere univoco all'interno della gerarchia dell'organizzazione, ma è univoco per le unità organizzative gemelle. Inoltre, il nome di un'unità organizzativa non fa distinzione tra maiuscole e minuscole.
  • Un'unità organizzativa eredita i criteri dalla gerarchia organizzativa. Qualsiasi unità organizzativa può bloccare questa catena di ereditarietà parentale sostituendo il criterio ereditato. La precedenza di un criterio rispetto a un altro è determinata dall'unità organizzativa più vicina. Ciò significa che i criteri di un'unità organizzativa di livello inferiore possono avere la precedenza su quelli delle unità parentali di livello superiore. L'impostazione blockInheritance consente di bloccare l'ereditarietà delle impostazioni in un'unità organizzativa e alla relativa organizzazione secondaria. L'API blockInheritance è deprecata. L'impostazione su "true" non è più supportata e può avere conseguenze involontarie. Per maggiori informazioni sull'ereditarietà e sugli utenti in una struttura organizzativa, consulta il Centro assistenza per l'amministrazione.
  • Un'unità organizzativa può essere spostata in alto o in basso in una struttura gerarchica. Inoltre, gli utenti associati all'organizzazione possono essere spostati singolarmente o in batch quando si compila una nuova organizzazione o un sottoinsieme di utenti da un'unità organizzativa a un'altra.
  • I dati conservati nelle proprietà delle unità organizzative possono cambiare continuamente. Quando effettui una richiesta, viene garantito che le proprietà restituite per un'entità siano coerenti al momento del recupero dell'entità.Ciò significa che non vedrai aggiornamenti "parziali". Se un'operazione di recupero restituisce più di un'entità, non vi è alcuna garanzia di coerenza tra le entità.Ciò è particolarmente vero quando una risposta si estende su più pagine nell'impaginazione.

Creare un'unità organizzativa

Per creare un'unità organizzativa, utilizza la seguente richiesta POST e includi l'autorizzazione descritta in Autorizzare le richieste.

Se sei un amministratore e stai creando un'unità organizzativa, utilizza my_customer.

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

Se sei un rivenditore che crea un'unità organizzativa per un suo cliente, utilizza customerId. Per recuperare customerId, utilizza l'operazione Recupera un utente.

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

Per comprendere la struttura organizzativa del tuo account, consulta il Centro assistenza per amministratori. Per le proprietà di richiesta e risposta, consulta la documentazione di riferimento API.

Richiesta JSON

Il seguente esempio di rivenditore JSON mostra un corpo della richiesta di esempio che crea l'unità organizzativa sales_support. I name e le parentOrgUnitPath sono obbligatori: 

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

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

Risposta JSON

Una risposta corretta restituisce un codice di stato HTTP 201. Insieme al codice di stato, la risposta restituisce le proprietà per il nuovo gruppo: 

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

Aggiorna un'unità organizzativa

Per aggiornare un'unità organizzativa, utilizza la seguente richiesta PUT e includi l'autorizzazione descritta in Autorizzare le richieste. Per le proprietà richiesta e risposta, consulta la documentazione di riferimento API:

Se sei un amministratore che aggiorna un'unità organizzativa, utilizza my_customer.

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

Se sei un rivenditore che aggiorna l'unità organizzativa per un suo cliente, utilizza customerId. Per ottenere customerId, utilizza l'operazione Recupera un utente.

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

Richiesta JSON

Nell'esempio riportato di seguito, la descrizione dell'unità organizzativa è stata aggiornata: 

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

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

Note per una richiesta di aggiornamento:

  • Devi solo inviare le informazioni aggiornate nella richiesta. Non è necessario inserire tutte le proprietà del gruppo nella richiesta.
  • Se un utente non è stato assegnato a un'unità organizzativa specifica al momento della creazione dell'account utente, l'account si trova nell'unità organizzativa di primo livello.
  • Puoi spostare un'unità organizzativa in un'altra parte della struttura organizzativa del tuo account impostando la proprietà parentOrgUnitPath nella richiesta. È importante notare che lo spostamento di un'unità organizzativa può comportare la modifica dei servizi e delle impostazioni per gli utenti dell'unità organizzativa da spostare.

Risposta JSON

Una risposta corretta restituisce un codice di stato HTTP 201. Insieme al codice di stato, la risposta restituisce le proprietà per l'unità organizzativa aggiornata. 

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

Se un utente non è stato assegnato a un'unità organizzativa specifica al momento della creazione dell'account utente, l'account si trova nell'unità organizzativa di primo livello. L'unità organizzativa di un utente determina a quali servizi di Google Workspace ha accesso l'utente. Se l'utente viene spostato in una nuova organizzazione, l'accesso dell'utente cambia. Per ulteriori informazioni sulle strutture organizzative, consulta il Centro assistenza per l'amministrazione. Per saperne di più su come spostare un utente in un'altra organizzazione, vedi Aggiornare un utente.

Recupera un'unità organizzativa

Per recuperare un'unità organizzativa, usa la seguente richiesta GET e includi l'autorizzazione descritta in Autorizzare le richieste. La stringa di query orgUnitPath è il percorso completo per questa unità organizzativa. Per le proprietà richiesta e risposta, consulta la documentazione di riferimento API:

Se sei un amministratore che recupera un'unità organizzativa, utilizza my_customer.

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

Se sei un rivenditore e vuoi recuperare un'unità organizzativa per un suo cliente, utilizza customerId. Per ottenere customerId, utilizza l'operazione Recupera un utente.

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

Risposta JSON

Nell'esempio seguente, viene recuperata l'unità organizzativa "Vendite a contatto con il pubblico". Prendi nota della codifica HTTP "frontline+sales" nell'URI della richiesta: 

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

Una risposta corretta restituisce un codice di stato HTTP 200. Insieme al codice di stato, la risposta restituisce le impostazioni dell'unità organizzativa: 

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

Recupera le unità organizzative

Per recuperare tutte le unità organizzative secondarie di un'unità organizzativa, le unità organizzative secondarie immediate o tutte le unità organizzative secondarie più l'unità organizzativa specificata, utilizza la seguente richiesta GET e includi l'autorizzazione descritta in Autorizzazione delle richieste. Per le proprietà di richiesta e risposta, consulta la documentazione di riferimento API.

Se sei un amministratore dell'account e recupera tutte le unità organizzative secondarie, utilizza my_customer. Per la leggibilità, in questo esempio vengono utilizzati i ritorni a riga: 

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

Se sei un rivenditore che recupera le unità organizzative per un suo cliente, utilizza customerId. Per ottenere customerId, utilizza l'operazione Recupera un utente: 

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

La stringa di query get restituisce all unità organizzative secondarie in orgUnitPath, l'children immediata di orgUnitPath o tutte le unità organizzative secondarie e il orgUnitPath specificato per all_including_parent. Il valore predefinito è type=children.

Risposta JSON

Ad esempio, questa richiesta restituisce tutte le unità organizzative a partire dall'unità organizzativa /corp: 

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

Una risposta corretta restituisce un codice di stato HTTP 200. Insieme al codice di stato, la risposta restituisce le unità organizzative dell'account: 

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

Eliminare un'unità organizzativa

Per eliminare un'unità organizzativa, utilizza la seguente richiesta DELETE e includi l'autorizzazione descritta in Autorizzare le richieste. Per recuperare customerId, utilizza l'operazione Recupera un utente. Per le proprietà richiesta e risposta, consulta la documentazione di riferimento API:

Se sei un amministratore dell'account e stai eliminando un'unità organizzativa, utilizza my_customer. 

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

Se sei un rivenditore e stai eliminando un'unità organizzativa per un suo cliente, utilizza l'customerId. Per ottenere customerId, utilizza l'operazione Recupera un utente. 

DELETE https://admin.googleapis.com/admin/directory/v1/customer/customerId/orgunits/orgUnitPath
Ad esempio, la richiesta DELETE di questo amministratore rivenditore elimina l'unità organizzativa "backend_tests": 
DELETE https://admin.googleapis.com/admin/directory/v1/customer/C03az79cb/orgunits/corp/sales/backend_tests

Una risposta corretta restituisce un codice di stato HTTP 200.

Puoi eliminare solo le unità organizzative a cui non sono state assegnate unità organizzative secondarie o a cui non sono stati assegnati utenti. Prima dell'eliminazione, devi riassegnare gli utenti ad altre unità organizzative e rimuovere le eventuali unità organizzative secondarie.