Omówienie interfejsu Admin Settings API

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

Interfejs Admin Settings API umożliwia administratorom domen Google Workspace pobieranie i zmienianie ustawień swoich domen w plikach 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 i integrowanie domen Google Workspace z dotychczasowym środowiskiem.

Interfejs Admin Settings API korzysta z protokołu Google Data API. Interfejs Google Data API jest zgodny z modelem publikowania i edytowania AtomPub. Żądania HTTP AtomPub korzystają z projektu reprezentatywnego zestawu transferu (RESTful) do usług internetowych. Więcej informacji znajdziesz w przewodniku Google dla programistów danych.

Odbiorcy

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

Zakładamy, że znasz ogólne pojęcia związane z protokołem 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.

Pierwsze kroki

Tworzenie konta

Interfejs Admin Settings API jest włączony na kontach Google Workspace. Zarejestruj się na konto Google Workspace na potrzeby testowania. Usługa ustawień administracyjnych korzysta z kont Google, więc jeśli masz już konto w domenie Google Workspace, nie musisz nic więcej robić.

Informacje o typach plików danych Admin API

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

Ustawienia logowania jednokrotnego

Użytkownicy korzystający z logowania jednokrotnego opartego na SAML mogą używać tego samego loginu i hasła w usługach hostowanych w Google Workspace oraz w innych usługach hostowanych w organizacji. W przypadku korzystania z logowania jednokrotnego, hostowanej aplikacji internetowej, takiej jak Google Workspace, użytkownicy są przekierowywani do dostawcy tożsamości w organizacji w celu uwierzytelniania użytkowników podczas logowania. Więcej informacji znajdziesz w artykule Omówienie logowania jednokrotnego opartego na SAML w Google Workspace

Konfigurowanie logowania jednokrotnego obejmuje informacje potrzebne usłudze Google Workspace do komunikacji z dostawcą tożsamości, który przechowuje dane logowania, a także konfigurowanie linków, do których użytkownicy mają być kierowani w celu zalogowania się, wylogowania i zmiany haseł. Interfejs Admin Settings API umożliwia automatyczne aktualizowanie i pobieranie tych ustawień. Google użyje wygenerowanego klucza publicznego do zweryfikowania tego żądania logowania jednokrotnego u dostawcy tożsamości i okaże się, że odpowiedź SAML nie została zmodyfikowana podczas przesyłania sieciowego.

Aby uzyskać krótkie podsumowanie związane z używaniem ustawień SSO w interfejsie API, pobierz certyfikat klucza publicznego od dostawcy tożsamości, zarejestruj klucz publiczny w Google i skonfiguruj ustawienia zapytania SSO opartego na SAML. Komunikaty o błędach znajdziesz w artykule Rozwiązywanie problemów z logowaniem jednokrotnym:

  • Generowanie kluczy: za pomocą dostawcy tożsamości wygeneruj zestaw kluczy publicznych i prywatnych za pomocą algorytmów DSA lub RSA. Klucz publiczny jest w certyfikacie w formacie X.509. Więcej informacji o kluczach logowania jednokrotnego opartych na SAML znajdziesz w artykule Generowanie kluczy i certyfikatów dla usługi logowania jednokrotnego Google Workspace.
  • Zarejestruj się w Google – użyj ustawień logowania jednokrotnego w interfejsie API ustawień administracyjnych, aby zarejestrować certyfikat klucza publicznego w Google.
  • Skonfiguruj ustawienia logowania jednokrotnego – korzystając z ustawień logowania jednokrotnego w interfejsie Admin Settings API, możesz skonfigurować ustawienia komunikacji z serwerami dostawcy tożsamości w domenie.

Ustawienia bramy i trasy

Dzięki temu kanałowi administratorzy mogą kontrolować routing poczty e-mail w swoich domenach.

Operacje routingu poczty e-mail pozwalają administratorom określać ustawienia routingu poczty e-mail na poziomie domeny. Jest do podobne do funkcji 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 routingu poczty e-mail.

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

