Обзор API настроек администратора

API настроек администратора позволяет администраторам доменов Google Workspace получать и изменять настройки своих доменов в виде данных из каналов Google Data API.

Эти настройки домена включают в себя многие функции, доступные в консоли администратора Google Workspace . Примерами использования этого API являются создание пользовательской панели управления или интеграция доменов Google Workspace в существующую устаревшую среду.

API настроек администратора реализует протокол Google Data API . Google Data API соответствует модели публикации и редактирования Atom Publishing Protocol (AtomPub). HTTP-запросы AtomPub используют подход проектирования веб-сервисов на основе Representational Set Transfer (RESTful). Для получения дополнительной информации см. Руководство разработчика Google Data API .

Аудитория

Этот документ предназначен для разработчиков, которые хотят создавать клиентские приложения, способные изменять и получать информацию о доменах Google Workspace. В нем приведены примеры базового взаимодействия с API настроек администратора с использованием необработанного XML и HTTP.

В этом документе предполагается, что вы понимаете общие принципы работы протокола Google Data API и знакомы с консолью администратора Google Workspace. Для получения дополнительной информации о консоли администратора см. раздел «Использование консоли администратора» .

Начать

Для начала использования API настроек администратора необходимо сначала создать свою учетную запись.

Завести аккаунт

API настроек администратора включен для учетных записей Google Workspace. Для тестирования зарегистрируйте учетную запись Google Workspace . Сервис настроек администратора использует учетные записи Google , поэтому, если у вас уже есть учетная запись в домене Google Workspace, все готово.

О типах фидов API в настройках администратора

API настроек администратора позволяет управлять следующими категориями параметров домена:

Настройки единого входа
Единый вход (SSO) на основе SAML позволяет пользователям использовать один и тот же логин и пароль как для размещенных в Google Workspace сервисов, так и для других сервисов, которые могут быть размещены в вашей организации. В частности, при использовании SSO размещенное веб-приложение, такое как Google Workspace, перенаправляет пользователей к поставщику идентификации вашей организации для аутентификации при входе в систему. Для получения подробной информации см. раздел «Понимание единого входа на основе SAML для Google Workspace» .

Настройка единого входа (SSO) включает в себя ввод необходимой информации для связи сервиса Google Workspace с поставщиком идентификации, хранящим данные для входа пользователей, а также настройку ссылок, на которые пользователи должны перенаправляться для входа, выхода и смены паролей. API настроек администратора позволяет программно обновлять и получать эти настройки. Google использует сгенерированный вами открытый ключ для проверки этого запроса SSO с вашим поставщиком идентификации и для подтверждения того, что ответ SAML закрытого ключа не был изменен во время передачи по сети.

Для краткого обзора настроек SSO, специфичных для API, получите сертификат открытого ключа у своего поставщика удостоверений, зарегистрируйте открытый ключ в Google и настройте параметры запросов SSO на основе SAML. Сообщения об ошибках см. в разделе «Устранение неполадок SSO» .

  • Сгенерируйте ключи — с помощью вашего поставщика удостоверений сгенерируйте набор открытых и закрытых ключей, используя алгоритмы DSA или RSA. Открытый ключ находится в сертификате в формате X.509. Для получения дополнительной информации о ключах подписи единого входа на основе SAML см. раздел «Генерация ключей и сертификатов для службы единого входа Google Workspace» .
  • Зарегистрируйтесь в Google — используйте настройки единого входа API Admin Settings для регистрации сертификата открытого ключа в Google.
  • Настройте параметры единого входа (SSO) — используйте параметры единого входа в 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>

Управление настройками единого входа

Функция единого входа (SSO) в Google Workspace позволяет пользователям входить в несколько сервисов, вводя логин и пароль только один раз. Этот пароль хранится поставщиком идентификации домена, а не Google Workspace. Для получения дополнительной информации см. страницу SSO в Справочном центре . В следующих разделах показан формат XML, используемый для настроек единого входа.

Получение настроек единого входа

Для получения настроек единого входа (SSO) отправьте HTTP GET на общий URL-адрес ленты SSO и добавьте заголовок Authorization как описано в разделе «Аутентификация в службе настроек администратора» . Сообщения об ошибках см. в разделе «Устранение неполадок SSO» .

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

В теле запроса для этой операции отсутствуют параметры.

В случае успешного ответа возвращается код состояния HTTP 200 OK , а также лента AtomPub с настройками SSO домена.

В ответ на GET-запрос в формате XML возвращаются свойства 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
Включает единый вход (SSO) на основе SAML для этого домена. Если вы ранее настроили параметры SSO и впоследствии установили enableSSO в значение enableSSO=false , ранее введенные вами настройки будут сохранены.
ssoWhitelist
ssoWhitelist — это IP-адрес с маской сети в формате CIDR (Classless Inter-Domain Routing). ssoWhitelist определяет, какие пользователи будут входить в систему с помощью SSO, а какие — с помощью страницы аутентификации учетной записи Google Workspace. Если маски не указаны, все пользователи будут входить в систему с помощью SSO. Дополнительную информацию см. в разделе «Как работают маски сети» .
useDomainSpecificIssuer
В SAML-запросе к поставщику идентификации можно указать эмитента, специфичного для конкретного домена. Хотя это не обязательно для большинства развертываний SSO, эта функция полезна для крупных компаний, использующих одного поставщика идентификации для аутентификации всей организации с несколькими поддоменами. Указание конкретного эмитента домена определяет, какой поддомен следует связать с запросом. Для получения дополнительной информации см. раздел «Как работает элемент Issuer в SAML-запросе?»

Если ваш запрос по какой-либо причине не удался, возвращается другой код состояния. Дополнительную информацию о кодах состояния Google Data API см. в разделе «Коды состояния HTTP» .

