هشدار : این صفحه درباره APIهای قدیمیتر گوگل، یعنی APIهای دادههای گوگل، است؛ این صفحه فقط مربوط به APIهایی است که در فهرست APIهای دادههای گوگل فهرست شدهاند و بسیاری از آنها با APIهای جدیدتر جایگزین شدهاند. برای اطلاعات بیشتر در مورد یک API جدید خاص، به مستندات API جدید مراجعه کنید. برای اطلاعات بیشتر در مورد تأیید درخواستها با یک API جدیدتر، به بخش تأیید هویت و مجوز حسابهای گوگل مراجعه کنید.
مهم: از ClientLogin برای برنامههای جدید استفاده نکنید . در عوض، از پروتکل احراز هویت OAuth که امنتر است استفاده کنید. ClientLogin یک پروتکل احراز هویت منسوخ شده است و از 20 آوریل 2015 رد شده است. در آن زمان، درخواستهای ClientLogin دیگر پاسخ داده نخواهند شد. اگر برنامههای موجود شما از ClientLogin استفاده میکنند، توصیه میکنیم به OAuth مهاجرت کنید. پشتیبانی از ClientLogin در این کتابخانه در نسخه اصلی بعدی حذف خواهد شد.
این سند نحوه استفاده از احراز هویت گوگل برای برنامههای نصبشده در هر یک از کتابخانههای کلاینت Google Data API را شرح میدهد.
برنامههای نصبشدهای که نیاز به دسترسی به دادههای خصوصی کاربر (محافظتشده توسط حساب گوگل یا G Suite) دارند، میتوانند از ClientLogin به عنوان ابزاری برنامهنویسیشده برای احراز هویت کاربران استفاده کنند. «برنامه نصبشده» برنامهای است که بر روی دستگاهی مانند رایانه رومیزی یا تلفن همراه نصب میشود، برخلاف یک برنامه وب.
ساخت یک برنامه وب؟
استفاده از ClientLogin به عنوان روش احراز هویت برای برنامههای وب توصیه نمیشود. در عوض، لطفاً به بخش «استفاده از AuthSub با کتابخانههای کلاینت Google Data API» مراجعه کنید.
مخاطب
این سند برای توسعهدهندگانی در نظر گرفته شده است که میخواهند برنامههایی بنویسند که با استفاده از کتابخانههای کلاینت APIهای Google Data به سرویس Google Data دسترسی داشته باشند. این سند فرض میکند که شما با رابط ClientLogin آشنا هستید. برای شرح کامل پروتکل ClientLogin، به بخش احراز هویت برای برنامههای نصبشده مراجعه کنید.
کتابخانههای کلاینت Google Data API روشهایی را برای کمک به شما در استفاده از ClientLogin در برنامههایتان ارائه میدهند. به طور خاص، روشهایی برای دریافت توکن احراز هویت، مدیریت چالشهای CAPTCHA، فراخوانی توکن احراز هویت برای استفادههای بعدی و ارسال هدر صحیح Authorization با هر درخواست وجود دارد.
استفاده از ClientLogin و APIهای Google Data بدون کتابخانههای کلاینت
کتابخانههای کلاینت به هیچ وجه تنها راه استفاده از ClientLogin در برنامههای شما نیستند. هر آنچه که باید بدانید را میتوانید در مستندات ClientLogin، Authentication for Installed Applications ، بیابید. با این حال، کتابخانههای کلاینت روشهای مفیدی برای استفاده از ClientLogin در برنامه Google Data شما ارائه میدهند.
کار با ClientLogin و APIهای Google Data: نمونههایی از کتابخانه کلاینت
این بخش نمونههایی از استفاده از کتابخانههای کلاینت Google Data APIs را برای دنبال کردن مراحل ذکر شده در بخش « رابط ClientLogin » از مستندات ClientLogin ارائه میدهد.
مثالهای موجود در این سند، تعامل با تقویم گوگل را نشان میدهند (اگرچه برای دنبال کردن مثالها نیازی به دانستن چیزی در مورد API دادههای تقویم ندارید).
دریافت توکن احراز هویت
برای استفاده از ClientLogin، برنامه شما باید یک درخواست HTTPS POST به handler مربوط به ClientLogin https://www.google.com/accounts/ClientLogin ارسال کند. بدنه POST باید به صورت form post با کدگذاری پیشفرض application/x-www-form-urlencoded ساختاربندی شود. با استفاده از یکی از کتابخانههای کلاینت، میتوانید این درخواست را در یک خط کد ارسال کنید.
نمونههای زیر ابتدا یک شیء سرویس راهاندازی میکنند که به 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
پی اچ پی
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()
همانند نسخه ۲.۰+، اگر کاربران شما از حساب 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')
اگر از کلاسهای قدیمیتر نسخه ۱.۰ مبتنی بر 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 از مستندات «احراز هویت برای برنامههای نصبشده» مراجعه کنید.
منابع و نمونههای بیشتر
- مثالهای ClientLogin در وبلاگ نکات API داده گوگل
- احراز هویت برای برنامههای نصب شده