Ten dokument zawiera przykłady kodu podstawowych żądań interfejsu API z ustawieniami administracyjnymi oraz odpowiedzi przy użyciu nieprzetworzonego kodu XML i HTTP. Ten przykładowy język domyślny domeny to pełna składnia XML i HTTP dla treści żądania i treści odpowiedzi, która jest wspólna dla każdej operacji:

Aby zmienić ustawienie bramy poczty wychodzącej domeny, wyślij PUT HTTP na adres 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:

<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 działaniem elementy atom:property zawierają pojedynczą parę klucz-wartość zawierającą informacje o usłudze, którą chcesz pobrać lub zaktualizować. Są to elementy typowe dla wszystkich treści żądań do interfejsu Admin Settings API.

Element domyślnej odpowiedzi entry w domenie zwraca właściwości smartHost i smtpMode wraz ze składnią XML, która jest wspólna dla wszystkich treści odpowiedzi w interfejsie 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 użyciu tylko jednego 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 logowania jednokrotnego w Centrum pomocy. W kolejnych sekcjach przedstawiamy format XML używany do ustawień logowania jednokrotnego.

Odzyskiwanie ustawień logowania jednokrotnego

Aby pobrać ustawienia logowania jednokrotnego, wyślij HTTP HTTP GET na adres URL ogólnego kanału logowania jednokrotnego i dołącz nagłówek Authorization w sposób opisany 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 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>

Usługi te obejmują:

SAMLSignonUri,
Adres URL dostawcy tożsamości, na który Google Workspace wysyła żądanie SAML na potrzeby uwierzytelniania użytkownika.
Identyfikator URI logowania jednokrotnego
Adres, na który użytkownicy zostaną przekierowani po wylogowaniu się z aplikacji internetowej.
identyfikator URI zmiany hasła
Adres, na który zostaną przekierowani użytkownicy, którzy chcą zmienić swoje hasło do logowania w aplikacji internetowej.
włącz logowanie jednokrotne
Włącza logowanie jednokrotne oparte na SAML w tej domenie. Jeśli ustawienia logowania jednokrotnego zostały przez Ciebie skonfigurowane, a enableSSO został ustawiony na enableSSO=false, podane przez Ciebie ustawienia są nadal zapisywane.
Biała lista nadawców
Plik ssoWhite to adres IP maski sieci w formacie Classless Inter-Domain Routing (CIDR). Parametr ssoWhite 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ą SSO. Więcej informacji znajdziesz w artykule Jak działają maski sieci.
Użycie typu-wydawcy-specyfikacyjnego
W żądaniu SAML dostawcy tożsamości można użyć dostawcy określonej domeny. Chociaż nie jest to konieczne w przypadku większości wdrożeń SSO, ta funkcja jest przydatna dla dużych firm korzystających z jednego dostawcy tożsamości do uwierzytelniania całej organizacji z wieloma subdomenami. Podanie 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 się nie powiedzie, zostanie zwrócony inny kod stanu. Więcej informacji o kodach stanu interfejsu Google Data API znajdziesz w artykule Kody stanu HTTP.

Aktualizacja ustawień logowania jednokrotnego

Aby zaktualizować ustawienia logowania jednokrotnego w domenie, najpierw pobierz ustawienia SSO przy użyciu operacji Pobieranie ustawień logowania jednokrotnego, zmodyfikuj je, a następnie wyślij żądanie PUT na adres URL kanału SSO. Sprawdź, czy wartość <id> we zaktualizowanym wpisie dokładnie odpowiada wartości <id> w istniejącym wpisie. Dołącz nagłówek Authorization w sposób opisany w artykule Uwierzytelnianie w usłudze Admin Settings API. Komunikaty o błędach znajdziesz w artykule Rozwiązywanie problemów z logowaniem jednokrotnym.

Podczas aktualizowania ustawień logowania jednokrotnego wyślij URL 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 oraz kanał AtomPub z ustawieniami SSO.

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

Odzyskiwanie klucza podpisywania jednokrotnego

Aby pobrać klucz podpisywania jednokrotnego logowania, wyślij GET HTTP na adres URL kanału klucza podpisywania jednokrotnego i dołącz nagłówek Authorization w sposób opisany w artykule o uwierzytelnianiu 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 treści żądania.

