お気に入り | 日本語 | ログイン

Google Provisioning API デベロッパー ガイド: プロトコル

最終更新日: 2007年8月7日 (最近の更新履歴)

目次

  1. 概要
  2. API の処理
  3. 認証
  4. API の動作
    1. XML リクエストのフォーマット
    2. XML レスポンスのフォーマット
    3. 結果のページネーション
  5. 補足情報
    1. 補足情報 A - Google Apps の設定
    2. 補足情報 B - XML タグの定義
    3. 補足情報 C - サンプル XML レスポンス
    4. 補足情報 D - Google Data エラーコード
    5. 補足情報 E - クライアント ライブラリのメソッド

概要

Google Apps を使用すると、ウェブサイト管理者は Gmail などのさまざまな個人向け Google アプリケーションの独自ドメイン バージョンをユーザーに提供することができます。このドキュメントで説明する Google Apps Provisioning API は、Google パートナーがプログラムを通じてこのようなアプリケーションにアクセスするために使用されます。この API は、特にユーザー アカウント、ニックネーム、メーリング リストの作成、取得、更新、削除のための機能を提供します。

このバージョンの Provisioning API は、Google Data API の原則に従っています。また、Atom 1.0 と RSS 2.0 の 2 つのシンジケーション フォーマットと、Atom Publishing Protocol に基づいています。Google Data API の詳細をご覧ください。

注: Provisioning API を使用できるのは、Google Apps Premier Edition と Google Apps Education Edition のパートナーのみです。API を使用するには、管理者アカウントでログインして、[ユーザー アカウント] タブをクリックします。次に、[設定] サブタブをクリックし、Provisioning API を有効化するチェックボックスをオンにして、変更を保存します (管理者アカウントでログインする前に、Google Apps の設定の手順を終了させる必要があります)。

(Google は、既に Provisioning API バージョン 1.0 を導入済みのパートナーへのサポートを継続しますが、新規パートナーはバージョン 2.0 の API を導入してください)

このドキュメントについて

このドキュメントには次のセクションがあります。

  • API の処理では、Provisioning API からアクセスできるさまざまなタイプの機能を紹介します。

  • 認証では、すべての API リクエストに必要な認証プロセスについて説明します。

  • API の動作では、さまざまなタイプの API リクエスト、各リクエストの XML フォーマット、各リクエストに対する API の XML レスポンスのフォーマットについて説明します。これらのセクションでは、全体として API の XML リクエストの構築方法と XML レスポンスの処理方法を説明します。

  • Java クライアント ライブラリの使用では、API の XML リクエストを作成し、適切な URL に送信して、リクエストに対する API レスポンスを処理する Google Apps Java クライアント ライブラリについて説明します。言い換えれば、このセクションでは API の動作のセクションで説明した処理を実行するための Java クライアント ライブラリの使用方法を説明します。

  • .NET クライアント ライブラリの使用では、以下で説明する処理を実行するための .NET クライアント ライブラリの使用方法を説明します。

  • Python クライアント ライブラリの使用では、以下で説明する処理を実行するための Python クライアント ライブラリの使用方法を説明します。

  • 補足情報では、Google Apps を使用するためのドメイン設定に関する背景情報を提供します。また、ここで論じられている XML ドキュメントについて、さらに詳しく説明します。

API の処理

API を使用するには、ドメイン内のリソースに対する作成、取得、更新、削除処理を実行するように指示する HTTP リクエストを Google に送信します。リソースとは、ユーザー アカウント、ニックネーム、メーリング リストです。

このセクションでは、API がサポートするさまざまなタイプの処理について説明します。以下のAPI の動作のセクションでは、各 API 処理に対応する URL を示します。注: 以下のリンクは、関連の Java クライアント ライブラリ メソッドを示すものです。その他のクライアント ライブラリでも、同等のメソッドが提供されています。

  • 作成処理では、新規のユーザー アカウント、ニックネーム、メーリング リストを追加できます。また、作成リクエストで、特定のメーリング リストにメールアドレスを追加することもできます。これらのいずれかの処理を実行するには、適切な URL に対する HTTP POST リクエストを発行します。POST リクエストのボディは、作成するリソースの情報を含む XML ドキュメントです。

  • 取得処理では、ユーザー アカウント、ニックネーム、メーリング リストに関する情報をリクエストし、取得することができます。これらのいずれかのリソースについての情報を取得するには、適切な URL に対する HTTP GET リクエストを発行します。URL には、要求されたリソースを識別する情報が含まれます。

  • 更新処理では、ユーザー アカウントに関する情報を変更できます。ユーザー アカウントを更新するには、適切な URL に対する HTTP PUT リクエストを発行します。PUT リクエストのボディは、更新するリソースに関する情報を含む XML ドキュメントです。API は、次のタイプの更新をサポートします。

    • ユーザーの姓、名、またはパスワードの更新
    • ユーザー アカウントのアクセスの停止、再開
    • ユーザーに割り当てられるディスク容量の更新 (この機能は、すべてのパートナーに提供されるものではありません)

    注: API はニックネームまたはメーリング リストの更新をサポートしません。ニックネームまたはメーリング リストを更新するには、古いエンティティを削除して、代わりに新しいエンティティを作成します。メーリング リストの登録者リストを更新するには、メーリング リスト受信者を作成または削除する API リクエストを使用する必要があります。

  • 削除処理では、ユーザー アカウント、ニックネーム、メーリング リストを削除することができます。また、削除リクエストで、メーリング リストからメール アドレスを削除することもできます。これらのいずれかの処理を実行するには、適切な URL に対する HTTP DELETE リクエストを発行します。URL には、削除するリソースを識別する情報が含まれます。

    注: アカウントを削除すると、少なくとも 5日間、同じユーザー名を持つアカウントを作成することができません。

Google では、すべての作成、更新リクエストに、必要なすべてのデータ フィールド、認証要件などを満たす有効な XML が含まれていることを検証します。

認証

API リクエストは、すべて HTTPS 経由で送信する必要があります。送信する API リクエストには、それぞれ認証トークンが含まれている必要があります。Google はこれを使用して、API リクエストで指定された処理へのアクセスを認証します。認証トークンを使用できるのは、ドメインの管理権限を持つユーザーのみです。また、これらのトークンはドメイン内の処理のみを認証します。

ClientLogin インターフェースでは、プログラムによるユーザー アカウントへのログインについての追加情報を提供します。

認証トークンの取得

認証トークンを取得するには、次の URL に HTTP POST リクエストを送信します。

https://www.google.com/accounts/ClientLogin

リクエストには次のガイドラインが適用されます。

  • POST のボディには、次の形式の文字列を含める必要があります。

    &Email=<email_address>&Passwd=<password>&accountType=HOSTED&service=apps

    この文字列を、次のように変更します。

    • <email_address> には管理者アカウントのメール アドレスを指定します。

    • <password> にはそのアカウントのパスワードを指定します。

  • メール アドレスとパスワードの値は、URL エンコードする必要があります。たとえば、メール アドレス apps.test.account@example.com を URL エンコードすると、apps%2Etest%2Eaccount%40example%2Ecom となります。

  • POST リクエストの Content-Type ヘッダーには、値 application/x-www-form-urlencoded を指定する必要があります。

Google は、POST リクエストへのレスポンスに認証トークンを含めます。認証トークンはそのページの Auth 値です。このページからトークンを抽出してください。API リクエストを送信するときは、次の例に示すように、Content-type と Authorization ヘッダーを設定する必要があります。

   Content-type: application/atom+xml
   Authorization: GoogleLogin auth=your-authentication-token

注: 認証トークンは 24 時間経過すると無効になります。上記の URL に、最低でも 24 時間に 1 回はリクエストを送信してください。トークンはファイルに書きだすのではなく、メモリに記憶しておくことをおすすめします。認証トークンの取得に際して CAPTCHA 入力を求められた場合の対処方法については、よくある質問をご覧ください。

認証トークン取得のサンプル コード

次の Perl スクリプトは、認証トークンを要求する HTTP POST リクエストの作成方法を示すものです。

   #! /usr/bin/perl -w

   use strict;
   use LWP::UserAgent;

   # Create an LWP object to make the HTTP POST request
   my $lwp_object = LWP::UserAgent->new;

   # Define the URL to submit the request to
   my $url = 'https://www.google.com/accounts/ClientLogin';

   # Submit the request with values for the Email, Passwd, 
   # accountType and service variables.
   my $response = $lwp_object->post( $url,
               [ 'accountType' => 'HOSTED',
                 'Email' => 'admin_email@example.com',
                 'Passwd' => 'admin_password',
                 'service' => 'apps'
               ]
   );

   die "$url error: ", $response->status_line unless $response->is_success;

   # Extract the authentication token from the response
   my $auth_token;
   foreach my $line (split/\n/, $response->content) {
       if ($line =~ m/^Auth=(.+)$/) {
           $auth_token = $1;
           last;
       }
   }

   print "authentication token is $auth_token\n";

