Omówienie interfejsu Admin Settings API

Admin Settings API umożliwia administratorom domen Google Workspace pobieranie i zmienianie ich ustawień za pomocą plików danych interfejsu Google Data API.

Te ustawienia domeny obejmują wiele funkcji dostępnych w konsoli administracyjnej Google Workspace. Przykładowe zastosowania tego interfejsu API obejmują tworzenie niestandardowego panelu sterowania lub integrowanie domen Google Workspace z istniejącym środowiskiem źródłowym.

Interfejs Admin Settings API implementuje protokół Google Data API. Interfejs Google Data API jest zgodny z modelem publikowania i edytowania opracowanego przez protokół Atom Publishing Protocol (AtomPub). Żądania HTTP AtomPub korzystają z podejścia projektowania reprezentatywnego (RESTful) usług internetowych. Więcej informacji znajdziesz w przewodniku Google Data Developer's.

Odbiorcy

Ten dokument jest przeznaczony dla programistów, którzy chcą tworzyć aplikacje klienckie mogące modyfikować i pobierać informacje o domenach Google Workspace. Zawiera on przykłady podstawowych interakcji z interfejsem Admin Settings API przy użyciu nieprzetworzonego kodu XML i protokołu HTTP.

Zakładamy w nim, że znasz ogólne koncepcje protokołu interfejsu Google Data API i obsługę konsoli administracyjnej Google Workspace. Więcej informacji o konsoli administracyjnej znajdziesz w artykule Używanie konsoli administracyjnej.

Pierwsze kroki

Tworzenie konta

Interfejs Admin Settings API jest włączony na kontach Google Workspace. Załóż konto Google Workspace na potrzeby testowania. Usługa Ustawienia administratora korzysta z kont Google, więc jeśli masz już konto w domenie Google Workspace, nie musisz nic robić.

Informacje o typach plików danych w interfejsie Admin Settings API

Interfejs Admin Settings API umożliwia zarządzanie tymi kategoriami ustawień domeny:

Ustawienia logowania jednokrotnego

Logowanie jednokrotne przez SAML umożliwia użytkownikom używanie tego samego loginu i hasła w usługach hostowanych w Google Workspace oraz innych usługach hostowanych w organizacji. W przypadku używania logowania jednokrotnego hostowana aplikacja internetowa taka jak Google Workspace przekierowuje użytkowników do dostawcy tożsamości organizacji w celu uwierzytelniania użytkowników podczas logowania. Szczegółowe informacje znajdziesz w artykule Omówienie logowania jednokrotnego opartego na SAML w Google Workspace.

Skonfigurowanie logowania jednokrotnego obejmuje podanie informacji niezbędnych do komunikowania się z dostawcą tożsamości, który przechowuje dane logowania użytkowników, oraz skonfigurowanie linków, do których użytkownicy mają być odsyłani podczas logowania, wylogowywania się i zmiany hasła. Interfejs Admin Settings API umożliwia automatyczne aktualizowanie i pobieranie tych ustawień. Google używa wygenerowanego klucza publicznego do weryfikowania tego żądania logowania jednokrotnego u dostawcy tożsamości i sprawdzania, czy odpowiedź SAML klucza prywatnego nie została zmodyfikowana podczas przesyłania sieciowego.

Aby zobaczyć krótkie podsumowanie dotyczące używania ustawień logowania jednokrotnego, pobierz certyfikat klucza publicznego od dostawcy tożsamości, zarejestruj klucz publiczny w Google i skonfiguruj ustawienia zapytania logowania jednokrotnego opartego na SAML. Instrukcje dotyczące komunikatów o błędach znajdziesz w artykule Rozwiązywanie problemów z logowaniem jednokrotnym:

  • Wygeneruj klucze – z pomocą dostawcy tożsamości wygeneruj zestaw publicznych i prywatnych kluczy za pomocą algorytmów DSA lub RSA. Klucz publiczny znajduje się w certyfikacie sformatowanym na podstawie X.509. Więcej informacji o kluczach podpisywania jednokrotnego opartych na SAML znajdziesz w artykule Generowanie kluczy i certyfikatów usługi logowania jednokrotnego Google Workspace.
  • Zarejestruj się w Google – użyj ustawień logowania jednokrotnego w interfejsie Admin Settings API, aby zarejestrować certyfikat klucza publicznego w Google.
  • Konfigurowanie ustawień logowania jednokrotnego – korzystając z ustawień logowania jednokrotnego w interfejsie Admin Settings API, możesz skonfigurować ustawienia używane do komunikacji z serwerami dostawcy tożsamości domeny.

