ClientLogin در Google Data Protocol Client Libraries

اخطار : این صفحه درباره APIهای قدیمی Google، Google Data APIها است. فقط مربوط به APIهایی است که در فهرست راهنمای Google Data APIs فهرست شده اند، که بسیاری از آنها با 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 APIs به سرویس Google Data دسترسی دارند. این سند فرض می کند که شما با رابط کاربری ClientLogin آشنا هستید. برای توضیح کامل پروتکل ClientLogin، به احراز هویت برای برنامه های نصب شده مراجعه کنید.

کتابخانه های سرویس گیرنده Google Data API روش هایی را برای کمک به شما در استفاده از ClientLogin در برنامه های خود ارائه می دهند. به طور خاص، روش‌هایی برای به دست آوردن یک نشانه احراز هویت، رسیدگی به چالش‌های CAPTCHA، فراخوانی رمز تأیید برای استفاده بعدی، و ارسال هدر Authorization صحیح با هر درخواست وجود دارد.

استفاده از ClientLogin و Google Data API بدون کتابخانه های سرویس گیرنده

کتابخانه های سرویس گیرنده به هیچ وجه تنها راه استفاده از ClientLogin در برنامه های شما نیستند. هر چیزی که باید بدانید را می توانید در اسناد ClientLogin، Authentication for Installed Applications پیدا کنید. با این حال، کتابخانه های سرویس گیرنده روش های مفیدی برای استفاده از ClientLogin در برنامه Google Data شما ارائه می دهند.

کار با ClientLogin و Google Data API: نمونه های کتابخانه مشتری

این بخش نمونه‌هایی از استفاده از کتابخانه‌های سرویس گیرنده Google Data APIs را برای دنبال کردن مراحل ذکر شده در بخش « رابط ClientLogin » در اسناد ClientLogin ارائه می‌کند.

مثال‌های موجود در این سند تعامل با Google Calendar را نشان می‌دهند (اگرچه برای دنبال کردن مثال‌ها نیازی به دانستن چیزی در مورد 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 ایجاد می‌کند.

جاوا

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

.خالص

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

پایتون

اگر از کلاس‌های جدیدتر 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());
}

.خالص

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();
  }
}

پایتون

اگر از کلاس‌های جدیدتر 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 Response در مستندات "Authentication for Installed Applications" مراجعه کنید.

منابع و نمونه های اضافی

بازگشت به بالا