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 デベロッパー ガイドをご覧ください。

オーディエンス

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

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

スタートガイド

アカウントの作成

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

注: 管理設定 API を使用してドメイン設定を構成し、メール設定 API を使用してユーザーのメール設定を構成します。

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 は、生成された公開鍵を使用して、ID プロバイダでこの SSO リクエストを確認し、ネットワーク送信中に秘密鍵 SAML レスポンスが変更されていないことを確認します。

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

• 鍵を生成する - ID プロバイダで、DSA または RSA のアルゴリズムを使用して公開鍵と秘密鍵のセットを生成します。公開鍵は X.509 形式の証明書にあります。SAML ベースのシングル サインオン署名鍵の詳細については、Google Workspace シングル サインオン サービスの鍵と証明書を生成するをご覧ください。
• Google に登録する - 管理設定 API のシングル サインオン設定を使用して、公開鍵証明書を Google に登録します。
• SSO 設定を行う - Admin Settings API のシングル サインオン設定を使用して、ドメインの ID プロバイダのサーバーとの通信に使用する設定を構成します。

注: 一部の POP/IMAP メール クライアントなど、ウェブベースのログイン フローを使用しないプロトコルでは、ユーザーは Google Workspace のユーザー名とパスワードを使用して直接ログインします。

ゲートウェイとルーティングの設定

このフィードを使用すると、ドメイン管理者はドメインのメールのルーティングを制御できます。

メール転送オペレーションを使用すると、管理者はドメインレベルのメール転送設定を指定できます。これは、管理コンソールの 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> と完全に一致していることを確認します。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>

注: このリクエストには signingKey プロパティが必要です。

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

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

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

送信メール ゲートウェイの設定を取得する

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

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

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

注: Google Workspace アウトバウンド ゲートウェイ機能を使用するには、対象の Google Workspace エディションが必要です。

成功すると、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

注: Google Workspace アウトバウンド ゲートウェイ機能を使用するには、対象の Google Workspace エディションが必要です。

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 で接続を保護します。

注: Google Workspace から送信されたリレーメールを構成するには、メール転送エージェントの手順に沿って操作してください。

成功すると、レスポンスとして HTTP 200 OK ステータス コードと、メールゲートウェイ設定のステータスを含む AtomPub フィードが返されます。

注: 変更後、ゲートウェイ経由で送信された送信メールが機能していることを確認するには、Google Workspace からドメイン外のユーザーにメールを送信します。

リクエストが何らかの理由で失敗した場合は、別のステータス コードが返されます。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