Admin Settings API の概要

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

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

Admin Settings API は Google Data API プロトコルを実装しています。Google Data API は、Atom パブリッシング プロトコル（AtomPub）のパブリッシング モデルと編集モデルに準拠しています。AtomPub HTTP リクエストは、ウェブサービスに Representational Set Transfer（RESTful）設計アプローチを使用します。詳しくは、Google Data デベロッパー ガイドをご覧ください。

オーディエンス

このドキュメントは、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 レスポンスがネットワーク転送中に変更されていないことを確認します。

SSO 設定の使用に関する API 固有の簡単な概要については、ID プロバイダから公開鍵証明書を取得し、Google に公開鍵を登録して、SAML ベースの SSO クエリ設定を設定します。エラー メッセージについては、SSO のトラブルシューティングをご覧ください。

  • 鍵を生成する - 認証プロバイダを使用して、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 の完全な構文を示しています。

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

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 要素は、取得または更新するプロパティに関する情報を含む単一の Key-Value ペアを表します。これらは、すべての Admin Settings API リクエストの本文に共通します。

ドメインのデフォルト言語レスポンスの entry 要素は、すべての Admin Settings API レスポンス本文に共通する XML 構文とともに、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'>
<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 形式について説明します。

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

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

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

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

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

GET レスポンス XML は、samlSignonUri、samlLogoutUri、changePasswordUri、enableSSO、ssoWhitelist、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>

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

samlSignonUri
Google Workspace がユーザー認証用の SAML リクエストを送信する ID プロバイダの URL。
samlLogoutUri
ウェブ アプリケーションからログアウトしたユーザーがリダイレクトされるアドレス。
changePasswordUri
ウェブ アプリケーションの SSO パスワードを変更するときにユーザーがリダイレクトされるアドレス。
enableSSO
このドメインで SAML ベースの SSO を有効にします。以前に SSO 設定を構成し、その後 enableSSO を enableSSO=false に設定した場合、以前に入力した設定は引き続き保存されます。
ssoWhitelist
ssoWhitelist は、クラスレス ドメイン間ルーティング（CIDR）形式のネットワーク マスク IP アドレスです。ssoWhitelist は、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 のトラブルシューティングをご覧ください。

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

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 ステータス コードをご覧ください。

対象のお客様が機密情報に関する操作に対する複数の関係者による承認を有効にしている場合、シングル サインオンの設定を変更することはできません。リクエストは errorCode="1811" と reason="LegacyInboundSsoChangeNotAllowedWithMultiPartyApproval" で失敗します。

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

シングル サインオン署名鍵を取得するには、SSO 署名鍵フィードの URL に HTTP GET を送信し、管理設定サービスへの認証で説明されているように Authorization ヘッダーを含めます。エラー メッセージについては、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 シングル サインオン サービス用の鍵と証明書を生成するをご覧ください。

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

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>

対象のお客様が機密情報に関する操作に対する複数の関係者による承認を有効にしている場合、シングル サインオンの設定を変更することはできません。リクエストは errorCode="1811" と reason="LegacyInboundSsoChangeNotAllowedWithMultiPartyApproval" で失敗します。

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

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

送信メール ゲートウェイの設定を取得しています

送信メール ゲートウェイの設定を取得するには、ゲートウェイ フィード URL に HTTP GET を送信し、管理設定サービスへの認証で説明されているように Authorization ヘッダーを含めます。

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 ステータス コードをご覧ください。

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

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

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

この設定により、ドメイン内のさまざまなタイプのユーザーがメール転送の影響を受ける仕組みが決まります。

  • allAccounts - すべてのメールをこの宛先に配信します。
  • provisionedAccounts - Google Workspace にユーザーが存在する場合は、この宛先にメールを配信します。
  • unknownAccounts - Google Workspace にユーザーが存在しない場合、メールをこの宛先に配信します。これは、管理コンソールの [配信メール] の設定に似ています。前提条件とメールのルーティングの使用方法について詳しくは、メールのルーティングのドメイン設定をご覧ください。~ このリクエストを公開するには、メール ルーティング フィード URL に HTTP POST を送信し、管理設定サービスへの認証で説明されているように 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