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

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

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

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

Аудитория

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

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

Начиная

Создание учетной записи

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 с закрытым ключом не был изменён во время передачи по сети.

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

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

За исключением свойств и значений, специфичных для конкретной операции, элементы 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-формат, используемый для настроек единого входа.

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

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

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

Если запрос по какой-либо причине не выполнен, возвращается другой код статуса. Подробнее о кодах статуса API данных Google см. в разделе Коды статуса HTTP .

Обновление настроек единого входа

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

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

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

Если запрос по какой-либо причине не выполнен, возвращается другой код статуса. Подробнее о кодах статуса API данных Google см. в разделе Коды статуса HTTP .

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

Получение ключа подписи единого входа

Чтобы получить ключ подписи единого входа, отправьте HTTP- GET на URL-адрес канала ключа подписи единого входа (SSO) и включите заголовок 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) домена, сначала получите ключ подписи с помощью операции « Получение ключа подписи единого входа» (Retrieving Single Sign-On signing key) , измените его, а затем отправьте запрос PUT на URL-адрес фида ключей подписи единого входа (SSO). Убедитесь, что значение <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>

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

Если запрос по какой-либо причине не выполнен, возвращается другой код статуса. Подробнее о кодах статуса 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>

Свойства запроса:

smartHost
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 с маршрутизацией электронной почты» .
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 с информацией об архиве.

Если запрос по какой-либо причине не выполнен, возвращается другой код статуса. Подробнее о кодах статуса 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/{имя_домена}/general/имя_организации
  • 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