L'API Admin Settings consente agli amministratori dei domini Google Workspace di recuperare e modificare le impostazioni dei propri domini sotto forma di feed dell'API di dati Google.
Queste impostazioni del dominio includono molte delle funzionalità disponibili nella Console di amministrazione Google Workspace. Esempi di utilizzo di questa API includono la creazione di un pannello di controllo personalizzato o l'integrazione dei domini Google Workspace in un ambiente legacy esistente.
L'API Admin Settings implementa il protocollo dell'API di dati Google. L'API di dati Google è conforme al modello di pubblicazione e modifica del protocollo Atom Publishing (AtomPub). Le richieste HTTP AtomPub utilizzano l'approccio di progettazione RESTful (Representational Set Transfer) per i servizi web. Per ulteriori informazioni, consulta la Guida per gli sviluppatori dell'API di dati Google.
Pubblico
Questo documento è destinato agli sviluppatori che vogliono scrivere applicazioni client in grado di modificare e recuperare informazioni sui domini Google Workspace. Fornisce esempi delle interazioni di base dell'API Admin Settings utilizzando XML e HTTP non elaborati.
Questo documento presuppone che tu comprenda le idee generali alla base del the protocollo dell'API di dati Google e che tu abbia familiarità con la Console di amministrazione Google Workspace. Per ulteriori informazioni sulla Console di amministrazione, consulta Utilizzare la Console di amministrazione.
Inizia
Per iniziare a utilizzare l'API Admin Settings, configura prima il tuo account.
Crea un account
L'API Admin Settings è abilitata per gli account Google Workspace. Registrati per un account Google Workspace a scopo di test. Il servizio Admin Settings utilizza Google Accounts, quindi se hai già un account su un dominio Google Workspace, non devi fare altro.
Informazioni sui tipi di feed dell'API Admin Settings
L'API Admin Settings consente di gestire queste categorie di impostazioni del dominio:
- Impostazioni Single Sign-On
- Il Single Sign-On (SSO) basato su SAML consente agli utenti di utilizzare lo stesso nome utente e la stessa password sia per i servizi ospitati di Google Workspace sia per altri servizi che potresti ospitare all'interno della tua organizzazione. In particolare, quando si utilizza SSO, un'applicazione web ospitata, come Google Workspace, reindirizza gli utenti al provider di identità della tua organizzazione per autenticarli quando accedono. Per informazioni dettagliate, consulta Informazioni sul servizio SSO basato su SAML per Google Workspace.
La configurazione di SSO prevede l'inserimento delle informazioni necessarie affinché il servizio Google Workspace comunichi con il provider di identità che memorizza i dati di accesso degli utenti, nonché la configurazione dei link a cui gli utenti devono essere inviati per accedere, uscire e modificare le password. L'API Admin Settings consente di aggiornare e recuperare queste impostazioni in modo programmatico. Google utilizza la chiave pubblica generata per verificare questa richiesta SSO con il tuo provider di identità e che la risposta SAML della chiave privata non sia stata modificata durante la trasmissione di rete.
Per un breve riepilogo specifico dell'API sull'utilizzo delle impostazioni SSO, recupera il certificato di chiave pubblica dal tuo provider di identità, registra la chiave pubblica con Google e configura le impostazioni di query SSO basate su SAML. Per i messaggi di errore, consulta Risoluzione dei problemi relativi a SSO:
- Genera le chiavi: con il tuo provider di identità, genera un insieme di chiavi pubbliche e private utilizzando gli algoritmi DSA o RSA. La chiave pubblica è in un certificato in formato X.509. Per ulteriori informazioni sulle chiavi di firma Single Sign-On basate su SAML, consulta Generare chiavi e certificati per il servizio Single Sign-On di Google Workspace.
- Registrati con Google: utilizza le impostazioni Single Sign-On dell'API Admin Settings per registrare il certificato di chiave pubblica con Google.
- Configura le impostazioni SSO: utilizza le impostazioni Single Sign-On dell'API Admin Settings per configurare le impostazioni utilizzate per la comunicazione con i server del provider di identità del dominio.
- Impostazioni del gateway
Questo feed consente agli amministratori di dominio di controllare il routing delle email per i propri domini.
Le operazioni di routing delle email consentono agli amministratori di specificare le impostazioni di routing delle email a livello di dominio. È simile alla funzionalità di routing delle email delle impostazioni di Gmail della Console di amministrazione. Per ulteriori informazioni, consulta Routing delle email e configurazione della doppia consegna della funzionalità di routing delle email.
Esempio di richiesta e risposta XML dell'API Admin Settings
Questo documento fornisce esempi di codice di richieste e risposte di base dell'API Admin Settings utilizzando XML e HTTP non elaborati. Questo esempio di lingua predefinita del dominio mostra la sintassi XML e HTTP completa per il corpo di una voce di richiesta e risposta, comune a ogni operazione:
Per modificare l'impostazione del gateway della posta in uscita del dominio, invia una richiesta HTTP PUT all'URL del feed del gateway:
https://apps-apis.google.com/a/feeds/domain/2.0/{domainName}/email/gateway
L'XML entry AtomPub della richiesta PUT della lingua predefinita del dominio è:
<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>
Ad eccezione delle proprietà e dei valori specifici dell'operazione, gli elementi atom:property rappresentano una singola coppia chiave-valore contenente informazioni su una proprietà che vuoi recuperare o aggiornare. Questi sono comuni a tutti i corpi delle richieste dell'API Admin Settings.
L'elemento entry della risposta della lingua predefinita del dominio restituisce le proprietà smartHost e smtpMode insieme alla sintassi XML comune a tutti i corpi delle risposte dell'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>
Gestire le impostazioni Single Sign-On
La funzionalità Single Sign-On (SSO) di Google Workspace consente agli utenti di accedere a più servizi inserendo un nome utente e una password una sola volta. Questa password viene memorizzata dal provider di identità del dominio, non da Google Workspace. Per ulteriori informazioni, consulta la pagina SSO del Centro assistenza. Le sezioni seguenti mostrano il formato XML utilizzato per le impostazioni Single Sign-On.
Recuperare le impostazioni Single Sign-On
Per recuperare le impostazioni Single Sign-On, invia una richiesta HTTP GET all'URL del feed generale SSO
e includi un'intestazione Authorization come descritto in Autenticarsi al servizio Admin Settings. Per i
messaggi di errore, consulta Risoluzione dei problemi
relativi a SSO:
https://apps-apis.google.com/a/feeds/domain/2.0/{domainName}/sso/general
Questa operazione non ha parametri nel corpo della richiesta.
Una risposta riuscita restituisce un codice di stato HTTP 200 OK, insieme a un feed AtomPub con le impostazioni SSO del dominio.
L'XML della risposta GET restituisce le proprietà samlSignonUri, samlLogoutUri, changePasswordUri, enableSSO, ssoWhitelist e 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>
Le proprietà includono:
- samlSignonUri
- L'URL del provider di identità a cui Google Workspace invia la richiesta SAML per l'autenticazione degli utenti.
- samlLogoutUri
- L'indirizzo a cui gli utenti verranno inviati quando escono dall'applicazione web.
- changePasswordUri
- L'indirizzo a cui gli utenti verranno inviati quando vogliono modificare la password SSO per l'applicazione web.
- enableSSO
- Attiva SSO basato su SAML per questo dominio. Se hai configurato in precedenza
le impostazioni SSO e successivamente hai impostato
enableSSOsuenableSSO=false, le impostazioni inserite in precedenza vengono comunque salvate. - ssoWhitelist
- Un ssoWhitelist è un indirizzo IP della maschera di rete in formato CIDR (Classless Inter-Domain Routing). Il ssoWhitelist determina quali utenti accedono utilizzando SSO e quali utenti accedono utilizzando la pagina di autenticazione dell'account Google Workspace. Se non vengono specificate maschere, tutti gli utenti accederanno utilizzando SSO. Per ulteriori informazioni, consulta Come funzionano le maschere di rete.
- useDomainSpecificIssuer
- Nella richiesta SAML al provider di identità è possibile utilizzare un emittente specifico del dominio. Sebbene non sia necessario per la maggior parte delle implementazioni SSO, questa funzionalità è utile nelle grandi aziende che utilizzano un singolo provider di identità per autenticare un'intera organizzazione con più sottodomini. L'emittente del dominio specifico determina il sottodominio da associare alla richiesta. Per ulteriori informazioni, consulta Come funziona l'elemento Issuer nella richiesta SAML work?
Se la richiesta non va a buon fine per qualche motivo, viene restituito un codice di stato diverso. Per ulteriori informazioni sui codici di stato dell'API di dati Google, consulta Codici di stato HTTP.
Aggiornare le impostazioni Single Sign-On
Per aggiornare le impostazioni SSO di un dominio, recupera prima le impostazioni SSO utilizzando l'
operazione Recupera impostazioni Single Sign-On,
modificala e poi invia una richiesta PUT all'URL del feed SSO. Assicurati che il <id>
valore nella voce aggiornata corrisponda esattamente all'elemento <id> della voce esistente.
Includi un'intestazione Authorization come descritto in Autenticarsi al
servizio dell'API Admin Settings. Per i messaggi di errore,
consulta Risoluzione dei problemi relativi a SSO.
Quando aggiorni le impostazioni Single Sign-On, invia una richiesta HTTP PUT all'URL del feed generale SSO:
https://apps-apis.google.com/a/feeds/domain/2.0/{domainName}/sso/general
Il corpo XML della richiesta PUT è:
<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>
Una risposta riuscita restituisce un codice di stato HTTP 200 OK, insieme a un feed AtomPub con le impostazioni SSO.
L'XML della risposta PUT è:
<?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>
Se la richiesta non va a buon fine per qualche motivo, viene restituito un codice di stato diverso. Per ulteriori informazioni sui codici di stato dell'API di dati Google, consulta Codici di stato HTTP.
Le modifiche alle impostazioni Single Sign-On non sono consentite quando il cliente di destinazione ha
attivato l'approvazione da più parti per le azioni sensibili. Le richieste non andranno a buon fine con
errorCode="1811" e
reason="LegacyInboundSsoChangeNotAllowedWithMultiPartyApproval".
Recuperare la chiave di firma Single Sign-On
Per recuperare la chiave di firma Single Sign-On, invia una richiesta HTTP GET all'URL del feed della chiave di firma SSO
e includi un'intestazione Authorization come descritto in
Autenticarsi al servizio Admin Settings. Per i messaggi di errore,
consulta Risoluzione dei problemi relativi a SSO:
https://apps-apis.google.com/a/feeds/domain/2.0/{domainName}/sso/signingkey
Questa operazione non ha parametri nel corpo della richiesta.
Una risposta riuscita restituisce un codice di stato HTTP 200 OK, insieme a un feed AtomPub con la chiave di firma.
L'XML della risposta GET restituisce la proprietà 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>
Se la richiesta non va a buon fine per qualche motivo, viene restituito un codice di stato diverso. Per ulteriori informazioni sui codici di stato dell'API di dati Google, consulta Codici di stato HTTP.
Aggiornare la chiave di firma Single Sign-On
Per aggiornare la chiave di firma SSO di un dominio, recupera prima la chiave di firma utilizzando l'
operazione Recupera chiave di firma Single Sign-On
, modificala e poi invia una richiesta PUT all'
URL del feed della chiave di firma SSO. Assicurati che il valore <id> nella voce aggiornata corrisponda esattamente al
<id> della voce esistente. Per ulteriori informazioni sulle chiavi di firma Single
Sign-On basate su SAML, consulta Generare chiavi e certificati per il servizio Single Sign-On di Google Workspace.
Quando aggiorni la chiave di firma Single Sign-On, invia una richiesta HTTP PUT all'URL del feed della chiave di firma SSO:
https://apps-apis.google.com/a/feeds/domain/2.0/{domainName}/sso/signingkey
L'XML della richiesta PUT è:
<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>
Le modifiche alle impostazioni Single Sign-On non sono consentite quando il cliente di destinazione ha
attivato l'approvazione da più parti per le azioni sensibili. Le richieste non andranno a buon fine con
errorCode="1811" e
reason="LegacyInboundSsoChangeNotAllowedWithMultiPartyApproval".
Gestire il gateway email
La sezione relativa al gateway della posta in uscita mostra come l'API Admin Settings supporta il routing in uscita della posta degli utenti nel tuo dominio.
Recuperare le impostazioni del gateway della posta in uscita
Per recuperare le impostazioni del gateway della posta in uscita, invia una richiesta HTTP GET all'URL del feed del gateway
e includi un'intestazione Authorization come descritto in Autenticarsi
al servizio Admin Settings:
https://apps-apis.google.com/a/feeds/domain/2.0/{domainName}/email/gateway
Questa operazione non ha parametri nel corpo della richiesta.
Una risposta riuscita restituisce un codice di stato HTTP 200 OK, insieme a un feed AtomPub con le informazioni sullo stato del gateway email.
La risposta GET restituisce le proprietà smartHost e smtpMode. Per ulteriori
informazioni su queste proprietà, consulta Aggiornare le impostazioni del gateway della posta in uscita
settings.
Ecco un esempio di una possibile risposta:
<?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>
Se la richiesta non va a buon fine per qualche motivo, viene restituito un codice di stato diverso. Per ulteriori informazioni sui codici di stato dell'API di dati Google, consulta Codici di stato HTTP.
Aggiornare le impostazioni del gateway della posta in uscita
Per aggiornare l'impostazione del gateway della posta in uscita di un dominio, invia una richiesta HTTP PUT all'URL del feed del gateway:
https://apps-apis.google.com/a/feeds/domain/2.0/{domainName}/email/gateway
L'XML della richiesta PUT è:
<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>
Le proprietà della richiesta sono:
- smartHost
- L'indirizzo IP o il nome host del server SMTP. Google Workspace instrada la posta in uscita a questo server.
- smtpMode
- Il valore predefinito è SMTP. Un altro valore, SMTP_TLS, protegge una connessione con TLS durante il recapito del messaggio.
Una risposta riuscita restituisce un codice di stato HTTP 200 OK, insieme al feed AtomPub con lo stato delle impostazioni del gateway email.
Se la richiesta non va a buon fine per qualche motivo, viene restituito un codice di stato diverso. Per ulteriori informazioni sui codici di stato dell'API di dati Google, consulta Codici di stato HTTP.
Endpoint ritirati il 31 ottobre 2018
Nell'ambito di questo annuncio, abbiamo ritirato i seguenti endpoint. Sono stati ritirati il 31 ottobre 2018 e non sono più disponibili.
https://apps-apis.google.com/a/feeds/domain/2.0/{domainName}/general/defaultLanguagehttps://apps-apis.google.com/a/feeds/domain/2.0/{domainName}/general/organizationNamehttps://apps-apis.google.com/a/feeds/domain/2.0/{domainName}/general/currentNumberOfUsershttps://apps-apis.google.com/a/feeds/domain/2.0/{domainName}/general/maximumNumberOfUsershttps://apps-apis.google.com/a/feeds/domain/2.0/{domainName}/accountInformation/supportPINhttps://apps-apis.google.com/a/feeds/domain/2.0/{domainName}/accountInformation/customerPINhttps://apps-apis.google.com/a/feeds/domain/2.0/{domainName}/accountInformation/adminSecondaryEmailhttps://apps-apis.google.com/a/feeds/domain/2.0/{domainName}/accountInformation/editionhttps://apps-apis.google.com/a/feeds/domain/2.0/{domainName}/accountInformation/creationTimehttps://apps-apis.google.com/a/feeds/domain/2.0/{domainName}/accountInformation/countryCodehttps://apps-apis.google.com/a/feeds/domain/2.0/{domainName}/appearance/customLogohttps://apps-apis.google.com/a/feeds/domain/2.0/{domainName}/verification/mx