Interfejs Admin Settings API umożliwia administratorom domen Google Workspace pobieranie i zmienianie ustawień domen za pomocą plików danych 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 starszym środowiskiem.
Interfejs Admin Settings API implementuje protokół Google Data API. Interfejs Google Data API jest zgodny z modelem publikowania i edytowania protokołu Atom Publishing Protocol (AtomPub). W przypadku żądań HTTP AtomPub do usług internetowych stosowana jest metoda przesyłania reprezentacyjnego zestawu danych (RESTful). Więcej informacji znajdziesz w Przewodniku dla deweloperów danych Google.
Odbiorcy
Ten dokument jest przeznaczony dla deweloperów, którzy chcą tworzyć aplikacje klienckie umożliwiające modyfikowanie i pobieranie informacji o domenach Google Workspace. Przedstawia przykłady podstawowych interakcji interfejsu Admin Settings API z użyciem nieprzetworzonych plików XML i HTTP.
Zakładamy w nim, że znasz ogólne założenia protokołu Google Data API i znasz konsolę administracyjną 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. Aby przeprowadzić testy, zarejestruj konto Google Workspace. 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 korzystanie z tego samego loginu i hasła w usługach hostowanych przez Google Workspace oraz innych usługach, które hostujesz w organizacji. W szczególności w przypadku korzystania z logowania jednokrotnego hostowana aplikacja internetowa, taka jak Google Workspace, przekierowuje użytkowników do dostawcy tożsamości w organizacji w celu uwierzytelnienia ich podczas logowania. Szczegółowe informacje znajdziesz w artykule Omówienie logowania jednokrotnego opartego na SAML w Google Workspace.
Konfigurowanie logowania jednokrotnego przez usługę Google Workspace obejmuje wpisanie informacji niezbędnych do komunikowania się usługi Google Workspace z dostawcą tożsamości, który przechowuje dane logowania użytkowników, a także skonfigurowanie linków, do których użytkownicy będą kierowani na potrzeby logowania się, wylogowywania się i zmieniania hasła. Interfejs Admin Settings API umożliwia automatyczne aktualizowanie i pobieranie tych ustawień. Google używa wygenerowanego klucza publicznego do zweryfikowania tego żądania logowania jednokrotnego u dostawcy tożsamości i do potwierdzenia, że odpowiedź SAML klucza prywatnego nie została zmodyfikowana podczas transmisji sieciowej.
Aby uzyskać krótkie podsumowanie korzystania z ustawień logowania jednokrotnego w interfejsie API, pobierz certyfikat klucza publicznego od dostawcy tożsamości, zarejestruj klucz publiczny w Google i skonfiguruj ustawienia zapytania logowania jednokrotnego opartego na SAML. Informacje o komunikatach o błędach znajdziesz w artykule Rozwiązywanie problemów z logowaniem jednokrotnym:- Generowanie kluczy – z pomocą dostawcy tożsamości wygeneruj zestaw kluczy publicznych i prywatnych za pomocą algorytmów DSA lub RSA. Klucz publiczny znajduje się w certyfikacie w formacie X.509. Więcej informacji o kluczach podpisywania jednokrotnego opartego na SAML znajdziesz w artykule Generowanie kluczy i certyfikatów dla usługi logowania jednokrotnego w Google Workspace.
- Zarejestruj się w Google – użyj ustawień logowania jednokrotnego interfejsu Admin Settings API, aby zarejestrować certyfikat klucza publicznego w Google.
- Konfigurowanie ustawień logowania jednokrotnego – użyj ustawień logowania jednokrotnego w interfejsie Admin Settings API, aby skonfigurować ustawienia używane do komunikacji z serwerami dostawcy tożsamości domeny.
- Ustawienia bramy i trasy
Ten kanał pozwala administratorom domen kontrolować routing poczty e-mail w swoich domenach.
Operacje routingu poczty e-mail umożliwiają administratorom określanie ustawień routingu poczty e-mail na poziomie domeny. Jest to podobne do funkcji routingu poczty e-mail dostępnej w ustawieniach Gmaila w konsoli administracyjnej. Więcej informacji znajdziesz w artykułach Routing poczty e-mail i Konfigurowanie podwójnego dostarczania poczty e-mail w funkcji routingu.
Przykład żądania i odpowiedzi XML do interfejsu Admin Settings API
Ten dokument zawiera przykłady kodu podstawowych żądań i odpowiedzi interfejsu Admin Settings API, które korzystają z nieprzetworzonych plików XML i HTTP. Ten przykład domyślnego języka domeny przedstawia 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
Domyślny język XML domeny PUT AtomPub entry XML 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, z wyjątkiem właściwości i wartości związanych z operacją, 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 w przypadku domyślnego języka odpowiedzi domeny zwraca właściwości smartHost i smtpMode wraz ze 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 wielu usługach przy jednoczesnym wpisywaniu loginu i hasła tylko raz. To hasło jest przechowywane przez dostawcę tożsamości domeny, a nie przez Google Workspace. Więcej informacji znajdziesz na stronie logowania jednokrotnego w Centrum pomocy. W poniższych sekcjach przedstawiamy format XML używany na potrzeby ustawień logowania jednokrotnego.
Pobieranie ustawień logowania jednokrotnego
Aby pobrać ustawienia logowania jednokrotnego, wyślij żądanie HTTP GET na adres URL ogólnego pliku danych logowania jednokrotnego i dołącz nagłówek Authorization zgodnie z opisem w sekcji Uwierzytelnianie w usłudze Ustawienia administratora. Informacje o komunikatach o błędach znajdziesz w sekcji Rozwiązywanie problemów z logowaniem jednokrotnym:
https://apps-apis.google.com/a/feeds/domain/2.0/{domainName}/sso/general
Ta operacja nie ma parametrów w treści żądania.
Pomyślna odpowiedź zwraca kod stanu HTTP 200 OK oraz kanał AtomPub z ustawieniami logowania jednokrotnego w domenie.
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>
Dostępne są następujące właściwości:
- samlSignonUri
- Adres URL dostawcy tożsamości, na który Google Workspace wysyła żądanie SAML dotyczące uwierzytelniania użytkownika.
- samlLogoutUri
- Adres, na który zostaną przekierowani użytkownicy po wylogowaniu się z aplikacji internetowej.
- changePasswordUri
- Adres, na który będą kierowani użytkownicy, gdy będą chcieli zmienić hasło do logowania jednokrotnego w aplikacji internetowej.
- enableSSO
- Włącza w tej domenie logowanie jednokrotne oparte na SAML. Jeśli masz już skonfigurowane ustawienia logowania jednokrotnego, a następnie ustawisz
enableSSOnaenableSSO=false, wcześniej wprowadzone ustawienia zostaną zachowane. - ssoWhitelist
- ssoBiała lista to adres IP maski sieci w formacie CIDR (Classless Inter-Domain Routing). ssoBiała lista określa, którzy użytkownicy logują się za pomocą logowania jednokrotnego, a którzy logują się na stronie uwierzytelniania konta Google Workspace. Jeśli nie podano masek, wszyscy użytkownicy będą logować się za pomocą SSO. 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ć nazwy wystawcy specyficznego dla domeny. Chociaż nie jest to konieczne w przypadku większości wdrożeń SSO, ta funkcja jest przydatna w dużych firmach korzystających z jednego dostawcy tożsamości do uwierzytelniania całej organizacji z wieloma subdomenami. Nadanie określonego wydawcy domeny określa, którą subdomenę należy powiązać z żądaniem. Więcej informacji znajdziesz w artykule Jak działa element Issuer w żądaniu SAML.
Jeśli żądanie nie powiedzie się z jakiegoś powodu, zostanie zwrócony 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 pobierania ustawień logowania jednokrotnego, zmodyfikuj te ustawienia i wyślij żądanie PUT na adres URL kanału logowania jednokrotnego. Upewnij się, że wartość <id> w zaktualizowanym wpisie dokładnie odpowiada wartości <id> istniejącego wpisu. Dołącz nagłówek Authorization zgodnie z opisem w sekcji Uwierzytelnianie w usłudze Admin Settings API. Informacje o komunikatach o błędach znajdziesz w artykule Rozwiązywanie problemów z logowaniem jednokrotnym.
Podczas aktualizowania ustawień logowania jednokrotnego wyślij HTTP PUT na adres URL ogólnego pliku danych logowania jednokrotnego:
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 oraz kanał 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 żądanie nie powiedzie się z jakiegoś powodu, zostanie zwrócony inny kod stanu. Więcej informacji o kodach stanu interfejsu Google Data API znajdziesz w artykule Kody stanu HTTP.
Pobieranie klucza podpisywania jednokrotnego logowania
Aby pobrać klucz podpisywania jednokrotnego, wyślij żądanie HTTP GET na adres URL pliku danych klucza podpisywania jednokrotnego i dołącz nagłówek Authorization zgodnie z opisem w sekcji Uwierzytelnianie w usłudze Ustawienia administracyjne. Informacje o komunikatach o błędach znajdziesz w sekcji Rozwiązywanie problemów z logowaniem jednokrotnym:
https://apps-apis.google.com/a/feeds/domain/2.0/{domainName}/sso/signingkey
Ta operacja nie ma parametrów w treści żądania.
Odpowiedź pomyślna zwraca kod stanu HTTP 200 OK oraz kanał 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 żądanie nie powiedzie się z jakiegoś powodu, zostanie zwrócony inny kod stanu. Więcej informacji o kodach stanu interfejsu Google Data API znajdziesz w artykule Kody stanu HTTP.
Aktualizowanie klucza podpisywania jednokrotnego logowania
Aby zaktualizować klucz podpisywania logowania jednokrotnego w domenie, najpierw pobierz klucz podpisywania przy użyciu operacji pobierania klucza podpisywania jednokrotnego, zmodyfikuj go, a następnie wyślij żądanie PUT na adres URL pliku danych klucza podpisywania logowania jednokrotnego. Upewnij się, że wartość <id> w zaktualizowanym wpisie dokładnie odpowiada wartości <id> istniejącego wpisu. Więcej informacji o kluczach podpisywania jednokrotnego opartego na SAML znajdziesz w artykule Generowanie kluczy i certyfikatów dla usługi logowania jednokrotnego w Google Workspace.
Podczas aktualizowania klucza podpisywania logowania jednokrotnego wyślij HTTP PUT na adres URL pliku danych klucza podpisywania jednokrotnego:
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
W sekcji bramy poczty wychodzącej znajdziesz informacje o tym, jak interfejs Admin Settings API obsługuje routing poczty wychodzącej od użytkowników w Twojej domenie. W sekcji Routing poczty e-mail znajdziesz informacje o kierowaniu 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 ma parametrów w treści żądania.
Odpowiedź pomyślna 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 żądanie nie powiedzie się z jakiegoś powodu, zostanie zwrócony 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 to:
- smartHost
- Adres IP lub nazwa hosta serwera SMTP. Google Workspace kieruje 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.
Odpowiedź pomyślna zwraca kod stanu HTTP 200 OK i kanał AtomPub ze stanem ustawień bramy poczty e-mail.
Jeśli żądanie nie powiedzie się z jakiegoś powodu, zostanie zwrócony 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 to:
- routeDestination
- To miejsce docelowe to nazwa hosta lub adres IP serwera poczty SMTP, na który kierowany jest e-mail. Nazwa hosta lub adres IP musi wskazywać serwer firmy Google. Więcej informacji o rozpoznawaniu nazw hostów poczty znajdziesz w artykule Wdrożenie pilotażowe Google Workspace z routingiem poczty e-mail.
- routeRewriteTo
- Jeśli ma wartość true, pole
to:w kopercie SMTP wiadomości jest zmieniane na docelową nazwę hosta (użytkownik@nazwa hosta miejsca docelowego), a wiadomość jest dostarczana na ten adres użytkownika na docelowym serwerze poczty. W przypadkufalsee-mail zostanie dostarczony na adres e-mailto:oryginalnej 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
true, funkcja routingu poczty e-mail jest włączona. Jeśli zasada jestfalse, funkcja jest wyłączona. - bounceNotifications
- Jeśli zasada
truejest włączona, Google Workspace może wysyłać do nadawcy powiadomienia o problemie z dostarczeniem, gdy nie uda się ich dostarczyć. - accountHandling
To ustawienie określa wpływ routingu poczty e-mail na różne typy użytkowników w domenie:
allAccounts– dostarczanie wszystkich e-maili do tego miejsca docelowego.provisionedAccounts– jeśli użytkownik istnieje w Google Workspace, dostarczanie poczty do tego miejsca docelowego.unknownAccounts– jeśli użytkownik nie istnieje w Google Workspace, dostarczanie poczty do tego miejsca docelowego. Jest to podobne do ustawienia „Dostarczanie e-maili do” w konsoli administracyjnej. Więcej informacji na temat wymagań wstępnych i sposobu korzystania z routingu poczty znajdziesz w artykule Ustawienia domeny na potrzeby routingu poczty e-mail. ~ Aby opublikować to żądanie, wyślij żądanie HTTPPOSTna adres URL kanału routingu poczty e-mail i dołącz nagłówekAuthorizationzgodnie z opisem w sekcji Uwierzytelnianie w usłudze Ustawienia administracyjne:
https://apps-apis.google.com/a/feeds/domain/2.0/{domainName}/emailrouting
Odpowiedź pomyślna zwraca kod stanu HTTP 200 OK oraz kanał AtomPub z informacjami o archiwum.
Jeśli żądanie nie powiedzie się z jakiegoś powodu, zostanie zwrócony inny kod stanu. Więcej informacji o kodach stanu interfejsu Google Data API znajdziesz w artykule Kody stanu HTTP.
Punkty końcowe wycofujemy 31 października 2018 r.
W ramach tego powiadomienia wycofaliśmy poniższe 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