Admin Settings API の概要

Google Workspace ドメインの管理者は、Admin Settings API を使用して、Google Data API フィードの形式でドメインの設定を取得、変更できます。

これらのドメイン設定には、Google Workspace 管理コンソールで利用できる機能の多くが含まれています。この API の使用例は、カスタム コントロール パネルを作成する、Google Workspace ドメインを既存の既存の環境に統合する、などです。

Admin Settings API は、Google Data API プロトコルを実装しています。Google Data API は、Atom Publishing Protocol(AtomPub)の公開および編集モデルに準拠しています。AtomPub HTTP リクエストは、ウェブサービスに対する RESTful(Representational Set Transfer)設計手法を使用します。詳しくは、Google データ デベロッパー ガイドをご覧ください。

対象

このドキュメントは、Google Workspace ドメインに関する情報を変更、取得できるクライアント アプリケーションを作成するデベロッパーを対象としています。XML と HTTP をそのまま使用する Admin Settings API の基本的なインタラクションの例を紹介します。

このドキュメントは、読者が Google Data API プロトコルの背後にある一般的な概念を理解し、Google Workspace 管理コンソールに精通していることを前提としています。管理コンソールについて詳しくは、管理コンソールを使用するをご覧ください。

はじめに

アカウントを作成する

Admin Settings API が Google Workspace アカウントに対して有効になっています。テスト用に Google Workspace アカウントに登録します。管理者設定サービスは Google アカウントを使用するため、すでに Google Workspace ドメインのアカウントをお持ちであれば、すべてご利用になれます。

Admin Settings API のフィードタイプについて

Admin Settings API を使用すると、次のカテゴリのドメイン設定を管理できます。

シングル サインオンの設定

SAML ベースのシングル サインオン(SSO)を使用すると、ユーザーは Google Workspace でホストされているサービスと、組織内でホストしているその他のサービスの両方に同じログイン情報とパスワードを使用できます。特に SSO を使用する場合、Google Workspace などのホストされたウェブ アプリケーションでユーザーを組織の ID プロバイダにリダイレクトし、ユーザーがログインしたときに認証します。詳しくは、Google Workspace の SAML ベースの SSO についてをご覧ください。

SSO を構成するには、Google Workspace サービスがユーザーのログイン情報を保管している ID プロバイダと通信するための必要な情報を入力し、ログイン、ログアウト、パスワードの変更のためにユーザーに送信するリンクを設定します。Admin Settings API を使用すると、これらの設定をプログラムで更新、取得することができます。Google は生成された公開鍵を使用して、この SSO リクエストを ID プロバイダで確認し、秘密鍵 SAML レスポンスがネットワーク送信中に変更されていないことを確認します。

ID プロバイダから公開鍵証明書を入手して公開鍵を Google に登録し、SAML ベースの SSO クエリの設定を行うと、API 固有の SSO 設定の概要を確認できます。エラー メッセージについては、SSO のトラブルシューティングをご覧ください。

  • 鍵の生成: ご利用の ID プロバイダで、DSA または RSA のアルゴリズムを使用して公開鍵と秘密鍵のセットを生成します。公開鍵は X.509 形式の証明書です。SAML ベースのシングル サインオン署名鍵について詳しくは、Google Workspace のシングル サインオン サービスの鍵と証明書の生成をご覧ください。
  • Google への登録 -- Admin Settings API のシングル サインオン設定を使用して、公開鍵証明書を Google に登録します。
  • SSO の設定 -- Admin Settings API のシングル サインオン設定を使用して、ドメインの ID プロバイダのサーバーとの通信に使用する設定を行います。

ゲートウェイとルーティングの設定

このフィードを使用すると、ドメイン管理者はドメインのメールのルーティングを管理できます。

管理者は、メール ルーティング操作を使用してドメインレベルのメール ルーティング設定を指定できます。これは、管理コンソールの Gmail の設定にあるメール ルーティング機能に似ています。詳しくは、メール ルーティングメール ルーティング機能の二重配信設定をご覧ください。

Admin Settings API の XML リクエストとレスポンスのサンプル

このドキュメントでは、XML と HTTP をそのまま使用する基本的な Admin Settings API のリクエストとレスポンスのコードサンプルについて説明します。このドメインのデフォルト言語の例は、各操作に共通するリクエストとレスポンスのエントリの本文に対する、完全な XML と HTTP の構文を示しています。

ドメインの送信メール ゲートウェイの設定を変更するには、HTTP PUT をゲートウェイ フィード URL に送信します。

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

ドメインのデフォルトの言語 PUT リクエストの 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>

オペレーション固有のプロパティと値を除き、atom:property 要素は、取得または更新するプロパティに関する情報を含む 1 つの Key-Value ペアを表します。これらは、すべての Admin Settings API リクエストの本文に共通です。