Pomyślna odpowiedź zwraca kod stanu HTTP 200 OK wraz z kanałem 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 się nie powiedzie, 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

Aby zaktualizować klucz podpisywania domeny, najpierw pobierz klucz podpisywania, korzystając z operacji Pobieranie klucza podpisywania jednokrotnego logowania, zmodyfikuj go, a następnie wyślij żądanie PUT na adres URL kanału klucza podpisywania jednokrotnego. Sprawdź, czy wartość <id> we zaktualizowanym wpisie dokładnie odpowiada wartości <id> w istniejącym wpisie. Więcej informacji o kluczach logowania jednokrotnego opartych na SAML znajdziesz w artykule Generowanie kluczy i certyfikatów dla usługi logowania jednokrotnego Google Workspace.

Podczas aktualizowania klucza podpisywania jednokrotnego logowania wyślij żądanie HTTP PUT na adres URL kanału 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ą poczty e-mail i routingiem

W sekcji Brama poczty wychodzącej znajdziesz informacje o tym, jak interfejs Admin Settings API obsługuje routing poczty wychodzącej od użytkowników z Twojej domeny. W sekcji Routing poczty znajdziesz informacje o sposobie kierowania 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 dodaj nagłówek Authorization w sposób opisany w artykule Uwierzytelnianie w usłudze ustawień administratora:

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 i plik danych AtomPub wraz 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 się nie powiedzie, 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 domeny, 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:

hosta inteligentnego
Możesz wpisać adres IP lub nazwę hosta serwera SMTP. Google Workspace przekierowuje pocztę wychodzącą na ten serwer.
smtpMode
Wartość domyślna to SMTP. Inna wartość – SMTP_TLS – powoduje, że wiadomość jest dostarczana z TLS.

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

Jeśli z jakiegoś powodu żądanie się nie powiedzie, 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:

RouteDestination
Miejsce docelowe to nazwa hosta lub adres IP serwera poczty SMTP-In, na który jest przekierowywany e-mail. Nazwa hosta lub adres IP muszą być rozpoznawane przez Google. Więcej informacji o rozwiązywaniu problemów z nazwami hostów poczty znajdziesz w artykule Pilot Google Workspace z routingiem poczty e-mail.
routingRewriteTo
Jeśli ma wartość true (prawda), pole „to:” w kopercie SMTP wiadomości jest zmieniane na nazwę hosta docelowego (użytkownik@destination), a wiadomość jest dostarczana na ten adres użytkownika na docelowym serwerze poczty. W przypadku adresu false e-mail jest dostarczany na docelowy adres e-mail to: (użytkownik@oryginalna nazwa hosta) na docelowym serwerze poczty. Jest do podobne do ustawienia „Zmień kopertę SMTP” w konsoli administracyjnej. Więcej informacji znajdziesz w artykule Ustawienia routingu poczty e-mail w domenie.
RouteEnabled
Jeśli true, 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 może wysyłać powiadomienia o problemie z dostarczeniem w przypadku niepowodzenia dostarczenia wiadomości.
obsługa konta

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 miejsca docelowego.
  • provisionedAccounts – poczta będzie dostarczana do tego miejsca docelowego, jeśli użytkownik istnieje w Google Workspace;
  • unknownAccounts – jeśli użytkownik nie istnieje w Google Workspace, poczta może być dostarczana do tego miejsca docelowego. Działa to podobnie do ustawienia w konsoli administracyjnej. Więcej informacji o wymaganiach wstępnych i sposobie korzystania z routingu poczty znajdziesz w artykule Ustawienia routingu poczty e-mail w domenie. ~ Aby opublikować to żądanie, wyślij POST HTTP na adres URL kanału routingu poczty e-mail i dołącz nagłówek Authorization w sposób opisany w artykule o uwierzytelnianiu w usłudze Ustawienia administracyjne:

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

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

Jeśli z jakiegoś powodu żądanie się nie powiedzie, 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 zostaną wycofane 31 października 2018 r.

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