Ta strona została przetłumaczona przez Cloud Translation API.

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ładowe zastosowania tego interfejsu API to 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 Atom Publishing Protocol (AtomPub). Żądania HTTP AtomPub korzystają z podejścia do usług internetowych opartego na protokole REST (Representational State Transfer). Więcej informacji znajdziesz w przewodniku dla programistów Google Data.

Odbiorcy

Ten dokument jest przeznaczony dla programistów, którzy chcą pisać aplikacje klienckie, które mogą modyfikować i pobierać informacje o domenach Google Workspace. Zawiera on przykłady podstawowych interakcji interfejsu Admin Settings API za pomocą nieprzetworzonego kodu XML i HTTP.

W tym dokumencie zakładamy, że rozumiesz ogólne założenia protokołu Google Data API i masz doświadczenie w korzystaniu z 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. Zarejestruj konto Google Workspace na potrzeby testowania. Usługa Ustawienia administracyjne korzysta z kont Google, więc jeśli masz już konto w domenie Google Workspace, możesz zacząć.

Typy plików danych interfejsu 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 tych samych danych logowania i hasła zarówno w przypadku usług hostowanych w Google Workspace, jak i innych usług hostowanych w Twojej organizacji. W szczególności w przypadku logowania jednokrotnego hostowana aplikacja internetowa, np. Google Workspace, przekierowuje użytkowników do dostawcy tożsamości organizacji, aby uwierzytelnić użytkowników podczas logowania. Szczegółowe informacje znajdziesz w artykule Logowanie jednokrotne w Google Workspace na podstawie protokołu SAML.

Konfigurowanie logowania jednokrotnego wymaga podania informacji niezbędnych do komunikacji usługi Google Workspace z dostawcą tożsamości, który przechowuje informacje logowania użytkowników, a także skonfigurowania linków, które użytkownicy powinni otrzymać, aby zalogować się, wylogować i zmienić hasło. Interfejs Admin Settings API umożliwia aktualizowanie i pobieranie tych ustawień w sposób programowy. Google używa wygenerowanego klucza publicznego, aby zweryfikować to żądanie SSO u dostawcy tożsamości, oraz sprawdzić, czy odpowiedź SAML z kluczem prywatnym nie została zmodyfikowana podczas transmisji sieciowej.

Aby uzyskać krótkie podsumowanie korzystania z ustawień SSO w przypadku konkretnego interfejsu API, pobierz certyfikat klucza publicznego od dostawcy tożsamości, zarejestruj klucz publiczny w Google i skonfiguruj ustawienia zapytań SSO na podstawie SAML. Komunikaty o błędach: Rozwiązywanie problemów z logowaniem jednokrotnym

Wygeneruj klucze – za pomocą dostawcy tożsamości wygeneruj 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 protokole SAML znajdziesz w artykule Generowanie kluczy i certyfikatów do 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.
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 i routingu

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

Operacje routingu poczty umożliwiają administratorom określenie ustawień routingu poczty na poziomie domeny. Działa to podobnie jak funkcja routingu e-mail w ustawieniach Gmaila w konsoli administracyjnej. Więcej informacji znajdziesz w artykule Routing poczty e-mail i konfiguracja podwójnego dostarczania w ramach funkcji routingu poczty e-mail.

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

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

Aby zmienić ustawienie bramy poczty wychodzącej w domenie, wyślij HTTP PUT do adresu URL pliku danych bramy:

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

Domyślny język domeny PUT żądania AtomPub entry XML:

<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 związanych z operacją elementy atom:property stanowią pojedynczą parę klucz-wartość zawierającą informacje o usłudze, którą chcesz pobrać lub zaktualizować. Są one wspólne dla wszystkich treści żądań w ramach interfejsu Admin Settings API.

Element odpowiedzi entry z danymi o domyślnym języku domeny zwraca właściwości smartHost i smtpMode wraz z 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 Google Workspace (SSO) umożliwia użytkownikom logowanie się w wielu usługach przy jednorazowym wpisaniu danych logowania. Hasło to jest przechowywane przez dostawcę tożsamości domeny, a nie przez Google Workspace. Więcej informacji znajdziesz na stronie Centrum pomocy poświęconej logowaniu jednokrotnemu. W kolejnych sekcjach przedstawiono format XML używany do ustawień logowania jednokrotnego.

Pobieranie ustawień logowania jednokrotnego

