Omówienie interfejsu Admin Settings API

Interfejs Admin Settings API umożliwia administratorom domen Google Workspace pobieranie i zmienianie ustawień domen w postaci plików danych Google Data API.

Te ustawienia domeny obejmują wiele funkcji dostępnych w konsoli administracyjnej Google Workspace. Przykłady zastosowań tego interfejsu API to tworzenie niestandardowego panelu sterowania lub integrowanie domen Google Workspace z dotychczasowym środowiskiem.

Interfejs Admin Settings API implementuje protokół Google Data API. Interfejsy Google Data API są zgodne z modelem publikowania i edytowania protokołu Atom Publishing Protocol (AtomPub). Żądania HTTP AtomPub korzystają z podejścia projektowego Representational Set Transfer (RESTful) do usług internetowych. Więcej informacji znajdziesz w przewodniku dla programistów Google Data APIs.

Odbiorcy

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

Zakładamy, że znasz ogólne założenia protokołu Google Data API i wiesz, jak korzystać z konsoli administracyjnej Google Workspace. Więcej informacji o konsoli administracyjnej znajdziesz w artykule Używanie konsoli administracyjnej.

Rozpocznij

Aby zacząć korzystać z interfejsu Admin Settings API, najpierw skonfiguruj konto.

Utwórz konto

Interfejs Admin Settings API jest włączony na kontach Google Workspace. Zarejestruj się, aby utworzyć konto Google Workspace na potrzeby testowania. Usługa Admin Settings korzysta z kont Google, więc jeśli masz już konto w domenie Google Workspace, wszystko jest gotowe.

Informacje o typach plików danych interfejsu Admin Settings API

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

Ustawienia logowania jednokrotnego

Logowanie jednokrotne (SSO) oparte na SAML umożliwia użytkownikom korzystanie z tego samego loginu i hasła zarówno w przypadku usług hostowanych w Google Workspace, jak i innych usług hostowanych w organizacji. W szczególności w przypadku korzystania z logowania jednokrotnego hostowana aplikacja internetowa, np. Google Workspace, przekierowuje użytkowników do dostawcy tożsamości organizacji w celu uwierzytelnienia podczas logowania. Szczegółowe informacje znajdziesz w artykule Logowanie jednokrotne oparte na SAML w Google Workspace.

Konfigurowanie logowania jednokrotnego polega na wpisaniu informacji niezbędnych do komunikacji usługi Google Workspace z dostawcą tożsamości, który przechowuje dane logowania użytkowników, oraz na skonfigurowaniu linków, do których użytkownicy powinni być przekierowywani podczas logowania, wylogowywania i zmiany hasła. Interfejs Admin Settings API umożliwia programowe aktualizowanie i pobieranie tych ustawień. Google używa wygenerowanego klucza publicznego do weryfikowania żądania logowania jednokrotnego u dostawcy tożsamości oraz do sprawdzania, czy klucz prywatny odpowiedzi SAML nie został zmodyfikowany podczas transmisji w sieci.

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

• Wygeneruj klucze – wygeneruj u dostawcy tożsamości zestaw kluczy publicznych i prywatnych przy użyciu algorytmu DSA lub RSA. Klucz publiczny jest w certyfikacie w formacie X.509. Więcej informacji o kluczach podpisywania logowania jednokrotnego opartego na SAML znajdziesz w artykule Generowanie kluczy i certyfikatów na potrzeby usługi logowania jednokrotnego Google Workspace.
• Zarejestruj się w Google – użyj ustawień logowania jednokrotnego interfejsu Admin Settings API, aby zarejestrować w Google certyfikat klucza publicznego.
• Skonfiguruj ustawienia logowania jednokrotnego – użyj ustawień logowania jednokrotnego interfejsu Admin Settings API, aby skonfigurować ustawienia używane do komunikacji z serwerami dostawcy tożsamości domeny.

Ustawienia bramy

