ClientLogin ในไลบรารีของไคลเอ็นต์ Google Data Protocol

คำเตือน: หน้านี้เป็นข้อมูลเกี่ยวกับ API เก่าของ Google ซึ่งก็คือ Google Data API โดยเกี่ยวข้องกับ API ที่แสดงอยู่ในไดเรกทอรี Google Data API เท่านั้น ซึ่ง API หลายรายการถูกแทนที่ด้วย API ใหม่กว่าแล้ว ดูข้อมูลเกี่ยวกับ API ใหม่ที่เฉพาะเจาะจงได้ในเอกสารประกอบของ API ใหม่ ดูข้อมูลเกี่ยวกับการให้สิทธิ์คำขอด้วย API เวอร์ชันใหม่กว่าได้ที่การตรวจสอบสิทธิ์และการให้สิทธิ์บัญชี Google

สำคัญ: อย่าใช้ ClientLogin สำหรับแอปพลิเคชันใหม่ แต่ให้ใช้โปรโตคอลการตรวจสอบสิทธิ์ OAuth ที่ปลอดภัยกว่าแทน ClientLogin เป็นโปรโตคอลการตรวจสอบสิทธิ์ที่เลิกใช้งานแล้ว และจะปิดตัวลงในวันที่ 20 เมษายน 2015 เมื่อถึงเวลานั้น ระบบจะไม่ตอบคำขอ ClientLogin อีกต่อไป หากมีแอปพลิเคชันที่ใช้ ClientLogin อยู่แล้ว เราขอแนะนำให้คุณย้ายข้อมูลไปยัง OAuth เราจะนำการรองรับ ClientLogin ในไลบรารีนี้ออกในการเปิดตัวเวอร์ชันหลักครั้งถัดไป

เอกสารนี้อธิบายวิธีใช้การตรวจสอบสิทธิ์สำหรับแอปพลิเคชันที่ติดตั้งของ Google ภายในไลบรารีของไคลเอ็นต์ Google Data API แต่ละรายการ

แอปพลิเคชันที่ติดตั้งซึ่งต้องเข้าถึงข้อมูลส่วนตัวของผู้ใช้ (ได้รับการปกป้องโดยบัญชี Google หรือ G Suite) สามารถใช้ ClientLogin เป็นวิธีการแบบเป็นโปรแกรม ในการตรวจสอบสิทธิ์ผู้ใช้ "แอปพลิเคชันที่ติดตั้ง" คือแอปพลิเคชันที่ติดตั้งในอุปกรณ์ เช่น คอมพิวเตอร์เดสก์ท็อปหรือโทรศัพท์มือถือ ซึ่งแตกต่างจากเว็บแอปพลิเคชัน

กำลังสร้างเว็บแอปพลิเคชันใช่ไหม

เราไม่แนะนำให้เว็บแอปพลิเคชันใช้ ClientLogin เป็นวิธีการตรวจสอบสิทธิ์ โปรดดูการใช้ AuthSub กับไลบรารีของไคลเอ็นต์ Google Data API แทน

กลุ่มเป้าหมาย

เอกสารนี้มีไว้สำหรับนักพัฒนาซอฟต์แวร์ที่ต้องการเขียนแอปพลิเคชันที่เข้าถึงบริการ Google Data โดยใช้ไลบรารีของไคลเอ็นต์ Google Data APIs เอกสารนี้ถือว่าคุณคุ้นเคยกับอินเทอร์เฟซ ClientLogin ดูคำอธิบายแบบเต็มของโปรโตคอล ClientLogin ได้ที่ การตรวจสอบสิทธิ์สำหรับแอปพลิเคชันที่ติดตั้ง

