Cette page a été traduite par l'API Cloud Translation.

Présentation de l'API Admin Settings

L'API Admin Settings permet aux administrateurs de domaines Google Workspace de récupérer et de modifier les paramètres de leurs domaines sous la forme de flux d'API Google Data.

Ces paramètres de domaine incluent de nombreuses fonctionnalités disponibles dans la console d'administration Google Workspace. Cette API peut être utilisée, par exemple, pour créer un panneau de configuration personnalisé ou intégrer des domaines Google Workspace à un ancien environnement existant.

L'API Admin Settings met en œuvre le protocole Google Data API. L'API Google Data est conforme au modèle de publication et d'édition AtomPub (Atom Publishing Protocol). Les requêtes HTTP AtomPub utilisent l'approche de conception RESTful (Representational Set Transfer) pour les services Web. Pour en savoir plus, consultez le guide du développeur de données Google.

Audience

Ce document est destiné aux développeurs qui souhaitent créer des applications clientes capables de modifier et de récupérer des informations sur les domaines Google Workspace. Il fournit des exemples d'interactions de base de l'API Admin Settings à l'aide de fichiers XML et HTTP bruts.

Dans ce document, nous partons du principe que vous comprenez les concepts généraux du protocole API Google Data et que vous connaissez la console d'administration Google Workspace. Pour en savoir plus sur la console d'administration, consultez Utiliser votre console d'administration.

Premiers pas

Création d'un compte

L'API Admin Settings est activée pour les comptes Google Workspace. Créez un compte Google Workspace à des fins de test. Le service Paramètres administrateur utilise des comptes Google. Si vous possédez déjà un compte sur un domaine Google Workspace, vous n'avez donc rien à faire.

À propos des types de flux de l'API Admin Settings

L'API Admin Settings vous permet de gérer ces catégories de paramètres de domaine:

Paramètres d'authentification unique

L'authentification unique (SSO) basée sur SAML permet aux utilisateurs d'utiliser les mêmes identifiant et mot de passe pour les services hébergés par Google Workspace et pour d'autres services hébergés par votre organisation. Plus précisément, lorsque vous utilisez l'authentification unique, une application Web hébergée, telle que Google Workspace, redirige les utilisateurs vers le fournisseur d'identité de votre organisation pour authentifier les utilisateurs lorsqu'ils se connectent. Pour en savoir plus, consultez Comprendre l'authentification unique basée sur SAML pour Google Workspace.

La configuration de l'authentification unique implique de saisir les informations nécessaires pour que le service Google Workspace puisse communiquer avec le fournisseur d'identité qui stocke les informations de connexion de vos utilisateurs. Elle définit également les liens vers lesquels les utilisateurs doivent être envoyés pour se connecter, se déconnecter et modifier leurs mots de passe. L'API Admin Settings vous permet de mettre à jour et de récupérer ces paramètres par programmation. Google utilise la clé publique générée pour vérifier cette requête SSO auprès de votre fournisseur d'identité et que la réponse SAML associée à la clé privée n'a pas été modifiée lors de la transmission réseau.

Pour obtenir un bref résumé de l'utilisation des paramètres SSO pour l'API, obtenez un certificat de clé publique auprès de votre fournisseur d'identité, enregistrez la clé publique auprès de Google et configurez les paramètres de requête SSO SAML. Pour les messages d'erreur, consultez Résoudre les problèmes liés à l'authentification unique:

Générez vos clés : avec votre fournisseur d'identité, générez un ensemble de clés publiques et privées à l'aide des algorithmes DSA ou RSA. La clé publique se trouve dans un certificat au format X.509. Pour en savoir plus sur les clés de signature d'authentification unique basées sur SAML, consultez Générer des clés et des certificats pour le service d'authentification unique de Google Workspace.
Enregistrement auprès de Google : utilisez les paramètres d'authentification unique de l'API Admin Settings pour enregistrer votre certificat de clé publique auprès de Google.
Définissez vos paramètres SSO : utilisez les paramètres d'authentification unique de l'API Admin Settings pour configurer les paramètres de communication avec les serveurs du fournisseur d'identité du domaine.