このコードを使うには、Email と Passwd の値に、ホストされている管理者アカウントのメールアドレスとパスワードを指定します。

API の動作

API を使用して処理を実行するには、実行する処理に対応する URL に HTTP POST、GET、PUT、DELETE リクエストを送信する必要があります。各 URL にはドメインが指定されます。作成、取得、更新、削除を行うリソースを識別する変数が含まれることもあります。たとえば、www.example.com ドメインの us-sales メーリング リストについての情報を取得するには、次の URL に HTTP GET リクエストを送信します。 

https://www.google.com/a/feeds/www.example.com/emailList/2.0/us-sales

以下の項の表に、各 API 処理に対する URL を示します。また、各 API 処理に対する HTTP リクエストのタイプも示します。

作成リクエストと更新リクエスト (POST と PUT) を成功させるには、必ず必要な情報を含む XML ドキュメントを送信する必要があるということにも注意してください。コンテンツは、application/atom+xml コンテンツ タイプで送信する必要があります。これらの XML 構造については、表の下の XML リクエストのフォーマットのセクションで説明します。

次の表では、変数を太字の青い文字で強調表示しています。

ユーザー アカウントの作成、取得、更新、削除

処理 HTTP リクエスト タイプと URL
ユーザー アカウントの作成 POST https://www.google.com/a/feeds/{domain}/user/2.0
ユーザー アカウントの取得 GET https://www.google.com/a/feeds/{domain}/user/2.0/{userName}
ドメイン内の全ユーザーの取得 GET https://www.google.com/a/feeds/{domain}/user/2.0
ユーザー アカウントの更新 PUT https://www.google.com/a/feeds/{domain}/user/2.0/{userName}
ユーザー アカウントの削除 DELETE https://www.google.com/a/feeds/{domain}/user/2.0/{userName}

ニックネームの作成、取得、削除

処理 HTTP リクエスト タイプと URL
ニックネームの作成 POST https://www.google.com/a/feeds/{domain}/nickname/2.0
ニックネームの取得 GET https://www.google.com/a/feeds/{domain}/nickname/2.0/{nickname}
特定のユーザーの全ニックネームの取得 GET https://www.google.com/a/feeds/{domain}/nickname/2.0?username={userName}
ドメイン内の全ニックネームの取得 GET https://www.google.com/a/feeds/{domain}/nickname/2.0
ニックネームの削除 DELETE https://www.google.com/a/feeds/{domain}/nickname/2.0/{nickname}

メーリング リストの作成、取得、削除

処理 HTTP リクエスト タイプと URL
メーリング リストの作成 POST https://www.google.com/a/feeds/{domain}/emailList/2.0
メーリング リストの取得 GET https://www.google.com/a/feeds/{domain}/emailList/2.0/{emailListName}
特定のメールアドレスが登録されている全メーリング リストの取得 GET https://www.google.com/a/feeds/{domain}/emailList/2.0?recipient={emailAddress}
ドメイン内の全メーリング リストの取得 GET https://www.google.com/a/feeds/{domain}/emailList/2.0
メーリング リストの削除 DELETE https://www.google.com/a/feeds/{domain}/emailList/2.0/{emailListName}

メーリング リスト登録の変更、取得

処理 HTTP リクエスト タイプと URL
メーリング リストへのアドレス追加 POST
https://www.google.com/a/feeds/{domain}/emailList/2.0/{emailListName}/recipient/
メーリング リストの全登録者の取得 GET
https://www.google.com/a/feeds/{domain}/emailList/2.0/{emailListName}/recipient/
メーリング リストからのアドレス削除 DELETE
https://www.google.com/a/feeds/{domain}/emailList/2.0/{emailListName}/recipient/{emailAddress}

XML リクエストのフォーマット

情報を作成または更新する API リクエスト (HTTP POST、PUT リクエスト) では、ボディはリクエストを完了させるために必要なデータを含む XML ドキュメントでなければなりません。情報を取得または削除する API リクエスト (HTTP GET、DELETE リクエスト) では、URL と HTTP リクエスト タイプに Google がリクエストを完了させるために必要な情報がすべて指定されていなければなりません。

次の項では、ユーザー アカウント、ニックネーム、メーリング リスト、メーリング リスト受信者を作成する XML リクエストの例を示します。ユーザー アカウントを作成する XML リクエストは、ユーザー アカウントの更新にも使用できます (ニックネーム、メーリング リスト、メーリング リスト受信者は作成、取得、削除のみが可能で更新はできません)。

ユーザー データの XML フォーマット
ニックネーム データの XML フォーマット
メーリング リスト データの XML フォーマット
メーリング リスト受信者データの XML フォーマット

クライアント ライブラリを使用しているパートナー様へ: クライアント ライブラリは、これらの XML 構造を自動的に作成、送信するメソッドを提供します。次の XML サンプルを確認していただくことをお勧めしますが、Java クライアント ライブラリによる API リクエスト送信、.NET クライアント ライブラリによる API リクエスト送信、Python クライアント ライブラリによる API リクエスト送信のセクションでは、直接 XML を操作せずに、クライアント ライブラリを使用して API リクエストを送信し、API レスポンスを処理する方法を説明しています。

ユーザー データの XML フォーマット

次の XML は、ユーザーを作成するためのサンプル リクエストを示しています。この XML は、ユーザー アカウントの更新にも使用できます。なお、<apps:quota> を使用してユーザーのディスク容量の割り当てを設定する機能は、すべてのパートナーに提供されているものではありません。ドメインでこの機能を使用できるかどうかについては、パートナー契約をご覧ください。パートナーが設定するフィールドは、すべて太字で示されています。

注: この XML フォーマットには、クライアント ライブラリで UserEntry オブジェクトに格納できるデータがすべて含まれています。

<?xml version="1.0" encoding="UTF-8"?>
<atom:entry xmlns:atom="http://www.w3.org/2005/Atom"
  xmlns:apps="http://schemas.google.com/apps/2006">
    <atom:category scheme="http://schemas.google.com/g/2005#kind" 
        term="http://schemas.google.com/apps/2006#user"/>
    <apps:login userName="SusanJones-1321" 
        password="123$$abc" suspended="false"/>
    <apps:quota limit="2048"/>
    <apps:name familyName="Jones" givenName="Susan"/>
</atom:entry>

ユーザー アカウントの作成と更新のリクエストに同じ XML フォーマットが使用されても、これらのリクエストはいくつかの点で異なります。

  • ユーザーを作成するリクエストには、<apps:name> タグと属性 (familyName と givenName) が必要です。ユーザーを更新するリクエストには、ユーザーの姓または名前を更新するリクエストでない限り、このタグと属性を含める必要はありません。

  • ユーザーを作成するリクエストには <apps:login> タグが必要です。また、リクエストでは username と password 属性の値を指定する必要があります。ユーザーを更新するリクエストには、<apps:login> タグを含める必要はありません。なお、ユーザーのパスワードを更新するのでない限り、<apps:login> タグの password 属性の値を指定しないでください。

  • 通常、<apps:login> タグの suspended 属性は更新リクエストのみに使用されます (デフォルトでは、新規作成されたアカウントは有効)。

ニックネーム データの XML フォーマット

次の XML は、ニックネームを作成するためのサンプル リクエストを示しています。この XML は <apps:nickname> タグでニックネームを指定し、<apps:login> タグでニックネームを割り当てるユーザーを指定します。パートナーが設定するフィールドは、太字で示されています。

注: この XML フォーマットには、クライアント ライブラリで NicknameEntry オブジェクトに格納できるデータがすべて含まれています。

<?xml version="1.0" encoding="UTF-8"?>
<atom:entry xmlns:atom="http://www.w3.org/2005/Atom"
  xmlns:apps="http://schemas.google.com/apps/2006">
    <atom:category scheme="http://schemas.google.com/g/2005#kind" 
        term="http://schemas.google.com/apps/2006#nickname"/>
    <apps:nickname name="Susy-1321"/>
    <apps:login userName="SusanJones-1321"/>
</atom:entry>

メーリング リスト データの XML フォーマット

次の XML は、メーリング リストを作成するためのサンプル リクエストを示しています。この XML は <apps:emailList> タグでメーリング リストの名前を指定します。パートナーが設定するフィールドは、太字で示されています。

注: この XML フォーマットには、クライアント ライブラリで EmailListEntry オブジェクトに格納できるデータがすべて含まれています。

