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

تحذير: تتناول هذه الصفحة واجهات برمجة التطبيقات القديمة من Google، أي Google Data APIs، وهي ذات صلة فقط بواجهات برمجة التطبيقات المدرَجة في دليل Google Data APIs، وقد تم استبدال العديد منها بواجهات برمجة تطبيقات أحدث. للحصول على معلومات حول واجهة برمجة تطبيقات جديدة معيّنة، يُرجى الاطّلاع على مستندات واجهة برمجة التطبيقات الجديدة. للحصول على معلومات عن الموافقة على الطلبات باستخدام واجهة برمجة تطبيقات أحدث، يُرجى الاطّلاع على مقالة المصادقة والتفويض في حسابات Google.

يوضّح هذا المستند كيفية استخدام مكتبات برامج Google Data API للربط بـ مصادقة OAuth لتطبيقات الويب من Google.

تتيح واجهة OAuth لتطبيق مستند إلى الويب الوصول إلى إحدى خدمات Google بالنيابة عن مستخدم. للحفاظ على مستوى عالٍ من الأمان، يتيح بروتوكول OAuth للتطبيق الحصول على رمز مميّز للوصول بدون الحاجة إلى معالجة معلومات تسجيل الدخول إلى حساب المستخدم.

توفّر مكتبات عميل Google Data API طرقًا لمساعدتك في استخدام OAuth في تطبيق الويب. على وجه التحديد، هناك طرق لإنشاء رمز مميّز للطلب والحصول عليه، والمصادقة على الرمز المميّز للطلب، واستبدال الرمز المميّز للطلب الذي تمت المصادقة عليه برمز مميّز للدخول. وتتعامل المكتبات أيضًا مع خوارزميات التوقيع اللازمة عند إرسال طلبات إلى إحدى خدمات "بيانات Google".

الجمهور

هذا المستند مخصّص للمبرمجين الذين يريدون أن تتمكّن تطبيقاتهم المستندة إلى الويب من الوصول إلى خدمات Google بالنيابة عن المستخدمين، وذلك باستخدام مكتبات برامج Google Data APIs.

يفترض هذا المستند أنّك على دراية بواجهة OAuth وعملية دمجها بشكل عام في تطبيق الويب. للحصول على وصف كامل لبروتوكول OAuth، يُرجى الاطّلاع على مصادقة OAuth لتطبيقات الويب أو المواصفات الرسمية على oauth.net.

استخدام بروتوكول OAuth الثلاثي وGoogle Data APIs بدون مكتبات العميل

إذا كنت تريد أن يتفاعل تطبيق الويب الخاص بك مع إحدى خدمات "بيانات Google" باستخدام OAuth كطريقة تفويض، ستجد كل ما تحتاج إلى معرفته في مصادقة OAuth لتطبيقات الويب. ليس عليك استخدام مكتبات برامج Google Data APIs إذا كنت لا تريد ذلك.

في ما يلي مخطط تفصيلي لكيفية مصادقة تطبيقك لمستخدم باستخدام OAuth:

  1. يرسل تطبيقك طلبًا موقّعًا لجلب رمز طلب OAuth الأولي من نقطة النهاية OAuthRequestToken.
  2. يعيد تطبيقك توجيه المستخدم إلى عنوان URL المناسب OAuthAuthorizeToken لتفويض رمز الطلب.
  3. عند منح الإذن بالوصول، تتم إعادة توجيه المستخدم إلى تطبيقك (عنوان URL oauth_callback).
  4. يرسل تطبيقك طلبًا موقّعًا لترقية رمز الطلب المفوَّض إلى رمز دخول باستخدام نقطة النهاية OAuthGetAccessToken.

تسهّل مكتبات عملاء Google Data APIs عملية منح الإذن هذه من خلال معالجة تفاصيل مختلفة نيابةً عنك. يوضّح هذا المستند كيفية إجراء ذلك.

تسجيل تطبيق الويب

يتطلّب بروتوكول OAuth توقيع جميع طلبات البيانات من واجهة برمجة التطبيقات رقميًا. يتيح محرّك بحث Google استخدام طريقتَي التوقيع HMAC-SHA1 وRSA-SHA1. لتوقيع الطلبات، يجب أن يسجّل تطبيقك لدى Google أولاً. بعد التسجيل، ستزوّدك Google بمفتاح مستهلك (ورمز سري لاستخدامه مع HMAC-SHA1)، ومكان لتحميل شهادة عامة.

1. تسجيل نطاقك

يُرجى اتّباع الخطوات الموضّحة في التسجيل في التطبيقات المستندة إلى الويب.

2. إنشاء زوج من المفتاح الخاص والشهادة العامة (اختياري)

إذا اخترت استخدام RSA-SHA1 كـ oauth_signature_method، عليك إنشاء RSA مفتاح خاص وشهادة عامة موقّعة ذاتيًا. راجِع القسم إنشاء مفتاح خاص وشهادة عامة ذاتية التوقيع(أدناه) للاطّلاع على أمثلة حول كيفية إجراء ذلك.

العمل باستخدام بروتوكول OAuth الثلاثي وGoogle Data APIs: أمثلة على مكتبات العملاء

تعرض الأقسام التالية أمثلة على استخدام طرق مكتبة برامج Google Data APIs لتنفيذ الخطوات الموضّحة في قسم العمل مع OAuth من مستندات OAuth. تفترض جميع الأمثلة الواردة في هذا المستند أنّ نطاق مضيف تطبيقك هو example.com.

