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 Admin API の基本的な操作の例を紹介します。

このドキュメントは、Google Data API プロトコルの一般的なコンセプトを理解しており、Google Workspace 管理コンソールについて理解していることを前提としています。管理コンソールについて詳しくは、管理コンソールの使用についての記事をご確認ください。

はじめに

アカウントを作成する

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

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

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

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

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

SSO を構成するには、ユーザーのログイン情報を保存する ID プロバイダと通信するために Google Workspace サービスが必要とする情報と、ログイン、ログアウト、パスワードの変更のためにユーザーがリダイレクトされるリンクを設定する必要があります。Admin Settings API を使用すると、これらの設定をプログラムで更新して取得できます。Google は、生成された公開鍵を使用して ID プロバイダに対するこの SSO リクエストを検証し、ネットワークの送信中に秘密鍵の 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 構文を示しています。

ドメインの送信メールのゲートウェイ設定を変更するには、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）機能により、ユーザーはログインとパスワードを入力しなくても、複数のサービスにログインできます。このパスワードは、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 に設定した場合でも、以前に入力した設定は保存されます。
sso ホワイトリスト
sso ホワイトリストは、クラスレス ドメイン間ルーティング（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 ヘッダーを指定します。そのため、エラー メッセージについては、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>

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

スマートホスト
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@original hostname）に配信されます。これは、管理コンソールの [SMTP エンベロープの変更] 設定に似ています。詳しくは、メール ルーティングのドメイン設定をご覧ください。
routeEnabled
true の場合、メール ルーティング機能が有効になります。false の場合、この機能は無効になります。
bounceNotifications
true の場合、配信に失敗したときに Google Workspace から送信者にバウンス通知を送信できます。
accountHandling

この設定では、ドメイン内のユーザーの種類によるメール ルーティングの影響を指定します。

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