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 API di dati di 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 di Google. L'API di dati di Google è conforme al modello di pubblicazione e modifica Atom Publishing Protocol (AtomPub). Le richieste HTTP AtomPub utilizzano l'approccio di progettazione RESTful (Representational Set Transfer) ai servizi web. Per ulteriori informazioni, consulta la Guida per gli sviluppatori di dati di Google.

Pubblico

Questo documento è destinato agli sviluppatori che desiderano scrivere applicazioni client in grado di modificare e recuperare informazioni sui domini Google Workspace. Offre esempi di interazioni di base dell'API Admin Settings che utilizzano XML e HTTP non elaborati.

Questo documento presuppone che tu comprenda le idee generali alla base del protocollo dell'API di dati di Google e che tu conosca la Console di amministrazione di Google Workspace. Per ulteriori informazioni sulla Console di amministrazione, vedi Utilizzare la Console di amministrazione.

Per iniziare

Creare un account

L'API Admin Settings è abilitata per gli account Google Workspace. Registrati per creare un account Google Workspace a scopo di test. Il servizio Impostazioni amministratore utilizza 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 servizio Single Sign-On (SSO) basato su SAML consente agli utenti di utilizzare lo stesso accesso e la stessa password sia per i servizi in hosting di Google Workspace sia per altri servizi che potresti ospitare all'interno della tua organizzazione. Nello specifico, 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, vedi Informazioni sul servizio SSO basato su SAML per Google Workspace.

La configurazione del servizio SSO prevede l'inserimento delle informazioni necessarie affinché il servizio Google Workspace comunichi con il provider di identità che archivia le informazioni di accesso degli utenti, nonché la configurazione dei link a cui gli utenti devono essere indirizzati per l'accesso, la disconnessione e la modifica delle 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 provider di identità, registra la chiave pubblica con Google e configura le impostazioni delle query SSO basate su SAML. Per i messaggi di errore, consulta la sezione Risoluzione dei 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 è contenuta in un certificato in formato X.509. Per saperne di più sulle chiavi di firma Single Sign-On basate su SAML, vedi Generare chiavi e certificati per il servizio Single Sign-On di Google Workspace.
  • Registrati su Google: utilizza le impostazioni Single Sign-On dell'API Admin Settings per registrare il tuo certificato di chiave pubblica su Google.
  • Configurazione delle 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 propri domini.

Le operazioni di routing dell'email consentono agli amministratori di specificare le impostazioni di routing della posta a livello di dominio. La funzionalità di routing dell'email è simile a quella delle impostazioni di Gmail nella Console di amministrazione. Per ulteriori informazioni, vedi Routing della posta 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 dell'API Admin Settings di base che utilizzano XML e HTTP non elaborati. Questo esempio di lingua predefinita del dominio mostra la sintassi completa XML e HTTP per il corpo di una voce di richiesta e risposta, comune a ciascuna operazione:

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

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

La lingua predefinita del dominio PUT richiesta AtomPub entry XML è:

<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>

Fatta eccezione per le proprietà e i 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 di risposta alla 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>

Gestione delle impostazioni Single Sign-On

La funzionalità Single Sign-On (SSO) di Google Workspace consente agli utenti di accedere a più servizi senza dover inserire i dati di accesso e la password una sola volta. Questa password viene memorizzata dal provider di identità del dominio, non da Google Workspace. Per ulteriori informazioni, visita la pagina del Centro assistenza relativa al servizio SSO. Nelle seguenti sezioni viene illustrato il formato XML utilizzato per le impostazioni Single Sign-On.

Recupero delle impostazioni Single Sign-On

Per recuperare le impostazioni Single Sign-On, invia un elemento GET HTTP all'URL del feed generale SSO e includi un'intestazione Authorization come descritto in Autenticazione nel servizio Impostazioni di amministrazione. Per i messaggi di errore, vedi 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 corretta restituisce un codice di stato HTTP 200 OK, insieme a un feed AtomPub con le impostazioni SSO del dominio.

Il file 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:

MiniSignonUri
L'URL del provider di identità a cui Google Workspace invia la richiesta SAML per l'autenticazione degli utenti.
MiniLogoutUri
L'indirizzo a cui verranno inviati gli utenti quando escono dall'applicazione web.
cambioPasswordUri
L'indirizzo a cui verranno inviati gli utenti quando vorranno cambiare la password SSO per l'applicazione web.
abilitaSSO
Abilita il servizio SSO basato su SAML per questo dominio. Se in precedenza hai configurato le impostazioni SSO e successivamente hai impostato enableSSO su enableSSO=false, le impostazioni immesse in precedenza rimangono salvate.
ssoWhitelist
Uno ssoWhitelist è un indirizzo IP 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 viene specificata alcuna maschera, tutti gli utenti accederanno utilizzando SSO. Per saperne di più, consulta l'articolo Come funzionano le maschere di rete.
useDomainSpecificIssuer
È possibile utilizzare un'autorità emittente specifica per il dominio nella richiesta SAML inviata 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. Se assegni all'autorità di emissione del dominio specifico, determina quale sottodominio associare alla richiesta. Per saperne di più, vedi Come funziona l'elemento Issuer nella richiesta SAML?

Se per qualche motivo la richiesta non va a buon fine, viene restituito un codice di stato diverso. Per ulteriori informazioni sui codici di stato dell'API di dati di Google, consulta la sezione Codici di stato HTTP.