تحديد نطاق الوصول إلى بياناتك

تحدّد كل خدمة من خدمات Google قيمة scope تحدّد إذن الوصول إلى بيانات المستخدم. يمكنك الاطّلاع على قيم النطاق المتاحة في الأسئلة الشائعة حول بيانات Google. على سبيل المثال، لاستخدام Documents List API، اضبط scope على https://docs.google.com/feeds/، كما هو موضّح في الأسئلة الشائعة.

ملاحظة: اضبط قيمة scope على أضيق عنوان URL يسمح بالوصول الذي تحتاجه. ويقلّل ذلك من فرص الحصول على البيانات الشخصية وتسريبها عن طريق الخطأ. على سبيل المثال، إذا أردت الوصول إلى خلاصة "قائمة المستندات" الخاصة بالمستخدم الحالي، استخدِم النطاق https://docs.google.com/feeds/default/private/full بدلاً من نطاق أوسع مثل https://docs.google.com/feeds/، الذي يتيح الوصول إلى جميع خلاصات "قائمة المستندات".

الرموز المميزة المتعددة النطاقات

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

scope=https://www.google.com/calendar/feeds/ https://docs.google.com/feeds/
ترميز عنوان URL

يجب ترميز عناوين URL التي تتضمّن أحرفًا غير ASCII، بما في ذلك النقطتان الشرطيتان والشرطة المائلة والمسافة، لكي يتم نقلها عبر HTTP. تشفّر مكتبات عميل Google Data API مَعلمات عناوين URL تلقائيًا، لذا يمكنك ببساطة استخدام سلاسل غير مشفّرة عند تعيين قيم للمَعلمات. على سبيل المثال، يمكنك إجراء عملية التعيين التالية في الرمز البرمجي:

scope=https://www.google.com/calendar/feeds/ https://docs.google.com/feeds/

عند استدعاء مكتبة العميل، يتم تلقائيًا ترميز المَعلمة scope بعنوان URL إلى القيمة التالية:
https%3a%2f%2fwww.google.com%2fcalendar%2ffeeds%2f+https%3a%2f%2fdocs.google.com%2ffeeds%2f

الحصول على رمز مميّز للطلب

جافا

بالنسبة إلى HMAC-SHA1، أنت بحاجة إلى طريقة ما للاحتفاظ بسر الرمز المميز (الذي تم الحصول عليه في الرد) من أجل إنشاء عنصر رمز مميز لبروتوكول OAuth يعود من صفحة الموافقة. لإجراء ذلك، اضبط متغيّر جلسة أو ملف تعريف ارتباط.

import com.google.gdata.client.docs.*;
import com.google.gdata.client.authn.oauth.*;

String CONSUMER_KEY = "example.com";
String CONSUMER_SECRET = "abc123doremi";

GoogleOAuthParameters oauthParameters = new GoogleOAuthParameters();
oauthParameters.setOAuthConsumerKey(CONSUMER_KEY);
oauthParameters.setOAuthConsumerSecret(CONSUMER_SECRET);
oauthParameters.setScope("https://docs.google.com/feeds/");
oauthParameters.setOAuthCallback("http://www.example.com/UpgradeToken.jsp");

GoogleOAuthHelper oauthHelper = new GoogleOAuthHelper(new OAuthHmacSha1Signer());
oauthHelper.getUnauthorizedRequestToken(oauthParameters);

باستخدام RSA-SHA1، لا يتم استخدام oauth_token_secret، لذا ليس من الضروري الاحتفاظ بسر الرمز المميّز.

import com.google.gdata.client.docs.*;
import com.google.gdata.client.authn.oauth.*;

String CONSUMER_KEY = "example.com";

GoogleOAuthParameters oauthParameters = new GoogleOAuthParameters();
oauthParameters.setOAuthConsumerKey(CONSUMER_KEY);
oauthParameters.setScope("https://docs.google.com/feeds/");
oauthParameters.setOAuthCallback("http://www.example.com/UpgradeToken.jsp");

PrivateKey privKey = getPrivateKey("/path/to/your/rsakey.pk8");

GoogleOAuthHelper oauthHelper = new GoogleOAuthHelper(new OAuthRsaSha1Signer(privKey));
oauthHelper.getUnauthorizedRequestToken(oauthParameters);

...

public static PrivateKey getPrivateKey(String privKeyFileName) {
  File privKeyFile = new File(privKeyFileName);
  FileInputStream fis = new FileInputStream(privKeyFile);
  DataInputStream dis  = new DataInputStream(fis);

  byte[] privKeyBytes = new byte[(int) privKeyFile.length()];
  dis.read(privKeyBytes);
  dis.close();
  fis.close();

  String BEGIN = "-----BEGIN PRIVATE KEY-----";
  String END = "-----END PRIVATE KEY-----";
  String str = new String(privKeyBytes);
  if (str.contains(BEGIN) && str.contains(END)) {
    str = str.substring(BEGIN.length(), str.lastIndexOf(END));
  }

  KeyFactory fac = KeyFactory.getInstance("RSA");
  EncodedKeySpec privKeySpec = new PKCS8EncodedKeySpec(Base64.decode(str));
  return fac.generatePrivate(privKeySpec);
}

PHP

استخدام HMAC-SHA1 كطريقة التوقيع:

require_once 'Zend/Oauth/Consumer.php';

session_start();