ドメインのデフォルトの言語レスポンスの entry 要素は、smartHost プロパティと smtpMode プロパティを、すべての Admin Settings API レスポンスの本文に共通する XML 構文とともに返します。

<?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>

シングル サインオン設定の管理

Google Workspace のシングル サインオン(SSO)機能を使用すると、ユーザーはログイン情報とパスワードを 1 回入力するだけで複数のサービスにログインできます。このパスワードは、Google Workspace ではなく、ドメインの ID プロバイダによって保存されます。詳しくは、ヘルプセンターの SSO に関するページをご覧ください。以降のセクションでは、シングル サインオン設定に使用される XML 形式について説明します。

シングル サインオン設定の取得

シングル サインオン設定を取得するには、HTTP GET を SSO 一般フィード URL に送信し、Authorization ヘッダーを含めます(Admin Settings サービスの認証を参照)。エラー メッセージについては、SSO のトラブルシューティングをご覧ください。

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

このオペレーションでは、リクエスト本文にパラメータはありません。

成功すると、HTTP ステータス コード 200 OK と、ドメインの SSO 設定を含む AtomPub フィードが返されます。

GET レスポンス XML は、samlSignonUrisamlLogoutUrichangePasswordUrienableSSOssoWhitelistuseDomainSpecificIssuer の各プロパティを返します。

<?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>

プロパティには次のものがあります。

samlSignonUri
Google Workspace がユーザー認証用の SAML リクエストを送信する ID プロバイダの URL。
samlLogoutUri
ユーザーがウェブ アプリケーションからログアウトしたときに表示されるアドレス。
changePasswordUri
ユーザーがウェブ アプリケーションの SSO パスワードを変更する場合の送信先アドレス。
enableSSO
このドメインに対して SAML ベースの SSO を有効にします。以前に SSO を設定した後、enableSSOenableSSO=false に設定した場合、以前に入力した設定が引き続き保存されます。
ssoWhitelist
ssowhite は、クラスレス ドメイン間ルーティング(CIDR)形式のネットワーク マスク IP アドレスです。sso ホワイトリストにより、どのユーザーが SSO を使用してログインし、どのユーザーが Google Workspace アカウント認証ページを使用してログインするかが決まります。マスクが指定されていない場合、すべてのユーザーが SSO を使用してログインします。詳細については、ネットワーク マスクの仕組みをご覧ください。
useDomainSpecificIssuer
ドメイン固有の発行元は、ID プロバイダへの SAML リクエストで使用できます。この機能は、ほとんどの SSO の導入では必要ありませんが、大企業が単一の ID プロバイダを使用して、複数のサブドメインを持つ組織全体を認証する場合に役立ちます。特定のドメイン発行者を指定することで、リクエストに関連付けるサブドメインが決まります。詳細については、SAML リクエストの Issuer 要素の仕組みをご覧ください。

なんらかの理由でリクエストが失敗した場合は、別のステータス コードが返されます。Google Data API のステータス コードについて詳しくは、HTTP ステータス コードをご覧ください。

シングル サインオン設定の更新

ドメインの SSO 設定を更新するには、まずシングル サインオン設定の取得処理を使用して SSO 設定を取得して変更し、それから SSO フィードの URL に PUT リクエストを送信します。更新したエントリの <id> 値が、既存のエントリの <id> と完全に一致することを確認してください。Admin Settings API サービスの認証の説明に従って、Authorization ヘッダーを含めます。エラー メッセージについては、SSO のトラブルシューティングをご覧ください。

シングル サインオン設定を更新するときに、HTTP PUT を SSO の一般的なフィード URL に送信します。

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

PUT リクエストの XML 本文は次のとおりです。

<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>

成功すると、HTTP ステータス コード 200 OK と、SSO 設定を含む AtomPub フィードが返されます。

PUT レスポンスの XML は次のとおりです。

<?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>

なんらかの理由でリクエストが失敗した場合は、別のステータス コードが返されます。Google Data API のステータス コードについて詳しくは、HTTP ステータス コードをご覧ください。

シングル サインオンの署名鍵の取得

シングル サインオンの署名鍵を取得するには、HTTP GET を SSO 署名鍵のフィード URL に送信し、Authorization ヘッダーを含めます(Admin Settings サービスの認証を参照)。エラー メッセージについては、SSO のトラブルシューティングをご覧ください。

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

このオペレーションでは、リクエスト本文にパラメータはありません。

成功すると、HTTP 200 OK ステータス コードと、署名鍵を含む AtomPub フィードが返されます。

GET レスポンスの XML は 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>

なんらかの理由でリクエストが失敗した場合は、別のステータス コードが返されます。Google Data API のステータス コードについて詳しくは、HTTP ステータス コードをご覧ください。

シングル サインオン署名鍵の更新

