API Directory: unités organisationnelles

Gérer les unités organisationnelles

L'arborescence d'un compte Google Workspace se compose d'unités organisationnelles qui vous permettent de gérer vos utilisateurs dans une structure logique et hiérarchique. Cette fonctionnalité est semblable à celle de l'onglet "Organisations et utilisateurs" de la console d'administration Google. La hiérarchie des unités organisationnelles du client est limitée à 35 niveaux de profondeur. Pour en savoir plus, consultez le Centre d'aide pour les administrateurs.

  • Un compte Google Workspace ne peut être associé qu'à un seul arbre d'organisation. Lors de la configuration initiale de ce compte, une unité organisationnelle est associée au niveau du compte. Il s'agit de l'organisation associée au domaine principal. Pour en savoir plus sur le domaine principal, consultez les informations sur les limites de l'API.
  • Le chemin d'accès d'une unité organisationnelle est unique. Le nom de l'unité organisationnelle n'est pas forcément unique dans la hiérarchie de l'organisation, mais il l'est parmi les unités organisationnelles sœurs. Le nom d'une unité organisationnelle n'est pas sensible à la casse.
  • Une unité organisationnelle hérite des règles de la hiérarchie organisationnelle. Toute unité organisationnelle peut bloquer cette chaîne d'héritage parental en remplaçant la règle héritée. La priorité d'une règle par rapport à une autre est déterminée par l'unité organisationnelle la plus proche. Cela signifie que les règles d'une unité organisationnelle de niveau inférieur peuvent prévaloir sur celles des unités parentales de niveau supérieur. Pour en savoir plus sur l'héritage et les utilisateurs dans une structure organisationnelle, consultez le Centre d'aide pour les administrateurs.
  • Une unité organisationnelle peut être déplacée vers le haut ou vers le bas dans une arborescence hiérarchique. De plus, les utilisateurs associés à l'organisation peuvent être déplacés individuellement ou par lot lors de la création d'une organisation ou du déplacement d'un sous-ensemble d'utilisateurs d'une unité organisationnelle vers une autre.
  • Les données conservées dans les propriétés des unités organisationnelles peuvent changer constamment. Lorsque vous effectuez une requête, les propriétés renvoyées pour une entité sont garanties d'être cohérentes au moment où l'entité a été récupérée.En d'autres termes, vous ne verrez pas de mises à jour "partielles". Si une opération de récupération renvoie plusieurs entités, aucune cohérence n'est garantie entre les entités.Cela est particulièrement vrai lorsqu'une réponse s'étend sur plusieurs pages dans la pagination.

Créer une unité organisationnelle

Pour créer une unité organisationnelle, utilisez la requête POST suivante et incluez l'autorisation décrite dans Autoriser les requêtes.

Si vous êtes un administrateur et que vous créez une unité organisationnelle, utilisez my_customer.

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

Si vous êtes un revendeur et que vous créez une unité organisationnelle pour un client revendu, utilisez customerId. Pour récupérer le customerId, utilisez l'opération Récupérer un utilisateur.

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

Pour comprendre la structure de votre compte, consultez le Centre d'aide pour les administrateurs. Pour en savoir plus sur les propriétés de requête et de réponse, consultez la documentation de référence de l'API.

Requête JSON

L'exemple JSON de revendeur suivant montre un exemple de corps de requête qui crée l'unité organisationnelle sales_support. Les champs name et parentOrgUnitPath sont obligatoires : 

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

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

Réponse JSON

Une réponse réussie renvoie un code d'état HTTP 201. En plus du code d'état, la réponse renvoie les propriétés du nouveau groupe : 

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

Modifier une unité organisationnelle

Pour mettre à jour une unité organisationnelle, utilisez la requête PUT suivante et incluez l'autorisation décrite dans Autoriser les requêtes. Pour en savoir plus sur les propriétés de requête et de réponse, consultez la documentation de référence de l'API :

Si vous êtes administrateur et que vous mettez à jour une unité organisationnelle, utilisez my_customer.

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

Si vous êtes un revendeur et que vous mettez à jour une unité organisationnelle pour un client revendu, utilisez customerId. Pour obtenir le customerId, utilisez l'opération Récupérer un utilisateur.

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

Requête JSON

Dans l'exemple ci-dessous, la description de l'unité organisationnelle a été modifiée : 

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

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

Remarques concernant une demande de mise à jour :

  • Il vous suffit de fournir les informations mises à jour dans votre demande. Vous n'avez pas besoin de saisir toutes les propriétés du groupe dans la requête.
  • Si un utilisateur n'a pas été attribué à une unité organisationnelle spécifique lors de la création de son compte, celui-ci se trouve dans l'unité organisationnelle racine.
  • Vous pouvez déplacer une unité organisationnelle vers une autre partie de la structure de votre compte en définissant la propriété parentOrgUnitPath dans la requête. Il est important de noter que le déplacement d'une unité organisationnelle peut modifier les services et les paramètres des utilisateurs de l'unité organisationnelle déplacée.