Aggiornamento delle impostazioni Single Sign-On

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

Quando aggiorni le impostazioni Single Sign-On, invia un PUT HTTP 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 corretta 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 per qualche motivo la richiesta non va a buon fine, viene restituito un codice di stato diverso. Per ulteriori informazioni sui codici di stato dell'API di dati di Google, consulta la sezione Codici di stato HTTP.

Recupero della chiave di firma Single Sign-On

Per recuperare la chiave di firma Single Sign-On, invia un elemento GET HTTP all'URL del feed della chiave di firma SSO e includi un'intestazione Authorization, come descritto in Autenticazione nel servizio Impostazioni di amministrazione. Per i messaggi di errore, vedi 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 corretta restituisce un codice di stato HTTP 200 OK, insieme a un feed AtomPub con la chiave di firma.

Il file 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 per qualche motivo la richiesta non va a buon fine, viene restituito un codice di stato diverso. Per ulteriori informazioni sui codici di stato dell'API di dati di Google, consulta la sezione Codici di stato HTTP.

Aggiornamento della chiave di firma Single Sign-On

Per aggiornare la chiave di firma SSO di un dominio, recupera innanzitutto la chiave di firma utilizzando l'operazione di recupero della chiave di firma Single Sign-On, modificala, quindi invia una richiesta PUT all'URL del feed della chiave di firma SSO. Assicurati che il valore <id> nella voce aggiornata corrisponda esattamente al valore <id> della voce esistente. Per saperne di più sulle chiavi di firma Single Sign-On basate su SAML, vedi Generare chiavi e certificati per il servizio Single Sign-On di Google Workspace.

Quando aggiorni la chiave di firma Single Sign-On, invia un PUT HTTP 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>

Gestione del gateway e del routing dell'email

La sezione relativa al gateway della posta in uscita mostra in che modo l'API Admin Settings supporta il routing in uscita della posta inviata dagli utenti del dominio. La sezione relativa al routing dell'email mostra come eseguire il routing dei messaggi a un altro server di posta.

Recupero delle impostazioni del gateway di posta in uscita

Per recuperare le impostazioni del gateway della posta in uscita, invia un GET HTTP all'URL del feed del gateway e includi un'intestazione Authorization come descritto in Autenticazione nel servizio Impostazioni di amministrazione:

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à, vedi Aggiornamento delle impostazioni del gateway di posta in uscita.

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 per qualche motivo la richiesta non va a buon fine, viene restituito un codice di stato diverso. Per ulteriori informazioni sui codici di stato dell'API di dati di Google, consulta la sezione Codici di stato HTTP.

Aggiornamento delle impostazioni del gateway di posta 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 indirizza la posta in uscita a questo server.
smtpMode
Il valore predefinito è SMTP. Un altro valore, SMTP_TLS, protegge una connessione con TLS durante la consegna del messaggio.

Una risposta corretta restituisce un codice di stato HTTP 200 OK, insieme al feed AtomPub con lo stato delle impostazioni del gateway email.

Se per qualche motivo la richiesta non va a buon fine, viene restituito un codice di stato diverso. Per ulteriori informazioni sui codici di stato dell'API di dati di Google, consulta la sezione Codici di stato HTTP.

Gestione delle impostazioni di routing dell'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
La destinazione è il nome host o l'indirizzo IP del server di posta SMTP-In a cui viene indirizzato l'email. Il nome host o l'indirizzo IP deve essere risolto per Google. Per maggiori dettagli su come risolvere i nomi host di posta, vedi Eseguire un progetto pilota di Google Workspace con routing dell'email.
routeRewriteTo
Se il valore è true, il campo to: della busta SMTP del messaggio viene modificato nel nome host di destinazione (utente@nome host della destinazione) 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 (utente@nome host originale) sul server di posta di destinazione. È simile all'impostazione "Modifica la busta SMTP" nella Console di amministrazione. Per saperne di più, vedi Impostazioni del dominio per il routing della posta.
routeEnabled
Se true, la funzionalità di routing dell'email è attivata. Se false, la funzionalità è disattivata.
Restituire notifiche
Se true, Google Workspace è abilitato all'invio di notifiche di mancato recapito al mittente quando un recapito non va a buon fine.
Gestione account

Questa impostazione determina in che modo il routing dell'email influisce sui diversi tipi di utenti del dominio:

  • allAccounts -- Recapita tutte le email a questa destinazione.
  • provisionedAccounts: recapita la posta a questa destinazione se l'utente esiste in Google Workspace.
  • unknownAccounts: recapita la posta a questa destinazione se l'utente non esiste in Google Workspace. Si tratta di un'impostazione simile all'opzione "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 della posta. ~ Per pubblicare questa richiesta, invia un elemento POST HTTP all'URL del feed di routing delle email e includi un'intestazione Authorization, come descritto in Autenticazione nel servizio Impostazioni di 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 di archivio.

Se per qualche motivo la richiesta non va a buon fine, viene restituito un codice di stato diverso. Per ulteriori informazioni sui codici di stato dell'API di dati di Google, consulta la sezione Codici di stato HTTP.

Ritiro di Endpoints il 31 ottobre 2018

Nell'ambito di questo annuncio abbiamo ritirato i seguenti endpoint. Erano 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