Google Data Protocol 用戶端程式庫中的 ClientLogin

警告：本頁面介紹的是 Google 舊版 API (Google Data API)，僅適用於Google Data API 目錄中列出的 API，其中許多 API 已由新版 API 取代。如要瞭解特定新版 API，請參閱該 API 的說明文件。如要瞭解如何使用較新的 API 授權要求，請參閱「Google 帳戶驗證和授權」。

重要事項：請勿為新應用程式使用 ClientLogin。請改用更安全的 OAuth 驗證通訊協定。ClientLogin 是已淘汰的驗證通訊協定，將於 2015 年 4 月 20 日停用。屆時系統將不再回應 ClientLogin 要求。如果您現有的應用程式使用 ClientLogin，建議您遷移至 OAuth。我們將在下一個主要版本中移除這個程式庫的 ClientLogin 支援。

本文說明如何在各個 Google Data API 用戶端程式庫中，使用 Google 的已安裝應用程式驗證。

如要存取使用者私人資料 (受 Google 或 G Suite 帳戶保護)，已安裝的應用程式可使用 ClientLogin 做為驗證使用者的程式輔助方式。「已安裝的應用程式」是指安裝在裝置上的應用程式，例如桌上型電腦或手機，而非網路應用程式。

您要建構網頁應用程式嗎？

我們不建議網路應用程式使用 ClientLogin 做為驗證方法。請改為參閱「使用 Google Data API 用戶端程式庫搭配 AuthSub」。

觀眾

本文適用於想使用 Google Data API 用戶端程式庫，編寫可存取 Google Data 服務的應用程式的開發人員。本文假設您熟悉 ClientLogin 介面。如要完整瞭解 ClientLogin 的通訊協定，請參閱「已安裝應用程式的驗證」。

Google Data API 用戶端程式庫提供的方法可協助您在應用程式中使用 ClientLogin。具體來說，這些方法包括取得驗證權杖、處理人機驗證 (CAPTCHA) 挑戰、回呼驗證權杖以供日後使用，以及在每個要求中傳送正確的 Authorization 標頭。

不使用用戶端程式庫，改用 ClientLogin 和 Google Data API

用戶端程式庫絕不是在應用程式中使用 ClientLogin 的唯一方法。如需所有相關資訊，請參閱 ClientLogin 說明文件中的「已安裝應用程式的驗證」。不過，用戶端程式庫提供實用的方法，可在 Google Data 應用程式中使用 ClientLogin。

使用 ClientLogin 和 Google Data API：用戶端程式庫範例

本節提供使用 Google Data API 用戶端程式庫的範例，說明如何按照 ClientLogin 說明文件的「ClientLogin 介面」一節所述步驟操作。

本文中的範例會示範如何與 Google 日曆互動 (但您不需要瞭解 Calendar Data API 即可按照範例操作)。

取得驗證權杖

如要使用 ClientLogin，應用程式應向處理常式 ClientLogin 的處理常式 https://www.google.com/accounts/ClientLogin 發出 HTTPS POST。POST 主體應以表單發布的形式建構，並採用預設編碼 application/x-www-form-urlencoded。使用其中一個用戶端程式庫，您可以在一行程式碼中提出這項要求。

下列範例會先設定連線至 Calendar Data API 的服務物件，然後對 ClientLogin 處理常式發出 HTTP POST。

Java

import com.google.gdata.client.*;
import com.google.gdata.client.calendar.*;

CalendarService client = new CalendarService("yourCompany-yourAppName-v1");
client.setUserCredentials("[e-mail]", "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("[e-mail]", "pa$$word", ClientLoginAccountType.HOSTED);

.NET

using Google.GData.Client;
using Google.GData.Calendar;

CalendarService client = new CalendarService("yourCompany-yourAppName-v1");
client.setUserCredentials("[e-mail]", "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("[e-mail]", "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('[e-mail]', '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(
    '[e-mail]', '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 = '[e-mail]'
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 = '[e-mail]'
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()

與 2.0 以上版本相同，如果使用者將使用 G Suite 帳戶，您可以指定適當的 ClientLogin 帳戶類型：

import gdata.calendar.service

client = gdata.calendar.service.CalendarService()
client.ClientLogin('[e-mail]', '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 [e-mail] 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 [e-mail].

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 = "[e-mail]";
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("[e-mail]", "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 = '[e-mail]';
$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 為基礎的舊版 1.0 類別，程序會略有不同。

import gdata.service

email = '[e-mail]'
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，請參閱「Authentication for Installed Applications」(已安裝應用程式的驗證) 說明文件的「ClientLogin Response」(ClientLogin 回應) 一節。

其他資源和範例

• Google Data API 提示網誌上的 ClientLogin 範例
• 已安裝應用程式的驗證

返回頁首