Questa pagina è stata tradotta dall'API Cloud Translation.

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. Si tratta di una funzionalità simile a quella disponibile nella scheda "Organizzazioni e utenti" della Console di amministrazione. La gerarchia delle unità organizzative del cliente è limitata a 35 livelli di profondità. Per ulteriori informazioni, visita il Centro assistenza per amministratori.

Un account Google Workspace ha un solo albero dell'organizzazione. Quando questo account viene configurato inizialmente, ha un'unità organizzativa a livello di account. Si tratta dell'organizzazione associata al dominio principale. Per ulteriori informazioni 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 deve essere univoco tra le unità organizzative sorelle. Inoltre, il nome di un'unità organizzativa non è sensibile alle maiuscole.
Un'unità organizzativa eredita i criteri dalla gerarchia dell'organizzazione. Qualsiasi unità organizzativa può bloccare questa catena di ereditarietà principale 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 sui criteri delle unità organizzative principali di livello superiore. Per ulteriori informazioni sull'ereditarietà e sugli utenti nella struttura di un'organizzazione, visita il Centro assistenza per l'amministrazione.
Un'unità organizzativa può essere spostata verso l'alto o verso il basso in una struttura ad albero gerarchica. Inoltre, gli utenti associati dell'organizzazione possono essere spostati singolarmente o in blocco quando viene compilata una nuova organizzazione o viene spostato un sottoinsieme di utenti da un'unità organizzativa all'altra.
I dati conservati nelle proprietà dell'unità organizzativa possono cambiare continuamente. Quando effettui una richiesta, le proprietà restituite per un'entità sono garantite come coerenti al momento del recupero dell'entità.In altre parole, non vedrai aggiornamenti "parziali". Se un'operazione di recupero restituisce più di un'entità, non esiste 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 nell'articolo 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 di rivendita, 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, visita il Centro assistenza per gli amministratori. Per le proprietà di richiesta e 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. name e 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",
}

Risposta JSON

Una risposta riuscita 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"
  }

Aggiornare un'unità organizzativa

Per aggiornare un'unità organizzativa, utilizza la seguente richiesta PUT e includi l'autorizzazione descritta nell'articolo relativo all'autorizzazione delle richieste. Per le proprietà di richiesta e 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 di cui hai rivenduto i prodotti, utilizza customerId. Per ottenere customerId, utilizza l'operazione Recupero di 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 inviare solo i dati aggiornati nella tua 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 tenere presente che lo spostamento di un'unità organizzativa può comportare la modifica dei servizi e delle impostazioni per gli utenti dell'unità organizzativa spostata.

Risposta JSON

Una risposta riuscita 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"
}

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 i servizi Google Workspace a cui ha accesso. Se l'utente viene spostato in una nuova organizzazione, il suo accesso cambia. Per ulteriori informazioni sulle strutture dell'organizzazione, visita il Centro assistenza amministrazione. Per ulteriori informazioni 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 relativo all'autorizzazione delle richieste. La stringa di query orgUnitPath è il percorso completo di questa unità organizzativa. Per le proprietà di richiesta e risposta, consulta i riferimenti 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 Recupero di 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 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 le unità organizzative

Per recuperare tutte le unità organizzative secondarie di un'unità organizzativa, le unità organizzative secondarie immediate 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 nell'articolo Autorizzare le richieste. Per le proprietà di richiesta e risposta, consulta il riferimento API.

Se sei un amministratore dell'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 di cui hai rivenduto i prodotti, utilizza customerId. Per ottenere customerId, utilizza l'operazione Recupero di 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 all sotto orgUnitPath, il children immediato 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 che iniziano 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. 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 relativo all'autorizzazione delle richieste. Per recuperare il valore customerId, utilizza l'operazione Recupero di un utente. Per le proprietà di richiesta e 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 di rivendita, utilizza customerId. Per ottenere customerId, utilizza l'operazione Recupero di un utente.

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

Ad esempio, la richiesta DELETE di questo amministratore del 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 a cui non sono assegnate unità organizzative secondarie o utenti. Prima di procedere con l'eliminazione, devi riassegnare gli utenti ad altre unità organizzative e rimuovere eventuali unità organizzative secondarie.