$CONSUMER_KEY = 'example.com';
$CONSUMER_SECRET = 'abc123doremi';

// Multi-scoped token.
$SCOPES = array(
  'https://docs.google.com/feeds/',
  'https://spreadsheets.google.com/feeds/'
);

$oauthOptions = array(
  'requestScheme' => Zend_Oauth::REQUEST_SCHEME_HEADER,
  'version' => '1.0',
  'consumerKey' => $CONSUMER_KEY,
  'consumerSecret' => $CONSUMER_SECRET,
  'signatureMethod' => 'HMAC-SHA1',
  'callbackUrl' => 'http://myapp.example.com/access_token.php',
  'requestTokenUrl' => 'https://www.google.com/accounts/OAuthGetRequestToken',
  'userAuthorizationUrl' => 'https://www.google.com/accounts/OAuthAuthorizeToken',
  'accessTokenUrl' => 'https://www.google.com/accounts/OAuthGetAccessToken'
);

$consumer = new Zend_Oauth_Consumer($oauthOptions);

// When using HMAC-SHA1, you need to persist the request token in some way.
// This is because you'll need the request token's token secret when upgrading
// to an access token later on. The example below saves the token object as a session variable.
if (!isset($_SESSION['ACCESS_TOKEN'])) {
  $_SESSION['REQUEST_TOKEN'] = serialize($consumer->getRequestToken(array('scope' => implode(' ', $SCOPES))));
}

استخدام RSA-SHA1 كطريقة التوقيع:

require_once 'Zend/Crypt/Rsa/Key/Private.php';
require_once 'Zend/Oauth/Consumer.php';

session_start();

$CONSUMER_KEY = 'example.com';
$SCOPE = 'https://docs.google.com/feeds/';

$oauthOptions = array(
  'requestScheme' => Zend_Oauth::REQUEST_SCHEME_HEADER,
  'version' => '1.0',
  'consumerKey' => $CONSUMER_KEY,
  'consumerSecret' => new Zend_Crypt_Rsa_Key_Private(file_get_contents(realpath('/path/to/yourRSAPrivateKey.pem'))),
  'signatureMethod' => 'RSA-SHA1',
  'callbackUrl' => 'http://myapp.example.com/access_token.php',
  'requestTokenUrl' => 'https://www.google.com/accounts/OAuthGetRequestToken',
  'userAuthorizationUrl' => 'https://www.google.com/accounts/OAuthAuthorizeToken',
  'accessTokenUrl' => 'https://www.google.com/accounts/OAuthGetAccessToken'
);

$consumer = new Zend_Oauth_Consumer($oauthOptions);

if (!isset($_SESSION['ACCESS_TOKEN'])) {
  $_SESSION['REQUEST_TOKEN'] = serialize($consumer->getRequestToken(array('scope' => $SCOPE)));
}

Python

استخدام HMAC-SHA1 كطريقة التوقيع:

إذا كنت تستخدم الفئات الأحدث 2.0 أو إصدارًا أحدث استنادًا إلى GDClient، استخدِم:

import gdata.gauth
import gdata.docs.client

CONSUMER_KEY = 'example.com'
CONSUMER_SECRET = 'abc123doremi'
SCOPES = ['https://docs.google.com/feeds/', 'https://www.google.com/calendar/feeds/']  # example of a multi-scoped token

client = gdata.docs.client.DocsClient(source='yourCompany-YourAppName-v1')

oauth_callback_url = 'http://%s/get_access_token' % self.request.host
request_token = client.GetOAuthToken(
    SCOPES, oauth_callback_url, CONSUMER_KEY, consumer_secret=CONSUMER_SECRET)

# When using HMAC-SHA1, you need to persist the request_token in some way.
# You'll need the token secret when upgrading to an access token later on.
# In Google App Engine, you can use the AeSave helper:
# gdata.gauth.AeSave(request_token, 'myKey')

استخدام RSA-SHA1 كطريقة التوقيع:

...

f = open('/path/to/yourRSAPrivateKey.pem')
RSA_KEY = f.read()
f.close()

request_token = client.GetOAuthToken(SCOPES, oauth_callback_url, CONSUMER_KEY, rsa_private_key=RSA_KEY)

بدلاً من ذلك، إذا كنت تستخدم الفئات القديمة 1.0 المستندة إلى GDataService، ستكون عمليات الاستدعاء مختلفة قليلاً:

import gdata.auth
import gdata.docs.service

CONSUMER_KEY = 'example.com'
CONSUMER_SECRET = 'abc123doremi'

client = gdata.docs.service.DocsService(source='yourCompany-YourAppName-v1')
client.SetOAuthInputParameters(gdata.auth.OAuthSignatureMethod.HMAC_SHA1, CONSUMER_KEY, consumer_secret=CONSUMER_SECRET)

req_token = client.FetchOAuthRequestToken()
client.SetOAuthToken(req_token)

استخدام RSA-SHA1 كطريقة التوقيع:

...

f = open('/path/to/yourRSAPrivateKey.pem')
RSA_KEY = f.read()
f.close()

client = gdata.docs.service.DocsService(source='yourCompany-YourAppName-v1')
client.SetOAuthInputParameters(gdata.auth.OAuthSignatureMethod.RSA_SHA1, CONSUMER_KEY, rsa_key=RSA_KEY)

SCOPES = ['https://docs.google.com/feeds/', 'https://www.google.com/calendar/feeds/']  # example of a multi-scoped token
req_token = client.FetchOAuthRequestToken(scopes=SCOPES)
client.SetOAuthToken(req_token)