Ustawienia bramy i routingu

Ten kanał umożliwia administratorom domen kontrolowanie routingu poczty e-mail w ich domenach.

Operacje routingu poczty e-mail pozwalają administratorom określać ustawienia routingu poczty e-mail na poziomie domeny. Działa to podobnie do routingu poczty e-mail w ustawieniach Gmaila w konsoli administracyjnej. Więcej informacji znajdziesz w artykułach na temat routingu poczty e-mail i konfiguracji podwójnego dostarczania funkcji routingu poczty e-mail.

Przykład żądania i odpowiedzi XML interfejsu Admin Settings API

Ten dokument zawiera przykłady kodu podstawowych żądań i odpowiedzi do interfejsu Admin Settings API przy użyciu nieprzetworzonego kodu XML i HTTP. Ten przykład domyślnego języka domeny pokazuje pełną składnię XML i HTTP treści żądania i odpowiedzi, która jest wspólna dla każdej operacji:

Aby zmienić ustawienie bramy poczty wychodzącej w domenie, wyślij żądanie HTTP PUT na adres URL kanału bramy:

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

Żądanie pliku XML AtomPub entry w domyślnym języku domeny PUT to:

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

Elementy atom:property reprezentują jedną parę klucz-wartość zawierającą informacje o właściwości, którą chcesz pobrać lub zaktualizować. Są one wspólne dla wszystkich treści żądań do interfejsu Admin Settings API.

Element entry odpowiedzi domyślnego języka domeny zwraca właściwości smartHost i smtpMode oraz składnię XML wspólną dla wszystkich treści odpowiedzi interfejsu Admin Settings 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>

Zarządzanie ustawieniami logowania jednokrotnego

Funkcja logowania jednokrotnego w Google Workspace umożliwia użytkownikom logowanie się w różnych usługach bez konieczności ponownego wpisywania loginu i hasła. To hasło jest przechowywane przez dostawcę tożsamości domeny, a nie przez Google Workspace. Więcej informacji znajdziesz na stronie dotyczącej logowania jednokrotnego w Centrum pomocy. W poniższych sekcjach opisano format XML używany w ustawieniach logowania jednokrotnego.

Pobieranie ustawień logowania jednokrotnego

Aby pobrać ustawienia logowania jednokrotnego, wyślij HTTP GET na ogólny adres URL kanału SSO i dołącz nagłówek Authorization zgodnie z opisem w sekcji Uwierzytelnianie w usłudze ustawień administratora. Komunikaty o błędach znajdziesz w artykule Rozwiązywanie problemów z logowaniem jednokrotnym:

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

Ta operacja nie zawiera parametrów w treści żądania.

Pomyślna odpowiedź zwraca kod stanu HTTP 200 OK, a także plik danych AtomPub z ustawieniami logowania jednokrotnego domeny.

Kod XML odpowiedzi GET zwraca właściwości samlSignonUri, samlLogoutUri, changePasswordUri, enableSSO, ssoWhitelist i 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>

Właściwości te obejmują:

samlSignonUri
Adres URL dostawcy tożsamości, na który Google Workspace wysyła żądanie SAML na potrzeby uwierzytelnienia użytkownika.
samlLogoutUri
Adres, na który zostaną przekierowani użytkownicy po wylogowaniu się z aplikacji internetowej.
changePasswordUri
Adres, na który zostaną przekierowani użytkownicy, gdy będą chcieli zmienić swoje hasło logowania jednokrotnego w aplikacji internetowej.
enableSSO
Włącza logowanie jednokrotne oparte na SAML w tej domenie. Jeśli masz już skonfigurowane ustawienia logowania jednokrotnego, a następnie w zakresie enableSSO zostanie ustawiona wartość enableSSO=false, wprowadzone wcześniej ustawienia pozostaną zapisane.
ssoWhitelist
ssoBiała lista adresów IP to adres IP maski sieci w formacie CIDR (Classless Inter-Domain Routing). ssoBiała lista użytkowników określa, którzy użytkownicy logują się przy użyciu logowania jednokrotnego, a którzy z nich logują się na stronie uwierzytelniania konta Google Workspace. Jeśli nie określisz masek, wszyscy użytkownicy będą logować się przy użyciu logowania jednokrotnego. Więcej informacji znajdziesz w artykule Jak działają maski sieci.
useDomainSpecificIssuer
W żądaniu SAML wysyłanym do dostawcy tożsamości można użyć wystawcy właściwego dla domeny. Chociaż nie jest to konieczne w przypadku większości wdrożeń SSO, ta funkcja jest przydatna w dużych firmach, które korzystają z jednego dostawcy tożsamości do uwierzytelniania całej organizacji za pomocą wielu subdomen. Udostępnienie określonego wystawcy domeny określa, z którą subdomeną należy powiązać żądanie. Więcej informacji znajdziesz w artykule Jak działa element Issuer (Wystawca) w żądaniu SAML.

