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 Publishing Protocol（AtomPub）の公開と編集のモデルに準拠しています。AtomPub HTTP リクエストは、ウェブ サービスに Representational Set Transfer（RESTful）設計アプローチを使用します。詳細については、Google Data APIs デベロッパー ガイドをご覧ください。

オーディエンス

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

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

使ってみる

Admin Settings API の使用を開始するには、まずアカウントを設定します。

アカウントを作成する

Google Workspace アカウントで Admin Settings API が有効になっている。テスト用に 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 のトラブルシューティングをご覧ください。

  • 鍵を生成する - ID プロバイダで、DSA または RSA アルゴリズムを使用して公開鍵と秘密鍵のペアを生成します。公開鍵は X.509 形式の証明書に含まれます。SAML ベースのシングル サインオン署名鍵について詳しくは、Google Workspace シングル サインオン サービスの鍵と証明書を生成するをご覧ください。
  • Google に登録する - Admin Settings API のシングル サインオン設定を使用して、公開鍵証明書を Google に登録します。
  • SSO 設定を行う - 管理設定 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 要素は、取得または更新するプロパティに関する情報を含む単一のキーと値のペアを表します。これらはすべての 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> と完全に一致していることを確認してください。管理設定 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 シングル サインオン サービスの鍵と証明書の生成をご覧ください。

シングル サインオン署名鍵を更新するときは、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>

対象のお客様が機密性の高い操作に対する複数の関係者による承認を有効にしている場合、シングル サインオン設定の変更は許可されません。リクエストは 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 ステータス コードをご覧ください。

エンドポイントのサポート終了日: 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