NET.

استخدام HMAC-SHA1 كطريقة التوقيع:

using Google.GData.Client;

string CONSUMER_KEY = "example.com";
string CONSUMER_SECRET = "abc123doremi";

// Multi-scoped token.
string SCOPE = "https://www.google.com/calendar/feeds/ https://www.google.com/m8/feeds/";

OAuthParameters parameters = new OAuthParameters() {
  ConsumerKey = CONSUMER_KEY,
  ConsumerSecret = CONSUMER_SECRET,
  Scope = SCOPE,
  Callback = "http://myapp.example.com/access_token",
  SignatureMethod = "HMAC-SHA1"
}

OAuthUtil.GetUnauthorizedRequestToken(parameters);

استخدام RSA-SHA1 كطريقة التوقيع:

RSA-SHA1 is not supported yet.

منح الإذن باستخدام رمز الطلب

للسماح برمز طلب، يجب أن يعيد تطبيقك توجيه المستخدم إلى عنوان URL الخاص بـ OAuthAuthorizeToken، والذي يطلب منه تسجيل الدخول إلى حسابه على Google. لمزيد من المعلومات عن عنوان URL الخاص بـ OAuthAuthorizeToken، يُرجى الاطّلاع على مصادقة OAuth لتطبيقات الويب الكاملة.

لإنشاء عنوان URL الخاص بـ OAuthAuthorizeToken في تطبيقك، استخدِم ما يلي لكل مكتبة برامج. يُرجى العِلم أنّ هذه العيّنات تستند إلى الأمثلة السابقة.

بعد إنشاء عنوان URL لصفحة الموافقة، يمكن لتطبيقك استخدامه بطرق متنوعة لإرسال المستخدم إلى معالج OAuthAuthorizeToken. الطريقة الأكثر شيوعًا هي إعادة توجيه المستخدم أو عرض رابط يؤدي إلى تلك الصفحة.

جافا

بالنسبة إلى HMAC-SHA1:

String approvalPageUrl = oauthHelper.createUserAuthorizationUrl(oauthParameters);
System.out.println(approvalPageUrl);

بالنسبة إلى RSA-SHA1:

String approvalPageUrl = oauthHelper.createUserAuthorizationUrl(oauthParameters);
System.out.println(approvalPageUrl);

PHP

// If on a G Suite domain, use your domain for the hd param (e.g. 'example.com').
$approvalUrl = $consumer->getRedirectUrl(array('hd' => 'default'));
echo "<a href=\"$approvalUrl\">Grant access</a>";

بدلاً من ذلك، يمكنك إعادة التوجيه ببساطة إلى عنوان URL الخاص بطلب الموافقة:

// If on a G Suite domain, use your domain for the hd param (e.g. 'example.com').
$consumer->redirect(array('hd' => 'default'));

Python

إذا كنت تستخدم الفئات الأحدث 2.0 أو إصدارًا أحدث استنادًا إلى GDClient، استخدِم:

# req_token is from previous call to client.GetOAuthToken()
domain = None  # If on a G Suite domain, use your domain (e.g. 'example.com').
self.redirect(request_token.generate_authorization_url(google_apps_domain=domain))

إذا كنت تستخدم الفئات القديمة 1.0 المستندة إلى GDataService، ستكون العملية مختلفة قليلاً.

# req_token is from previous call to client.FetchOAuthRequestToken()
oauth_callback_url = 'http://%s/get_access_token' % self.request.host
self.redirect(client.GenerateOAuthAuthorizationURL(callback_url=oauth_callback_url))

NET.

string authorizationUrl = OAuthUtil.CreateUserAuthorizationUrl(parameters);
Console.WriteLine(authorizationUrl);

استخراج الرمز المميّز من عنوان URL لرد الاتصال

عندما تعيد Google التوجيه إلى تطبيقك، تتم إضافة oauth_token إلى عنوان URL "oauth_callback_url" كمَعلمة طلب بحث. بعد ذلك، يجب أن يستخرج تطبيقك قيمة الرمز المميّز من مَعلمة طلب البحث لعنوان URL ويعيد إنشاء مَعلمات OAuth.

توفّر مكتبات البرامج طرقًا سهلة لاستخراج oauth_token. تستند هذه النماذج إلى الأمثلة السابقة.

جافا

إذا اخترت الاحتفاظ برمز الأمان المميز في عنوان URL لرد الاتصال (عند استخدام HMAC-SHA1):

GoogleOAuthParameters oauthParameters = new GoogleOAuthParameters();
oauthParameters.setOAuthConsumerKey(CONSUMER_KEY);
oauthParameters.setOAuthConsumerSecret(CONSUMER_SECRET);

GoogleOAuthHelper oauthHelper = new GoogleOAuthHelper(new OAuthHmacSha1Signer());
oauthHelper.getOAuthParametersFromCallback(request.getQueryString(), oauthParameters);

الاختلاف الوحيد مع RSA-SHA1 هو طريقة التوقيع:

GoogleOAuthParameters oauthParameters = new GoogleOAuthParameters();
oauthParameters.setOAuthConsumerKey(CONSUMER_KEY);

PrivateKey privKey = getPrivateKey("/path/to/your/rsakey.pk8");

GoogleOAuthHelper oauthHelper = new GoogleOAuthHelper(new OAuthRsaSha1Signer(privKey));
oauthHelper.getOAuthParametersFromCallback(request.getQueryString(), oauthParameters);

