API Directory: unità organizzative

Gestisci unità organizzative

Un albero dell'account Google Workspace è composto da unità organizzative che consentono di gestire gli utenti in una struttura logica e gerarchica. Questa funzionalità è simile a quella che si trova 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.

  • Per ogni account Google Workspace esiste una sola struttura organizzativa. Inizialmente, quando questo account è configurato, 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 nome del percorso di un'unità organizzativa è univoco. Il nome dell'unità organizzativa potrebbe non essere univoco all'interno della gerarchia dell'organizzazione, ma il suo nome è univoco tra quello dell'unità organizzativa affiliata. 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à dei genitori. La precedenza di un criterio rispetto all'altro è determinata dall'unità organizzativa più vicina. Il significato dei criteri di un'unità organizzativa inferiore può avere la precedenza sui criteri delle unità principali di livello superiore.
  • Un'unità organizzativa può essere spostata verso l'alto o verso il basso in una struttura gerarchica ad albero. Gli utenti associati all'organizzazione possono essere spostati singolarmente o in gruppo durante la compilazione di una nuova organizzazione o lo spostamento di un sottoinsieme di utenti da un'unità organizzativa a un'altra.
  • I dati conservati nelle proprietà delle unità organizzative possono cambiare continuamente. Quando si effettua 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 esiste alcuna garanzia di coerenza tra le entità.Ciò è particolarmente vero quando una risposta interessa più pagine di 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 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 del rivenditore, utilizza customerId. Per recuperare l'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 amministratori. Per le proprietà richiesta e risposta, consulta la documentazione di riferimento per l'API.

Richiesta JSON

L'esempio di rivenditore JSON seguente 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",
    "blockInheritance": false
}

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

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à richiesta e risposta, consulta la documentazione di riferimento dell'API:

Se sei un amministratore e aggiorni 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 del rivenditore, utilizza customerId. Per ottenere l'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 alla creazione dell'account utente non era stato assegnato alcun utente a un'unità organizzativa specifica, l'account appartiene all'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ò cambiare i servizi e le impostazioni per gli utenti di quella unità organizzativa.

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

Se alla creazione dell'account utente non era stato assegnato alcun utente a un'unità organizzativa specifica, l'account appartiene all'unità organizzativa di primo livello. L'unità organizzativa di un utente determina a quali servizi di Google Workspace ha accesso. Se l'utente viene spostato in una nuova organizzazione, l'accesso dell'utente cambia. Per ulteriori informazioni sulle strutture organizzative, visita 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 in Autorizzare le richieste. La stringa di query orgUnitPath è il percorso completo dell'unità organizzativa. Per le proprietà richiesta e risposta, consulta la documentazione di riferimento dell'API:

Se sei un amministratore e 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 recupera un'unità organizzativa per un cliente del rivenditore, utilizza la customerId. Per ottenere l'customerId, utilizza l'operazione Recupera un utente.

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

Risposta JSON

Nell'esempio seguente, l'unità organizzativa 'frontline sales' viene recuperata. Nota la codifica HTTP 'frontline+sales' nella richiesta's:

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. 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 tutte le unità organizzative secondarie o secondarie

Per recuperare tutte le unità organizzative secondarie di un'unità organizzativa o per recuperare le unità secondarie secondarie immediate di un'unità organizzativa, utilizza la richiesta GET seguente e includi l'autorizzazione descritta in Autorizzare le richieste. Per le proprietà della richiesta e della risposta, consulta la documentazione di riferimento dell'API.

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

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

Se sei un rivenditore e recupera unità organizzative per un cliente del rivenditore, utilizza la customerId. Per richiedere l'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

La stringa di query get restituisce all unità organizzative secondarie all'interno di orgUnitPath oppure restituisce immediatamente children di orgUnitPath. 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 riuscita 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 l'customerId, utilizza l'operazione Recupera un utente. Per le proprietà richiesta e risposta, consulta la documentazione di riferimento dell'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 e elimini un'unità organizzativa per un cliente del rivenditore, utilizza la customerId. Per ottenere l'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 del rivenditore elimina l'unità organizzativa 'backend_tests&#39:
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 unità organizzative che non dispongono di unità organizzative secondarie o utenti a loro assegnati. Prima di procedere all'eliminazione, devi riassegnare gli utenti ad altre unità organizzative e rimuovere le eventuali unità organizzative secondarie.