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 設定を行う - 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 要素は、取得または更新するプロパティに関する情報を含む単一のキーと値のペアを表します。これらは、すべての 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）機能を使用すると、ユーザーはログインとパスワードを一度入力するだけで、複数のサービスにログインできます。このパスワードは、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 設定を更新するには、まず Retrieve Single Sign-On settings オペレーションを使用して 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 シングル サインオン サービスの鍵と証明書の生成をご覧ください。

シングル サインオン署名鍵を更新するときは、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 ステータス コードをご覧ください。

メール ルーティング設定を管理する

まず、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@destination のホスト名）に変更され、メッセージが宛先メールサーバーのこのユーザー アドレスに配信されます。false の場合、メールは送信先のメールサーバーの元のメッセージの to: メールアドレス（user@元のホスト名）に配信されます。これは、管理コンソールの [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