ClientLogin في مكتبات برامج بروتوكول بيانات Google

تحذير: تتعلق هذه الصفحة بواجهات برمجة التطبيقات القديمة من Google، وهي واجهات برمجة التطبيقات لبيانات Google؛ وهي مرتبطة فقط بواجهات برمجة التطبيقات المدرجة في دليل 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 (على الرغم من أنك لست بحاجة إلى معرفة أي شيء حول واجهة برمجة التطبيقات لبيانات التقويم لاتباع الأمثلة).

الحصول على رمز مصادقة مميز

لاستخدام ClientLogin، يجب أن ينشئ تطبيقك HTTPS POST إلى معالج ClientLogin https://www.google.com/accounts/ClientLogin. يجب تنظيم نص POST كمشاركة نموذج باستخدام الترميز التلقائي application/x-www-form-urlencoded. وباستخدام إحدى مكتبات العملاء، يمكنك إجراء هذا الطلب في سطر شفرة واحد.

تعمل النماذج التالية أولاً على إعداد كائن خدمة يتصل بـ "واجهة برمجة التطبيقات لبيانات التقويم"، ثم إعداد 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

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

موارد ونماذج إضافية

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