ClientLogin ในไลบรารีของไคลเอ็นต์โปรโตคอลข้อมูลของ Google

คําเตือน: หน้านี้เกี่ยวกับ 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 API เอกสารนี้จะสมมติว่าคุณคุ้นเคยกับอินเทอร์เฟซ ClientLogin โปรดดูคําอธิบายโปรโตคอลทั้งหมดของ ClientLogin ที่หัวข้อการตรวจสอบสิทธิ์สําหรับแอปพลิเคชันที่ติดตั้งไว้

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

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

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

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

ส่วนนี้จะแสดงตัวอย่างการใช้ไลบรารีของไคลเอ็นต์ Google Data API เพื่อทําตามขั้นตอนที่ระบุไว้ในส่วน "The ClientLogin Interface" ของเอกสารประกอบ 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()

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

ทรัพยากรและตัวอย่างเพิ่มเติม

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