<?xml version="1.0" encoding="UTF-8"?>
<atom:entry xmlns:atom="http://www.w3.org/2005/Atom"
  xmlns:apps="http://schemas.google.com/apps/2006">
    <atom:category scheme="http://schemas.google.com/g/2005#kind" 
        term="http://schemas.google.com/apps/2006#emailList"/>
    <apps:emailList name="us-sales"/>
</atom:entry>

新規に作成されたメーリング リストには、登録者は含まれていません。この後は、さらに XML またはクライアント ライブラリ (Java、.NET、Python) を使用してメーリング リストに受信者を追加する方法について説明します。

メーリング リスト受信者データの XML フォーマット

次の XML は、メーリング リストにメール アドレスを登録するためのサンプル リクエストを示しています。この XML は、<gd:who> タグで追加するメール アドレスを指定します。パートナーが設定するフィールドは、太字で示されています。

注: この XML フォーマットには、クライアント ライブラリで EmailListRecipientEntry オブジェクトに格納できるデータがすべて含まれています。

<?xml version="1.0" encoding="UTF-8"?>
<atom:entry xmlns:atom="http://www.w3.org/2005/Atom"
  xmlns:apps="http://schemas.google.com/apps/2006"
    xmlns:gd='http://schemas.google.com/g/2005">
    <atom:category scheme="http://schemas.google.com/g/2005#kind" 
        term="http://schemas.google.com/apps/2006#emailList.recipient"/>
    <gd:who xmlns="http://schemas.google.com/g/2005"
        email="SusanJones-6389@example.com"/>
</atom:entry>

XML レスポンスのフォーマット

Google Apps Provisioning API は、API リクエストに基づいて 10 種類のレスポンスのいずれかを返します。以下に、レスポンスの種類とそのレスポンスを生成させる API リクエストの説明を示します。補足情報 C では、上から 9 番目までのレスポンスについて、それぞれの XML サンプルを示します (10 番目のレスポンス タイプは、XML を使用しません)。

注: 個別のレスポンス タイプの定義に使用する用語は、クライアント ライブラリで使用されるオブジェクト名に従います。たとえば、次のリストの UserEntry レスポンスは、単一のユーザーについての情報を含む XML ドキュメントとして定義されます。クライアント ライブラリは、この XML レスポンスを UserEntry オブジェクトに変換します。

  1. UserEntry レスポンスには単一のユーザーについての情報が含まれます。ユーザーを作成、取得、更新、停止、復元、再開する API リクエストは、すべて UserEntry レスポンスを生成させます。

  2. UserFeed レスポンスには、1 つまたは複数の一連の UserEntry XML 構造が含まれ、それぞれに単一ユーザーについての情報が含まれています。UserFeed レスポンスを生成する API リクエストは、ドメインの全ユーザー取得のリクエストのみです。

  3. NicknameEntry レスポンスには、単一のニックネームについての情報が含まれます。これにより、ニックネームと、そのニックネームを割り当てるユーザーが示されます。ニックネームを作成する API リクエスト、取得する API リクエストは、いずれも NicknameEntry レスポンスを生成させます。

  4. NicknameFeed レスポンスには、1 つまたは複数の一連の NicknameEntry XML 構造が含まれ、それぞれによってニックネームと、そのニックネームを割り当てるユーザーが示されます。ドメインの全ニックネームを取得する API リクエスト、特定ユーザーに割り当てられている全ニックネームを取得する API リクエストは、いずれも NicknameFeed レスポンスを生成させます。

  5. EmailListEntry レスポンスには、単一のメーリング リストについての情報と、そのメーリング リストの受信者のリストを取得するリンクが含まれます。メーリングリストを作成する API リクエスト、取得する API リクエストは、いずれも EmailListEntry レスポンスを生成させます。

  6. EmailListFeed レスポンスには、1 つまたは複数の一連の EmailListEntry レスポンスが含まれます。ドメインの全メーリング リストを取得する API リクエスト、特定ユーザーが受信する全メーリング リストを取得する API リクエストには、いずれも EmailListFeed レスポンスが返されます。

  7. EmailListRecipientEntry レスポンスは、特定のメーリング リストに登録されている個別のユーザーを示します。メーリング リストに受信者を追加する API リクエストは、EmailListRecipientEntry レスポンスを生成させます。

  8. EmailListRecipientFeed レスポンスには、1 つまたは複数の一連の EmailListRecipientEntry レスポンスが含まれ、それぞれによって特定のメーリング リストに登録しているユーザーが示されます。特定のメーリング リストの全受信者を取得する API リクエストは、EmailListRecipientFeed レスポンスを生成させます。

  9. 無効な API リクエストに対しては、API によってエラー の XML レスポンスが返されます。すべての API リクエストに、エラー レスポンスを発生させる可能性があります。レスポンスでは、<error> タグの値によって API リクエストが無効である理由が示されます。Java クライアント ライブラリと Python クライアント ライブラリは、Provisioning API からエラー レスポンスを受け取ると、AppsForYourDomainException を返します。.NET クライアント ライブラリは、AppsException オブジェクトを返します。このオブジェクトにはエラー情報が含まれます。また、クライアント ライブラリはエラーのタイプによって異なる例外をスローします。詳しくは、「API レスポンスに含まれるエラーの識別」のセクション (Java、.NET、Python) の説明をご覧ください。

  10. HTTP DELETE リクエストが成功すると、いずれの場合も API から HTTP 200 レスポンス コードが返されます。これにはユーザー アカウント、ニックネーム、メーリング リストの削除と、メーリング リストからの受信者の削除が含まれます。

9 タイプの XML レスポンスのサンプルを補足情報 C - サンプル XML レスポンスに示します (最後の HTTP 200 レスポンス コードは、XML を使用しません)。

結果のページネーション

API リクエストによって UserFeed、NicknameFeed、EmailListFeed、EmailListRecipientFeed レスポンスが発生した場合、Provisioning API は最大 100 個のエントリを含む Atom XML フィードを返します。フィードに 100 を超えるエントリがある場合、API レスポンスには rel 属性が next となっている <atom:link> タグが含まれます。この <atom:link> タグの URL は、リクエストに対する結果の続きのページを指します。

以下の XML の抜粋では、結果の続きのページを示す <atom:link> タグを太字で強調してあります。

<?xml version="1.0" encoding="UTF-8"?>
<atom:id>
    http://www.google.com/a/feeds/example.com/emailList/2.0
</atom:id>
<atom:category scheme="http://schemas.google.com/g/2005#kind"
    term="http://schemas.google.com/apps/2006#emailList"/>
<atom:title type="text">EmailLists</atom:title>
<atom:link rel="next" type="application/atom+xml"
    href="http://www.google.com/a/feeds/example.com/emailList/2.0?startEmailListName=eng"/>
<atom:link rel="http://schemas.google.com/g/2005#feed"
    type="application/atom+xml"
    href="http://www.google.com/a/feeds/example.com/emailList/2.0"/>
...

全ユーザー、全ニックネーム、全メーリング リスト、メーリング リストの全受信者のいずれかを取得するリクエストが完了するまでの時間は、取得されるデータの量に直接関係します。たとえば、メーリング リストの登録者が 100 人ならば、クライアント ライブラリは 1 つの HTTP リクエストで全登録者のリストを取得できます。しかし、メーリング リストの登録者が 1,000 人の場合は、全登録者のリストを取得するために 10 の HTTP リクエストを作成しなければなりません。

  • Java、.NET、または Python クライアント ライブラリを使用しているのであれば、コードによって結果の追加ページを明示的に要求するか、またはすべての結果が得られるまで追加の結果を自動的に要求するかを選択できます。たとえば、retrievePageOfUsers メソッドで最大 100 ユーザーまでの HTTP リクエストを 1 つ作成し、retrieveAllUsers メソッドですべての結果が得られるまで追加の HTTP リクエストを自動的に発行することができます。

  • API レスポンスを処理するコードを自分で作成する場合は、必要に応じて結果の追加ページを要求するようなコードを作成する必要があります。

補足情報

補足情報 A - Google Apps の設定

Google Apps を設定するには、ドメインの管理者アカウントとして機能する Google アカウントを作成する必要があります。既存の Google アカウントを使用することも可能です。ただし、アカウントの所有者はドメインのユーザー アカウントを作成、更新、削除できることになるので、個人の Google アカウントを使用するのではなく、新しい Google アカウントを作成することをお勧めします。