Paramètres de passerelle et d'itinéraire

Ce flux permet aux administrateurs de domaine de contrôler l'acheminement des e-mails pour leurs domaines.

Les opérations de routage des e-mails permettent aux administrateurs de spécifier les paramètres de routage des e-mails au niveau du domaine. Cette fonctionnalité est semblable à la fonctionnalité de routage des e-mails des paramètres Gmail de la console d'administration. Pour plus d'informations, consultez les articles relatifs au routage des e-mails et à la configuration de la double distribution des e-mails.

Exemple de requête et de réponse XML de l'API Admin Settings

Ce document fournit des exemples de code de requêtes et de réponses basiques de l'API Admin Settings au format XML et HTTP brut. Cet exemple de langage par défaut du domaine montre la syntaxe XML et HTTP complète pour le corps d'une entrée de requête et de réponse, commun à chaque opération:

Pour modifier le paramètre de passerelle de messagerie sortante du domaine, envoyez une requête HTTP PUT à l'URL du flux de la passerelle:

https://apps-apis.google.com/a/feeds/domain/2.0/{domainName}/email/gateway

La langue par défaut du domaine PUT pour la requête XML AtomPub entry est:

<atom:entry xmlns:atom='http://www.w3.org/2005/Atom'
  xmlns:apps='http://schemas.google.com/apps/2006'>
  <apps:property name='smartHost' value='smtp.out.domain.com' />
  <apps:property name='smtpMode' value='SMTP' />
</atom:entry>

À l'exception des propriétés et des valeurs spécifiques à l'opération, les éléments atom:property représentent une seule paire clé-valeur contenant des informations sur une propriété que vous souhaitez récupérer ou mettre à jour. Ils sont communs à tous les corps de requêtes de l'API Admin Settings.

L'élément entry de réponse en langue par défaut du domaine renvoie les propriétés smartHost et smtpMode, ainsi que la syntaxe XML commune à tous les corps de réponse de l'API Admin Settings:

<?xml version='1.0' encoding='UTF-8'?>
<entry xmlns='http://www.w3.org/2005/Atom' xmlns:apps='http://schemas.google.com/apps/2006'>
<id>https://apps-apis.google.com/a/feeds/domain/2.0/domainName/email/gateway</id>
<updated>2008-12-17T23:59:23.887Z</updated>
<link rel='self' type='application/atom+xml' href='https://apps-apis.google.com/a/feeds/domain/
  2.0/domainName/email/gateway'/>
<link rel='edit' type='application/atom+xml' href='https://apps-apis.google.com/a/feeds/domain/
  2.0/domainName/email/gateway'/>
<apps:property name='smartHost' value='smtp.out.domain.com' />
<apps:property name='smtpMode' value='SMTP' />
</entry>

Gestion des paramètres d'authentification unique

La fonctionnalité d'authentification unique (SSO) de Google Workspace permet aux utilisateurs de se connecter à plusieurs services sans avoir à saisir leur identifiant et leur mot de passe une seule fois. Ce mot de passe est stocké par le fournisseur d'identité du domaine, et non par Google Workspace. Pour en savoir plus, consultez la page sur l'authentification unique dans le centre d'aide. Les sections suivantes décrivent le format XML utilisé pour les paramètres d'authentification unique.

Récupération des paramètres d'authentification unique

Pour récupérer les paramètres d'authentification unique, envoyez une requête HTTP GET à l'URL de flux général d'authentification unique et incluez un en-tête Authorization, comme décrit dans la section Authentification auprès du service des paramètres de l'administrateur. Pour les messages d'erreur, consultez la page Résoudre les problèmes liés à l'authentification unique:

https://apps-apis.google.com/a/feeds/domain/2.0/{domainName}/sso/general

