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

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

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

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

Аудитория

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

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

Начиная

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

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

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

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

Настройки единого входа

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

Настройка единого входа включает в себя ввод необходимой информации для службы 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>

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

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

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

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

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

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

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

При обновлении настроек единого входа отправьте 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 с настройками единого входа.

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-адрес канала ключей подписи единого входа и включите заголовок 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-адрес канала ключа подписи 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 направляет исходящую почту на этот сервер.
смтпмоде
Значение по умолчанию — 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
Если это правда, поле to: конверта SMTP сообщения заменяется на имя хоста назначения (имя хоста пользователя@назначения), и сообщение доставляется по этому адресу пользователя на почтовом сервере назначения. Если false , электронное письмо доставляется на адрес исходного сообщения to: адрес электронной почты (пользователь@исходное имя хоста) на целевом почтовом сервере. Это похоже на настройку «Изменить конверт SMTP» в консоли администратора. Дополнительную информацию см. в разделе Настройки домена для маршрутизации электронной почты .
маршрутВключен
Если true , функция маршрутизации электронной почты включена. Если false , функция отключена.
отказовУведомления
Если 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/{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