Gérer les groupes

Cette page explique comment gérer les groupes Google avec l'API Directory :

  • Créer un groupe
  • Modifier un groupe
  • Ajouter un alias de groupe
  • Récupérer un groupe
  • Récupérer tous les groupes d'un domaine ou du compte
  • Récupérer tous les groupes d'un membre
  • Récupérer tous les alias de groupe
  • Supprimer un alias de groupe
  • Supprimer un groupe

Créer un groupe

Pour créer un groupe, utilisez la requête POST suivante et incluez l'autorisation décrite dans Autoriser les requêtes. Vous pouvez créer un groupe pour n'importe quel domaine associé au compte. Pour en savoir plus sur les chaînes de requête, la requête et les propriétés de réponse, consultez la méthode groups.insert. 

POST https://admin.googleapis.com/admin/directory/v1/groups

La requête JSON suivante montre un exemple de corps de requête qui crée un groupe. L'adresse e-mail du groupe est sales_group@example.com : 

{
   "email": "sales_group@example.com",
   "name": "Sales Group",
   "description": "This is the Sales group."
}

Une réponse positive renvoie un code d'état HTTP 201 et les propriétés du nouveau groupe.

Modifier un groupe

Pour mettre à jour les paramètres d'un groupe, utilisez la requête PUT suivante et incluez l'autorisation décrite dans Autoriser les requêtes. groupKey correspond à l'adresse e-mail du groupe, à l'une des adresses e-mail de l'alias du groupe ou à l'id unique du groupe. Pour en savoir plus sur les chaînes de requête, la requête et les propriétés de réponse, consultez la méthode groups.update.

PUT https://admin.googleapis.com/admin/directory/v1/groups/groupKey

En général, nous vous déconseillons d'utiliser l'adresse e-mail du groupe comme clé pour les données persistantes, car elle est susceptible de changer.

En général, nous vous déconseillons d'utiliser l'adresse e-mail du groupe comme clé pour les données persistantes, car elle est susceptible de changer.

Dans l'exemple suivant, l'groupKey unique est nnn et le nom du groupe est "APAC Sales Group" : 

PUT https://admin.googleapis.com/admin/directory/v1/groups/nnn

{
    "email": "sales_group@example.com",
    "name": "APAC Sales Group"
}

Pour une demande de modification, il vous suffit d'envoyer les informations modifiées dans votre demande. Vous n'avez pas besoin de saisir toutes les propriétés du groupe dans la requête.

Une réponse réussie renvoie un code d'état HTTP 201 et les propriétés du nouveau groupe : 

{
    "kind": "directory#groups",
    "id": "group's unique ID",
    "etag": "group's unique ETag",
    "email": "sales_group@example.com",
    "name": "APAC Sales Group",
    "directMembersCount": "5",
    "description": "This is the APAC sales group.",
    "adminCreated": true,
    "aliases": [
     {
        "alias": "best_sales_group@example.com"
     }
    ],
    "nonEditableAliases": [
     {
        "alias": "liz@test.com"
     }
    ]
}

Ajouter un alias de groupe

Pour ajouter un alias de groupe, utilisez la requête POST suivante et incluez l'autorisation décrite dans Autoriser les requêtes. groupKey correspond à l'adresse e-mail du groupe, à l'une des adresses e-mail de l'alias du groupe ou à l'id unique du groupe. Pour en savoir plus sur les chaînes de requête, la requête et les propriétés de réponse, consultez la ressource groups.

POST https://admin.googleapis.com/admin/directory/v1/groups/groupKey/aliases

En général, Google recommande de ne pas utiliser l'adresse e-mail du groupe comme clé pour les données persistantes, car elle est susceptible de changer.

La requête JSON suivante montre un exemple de requête permettant de créer un alias de groupe. groupKey est le id unique du groupe représenté par NNNN.

POST https://admin.googleapis.com/admin/directory/v1/groups/NNNN/aliases

{
    "alias": "best_sales_group@example.com"
}

Une réponse réussie renvoie un code d'état HTTP 201 et les propriétés du nouvel alias de groupe.

Récupérer un groupe

Pour récupérer un groupe, utilisez la requête GET suivante et incluez l'autorisation décrite dans Autoriser les requêtes. groupKey correspond à l'adresse e-mail du groupe, à l'une des adresses e-mail de l'alias du groupe ou à l'id unique du groupe. Pour en savoir plus sur les chaînes de requête, la requête et les propriétés de réponse, consultez la méthode groups.get. 

