Cette page explique comment gérer Google Groupes avec l'API Directory:
- Créer un groupe
- Mettre à jour un groupe
- Ajouter un alias de groupe
- Récupérer un groupe
- Récupérer 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 les chaînes de requête, et les propriétés de requête et 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." }
Les succès de la réponse affichent 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'une des adresses e-mail de l'alias de groupe ou au id
unique du groupe. Pour les chaînes de requête, et les propriétés de requête et 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 de changer.
Dans l'exemple suivant, le 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, il vous suffit d'envoyer les informations mises à jour. Vous n'avez pas besoin de saisir toutes les propriétés du groupe dans la requête.
Une réponse positive 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'une des adresses e-mail de l'alias de groupe ou au id
unique du groupe. Pour en savoir plus sur les chaînes de requête, et les propriétés de requête et 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 présente un exemple de requête permettant de créer un alias de groupe. groupKey
est l'élément 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 positive 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êteGET
suivante et incluez l'autorisation décrite dans la section Autoriser les requêtes.
groupKey
correspond à l'adresse e-mail du groupe, à l'une des adresses e-mail de l'alias de groupe ou au id
unique du groupe. Pour les chaînes de requête, et les propriétés de requête et 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 groupKey
unique est nnnn
:
GET https://admin.googleapis.com/admin/directory/v1/groups/nnnn
Une réponse positive 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 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 les chaînes de requête, et les propriétés de requête et de réponse, consultez la méthode groups.list
.
Pour une meilleure lisibilité, cet exemple utilise des retours à la ligne:
GET https://admin.googleapis.com/admin/directory/v1/groups?domain=domain name &customer=my_customer or customerId&pageToken=pagination token &maxResults=max results
Lors de la récupération de 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
avecmy_customer
ou la valeurcustomerId
du compte. En tant qu'administrateur de compte, utilisez la chaînemy_customer
pour représenter lecustomerId
de votre compte. Si vous êtes un revendeur accédant au compte d'un client indirect, utilisez lecustomerId
de ce compte. Pour la valeurcustomerId
, 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 valeurcustomerId
. - Utilisation des arguments
domain
etcustomer
: l'API Directory renvoie tous les groupes associés àdomain
. - Les arguments
domain
etcustomer
ne sont pas utilisés: l'API Directory renvoie tous les groupes du compte associé àmy_customer
. Il s'agit du comptecustomerId
de l'administrateur à l'origine de la requête. - Utilisation des arguments
customer
etuserKey
: 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 revendeur renvoie tous les groupes du compte revendu avec le customerId C03az79cb
. Le nombre maximal de résultats renvoyés par page de réponse est de 2.
Il existe un nextPageToken
pour la liste d'utilisateurs suivante dans cette réponse:
GET https://admin.googleapis.com/admin/directory/v1/groups?domain=sales.com&customer=C03az79cb&maxResults=2
Une réponse positive 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 la section Autoriser les requêtes. Pour une meilleure lisibilité, cet exemple utilise des retours à la ligne:
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.
- Le
userKey
peut être l'adresse e-mail principale de l'utilisateur, son alias d'adresse e-mail, l'adresse e-mail principale d'un groupe, l'alias d'adresse e-mail d'un groupe ou leid
unique de l'utilisateur (que vous pouvez trouver en utilisant l'opération de récupération d'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. Dans le cas de la pagination, la réponse renvoie la propriéténextPageToken
qui donne un jeton pour la page suivante de résultats de réponse. Votre prochaine requête utilisera ce jeton comme valeur de la chaîne de requêtepageToken
. - Utilisation des arguments
customer
etuserKey
: l'API Directory renvoie une erreur. Vous devez effectuer deux requêtes distinctes avec ces arguments.
Pour les propriétés de requête et de réponse, consultez la méthode groups.list
.
Une réponse positive renvoie un code d'état HTTP 200 et la liste des informations sur les membres:
- La liste renvoie tous les groupes auxquels un membre possède un abonnement, y compris les groupes extérieurs au domaine de l'utilisateur.
- Les groupes sont renvoyés dans l'ordre alphabétique de l'adresse e-mail de chaque groupe.
- Dans le corps de la réponse,
id
est l'identifiant 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" } ], "nextPakeToken": "NNNNN" }
Récupérer tous les alias de groupe
Pour récupérer tous les alias d'un groupe, utilisez la requêteGET
suivante et incluez l'autorisation décrite dans la section Autoriser les requêtes. groupKey
peut être l'adresse e-mail principale du groupe, l'adresse id
unique de celui-ci ou l'une des adresses e-mail des alias de groupe. Pour 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
Les appels réussis affichent un code d'état HTTP 201
et la liste des alias du groupe.
Supprimer un alias de groupe
Pour supprimer l'alias d'un groupe, utilisez la requêteDELETE
suivante et incluez l'autorisation décrite dans la section Autoriser les requêtes.
Le champ groupKey
peut être l'adresse e-mail principale du groupe, l'adresse id
unique du groupe ou l'une des adresses e-mail des alias de groupe. aliasId
est l'alias en cours de suppression. Pour 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
Les appels réussis affichent 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.
Le groupKey
est le id
unique du groupe:
DELETE https://admin.googleapis.com/admin/directory/v1/groups/groupKey
Par exemple, cette requête DELETE
supprime le groupe contenant le groupe nnnn
id
:
DELETE https://admin.googleapis.com/admin/directory/v1/group/nnnn
Les appels réussis affichent un code d'état HTTP 200
.
Voici ce qui se produit lorsqu'un groupe est supprimé:
- 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. À la place, l'expéditeur reçoit un message d'erreur automatique.