Interfejs API ustawień Google Workspace dla administratorów

Zadbaj o dobrą organizację dzięki kolekcji Zapisuj i kategoryzuj treści zgodnie ze swoimi preferencjami.

Interfejs Google Workspace 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ładem użycia tego interfejsu API jest utworzenie niestandardowego panelu sterowania lub zintegrowanie 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 AtomPub (AtomPub). Żądania HTTP AtomPub wykorzystują model reprezentatywny zestawu przenoszenia (RESTful) do usług internetowych. Więcej informacji znajdziesz w Przewodniku dla programistów danych Google.

Odbiorców

Ten dokument jest przeznaczony dla deweloperów, którzy chcą tworzyć aplikacje klienckie, które mogą zmieniać i pobierać informacje o domenach Google Workspace. Znajdziesz w nim przykłady podstawowych interakcji z interfejsem Admin Settings API za pomocą nieprzetworzonych plików XML i HTTP.

W tym dokumencie zakładamy, że znasz ogólne pomysły związane z protokołem 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 Google Workspace Admin Settings API jest włączony na kontach Google Workspace. Załóż konto Google Workspace na potrzeby testów. Usługa ustawień administracyjnych 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 ustawieniach administracyjnych

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 zarówno w usługach hostowanych przez Google Workspace, jak i w innych usługach hostowanych w Twojej organizacji. W szczególności podczas używania logowania jednokrotnego (hostowanej aplikacji internetowej, takiej jak Google Workspace), użytkownicy są przekierowywani do dostawcy tożsamości w Twojej organizacji w celu uwierzytelniania użytkowników podczas logowania. Szczegółowe informacje znajdziesz w artykule Omówienie logowania jednokrotnego przez SAML w Google Workspace

Skonfigurowanie logowania jednokrotnego obejmuje podanie informacji niezbędnych, aby usługa Google Workspace mogła komunikować się z dostawcą tożsamości, który przechowuje dane użytkowników, a także konfigurować linki, które mają być wysyłane do użytkowników do logowania się, wylogowywania i zmiany haseł. Interfejs Admin Settings API umożliwia automatyczne aktualizowanie i pobieranie tych ustawień. Google używa wygenerowanego klucza publicznego do weryfikacji tego żądania logowania jednokrotnego przy użyciu dostawcy tożsamości i sprawdza, czy odpowiedź dotycząca klucza prywatnego SAML nie została zmieniona podczas przesyłania sieci.

Aby zobaczyć krótkie podsumowanie konkretnego ustawienia API dotyczące ustawień logowania jednokrotnego, uzyskaj 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:

  • Wygeneruj klucze – przy użyciu 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. Aby dowiedzieć się więcej o kluczach logowania jednokrotnego opartych na SAML, zobacz Generowanie kluczy i certyfikatów dla usługi logowania jednokrotnego Google Workspace.
  • Zarejestruj w Google – użyj ustawień logowania jednokrotnego przez API i rejestracji Google, aby zarejestrować certyfikat klucza publicznego.
  • Skonfiguruj ustawienia logowania jednokrotnego – użyj ustawień logowania jednokrotnego przez API, aby skonfigurować ustawienia używane do komunikacji z serwerami dostawcy domeny.

Ustawienia bramy i routingu

Ten kanał umożliwia administratorom domeny 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. Jest to podobne do funkcji routingu poczty e-mail w ustawieniach konsoli administracyjnej Google. Więcej informacji znajdziesz w sekcjach na temat konfiguracji routingu poczty e-mail i konfiguracji routingu poczty e-mail.

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

Ten dokument zawiera przykłady kodu z podstawowymi żądaniami i odpowiedziami interfejsu Admin Settings API, które korzystają z surowego kodu XML i HTTP. Ten przykładowy język domyślny domeny zawiera pełną składnię XML i HTTP dla treści żądania i odpowiedzi, która jest typowa dla każdej operacji:

Aby zmienić ustawienie bramy poczty e-mail wychodzącej, wyślij PUT do adresu URL kanału bramy:

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

Domyślny język domeny PUT to 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>

Oprócz właściwości i wartości konkretnych elementów elementy atom:property reprezentują jedną parę klucz-wartość zawierającą informacje o usłudze, którą chcesz pobrać lub zaktualizować. Są one typowe dla wszystkich treści żądań do interfejsu Admin Settings API.