GET https://admin.googleapis.com/admin/directory/v1/groups/groupKey

En général, Google recommande de ne pas utiliser l'adresse e-mail du groupe comme clé pour les données persistantes, car elle est susceptible de changer.

Dans l'exemple suivant, l'ID unique groupKey est nnnn : 

GET https://admin.googleapis.com/admin/directory/v1/groups/nnnn

Une réponse réussie renvoie un code d'état HTTP 200 et les paramètres du groupe : 

{
    "kind": "directory#groups",
    "id": "group's unique ID",
    "etag": "group's unique ETag",
    "email": "sales_group@example.com",
    "name": "APAC Sales Group",
    "directMembersCount": "5",
    "description": "This is the APAC sales group.",
    "adminCreated": true,
    "aliases": [
     {
        "alias": "best_sales_group@example.com"
     }
    ],
    "nonEditableAliases": [
     {
        "alias": "liz@test.com"
     }
    ]
}

Récupérer tous les groupes d'un domaine ou du compte

Pour récupérer tous les groupes d'un domaine ou d'un compte spécifique, utilisez la requête GET suivante et incluez l'autorisation décrite dans Autoriser les requêtes. Pour en savoir plus sur les chaînes de requête, la requête et les propriétés de réponse, consultez la méthode groups.list. Des retours à la ligne ont été inclus dans cet exemple pour le rendre plus lisible. 

GET https://admin.googleapis.com/admin/directory/v1/groups?domain=domain name
&customer=my_customer or customerId&pageToken=pagination token
&maxResults=max results

Lorsque vous récupérez tous les groupes d'un domaine ou d'un compte, tenez compte des points suivants :

  • Tous les groupes d'un sous-domaine : utilisez l'argument domain avec le nom du domaine.
  • Tous les groupes du compte : utilisez l'argument customer avec my_customer ou la valeur customerId du compte. En tant qu'administrateur de compte, utilisez la chaîne my_customer pour représenter le customerId de votre compte. Si vous êtes un revendeur et que vous accédez au compte d'un client indirect, utilisez l'customerId du compte indirect. Pour la valeur customerId, utilisez le nom de domaine principal du compte dans la requête de l'opération Récupérer tous les utilisateurs d'un domaine. La réponse obtenue a la valeur customerId.
  • Utilisation des arguments domain et customer : l'API Directory renvoie tous les groupes pour domain.
  • Sans utiliser les arguments domain et customer : l'API Directory renvoie tous les groupes du compte associé à my_customer. Il s'agit du compte customerId de l'administrateur qui effectue la demande.
  • Utilisation des arguments customer et userKey : l'API Directory renvoie une erreur. Vous devez envoyer deux requêtes distinctes avec ces arguments.

Dans l'exemple suivant, un administrateur de compte utilise my_customer pour demander la liste de tous les groupes d'un compte :

GET https://admin.googleapis.com/admin/directory/v1/groups?domain=sales.com&customer=my_customer&maxResults=2

Dans l'exemple suivant, la requête d'un administrateur revendeur renvoie tous les groupes du compte revendu avec customerId C03az79cb. Le nombre maximal de résultats renvoyés par page de réponse est de deux. Il existe un nextPageToken pour la liste des utilisateurs suivants dans cette réponse : 

GET https://admin.googleapis.com/admin/directory/v1/groups?domain=sales.com&customer=C03az79cb&maxResults=2

Une réponse réussie renvoie un code d'état HTTP 200 et les groupes dans l'ordre alphabétique de l'adresse e-mail du groupe : 