以下に、Google Apps を設定する手順を説明します。

  1. Google Apps のホームページにアクセスし、説明に従って Google Apps Premier Edition (企業向け) または Google Apps Education Edition (教育機関向け) にサインアップします。

  2. ドメイン名を入力します。または、新規ドメインの購入を指定します。新規ドメインを購入する場合は、次の手順に進む前に新規ドメインの登録フォームに入力する必要があります。

  3. フォームに、所属組織と自分自身についての情報を入力します。

  4. 次のページのフォームに、購入するユーザー アカウントの数を指定して、利用規約に同意します。

  5. Google Checkout を使用して、登録処理を終了します。

  6. フォームに入力して、管理者アカウントを設定します。

  7. 説明に従って、ドメインの所有を確認します。

  8. 管理者アカウント用のメール アドレスとパスワードを使用して、ドメインの認証トークンを要求します。認証トークンは、Google に送信するすべての API リクエストに含まれて送信され、Google はその API リクエストの実行を認証するために認証トークンを使用します。

補足情報 B - XML タグの定義

この補足情報では、Provisioning API リクエストとレスポンスで使用される XML タグの定義を説明します。

サブタグの凡例

下記の定義では、サブタグの横に記号が表示されている場合があります。これらの記号は、それぞれ次のような意味があります。

? = オプションのサブタグ
* = 0 以上のサブタグ
+ = 1 以上のサブタグ
| = Boolean OR

atom:feed
定義

<atom:feed> タグは、特定のアカウントに関連する全ニックネームの取得、または特定のアカウントで登録している全メーリング リストの取得のリクエストに対する API レスポンスをカプセル化します。
例 <atom:feed xmlns="http://www.w3.org/2005/Atom" xmlns:openSearch="http://a9.com/-/spec/opensearchrss/1.0/">
サブタグ atom:id、atom:category、atom:link、openSearch:startIndex、openSearch:itemsPerPage、atom:entry
コンテンツ フォーマット コンテナ

atom:entry
定義

<atom:entry> タグは、API リクエストまたは API Atom レスポンスをカプセル化します。
サブタグ atom:id、atom:category、atom:title、atom:link、apps:login、apps:name、gd:feedLink、gd:who
コンテンツ フォーマット コンテナ

atom:category
定義

<atom:category> タグは、Atom リクエストまたはレスポンスに記述されるリソースのタイプを示します。
属性
名前 フォーマット 説明
scheme テキスト この属性は、リソース タイプを定義する XML スキーマを示します。属性値は、http://schemas.google.com/g/2005#kind に設定してください。
term テキスト この属性は、エントリが属するカテゴリを示します。API リクエストを送信する場合は、下のリストの適切な値を使用してください。

リソースのタイプ URL
アカウント http://schemas.google.com/apps/2006#user
ニックネーム http://schemas.google.com/apps/2006#nickname
メーリング リスト http://schemas.google.com/apps/2006#emailList

API の XML レスポンスでも、適切な値が返されます。
上位のタグ atom:entry
コンテンツ フォーマット 空

atom:title
定義

<atom:title> タグの値は、API レスポンスを示します。
属性
名前 フォーマット 説明
type 文字列

この属性は、タグの値のコンテンツ フォーマットを示します。type 属性の値はテキストである必要があります。
例 <atom:title type="text">SusanJones-1321</atom:title>
上位のタグ atom:entry
コンテンツ フォーマット 複合

atom:id
定義

<atom:id> タグの値は、フィードの恒久的でユニークな識別子を示します。このタグは API レスポンスに含まれます。また、ユーザー アカウント更新のリクエストにも含まれます。このタグを API リクエストに含めるときは、タグの値として API リクエストの送信先 URL を設定する必要があります。
例 <atom:id>http://www.google.com/a/feeds/example.com/emailList/2.0/us-sales</atom:id>
上位のタグ atom:entry
コンテンツ フォーマット 文字列 (IRI)

atom:link
定義

<atom:link> タグは、API 結果フィードまたはフィード内のリソースに関連する IRI リファレンスを提供します。
属性
名前 フォーマット 説明
rel テキスト

rel 属性は、API レスポンス フィードへのリンクの関係を示します。

  • rel 属性の値が self である場合は、href 属性値はフィードを要求するために使用する URL へのリンクとなります。

  • rel 属性の値が edit である場合は、href 属性値はリソースの取得、更新、または削除に使用する URL となります。注: リソースを取得するには HTTP GET リクエスト、リソースを更新するには HTTP PUT リクエスト、リソースを削除するには HTTP DELETE リクエストを使用します。

  • rel 属性の値が next である場合は、href 属性値にはリクエスト結果の次のページを取得するために使用する URL を指定します。詳しくは、このドキュメントの結果のページネーションのセクションをご覧ください。
href テキスト href 属性には、API レスポンスに含まれる情報の取得または編集方法を示す IRI リファレンスを指定します。
例 <atom:link rel="edit" type="application/atom+xml" href="http://www.google.com/a/feeds/example.com/emailList/2.0/us-sales"/>
上位のタグ atom:entry
コンテンツ フォーマット 空

atom:updated
定義

<atom:updated> タグは、Atom フィードに含まれるエントリが更新された日時を示します。Provisioning API のレスポンスにはこのタグが含まれるので、レスポンスは Atom の仕様に準拠しています。ただし、Provisioning API では、<atom:updated> タグの値は常に 1970年の日付となり、値は機能しません。
例 <atom:updated>1970-01-01T00:00:00.000Z</atom:updated>
上位のタグ atom:feed、atom:entry
コンテンツ フォーマット 日付

apps:emailList
定義

<apps:emailList> タグは、メーリング リストを示します。
属性
名前 フォーマット 説明
name テキスト name 属性はメーリング リストを示します。name 属性は必須です。
例 <apps:emailList name="us-sales"/>
上位のタグ atom:entry
コンテンツ フォーマット 複合

apps:login
定義

<apps:login> タグはユーザー アカウントに関連するユーザー名を示します。パスワードを示すこともあります。
属性
名前 フォーマット 説明
userName テキスト

userName 属性はユーザー アカウントに関連するユーザー名を示します。ユーザー アカウントまたはニックネームを作成するリクエストでは、userName 属性は必須です。ただし、ユーザー アカウント更新のリクエストでは任意です。ユーザー名に使用できる文字については、こちらで確認してください。

  • アカウント作成のリクエストでは、userName 属性は新規アカウントの名前を示します。
  • アカウント更新のリクエストでは、userName 属性は更新するアカウントを示します。
  • ニックネーム作成のリクエストでは、userName 属性はニックネームを作成するアカウントを示します。
password テキスト

password 属性は、ユーザー アカウントのパスワードを示します。パスワードは、6 文字以上で構成する必要があります。

アカウント作成のリクエストでは、password 属性は必須です。ただし、アカウント更新のリクエストではオプションで、そのアカウントのパスワードを更新する場合のみ指定します。

注: API レスポンスでは、この属性は返されません。
hashFunctionName テキスト

hashFunctionName 属性は password 属性の値のフォーマットを示します。現在、この属性として有効な値は「SHA-1」のみです。この属性を指定する場合、password はプレーン テキストではなくハッシュ値です。

例:

password="tiddlyWinkles"

とプレーン テキストで送信するのではなく、次のように password の値として「tiddlyWinkles」の SHA-1 ハッシュ値、hashFunctionName の値として「SHA-1」を送信することができます。

password="51eea05d46317fadd5cad6787a8f562be90b4446"
hashFunctionName="SHA-1"
admin テキスト

admin 属性は、ユーザーが管理者であるかどうかを示します。

  • ユーザーのステータスを管理者にするには、リクエストに含める admin 属性の値を true とします。
  • 特定のユーザーから管理者ステータスを取り除くには、リクエストに含める admin 属性の値を false とします。
  • リクエストから admin 属性を省略すると、Google はユーザー アカウントのステータスを更新しません。
agreedToTerms テキスト

agreedToTerms 属性は、ユーザーが利用規約に同意しているかどうかを示します。これは読み取り専用の属性です。

suspended テキスト

suspended 属性は、ユーザーアカウントが停止されているかどうかを示します。

  • ユーザー アカウントを停止するには、リクエストに含める suspended 属性の値を true とします。
  • 停止されたアカウントにユーザーが再びアクセスできるように戻すには、リクエストに含める suspended 属性の値を false とします。
  • リクエストから suspended 属性を省略すると、Google はユーザー アカウントのステータスを更新しません。
changePasswordAtNextLogin テキスト

changePasswordAtNextLogin 属性は、ユーザーが次回ログインする際に、強制的にパスワードを変更させるかどうかを示します。

  • ユーザーが次回ログインする際に強制的にパスワードを変更させる場合は、リクエストに含める changePasswordAtNextLogin 属性の値を true とします。
  • ユーザーが次回ログインする際にパスワードを変更しなくてもいいようにする場合は、リクエストに含める changePasswordAtNextLogin 属性の値を false とします。
  • リクエストから changePasswordAtNextLogin 属性を省略すると、Google はユーザー アカウントのステータスを更新しません。
