ClientLogin في مكتبات برامج Google Data Protocol

تحذير: تتناول هذه الصفحة واجهات برمجة التطبيقات القديمة من Google، أي Google Data APIs، وهي ذات صلة فقط بواجهات برمجة التطبيقات المدرَجة في دليل Google Data APIs، وقد تم استبدال العديد منها بواجهات برمجة تطبيقات أحدث. للحصول على معلومات حول واجهة برمجة تطبيقات جديدة معيّنة، يُرجى الاطّلاع على مستندات واجهة برمجة التطبيقات الجديدة. للحصول على معلومات عن الموافقة على الطلبات باستخدام واجهة برمجة تطبيقات أحدث، يُرجى الاطّلاع على مقالة المصادقة والتفويض في حسابات 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 APIs بدون مكتبات البرامج

إنّ مكتبات البرامج ليست بأي حال من الأحوال الطريقة الوحيدة لاستخدام ClientLogin في تطبيقاتك. يمكنك العثور على كل ما تحتاج إلى معرفته في مستندات ClientLogin، المصادقة للتطبيقات المثبَّتة. في المقابل، توفّر مكتبات البرامج طرقًا مفيدة لاستخدام ClientLogin في تطبيق "بيانات Google".

العمل مع ClientLogin وGoogle Data APIs: أمثلة على مكتبات البرامج

يعرض هذا القسم أمثلة على استخدام مكتبات برامج Google Data APIs لتنفيذ الخطوات الموضّحة في قسم واجهة 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.

جافا

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

إذا كنت تستخدم الفئات الأحدث 2.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

إذا كنت تستخدم الفئات الأحدث 2.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')

إذا كنت تستخدم الفئات القديمة 1.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" في مستندات "المصادقة للتطبيقات المثبّتة".

مراجع وعيّنات إضافية

الرجوع إلى الأعلى