ドメインの SSO 署名鍵を更新するには、まずシングル サインオン署名鍵の取得操作を使用して署名鍵を取得して変更し、SSO 署名鍵のフィード URL に PUT リクエストを送信します。更新したエントリの <id> 値が、既存のエントリの <id> と完全に一致することを確認してください。SAML ベースのシングル サインオン署名鍵について詳しくは、Google Workspace のシングル サインオン サービスの鍵と証明書の生成をご覧ください。

シングル サインオンの署名鍵を更新する場合は、HTTP PUT を SSO 署名鍵のフィード URL に送信します。

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

PUT リクエスト XML は次のとおりです。

<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>

メール ゲートウェイとルーティングの管理

送信メール ゲートウェイのセクションでは、Admin Settings API がドメイン内のユーザーの送信メールのルーティングをどのようにサポートしているかを示します。[メール ルーティング] では、メールを別のメールサーバーに転送する方法について説明します。

送信メール ゲートウェイ設定の取得

送信メール ゲートウェイの設定を取得するには、HTTP GET をゲートウェイ フィード URL に送信し、Authorization ヘッダーを含めます(Admin Settings サービスの認証を参照)。

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

このオペレーションでは、リクエスト本文にパラメータはありません。

成功すると、HTTP 200 OK ステータス コードと、メール ゲートウェイのステータス情報を含む AtomPub フィードが返されます。

GET レスポンスは、smartHost プロパティと smtpMode プロパティを返します。これらのプロパティの詳細については、送信メールのゲートウェイ設定の更新をご覧ください。

考えられるレスポンスは次のとおりです。

<?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>

なんらかの理由でリクエストが失敗した場合は、別のステータス コードが返されます。Google Data API のステータス コードについて詳しくは、HTTP ステータス コードをご覧ください。

送信メール ゲートウェイ設定の更新

ドメインの送信メール ゲートウェイの設定を更新するには、HTTP PUT リクエストをゲートウェイのフィード URL に送信します。

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

PUT リクエスト 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>

リクエストのプロパティは次のとおりです。

smartHost
SMTP サーバーの IP アドレスまたはホスト名。Google Workspace は、送信メールをこのサーバーに転送します。
smtpMode
デフォルト値は SMTP です。もう 1 つの値 SMTP_TLS は、メッセージの配信時に TLS を使用して接続を保護します。

成功すると、HTTP 200 OK ステータス コードと、メール ゲートウェイの設定ステータスを含む AtomPub フィードが返されます。

なんらかの理由でリクエストが失敗した場合は、別のステータス コードが返されます。Google Data API のステータス コードについて詳しくは、HTTP ステータス コードをご覧ください。

メール ルーティング設定の管理

まず、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>

リクエストのプロパティは次のとおりです。

routeDestination
この送信先は、メールがルーティングされている SMTP メールサーバーのホスト名または IP アドレスです。ホスト名または IP アドレスは Google 用に解決される必要があります。メールホスト名の解決の詳細については、メール ルーティングを使用した Google Workspace の試験運用をご覧ください。
routeRewriteTo
true の場合、メッセージの SMTP エンベロープの to: フィールドが宛先ホスト名(user@destination のホスト名)に変更され、メールは宛先メールサーバー上のこのユーザー アドレスに配信されます。false の場合、メールは宛先メールサーバーにある元のメールの to: のメールアドレス(user@元のホスト名)に配信されます。これは、管理コンソールの [SMTP エンベロープの変更] の設定に似ています。詳細については、メール ルーティングのドメイン設定をご覧ください。
routeEnabled
true の場合、メール ルーティング機能が有効になります。false の場合、この機能は無効になります。
bounceNotifications
true に設定すると、配信が失敗したときに Google Workspace から送信者にバウンス通知が送信されるようになります。
accountHandling

この設定により、ドメイン内のさまざまなタイプのユーザーにメール ルーティングの影響がどのように適用されるかが決まります。

  • allAccounts -- すべてのメールをこの宛先に配信します。
  • provisionedAccounts - ユーザーが Google Workspace に存在する場合に、この宛先にメールを配信します。
  • unknownAccounts - ユーザーが Google Workspace に存在しない場合は、この宛先にメールを配信します。 これは、管理コンソールの [メール配信先] 設定に似ています。前提条件とメール ルーティングの使用方法については、メール ルーティングのドメイン設定をご覧ください。~ このリクエストを公開するには、HTTP POST をメール ルーティング フィード URL に送信し、Authorization ヘッダーを含めます(管理者設定サービスの認証を参照)。

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

成功すると、HTTP ステータス コード 200 OK とアーカイブ情報を含む AtomPub フィードが返されます。

なんらかの理由でリクエストが失敗した場合は、別のステータス コードが返されます。Google Data API のステータス コードについて詳しくは、HTTP ステータス コードをご覧ください。

エンドポイントは 2018 年 10 月 31 日に廃止

今回のお知らせの一環として、次のエンドポイントのサポートを終了いたしました。2018 年 10 月 31 日に廃止され、ご利用いただけなくなりました。

  • 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