Le corps de la requête ne comporte aucun paramètre pour cette opération.

Les réponses positives renvoient un code d'état HTTP 200 OK, ainsi qu'un flux AtomPub avec les paramètres SSO du domaine.

Le code XML de réponse GET renvoie les propriétés samlSignonUri, samlLogoutUri, changePasswordUri, enableSSO, ssoWhitelist et useDomainSpecificIssuer:

<?xml version='1.0' encoding='UTF-8'?>
<entry xmlns='http://www.w3.org/2005/Atom' xmlns:apps='http://schemas.google.com/apps/2006'>
<apps:property name='samlSignonUri' value='http://www.example.com/sso/signon'/>
...
<apps:property name='samlLogoutUri' value='http://www.example.com/sso/logout'/>
<apps:property name='changePasswordUri' value='http://www.example.com/sso/changepassword'/>
<apps:property name='enableSSO' value='true'/>
<apps:property name='ssoWhitelist' value='CIDR formatted IP address'/>
<apps:property name='useDomainSpecificIssuer' value='false'/>
</entry>

Ces propriétés sont les suivantes:

dnsSignonUri: URL du fournisseur d'identité à laquelle Google Workspace envoie la requête SAML pour l'authentification de l'utilisateur.
docsLogoutUri: Adresse à laquelle les utilisateurs sont redirigés lorsqu'ils se déconnectent de l'application Web.
changePasswordURI: Adresse à laquelle les utilisateurs sont redirigés s'ils souhaitent modifier leur mot de passe SSO pour l'application Web.
activer l'authentification unique: Active l'authentification unique basée sur SAML pour ce domaine. Si vous avez déjà configuré des paramètres SSO et que vous avez ensuite défini enableSSO sur enableSSO=false, les paramètres précédemment saisis restent enregistrés.
ssoListe blanche: Une liste blanche est une adresse IP de masque réseau au format CIDR (Classless Inter-Domain Routing). La liste blanche ssoList détermine les utilisateurs qui se connectent avec l'authentification unique et ceux qui se connectent via la page d'authentification des comptes Google Workspace. Si aucun masque n'est spécifié, tous les utilisateurs se connecteront via l'authentification unique. Pour en savoir plus, consultez Fonctionnement des masques réseau.
useDomainSpecificIssuer: Un émetteur spécifique au domaine peut être utilisé dans la requête SAML adressée au fournisseur d'identité. Bien qu'elle ne soit pas nécessaire pour la plupart des déploiements SSO, cette fonctionnalité est utile dans les grandes entreprises qui utilisent un seul fournisseur d'identité pour authentifier l'ensemble d'une organisation avec plusieurs sous-domaines. Cela permet de déterminer le sous-domaine à associer à la requête. Pour en savoir plus, consultez Comment fonctionne l'élément "Émetteur" de la requête SAML ?

Si votre requête échoue pour une raison quelconque, un code d'état différent est renvoyé. Pour en savoir plus sur les codes d'état de l'API Google Data, consultez Codes d'état HTTP.

Mise à jour des paramètres d'authentification unique

Pour mettre à jour les paramètres SSO d'un domaine, commencez par les récupérer à l'aide de l'opération Récupérer les paramètres d'authentification unique, modifiez-les, puis envoyez une requête PUT à l'URL du flux SSO. Assurez-vous que la valeur <id> de l'entrée mise à jour correspond exactement à la valeur <id> de l'entrée existante. Incluez un en-tête Authorization comme décrit dans la section Authentification auprès du service de l'API Admin Settings. Pour les messages d'erreur, consultez Résoudre les problèmes liés à l'authentification unique.

Lors de la mise à jour des paramètres d'authentification unique, envoyez une requête HTTP PUT à l'URL générale du flux SSO:

https://apps-apis.google.com/a/feeds/domain/2.0/{domainName}/sso/general

Le corps XML de la requête PUT est le suivant:

