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 リクエストは、ウェブサービスに対して Representational Set Transfer（RESTful）設計アプローチを使用します。詳細については、Google データ デベロッパー ガイドをご覧ください。

対象読者

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

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

はじめに

アカウントを作成する

Google Workspace アカウントで Admin Settings API が有効になっています。テスト用に Google Workspace アカウントを申し込みます。Admin Settings サービスでは 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 の [Single Sign-On] の設定を使用して、ドメインの 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 要素は、取得または更新するプロパティに関する情報を含む単一の 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 ヘッダーを含めます（管理者設定サービスの認証をご覧ください）。エラー メッセージについては、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 リクエストの発行者要素の仕組みをご覧ください。

なんらかの理由でリクエストが失敗した場合は、別のステータス コードが返されます。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 ヘッダーを含めます（管理者設定サービスの認証を参照）。エラー メッセージについては、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 ヘッダーを含めます（管理者設定サービスの認証を参照）。

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-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 に存在しない場合に、この宛先にメールを配信します。これは、管理コンソールの [メール配信先] の設定とほぼ同じです。前提条件とメール ルーティングの使用方法については、メール ルーティングのドメイン設定をご覧ください。 このリクエストを公開するには、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