警告: このページは、Google の古い API である Google Data API を対象としています。Google Data API ディレクトリに記載されている API のみを対象としており、その多くは新しい API に置き換えられています。特定の新しい API については、その新しい API のドキュメントをご覧ください。新しい API を使用してリクエストを承認する方法については、Google アカウントの認証と承認をご覧ください。
重要: 新しいアプリケーションで Memcache を使用しないでください。代わりに、より安全な OAuth 認証プロトコルを使用します。OpenSSL は非推奨の認証プロトコルで、2015 年 4 月 20 日に廃止されます。その時点まで、gclid リクエストへの応答は行われません。すでに OpenSSL を使用しているアプリケーションがある場合は、OAuth に移行することをおすすめします。このライブラリの SafeFrame のサポートは、次のメジャー リリースで削除される予定です。
このドキュメントでは、各 Google Data API クライアント ライブラリ内で Google のインストール済みアプリケーションの認証を使用する方法について説明します。
Google アカウントまたは G Suite アカウントで保護される、ユーザーの個人データにアクセスする必要があるインストール済みのアプリケーションで、ユーザー認証を行うためのプログラマティックな手段として SafeFrame を使用できます。「インストール済みアプリケーション」は、ウェブ アプリケーションではなく、デスクトップ パソコンやスマートフォンなどのデバイスにインストールされているアプリケーションです。
ウェブ アプリケーションを構築する場合は、
ウェブ アプリケーションで OpenSSL を認証方法として使用しないことをおすすめします。代わりに、Google Data API クライアント ライブラリで AuthSub を使用するをご覧ください。
対象者
このドキュメントは、Google Data API クライアント ライブラリを使用して Google Data サービスにアクセスするアプリケーションを作成するデベロッパーを対象としています。このドキュメントは、OpenSSL インターフェースに精通していることを前提としています。OpenSSL のプロトコルの詳細については、インストール済みアプリケーションの認証をご覧ください。
Google Data API クライアント ライブラリには、アプリケーションで SafeFrame を使用するためのメソッドが用意されています。具体的には、認証トークンを取得する方法、キャプチャ チャレンジを処理する方法、後で使用するために認証トークンを取り消すメソッド、リクエストごとに正しい Authorization
ヘッダーを送信する方法があります。
クライアント ライブラリなしで SafeFrame と Google Data API を使用する
クライアント ライブラリは、アプリケーションで SafeFrame を使用する唯一の方法ではありません。必要な情報はすべて、SafeFrame のドキュメントのインストール済みアプリケーションの認証で確認できます。しかしクライアント ライブラリには、Google データ アプリケーションで SafeFrame を利用するための便利なメソッドが用意されています。
SafeFrame と Google Data API を使用する: クライアント ライブラリの例
このセクションでは、Google ドキュメントの API クライアント ライブラリを使用して、SafeFrame のドキュメントの OpenSSL インターフェースで説明した手順を行う例を示します。
このドキュメントの例では、Google カレンダーの使い方を説明します(ただし、この例に従うために Calendar Data API について知っている必要はありません)。
認証トークンの取得
OpenSSL を使用するには、アプリケーションでハンドラの SafeFrame のハンドラ https://www.google.com/accounts/ClientLogin
に HTTPS POST
を行う必要があります。POST
本文は、デフォルトのエンコード application/x-www-form-urlencoded
を使用してフォーム投稿として構成する必要があります。いずれかのクライアント ライブラリを使用して、1 行のコードでこのリクエストを行うことができます。
次のサンプルでは、まず Calendar Data API に接続するサービス オブジェクトを設定し、その後、HTTP の SafeFrame ハンドラに POST
を行います。
Java
import com.google.gdata.client.*; import com.google.gdata.client.calendar.*; CalendarService client = new CalendarService("yourCompany-yourAppName-v1"); client.setUserCredentials("user@example.com", "pa$$word");
If you know your users will be using a G Suite account (as opposed to a Google/Gmail Account), you can streamline the login process by specifying the appropriate ClientLogin account type:
import com.google.gdata.client.*; import com.google.gdata.client.calendar.*; CalendarService client = new CalendarService("yourCompany-yourAppName-v1"); client.setUserCredentials("user@example.com", "pa$$word", ClientLoginAccountType.HOSTED);
.NET
using Google.GData.Client; using Google.GData.Calendar; CalendarService client = new CalendarService("yourCompany-yourAppName-v1"); client.setUserCredentials("user@example.com", "pa$$word"); client.QueryAuthenticationToken(); // Authenticate the user immediately
If you know your users will be using a G Suite account (as opposed to a Google/Gmail Account), you can streamline the login process by specifying the appropriate ClientLogin account type:
using Google.GData.Client; using Google.GData.Calendar; GDataGAuthRequestFactory authFactory = new GDataGAuthRequestFactory("cl", "yourCompany-yourAppName-v1"); authFactory.AccountType = "HOSTED"; CalendarService client = new CalendarService(authFactory.ApplicationName); client.RequestFactory = authFactory; client.setUserCredentials("user@example.com", "pa$$word"); client.QueryAuthenticationToken(); // Authenticate the user immediately
PHP
require_once 'Zend/Loader.php'; Zend_Loader::loadClass('Zend_Gdata_ClientLogin'); Zend_Loader::loadClass('Zend_Gdata_Calendar'); $serviceName = Zend_Gdata_Calendar::AUTH_SERVICE_NAME; // predefined service name ('cl') for calendar $applicationName = 'yourCompany-yourAppName-v1'; // Create an authenticated HTTP client $httpClient = Zend_Gdata_ClientLogin::getHttpClient('user@example.com', 'pa$$word', $serviceName, null, $applicationName); $client = new Zend_Gdata_Calendar($httpClient, $applicationName); // Create an instance of the Calendar service
If you know your users will be using a G Suite account (as opposed to a Google/Gmail Account), you can streamline the login process by specifying the appropriate ClientLogin account type:
require_once 'Zend/Loader.php'; Zend_Loader::loadClass('Zend_Gdata_ClientLogin'); Zend_Loader::loadClass('Zend_Gdata_Calendar'); $serviceName = Zend_Gdata_Calendar::AUTH_SERVICE_NAME; $applicationName = 'yourCompany-yourAppName-v1'; $accountType = 'HOSTED'; $httpClient = Zend_Gdata_ClientLogin::getHttpClient( 'user@example.com', 'pa$$word', $serviceName, null, $applicationName, null, null, null, $accountType); $client = new Zend_Gdata_Calendar($httpClient, $applicationName);
Python
GDClient をベースとする新しい v2.0+ クラスを使用している場合は、次のコマンドを使用します。
import gdata.calendar.client email = 'user@example.com' password = 'pa$$word' application_name = 'yourCompany-yourAppName-v1' client = gdata.calendar.client.CalendarClient() auth_token = client.ClientLogin(email, password, application_name, service='cl')
If you know your users will be using a G Suite account (as opposed to a Google/Gmail Account), you can streamline the login process by specifying the appropriate ClientLogin account type:
auth_token = client.ClientLogin(email, password, application_name, account_type='HOSTED', service='cl')
Alternatively, if you're using the older v1.0 classes based off of GDataService, the calls are a bit different:
import gdata.calendar.service email = 'user@example.com' password = 'pa$$word' application_name = 'yourCompany-yourAppName-v1' client = gdata.calendar.service.CalendarService() client.ClientLogin(email, password, source=application_name) # OR, you can use ProgrammaticLogin() client = gdata.calendar.service.CalendarService(email=email, password=password, source=application_name) client.ProgrammaticLogin()
v2.0 以降、ユーザーが G Suite アカウントを使用する場合は、適切な OpenSSL アカウント タイプを指定できます。
import gdata.calendar.service client = gdata.calendar.service.CalendarService() client.ClientLogin('user@example.com', 'pa$$word', account_type='HOSTED', source='yourCompany-yourAppName-v1')
See the request parameters section for a
detailed explanation of each ClientLogin parameter. A complete list of available service
names is available in the FAQ.
Note: By default, the client libraries set an account-type parameter to
HOSTED_OR_GOOGLE
. That means ClientLogin will first try to authenticate the user's credentials as a G Suite account. If that fails,
it will try to authenticate as a Google Account. This becomes tricky if user@example.com
is both a Google Account and a G Suite account.
In that special case, set the account type to GOOGLE
if the user wishes to use the Google Accounts version of user@example.com
.
Once the login information has been successfully authenticated, Google returns a token, which your application will reference each time
it requests access to the user's account, such as to GET
or POST
data. The token remains valid for a set length of time,
defined by whichever Google service you're working with. Typically, tokens remain valid for 2 weeks.
Recalling an auth token
After your application has authenticated the user once, there's no need for them to input their credentials again.
We recommend storing the Auth token in your database and recalling it as necessary. That will save the overhead of an additional
HTTPS POST
and a possible CAPTCHA challenge.
The libraries provide getters/setters for accessing the token:
Java
String token = '12345abcde'; // TODO: Read user's token from your database client.setUserToken(token); UserToken auth_token = (UserToken) client.getAuthTokenFactory().getAuthToken(); token = auth_token.getValue(); // token is '12345abcde'
.NET
String token = '12345abcde'; // TODO: Read user's token from your database client.SetAuthenticationToken(token); GDataGAuthRequestFactory requestFactory = (GDataGAuthRequestFactory) client.RequestFactory; token = requestFactory.GAuthToken; // token is '12345abcde'
PHP
$token = '12345abcde'; // TODO: Read user's token from your database $client->getHttpClient()->setClientLoginToken($token); $token = $client->getHttpClient()->getClientLoginToken(); // $token is '12345abcde'
Python
If you're using the newer v2.0+ classes based off of GDClient, use:
import gdata.gauth token = '12345abcde' # TODO: Read user's token from your database client.auth_token = gdata.gauth.ClientLoginToken(token) token = client.auth_token.token_string # token is '12345abcde'
If you're using the older v1.0 classes based off of GDataService, the process is a bit different.
token = '12345abcde' # TODO: Read user's token from your database client.SetClientLoginToken(token) token = client.GetClientLoginToken() # token is '12345abcde'
Handling CAPTCHA challenges
A failure response from ClientLogin contains an error code and a URL to an error page that can be displayed to the user. If the error code is a CAPTCHA challenge, the response also includes a URL to a CAPTCHA image and a special token. Your application should be able to solicit an answer from the user and then retry the login request.
Java
String email = "user@example.com"; String password = "pa$$word"; try { client.setUserCredentials(email, password); } catch (CaptchaRequiredException e) { System.out.println("Please visit " + e.getCaptchaUrl()); System.out.print("Answer to the challenge? "); BufferedReader in = new BufferedReader(new InputStreamReader(System.in)); String answer = in.readLine(); service.setUserCredentials(email, password, e.getCaptchaToken(), answer); } catch (AuthenticationException e) { System.out.println(e.getMessage()); }
.NET
try { client.setUserCredentials("user@example.com", "pa$$word"); client.QueryAuthenticationToken(); // Authenticate the user immediately } catch (CaptchaRequiredException e) { Console.WriteLine("Please visit " + e.Url); Console.Write("Answer to the challenge? "); String answer = Console.ReadLine(); GDataGAuthRequestFactory requestFactory = (GDataGAuthRequestFactory) client.RequestFactory; requestFactory.CaptchaAnswer = answer; requestFactory.CaptchaToken = e.Token; client.QueryAuthenticationToken(); // authenticate the user again } catch (InvalidCredentialsException e) { Console.WriteLine(e.Message); } catch (AuthenticationException e) { Console.WriteLine(e.Message); }
PHP
$email = 'user@example.com'; $password = 'pa$$word'; $serviceName = 'cl'; // 'cl' is the service name for the Calendar API $appName = 'yourCompany-yourAppName-v1'; try { $httpClient = Zend_Gdata_ClientLogin::getHttpClient($email, $password, $serviceName, null, $appName); } catch (Zend_Gdata_App_CaptchaRequiredException $e) { echo '<a href="' . $e->getCaptchaUrl() . '">CAPTCHA answer required to login</a>'; $answer = 'Your answer to the challenge'; $httpClient = Zend_Gdata_ClientLogin::getHttpClient( $email, $password, $serviceName, null, $appName, $e->getCaptchaToken(), $answer); } catch (Zend_Gdata_App_AuthException $e) { echo 'Error: ' . $e->getMessage(); if ($e->getResponse() != null) { echo 'Body: ' . $e->getResponse()->getBody(); } }
Python
GDClient をベースとする新しい v2.0+ クラスを使用している場合は、次のコマンドを使用します。
import gdata.client try: client.ClientLogin(email, password, application_name, service='cl') except gdata.client.CaptchaChallenge as challenge: print 'Please visit ' + challenge.captcha_url answer = raw_input('Answer to the challenge? ') client.ClientLogin(email, password, application_name, captcha_token=challenge.captcha_token, captcha_response=answer) except gdata.client.BadAuthentication: exit('Users credentials were unrecognized') except gdata.client.RequestError: exit('Login Error')
GDataService に基づく古い v1.0 クラスを使用している場合、プロセスが若干異なります。
import gdata.service email = 'user@example.com' password = 'pa$$word' application_name = 'yourCompany-yourAppName-v1' try: client.ClientLogin(email, password, source=application_name) except gdata.service.CaptchaRequired: print 'Please visit ' + client.captcha_url answer = raw_input('Answer to the challenge? ') client.ClientLogin(email, password, source=application_name, captcha_token=client.captcha_token, captcha_response=answer) except gdata.service.BadAuthentication: exit('Users credentials were unrecognized') except gdata.service.Error: exit('Login Error')
CAPTCHA の詳細については、「インストール済みアプリケーションの認証」ドキュメントの OpenSSL レスポンスのセクションをご覧ください。
その他のリソースとサンプル
- Google Data API ガイド ブログの SafeFrame の例
- インストール済みアプリケーションの認証