例 <apps:login userName="SusanJones" suspended="false" admin="false" changePasswordAtNextLogin="false" agreedToTerms="true"/>
上位のタグ atom:entry
コンテンツ フォーマット 複合

apps:name
定義

<apps:name> タグは、アカウント所有者の姓と名を示します。姓と名に使用できる文字はスペース、英文字 (a～z)、数字 (0～9)、ダッシュ (-)、スラッシュ (/)、ピリオド (.) です。
属性
名前 フォーマット 説明
familyName テキスト familyName 属性は、ユーザーの姓を示します。familyName 属性は必須です。
givenName テキスト givenName 属性は、ユーザーの名前を示します。givenName 属性は必須です。
例 <apps:name familyName="Jones" givenName="Susan"/>
上位のタグ atom:entry
コンテンツ フォーマット 複合

apps:nickname
定義

<apps:nickname> タグは、ニックネームを示します。
属性
名前 フォーマット 説明
name テキスト name 属性は、ニックネームを示します。name 属性は必須です。
例 <apps:nickname name="Jones"/>
上位のタグ atom:entry
コンテンツ フォーマット 複合

apps:quota
定義

<apps:quota> タグは、ユーザー アカウントに割り当てられるディスク容量を示します。Google では、ユーザー アカウントにデフォルトで 2 GB のディスク容量が割り当てられます。

  • 契約上、有効な追加容量を割り当てることができるドメインでは、ユーザー アカウントを作成するリクエストで <apps:quota> タグを使用して値を指定する必要があります。

  • 契約上、有効な追加容量を割り当てることができないドメインでは、ユーザー アカウントを作成するリクエストから <apps:quota> を省略してかまいません。
属性
名前 フォーマット 説明
limit 整数値

limit 属性は、ユーザー アカウントに割り当てるディスク容量を、メガバイト (MB) で示します。limit 属性は必須です。
例 <apps:quota limit="2048"/>
上位のタグ atom:entry
コンテンツ フォーマット 複合

gd:feedLink
定義

<gd:feedLink> タグには、論理的にネストされた API レスポンスに関連するフィードについての情報が指定されます。たとえば、ユーザー アカウントについての情報を取得する場合、API レスポンスには 2 つの <gd:feedLink> タグが指定されます。一方のタグには取得されたアカウントに関する、ニックネームのフィードの情報、もう一方のタグには、そのアカウントが登録しているメーリング リストのフィードに関する情報が指定されます。
属性
名前 フォーマット 説明
rel テキスト rel 属性は、ネストされたフィードに含まれるコンテンツのタイプを示します。属性値の末尾が user.nicknames の場合、フィードにはユーザー アカウントに関するニックネームのリストが指定されます。属性値の末尾が #user.emailLists の場合、フィードにはユーザー アカウントが登録しているメーリング リストのリストが指定されます。
href テキスト href 属性は、関連するフィードの取得に使用する URI を示します。
例 <gd:feedLink rel="http://schemas.google.com/apps/2006#user.emailLists" href="http://www.google.com/a/feeds/example.com/emailList/2.0?recipient=us-sales@example.com"/>
上位のタグ atom:entry
コンテンツ フォーマット 複合

gd:who
定義

<gd:who> タグは API レスポンスに関連付けられた個人を示します。このタグは、API リクエストで個人をメーリング リストに追加するために使用されます。また、API レスポンスでは、メーリング リストの更新または取得を要求するために使用されます。
属性
名前 フォーマット 説明
email テキスト email 属性は、メーリング リストに登録するメール アドレスを示します。メール アドレスは、ドメインでホストされたメール アカウントのものでも、外部ドメインのアドレスでもかまいません。email 属性は必須です。
例 <gd:who email="SusanJones-1321@example.com"/>
上位のタグ atom:entry
コンテンツ フォーマット 複合

openSearch:startIndex
定義

<openSearch:startIndex> 値は、結果として返される最初の項目の、1 から始まるインデックスを示します。
例 <openSearch:startIndex>1</openSearch:startIndex>
上位のタグ atom:feed
コンテンツ フォーマット 整数値

openSearch:itemsPerPage
定義

<openSearch:itemsPerPage> 値は、API レスポンスに含まれる項目の総数を示します。
例 <openSearch:itemsPerPage>10</openSearch:itemsPerPage>
上位のタグ atom:feed
コンテンツ フォーマット 整数値

AppsForYourDomainErrors
定義

<AppsForYourDomainErrors> タグは、API リクエストが失敗した理由を示す <error> タグのリストをカプセル化します。
例 <AppsForYourDomainErrors>
サブタグ error
コンテンツ フォーマット コンテナ

error
定義

<error> タグには、Google が API リクエストの処理に失敗した理由を示す情報が指定されます。
属性
名前 フォーマット 説明
errorCode テキスト

errorCode 属性は、API リクエストの失敗の原因となったエラーのタイプを示します。以下に、この属性の有効値のリストを示します。これらのコードについての詳細は、補足情報 D - Google Data エラーコードをご覧ください。

  • UnknownError(1000)
  • UserDeletedRecently(1100)
  • UserSuspended(1101)
  • DomainUserLimitExceeded(1200)
  • DomainAliasLimitExceeded(1201)
  • DomainSuspended(1202)
  • DomainFeatureUnavailable(1203)
  • EntityExists(1300)
  • EntityDoesNotExist(1301)
  • EntityNameIsReserved(1302)
  • EntityNameNotValid(1303)
  • InvalidGivenName(1400)
  • InvalidFamilyName(1401)
  • InvalidPassword(1402)
  • InvalidUsername(1403)
  • InvalidHashFunctionName(1404)
  • InvalidHashDigestLength(1405)
  • InvalidEmailAddress(1406)
  • InvalidQueryParameterValue(1407)
  • TooManyRecipientsOnEmailList(1500)
reason テキスト reason 属性では、エラーの簡単な説明が示されます。
invalidInput テキスト invalidInput 属性には、API レスポンスの失敗の原因となったデータが指定されます。この属性は、すべてのエラー タイプについて提供されるわけではありません。
例 <error errorCode="1301" reason="EntityDoesNotExist" invalidInput="Some-Nonexistent-User"/>
上位のタグ AppsForYourDomainErrors
コンテンツ フォーマット 複合

補足情報 C - サンプル XML レスポンス

サンプル UserEntry レスポンス
 
サンプル UserFeed レスポンス
 
サンプル NicknameEntry レスポンス

サンプル NicknameFeed レスポンス
 
サンプル EmailListEntry レスポンス
 
サンプル EmailListFeed レスポンス
 
サンプル EmailListRecipientEntry レスポンス
 
サンプル EmailListRecipientFeed レスポンス
 
サンプル Failure レスポンス
 

サンプル UserEntry レスポンス

Provisioning API は、ユーザー アカウントの作成、取得、更新のいずれの場合も、同じフォーマットの Atom XML レスポンスを返します。以下の XML は、ユーザー アカウントの情報を変更する API レスポンスのサンプルです。クライアント ライブラリは、この XML を UserEntry オブジェクトに変換します。

<?xml version="1.0" encoding="UTF-8"?>
<atom:entry xmlns:atom="http://www.w3.org/2005/Atom"
  xmlns:apps="http://schemas.google.com/apps/2006"
  xmlns:gd="http://schemas.google.com/g/2005">
    <atom:id>https://www.google.com/a/feeds/example.com/user/2.0/SusanJones</atom:id>
    <atom:updated>1970-01-01T00:00:00.000Z</atom:updated>
    <atom:category scheme="http://schemas.google.com/g/2005#kind"
        term="http://schemas.google.com/apps/2006#user"/>
    <atom:title type="text">SusanJones</atom:title>
    <atom:link rel="self" type="application/atom+xml" 
        href="https://www.google.com/a/feeds/example.com/user/2.0/SusanJones"/>
    <atom:link rel="edit" type="application/atom+xml" 
        href="https://www.google.com/a/feeds/example.com/user/2.0/SusanJones"/>
    <apps:login userName="SusanJones" suspended="false" admin="false" changePasswordAtNextLogin="false" agreedToTerms="true"/>
    <apps:name familyName="Jones" givenName="Susan"/>
    <gd:feedLink rel="http://schemas.google.com/apps/2006#user.nicknames" 
        href="https://www.google.com/a/feeds/example.com/nickname/2.0?
	username=Susy-1321"/>
    <gd:feedLink rel="http://schemas.google.com/apps/2006#user.emailLists" 
        href="https://www.google.com/a/feeds/example.com/emailList/2.0?
	recipient=us-sales@example.com"/>
</atom:entry>

サンプル UserFeed レスポンス