Element domyślnej odpowiedzi w języku domeny entry zwraca właściwości smartHost i smtpMode, a także składnię XML, która jest typowa dla wszystkich treści 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 pozwala użytkownikom logować się w wielu usługach przy użyciu hasła i hasła tylko raz. Hasło jest przechowywane przez dostawcę tożsamości domeny, a nie Google Workspace. Więcej informacji znajdziesz na stronie logowania w Centrum pomocy. Poniższe sekcje pokazują format XML używany w ustawieniach logowania jednokrotnego.

Pobieram ustawienia logowania jednokrotnego

Aby pobrać ustawienia logowania jednokrotnego, wyślij GET na adres URL ogólnego kanału logowania SSO i dodaj 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/general

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

Pomyślna odpowiedź zwróci kod stanu HTTP 200 OK wraz z kanałem 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>

Właściwości:

samlSignonUri
URL dostawcy tożsamości, na który Google Workspace wysyła żądanie SAML dotyczące uwierzytelniania użytkownika.
Identyfikator URI SAML
Adres, na który użytkownicy zostaną przekierowani po wylogowaniu się z aplikacji internetowej.
identyfikator URI zmiany
Adres, na który zostaną kierowani użytkownicy, gdy chcą zmienić hasło do logowania jednokrotnego w aplikacji internetowej.
włączanie logowania jednokrotnego
Włącza logowanie jednokrotne oparte na protokole SAML dla tej domeny. Jeśli masz skonfigurowane wcześniej ustawienia logowania jednokrotnego, a kolejne enableSSO zostało ustawione na enableSSO=false, podane wcześniej ustawienia zostaną zapisane.
lista dozwolonych nadawców
Parametr ssoWhitelist to adres IP maski sieci w formacie Classless Inter-Domain Routing (CIDR). Parametr ssoWhitelist określa, którzy użytkownicy logują się przy użyciu logowania jednokrotnego, a którzy logują się na stronie uwierzytelniania konta Google Workspace. Jeśli nie określono 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 dostawcy tożsamości można użyć dostawcy właściwego dla domeny. Chociaż nie jest to konieczne w przypadku większości wdrożeń SSO, ta funkcja jest przydatna w przypadku dużych firm korzystających z jednego dostawcy tożsamości do uwierzytelniania całej organizacji przy użyciu wielu subdomen. Przypisanie konkretnego wydawcy domeny określa, która subdomena ma zostać powiązana z żądaniem. Więcej informacji znajdziesz w artykule Jak działa element wydawcy w żądaniu SAML?.

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

Aktualizacja ustawień logowania jednokrotnego

Aby zaktualizować ustawienia logowania jednokrotnego w domenie, najpierw pobierz ustawienia logowania jednokrotnego przy użyciu operacji Pobieranie ustawień logowania jednokrotnego, zmodyfikuj je, a następnie wyślij żądanie PUT na adres URL kanału logowania jednokrotnego. Upewnij się, że wartość <id> w zaktualizowanym wpisie jest dokładnie taki sam jak <id> dotychczasowego wpisu. Uwzględnij nagłówek Authorization w sposób opisany w artykule Uwierzytelnianie w usłudze Ustawienia administratora. Informacje o komunikatach o błędach znajdziesz w artykule Rozwiązywanie problemów z logowaniem jednokrotnym.

Podczas aktualizowania ustawień logowania jednokrotnego wyślij plik HTTP PUT na ogólny adres URL kanału 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ź zwróci kod stanu HTTP 200 OK wraz z kanałem AtomPub z ustawieniami logowania jednokrotnego.

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ę, zostanie zwrócony inny kod stanu. Więcej informacji o kodach stanu interfejsu Google Data API znajdziesz w artykule Kody stanów HTTP.

Odzyskiwanie klucza podpisywania jednokrotnego

Aby pobrać klucz logowania jednokrotnego, wyślij HTTP HTTP GET na adres URL kanału klucza logowania jednokrotnego 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 zawiera parametrów w treści żądania.

Pomyślna odpowiedź zwraca kod stanu HTTP 200 OK wraz z kanałem AtomPub i 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ę, zostanie zwrócony inny kod stanu. Więcej informacji o kodach stanu interfejsu Google Data API znajdziesz w artykule Kody stanów HTTP.

Aktualizowanie klucza podpisywania logowania jednokrotnego