ไลบรารีของไคลเอ็นต์ Google Data API มีเมธอดที่จะช่วยให้คุณใช้ ClientLogin ในแอปพลิเคชันได้ โดยเฉพาะอย่างยิ่ง มีวิธีการสำหรับ การขอโทเค็นการตรวจสอบสิทธิ์ การจัดการกับ CAPTCHA การเรียกคืนโทเค็นการตรวจสอบสิทธิ์เพื่อใช้ในภายหลัง และการส่งส่วนหัว Authorization ที่ถูกต้องพร้อมกับคำขอทุกรายการ

การใช้ ClientLogin และ Google Data API โดยไม่มีไลบรารีของไคลเอ็นต์

ไลบรารีของไคลเอ็นต์ไม่ใช่เพียงวิธีเดียวในการใช้ ClientLogin ในแอปพลิเคชัน คุณดูข้อมูลทั้งหมดที่จำเป็นได้ใน เอกสารประกอบ ClientLogin ซึ่งก็คือการตรวจสอบสิทธิ์สำหรับแอปพลิเคชันที่ติดตั้ง อย่างไรก็ตาม ไลบรารีของไคลเอ็นต์มีวิธีการที่เป็นประโยชน์ในการใช้ ClientLogin ในแอปพลิเคชัน Google Data

การทำงานกับ ClientLogin และ Google Data API: ตัวอย่างไลบรารีของไคลเอ็นต์

ส่วนนี้จะแสดงตัวอย่างการใช้ไลบรารีของไคลเอ็นต์ Google Data API เพื่อทำตามขั้นตอนที่ระบุไว้ในส่วน "อินเทอร์เฟซ ClientLogin" ของเอกสารประกอบ ClientLogin

ตัวอย่างในเอกสารนี้แสดงการโต้ตอบกับ Google ปฏิทิน (แม้ว่าคุณจะไม่จำเป็นต้องทราบเกี่ยวกับ Calendar Data API เพื่อทำตามตัวอย่าง)

การขอโทเค็นการตรวจสอบสิทธิ์

หากต้องการใช้ ClientLogin แอปพลิเคชันของคุณควรส่ง HTTPS POST ไปยังตัวแฮนเดิลของ ClientLogin https://www.google.com/accounts/ClientLogin POST เนื้อหาควรมีโครงสร้าง เป็นการโพสต์แบบฟอร์มที่มีการเข้ารหัสเริ่มต้น application/x-www-form-urlencoded การใช้ไลบรารีของไคลเอ็นต์อย่างใดอย่างหนึ่งจะช่วยให้คุณ ส่งคำขอนี้ได้ในโค้ดบรรทัดเดียว

ตัวอย่างต่อไปนี้จะตั้งค่าออบเจ็กต์บริการที่เชื่อมต่อกับ Calendar Data API ก่อน จากนั้นจึงสร้าง HTTP POST ไปยังตัวแฮนเดิล ClientLogin

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

หากคุณใช้คลาส v2.0 ขึ้นไปที่ใหม่กว่าซึ่งอิงตาม GDClient ให้ใช้สิ่งต่อไปนี้

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 คุณสามารถ ระบุประเภทบัญชี ClientLogin ที่เหมาะสมได้

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

หากคุณใช้คลาส v2.0 ขึ้นไปที่ใหม่กว่าซึ่งอิงตาม GDClient ให้ใช้สิ่งต่อไปนี้

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')

หากคุณใช้คลาส v1.0 รุ่นเก่าที่อิงตาม GDataService กระบวนการจะแตกต่างออกไปเล็กน้อย

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 ได้ที่ส่วนการตอบกลับ ClientLogin ในเอกสารประกอบ "การตรวจสอบสิทธิ์สำหรับแอปพลิเคชันที่ติดตั้ง"

แหล่งข้อมูลและตัวอย่างเพิ่มเติม

ตัวอย่าง ClientLogin ในบล็อกเคล็ดลับเกี่ยวกับ Google Data API
การตรวจสอบสิทธิ์สำหรับแอปพลิเคชันที่ติดตั้ง

กลับไปด้านบน