ドメインの全ユーザーを取得するリクエストを送信すると、Provisioning API はユーザーのリストを含む Atom XML フィードを返します。これは、それぞれ <atom:entry> の XML ブロックに示されます。クライアント ライブラリは、このフィードを UserFeed オブジェクトに変換します。これには、一連の UserEntry オブジェクトが含まれます。

以下の XML は、ドメインの全ユーザーを取得するリクエストに対する API レスポンスのサンプルです。

<?xml version="1.0" encoding="UTF-8"?>
<atom:feed xmlns:atom="http://www.w3.org/2005/Atom" 
  xmlns:apps="http://schemas.google.com/apps/2006"
  xmlns:openSearch="http://a9.com/-/spec/opensearchrss/1.0/"
  xmlns:gd="http://schemas.google.com/g/2005">
    <atom:id>
        http://www.google.com/a/feeds/example.com/user/2.0
    </atom:id>
    <atom:updated>1970-01-01T00:00:00.000Z</atom:updated>
    <atom:category scheme="http://schemas.google.com/g/2005#kind" 
        term="http://schemas.google.com/apps/2006#user"/>
    <atom:title type="text">Users</atom:title>
    <atom:link rel="next" type="application/atom+xml" 
        href="http://www.google.com/a/feeds/example.com/user/2.0?startUsername=john"/>
    <atom:link rel="http://schemas.google.com/g/2005#feed" 
        type="application/atom+xml" 
        href="http://www.google.com/a/feeds/example.com/user/2.0"/>
    <atom:link rel="http://schemas.google.com/g/2005#post" 
        type="application/atom+xml"
        href="http://www.google.com/a/feeds/example.com/user/2.0"/>
    <atom:link rel="self" type="application/atom+xml" 
        href="http://www.google.com/a/feeds/example.com/user/2.0"/>
    <openSearch:startIndex>1</openSearch:startIndex>
    <atom:entry>
        <atom:id>
            http://www.google.com/a/feeds/example.com/user/2.0/SusanJones
        </atom:id>
        <atom:category scheme="http://schemas.google.com/g/2005#kind"
            term="http://schemas.google.com/apps/2006#user"/>
        <atom:title type="text">SusanJones</atom:title>
        <atom:link rel="self" type="application/atom+xml" 
            href="http://www.google.com/a/feeds/example.com/user/2.0/SusanJones"/>
        <atom:link rel="edit" type="application/atom+xml"
            href="http://www.google.com/a/feeds/example.com/user/2.0/SusanJones"/>
        <gd:who rel="http://schemas.google.com/apps/2006#user.recipient" 
            email="SusanJones@example.com"/>
        <apps:login userName="SusanJones" suspended="false" admin="false" changePasswordAtNextLogin="false" agreedToTerms="true"/>
        <apps:quota limit="2048"/>
        <apps:name familyName="Jones" givenName="Susan"/>
        <gd:feedLink rel="http://schemas.google.com/apps/2006#user.nicknames" 
            href="http://www.google.com/a/feeds/example.com/nickname/2.0?username=SusanJones"/>
        <gd:feedLink rel="http://schemas.google.com/apps/2006#user.emailLists"
            href="http://www.google.com/a/feeds/example.com/emailList/2.0?recipient=SusanJones@example.com"/>
    </atom:entry>
    <atom:entry>
        <atom:id>
            http://www.google.com/a/feeds/example.com/user/2.0/JohnSmith
        </atom:id>
        <atom:category scheme="http://schemas.google.com/g/2005#kind"
            term="http://schemas.google.com/apps/2006#user"/>
        <atom:title type="text">JohnSmith</atom:title>
        <atom:link rel="self" type="application/atom+xml" 
            href="http://www.google.com/a/feeds/example.com/user/2.0/JohnSmith"/>
        <atom:link rel="edit" type="application/atom+xml"
            href="http://www.google.com/a/feeds/example.com/user/2.0/JohnSmith"/>
        <gd:who rel="http://schemas.google.com/apps/2006#user.recipient" 
            email="JohnSmith@example.com"/>
        <apps:login userName="JohnSmith" suspended="false" admin="false" changePasswordAtNextLogin="false" agreedToTerms="true"/>
        <apps:quota limit="2048"/>
        <apps:name familyName="Smith" givenName="John"/>
        <gd:feedLink rel="http://schemas.google.com/apps/2006#user.nicknames" 
            href="http://www.google.com/a/feeds/example.com/nickname/2.0?username=JohnSmith"/>
        <gd:feedLink rel="http://schemas.google.com/apps/2006#user.emailLists"
            href="http://www.google.com/a/feeds/example.com/emailList/2.0?recipient=JohnSmith@example.com"/>
    </atom:entry>
</atom:feed>

サンプル NicknameEntry レスポンス

Provisioning API は、ニックネームの作成、取得のいずれの場合も、同じフォーマットの Atom XML レスポンスを返します。以下の XML は、ニックネームの作成、取得のリクエストに対する API レスポンスのサンプルです。クライアント ライブラリは、この XML を NicknameEntry オブジェクトに変換します。

<?xml version="1.0" encoding="UTF-8"?>
<atom:entry xmlns:atom="http://www.w3.org/2005/Atom"
  xmlns:apps="http://schemas.google.com/apps/2006"
  xmlns:gd="http://schemas.google.com/g/2005">
    <atom:id>https://www.google.com/a/feeds/example.com/nickname/2.0/Susy</atom:id>
    <atom:updated>1970-01-01T00:00:00.000Z</atom:updated>
    <atom:category scheme="http://schemas.google.com/g/2005#kind"
        term="http://schemas.google.com/apps/2006#nickname"/>
    <atom:title type="text">Susy</atom:title>
    <atom:link rel="self" type="application/atom+xml" 
        href="https://www.google.com/a/feeds/example.com/nickname/2.0/Susy"/>
    <atom:link rel="edit" type="application/atom+xml" 
        href="https://www.google.com/a/feeds/example.com/nickname/2.0/Susy"/>
    <apps:nickname name="Susy"/>
    <apps:login userName="SusanJones" suspended="false" admin="false" changePasswordAtNextLogin="false" agreedToTerms="true"/>
</atom:entry>

サンプル NicknameFeed レスポンス

ドメインの全ニックネーム、または特定のユーザーに割り当てられた全ニックネームを取得するリクエストを送信すると、Provisioning API はニックネームのリストを含む Atom XML フィードを返します。これは、それぞれ <atom:entry> の XML ブロックに示されます。クライアント ライブラリは、このフィードを NicknameFeed オブジェクトに変換します。これには、一連の NicknameEntry オブジェクトが含まれます。

以下の XML は、ユーザー名 SusanJones のすべてのニックネームを取得するリクエストに対する API レスポンスのサンプルです。

<?xml version="1.0" encoding="UTF-8"?>
<atom:feed xmlns:atom="http://www.w3.org/2005/Atom" 
  xmlns:openSearch="http://a9.com/-/spec/opensearchrss/1.0/"
  xmlns:apps="http://schemas.google.com/apps/2006">
    <atom:id>
        http://www.google.com/a/feeds/example.com/nickname/2.0
    </atom:id>
    <atom:updated>1970-01-01T00:00:00.000Z</atom:updated>
    <atom:category scheme="http://schemas.google.com/g/2005#kind" 
        term="http://schemas.google.com/apps/2006#nickname"/>
    <atom:title type="text">Nicknames for user SusanJones</atom:title>
    <atom:link rel="http://schemas.google.com/g/2005#feed" 
        type="application/atom+xml" 
        href="http://www.google.com/a/feeds/example.com/nickname/2.0"/>
    <atom:link rel="http://schemas.google.com/g/2005#post" 
        type="application/atom+xml"
        href="http://www.google.com/a/feeds/example.com/nickname/2.0"/>
    <atom:link rel="self" type="application/atom+xml" 
        href="http://www.google.com/a/feeds/example.com/nickname/2.0?username=SusanJones"/>
    <openSearch:startIndex>1</openSearch:startIndex>
    <openSearch:itemsPerPage>2</openSearch:itemsPerPage>
    <atom:entry>
        <atom:id>
            http://www.google.com/a/feeds/example.com/nickname/2.0/susy
        </atom:id>
        <atom:category scheme="http://schemas.google.com/g/2005#kind"
            term="http://schemas.google.com/apps/2006#nickname"/>
        <atom:title type="text">susy</atom:title>
        <atom:link rel="self" type="application/atom+xml" 
            href="http://www.google.com/a/feeds/example.com/nickname/2.0/susy"/>
        <atom:link rel="edit" type="application/atom+xml"
            href="http://www.google.com/a/feeds/example.com/nickname/2.0/susy"/>
        <apps:nickname name="susy"/>
        <apps:login userName="SusanJones" suspended="false" admin="false" changePasswordAtNextLogin="false" agreedToTerms="true"/>
    </atom:entry>
    <atom:entry>
        <atom:id>
            http://www.google.com/a/feeds/example.com/nickname/2.0/suse
        </atom:id>
        <atom:category scheme="http://schemas.google.com/g/2005#kind"
            term="http://schemas.google.com/apps/2006#nickname"/>
        <atom:title type="text">suse</atom:title>
        <atom:link rel="self" type="application/atom+xml"
            href="http://www.google.com/a/feeds/example.com/nickname/2.0/suse"/>
        <atom:link rel="edit" type="application/atom+xml"
            href="http://www.google.com/a/feeds/example.com/nickname/2.0/suse"/>
        <apps:nickname name="suse"/>
        <apps:login userName="SusanJones" suspended="false" admin="false" changePasswordAtNextLogin="false" agreedToTerms="true"/>
    </atom:entry>