PHP

هذه الخطوة غير ضرورية عند استخدام مكتبة PHP.

Python

إذا كنت تستخدم الفئات الأحدث 2.0 أو إصدارًا أحدث استنادًا إلى GDClient، استخدِم:

# Recall request_token. In Google App Engine, use AeLoad():
# saved_request_token = gdata.gauth.AeLoad('myKey')

request_token = gdata.gauth.AuthorizeRequestToken(saved_request_token, self.request.uri)

إذا كنت تستخدم الفئات القديمة 1.0 المستندة إلى GDataService، استخدِم ما يلي:

oauth_token = gdata.auth.OAuthTokenFromUrl(self.request.uri)
if oauth_token:
  oauth_token.secret = # TODO: recall saved request_token and set the token secret here.
  oauth_token.oauth_input_params = gdata.auth.OAuthInputParams(
      gdata.auth.OAuthSignatureMethod.HMAC_SHA1, CONSUMER_KEY, consumer_secret=CONSUMER_SECRET)
 client.SetOAuthToken(oauth_token)
else:
  print 'No oauth_token found in the URL'

تكون العملية مشابهة بالنسبة إلى RSA-SHA1، ولكن بدون سر الرمز المميز:

oauth_token = gdata.auth.OAuthTokenFromUrl(self.request.uri)
if oauth_token:
  oauth_token.oauth_input_params = gdata.auth.OAuthInputParams(
      gdata.auth.OAuthSignatureMethod.RSA_SHA1, CONSUMER_KEY, rsa_key=RSA_KEY)
 client.SetOAuthToken(oauth_token)
else:
  print 'No oauth_token found in the URL'

NET.

في حال اختيار الاحتفاظ برمز الأمان المميز في عنوان URL لصفحة ردّ الاتصال:

OAuthUtil.UpdateOAuthParametersFromCallback(url, parameters);

الترقية إلى رمز دخول

تتمثّل الخطوة الأخيرة في عملية تبادل رموز OAuth المميزة في ترقية رمز الطلب المفوَّض إلى رمز دخول طويل الأمد باستخدام عنوان URL OAuthGetAccessToken، كما هو موضّح في مستند مصادقة OAuth لتطبيقات الويب الكامل.

في ما يلي بعض الأمثلة باستخدام كلّ من مكتبات البرامج:

جافا

String accessToken = oauthHelper.getAccessToken(oauthParameters);
// You can also pull the OAuth token string from the oauthParameters:
// String accessToken = oauthParameters.getOAuthToken();
System.out.println("OAuth Access Token: " + accessToken);

String accessTokenSecret = oauthParameters.getOAuthTokenSecret();
System.out.println("OAuth Access Token's Secret: " + accessTokenSecret);

PHP

if (!isset($_SESSION['ACCESS_TOKEN'])) {
  if (!empty($_GET) && isset($_SESSION['REQUEST_TOKEN'])) {
    $_SESSION['ACCESS_TOKEN'] = serialize($consumer->getAccessToken($_GET, unserialize($_SESSION['REQUEST_TOKEN'])));
  }
}

Python

إذا كنت تستخدم الفئات الأحدث 2.0 أو إصدارًا أحدث استنادًا إلى GDClient، استخدِم:

# Upgrade the token and save in the user's datastore
access_token = client.GetAccessToken(request_token)

# If you're using Google App Engine, you can call the AeSave() method to save
# the access token under the current logged in user's account.
#gdata.gauth.AeSave(access_token, token_key)

إذا كنت تستخدم الفئات القديمة 1.0 المستندة إلى GDataService، استخدِم ما يلي:

access_token = client.UpgradeToOAuthAccessToken()  # calls SetOAuthToken() for you

إذا كنت تستخدم gdata.gauth.AeSave() على App Engine، سيتم تخزين الرمز المميز ورمز الرمز المميز السري نيابةً عنك ضمن حساب المستخدم الحالي الذي تم تسجيل الدخول إليه.

NET.

OAuthUtil.GetAccessToken(parameters);

// If you want to extract the OAuth Token/TokenSecret from the OAuthParameters instance:
string accessToken = parameter.Token;
Console.WriteLine("OAuth Access Token: " + accessToken);

string accessTokenSecret = parameter.TokenSecret;
Console.WriteLine("OAuth Access Token's Secret: " + accessTokenSecret);

ملاحظة: إذا كنت تستخدم HMAC-SHA1، احرص على حفظ سر الرمز المميز لرمز الدخول إلى جانب قيمة الرمز المميز في قاعدة البيانات، وإلا لن تتمكّن من إعادة إنشاء مَعلمات OAuth بشكل سليم لاستخدامها لاحقًا.

استخدام رمز دخول

بعد الحصول على رمز الدخول، استخدِم طلبات مكتبة برامج Google Data APIs العادية للتفاعل مع الخدمة. ستتولّى المكتبة توقيع الطلبات وتضمين عنوان Authorization الصحيح نيابةً عنك. عادةً، ستسترجع الرمز المميّز للمستخدم من ملف تعريف ارتباط أو قاعدة بيانات. توضّح هذه الأمثلة كيفية إعادة إنشاء مَعلمات OAuth وإجراء طلب من مكتبة برامج العميل.

جافا