{
"kind": "directory#groups",
    "groups": [
     {
      "kind": "directory#groups",
      "id": "group's unique ID",
      "etag": "group's unique ETag",
      "email": "support@sales.com",
      "name": "Sales support",
      "directMembersCount": "6",
      "description": "The sales support group",
      "adminCreated": true
     },
     {
      "kind": "directory#groups",
      "id": "group's unique ID",
      "etag": "group's unique ETag",
      "email": "travel@sales.com",
      "name": "Sales travel",
      "directMembersCount": "2",
      "description": "The travel group supporting sales",
      "adminCreated": false,
      "aliases": [
       {
         "alias": "best_sales_group@example.com"
       }
      ],
      "nonEditableAliases": [
       {
         "alias": "liz@test.com"
       }
      ]
     },
  "nextPageToken": "NNNN"
  }

Récupérer tous les groupes d'un membre

Pour récupérer tous les groupes auxquels un membre est abonné, utilisez la requête GET suivante et incluez l'autorisation décrite dans Autoriser les requêtes. Des retours à la ligne ont été inclus dans cet exemple pour le rendre plus lisible. 

GET https://admin.googleapis.com/admin/directory/v1/groups?userKey=user key
&pageToken=pagination token
&maxResults=maximum results per response page
  • Un membre peut être un utilisateur ou un groupe.
  • userKey peut être l'adresse e-mail principale de l'utilisateur, son adresse e-mail d'alias, l'adresse e-mail principale d'un groupe, l'adresse e-mail d'alias d'un groupe ou l'id unique de l'utilisateur, que vous pouvez trouver à l'aide de l'opération Récupérer un utilisateur.
  • L'utilisateur ou le groupe spécifié dans userKey doit appartenir à votre domaine.
  • Utilisez la chaîne de requête pageToken pour les réponses comportant un grand nombre de groupes. En cas de pagination, la réponse renvoie la propriété nextPageToken, qui fournit un jeton pour la page suivante des résultats de la réponse. Votre prochaine requête utilise ce jeton comme valeur de chaîne de requête pageToken.
  • Utilisation des arguments customer et userKey : l'API Directory renvoie une erreur. Vous devez envoyer deux requêtes distinctes avec ces arguments.

Pour en savoir plus sur les propriétés de requête et de réponse, consultez la méthode groups.list.

Une réponse réussie renvoie un code d'état HTTP 200 et la liste des informations sur les membres :

  • Tous les groupes auxquels un membre est abonné sont renvoyés, y compris ceux qui ne font pas partie du domaine de l'utilisateur.
  • Les groupes sont renvoyés par ordre alphabétique de l'adresse e-mail de chacun d'eux.
  • Dans le corps de la réponse, id correspond à l'ID unique du groupe.
  • Dans la réponse, la liste d'un groupe extérieur au domaine de l'utilisateur n'inclut pas les alias du groupe externe. 
{
    "kind": "directory#groups",
    "groups": [
     {
      "kind": "directory#group",
      "id": "group's unique ID",
      "etag": "group's unique ETag",
      "email": "sales_group@example.com",
      "name": "sale group",
      "directMembersCount": "5",
      "description": "Sales group"
     },
     {
      "kind": "directory#group",
      "id": "group's unique ID",
      "etag": "group's unique ETag",
      "email": "support_group.com",
      "name": "support group",
      "directMembersCount": "5",
      "description": "Support group"
     }
  ],
   "nextPageToken": "NNNNN"
}

Récupérer tous les alias de groupe

Pour récupérer tous les alias d'un groupe, utilisez la requête GET suivante et incluez l'autorisation décrite dans Autoriser les requêtes. Le groupKey peut être l'adresse e-mail principale du groupe, son id unique ou l'une de ses adresses e-mail d'alias. Pour en savoir plus sur les propriétés de requête et de réponse, consultez la ressource groups. 

GET https://admin.googleapis.com/admin/directory/v1/groups/groupKey/aliases

Une réponse réussie renvoie un code d'état HTTP 201 et une liste des alias du groupe.

Supprimer un alias de groupe

Pour supprimer l'alias d'un groupe, utilisez la requête DELETE suivante et incluez l'autorisation décrite dans Autoriser les requêtes. Le groupKey peut être l'adresse e-mail principale du groupe, son id unique ou l'une de ses adresses e-mail d'alias. aliasId correspond à l'alias en cours de suppression. Pour en savoir plus sur les propriétés de requête et de réponse, consultez la ressource groups : 

DELETE https://admin.googleapis.com/admin/directory/v1/groups/groupKey/aliases/aliasId

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

Supprimer un groupe

Pour supprimer un groupe, utilisez la requête DELETE suivante et incluez l'autorisation décrite dans Autoriser les requêtes. groupKey est l'id unique du groupe : 

DELETE https://admin.googleapis.com/admin/directory/v1/groups/groupKey

Par exemple, cette requête DELETE supprime le groupe qui contient le groupe nnnn id :

DELETE https://admin.googleapis.com/admin/directory/v1/group/nnnn

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

Lorsque vous supprimez un groupe, les éléments suivants se produisent :

  • Tous les membres du groupe sont supprimés. Les comptes utilisateur du membre ne sont pas supprimés.
  • L'archive du groupe est supprimée.
  • Les messages envoyés à l'adresse du groupe supprimé ne sont pas distribués. En revanche, l'expéditeur reçoit un message d'erreur automatique.