Jeśli z jakiegoś powodu żądanie nie powiedzie się, zwracany jest inny kod stanu. Więcej informacji o kodach stanu interfejsu Google Data API znajdziesz w artykule Kody stanu HTTP.

Aktualizowanie ustawień logowania jednokrotnego

Aby zaktualizować ustawienia logowania jednokrotnego w domenie, najpierw pobierz ustawienia logowania jednokrotnego przy użyciu operacji Pobieranie ustawień logowania jednokrotnego, zmodyfikuj te ustawienia, a następnie wyślij żądanie PUT na adres URL kanału SSO. Upewnij się, że wartość <id> w zaktualizowanym wpisie dokładnie odpowiada <id> w istniejącym wpisie. Dołącz nagłówek Authorization zgodnie z opisem w sekcji Uwierzytelnianie w usłudze interfejsu Admin Settings API. Informacje o błędach znajdziesz w artykule Rozwiązywanie problemów z logowaniem jednokrotnym.

Podczas aktualizowania ustawień logowania jednokrotnego wyślij żądanie HTTP PUT na ogólny adres URL kanału SSO:

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

Treść XML żądania PUT to:

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

Pomyślna odpowiedź zwraca kod stanu HTTP 200 OK i plik danych AtomPub z ustawieniami logowania jednokrotnego.

Kod XML odpowiedzi PUT to:

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

Jeśli z jakiegoś powodu żądanie nie powiedzie się, zwracany jest inny kod stanu. Więcej informacji o kodach stanu interfejsu Google Data API znajdziesz w artykule Kody stanu HTTP.

Pobieranie klucza podpisywania jednokrotnego

Aby pobrać klucz podpisywania jednokrotnego, wyślij HTTP GET do adresu URL kanału klucza podpisywania SSO i dołącz nagłówek Authorization zgodnie z opisem w sekcji Uwierzytelnianie w usłudze ustawień administratora. Komunikaty o błędach znajdziesz w artykule Rozwiązywanie problemów z logowaniem jednokrotnym:

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

Ta operacja nie zawiera parametrów w treści żądania.

Pomyślna odpowiedź zwraca kod stanu HTTP 200 OK i plik danych AtomPub z kluczem podpisywania.

Kod XML odpowiedzi GET zwraca właściwość 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>

Jeśli z jakiegoś powodu żądanie nie powiedzie się, zwracany jest inny kod stanu. Więcej informacji o kodach stanu interfejsu Google Data API znajdziesz w artykule Kody stanu HTTP.

Aktualizowanie klucza podpisywania jednokrotnego

Aby zaktualizować klucz podpisywania jednokrotnego logowania w domenie, najpierw pobierz go przy użyciu operacji Pobieranie klucza podpisywania jednokrotnego, zmodyfikuj go, a następnie wyślij żądanie PUT na adres URL kanału klucza podpisywania SSO. Upewnij się, że wartość <id> w zaktualizowanym wpisie dokładnie odpowiada <id> w istniejącym wpisie. Więcej informacji o kluczach podpisywania jednokrotnego opartych na SAML znajdziesz w artykule Generowanie kluczy i certyfikatów usługi logowania jednokrotnego Google Workspace.

Gdy aktualizujesz klucz podpisywania jednokrotnego, wyślij HTTP PUT na adres URL kanału klucza podpisywania SSO:

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

Kod XML żądania PUT to:

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

Zarządzanie bramą i routingiem poczty e-mail

Sekcja Brama poczty wychodzącej zawiera informacje o tym, w jaki sposób interfejs Admin Settings API obsługuje routing wychodzący poczty od użytkowników w Twojej domenie. Sekcja Routing poczty e-mail zawiera informacje na temat kierowania wiadomości na inny serwer poczty.

Pobieranie ustawień bramy poczty wychodzącej

Aby pobrać ustawienia bramy poczty wychodzącej, wyślij żądanie HTTP GET na adres URL kanału bramy i dołącz nagłówek Authorization zgodnie z opisem w sekcji Uwierzytelnianie w usłudze Ustawienia administratora:

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

Ta operacja nie zawiera parametrów w treści żądania.

Pomyślna odpowiedź zwraca kod stanu HTTP 200 OK i kanał AtomPub z informacjami o stanie bramy poczty e-mail.

