Panoramica dell'API Admin Settings

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 di Google Workspace. Alcuni 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 precedente esistente.

L'API Admin Settings implementa il protocollo dell'API di dati Google. L'API Google Data è conforme al modello di pubblicazione e modifica di Atom Publishing Protocol (AtomPub). Le richieste HTTP AtomPub utilizzano l'approccio di progettazione Representational Set Transfer (RESTful) per i servizi web. Per ulteriori informazioni, consulta la Guida per gli sviluppatori di Google Data.

Pubblico

Questo documento è rivolto 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 Impostazioni amministratore che utilizzano XML e HTTP non elaborati.

Questo documento presuppone che tu abbia compreso le idee generali alla base del protocollo dell'API Google Data e che tu abbia dimestichezza con la Console di amministrazione Google Workspace. Per ulteriori informazioni sulla Console di amministrazione, vedi Utilizzare la Console di amministrazione.

Per iniziare

Creazione di un account

L'API Admin Settings è attivata per gli account Google Workspace. Registrati per un account Google Workspace a scopo di test. Il servizio Impostazioni amministratore utilizza gli Account Google, 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 le seguenti 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 in Google Workspace sia per altri servizi che potresti ospitare all'interno della tua organizzazione. Nello specifico, quando utilizzi l'accesso SSO, un'applicazione web ospitata, come Google Workspace, reindirizza gli utenti all'identity provider della tua organizzazione per autenticarli quando accedono. Per informazioni dettagliate, vedi Informazioni sull'accesso single sign-on basato su SAML per Google Workspace.

La configurazione dell'accesso single sign-on prevede l'inserimento delle informazioni necessarie per consentire al servizio Google Workspace di comunicare con l'identity provider che memorizza i dati di accesso degli utenti, nonché la configurazione dei link a cui devono essere indirizzati gli utenti per accedere, uscire e modificare le password. L'API Admin Settings ti 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, ottieni il certificato della 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 la sezione Risolvere i problemi relativi al servizio 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 si trova 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 su Google: utilizza le impostazioni di accesso singolo dell'API Admin Settings per registrare il tuo certificato della chiave pubblica su 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 di gateway e routing

Questo feed consente agli amministratori di dominio di controllare il routing delle email per i loro domini.

Le operazioni di routing email consentono agli amministratori di specificare le impostazioni di routing email a livello di dominio. Si tratta di una funzionalità simile al routing delle email delle impostazioni di Gmail della Console di amministrazione. Per ulteriori informazioni, vedi Routing delle email e Configurazione della doppia consegna della funzionalità di routing delle email.

Esempio di richiesta e risposta XML dell'API Impostazioni amministratore

Questo documento fornisce esempi di codice di richieste e risposte di base dell'API Impostazioni amministratore che utilizzano 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, che è comune a ogni operazione:

Per modificare l'impostazione del gateway email in uscita del dominio, invia un PUT HTTP all'URL del feed del gateway:

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

Il codice XML AtomPub PUT della richiesta PUT della lingua predefinita del dominio è:entry

<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 campi sono comuni a tutti i campi delle richieste dell'API Admin Settings.

L'elemento di risposta della lingua predefinita del dominio entry restituisce le proprietà smartHost e smtpMode insieme alla sintassi XML comune a tutti i corpi di risposta 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>

Gestione delle impostazioni di Single Sign-On

La funzionalità Single Sign-On (SSO) di Google Workspace consente agli utenti di accedere a più servizi inserendo nome utente e password una sola volta. Questa password viene archiviata 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 del Single Sign-On.

Recupero delle impostazioni di Single Sign-On

Per recuperare le impostazioni del Single Sign-On, invia un GET HTTP all'URL del feed generale SSO e includi un'intestazione Authorization come descritto in Autenticazione al servizio Impostazioni amministratore. Per i messaggi di errore, consulta la sezione Risoluzione dei problemi relativi al servizio 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.

Il codice 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 dell'utente.
samlLogoutUri
L'indirizzo a cui verranno indirizzati gli utenti quando escono dall'applicazione web.
changePasswordUri
L'indirizzo a cui verranno indirizzati gli utenti quando vogliono modificare la password SSO per l'applicazione web.
enableSSO
Attiva il servizio SSO basato su SAML per questo dominio. Se hai configurato in precedenza le impostazioni SSO e in seguito hai impostato enableSSO su enableSSO=false, le impostazioni inserite in precedenza vengono comunque salvate.
ssoWhitelist
Una ssoWhitelist è un indirizzo IP di una maschera di rete in formato Classless Inter-Domain Routing (CIDR). ssoWhitelist determina quali utenti accedono utilizzando SSO e quali utenti accedono utilizzando la pagina di autenticazione dell'account Google Workspace. Se non sono specificate maschere, tutti gli utenti accederanno utilizzando l'SSO. Per saperne di più, consulta Come funzionano le maschere di rete.
useDomainSpecificIssuer
Un emittente specifico per il dominio può essere utilizzato nella richiesta SAML al provider di identità. Sebbene non sia necessaria per la maggior parte dei deployment SSO, questa funzionalità è utile nelle grandi aziende che utilizzano un unico provider di identità per autenticare un'intera organizzazione con più sottodomini. L'indicazione dell'emittente del dominio specifico determina quale sottodominio associare alla richiesta. Per saperne di più, vedi Come funziona l'elemento Issuer nella richiesta SAML?

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 Google Data, consulta Codici di stato HTTP.

