API настроек администратора позволяет администраторам доменов Google Workspace получать и изменять настройки своих доменов в форме фидов API данных Google.
Эти настройки домена включают многие функции, доступные в консоли администратора Google Workspace . Примеры использования этого API включают создание пользовательской панели управления или интеграцию доменов Google Workspace в существующую устаревшую среду.
API настроек администратора реализует протокол Google Data API . Google Data API соответствует модели публикации и редактирования Atom Publishing Protocol (AtomPub). HTTP-запросы AtomPub используют подход к проектированию передачи репрезентативных наборов (RESTful) для веб-служб. Дополнительную информацию см. в Руководстве разработчика данных Google .
Аудитория
Этот документ предназначен для разработчиков, которые хотят писать клиентские приложения, которые могут изменять и получать информацию о доменах Google Workspace. В нем приведены примеры основных взаимодействий с API параметров администратора с использованием необработанного XML и HTTP.
В этом документе предполагается, что вы понимаете общие принципы протокола Google Data API и знакомы с консолью администратора Google Workspace. Дополнительные сведения о консоли администратора см. в статье Использование консоли администратора .
Начиная
Создание учетной записи
API настроек администратора включен для учетных записей Google Workspace. Зарегистрируйте учетную запись Google Workspace для целей тестирования. Служба настроек администратора использует учетные записи Google , поэтому, если у вас уже есть учетная запись в домене Google Workspace, все готово.
О типах каналов API настроек администратора
API настроек администратора позволяет управлять следующими категориями настроек домена:
- Настройки единого входа
Система единого входа (SSO) на основе SAML позволяет пользователям использовать один и тот же логин и пароль как для служб, размещенных в Google Workspace, так и для других служб, которые могут размещаться в вашей организации. В частности, при использовании системы единого входа размещенное веб-приложение, такое как Google Workspace, перенаправляет пользователей к поставщику удостоверений вашей организации для аутентификации пользователей при входе в систему. Подробную информацию см. в разделе Общие сведения о системе единого входа на основе SAML для Google Workspace .
Настройка SSO включает в себя ввод необходимой информации для службы Google Workspace для связи с поставщиком удостоверений, который хранит регистрационную информацию ваших пользователей, а также настройку ссылок, по которым пользователи должны отправляться для входа в систему, выхода из системы и для изменения своих паролей. . API настроек администратора позволяет программно обновлять и извлекать эти настройки. Google использует сгенерированный вами открытый ключ, чтобы проверить этот запрос единого входа у вашего поставщика удостоверений и убедиться, что ответ SAML с закрытым ключом не был изменен во время передачи по сети.
Чтобы получить краткий обзор использования настроек единого входа для конкретного API, получите сертификат открытого ключа у поставщика удостоверений, зарегистрируйте открытый ключ в Google и настройте параметры запроса единого входа на основе SAML. Сообщения об ошибках см. в разделе Устранение неполадок единого входа :- Создайте свои ключи. С помощью поставщика удостоверений создайте набор открытых и закрытых ключей, используя алгоритмы DSA или RSA. Открытый ключ находится в сертификате в формате X.509. Дополнительные сведения о ключах подписи единого входа на основе SAML см. в разделе Создание ключей и сертификатов для службы единого входа Google Workspace .
- Зарегистрируйтесь в Google. Используйте настройки единого входа API настроек администратора, чтобы зарегистрировать сертификат открытого ключа в Google.
- Настройте параметры единого входа. Используйте параметры единого входа API настроек администратора, чтобы настроить параметры, используемые для связи с серверами поставщика удостоверений домена.
- Настройки шлюза и маршрутизации
Этот фид позволяет администраторам доменов управлять маршрутизацией электронной почты для своих доменов.
Операции маршрутизации электронной почты позволяют администраторам указывать параметры маршрутизации электронной почты на уровне домена. Это похоже на функцию маршрутизации электронной почты в настройках Gmail в консоли администратора. Дополнительные сведения см. в разделе Маршрутизация электронной почты и конфигурация двойной доставки функции маршрутизации электронной почты .
Пример XML-запроса и ответа API настроек администратора
В этом документе представлены примеры кода базовых запросов и ответов API настроек администратора с использованием необработанного XML и HTTP. В этом примере языка домена по умолчанию показан полный синтаксис XML и HTTP для тела запроса и ответа, который является общим для каждой операции:
Чтобы изменить настройку шлюза исходящей почты домена, отправьте HTTP PUT на URL фида шлюза:
https://apps-apis.google.com/a/feeds/domain/2.0/{domainName}/email/gateway
XML-код entry запроса PUT AtomPub для домена по умолчанию:
<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>
За исключением свойств и значений, связанных с операцией, элементы atom:property представляют собой одну пару ключ-значение, содержащую информацию о свойстве, которое вы хотите получить или обновить. Они являются общими для всех тел запросов API настроек администратора.
Элемент entry ответа на языке домена по умолчанию возвращает свойства smartHost и smtpMode вместе с синтаксисом XML, общим для всех тел ответов API настроек администратора:
<?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>
Управление настройками единого входа
Функция единого входа Google Workspace (SSO) позволяет пользователям входить в несколько служб, введя логин и пароль только один раз. Этот пароль хранится у поставщика удостоверений домена, а не в Google Workspace. Дополнительные сведения см. на странице системы единого входа в Справочном центре . В следующих разделах демонстрируется формат XML, используемый для параметров единого входа.
Получение настроек единого входа
Чтобы получить настройки единого входа, отправьте запрос HTTP GET на общий URL-адрес канала единого входа и включите заголовок Authorization , как описано в разделе Аутентификация в службе настроек администратора . Сообщения об ошибках см. в разделе Устранение неполадок системы единого входа :
https://apps-apis.google.com/a/feeds/domain/2.0/{domainName}/sso/general
Эта операция не имеет параметров в теле запроса.
Успешный ответ возвращает код состояния HTTP 200 OK , а также фид AtomPub с настройками SSO домена.
XML-код ответа GET возвращает samlSignonUri , samlLogoutUri , changePasswordUri , enableSSO , ssoWhitelist и 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>
Свойства включают в себя:
- samlSignonUri
- URL-адрес поставщика удостоверений, на который Google Workspace отправляет запрос SAML для аутентификации пользователя.
- samlLogoutUri
- Адрес, на который будут отправляться пользователи при выходе из веб-приложения.
- changePasswordUri
- Адрес, на который будут отправлены пользователи, когда они захотят изменить свой пароль единого входа для веб-приложения.
- включитьSSO
- Включает SSO на основе SAML для этого домена. Если вы предварительно настроили параметры единого входа и впоследствии установили для параметра
enableSSOзначениеenableSSO=false, введенные вами ранее параметры сохраняются. - ssoБелый список
- ssoWhitelist — это IP-адрес сетевой маски в формате бесклассовой междоменной маршрутизации (CIDR). ssoWhitelist определяет, какие пользователи входят в систему с помощью системы единого входа, а какие — с помощью страницы аутентификации учетной записи Google Workspace. Если маски не указаны, все пользователи будут входить в систему с помощью SSO. Дополнительные сведения см. в разделе Как работают маски сети .
- useDomainSpecificIssuer
- В запросе SAML к поставщику удостоверений можно использовать издателя, специфичного для домена. Хотя это и не требуется для большинства развертываний SSO, эта функция полезна в крупных компаниях, использующих одного поставщика удостоверений для аутентификации всей организации с несколькими поддоменами. Предоставление конкретного эмитента домена определяет, какой поддомен связать с запросом. Дополнительные сведения см. в разделе Как работает элемент Issuer в запросе SAML?
Если ваш запрос по какой-либо причине не выполняется, возвращается другой код состояния. Дополнительные сведения о кодах состояния API данных Google см. в разделе Коды состояния HTTP .
Обновление настроек единого входа
Чтобы обновить параметры единого входа домена, сначала получите параметры единого входа с помощью операции получения параметров единого входа , измените их, а затем отправьте запрос PUT на URL-адрес канала единого входа. Убедитесь, что значение <id> в обновленной записи точно соответствует <id> существующей записи. Включите заголовок Authorization , как описано в разделе Аутентификация в службе API настроек администратора . Сообщения об ошибках см. в разделе Устранение неполадок единого входа .
При обновлении настроек единого входа отправьте HTTP PUT на общий URL-адрес канала единого входа:
https://apps-apis.google.com/a/feeds/domain/2.0/{domainName}/sso/general
Тело XML запроса 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>
Успешный ответ возвращает код состояния HTTP 200 OK вместе с каналом AtomPub с настройками единого входа.
XML-код ответа 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>
Если ваш запрос по какой-либо причине не выполняется, возвращается другой код состояния. Дополнительные сведения о кодах состояния API данных Google см. в разделе Коды состояния HTTP .
Получение ключа подписи единого входа
Чтобы получить ключ подписи единого входа, отправьте запрос HTTP GET на URL-адрес фида ключей подписи единого входа и включите заголовок Authorization , как описано в разделе Аутентификация в службе настроек администратора . Сообщения об ошибках см. в разделе Устранение неполадок системы единого входа :
https://apps-apis.google.com/a/feeds/domain/2.0/{domainName}/sso/signingkey
Эта операция не имеет параметров в теле запроса.
Успешный ответ возвращает код состояния HTTP 200 OK вместе с каналом AtomPub с ключом подписи.
XML-ответ GET возвращает свойство 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>
Если ваш запрос по какой-либо причине не выполняется, возвращается другой код состояния. Дополнительные сведения о кодах состояния API данных Google см. в разделе Коды состояния HTTP .
Обновление ключа подписи единого входа
Чтобы обновить ключ подписи SSO домена, сначала получите ключ подписи с помощью операции Получение ключа подписи единого входа , измените его, а затем отправьте запрос PUT на URL-адрес фида ключа подписи единого входа. Убедитесь, что значение <id> в обновленной записи точно соответствует <id> существующей записи. Дополнительные сведения о ключах подписи единого входа на основе SAML см. в разделе Создание ключей и сертификатов для службы единого входа Google Workspace .
При обновлении ключа подписи единого входа отправьте HTTP PUT на URL-адрес фида ключей подписи единого входа:
https://apps-apis.google.com/a/feeds/domain/2.0/{domainName}/sso/signingkey
XML-код запроса 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>
Управление шлюзом электронной почты и маршрутизацией
В разделе шлюза исходящей почты показано, как API настроек администратора поддерживает маршрутизацию исходящей почты от пользователей в вашем домене. В разделе маршрутизации электронной почты показано, как перенаправлять сообщения на другой почтовый сервер.
Получение настроек шлюза исходящей почты
Чтобы получить настройки шлюза исходящей электронной почты, отправьте HTTP GET на URL-адрес фида шлюза и включите заголовок Authorization , как описано в разделе Аутентификация в службе настроек администратора :
https://apps-apis.google.com/a/feeds/domain/2.0/{domainName}/email/gateway
Эта операция не имеет параметров в теле запроса.
Успешный ответ возвращает код состояния HTTP 200 OK, а также фид AtomPub с информацией о состоянии шлюза электронной почты.
Ответ GET возвращает свойства smartHost и smtpMode . Дополнительные сведения об этих свойствах см. в разделе Обновление параметров шлюза исходящей электронной почты .
Пример возможного ответа:
<?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>
Если ваш запрос по какой-либо причине не выполняется, возвращается другой код состояния. Дополнительные сведения о кодах состояния API данных Google см. в разделе Коды состояния HTTP .
Обновление настроек шлюза исходящей почты
Чтобы обновить настройки шлюза исходящей электронной почты домена, отправьте HTTP-запрос PUT на URL-адрес фида шлюза:
https://apps-apis.google.com/a/feeds/domain/2.0/{domainName}/email/gateway
XML-код запроса 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>
Свойства запроса:
- умный хост
- Либо IP-адрес, либо имя хоста вашего SMTP-сервера. Google Workspace направляет исходящую почту на этот сервер.
- smtpMode
- Значение по умолчанию — SMTP. Другое значение, SMTP_TLS, защищает соединение с помощью TLS при доставке сообщения.
Успешный ответ возвращает код состояния HTTP 200 OK вместе с лентой AtomPub со статусом настроек шлюза электронной почты.
Если ваш запрос по какой-либо причине не выполняется, возвращается другой код состояния. Дополнительные сведения о кодах состояния API данных Google см. в разделе Коды состояния HTTP .
Управление настройками маршрутизации электронной почты
Сначала создайте 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>
Свойства запроса:
- маршрутПункт назначения
- Это место назначения — имя хоста или IP-адрес почтового сервера SMTP-In, на который направляется электронная почта. Имя хоста или IP-адрес должны разрешаться для Google. Дополнительные сведения о разрешении имен почтовых хостов см. в статье Пилотная версия Google Workspace с маршрутизацией электронной почты .
- маршрутRewriteTo
- Если значение равно true, поле SMTP-конверта сообщения
to:заменяется на имя хоста назначения (имя хоста user@destination), и сообщение доставляется на этот адрес пользователя на почтовом сервере назначения. Еслиfalse, электронное письмо доставляется на адрес исходного сообщенияto:адрес электронной почты (user@original hostname) на целевом почтовом сервере. Это похоже на параметр «Изменить конверт SMTP» в консоли администратора. Дополнительные сведения см. в разделе Настройки домена для маршрутизации электронной почты . - маршрут включен
- Если
true, функция маршрутизации электронной почты включена. Еслиfalse, функция отключена. - bounceУведомления
- Если задано значение
true, Google Workspace может отправлять уведомления о возврате отправителю в случае сбоя доставки. - учетная обработка
Этот параметр определяет, как маршрутизация электронной почты влияет на разные типы пользователей в домене:
-
allAccounts— доставлять всю электронную почту в это место назначения. -
provisionedAccounts– доставлять почту по этому адресу, если пользователь существует в Google Workspace. -
unknownAccounts– доставлять почту по этому адресу, если пользователь не существует в Google Workspace. Это похоже на настройку "Доставка электронной почты для" в консоли администратора. Дополнительные сведения о предварительных требованиях и использовании маршрутизации почты см. в разделе Параметры домена для маршрутизации электронной почты . ~ Чтобы опубликовать этот запрос, отправьте HTTPPOSTна URL-адрес канала маршрутизации электронной почты и включите заголовокAuthorization, как описано в разделе Аутентификация в службе настроек администратора :
https://apps-apis.google.com/a/feeds/domain/2.0/{domainName}/emailrouting
-
Успешный ответ возвращает код состояния HTTP 200 OK вместе с каналом AtomPub с информацией об архиве.
Если ваш запрос по какой-либо причине не выполняется, возвращается другой код состояния. Дополнительные сведения о кодах состояния API данных Google см. в разделе Коды состояния HTTP .
Конечные точки закрываются 31 октября 2018 г.
В рамках этого объявления мы объявили устаревшими следующие конечные точки. Они были закрыты 31 октября 2018 года и больше не доступны.
- 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