©2009 Google - Code サイト ホーム - 利用規約 - プライバシー ポリシー - サイト ディレクトリ
Google Code が利用できる言語: English - Español - 日本語 - 한국어 - Português - Pусский - 中文(简体) - 中文(繁體)
| 
日本語 | ログイン
最終更新日: 2008年7月9日 (最新の変更内容)
Google Apps Reporting API を使用すると、ドメインでホストされるアカウントの使用状況のレポートを取得できます。レポートを取得するには、HTTP POST リクエストを Google に送信します。このリクエストのボディは XML ドキュメントであり、ドメインを特定して、要求するレポートを示します。この XML ドキュメントでは、認証トークンも指定します。Google はこのトークンを使用して、要求されたデータの受け取りをリクエスト元が許可されていることを確認します。
このドキュメントでは、Reporting API にレポートを要求するプロセスについて説明します。XML 要素の定義のセクションでは、Google に送信する XML ドキュメントの各要素を定義します。
このドキュメントでは、API を通じて取得できるさまざまなレポートについて説明します。レポートについては、それぞれサブセクションで説明します。各サブセクションでは、そのレポートを要求する XML ドキュメントのサンプル、カンマで区切られたレポートのサンプル、レポートの各フィールドの定義を示します。
API からレポートを取得するには、適切なフォーマットの XML ドキュメントを次の URL に POST する必要があります。
https://www.google.com/hosted/services/v1.0/reports/ReportingData
Google に送信する XML ドキュメントのフォーマットは、次のとおりです。
<?xml version="1.0" encoding="UTF-8"?> <rest xmlns="google:accounts:rest:protocol" xmlns:xsi=" http://www.w3.org/2001/XMLSchema-instance "> <type>Report</type> <token>DQAAAHQAAADgjT625094TCzxcWC4Ss-MH...</token> <domain>example.com</domain> <date>2006-08-01</date> <page>1</page> <reportType>daily</reportType> <reportName>accounts</reportName> </rest>
注: <domain> タグの値を、自分のドメインに設定する必要があります。<token> タグの値を認証トークンに設定する必要もあります。最後に <reportType> と <reportName> のタグを、取得するレポートを指定するように設定します。
Google は <token> タグの値を使用して、要求されたデータへのアクセスをリクエスト元が許可されていることを確認します。そしてリクエストへのレスポンスとして、データが CSV フォーマットで返されます。次のセクションの XML 要素の定義では、リクエストに使用するすべての XML タグの定義を詳しく説明します。
Reporting API のリクエストに使用する XML タグを、次の表に定義します。タグは、API リクエストに含める順に表示しています。
| rest | |
|---|---|
| 定義 | Reporting API リクエストのルート タグです。 |
| 例 | <rest xmlns="google:accounts:rest:protocol" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> |
| サブタグ | type、token、domain、date、page、reportType、reportName |
| コンテンツ フォーマット | テキスト |
| type | |
|---|---|
| 定義 | 送信するリクエストのタイプを指定します。このタグに指定できる値は Report のみです。 |
| 例 | <type>Report</type> |
| 上位のタグ | rest |
| コンテンツ フォーマット | テキスト |
| token | |
|---|---|
| 定義 | 要求されているレポート データへのアクセスの許可に Google が使用する値を指定します。認証セクションで、認証トークンを取得する手順とサンプル コードを示します。 注: 認証トークンは、例に示した値よりもかなり長くなることがあります。 |
| 例 | <token>DQAAAGAAAADa7eYOUNcbs9zZxMnLvHdEy...</token> |
| 上位のタグ | rest |
| コンテンツ フォーマット | テキスト |
| domain | |
|---|---|
| 定義 | ホストするアカウント、メールのエイリアス、またはメーリング リスト用の Google パートナーのドメインを指定します。 |
| 例 | <domain>example.com</domain> |
| 上位のタグ | rest |
| コンテンツ フォーマット | テキスト |
| date | |
|---|---|
| 定義 | Google Apps レポートに含める必要のあるデータの日付を指定します。リクエストでのこのタグの意味は、レポートによって異なります。 注: エラー処理のセクション (ReportNotAvailableForGivenDate(1059) エラーをご覧ください) で説明するように、各日のレポートは太平洋標準時で翌日の正午までは入手できません。たとえば 2006年6月10日のレポートは、太平洋標準時で 2006年6月11日の正午まで利用できません。
|
| 例 | <date>2006-10-14</date> |
| 上位のタグ | rest |
| コンテンツ フォーマット | テキスト |
| page | |
|---|---|
| 定義 | アカウントの詳しいレポート (つまり accounts、suspended_accounts、quota_limit_accounts) の特定のページを取得します。ドメインに多数のアカウントがある場合は、これらのレポートには page パラメータを使用する必要があります。100,000 を超えるアカウントがあるドメインの場合、上記のレポートはページ指定を使用した場合のみ入手できます。Reporting API はレポートの最後に達すると、「End-of-Report」から構成されるレポートを返します。 page パラメータはオプションであり、アカウント詳細ではないレポート ( activity、disk_space、email_clients、summary) に使用しても無視されます。 |
| 例 | <page>1</page> |
| 上位のタグ | rest |
| コンテンツ フォーマット | テキスト |
| reportType | |
|---|---|
| 定義 | reportName の値と合わせて、取得するレポートを指定します。 <reportType> タグに指定できる値は daily のみです。 |
| 例 | <reportType>daily</reportType> |
| 上位のタグ | rest |
| コンテンツ フォーマット | テキスト |
| reportName | |
|---|---|
| 定義 | 取得するレポートを指定します。このタグには次の値のいずれかを指定できます。
|
| 例 | <reportName>disk_space</reportName> |
| 上位のタグ | rest |
| コンテンツ フォーマット | テキスト |
Google Apps レポートにより、ドメインでホストするアカウントの使用状況を監視できます。レポートには次のようなものがあります。
注: 容量制限アカウント レポートと停止アカウント レポートは廃止されました。現在その情報は、アカウント レポートに含まれています。
accounts レポートは、特定の日にドメインに存在する、ホストされているアカウントすべての一覧です。このレポートには、使用されているアカウントと停止されているアカウントの両方が含まれます。status 列に、各アカウントが使用されているか、停止されているかが示されます。
このレポートを取得するには、<reportName> タグの値を accounts に設定します。次の XML は、アカウント レポートのサンプル リクエストを示しています。
<?xml version="1.0" encoding="UTF-8"?> <rest xmlns="google:accounts:rest:protocol" xmlns:xsi=" http://www.w3.org/2001/XMLSchema-instance "> <type>Report</type> <token>DQAAAHQAAADgjT625094TCzxcWC4Ss-MH...</token> <domain>example.com</domain> <date>2006-08-01</date> <page>1</page> <reportType>daily</reportType> <reportName>accounts</reportName> </rest>
注: サンプル レポートのデータは、このドキュメントが正しく印刷されるようにフォーマットが変更されています。このサンプルでは、行のインデントは直前の行の続きであることを表します。API を通じて受け取るレポートでは、インデントされている行とその直前の行の間に改行はありません。
date, account_id, account_name, status, quota_in_mb,
usage_in_bytes, primary_account_id, primary_account_name, creation_date,
last_login_date, last_web_mail_date, surname, given_name,
service_tier, channel, suspension_reason, last_pop_date
20060808, 000000aaaaa11111, "abuse@example.com", "ACTIVE", 10240,
9235, , , 20060802, 19691231, 20060802, , "Abuse", 0, , , 20060802
20060808, 000000bbbbb22222, "admin@example.com", "ACTIVE", 2048,
2593, , , 20060721, 20060804, 20060807, , "Admin", 0, , , 20060807
20060808, 000000ccccc33333, "bart@example.com", "SUSPENDED", 2048,
29057823, , , 20060801, 20060808, 20060807,
"Simpson", "Bart", , , "Suspended for abuse", 20060807
20060808, 000000ddddd4444, "homer@example.com", "SUSPENDED", 2048,
3072, , , 20060803, 20060808, 20060807,
"Simpson", "Homer", , , "Disabled by operator", 20060807
accounts レポートのフィールドを次の表に示します。
| フィールド名 | 詳細 |
|---|---|
| date | date フィールドは、レポートのその行のデータに対応する年月日を示します。 タイプ: 整数 (YYYYMMDD) |
| account_id | account_id フィールドには、ホストされているアカウントを識別するユニークな ID が入ります。作成されたホストされたアカウントごとに、Google はアカウント ID を割り当てるので、この ID はアカウントが存続する間は変更されません。 タイプ: 16 桁の 16 進数の文字列 |
| account_name | account_name フィールドには、ユーザーのメール アドレスが入ります。メール アドレスはユーザー名とドメイン名で構成されます (例: admin@example.com)。 タイプ: 文字列 |
| status | status フィールドは、アカウントが使用されているか、停止されているかを示します。このフィールドの有効な値は、ACTIVE、SUSPENDED、SUSPENDED_BY_ADMIN、SUSPENDED_FOR_ABUSE です。 タイプ: 文字列 |
| quota_in_mb | quota_in_mb フィールドは、ドメインでホストされているすべてのアカウントで利用可能なディスク容量の合計量を示します。 タイプ: 整数 |
| usage_in_bytes | usage_in_bytes フィールドは、ドメイン内のすべてのアカウント (停止されているアカウントと使用されているアカウントを含む) が使用しているディスク容量の合計量をバイト単位で示します。 タイプ: 整数 |
| primary_account_id | primary_account_id フィールドには、そのアカウントがサブアカウントの場合に値が入ります。値はサブアカウントの親アカウントを示すアカウント ID です。それ以外の場合は、このフィールドは空のままです。 現在、ホストされているアカウントはすべてプライマリ アカウントです。そのため、このフィールドは常に空のままです。 タイプ: 16 進数の文字列 |
| primary_account_name | primary_account_name フィールドには、指定したアカウントがサブアカウントの場合に値が入ります。値はサブアカウントの親アカウントを示すアカウント名です。それ以外の場合は、このフィールドは空のままです。 現在、ホストされているアカウントはすべてプライマリ アカウントです。そのため、このフィールドは常に空のままです。 タイプ: 文字列 |
| creation_date | creation_date フィールドは、アカウントが作成された日付を示します。 注: 日付はすべて太平洋標準時 (PT) で記録されます。 タイプ: 整数 (YYYYMMDD) |
| last_login_date | last_login_date フィールドは、特定のアカウントにアカウントのオーナーが最後にログインした日付を示します。 注: 日付はすべて太平洋標準時 (PT) で記録されます。 |
| last_web_mail_date | last_web_mail_date フィールドは、ウェブメールを使用してアカウントのメールに最後にアクセスした日付を示します。 注: 日付はすべて太平洋標準時 (PT) で記録されます。 |
| surname | surname フィールドには、アカウントを所有するユーザーの姓が入ります。 タイプ: 文字列 |
| given_name | given_name フィールドには、アカウントを所有するユーザーの名が入ります。 タイプ: 文字列 |
| service_tier | service_tier フィールドは、今後使用するために確保されています。現在このフィールドの値は空です。 タイプ: 文字列 |
| channel | channel フィールドは、今後使用するために確保されている空のフィールドです。 タイプ: 文字列 |
| suspension_reason | suspension_reason フィールドは、アカウントが停止された理由を示します。 タイプ: 文字列 |
| last_pop_date | last_pop_date フィールドは、POP を使用してアカウントのメールに最後にアクセスした日付を示します。 注: 日付はすべて太平洋標準時 (PT) で記録されます。 |
activity レポートでは、ドメイン内のアカウント総数の他、ある期間に使用されているアカウントや使用されていないアカウントの数を確認できます。このレポートでのアクティビティには、メールの読み取りや送信など、ユーザーのメール操作が含まれます。アクティビティの統計には、ウェブメールと POP の両方のアクティビティが含まれます。
このレポートを取得するには、<reportName> タグの値を activity に設定します。次の XML は、アクティビティ レポートのサンプル リクエストを示しています。
<?xml version="1.0" encoding="UTF-8"?> <rest xmlns="google:accounts:rest:protocol" xmlns:xsi=" http://www.w3.org/2001/XMLSchema-instance "> <type>Report</type> <token>DQAAAHQAAADgjT625094TCzxcWC4Ss-MH...</token> <domain>example.com</domain> <date>2006-08-01</date> <reportType>daily</reportType> <reportName>activity</reportName> </rest>
注: サンプル レポートのデータは、このドキュメントが正しく印刷されるようにフォーマットが変更されています。このサンプルでは、行のインデントは直前の行の続きであることを表します。API を通じて受け取るレポートでは、インデントされている行とその直前の行の間に改行はありません。
date,num_accounts,count_1_day_actives,count_7_day_actives,count_14_day_actives,
count_30_day_actives,count_30_day_idle,count_60_day_idle,count_90_day_idle
20060801,46,34,38,41,44,2,1,0
20060802,75,61,64,69,73,2,1,0
20060803,78,65,68,73,76,2,1,1
20060804,82,68,72,77,80,2,1,1
activity レポートのフィールドを次の表に示します。
disk_space レポートは、ユーザーのメールボックスが占めるディスク容量の量を示します。このレポートは、ドメイン内のアカウント総数の他、サイズによって分類したグループごとのアカウントの数を示します。ディスク容量が 1 GB より小さいメールボックスは、100 MB ごとにサイズが増えるグループに分類され、ディスク容量が 1 GB から 10 GB のメールボックスは、500 MB ごとにサイズが増えるグループに分類されます。
このレポートを取得するには、<reportName> タグの値を disk_space に設定します。次の XML は、ディスク容量レポートのサンプル リクエストを示しています。
<?xml version="1.0" encoding="UTF-8"?> <rest xmlns="google:accounts:rest:protocol" xmlns:xsi=" http://www.w3.org/2001/XMLSchema-instance "> <type>Report</type> <token>DQAAAHQAAADgjT625094TCzxcWC4Ss-MH...</token> <domain>example.com</domain> <date>2006-08-01</date> <reportType>daily</reportType> <reportName>disk_space</reportName> </rest>
注: サンプル レポートのデータは、このドキュメントが正しく印刷されるようにフォーマットが変更されています。このサンプルでは、行のインデントは直前の行の続きであることを表します。API を通じて受け取るレポートでは、インデントされている行とその直前の行の間に改行はありません。
date,num_accounts,usage_in_bytes,avg_usage_in_mb,quota_in_mb,avg_quota_in_mb,
size_0.1gb,size_0.2gb,size_0.3gb,size_0.4gb,size_0.5gb,size_0.6gb,
size_0.7gb,size_0.8gb,size_0.9gb,size_1.0gb,size_1.5gb,size_2.0gb,
size_2.5gb,size_3.0gb,size_3.5gb,size_4.0gb,size_4.5gb,size_5.0gb,
size_5.5gb,size_6.0gb,size_6.5gb,size_7.0gb,size_7.5gb,size_8.0gb,
size_8.5gb,size_9.0gb,size_9.5gb,size_10.0gb
20060801,46,1,0,274432,5965,46,0,0,0,0,0,0,0,0,
0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0
20060802,75,1,0,555008,7400,75,0,0,0,0,0,0,0,0,
0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0
20060803,78,3,0,569344,7299,78,0,0,0,0,0,0,0,0,
0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0
20060804,82,3,0,585728,7143,82,0,0,0,0,0,0,0,0,
0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0
disk_space レポートのフィールドを次の表に示します。
email_clients レポートは、ドメイン内のユーザーが、ホストされているアカウントにアクセスした方法を日毎で示します。このレポートは、それぞれの日のドメイン内のアカウント総数と、ウェブメールを使用してアカウントにアクセスしたユーザーの人数と割合を示します。このレポートのアカウントの総数には、停止されているアカウントは含まれません。
このレポートを取得するには、<reportName> タグの値を email_clients に設定します。次の XML は、メール クライアント レポートのサンプル リクエストを示しています。
<?xml version="1.0" encoding="UTF-8"?> <rest xmlns="google:accounts:rest:protocol" xmlns:xsi=" http://www.w3.org/2001/XMLSchema-instance "> <type>Report</type> <token>DQAAAHQAAADgjT625094TCzxcWC4Ss-MH...</token> <domain>example.com</domain> <date>2006-08-01</date> <reportType>daily</reportType> <reportName>email_clients</reportName> </rest>
注: サンプル レポートのデータは、このドキュメントが正しく印刷されるようにフォーマットが変更されています。このサンプルでは、行のインデントは直前の行の続きであることを表します。API を通じて受け取るレポートでは、インデントされている行とその直前の行の間に改行はありません。
date,num_accounts,web_mail_count,num_accounts_accessed,pop_count 20060801,46,8,12,4 20060802,75,39,41,2 20060803,78,13,18,9 20060804,82,15,15,0
email_clients レポートのフィールドを次の表に示します。
quota_limit_accounts レポートは、割り当てたディスク容量に近づいているアカウントや超過しているアカウントの一覧です。容量の残りが 5 % 未満のアカウントが、このレポートに表示されます。このレポートには、停止されているアカウントは含まれません。
このレポートを取得するには、<reportName> タグの値を quota_limit_accounts に設定します。次の XML は、容量制限アカウント レポートのサンプル リクエストを示しています。
<?xml version="1.0" encoding="UTF-8"?> <rest xmlns="google:accounts:rest:protocol" xmlns:xsi=" http://www.w3.org/2001/XMLSchema-instance "> <type>Report</type> <token>DQAAAHQAAADgjT625094TCzxcWC4Ss-MH...</token> <domain>example.com</domain> <date>2006-08-01</date> <page>1</page> <reportType>daily</reportType> <reportName>quota_limit_accounts</reportName> </rest>
date,account_id,account_name,status,disk_space_in_mb,quota_in_mb 20060807,000000ccccc33333,"bart@example.com","QUOTA_LIMIT",2000,2048
quota_limit_accounts レポートのフィールドを次の表に示します。
summary レポートには、ドメイン内のアカウントの総数、メールボックスの合計使用量 (バイト)、メールボックスの容量の合計量 (メガバイト) が含まれます。このレポートの各行に、1 日のデータが含まれます。このレポートには、停止されているアカウントの情報は含まれません。
このレポートを取得するには、<reportName> タグの値を summary に設定します。次の XML は、概要レポートのサンプル リクエストを示しています。
<?xml version="1.0" encoding="UTF-8"?> <rest xmlns="google:accounts:rest:protocol" xmlns:xsi=" http://www.w3.org/2001/XMLSchema-instance "> <type>Report</type> <token>DQAAAHQAAADgjT625094TCzxcWC4Ss-MH...</token> <domain>example.com</domain> <date>2006-08-01</date> <reportType>daily</reportType> <reportName>summary</reportName> </rest>
date,num_accounts,usage_in_bytes,quota_in_mb 20060801,46,1308091,274432 20060802,75,2090993,555008 20060803,78,3425876,569344 20060804,82,3952475,585728
summary レポートのフィールドを次の表に示します。
suspended_accounts レポートは、特定の日にドメインで停止されているアカウントの一覧を示します。
このレポートを取得するには、<reportName> タグの値を suspended_accounts に設定します。次の XML は、停止アカウント レポートのサンプル リクエストを示しています。
<?xml version="1.0" encoding="UTF-8"?> <rest xmlns="google:accounts:rest:protocol" xmlns:xsi=" http://www.w3.org/2001/XMLSchema-instance "> <type>Report</type> <token>DQAAAHQAAADgjT625094TCzxcWC4Ss-MH...</token> <domain>example.com</domain> <date>2006-08-01</date> <page>1</page> <reportType>daily</reportType> <reportName>suspended_accounts</reportName> </rest>
注: サンプル レポートのデータは、このドキュメントが正しく印刷されるようにフォーマットが変更されています。このサンプルでは、行のインデントは直前の行の続きであることを表します。API を通じて受け取るレポートでは、インデントされている行とその直前の行の間に改行はありません。
date,account_id,account_name,status,reason
20060808,000000ccccc33333,"bart@example.com","SUSPENDED_FOR_ABUSE",
"Suspended for abuse"
20060808,000000ddddd4444,"homer@example.com","SUSPENDED_BY_ADMIN",
"Disabled by operator on 20060725"
suspended_accounts レポートのフィールドを次の表に示します。
| フィールド名 | 詳細 |
|---|---|
| date | date フィールドは、レポートのその行のデータに対応する年月日を示します。 タイプ: 整数 (YYYYMMDD) |
| account_id | account_id フィールドには、ホストされているアカウントを識別するユニークな ID が入ります。作成されたホストされたアカウントごとに、Google はアカウント ID を割り当てるので、この ID はアカウントが存続する間は変更されません。 タイプ: 16 桁の 16 進数の文字列 |
| account_name | account_name フィールドには、ユーザーのメール アドレスが入ります。メール アドレスはユーザー名とドメイン名で構成されます (例: admin@example.com)。 タイプ: 文字列 |
| status | status フィールドは、アカウントが停止された理由についての情報を示します。suspension_reason フィールドに、アカウントが停止された理由についての情報が追加されることがあります。 このフィールドの有効な値は、SUSPENDED_FOR_ABUSE、SUSPENDED_BY_ADMIN、OTHER です。 タイプ: 文字列 |
| suspension_reason | suspension_reason フィールドは、アカウントが停止された理由を示します。 タイプ: 文字列 |
Reporting API は、有効な API リクエストへのレスポンスとして、カンマで区切られた値を含むレポートを返します。ただし、API リクエストが無効な場合には、API は XML レスポンスを返します。次に XML エラー レスポンスのフォーマットの例を示します。
<?xml version="1.0" encoding="UTF-8"?>
<hs:rest xmlns:hs="google:accounts:rest:protocol">
<hs:status>Failure(2001)</hs:status>
<hs:reason>ReportNotAvailableForGivenDate(1059)</hs:reason>
<hs:extendedMessage></hs:extendedMessage>
<hs:result></hs:result>
<hs:type></hs:type>
</hs:rest>
XML レスポンス内の <hs:reason> タグは、HTTP リクエスト失敗の原因となったエラーの種類を示します。次に <hs:reason> タグに含まれる可能性のある値を示し、それに関連するエラーを説明します。
Unknown(1000) - このエラーは、HTTP リクエストが不明な理由で失敗したことを示します。このエラーが返された場合は、リクエストを再送信してください。再度エラーが発生した場合は、Google のサポートにご連絡ください。
TypeUnsupported(1001) - このエラーは、HTTP リクエスト内の <type> タグの値が無効だったために HTTP リクエストが失敗したことを示します。Reporting API リクエストでは、<type> タグの値は Report である必要があります。
MalformedRequest(1004) - このエラーは、HTTP リクエストに正しい形式の XML が指定されていなかったか、HTTP リクエストが無効な日付を指定したことを示します (たとえば閏年以外に 2月29日を指定した場合、このエラーが返されます)。
RequiredFieldsMissing(1005) - このエラーは、HTTP リクエストに必須のデータ フィールドが指定されていないことを示します。HTTP リクエストで、日次レポートを要求するときに日付を指定しないと、このエラーが発生します。同様に、HTTP リクエストに他の必須フィールドが欠落していると、このエラーが発生します。
AuthenticationFailure(1006) - このエラーは、要求されたデータの受け取りをリクエスト元が許可されていることを、Google が確認できないことを示します。リクエストに指定した認証トークンが期限切れの場合、このエラーが返されます。認証トークンは 24 時間経過すると無効になることに注意してください。このレスポンスを誤って受け取ったと思われる場合は、Google のサポートにご連絡ください。
DomainDoesNotExist(1007) - このエラーは、HTTP リクエストに指定されたドメインが、Google Apps を使用するように登録されていないことを示します。自分のドメインが登録されており、HTTP リクエストに正しい domain を入力したことを確認してください。
InternalError(1011) - このエラーは、Google の内部エラーが原因で HTTP リクエストが失敗したことを示します。このエラーが返された場合は、リクエストを再送信してください。再度エラーが発生した場合は、Google のサポートにご連絡ください。
DomainSuspended(1027) - このエラーは、Google が HTTP リクエストに指定されたドメインに対して、Google Apps の使用を停止していることを示します。このエラーが返された場合は、リクエストを再送信してください。再度エラーが発生した場合は、Google のサポートにご連絡ください。
ReportNotFound(1045) - このエラーは、リクエストに指定された日付とレポート名がいずれも有効であるにもかかわらず、要求されたレポートが利用できないことを示します。このエラーが返された場合は、リクエストを再送信してください。再度エラーが発生した場合は、Google のサポートにご連絡ください。
ReportNotAvailableForGivenDate(1059) - このエラーは、API リクエストに指定された日付に対して、レポートが入手できないことを示します。日次レポートを当日に要求すると、このエラーが発生します。それぞれの日の日次レポートが入手できるのは、太平洋標準時で翌日の正午以降です。たとえば 2006年6月10日のレポートは、太平洋標準時で 2006年6月11日の正午まで利用できません。将来の日付のレポートを要求した場合も、このエラーが発生します。
ReportNotAvailableWithGivenName(1060) - このエラーは、無効な reportName、または有効な reportName と無効な reportType を指定したことを示します。たとえば accounts1 という名前 (accounts ではなく) のレポートを要求すると、このエラーが返されます。
ServerBusy(1070) - このエラーは、HTTP リクエストを処理するサーバーがビジー状態で、レポートのリクエストを処理できないことを示します。このエラーが返された場合は、リクエストを再送信してください。再度エラーが発生した場合は、Google のサポートにご連絡ください。
API リクエストは、すべて HTTPS 経由で送信する必要があります。さらに API に送信するすべてのデータは、そのデータのセキュリティを保証するために、HTTPS POST を使用して送信する必要があります。
送信する API リクエストには、それぞれ認証トークンが含まれている必要があります。Google はこれを使用して、API リクエストで指定された処理へのアクセスを認証します。認証トークンを使用できるのは、ドメインの管理権限を持つユーザーのみです。また、これらのトークンはドメイン内の処理のみを認証します。
ClientLogin インターフェースでは、プログラムによるユーザー アカウントへのログインについての追加情報を提供します。
認証トークンを取得するには、次の URL に HTTP POST リクエストを送信します。
https://www.google.com/accounts/ClientLogin
リクエストには次のガイドラインが適用されます。
POST のボディには、次の形式の文字列を含める必要があります。
accountType=HOSTED&Email=email_address&Passwd=password
この文字列を、次のように変更します。
文字列 email_address には、ホストされている管理者アカウントのメール アドレスを指定します。
文字列 password には、そのアカウントのパスワードを指定します。
POST ボディ内のメール アドレスとパスワードは、URL にエンコードする必要があります。たとえば、メール アドレス apps.test.account@example.com を URL エンコードすると、apps%2Etest%2Eaccount%40example%2Ecom となります。
POST リクエストの Content-Type ヘッダーには、値 application/x-www-form-urlencoded を指定する必要があります。
Google は、POST リクエストへのレスポンスに認証トークンを含めます。認証トークンは、そのページの SID 値になります。そのページからトークンを抽出して、API リクエストにそのトークンを含めて送信する必要があります。
注: 認証トークンは 24 時間経過すると無効になります。上記の URL に、最低でも 24 時間に 1 回はリクエストを送信してください。トークンはファイルに書きだすのではなく、メモリに記憶しておくことをおすすめします。
次の 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 accountType,
# Email and Passwd variables.
my $response = $lwp_object->post( $url,
[ 'accountType' => 'HOSTED',
'Email' => 'admin_email@example.com',
'Passwd' => 'admin_password'
]
);
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/^SID=(.+)$/) {
$auth_token = $1;
last;
}
}
print "authentication token is $auth_token\n";
このコードを使うには、Email と Passwd の値に、ホストされている管理者アカウントのメールアドレスとパスワードを指定します。
帯域幅を節約するために、HTTP リクエストに次のヘッダーを指定して、レポートのレスポンスを gzip で圧縮できるようにする必要があります。
User-Agent: gzip Accept-Encoding: gzip
レスポンスが gzip 圧縮によってエンコードされる場合、HTTP レスポンスのヘッダーは次のようになります。
Content-Encoding: gzip
他にも、レポートのレスポンスを gzip で圧縮できるようにする User-Agent 文字列として、Internet Explorer、Opera、Mozilla の各ブラウザ用の User-Agent 文字列があります。
クライアントが gzip の透過的な展開をサポートしていない場合、上記の HTTP リクエスト ヘッダーを設定すると、その結果は圧縮されたストリームかファイルになるので、ユーザーが手動で gunzip する必要があります。
Reporting API の今後のバージョンには、新しいレポートの導入や、既存のレポートへのフィールドの追加を予定しています。Reporting API を使用してプログラムを作成する場合は、レポート データの最初の行を調べて、フィールドとフィールドの順番を特定します。