<atom:entry xmlns:atom='http://www.w3.org/2005/Atom' xmlns:apps='http://schemas.google.com/apps/2006'>
<apps:property name='enableSSO' value='false' />
<apps:property name='samlSignonUri' value='http://www.example.com/sso/signon' />
<apps:property name='samlLogoutUri' value='http://www.example.com/sso/logout' />
<apps:property name='changePasswordUri' value='http://www.example.com/sso/changepassword' />
<apps:property name='ssoWhitelist' value='127.0.0.1/32' />
<apps:property name='useDomainSpecificIssuer' value='false'/>
</atom:entry>

Les réponses positives renvoient un code d'état HTTP 200 OK, ainsi qu'un flux AtomPub avec les paramètres SSO.

Le code XML de la réponse PUT est le suivant:

<?xml version='1.0' encoding='UTF-8'?>
<entry xmlns='http://www.w3.org/2005/Atom' xmlns:apps='http://schemas.google.com/apps/2006'>
...
<apps:property name='samlSignonUri' value='http://www.example.com/sso/signon'/>
<apps:property name='samlLogoutUri' value='http://www.example.com/sso/logout'/>
<apps:property name='changePasswordUri' value='http://www.example.com/sso/changepassword'/>
<apps:property name='enableSSO' value='false'/>
<apps:property name='ssoWhitelist' value='127.0.0.1/32'/>
<apps:property name='useDomainSpecificIssuer' value='false'/>
</entry>

Si votre requête échoue pour une raison quelconque, un code d'état différent est renvoyé. Pour en savoir plus sur les codes d'état de l'API Google Data, consultez Codes d'état HTTP.

Récupération de la clé de signature d'authentification unique

Pour récupérer la clé de signature d'authentification unique, envoyez une requête HTTP GET à l'URL du flux de la clé de signature SSO et incluez un en-tête Authorization, comme décrit dans la section Authentification auprès du service des paramètres de l'administrateur. Pour les messages d'erreur, consultez la page Résoudre les problèmes liés à l'authentification unique:

https://apps-apis.google.com/a/feeds/domain/2.0/{domainName}/sso/signingkey

Le corps de la requête ne comporte aucun paramètre pour cette opération.

Les réponses positives renvoient un code d'état HTTP 200 OK, ainsi qu'un flux AtomPub et la clé de signature.

Le code XML de la réponse GET renvoie la propriété signingKey:

<?xml version='1.0' encoding='UTF-8'?>
<entry xmlns='http://www.w3.org/2005/Atom' xmlns:apps='http://schemas.google.com/apps/2006'>
...
<apps:property name='signingKey' value='yourBase64EncodedPublicKey'/>
</entry>

Si votre requête échoue pour une raison quelconque, un code d'état différent est renvoyé. Pour en savoir plus sur les codes d'état de l'API Google Data, consultez Codes d'état HTTP.

Mise à jour de la clé de signature d'authentification unique

Pour mettre à jour la clé de signature SSO d'un domaine, récupérez-la d'abord à l'aide de l'opération Récupération de la clé de signature d'authentification unique, modifiez-la, puis envoyez une requête PUT à l'URL du flux de la clé de signature SSO. Assurez-vous que la valeur <id> de l'entrée mise à jour correspond exactement à la valeur <id> de l'entrée existante. Pour en savoir plus sur les clés de signature d'authentification unique basées sur SAML, consultez Générer des clés et des certificats pour le service d'authentification unique de Google Workspace.

Lors de la mise à jour de la clé de signature d'authentification unique, envoyez une requête HTTP PUT à l'URL du flux de la clé de signature SSO:

https://apps-apis.google.com/a/feeds/domain/2.0/{domainName}/sso/signingkey

Le code XML de la requête PUT est le suivant:

<atom:entry xmlns:atom='http://www.w3.org/2005/Atom' xmlns:apps="http://schemas.google.com/apps/2006">
<apps:property name='signingKey' value='yourBase64EncodedPublicKey'/>
</atom:entry>