</atom:feed>

サンプル EmailListEntry レスポンス

メーリング リスト作成のリクエストを送信すると、Provisioning API は新規に作成されたリストを示す XML レスポンスを返します。クライアント ライブラリは、このレスポンスを EmailListEntry オブジェクトに変換します。このオブジェクトは、メーリング リストにアドレスを追加するリクエストの後、リクエストが成功したことを確認する目的以外で機能しません。

以下の XML は、メーリング リスト作成のリクエストに対する API レスポンスのサンプルです。

<?xml version="1.0" encoding="UTF-8"?>
<atom:entry xmlns:atom="http://www.w3.org/2005/Atom"
  xmlns:apps="http://schemas.google.com/apps/2006"
  xmlns:gd="http://schemas.google.com/g/2005">
    <atom:id>https://www.google.com/a/feeds/example.com/emailList/2.0/us-sales</atom:id>
    <atom:updated>1970-01-01T00:00:00.000Z</atom:updated>
    <atom:category scheme="http://schemas.google.com/g/2005#kind"
        term="http://schemas.google.com/apps/2006#emailList"/>
    <atom:title type="text">us-sales</atom:title>
    <atom:link rel="self" type="application/atom+xml" 
        href="https://www.google.com/a/feeds/example.com/emailList/2.0/us-sales"/>
    <atom:link rel="edit" type="application/atom+xml" 
        href="https://www.google.com/a/feeds/example.com/emailList/2.0/us-sales"/>
    <apps:emailList name="us-sales"/>
    <gd:feedLink rel="http://schemas.google.com/apps/2006#emailList.recipients"
        href="http://www.google.com/a/feeds/example.com/emailList/2.0/us-sales/recipient/"/>
</atom:entry>

サンプル EmailListFeed レスポンス

ドメインの全メーリング リスト、または特定のユーザーが登録している全メーリング リストを取得するリクエストを送信すると、Provisioning API はメーリング リストのリストを含む Atom XML フィードを返します。これは、それぞれ <atom:entry> の XML ブロックに示されます。クライアント ライブラリは、このフィードを EmailListFeed オブジェクトに変換します。これには、一連の EmailListEntry オブジェクトが含まれます。

以下の XML は、ドメインの全メーリング リストを取得するリクエストに対する API レスポンスのサンプルです。

<?xml version="1.0" encoding="UTF-8"?>
<atom:feed xmlns:atom="http://www.w3.org/2005/Atom" 
  xmlns:openSearch="http://a9.com/-/spec/opensearchrss/1.0/"
  xmlns:gd="http://schemas.google.com/g/2005">
    <atom:id>
        http://www.google.com/a/feeds/example.com/emailList/2.0
    </atom:id>
    <atom:updated>1970-01-01T00:00:00.000Z</atom:updated>
    <atom:category scheme="http://schemas.google.com/g/2005#kind" 
        term="http://schemas.google.com/apps/2006#emailList"/>
    <atom:title type="text">EmailLists</atom:title>
    <atom:link rel="next" type="application/atom+xml" 
        href="http://www.google.com/a/feeds/example.com/emailList/2.0?startEmailListName=john"/>
    <atom:link rel="http://schemas.google.com/g/2005#feed" 
        type="application/atom+xml" 
        href="http://www.google.com/a/feeds/example.com/emailList/2.0"/>
    <atom:link rel="http://schemas.google.com/g/2005#post" 
        type="application/atom+xml"
        href="http://www.google.com/a/feeds/example.com/emailList/2.0"/>
    <atom:link rel="self" type="application/atom+xml" 
        href="http://www.google.com/a/feeds/example.com/emailList/2.0"/>
    <openSearch:startIndex>1</openSearch:startIndex>
    <atom:entry>
        <atom:id>
            http://www.google.com/a/feeds/example.com/emailList/2.0/us-sales
        </atom:id>
        <atom:updated>1970-01-01T00:00:00.000Z</atom:updated>
        <atom:category scheme="http://schemas.google.com/g/2005#kind"
            term="http://schemas.google.com/apps/2006#emailList"/>
        <atom:title type="text">us-sales</atom:title>
        <atom:link rel="self" type="application/atom+xml" 
            href="http://www.google.com/a/feeds/example.com/emailList/2.0/us-sales"/>
        <atom:link rel="edit" type="application/atom+xml"
            href="http://www.google.com/a/feeds/example.com/emailList/2.0/us-sales"/>
        <apps:emailList name="us-sales"/>
        <gd:feedLink rel="http://schemas.google.com/apps/2006#emailList.recipients"
            href="http://www.google.com/a/feeds/example.com/emailList/2.0/us-sales/recipient/"/>
    </atom:entry>
    <atom:entry>
        <atom:id>
            http://www.google.com/a/feeds/example.com/emailList/2.0/us-eng
        </atom:id>
        <atom:updated>1970-01-01T00:00:00.000Z</atom:updated>
        <atom:category scheme="http://schemas.google.com/g/2005#kind"
            term="http://schemas.google.com/apps/2006#emailList"/>
        <atom:title type="text">us-eng</atom:title>
        <atom:link rel="self" type="application/atom+xml" 
            href="http://www.google.com/a/feeds/example.com/emailList/2.0/us-eng"/>
        <atom:link rel="edit" type="application/atom+xml"
            href="http://www.google.com/a/feeds/example.com/emailList/2.0/us-eng"/>
        <apps:emailList name="us-eng"/>
        <gd:feedLink rel="http://schemas.google.com/apps/2006#emailList.recipients"
            href="http://www.google.com/a/feeds/example.com/emailList/2.0/us-eng/recipient/"/>
    </atom:entry>
</atom:feed>

サンプル EmailListRecipientEntry レスポンス

メール アドレスをメーリング リストに追加するリクエストを送信すると、Provisioning API は新規に追加されたアドレスを示す XML レスポンスを返します。クライアント ライブラリは、このレスポンスを EmailListRecipientEntry オブジェクトに変換します。このオブジェクトは、メーリング リストにアドレスを追加するリクエストの後、リクエストが成功したことを確認する目的以外で機能しません。

以下の XML は、特定のメーリング リストに登録されている特定の受信者を取得するリクエストに対する API レスポンスのサンプルです。

<?xml version="1.0" encoding="UTF-8"?>
<atom:entry xmlns:atom="http://www.w3.org/2005/Atom"
  xmlns:apps="http://schemas.google.com/apps/2006"
  xmlns:gd="http://schemas.google.com/g/2005">
    <atom:id>https://www.google.com/a/feeds/example.com/emailList/2.0/us-sales/recipient/SusanJones%40example.com</atom:id>
    <atom:updated>1970-01-01T00:00:00.000Z</atom:updated>
    <atom:category scheme="http://schemas.google.com/g/2005#kind"
        term="http://schemas.google.com/apps/2006#emailList.recipient"/>
    <atom:title type="text">SusanJones</atom:title>
    <atom:link rel="self" type="application/atom+xml" 
        href="https://www.google.com/a/feeds/example.com/emailList/2.0/us-sales/recipient/SusanJones%40example.com"/>
    <atom:link rel="edit" type="application/atom+xml" 
        href="https://www.google.com/a/feeds/example.com/emailList/2.0/us-sales/recipient/SusanJones%40example.com"/>
    <gd:who email="SusanJones@example.com"/>
</atom:entry>

サンプル EmailListRecipientFeed レスポンス

メーリング リストの全登録者を取得するリクエストを送信すると、Provisioning API は登録者のリストを含む Atom XML フィードを返します。これは、それぞれ atom:entry の XML ブロックに示されます。それぞれのブロックに含まれる <gd:who> タグには、登録されているメール アドレスが示されます。クライアント ライブラリは、このレスポンスを EmailListRecipientFeed オブジェクトに変換します。これには、一連の EmailListRecipientEntry オブジェクトが含まれます。