Aby pobrać ustawienia logowania jednokrotnego, wyślij żądanie HTTP GET do adresu URL ogólnego pliku danych SSO i dołącz nagłówek Authorization zgodnie z opisem w sekcji Uwierzytelnianie w usłudze ustawień administratora. W przypadku komunikatów o błędach zapoznaj się z artykułem 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 ciele żądania.

Pomyślna odpowiedź zwraca kod stanu HTTP 200 OK wraz z kanałem AtomPub z ustawieniami SSO domeny.

Odpowiedź XML metody 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, do którego Google Workspace wysyła żądanie SAML w celu uwierzytelnienia użytkownika.
samlLogoutUri: Adres, na który użytkownicy będą wysyłani po wylogowaniu się z aplikacji internetowej.
changePasswordUri: Adres, na który wysyłane są użytkownicy, gdy chcą zmienić hasło logowania jednokrotnego do aplikacji internetowej.
enableSSO: Włącza logowanie jednokrotne oparte na protokole SAML w tej domenie. Jeśli ustawienia logowania jednokrotnego zostały wcześniej skonfigurowane, a następnie opcja enableSSO została ustawiona na enableSSO=false, wcześniej wprowadzone ustawienia są nadal zapisane.
ssoWhitelist: SsoWhitelist to adres IP maski sieci w formacie CIDR (Classless Inter-Domain Routing). Lista 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 podano masek, wszyscy użytkownicy będą logować się za pomocą SSO. Więcej informacji znajdziesz w artykule Jak działają maski sieciowe.
useDomainSpecificIssuer: W żądaniu SAML do dostawcy tożsamości można użyć wystawcy specyficznego dla domeny. Ta funkcja nie jest wymagana w przypadku większości wdrożeń SSO, ale jest przydatna w dużych firmach, które korzystają z jednego dostawcy tożsamości do uwierzytelniania całej organizacji z wieloma subdomenami. Podanie konkretnego wystawcy domeny określa, który subdomena ma być powiązany z żądaniem. Więcej informacji znajdziesz w artykule Jak działa element Issuer w prośbie SAML.

Jeśli prośba nie powiedzie się z jakiegoś powodu, zwrócony zostanie 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 domeny, najpierw pobierz ustawienia logowania jednokrotnego za pomocą operacji Pobieranie ustawień logowania jednokrotnego, zmień je, a następnie wyślij żądanie PUT do adresu URL pliku danych logowania jednokrotnego. Upewnij się, że wartość <id> w zaktualizowanym wpisie dokładnie odpowiada wartości <id> w istniejącym wpisie. Uwzględnij nagłówek Authorization zgodnie z opisem w artykule Uwierzytelnianie w usłudze Admin Settings API. Informacje o komunikatach o błędach znajdziesz w artykule Rozwiązywanie problemów z usługą SSO.

Podczas aktualizowania ustawień logowania jednokrotnego wyślij żądanie HTTP PUT do ogólnego adresu URL kanału SSO:

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

Treść XML żądania 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>

Pomyślna odpowiedź zwraca kod stanu HTTP 200 OK oraz kanał AtomPub z ustawieniami SSO.

Kod XML odpowiedzi 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>

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

Zmiany ustawień logowania jednokrotnego są niedozwolone, gdy klient docelowy ma włączone Zatwierdzenie przez wiele osób w przypadku działań poufnych. Żądania nie powiedzie się, gdy errorCode="1811" i reason="LegacyInboundSsoChangeNotAllowedWithMultiPartyApproval".

Pobieranie klucza podpisywania logowania jednokrotnego

Aby pobrać klucz podpisywania logowania jednokrotnego, wyślij żądanie HTTP GET do adresu URL pliku danych klucza podpisywania SSO i dołącz nagłówek Authorization zgodnie z opisem w sekcji Uwierzytelnianie w usłudze Ustawienia administratora. W przypadku komunikatów o błędach zapoznaj się z artykułem 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 ciele żądania.

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

Aktualizowanie klucza podpisywania logowania jednokrotnego

Aby zaktualizować klucz podpisywania SSO domeny, najpierw pobierz klucz podpisywania za pomocą operacji Pobieranie klucza podpisywania logowania jednokrotnego, zmień go, a następnie wyślij PUT do adresu URL pliku danych klucza podpisywania SSO. Upewnij się, że wartość <id> w zaktualizowanym wpisie jest taka sama jak <id> w istniejącym wpisie. Więcej informacji o kluczach podpisywania logowania jednokrotnego opartego na protokole SAML znajdziesz w artykule Generowanie kluczy i certyfikatów do logowania jednokrotnego w Google Workspace.