إذا كنت تستخدم HMAC-SHA1:

  GoogleOAuthParameters oauthParameters = new GoogleOAuthParameters();
  oauthParameters.setOAuthConsumerKey(CONSUMER_KEY);
  oauthParameters.setOAuthConsumerSecret(CONSUMER_SECRET);
  oauthParameters.setOAuthToken(ACCESS_TOKEN);
  oauthParameters.setOAuthTokenSecret(TOKEN_SECRET);

  DocsService client = new DocsService("yourCompany-YourAppName-v1");
  client.setOAuthCredentials(oauthParameters, new OAuthHmacSha1Signer());

  URL feedUrl = new URL("https://docs.google.com/feeds/default/private/full");
  DocumentListFeed resultFeed = client.getFeed(feedUrl, DocumentListFeed.class);
  for (DocumentListEntry entry : resultFeed.getEntries()) {
    System.out.println(entry.getTitle().getPlainText());
  }
  

يختلف RSA-SHA1 عن المثال السابق في أنّك لست بحاجة إلى ضبط سر الرمز المميز للوصول، كما أنّ طريقة إنشاء عنصر الموقّع تختلف:

  GoogleOAuthParameters oauthParameters = new GoogleOAuthParameters();
  oauthParameters.setOAuthConsumerKey(CONSUMER_KEY);
  oauthParameters.setOAuthConsumerSecret(CONSUMER_SECRET);
  oauthParameters.setOAuthToken(ACCESS_TOKEN);

  PrivateKey privKey = getPrivateKey("/path/to/your/rsakey.pk8");  // See above for the defintion of getPrivateKey()

  DocsService client = new DocsService("yourCompany-YourAppName-v1");
  client.setOAuthCredentials(oauthParameters, new OAuthRsaSha1Signer(privKey));

  URL feedUrl = new URL("https://docs.google.com/feeds/default/private/full");
  DocumentListFeed resultFeed = client.getFeed(feedUrl, DocumentListFeed.class);
  for (DocumentListEntry entry : resultFeed.getEntries()) {
    System.out.println(entry.getTitle().getPlainText());
  }
  

PHP

require_once 'Zend/Gdata/Docs.php';

if (isset($_SESSION['ACCESS_TOKEN'])) {
  $accessToken = unserialize($_SESSION['ACCESS_TOKEN']);
} else {
  exit;
}


/*  Or, you could set an existing token (say one stored from your database). For HMAC-SHA1:
$accessToken = new Zend_Oauth_Token_Access();
$accessToken->setToken('1/AQfoI-qJDqkvvkf216Gc2g');
$accessToken->setTokenSecret('2c26GLW250tZiQ');
*/

$httpClient = $accessToken->getHttpClient($oauthOptions);
$client = new Zend_Gdata_Docs($httpClient, "yourCompany-YourAppName-v1");

// Retrieve user's list of Google Docs
$feed = $client->getDocumentListFeed();
foreach ($feed->entries as $entry) {
  echo "$entry->title\n";
}

Python

يفترض هذا المقتطف أنّك سبق أن جلبت رمزًا مميّزًا للوصول (باستخدام HMAC-SHA1) وأنّك تسترجع مفتاح الرمز المميّز/الرمز السري لاستخدامه لاحقًا.

إذا كنت تستخدم الفئات الأحدث 2.0 أو إصدارًا أحدث استنادًا إلى GDClient، استخدِم:

client = gdata.docs.client.DocsClient(source='yourCo-yourAppName-v1')
client.auth_token = gdata.gauth.OAuthHmacToken(CONSUMER_KEY, CONSUMER_SECRET, TOKEN,
                                               TOKEN_SECRET, gdata.gauth.ACCESS_TOKEN)
feed = client.GetDocList()
for entry in feed.entry:
  print entry.title.text

إذا كنت تستخدم الفئات القديمة 1.0 المستندة إلى GDataService، استخدِم ما يلي:

client = gdata.docs.service.DocsService(source='yourCompany-YourAppName-v1')
client.SetOAuthInputParameters(SIG_METHOD, CONSUMER_KEY, consumer_secret=CONSUMER_SECRET)

# the token key and secret should be recalled from your database
client.SetOAuthToken(gdata.auth.OAuthToken(key=TOKEN, secret=TOKEN_SECRET))

feed = client.GetDocumentListFeed()
for entry in feed.entry:
  print entry.title.text

NET.

إذا كنت تستخدم HMAC-SHA1:

OAuthParameters parameters = new OAuthParameters() {
  ConsumerKey = CONSUMER_KEY,
  ConsumerSecret = CONSUMER_SECRET,
  Token = ACCESS_TOKEN,
  TokenSecret = TOKEN_SECRET
}

GOAuthRequestFactory requestFactory = new GOAuthRequestFactory("writely", APPLICATION_NAME, parameters);

DocsService service = new DocsService(APPLICATION_NAME);
service.RequestFactory = requestFactory;

DocumentsListQuery query = new DocumentsListQuery();
DocumentsFeed feed = service.Query(query);
foreach (DocumentEntry entry in feed.Entries) {
  Console.WriteLine(entry.Title.Text);
}

يختلف RSA-SHA1 عن المثال السابق في أنّك لست بحاجة إلى ضبط سر الرمز المميز للوصول، كما أنّ طريقة إنشاء عنصر الموقّع تختلف:

RSA-SHA1 is not supported yet.

مراجع ونماذج إضافية لبروتوكول OAuth الثلاثي

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

بروتوكول OAuth الثنائي