Aby zaktualizować klucz podpisywania domeny, najpierw pobierz klucz podpisywania, używając operacji Pobieranie klucza logowania jednokrotnego, zmodyfikuj go, a następnie wyślij żądanie PUT na adres URL kanału klucza logowania jednokrotnego. Upewnij się, że wartość <id> w zaktualizowanym wpisie jest dokładnie taki sam jak <id> dotychczasowego wpisu. Aby dowiedzieć się więcej o kluczach logowania jednokrotnego opartych na SAML, zobacz Generowanie kluczy i certyfikatów dla usługi logowania jednokrotnego Google Workspace.

Podczas aktualizowania klucza podpisywania logowania jednokrotnego wyślij HTTP PUT na adres URL kanału klucza logowania jednokrotnego:

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

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ą poczty e-mail i routingiem

Sekcja Brama poczty wychodzącej zawiera informacje o tym, jak interfejs API obsługuje routing poczty wychodzącej od użytkowników w Twojej domenie. Sekcja routingu poczty e-mail pokazuje, jak kierować wiadomości na inny serwer poczty.

Pobieram ustawienia 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, plik danych AtomPub i 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.

Przykładowa możliwa 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ę, zostanie zwrócony inny kod stanu. Więcej informacji o kodach stanu interfejsu Google Data API znajdziesz w artykule Kody stanów HTTP.

Aktualizowanie ustawień bramy poczty wychodzącej

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

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

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 przekierowuje pocztę wychodzącą na ten serwer.
Tryb smtpMode
Wartość domyślna to SMTP. Inna wartość – SMTP_TLS – podczas dostarczania wiadomości zabezpiecza połączenie za pomocą protokołu TLS.

Pomyślna odpowiedź zwróci kod stanu HTTP 200 OK wraz z kanałem AtomPub i stanem ustawień bramy poczty e-mail.

Jeśli z jakiegoś powodu żądanie nie powiedzie się, zostanie zwrócony inny kod stanu. Więcej informacji o kodach stanu interfejsu Google Data API znajdziesz w artykule Kody stanów 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
Miejsce docelowe to nazwa hosta lub adres IP serwera poczty SMTP SMTP, na który jest kierowany e-mail. Nazwa hosta lub adres IP muszą być rozpoznawane przez Google. Więcej informacji na temat rozwiązywania problemów z nazwami hostów poczty znajdziesz w artykule Wdrożenie pilotażowe Google Workspace.
RouteRewriteTo
Jeśli wybrano wartość „prawda”, pole to: w polu SMTP wiadomości zostanie zmienione na docelową nazwę hosta (użytkownik@miejsce_docelowe) i wiadomość zostanie dostarczona na ten adres użytkownika na docelowym serwerze poczty. Jeśli false, e-mail jest dostarczane na oryginalny adres e-mail to: (użytkownik@pierwotna nazwa hosta) na docelowym serwerze poczty. Jest to podobne do ustawienia w konsoli administracyjnej i Zmień kopertę SMTP. Więcej informacji znajdziesz w artykule Ustawienia domeny dla routingu poczty e-mail.
trasa po włączeniu
Jeśli funkcja true jest włączona, funkcja routingu poczty e-mail jest włączona. Jeśli zasada false jest wyłączona, funkcja jest wyłączona.
Powiadomienia o odrzuceniu
Jeśli usługa true jest włączona, Google Workspace umożliwia wysyłanie powiadomień o problemie z dostarczeniem do nadawcy, gdy nie uda się go dostarczyć.
obsługa konta

To ustawienie określa wpływ routingu na wszystkie typy użytkowników w domenie:

  • allAccounts – dostarcza wszystkie e-maile do tego miejsca docelowego
  • provisionedAccounts – poczta będzie dostarczana do tego miejsca docelowego, jeśli użytkownik istnieje w Google Workspace.
  • unknownAccounts – dostarcza pocztę do tego miejsca docelowego, jeśli użytkownik nie istnieje w Google Workspace; Jest to podobne do ustawienia w konsoli administracyjnej Więcej informacji o wymaganiach wstępnych i sposobie korzystania z routingu poczty znajdziesz w artykule Ustawienia domeny dla 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 Authorizationw sposób opisany w Uwierzytelnianie w usłudze Ustawienia administratora:

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

Pomyślna odpowiedź zwróci kod stanu HTTP 200 OK wraz z kanałem AtomPub z informacjami o archiwum.

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

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

W tym ogłoszeniu wycofaliśmy następujące punkty końcowe. 31 października 2018 r. zostały one wycofane 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