Podczas aktualizowania klucza podpisywania logowania jednokrotnego wyślij HTTP PUT do adresu URL kanału klucza podpisywania SSO:

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

Kod XML żądania 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>

Zmiany ustawień logowania jednokrotnego są niedozwolone, gdy klient docelowy ma włączone Zatwierdzenie przez wiele osób w przypadku działań poufnych. Żądania zakończą się błędem errorCode="1811" i reason="LegacyInboundSsoChangeNotAllowedWithMultiPartyApproval".

Zarządzanie bramą poczty e-mail i routingiem

W sekcji bramy poczty wychodzącej znajdziesz informacje o tym, jak interfejs Admin Settings API obsługuje kierowanie poczty wychodzącej od użytkowników w Twojej domenie. W sekcji kierowania poczty e-mail znajdziesz informacje o tym, jak kierować wiadomości na inny serwer poczty.

Pobieranie ustawień bramy poczty wychodzącej

Aby pobrać ustawienia bramy poczty wychodzącej, wyślij żądanie HTTP GET do adresu URL pliku danych 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 ciele żądania.

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

Odpowiedź GET zwraca właściwości smartHost i smtpMode. Więcej informacji o tych usługach 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 prośba nie powiedzie się z jakiegoś powodu, zwrócony zostanie 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 domeny, wyślij żądanie HTTP PUT do adresu URL pliku danych bramy:

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

Kod XML żądania 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>

Właściwości żądania:

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, szyfruje połączenie przy dostarczaniu wiadomości.

Pomyślna odpowiedź zwraca kod stanu HTTP 200 OK oraz kanał AtomPub z ustawieniami bramy poczty e-mail.

Jeśli prośba nie powiedzie się z jakiegoś powodu, zwrócony zostanie 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-In, do którego kierowany jest e-mail. Nazwa hosta lub adres IP muszą być rozpoznawane przez Google. Więcej informacji o rozwiązywaniu nazw hostów poczty znajdziesz w artykule Testowanie Google Workspace z routingiem poczty e-mail.

routeRewriteTo

Jeśli to pole ma wartość true, pole to: zaadresowanej koperty SMTP jest zmieniane na nazwę hosta docelowego (nazwa hosta użytkownika@docelowego), a wiadomość jest dostarczana na adres tego użytkownika na serwerze poczty docelowej. Jeśli false, e-mail jest dostarczany na adres to: (użytkownik@nazwa_hosta_pierwotnego) na docelowym serwerze poczty. Jest to podobne do ustawienia „Zmień kopertę SMTP” w konsoli administracyjnej. Więcej informacji znajdziesz w artykule Ustawienia domeny dotyczące routingu poczty e-mail.

routeEnabled

Jeśli true, funkcja routingu poczty e-mail jest włączona. Jeśli false, funkcja jest wyłączona.

bounceNotifications

Jeśli true, Google Workspace może wysyłać do nadawcy powiadomienia o odrzuceniu wiadomości.

accountHandling

To ustawienie określa, jak kierowanie poczty e-mail wpływa na różnych użytkowników w domenie:

allAccounts – dostarczanie wszystkich e-maili do tego miejsca docelowego.
provisionedAccounts – dostarczanie poczty do tego miejsca docelowego, jeśli użytkownik istnieje w Google Workspace.
unknownAccounts – wysyłanie poczty do tego miejsca docelowego, jeśli użytkownik nie istnieje w Google Workspace. Jest to podobne do ustawienia „E-mail dostawy dla” w konsoli administracyjnej. Więcej informacji o wymaganiach wstępnych i sposobie korzystania z routingu poczty znajdziesz w artykule Ustawienia domeny dotyczące routingu poczty e-mail. ~ Aby opublikować to żądanie, wyślij żądanie HTTP POST do adresu URL kanału routingu e-maila 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

W przypadku pomyślnej odpowiedzi zwracany jest kod stanu HTTP 200 OK oraz kanał AtomPub z informacjami o archiwum.

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

Punkty końcowe zostaną wycofane 31 października 2018 r.

W ramach tego ogłoszenia wycofujemy 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