Ten plik danych umożliwia administratorom domen kontrolowanie routingu 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 w ustawieniach Gmaila w konsoli administracyjnej. Więcej informacji znajdziesz w artykule Routing poczty e-mail i konfiguracja 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 interfejsu Admin Settings API przy użyciu czystego kodu XML i protokołu HTTP. Ten przykład domyślnego języka domeny pokazuje pełną składnię XML i HTTP dla treści żądania i odpowiedzi, która jest wspólna dla każdej operacji:

Aby zmienić ustawienie bramy poczty wychodzącej domeny, wyślij żądanie HTTP PUT na adres URL pliku danych bramy:

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

Żądanie PUT w języku domeny 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>

Z wyjątkiem właściwości i wartości specyficznych dla operacji elementy atom:property reprezentują pojedynczą 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 w języku 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 (SSO) w Google Workspace umożliwia użytkownikom logowanie się do wielu usług przy użyciu tylko jednego loginu i hasła. Hasło jest przechowywane przez dostawcę tożsamości domeny, a nie przez Google Workspace. Więcej informacji znajdziesz na stronie Logowanie jednokrotne w Centrum pomocy. W kolejnych sekcjach pokazujemy format XML używany w przypadku 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 dodaj nagłówek Authorization zgodnie z opisem w artykule Uwierzytelnianie w usłudze Admin Settings. Komunikaty o błędach znajdziesz w artykule Rozwiązywanie problemów z logowaniem jednokrotnym SSO:

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 wraz z plikiem danych AtomPub zawierającym ustawienia 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 obejmują:

samlSignonUri

Adres URL dostawcy tożsamości, na który Google Workspace wysyła żądanie SAML w celu uwierzytelnienia użytkownika.

samlLogoutUri

Adres, na który użytkownicy będą przekierowywani po wylogowaniu się z aplikacji internetowej.

changePasswordUri

Adres, na który użytkownicy będą przekierowywani, gdy będą chcieli zmienić 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 ustawisz enableSSO na enableSSO=false, wcześniej wprowadzone ustawienia zostaną zapisane.

ssoWhitelist

`ssoWhitelist` to adres IP maski sieci w formacie CIDR (Classless Inter-Domain Routing). `ssoWhitelist` określa, którzy użytkownicy logują się za pomocą logowania jednokrotnego, a którzy za pomocą strony uwierzytelniania konta Google Workspace. Jeśli nie określono żadnych masek, wszyscy użytkownicy będą logować się za pomocą logowania jednokrotnego. Więcej informacji znajdziesz w artykule Jak działają maski sieci.

useDomainSpecificIssuer

W żądaniu SAML do dostawcy tożsamości można użyć wystawcy specyficznego dla domeny. Chociaż nie jest to konieczne w przypadku większości wdrożeń logowania jednokrotnego, ta funkcja jest przydatna w dużych firmach, które używają jednego dostawcy tożsamości do uwierzytelniania całej organizacji z wieloma subdomenami. Podanie konkretnego wystawcy domeny określa, z którą subdomeną należy powiązać żądanie. Więcej informacji znajdziesz w artykule Jak działa element Issuer w żądaniu SAML work?.

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

Aktualizowanie ustawień logowania jednokrotnego

Aby zaktualizować ustawienia logowania jednokrotnego domeny, najpierw pobierz te ustawienia za pomocą operacji Pobieranie ustawień logowania jednokrotnego, zmodyfikuj je, a następnie wyślij żądanie PUT na adres URL pliku danych logowania jednokrotnego. Upewnij się, że <id> wartość w zaktualizowanym wpisie jest dokładnie taka sama jak <id> w istniejącym wpisie. Dodaj nagł0/}wek zgodnie z opisem w artykule Uwierzytelnianie w usłudze Admin Settings API.Authorization Komunikaty o błędach znajdziesz w artykule Rozwiązywanie problemów z logowaniem jednokrotnym.