以下の XML は、メーリング リストの全登録者を取得するリクエストに対する API レスポンスのサンプルです。

<?xml version="1.0" encoding="UTF-8"?>
<atom:feed xmlns:atom="http://www.w3.org/2005/Atom" 
  xmlns:openSearch="http://a9.com/-/spec/opensearchrss/1.0/"
  xmlns:gd="http://schemas.google.com/g/2005">
    <atom:id>
        http://www.google.com/a/feeds/example.com/emailList/2.0/us-sales/recipient
    </atom:id>
    <atom:updated>1970-01-01T00:00:00.000Z</atom:updated>
    <atom:category scheme="http://schemas.google.com/g/2005#kind" 
        term="http://schemas.google.com/apps/2006#emailList.recipient"/>
    <atom:title type="text">Recipients for email list us-sales</atom:title>
    <atom:link rel="next" type="application/atom+xml" 
        href="http://www.google.com/a/feeds/example.com/emailList/2.0/us-sales/recipient/?startRecipient=terry@example.com"/>
    <atom:link rel="http://schemas.google.com/g/2005#feed" 
        type="application/atom+xml" 
        href="http://www.google.com/a/feeds/example.com/emailList/2.0/us-sales/recipient"/>
    <atom:link rel="http://schemas.google.com/g/2005#post" 
        type="application/atom+xml"
        href="http://www.google.com/a/feeds/example.com/emailList/2.0/us-sales/recipient"/>
    <atom:link rel="self" type="application/atom+xml" 
        href="http://www.google.com/a/feeds/example.com/emailList/2.0/us-sales/recipient"/>
    <openSearch:startIndex>1</openSearch:startIndex>
    <atom:entry>
        <atom:id>
            http://www.google.com/a/feeds/example.com/emailList/2.0/us-sales/recipient/joe%40example.com
        </atom:id>
        <atom:updated>1970-01-01T00:00:00.000Z</atom:updated>
        <atom:category scheme="http://schemas.google.com/g/2005#kind"
            term="http://schemas.google.com/apps/2006#emailList.recipient"/>
        <atom:title type="text">joe@example.com</atom:title>
        <atom:link rel="self" type="application/atom+xml" 
            href="http://www.google.com/a/feeds/example.com/emailList/2.0/us-sales/recipient/joe%40example.com"/>
        <atom:link rel="edit" type="application/atom+xml"
            href="http://www.google.com/a/feeds/example.com/emailList/2.0/us-sales/recipient/joe%40example.com"/>
        <gd:who email="joe@example.com"/>
    </atom:entry>
    <atom:entry>
        <atom:id>
            http://www.google.com/a/feeds/example.com/emailList/2.0/us-sales/recipient/susan%40example.com
        </atom:id>
        <atom:updated>1970-01-01T00:00:00.000Z</atom:updated>
        <atom:category scheme="http://schemas.google.com/g/2005#kind"
            term="http://schemas.google.com/apps/2006#emailList.recipient"/>
        <atom:title type="text">susan@example.com</atom:title>
        <atom:link rel="self" type="application/atom+xml" 
            href="http://www.google.com/a/feeds/example.com/emailList/2.0/us-sales/recipient/susan%40example.com"/>
        <atom:link rel="edit" type="application/atom+xml"
            href="http://www.google.com/a/feeds/example.com/emailList/2.0/us-sales/recipient/susan%40example.com"/>
        <gd:who email="susan@example.com"/>
    </atom:entry>
</atom:feed>

サンプル Failure レスポンス

以下の XML は、無効な API リクエストに対するレスポンスのサンプルです。errorCode 属性の有効値は、<error> タグで定義されます。Provisioning API からエラー レスポンスを受け取ると、Java と Python のクライアント ライブラリは AppsForYourDomainException を返し、.NET クライアント ライブラリは AppsException を返します。このオブジェクトはエラー情報によって生成されます。

<?xml version="1.0" encoding="UTF-8"?>

<AppsForYourDomainErrors>
    <error errorCode="1301" reason="EntityDoesNotExist"
        invalidInput="your-invalid-input"/>
</AppsForYourDomainErrors>

注: クライアント ライブラリは、無効な XML やリクエスト送信先のパスのエラーなど、より一般的なタイプのエラーに対して他の例外を返す場合もあります。詳しくは、ServiceException のドキュメントをご覧ください。これは、Google Data API リクエストのエラーを識別するための基本的な例外クラスです。

補足情報 D - Google Data エラーコード

以下のリストは、Google Apps XML レスポンスで受信する可能性があるさまざまなエラー コードの説明です (エラー コード番号順)。

  • UnknownError(1000) - リクエストは、不明な理由で失敗しました。

  • UserDeletedRecently(1100) - Google に対して新規ユーザーを作成するように指示するリクエストに、5 日以内に削除されたアカウントのユーザー名が指定されていました。

  • UserSuspended(1101) - リクエストで指定されたユーザーのアカウントは停止されています。

  • DomainUserLimitExceeded(1200) - 指定されたドメインは、既にユーザー アカウントの割り当てに達しています。

  • DomainAliasLimitExceeded(1201) - 指定されたドメインは、既にエイリアスの割り当てに達しています。エイリアスとは、ニックネームとメーリング リストです。

  • DomainSuspended(1202) - Google は、指定されたドメインの Google Apps へのアクセスを停止しています。

  • DomainFeatureUnavailable(1203) - 指定されたドメインでは、この特定の機能を使用できません。

  • EntityExists(1300) - リクエストで Google に作成を指示したエンティティは、既に存在しています。

  • EntityDoesNotExist(1301) - リクエストで Google に取得を要求したエンティティは存在しません。

  • EntityNameIsReserved(1302) - リクエストで Google に作成を指示したエンティティの名前は、確保されています (「abuse」、「postmaster」など)。

  • EntityNameNotValid(1303) - リクエストで指定されたリソース名は無効です。

  • InvalidGivenName(1400) - API リクエストの中に、ユーザーの名前として使用できない文字が含まれています。このフィールドで使用できる文字についてのヘルプをご覧ください。

  • InvalidFamilyName(1401) - API リクエストの中に、ユーザーの姓として使用できない文字が含まれています。このフィールドで使用できる文字についてのヘルプをご覧ください。

  • InvalidPassword(1402) - API リクエストのユーザー パスワードに、無効な数字か文字、または使用できない文字が含まれています。このフィールドで使用できる文字についてのヘルプをご覧ください。

  • InvalidUsername(1403) - API リクエストの中に、ユーザー名として使用できない文字が含まれています。このフィールドで使用できる文字についてのヘルプをご覧ください。

  • InvalidHashFunctionName(1404) - 指定されたハッシュ関数は無効です。

  • InvalidHashDigestLength(1405) - 指定されたパスワードは、指定されたハッシュ関数に従っていません。

  • InvalidEmailAddress(1406) - 指定されたメール アドレスは無効です。

  • InvalidQueryParameterValue(1407) - 指定されたクエリ パラメータ値は無効です。

  • TooManyRecipientsOnEmailList(1500) - リクエストは Google にメーリング リストへのユーザーの追加を指示しましたが、このリストは既に登録者数が上限 (1000) に達しています。

補足情報 E - クライアント ライブラリのメソッド

関数 入力パラメータ 戻り値
createUser String username
String givenName
String familyName
String password
String passwordHashFunction (オプション)
Integer quotaLimitInMB (オプション)		 UserEntry
retrieveUser String username UserEntry
retrieveAllUsers なし UserFeed
retrievePageOfUsers String startUsername UserFeed
updateUser String username
UserEntry userEntry		 UserEntry
suspendUser String username UserEntry
restoreUser String username UserEntry
deleteUser String username なし
createNickname String username
String nickname		 NicknameEntry
retrieveNickname String nickname NicknameEntry
retrieveNicknames (ユーザー用) String username NicknameFeed
retrieveAllNicknames (ドメイン内) なし NicknameFeed
retrievePageOfNicknames (ドメイン内) String startNickname NicknameFeed
deleteNickname String nickname なし
createEmailList String emailList EmailListEntry
retrieveEmailLists (ユーザー用) String recipient EmailListFeed
retrieveAllEmailLists なし EmailListFeed
retrievePageOfEmailLists String startEmailListName EmailListFeed
deleteEmailList String emailList なし
createUser String username
String givenName
String familyName
String password
Integer quotaLimitInMB (オプション)		 UserEntry
addRecipientToEmailList String recipientAddress、String emailList EmailListRecipientEntry
retrieveAllRecipients String emailList EmailListRecipientFeed
retrievePageOfRecipients String emailList、String startRecipient EmailListRecipientFeed
removeRecipientFromEmailList String recipientAddress
String emailList		 なし