يتيح بروتوكول OAuth ذو الخطوتين للتطبيقات الموثوق بها الوصول إلى بيانات المستخدمين على Google بدون تدخلهم المباشر. يمكن لمجموعتَين رئيسيتَين استخدام بروتوكول OAuth الثنائي:

مشرفو نطاق G Suite: يمكن للمشرفين إنشاء نصوص برمجية وتطبيقات مخصّصة تدير بيانات المستخدمين لنطاقهم من خلال Google Data APIs. للتعرّف على كيفية إدارة المفتاح والسر المرتبطين بنطاق G Suite ومنح إذن التحكّم في الوصول على مستوى العالم، يُرجى الاطّلاع على "إدارة مفتاح OAuth وسرّه".

مورّدو البرامج التابعة لجهات خارجية: قد يقدّم المورّدون تطبيقات تستخدم OAuth من خطوتين للدمج مع G Suite. يمكن منح إذن الوصول إلى تطبيقات الجهات الخارجية في صفحة "إدارة عميل واجهة برمجة التطبيقات" أو من خلال التثبيت من سوق G Suite.

لا يلزم توفّر رمز دخول وفقًا لمسار التفويض العادي (المعروف أيضًا باسم بروتوكول OAuth الثلاثي).

توضّح عيّنات مكتبة البرامج التالية كيفية إعداد العميل لاستخدام بروتوكول OAuth ذي الخطوتين باستخدام HMAC-SHA1.

جافا

import com.google.gdata.client.docs.*;
import com.google.gdata.client.authn.oauth.*;

String CONSUMER_KEY = "example.com";
String CONSUMER_SECRET = "abc123doremi";

GoogleOAuthParameters oauthParameters = new GoogleOAuthParameters();
oauthParameters.setOAuthConsumerKey(CONSUMER_KEY);
oauthParameters.setOAuthConsumerSecret(CONSUMER_SECRET);

DocsService client = new DocsService("yourCompany-YourAppName-v1");
client.setOAuthCredentials(oauthParameters, new OAuthHmacSha1Signer());

// Retrieve user's list of Google Docs
String user = "any.user@anydomain.com";
URL feedUrl = new URL("https://docs.google.com/feeds/default/private/full" +
                      "?xoauth_requestor_id=" + user);

DocumentListFeed resultFeed = client.getFeed(feedUrl, DocumentListFeed.class);
for (DocumentListEntry entry : resultFeed.getEntries()) {
  System.out.println(entry.getTitle().getPlainText());
}

PHP

require_once 'Zend/Oauth/Consumer.php';
require_once 'Zend/Gdata/Docs.php';

$CONSUMER_KEY = 'example.com';
$CONSUMER_SECRET = 'abc123doremi';
$USER = 'any.user@anydomain.com';

$oauthOptions = array(
    'requestScheme' => Zend_Oauth::REQUEST_SCHEME_HEADER,
    'version' => '1.0',
    'signatureMethod' => 'HMAC-SHA1',
    'consumerKey' => $CONSUMER_KEY,
    'consumerSecret' => $CONSUMER_SECRET
);

$consumer = new Zend_Oauth_Consumer($oauthOptions);
$token = new Zend_Oauth_Token_Access();
$httpClient = $token->getHttpClient($oauthOptions);

$client = new Zend_Gdata_Docs($httpClient);

// Retrieve user's list of Google Docs
$feed = $client->getDocumentListFeed('https://docs.google.com/feeds/default/private/full?xoauth_requestor_id=' . urlencode($USER));
foreach ($feed->entries as $entry) {
  echo "$entry->title\n";
}

Python

إذا كنت تستخدم الفئات الأحدث 2.0 أو إصدارًا أحدث استنادًا إلى GDClient، استخدِم:

import gdata.gauth
import gdata.docs.client

CONSUMER_KEY = 'example.com'
CONSUMER_SECRET = 'abc123doremi'
requestor_id = 'any.user@anydomain.com'

client = gdata.docs.client.DocsClient(source='yourCompany-YourAppName-v1')
client.auth_token = gdata.gauth.TwoLeggedOAuthHmacToken(
    CONSUMER_KEY, CONSUMER_SECRET, requestor_id)

# Retrieve user's list of Google Docs
feed = client.GetDocList()
for entry in feed.entry:
  print entry.title.text

إذا كنت تستخدم الفئات القديمة 1.0 المستندة إلى GDataService، استخدِم ما يلي:

import gdata.auth
import gdata.docs.service

CONSUMER_KEY = 'example.com'
CONSUMER_SECRET = 'abc123doremi'
SIG_METHOD = gdata.auth.OAuthSignatureMethod.HMAC_SHA1

requestor_id = 'any.user@anydomain.com'

client = gdata.docs.service.DocsService(source='yourCompany-YourAppName-v1')
client.SetOAuthInputParameters(SIG_METHOD, CONSUMER_KEY, consumer_secret=CONSUMER_SECRET,
                               two_legged_oauth=True, requestor_id=requestor_id)

# Retrieve user's list of Google Docs
feed = client.GetDocumentListFeed()
for entry in feed.entry:
  print entry.title.text

# Change to another user on your domain
client.GetOAuthInputParameters().requestor_id = 'another.user@example.com'

NET.

using Google.GData.Client;
using Google.GData.Documents;

// Create an OAuth factory to use
GOAuthRequestFactory requestFactory = new GOAuthRequestFactory("writely", "yourCompany-YourAppName-v1");
requestFactory.ConsumerKey = "example.com";
requestFactory.ConsumerSecret = "abc123doremi";