Réponse JSON

Une réponse réussie renvoie un code d'état HTTP 201. En plus du code d'état, la réponse renvoie les propriétés de l'unité organisationnelle mise à jour. 

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

Si un utilisateur n'a pas été attribué à une unité organisationnelle spécifique lors de la création de son compte, celui-ci se trouve dans l'unité organisationnelle racine. L'unité organisationnelle d'un utilisateur détermine les services Google Workspace auxquels il a accès. Si l'utilisateur est déplacé vers une autre organisation, son accès change. Pour en savoir plus sur les structures organisationnelles, consultez le Centre d'aide pour les administrateurs. Pour savoir comment déplacer un utilisateur vers une autre organisation, consultez Mettre à jour un utilisateur.

Récupérer une unité organisationnelle

Pour récupérer une unité organisationnelle, utilisez la requête GET suivante et incluez l'autorisation décrite dans Autoriser les requêtes. La chaîne de requête orgUnitPath correspond au chemin d'accès complet de cette unité organisationnelle. Pour en savoir plus sur les propriétés de requête et de réponse, consultez la documentation de référence de l'API :

Si vous êtes administrateur et que vous récupérez une unité organisationnelle, utilisez my_customer.

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

Si vous êtes un revendeur et que vous récupérez une unité organisationnelle pour un client revendu, utilisez customerId. Pour obtenir le customerId, utilisez l'opération Récupérer un utilisateur.

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

Réponse JSON

Dans l'exemple ci-dessous, l'unité organisationnelle "frontline sales" (ventes en première ligne) est récupérée. Notez l'encodage HTTP "frontline+sales" dans l'URI de la requête : 

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

Une réponse réussie renvoie un code d'état HTTP 200. En plus du code d'état, la réponse renvoie les paramètres de l'unité organisationnelle : 

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

Récupérer des unités organisationnelles

Pour récupérer toutes les sous-unités organisationnelles d'une unité organisationnelle, les enfants immédiats d'une unité organisationnelle ou toutes les sous-unités organisationnelles plus l'unité organisationnelle spécifiée, utilisez la requête GET suivante et incluez l'autorisation décrite dans Autoriser les requêtes. Pour en savoir plus sur les propriétés de requête et de réponse, consultez la documentation de référence de l'API.

Si vous êtes administrateur de compte et que vous récupérez toutes les sous-unités organisationnelles, utilisez my_customer. Des retours à la ligne ont été inclus dans cet exemple pour le rendre plus lisible. 

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

Si vous êtes un revendeur et que vous récupérez des unités organisationnelles pour un client revendu, utilisez customerId. Pour obtenir le customerId, utilisez l'opération Récupérer un utilisateur : 

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 chaîne de requête get renvoie les sous-unités organisationnelles sous orgUnitPath, les children immédiats de orgUnitPath ou toutes les sous-unités organisationnelles et le orgUnitPath spécifié pour all_including_parent.all La valeur par défaut est type=children.

Réponse JSON

Par exemple, cette requête renvoie toutes les unités organisationnelles à partir de l'unité organisationnelle /corp : 

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

Une réponse réussie renvoie un code d'état HTTP 200. En plus du code d'état, la réponse renvoie les unités organisationnelles du compte : 

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

Supprimer une unité organisationnelle

Pour supprimer une unité organisationnelle, utilisez la requête DELETE suivante et incluez l'autorisation décrite dans Autoriser les requêtes. Pour récupérer le customerId, utilisez l'opération Récupérer un utilisateur. Pour en savoir plus sur les propriétés de requête et de réponse, consultez la documentation de référence de l'API :

Si vous êtes administrateur de compte et que vous supprimez une unité organisationnelle, utilisez my_customer. 

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

Si vous êtes un revendeur et que vous supprimez une unité organisationnelle pour un client revendu, utilisez customerId. Pour obtenir le customerId, utilisez l'opération Récupérer un utilisateur. 

DELETE https://admin.googleapis.com/admin/directory/v1/customer/customerId/orgunits/orgUnitPath
 Par exemple, la requête DELETE de cet administrateur revendeur supprime l'unité organisationnelle "backend_tests" : 
DELETE https://admin.googleapis.com/admin/directory/v1/customer/C03az79cb/orgunits/corp/sales/backend_tests

Une réponse réussie renvoie un code d'état HTTP 200.

Vous ne pouvez supprimer que les unités organisationnelles qui ne comportent aucune unité organisationnelle enfant ni aucun utilisateur. Avant de supprimer une unité organisationnelle, vous devez réattribuer ses utilisateurs à d'autres unités organisationnelles et supprimer ses unités organisationnelles enfants.