Gérer la passerelle de messagerie et le routage

La section "Passerelle de messagerie sortante" explique comment l'API Admin Settings gère le routage des e-mails sortants des utilisateurs de votre domaine. La section "Routage des e-mails" montre comment router les messages vers un autre serveur de messagerie.

Récupération des paramètres de passerelle de messagerie sortante...

Pour récupérer les paramètres de la passerelle de messagerie sortante, envoyez une requête HTTP GET à l'URL du flux de la passerelle et incluez un en-tête Authorization comme décrit dans la section Authentification auprès du service Paramètres de l'administrateur:

https://apps-apis.google.com/a/feeds/domain/2.0/{domainName}/email/gateway

Le corps de la requête ne comporte aucun paramètre pour cette opération.

Une réponse positive renvoie un code d'état HTTP 200 OK, ainsi qu'un flux AtomPub contenant les informations d'état de la passerelle de messagerie.

La réponse GET renvoie les propriétés smartHost et smtpMode. Pour en savoir plus sur ces propriétés, consultez l'article Mettre à jour les paramètres de passerelle de messagerie sortante.

Voici un exemple de réponse possible:

<?xml version='1.0' encoding='UTF-8'?>
<entry xmlns='http://www.w3.org/2005/Atom' xmlns:apps='http://schemas.google.com/apps/2006'>
...
<apps:property name='smartHost' value='smtpout.domain.com'/>
<apps:property name='smtpMode' value='SMTP'/>
</entry>

Si votre requête échoue pour une raison quelconque, un code d'état différent est renvoyé. Pour en savoir plus sur les codes d'état de l'API Google Data, consultez Codes d'état HTTP.

Mise à jour des paramètres de passerelle de messagerie sortante...

Pour mettre à jour le paramètre de passerelle de messagerie sortante d'un domaine, envoyez une requête HTTP PUT à l'URL du flux de la passerelle:

https://apps-apis.google.com/a/feeds/domain/2.0/{domainName}/email/gateway

Le code XML de la requête PUT est le suivant:

<atom:entry xmlns:atom='http://www.w3.org/2005/Atom' xmlns:apps="http://schemas.google.com/apps/2006">
<apps:property name='smartHost' value='smtp.out.domain.com' />
<apps:property name='smtpMode' value='SMTP' />
</atom:entry>

Les propriétés de la requête sont les suivantes:

Hôte intelligent: Adresse IP ou nom d'hôte de votre serveur SMTP. Google Workspace achemine les messages sortants vers ce serveur.
smtpMode: La valeur par défaut est SMTP. Une autre valeur, SMTP_TLS, sécurise une connexion avec TLS lors de la distribution du message.

Les réponses réussies renvoient un code d'état HTTP 200 OK, ainsi que le flux AtomPub et l'état des paramètres de la passerelle de messagerie.

Si votre requête échoue pour une raison quelconque, un code d'état différent est renvoyé. Pour en savoir plus sur les codes d'état de l'API Google Data, consultez Codes d'état HTTP.

Gestion des paramètres de routage des e-mails

Commencez par créer une requête XML:

<atom:entry xmlns:atom='http://www.w3.org/2005/Atom' xmlns:apps="http://schemas.google.com/apps/2006">
<apps:property name='routeDestination' value='route-smtp.domain.com'/>
<apps:property name='routeRewriteTo' value='true'/>
<apps:property name='routeEnabled' value='true'/>
<apps:property name='bounceNotifications' value='true'/>
<apps:property name='accountHandling' value='can be either allAccounts | provisionedAccounts | unknownAccounts'/>
</atom:entry>

Les propriétés de la requête sont les suivantes:

routeDestination

