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ślifalse
, e-mail zostanie dostarczony na adres e-mailto:
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 HTTPPOST
na adres URL kanału routingu poczty e-mail i dołącz nagłówekAuthorization
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