API Directory: unità organizzative

Gestisci le unità organizzative

La struttura organizzativa 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 indicata nella sezione "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.

  • Esiste una sola struttura organizzativa per un account Google Workspace. Quando questo account viene configurato inizialmente, ha un'unità organizzativa a livello di account. Questa è l'organizzazione associata al dominio principale. Per ulteriori informazioni sul dominio principale, consulta le informazioni sui limiti API.
  • Il nome di 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 fa distinzione tra maiuscole e minuscole.
  • Un'unità organizzativa eredita i criteri dalla gerarchia dell'organizzazione. Qualsiasi organizzazione può bloccare questa catena di ereditarietà parentale eseguendo l'override del criterio ereditato. La la precedenza di un criterio su 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 di unità principali di livello superiore. L'impostazione blockInheritance consente di bloccare l'ereditarietà delle impostazioni per di un'unità organizzativa e della sua organizzazione secondaria. L'API blockInheritance è deprecata. L'impostazione su "true" non è più supportata e può avere conseguenze indesiderate. Per Per ulteriori informazioni sull'ereditarietà e sugli utenti in una struttura organizzativa, consulta le Centro assistenza per gli amministratori.
  • 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 completa una nuova organizzazione o si sposta un sottoinsieme di utenti da un'unità organizzativa a un'altra.
  • I dati conservati nelle proprietà delle unità organizzative possono variare di continuo. 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 il valore "parziale" aggiornamenti. 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 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 e stai creando un'unità organizzativa per un cliente del rivenditore, 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 pagina Riferimento API.

Richiesta JSON

L'esempio di rivenditore JSON seguente mostra un corpo della richiesta di esempio che crea l'unità organizzativa vendite_support. I campi 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 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
  }

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à di richiesta e risposta, consulta i riferimenti 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 del rivenditore, 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 inviare solo i dati aggiornati nella tua richiesta. Non è necessario inserire nella richiesta tutte le proprietà del gruppo.
  • 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 spostata.

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, il suo accesso cambia. Per ulteriori informazioni sulle strutture organizzative, consulta il Centro assistenza per l'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 in Autorizzare le richieste. La stringa di query orgUnitPath è il percorso completo per 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 del rivenditore, 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, il campo "vendite front-line" Unità organizzativa recuperata. Tieni presente che "frontline+sales" Codifica HTTP 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, quelle 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 in Autorizzare le richieste. Per le proprietà di richiesta e risposta, consulta la documentazione di riferimento API.

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

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 unità organizzative per un cliente del rivenditore, 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, children immediato di orgUnitPath o tutte le unità organizzative secondarie e 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. 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à di richiesta e risposta, consulta i riferimenti 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 del rivenditore, 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 di rivenditore elimina il "backend_tests" unità organizzativa: 
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 utenti associati. Prima di procedere con l'eliminazione, devi riassegnare gli utenti ad altre unità organizzative e rimuovere eventuali unità organizzative secondarie.