Cette destination correspond au nom d'hôte ou à l'adresse IP du serveur de messagerie SMTP-In vers lequel les e-mails sont routés. Le nom d'hôte ou l'adresse IP doit être résolu pour Google. Pour en savoir plus sur la résolution des noms d'hôte de messagerie, consultez Piloter Google Workspace avec routage des e-mails.

routeRewriteTo

Si la valeur est "true", le champ to: de l'enveloppe SMTP du message est remplacé par le nom d'hôte de destination (utilisateur@nom d'hôte de la destination). Le message est alors distribué à cet utilisateur sur le serveur de messagerie de destination. Si la valeur est false, l'e-mail est distribué à l'adresse e-mail to: du message d'origine (utilisateur@nom d'hôte d'origine) sur le serveur de messagerie de destination. Ce paramètre est similaire au paramètre "Modifier l'enveloppe SMTP" de la console d'administration. Pour en savoir plus, consultez Paramètres du domaine pour le routage des e-mails.

routeEnabled

Si la valeur est true, la fonctionnalité de routage des e-mails est activée. Si la valeur est false, la fonctionnalité est désactivée.

notifications de non-distribution

Si la valeur est true, Google Workspace est activé pour envoyer des notifications de non-distribution à l'expéditeur en cas d'échec de la distribution.

gestionducompte

Ce paramètre détermine l'impact du routage des e-mails sur les différents types d'utilisateurs du domaine:

allAccounts : distribue tous les e-mails à cette destination.
provisionedAccounts : distribue le courrier à cette destination si l'utilisateur existe dans Google Workspace.
unknownAccounts : distribue le courrier à cette destination si l'utilisateur n'existe pas dans Google Workspace. Ce paramètre est similaire au paramètre "Envoyer un e-mail pour" dans la console d'administration. Pour plus d'informations sur les conditions préalables et l'utilisation du routage des e-mails, consultez Paramètres du domaine pour le routage des e-mails. ~ Pour publier cette requête, envoyez une requête HTTP POST à l'URL du flux d'acheminement des e-mails et incluez un en-tête Authorization comme décrit dans la section Authentification auprès du service des paramètres d'administration:

https://apps-apis.google.com/a/feeds/domain/2.0/{domainName}/emailrouting

Une réponse positive renvoie un code d'état HTTP 200 OK, ainsi qu'un flux AtomPub avec les informations d'archive.

Si votre requête échoue pour une raison quelconque, un code d'état différent est renvoyé. Pour en savoir plus sur les codes d'état de l'API Google Data, consultez Codes d'état HTTP.

Abandon des points de terminaison le 31 octobre 2018

Nous avons abandonné les points de terminaison suivants dans le cadre de cette annonce. Ils ont été abandonnés le 31 octobre 2018 et ne sont plus disponibles.

https://apps-apis.google.com/a/feeds/domain/2.0/{domainName}/general/defaultLanguage
https://apps-apis.google.com/a/feeds/domain/2.0/{domainName}/general/organizationName
https://apps-apis.google.com/a/feeds/domain/2.0/{domainName}/general/currentNumberOfUsers
https://apps-apis.google.com/a/feeds/domain/2.0/{domainName}/general/maximumNumberOfUsers
https://apps-apis.google.com/a/feeds/domain/2.0/{domainName}/accountInformation/supportPIN
https://apps-apis.google.com/a/feeds/domain/2.0/{domainName}/accountInformation/customerPIN
https://apps-apis.google.com/a/feeds/domain/2.0/{domainName}/accountInformation/adminSecondaryEmail
https://apps-apis.google.com/a/feeds/domain/2.0/{domainName}/accountInformation/edition
https://apps-apis.google.com/a/feeds/domain/2.0/{domainName}/accountInformation/creationTime
https://apps-apis.google.com/a/feeds/domain/2.0/{domainName}/accountInformation/countryCode
https://apps-apis.google.com/a/feeds/domain/2.0/{domainName}/appearance/customLogo
https://apps-apis.google.com/a/feeds/domain/2.0/{domainName}/verification/mx