Обновить настройки единого входа (SSO)

Чтобы обновить настройки единого входа (SSO) домена, сначала получите настройки SSO с помощью операции «Получить настройки единого входа» , измените их, а затем отправьте PUT запрос на URL-адрес канала SSO. Убедитесь, что значение <id> в обновленной записи точно совпадает со значением <id> в существующей записи. Добавьте заголовок Authorization , как описано в разделе «Аутентификация в службе API настроек администратора» . Сообщения об ошибках см. в разделе «Устранение неполадок SSO» .

При обновлении настроек единого входа (SSO) отправьте HTTP-запрос PUT на общий URL-адрес ленты SSO:

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

Тело PUT запроса в формате XML выглядит следующим образом:

<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 с настройками SSO.

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>

Если ваш запрос по какой-либо причине не удался, возвращается другой код состояния. Дополнительную информацию о кодах состояния Google Data API см. в разделе «Коды состояния HTTP» .

Изменения настроек единого входа (SSO) запрещены, если целевой клиент включил многостороннее подтверждение для конфиденциальных действий . Запросы завершатся errorCode="1811" и reason="LegacyInboundSsoChangeNotAllowedWithMultiPartyApproval" .

Получите ключ подписи для единого входа (SSO).

Чтобы получить ключ подписи единого входа (SSO), отправьте HTTP GET на URL-адрес источника ключей подписи SSO и добавьте заголовок Authorization , как описано в разделе «Аутентификация в службе настроек администратора» . Сообщения об ошибках см. в разделе «Устранение неполадок SSO» .

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

В теле запроса для этой операции отсутствуют параметры.

В случае успешного ответа возвращается код состояния HTTP 200 OK , а также лента AtomPub с ключом подписи.

В ответ GET запрос в формате XML возвращается свойство 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>

Если ваш запрос по какой-либо причине не удался, возвращается другой код состояния. Дополнительную информацию о кодах состояния Google Data API см. в разделе «Коды состояния HTTP» .

Обновите ключ подписи для единого входа (SSO).

Чтобы обновить ключ подписи SSO для домена, сначала получите ключ подписи с помощью операции «Получить ключ подписи единого входа» , измените его, а затем отправьте PUT запрос на URL-адрес источника ключей подписи SSO. Убедитесь, что значение <id> в обновленной записи точно совпадает со значением <id> в существующей записи. Дополнительную информацию о ключах подписи единого входа на основе SAML см. в разделе «Генерация ключей и сертификатов для службы единого входа Google Workspace» .

При обновлении ключа подписи единого входа (SSO) отправьте HTTP PUT на URL-адрес источника ключа подписи SSO: 

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>

Изменения настроек единого входа (SSO) запрещены, если целевой клиент включил многостороннее подтверждение для конфиденциальных действий . Запросы завершатся errorCode="1811" и reason="LegacyInboundSsoChangeNotAllowedWithMultiPartyApproval" .

Управление почтовым шлюзом и маршрутизацией.

В разделе «Шлюз исходящей почты» показано, как 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>

Если ваш запрос по какой-либо причине не удался, возвращается другой код состояния. Дополнительную информацию о кодах состояния Google Data API см. в разделе «Коды состояния 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>

Свойства запроса следующие:

smartHost
Это может быть либо IP-адрес, либо имя хоста вашего SMTP-сервера. Google Workspace направляет исходящую почту на этот сервер.
smtpMode
Значение по умолчанию — SMTP. Другое значение, SMTP_TLS, обеспечивает защиту соединения с помощью TLS при доставке сообщения.

В случае успешного ответа возвращается код состояния HTTP 200 OK , а также лента AtomPub со статусом настроек почтового шлюза.

Если ваш запрос по какой-либо причине не удался, возвращается другой код состояния. Дополнительную информацию о кодах состояния Google Data API см. в разделе «Коды состояния 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 с маршрутизацией электронной почты» .
routeRewriteTo
Если значение равно true, поле to: в SMTP-конверте сообщения изменяется на имя хоста назначения (user@имя хоста назначения), и сообщение доставляется на этот адрес пользователя на почтовом сервере назначения. Если false , электронное письмо доставляется на адрес электронной почты to: исходном сообщении (user@имя хоста исходного сообщения) на почтовом сервере назначения. Это аналогично настройке «Изменить SMTP-конверт» в консоли администратора. Для получения дополнительной информации см. раздел «Настройки домена для маршрутизации электронной почты» .
routeEnabled
Если true , функция маршрутизации электронной почты включена. Если false , функция отключена.
bounceNotifications
Если true , Google Workspace будет отправлять отправителю уведомления о недоставке в случае сбоя доставки.
Обработка учетных записей
Этот параметр определяет, как маршрутизация электронной почты влияет на различные типы пользователей в домене:
  • allAccounts -- Доставлять всю электронную почту в это место назначения.
  • provisionedAccounts -- Доставлять почту по этому адресу, если пользователь существует в Google Workspace.
  • unknownAccounts — Доставлять почту по этому адресу, если пользователь не существует в Google Workspace. Это аналогично параметру «Доставлять почту для» в консоли администратора. Для получения дополнительной информации о предварительных условиях и использовании маршрутизации почты см. раздел « Настройки домена для маршрутизации электронной почты ».

Для публикации этого запроса отправьте HTTP POST на URL-адрес канала маршрутизации электронной почты и добавьте заголовок Authorization как описано в разделе «Аутентификация в службе настроек администратора» : 

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

В случае успешного ответа возвращается код состояния HTTP 200 OK , а также лента AtomPub с информацией из архива.

Если ваш запрос по какой-либо причине не удался, возвращается другой код состояния. Дополнительную информацию о кодах состояния Google Data API см. в разделе «Коды состояния 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