String user = "any.user@anydomain.com";

DocumentsService client = new DocumentsService("yourCompany-YourAppName-v1");
client.RequestFactory = requestFactory;

// Retrieve user's list of Google Docs
DocumentsListQuery query = new DocumentsListQuery();
query.Uri = new OAuthUri("https://docs.google.com/feeds/default/private/full", user, requestFactory.ConsumerKey);

DocumentsFeed feed = client.Query(query);

foreach (DocumentEntry entry in feed.Entries)
{
  Console.WriteLine(entry.Title.Text);
}

مراجع ونماذج إضافية لبروتوكول OAuth الثنائي

إنشاء مفتاح خاص وشهادة علنية ذاتية التوقيع

يُستخدَم المفتاح الخاص لإنشاء توقيع يجب تضمينه مع كل طلب. تستخدم Google المفتاح العام المضمّن في الشهادة للتحقّق من التوقيع. يجب أن يكون المفتاح العام مفتاح RSA بحجم 1024 بت مشفّرًا في شهادة X.509 بتنسيق PEM. يجب إرسال الشهادة إلى Google عند التسجيل.

تقدّم الأقسام التالية أمثلة على كيفية إنشاء المفاتيح والشهادات باستخدام أداتَين معيّنتَين: الأداة المساعدة OpenSSL والأداة المساعدة keytool في Java.

لا ترتبط هذه الأمثلة بواجهات Google Data APIs تحديدًا، ويمكنك استخدام الأدوات المساعدة نفسها لإنشاء مفاتيح لأي غرض.

تفترض الأمثلة أنّ اسم شركتك هو My_Company، وأنّها تقع في ماونتن فيو، كاليفورنيا، الولايات المتحدة، واسم النطاق هو example.com.

إنشاء المفاتيح باستخدام OpenSSL

لإنشاء زوج من مفاتيح RSA والشهادة المقابلة، يمكنك استخدام الأمر التالي:

# Generate the RSA keys and certificate
openssl req -x509 -nodes -days 365 -newkey rsa:1024 -sha1 -subj \
  '/C=US/ST=CA/L=Mountain View/CN=www.example.com' -keyout \
  myrsakey.pem -out /tmp/myrsacert.pem

تحذير: يؤدي تضمين المَعلمة -nodes إلى إنشاء مفتاح خاص بدون كلمة مرور لحمايته. ومع ذلك، ننصحك بحذف هذه المَعلمة لتعزيز الأمان.

تحدّد المَعلمة -sha1 أنّه سيتم استخدام المفتاح لإنشاء توقيعات SHA1.

تحدّد المَعلمة -subj هوية التطبيق الذي تمثّله الشهادة.

تحدّد المَعلمة -keyout الملف الذي سيحتوي على المفاتيح. يحتوي هذا الملف على معلومات حساسة ويجب حمايته وعدم مشاركته مع أي شخص.

تحدّد المَعلمة -out الملف الذي سيحتوي على الشهادة بتنسيق PEM (والذي يمكن إرساله إلى Google أثناء التسجيل).

إنشاء مفاتيح لبرنامج .NET

لا يفهم إطار عمل .NET المفاتيح أو الشهادات المخزّنة بتنسيق PEM. لذلك، يجب اتّخاذ خطوة إضافية بعد إنشاء ملف ‎ .pem:

openssl pkcs12 -export -in test_cert.pem -inkey myrsacert.pem -out myrsacert.pfx -name "Testing Certificate"

تنشئ هذه الخطوة ملف PFX من مفتاحك الخاص وشهادتك. يمكن استيراد هذا الملف إلى مكتبة برامج عميل ‎ .NET لتوقيع الطلبات التي يتم إرسالها إلى Google Data APIs رقميًا.

إنشاء مفاتيح لبرنامج Java

يقبل برنامج Java الخادم المفاتيح الخاصة بتنسيق PKCS#8. بعد إنشاء مفتاح/شهادة باستخدام الإرشادات أعلاه، أنشئ ملف ‎ .pk8 من ملف ‎ .pem الذي أنشأته:

openssl pkcs8 -in myrsakey.pem -topk8 -nocrypt -out myrsakey.pk8

بدلاً من ذلك، يمكنك استخدام مخزن مفاتيح Java وأداة keytool لإنشاء زوج من مفاتيح RSA والشهادة المقابلة. استخدِم الأمر التالي:

# Generate the RSA keys and certificate
keytool -genkey -v -alias Example -keystore ./Example.jks\
  -keyalg RSA -sigalg SHA1withRSA\
  -dname "CN=www.example.com, OU=Engineering, O=My_Company, L=Mountain  View, ST=CA, C=US"\
  -storepass changeme -keypass changeme

تحذير: "changeme" ليست كلمة مرور جيدة، هذا مجرد مثال.

تحدّد المَعلمة -dname هوية التطبيق الذي تمثّله الشهادة. تحدّد المَعلمة -storepass كلمة المرور المستخدَمة لحماية ملف تخزين المفاتيح. تحدّد المَعلمة -keypass كلمة المرور المستخدَمة لحماية المفتاح الخاص.

لكتابة الشهادة في ملف يمكن استخدامه في أداة ManageDomains، استخدِم الأمر التالي:

# Output the public certificate to a file
keytool -export -rfc -keystore ./Example.jks -storepass changeme \
  -alias Example -file mycert.pem

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