דף זה תורגם על ידי Cloud Translation API.

ClientLogin בספריות הלקוח של פרוטוקול הנתונים של Google

אזהרה: דף זה עוסק בממשקי API הישנים יותר של Google, בממשקי ה-API של נתוני Google, והוא רלוונטי רק לממשקי ה-API שרשומים בספריית ממשקי ה-API של נתוני Google, שרבים מהם הוחלפו בממשקי API חדשים יותר. למידע על API חדש ספציפי, עיינו במסמכי התיעוד של ה-API החדש. למידע על הרשאת בקשות באמצעות ממשק API חדש יותר, יש לעיין בקטע אימות והרשאה של חשבונות Google.

חשוב: לא להשתמש ב-ClientLogin לאפליקציות חדשות. במקום זאת, יש להשתמש בפרוטוקול האימות המאובטח יותר מסוג OAuth. ClientLogin הוא פרוטוקול אימות שהוצא משימוש, ויושבת ב-20 באפריל 2015. במועד זה, בקשות ClientLogin לא ייענו. אם יש לך אפליקציות קיימות שמשתמשות ב-ClientLogin, מומלץ לעבור ל-OAuth. התמיכה של ClientLogin בספרייה הזו תוסר בגרסה הראשית הבאה.

מסמך זה מתאר כיצד להשתמש באימות של Google Apps המותקנים בכל אחת מספריות הלקוח של Google Data API.

אפליקציות מותקנות שזקוקות לגישה לנתונים פרטיים של משתמש (המוגנות על ידי חשבון Google או G Suite), יכולות להשתמש ב-ClientLogin כאמצעי פרוגרמטי לאימות משתמשים. "אפליקציה מותקנת" היא אפליקציה המותקנת במכשיר, כגון מחשב שולחני או טלפון סלולרי, בניגוד לאפליקציית אינטרנט.

בונים אפליקציית אינטרנט?

לא מומלץ ליישומי אינטרנט להשתמש ב-ClientLogin בתור שיטת האימות שלהם. במקום זאת, אפשר לקרוא על שימוש ב-AuthSub בספריות הלקוח של Google Data API.

Audience

המסמך הזה מיועד למפתחים שרוצים לכתוב אפליקציות שיש להן גישה לשירות של נתוני Google באמצעות ספריות הלקוח של 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 (עם זאת, לא צריך לדעת דבר על ה-Data Data API כדי לעקוב אחר הדוגמאות).

קבלת אסימון אימות

כדי להשתמש ב-ClientLogin, האפליקציה שלך צריכה להפוך את POST ל-handler של handler של ClientLogin https://www.google.com/accounts/ClientLogin. הגוף של POST צריך להיות מובנה כפוסט בטופס עם קידוד ברירת המחדל application/x-www-form-urlencoded. באמצעות אחת מספריות הלקוח, אפשר לשלוח את הבקשה הזו בשורת קוד אחת.

בדוגמאות הבאות הוגדרה קודם כל אובייקט שירות המתחבר ל-Calendar Data API, ולאחר מכן יוצר HTTP POST ל-handler של 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:

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

אם אתם משתמשים במחלקות 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 בבלוג הטיפים של Google Data API
אימות לאפליקציות מותקנות

חזרה למעלה