Gérer les groupes

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

  • Créer un groupe
  • Mettre à jour un groupe
  • Ajouter un alias de groupe
  • Récupérer un groupe
  • Récupérez tous les groupes d'un domaine ou d'un 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 la section 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 réussie renvoie un code d'état HTTP 201 et les propriétés du nouveau groupe.

Mettre à jour un groupe

Pour mettre à jour les paramètres d'un groupe, utilisez la requête PUT suivante et incluez l'autorisation décrite dans la section Autoriser les requêtes. groupKey correspond à l'adresse e-mail du groupe, à l'adresse 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, Google recommande de ne pas utiliser l'adresse e-mail du groupe comme clé pour les données persistantes, car elle est susceptible d'être modifiée.

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 mise à jour, vous n'avez qu'à envoyer 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.

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 la section Autoriser les requêtes. groupKey correspond à l'adresse e-mail du groupe, à l'adresse 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 d'être modifiée.

La requête JSON suivante montre un exemple de requête pour créer l'alias d'un 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 la section Autoriser les requêtes. groupKey correspond à l'adresse e-mail du groupe, à l'adresse 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 d'être modifiée.

Dans l'exemple suivant, l'ID groupKey unique 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érez tous les groupes d'un domaine ou d'un 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 la section 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 qui accède 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.
  • Ne pas 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 envoie la requête.
  • Utilisation des arguments customer et userKey: l'API Directory renvoie une erreur. Vous devez effectuer 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 de 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. La réponse contient un nextPageToken pour la liste des utilisateurs suivante: 

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 par 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 pour lesquels un membre dispose d'un abonnement, utilisez la requête GET suivante et incluez l'autorisation décrite dans la section 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'alias d'adresse e-mail d'un groupe ou l'id unique de l'utilisateur, que vous pouvez trouver à l'aide de l'opération Retrieve a user (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 de résultats de la réponse. Votre prochaine requête utilise ce jeton comme valeur de la chaîne de requête pageToken.
  • Utilisation des arguments customer et userKey: l'API Directory renvoie une erreur. Vous devez effectuer 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 pour lesquels un membre dispose d'un abonnement, y compris les groupes en dehors du domaine de l'utilisateur, sont renvoyés.
  • Les groupes sont renvoyés par ordre alphabétique de l'adresse e-mail de chaque groupe.
  • Dans le corps de la réponse, id correspond à l'ID unique du groupe.
  • Dans la réponse, la liste d'un groupe en dehors du 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"
     }
  ],
   "nextPakeToken": "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 la section Autoriser les requêtes. groupKey peut être l'adresse e-mail principale du groupe, son id unique ou l'une des adresses e-mail des alias du groupe. 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 la section Autoriser les requêtes. groupKey peut être l'adresse e-mail principale du groupe, son id unique ou l'une des adresses e-mail des alias du groupe. aliasId correspond à l'alias supprimé. 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 la section 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 possède le groupe id nnnn: 
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 conséquences sont les suivantes:

  • Tous les membres du groupe sont supprimés. Les comptes utilisateur des membres 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. L'expéditeur reçoit alors un message d'erreur automatique.