API Directory: Unità organizzative

Gestire le unità organizzative

La struttura dell'organizzazione di un account Google Workspace è composta da unità organizzative che ti consentono di gestire gli utenti in una struttura logica e gerarchica. Questa funzionalità è simile a quella disponibile nella scheda "Organizzazioni e utenti" della Console di amministrazione Google. La gerarchia delle unità organizzative del cliente è limitata a 35 livelli di profondità. Per ulteriori informazioni, consulta il Centro assistenza Amministratore.

  • A un account Google Workspace è associato un solo albero dell'organizzazione. Quando questo account viene configurato inizialmente, ha un'unità organizzativa a livello di account. L'organizzazione associata al dominio principale. Per ulteriori informazioni sul dominio principale, consulta le informazioni sui limiti dell'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 tra le unità organizzative di pari livello. Inoltre, il nome di un'unità organizzativa non è sensibile alle maiuscole.
  • Un'unità organizzativa eredita i criteri dalla gerarchia organizzativa. Qualsiasi unità organizzativa può bloccare questa catena di ereditarietà principale sostituendo il criterio ereditato. La precedenza di una policy rispetto a un'altra è determinata dall'unità organizzativa più vicina. Ciò significa che i criteri di un'unità organizzativa di livello inferiore possono avere la precedenza sui criteri delle unità organizzative principali di livello superiore. Per saperne di più sull'ereditarietà e sugli utenti in una struttura organizzativa, consulta il Centro assistenza per l'amministrazione.
  • Un'unità organizzativa può essere spostata verso l'alto o verso il basso in una struttura gerarchica. Inoltre, gli utenti associati all'organizzazione possono essere spostati singolarmente o in batch quando viene compilata una nuova organizzazione o quando viene spostato 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, le proprietà restituite per un'entità sono garantite per essere 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 è garantita la coerenza tra le entità.Ciò è particolarmente vero quando una risposta si estende su più pagine nella paginazione.

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 che crea 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 cliente rivenduto, 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 gli amministratori. Per le proprietà della richiesta e della risposta, consulta il riferimento API.

Richiesta JSON

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

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

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

Risposta JSON

Una risposta riuscita restituisce un codice di stato HTTP 201. Oltre al codice di stato, la risposta restituisce le proprietà del nuovo gruppo: 

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

Aggiornare 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à della richiesta e della risposta, consulta il 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 un'unità organizzativa per un cliente rivenduto, 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 seguente, 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 tua richiesta. Non è necessario inserire tutte le proprietà del gruppo nella richiesta.
  • Se a un utente non è stata assegnata 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ò modificare i servizi e le impostazioni per gli utenti dell'unità organizzativa spostata.

Risposta JSON

Una risposta riuscita restituisce un codice di stato HTTP 201. Oltre al codice di stato, la risposta restituisce le proprietà dell'unità organizzativa aggiornata. 

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

Se a un utente non è stata assegnata 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 Google Workspace ha accesso. Se l'utente viene spostato in una nuova organizzazione, il suo accesso cambia. Per saperne di più sulle strutture organizzative, consulta il Centro assistenza per l'amministrazione. Per saperne di più sullo spostamento di un utente in un'altra organizzazione, vedi Aggiornare un utente.

Recuperare un'unità organizzativa

Per recuperare un'unità organizzativa, utilizza la seguente richiesta GET e includi l'autorizzazione descritta nell'articolo Autorizzare le richieste. La stringa di query orgUnitPath è il percorso completo per questa unità organizzativa. Per le proprietà della richiesta e della risposta, consulta il 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 che recupera un'unità organizzativa per un cliente rivenduto, 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 riportato di seguito, viene recuperata l'unità organizzativa "Vendite di prima linea". 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 riuscita restituisce un codice di stato HTTP 200. Oltre 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"
}

Recuperare unità organizzative

Per recuperare tutte le unità organizzative secondarie di un'unità organizzativa, i figli immediati di un'unità organizzativa o tutte le unità organizzative secondarie più l'unità organizzativa specificata, utilizza la seguente richiesta GET e includi l'autorizzazione descritta in Autorizzare le richieste. Per le proprietà della richiesta e della risposta, consulta il Riferimento API.

Se sei un amministratore account che recupera tutte le unità organizzative secondarie, utilizza my_customer. Per favorire la leggibilità, in questo esempio sono stati inseriti dei ritorni a capo. 

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 cliente rivenduto, 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 le unità organizzative secondarie in orgUnitPath, le children immediate di orgUnitPath o tutte le unità organizzative secondarie e l'orgUnitPath specificata per all_including_parent.all 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 riuscita restituisce un codice di stato HTTP 200. Oltre 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"
     },
     {
    "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"
     }
  ]
  }

Eliminare un'unità organizzativa

Per eliminare un'unità organizzativa, utilizza la seguente richiesta DELETE e includi l'autorizzazione descritta nell'articolo Autorizzare le richieste. Per recuperare customerId, utilizza l'operazione Recupera un utente. Per le proprietà della richiesta e della risposta, consulta il Riferimento API:

Se sei un amministratore dell'account che elimina un'unità organizzativa, utilizza my_customer. 

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

Se sei un rivenditore che elimina un'unità organizzativa per un cliente rivenduto, utilizza 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 riuscita restituisce un codice di stato HTTP 200.

Puoi eliminare solo le unità organizzative che non hanno unità organizzative secondarie o utenti assegnati. Prima di eliminare l'unità organizzativa, devi riassegnare gli utenti ad altre unità organizzative e rimuovere le unità organizzative secondarie.