Aby zaktualizować ustawienia logowania jednokrotnego, wyślij żądanie 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 wraz z plikiem danych AtomPub zawierającym ustawienia 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 z jakiegoś powodu się nie powiedzie, zostanie zwrócony inny kod stanu. Więcej informacji o kodach stanu Google Data API znajdziesz w artykule Kody stanu HTTP.

Zmiany ustawień logowania jednokrotnego są niedozwolone, gdy docelowy klient włączył zatwierdzenie przez wiele osób w przypadku działań związanych z danymi poufnymi. Żądania nie powiodą się z errorCode="1811" i reason="LegacyInboundSsoChangeNotAllowedWithMultiPartyApproval".

Pobieranie klucza podpisywania logowania jednokrotnego

Aby pobrać klucz podpisywania logowania jednokrotnego, wyślij żądanie HTTP GET na adres URL pliku danych klucza podpisywania logowania jednokrotnego i dodaj nagłówek Authorization zgodnie z opisem w artykule Uwierzytelnianie w usłudze Admin Settings. 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 ma parametrów w treści żądania.

Pomyślna odpowiedź zwraca kod stanu HTTP 200 OK wraz z plikiem danych AtomPub zawierającym klucz 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 z jakiegoś powodu się nie powiedzie, zostanie zwrócony inny kod stanu. Więcej informacji o kodach stanu Google Data API znajdziesz w artykule Kody stanu HTTP.

Aktualizowanie klucza podpisywania logowania jednokrotnego

Aby zaktualizować klucz podpisywania logowania jednokrotnego domeny, najpierw pobierz ten klucz za pomocą operacji Pobieranie klucza podpisywania logowania 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 jest dokładnie taka sama jak wartość <id> w istniejącym wpisie. Więcej informacji o kluczach podpisywania logowania jednokrotnego opartego na SAML znajdziesz w artykule Generowanie kluczy i certyfikatów na potrzeby usługi logowania jednokrotnego Google Workspace.

Aby zaktualizować klucz podpisywania logowania jednokrotnego, wyślij żądanie HTTP PUT na adres URL pliku danych klucza podpisywania logowania 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>

Zmiany ustawień logowania jednokrotnego są niedozwolone, gdy docelowy klient włączył zatwierdzenie przez wiele osób w przypadku działań związanych z danymi poufnymi. Żądania nie powiodą się z errorCode="1811" i reason="LegacyInboundSsoChangeNotAllowedWithMultiPartyApproval".

Zarządzanie bramą poczty e-mail

Sekcja dotycząca bramy poczty wychodzącej pokazuje, jak interfejs Admin Settings API obsługuje routing poczty wychodzącej od użytkowników w Twojej domenie.

Pobieranie ustawień bramy poczty wychodzącej

Aby pobrać ustawienia bramy poczty wychodzącej, wyślij żądanie HTTP GET na adres URL pliku danych bramy i dodaj nagłówek Authorization zgodnie z opisem w artykule Uwierzytelnianie w usłudze Admin Settings:

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

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

Pomyślna odpowiedź zwraca kod stanu HTTP 200 OK wraz z plikiem danych AtomPub zawierającym informacje 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 settings.

Oto przykład możliwej odpowiedzi:

<?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 z jakiegoś powodu się nie powiedzie, zostanie zwrócony inny kod stanu. Więcej informacji o kodach stanu Google Data API znajdziesz w artykule Kody stanu HTTP.

Aktualizowanie ustawień bramy poczty wychodzącej

Aby zaktualizować ustawienie bramy poczty wychodzącej domeny, wyślij żądanie HTTP PUT na adres URL pliku danych 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 za pomocą protokołu TLS podczas dostarczania wiadomości.

Pomyślna odpowiedź zwraca kod stanu HTTP 200 OK wraz z plikiem danych AtomPub zawierającym stan ustawień bramy poczty e-mail.

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

Wycofanie punktów końcowych 31 października 2018 r.

W ramach tego ogłoszenia wycofaliśmy te punkty końcowe: Zostały one 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