Aggiornamento delle impostazioni di Single Sign-On

Per aggiornare le impostazioni SSO di un dominio, recuperale innanzitutto utilizzando l'operazione Recupero delle impostazioni del Single Sign-On, modificale e poi invia una richiesta PUT all'URL del feed SSO. Assicurati che il valore <id> nella voce aggiornata corrisponda esattamente a <id> della voce esistente. Includi un'intestazione Authorization come descritto in Autenticazione al servizio API Admin Settings. Per i messaggi di errore, consulta la sezione Risoluzione dei problemi relativi all'accessoSSO.

Quando aggiorni le impostazioni del 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.

Il codice 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 Google Data, consulta Codici di stato HTTP.

Le modifiche alle impostazioni del Single Sign-On non sono consentite se 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".

Recupero della chiave di firma di Single Sign-On

Per recuperare la chiave di firma del Single Sign-On, invia un GET HTTP all'URL del feed della chiave di firma SSO e includi un'intestazione Authorization come descritto in Autenticazione al servizio Impostazioni amministrazione. Per i messaggi di errore, consulta la sezione Risoluzione dei problemi relativi al servizio 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.

Il codice 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 Google Data, consulta Codici di stato HTTP.

Aggiornamento della chiave di firma di Single Sign-On

Per aggiornare la chiave di firma SSO di un dominio, recupera prima la chiave di firma utilizzando l'operazione Recupero della 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 a <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 un messaggio HTTP PUT all'URL del feed della chiave di firma SSO:

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

Il codice 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 del Single Sign-On non sono consentite se 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".

Gestione del gateway email e del routing

La sezione sul gateway email in uscita mostra in che modo l'API Admin Settings supporta il routing in uscita della posta dagli utenti del tuo dominio. La sezione relativa all'indirizzamento email mostra come inoltrare i messaggi a un altro server di posta.

Recupero delle impostazioni del gateway email in uscita

Per recuperare le impostazioni del gateway email in uscita, invia un GET HTTP all'URL del feed del gateway e includi un'intestazione Authorization come descritto in Autenticazione al servizio Impostazioni amministratore:

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

Questa operazione non ha parametri nel corpo della richiesta.

Una risposta corretta 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 email in uscita.

Un esempio di 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 Google Data, consulta Codici di stato HTTP.

Aggiornamento delle impostazioni del gateway email in uscita

Per aggiornare l'impostazione del gateway email 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

Il codice 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 inoltra la posta in uscita a questo server.
smtpMode
Il valore predefinito è SMTP. Un altro valore, SMTP_TLS, protegge una connessione con TLS durante l'invio del messaggio.

Una risposta positiva 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 Google Data, consulta Codici di stato HTTP.

Gestione delle impostazioni di routing delle email

Innanzitutto, crea una richiesta 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>

Le proprietà della richiesta sono:

routeDestination
Questa destinazione è il nome host o l'indirizzo IP del server di posta SMTP-In a cui viene inoltrata l'email. Il nome host o l'indirizzo IP deve essere risolto per Google. Per maggiori dettagli sulla risoluzione dei nomi host della posta, vedi Eseguire il progetto pilota di Google Workspace con il routing delle email.
routeRewriteTo
Se true, il campo to: dell'involucro SMTP del messaggio viene modificato in base all'hostname di destinazione (hostname di user@destination) e il messaggio viene recapitato a questo indirizzo utente sul server di posta di destinazione. Se false, l'email viene recapitata all'indirizzo email to: del messaggio originale (user@nome host originale) sul server di posta di destinazione. Questa impostazione è simile a "Modifica intestazione SMTP" della Console di amministrazione. Per ulteriori informazioni, vedi Impostazioni del dominio per il routing delle email.
routeEnabled
Se true, la funzionalità di routing delle email è attivata. Se false, la funzionalità è disattivata.
bounceNotifications
Se true, Google Workspace è abilitato a inviare notifiche di ritorno al mittente quando l'invio non va a buon fine.
accountHandling

Questa impostazione determina in che modo i diversi tipi di utenti del dominio sono interessati dal routing delle email:

  • allAccounts: invia tutte le email a questa destinazione.
  • provisionedAccounts: invia la posta a questa destinazione se l'utente esiste in Google Workspace.
  • unknownAccounts: invia la posta a questa destinazione se l'utente non esiste in Google Workspace. È simile all'impostazione "Indirizzo email di recapito per" della Console di amministrazione. Per ulteriori informazioni sui prerequisiti e su come utilizzare il routing della posta, vedi Impostazioni del dominio per il routing delle email. ~ Per pubblicare questa richiesta, invia un POST HTTP all'URL del feed di routing delle email e includi un'intestazione Authorization come descritto in Autenticazione al servizio Impostazioni amministrazione:

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

Una risposta corretta restituisce un codice di stato HTTP 200 OK, insieme a un feed AtomPub con le informazioni sull'archivio.

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 Google Data, consulta Codici di stato HTTP.

Ritiro degli endpoint 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/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