Odpowiedź GET zwraca właściwości smartHost i smtpMode. Więcej informacji o tych właściwościach znajdziesz w artykule Aktualizowanie ustawień bramy poczty wychodzącej.

Przykładowa odpowiedź:

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

Jeśli z jakiegoś powodu żądanie nie powiedzie się, zwracany jest inny kod stanu. Więcej informacji o kodach stanu interfejsu Google Data API znajdziesz w artykule Kody stanu HTTP.

Aktualizowanie ustawień bramy poczty wychodzącej

Aby zaktualizować ustawienie bramy poczty wychodzącej w domenie, wyślij żądanie HTTP PUT na adres URL kanału bramy:

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

Kod XML żądania PUT to:

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

Właściwości żądania:

smartHost
Adres IP lub nazwa hosta serwera SMTP. Google Workspace przekierowuje pocztę wychodzącą na ten serwer.
smtpMode
Wartość domyślna to SMTP. Inna wartość, SMTP_TLS, zabezpiecza połączenie przy użyciu protokołu TLS podczas dostarczania wiadomości.

Pomyślna odpowiedź zwraca kod stanu HTTP 200 OK i kanał AtomPub ze stanem ustawień bramy poczty e-mail.

Jeśli z jakiegoś powodu żądanie nie powiedzie się, zwracany jest inny kod stanu. Więcej informacji o kodach stanu interfejsu Google Data API znajdziesz w artykule Kody stanu HTTP.

Zarządzanie ustawieniami routingu poczty e-mail

Najpierw utwórz żądanie 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>

Właściwości żądania:

routeDestination
To miejsce docelowe to nazwa hosta lub adres IP serwera poczty SMTP, na który jest kierowana e-mail. Nazwa hosta lub adres IP muszą wskazywać serwer Google. Więcej informacji o rozwiązywaniu problemów z nazwami hostów poczty znajdziesz w artykule Wdrożenie pilotażowe Google Workspace z routingiem poczty e-mail.
routeRewriteTo
Jeśli wartość to prawda, pole to: w kopercie SMTP wiadomości zostanie zmienione na docelową nazwę hosta (użytkownik@nazwa hosta miejsca docelowego) i wiadomość zostanie dostarczona na ten adres na docelowym serwerze poczty. Jeśli false, e-mail zostanie dostarczony na adres e-mail to: pierwotnej wiadomości (użytkownik@pierwotna nazwa hosta) na docelowym serwerze poczty. Jest to podobne do ustawienia „Zmień kopertę SMTP” w konsoli administracyjnej. Więcej informacji znajdziesz w artykule Ustawienia domeny na potrzeby routingu poczty e-mail.
routeEnabled
Jeśli wybrano ustawienie true, funkcja routingu poczty e-mail jest włączona. Jeśli ustawiona jest wartość false, funkcja jest wyłączona.
bounceNotifications
Jeśli wybrano ustawienie true, Google Workspace może wysyłać do nadawcy powiadomienia o odrzuceniu w przypadku niepowodzenia dostarczenia.
accountHandling

To ustawienie określa wpływ routingu poczty e-mail na różne typy użytkowników w domenie:

  • allAccounts – wszystkie e-maile będą dostarczane do tego miejsca docelowego.
  • provisionedAccounts – poczta będzie dostarczana do tego miejsca docelowego, jeśli użytkownik istnieje w Google Workspace.
  • unknownAccounts – dostarczaj pocztę do tego miejsca docelowego, jeśli użytkownika nie ma w Google Workspace. Jest to podobne do ustawienia „E-mail dostarczania dla” w konsoli administracyjnej. Aby uzyskać więcej informacji o wymaganiach wstępnych i korzystaniu z routingu poczty, przeczytaj artykuł Ustawienia domeny na potrzeby routingu poczty e-mail. ~ Aby opublikować to żądanie, wyślij HTTP POST na adres URL kanału routingu poczty e-mail i dołącz nagłówek Authorization zgodnie z opisem w sekcji Uwierzytelnianie w usłudze Ustawienia administratora:

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

Pomyślna odpowiedź zwraca kod stanu HTTP 200 OK i kanał AtomPub z informacjami z archiwum.

Jeśli z jakiegoś powodu żądanie nie powiedzie się, zwracany jest inny kod stanu. Więcej informacji o kodach stanu interfejsu Google Data API znajdziesz w artykule Kody stanu HTTP.

Wyłączenie punktów końcowych 31 października 2018 r.

W ramach tego ogłoszenia wycofaliśmy wymienione poniżej punkty końcowe. Zostały wycofane 31 października 2018 r. i nie są już dostępne.

  • 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