تفويض واجهة برمجة التطبيقات

استخدام OAuth 2.0 لمصادقة تطبيقك عند الوصول إلى واجهات برمجة تطبيقات الفنادق

إعداد OAuth 2.0

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

تكون رموز الدخول صالحة لمدة ساعة (3600 ثانية).

إذا نفذت ClientLogin سابقًا، فإن طريقة OAuth 2.0 تكون مشابهة، مع الاختلافات التالية:

• يستخدم تطبيقك حساب خدمة Google للوصول إلى واجهة برمجة التطبيقات.
• يمكنك ضبط رمز الدخول OAuth 2.0 في عنوان HTTP يتضمّن العنصر Authorization عندما لواجهات برمجة التطبيقات.

لإعداد حسابك على استخدام OAuth 2.0 مع Travel Partner API، يُرجى تنفيذ الخطوات التالية:

1. إنشاء مشروع جديد على Google Developers Console (DevConsole)

2. تفعيل إمكانية الوصول إلى Travel Partner API للمشروع الجديد

3. إنشاء حساب خدمة وبيانات الاعتماد الخاصة به

4. منح حساب الخدمة إذن الوصول إلى بيانات فنادقك

كل خطوة من هذه الخطوات موضّحة في الأقسام التالية.

الخطوة 1: إنشاء مشروع DevConsole جديد

منصة Google Developers Console ("DevConsole") هي إحدى تجارب المطوّرين من Google لإدارة وعرض بيانات حركة المرور، والمصادقة، ومعلومات الفوترة لـ Google APIs التي تستخدمها مشاريعك.

في وحدة تحكم مطوري البرامج، المشروع عبارة عن مجموعة من الإعدادات وبيانات الاعتماد وبيانات وصفية عن التطبيق أو التطبيقات التي تعمل عليها التي تستخدم واجهات Google Developer API وموارد Google Cloud.

وحدة تحكم مطوري البرامج هي المكان الذي تدير فيه هذه الجوانب من مشروعك، مثل إنشاء بيانات اعتماد واجهة برمجة التطبيقات وتفعيل واجهات برمجة التطبيقات وإدارة الفريق والفوترة المعلومات المرتبطة بمشروعك.

لإنشاء مشروع DevConsole جديد:

1. سجِّل الدخول إلى حسابك على Gmail أو Google.

2. افتح Google Developer Console. إذا كان هذا هو مشروعك الأول، ستعرض طريقة العرض الرئيسية زر إنشاء مشروع البسيط:

   

3. انقر على الزر إنشاء مشروع. تعرض DevConsole مربع الحوار مشروع جديد:

   

   أدخِل اسمًا مناسبًا لمشروعك الجديد في اسم المشروع. حقل إدخال أسفل الحقل، تنشئ وحدة تحكم مطوّري البرامج رقم تعريف مشروع لك، مما يضمن أن يكون المعرف فريدًا عبر جميع المشروعات. على سبيل المثال، إذا ثم تدخل "مشروعي الجديد"، تعين DevConsole معرّفًا مثل my-new-project-266022

4. انقر على الزرّ إنشاء لإنشاء مشروعك الجديد.

5. استخدم قائمة التنقل لتحديد واجهات برمجة التطبيقات الخدمات > لوحة البيانات.

   

   توضح الصورة أدناه قائمة التنقل أعلى يسار DevConsole. ويؤدي ذلك إلى عرض طريقة عرض لوحة البيانات لمشروعك:

   

لمزيد من المعلومات، يُرجى الاطّلاع على مقالة إدارة المشاريع في صفحة "المطوّرون". Console.

عند إنشاء مشروع جديد، لن تتوفّر له أي واجهات برمجة تطبيقات مرتبطة به حتى الآن. في جلسة المعمل، الخطوة التالية، عليك تفعيل Travel Partner API لمشروعك الجديد.

الخطوة 2: تفعيل Travel Partner API للمشروع الجديد

لاستخدام واجهات برمجة التطبيقات للفنادق، يجب تفعيل Travel Partner API في مشروع DevConsole الجديد.

لتفعيل واجهات برمجة التطبيقات للفنادق في مشروعك الجديد:

1. انتقل إلى طريقة عرض لوحة البيانات لمشروعك كما هو موضح أعلاه.

2. انقر على تفعيل واجهات برمجة التطبيقات والخدمات. يؤدي ذلك إلى عرض رسالة ترحيب واجهة برمجة التطبيقات .

3. في حقل البحث، ابدأ كتابة Travel Partner API. تعرض وحدة التحكم في واجهة Google API قائمة بواجهات برمجة التطبيقات التي تتطابق مع ما تكتبه.

4. انقر على Travel Partner API في جدول واجهات برمجة التطبيقات المطابقة. DevConsole وصفًا عن واجهة برمجة التطبيقات.

5. انقر على الزر تفعيل واجهة برمجة التطبيقات لتفعيل واجهة برمجة التطبيقات هذه لمشروعك.

لمزيد من المعلومات، راجِع مقالة التفعيل والإيقاف. API.

تم تفعيل واجهات برمجة تطبيقات الفنادق للمشروع الجديد لحسابك على Google.

الخطوة التالية هي إنشاء حساب خدمة وإنشاء مفاتيح له.

الخطوة 3: إنشاء حساب خدمة وإنشاء بيانات الاعتماد الخاصة به

تُستخدم حسابات الخدمة من خلال التفاعلات من خادم إلى خادم مثل تلك بين تطبيق ويب وبيانات فندقك.

لإنشاء حساب خدمة وإعداده:

1. في الشاشة الرئيسية لوحدة تحكُّم Google API، انقر على بيانات الاعتماد في التنقل الأيمن. يعرض DevConsole طريقة عرض بيانات الاعتماد.

   تعرض طريقة عرض بيانات الاعتماد معرِّفات العملاء وبيانات الاعتماد الخاصة مشروعك. سيستخدم تطبيقك معرِّف العميل عند طلب رمز الدخول إلى OAuth 2.0. لن تحتوي المشاريع الجديدة على عملاء أو بيانات اعتماد حتى الآن.

2. انقر على رابط بيانات الاعتماد في واجهات برمجة التطبيقات والخدمات.

3. انقر على الزر إنشاء بيانات اعتماد، واختَر مفتاح حساب الخدمة. من القائمة المنسدلة. تظهر طريقة العرض إنشاء مفتاح حساب الخدمة.

4. من القائمة المنسدلة حساب الخدمة، اختَر حساب خدمة جديد.

5. أدخِل اسم حساب الخدمة ورقم تعريف حساب الخدمة.

   يمكن إدخال أي اسم تريده، ولكن يجب أن يكون رقم تعريف الحساب فريدًا. عبر جميع المشروعات. ستنشئ شركة DevConsole رقم تعريف حساب فريدًا لك، استنادًا إلى الاسم الذي أدخلته.

6. اختَر P12 لنوع المفتاح كما هو موضّح أدناه. يجب توفير الأولوية P12.

   

7. انقر على الزر إنشاء. ينشئ DevConsole مفتاحَي تشفير خاص وعام لمشروعك. يتم حفظ المفتاح الخاص في الموقع الافتراضي الذي يخزن متصفحك التنزيلات. يجب تنزيل .p12 (ثنائي)، بدلاً من تنسيق الملف .json.

   استخدام المفتاح الخاص في النصوص البرمجية أو التطبيقات الأخرى التي يمكنها الوصول إلى Travel Partner API.

   يعرض DevConsole الإشعار التالي عند الانتهاء من إنشاء المفاتيح:

   

8. انقر على الزر حسنًا، أعي ذلك. تعيدك DevConsole إلى عرض بيانات الاعتماد. لتأكيد تفاصيل حساب الخدمة راجِع حسابات الخدمة المرتبطة بمشروعك، ثم انقر على إدارة. حسابات الخدمة في طريقة العرض هذه.

   يحتوي حساب الخدمة الآن على بيانات الاعتماد التالية المرتبطة به:

   • معرّف العميل: معرّف فريد يستخدمه تطبيقك عندما طلب رمز الدخول OAuth 2.0.
   • عنوان البريد الإلكتروني: عنوان بريد إلكتروني تم إنشاؤه لحساب الخدمة، في النموذج "account_name@account_name.google.com.iam.gserviceaccount.com".
   • الملفات المرجعية للشهادة: رقم تعريف المفتاح الخاص الذي تم تنزيله.

للحصول على مزيد من المعلومات، يمكنك مراجعة استخدام OAuth 2.0 للخادم من أجل تطبيقات الخادم

الخطوة 4: منح حساب الخدمة إذن الوصول إلى بياناتك في Hotel Center

الخطوة الأخيرة هي منح حساب الخدمة الجديد إمكانية الوصول إلى مركز إدارة معلومات الفنادق: ويتم تحديد حساب الخدمة من خلال عنوان البريد الإلكتروني الذي تم إنشاؤه قمت بإنشائه في الخطوة السابقة. أنت تمنح حق الوصول إلى هذا الحساب باستخدام إعدادات المشاركة في Hotel Center.

لمنح حساب خدمة إذن الوصول إلى بياناتك في "مركز إدارة معلومات الفنادق":

إذا لم يكن لديك إذن الوصول المناسب لإضافة مستخدمين إلى الحساب، يُرجى التواصل مع فريق "الفنادق على Google" باستخدام نموذج التواصل معنا وطلب إعداد الملكية لـ لحسابك. يمكنك طلب إرسال رسالة إلكترونية واحدة أو أكثر إلى أحد المالكين. لمزيد من المعلومات عن الوصول إلى Hotel Center، يُرجى الرجوع إلى مقالة ربط Hotel Center و "إعلانات Google":

1. في نافذة متصفِّح جديدة، افتح Hotel Center.

2. على بانر Hotel Center من Google، انقر على رمز إضافة مستخدم لفتح مربع حوار المشاركة.

   

3. في الحقل إضافة المزيد من الأشخاص، أدخِل عنوان البريد الإلكتروني للخدمة. حسابك الذي تريد إضافته إلى مركز إدارة معلومات الفنادق.

4. أبقِ خيار إشعار الأشخاص محدّدًا.

5. من القائمة المنسدلة، اختَر إدارة.

6. انقر على الزر دعوة.

7. بعد إضافة مستخدِمين إلى حسابك على Hotel Center، من المفترض أن يكون حساب الخدمة كما يلي: يمكن الوصول إليها من خلال واجهة برمجة التطبيقات في غضون 24 ساعة تقريبًا.

بعد أن ترسل Google إشعارًا إليك بأنّه تم تفعيل إمكانية الوصول إلى واجهة برمجة التطبيقات لخدمتك يمكنك بدء الوصول إلى واجهة برمجة التطبيقات باستخدام OAuth.

استخدام OAuth 2.0

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

تعد رموز الدخول (المعروفة أيضًا باسم رموز الحامل) جزءًا من OAuth 2.0 القياسية. بناء الجملة لتحديد رمز الدخول في عنوان HTTP هو:

Authorization: Bearer *oauth2_access_token*

يوضح المثال التالي نماذج لعناوين HTTP لطلب يصل إلى واجهة برمجة التطبيقات لإعداد التقارير:

GET /travelpartner/v2.0/42000042/reports/top_opportunity_7_day HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer nd42.fdLSKkljD98344444444444lSDF42fdLSKkljD98344444444444lSDF42
Cache-Control: no-cache

ولإنشاء رمز دخول، أنشئ تطبيقًا بأي لغة تختارها. ينشئ المثال التالي الرمز المميز في Python. يمكنك بعد ذلك استخدام رمز مميز في طلباتك Authorization من العناوين عند الوصول إلى Travel Partner API.

#!/usr/bin/python2.7
#
""" Sample code to get an auth header that you can use in your HTTP requests
    1. Please see https://developers.google.com/api-client-library/python/start/installation
       to download and install the google-api-python-client package.
    2. Edit lines below marked _SERVICE_ACCOUNT, _KEY_FILE,  _PARTNER_NAME,
       and _API_VERSION.
    3. Run the program using: "python sample.py". The app returns the value that
       you use for the Authorization header's Bearer token in your request.
    4. Copy the token and use it in requests to the Travel Partner API.
       For example (2.0):
       https://www.googleapis.com/travelpartner/2.0/42000042/reports/budget
       For example (1.x):
       https://www.googleapis.com/travelpartner/1.2/reports?report_type=BUDGET
"""
import httplib2
import json
import os
import sys
import urllib

HAS_CRYPTO = False

from apiclient import discovery
from oauth2client.client import flow_from_clientsecrets
try:
  # Some systems may not have OpenSSL installed so can't use SignedJwtAssertionCredentials.
  from oauth2client.client import SignedJwtAssertionCredentials
  HAS_CRYPTO = True
except ImportError:
  print "Unable to import SignedJwtAssertionCredentials"

from oauth2client import tools
from oauth2client.file import Storage

# Authorization scope for our requests (do not change)
_DEFAULT_APISCOPE = 'https://www.googleapis.com/auth/travelpartner'

# Use the service account you set up in the Google Developers Platform.
# It will be of the form "gsaccount_name@project_name.google.com.iam.gserviceaccount.com".
_SERVICE_ACCOUNT = ('myserviceaccount@my-hotel-project.google.com.iam.gserviceaccount.com')

# Set this to the full path to your service account's private binary .p12 key file
# that you downloaded from the Google Developer's Console and stored in a secure place.
# DO NOT use the json version of the certificate.
_KEY_FILE = '../mylocaldir/api-keys/8482bb2bdb08.p12'

# Set this to the case-sensitive "Partner Key", NOT the account
# name in the Hotel Ads Center or the numeric partner ID.
# Check with your TAM if you do not know your "Partner Key" name.
_PARTNER_NAME = 'testpartner2'

class HotelAdsAPIConnection(object):
  def __init__(self, service_account=_SERVICE_ACCOUNT, key=_KEY_FILE, partner=_PARTNER_NAME):
    self.key_file = key
    self.account = service_account
    self.partner = partner

  def InitializeCredentials(self, scope):
    '''Get credentials for use in API requests.
    Generates service account credentials if the key file is present,
    and regular user credentials if the file is not found.
    '''
    if os.path.exists(self.key_file):
      if not HAS_CRYPTO:
        raise Exception("Unable to use cryptographic functions "
                        + "Try installing OpenSSL")
      with open (self.key_file, 'rb') as file:
        key = file.read();
      creds = SignedJwtAssertionCredentials(self.account, key, scope)
      self.credentials = creds

  def authorize(self):
    '''Construct a HTTP client that uses the supplied credentials.'''
    return credentials.authorize(httplib2.Http())

  def print_creds(self):
    '''Prints the Authorization header to use in HTTP requests.'''
    cred_dict = json.loads(self.credentials.to_json())

    if 'access_token' in cred_dict:
      print 'Authorization: Bearer %s' % (cred_dict['access_token'],)
    else:
      print 'creds: %s' % (cred_dict,)

  def GetConnection(self):
    http = httplib2.Http()
    self.credentials.refresh(http)
    http = self.credentials.authorize(http)
    self.print_creds()
    return http

def main(args):
  # Create an instance of the HotelAdsAPIConnection inner class
  api = HotelAdsAPIConnection()

  # Generate credentials
  api.InitializeCredentials(_DEFAULT_APISCOPE)

  # Output the Authorization header to use in HTTP requests
  api.GetConnection()

if __name__ == "__main__":
    main(sys.argv)</pre>

عند تطوير تطبيقك، احرص على اتّباع أفضل الممارسات. لاستخدام مفاتيح واجهة برمجة التطبيقات بأمان

ينتج عن نموذج نص Python البرمجي حامل العنوان Authorization كرمز مميّز، كما يبيِّن المثال التالي:

$ python sample.py
Authorization: Bearer ya29.42424242sample_420icu8122KSvoh4T42cRoG3rW1lc0Q
$

استخدِم قيمة الرمز المميّز في طلباتك. من الجيد لمدة ساعة بعد وإنشائها.

تحديد المشاكل وحلّها

هل تواجه مشاكل؟ قد يؤدي إجراء تحقق سريع من العناصر التالية إلى حل المشكلة.

1. هل أنشأت مشروعًا في Google Developer Console؟
2. هل عثرت على ميزة "Travel Partner API" وفعّلتها؟
3. هل نزّلت ملف .p12: مفتاح خاص بعد النقر هل تريد إنشاء معرّف عميل واختيار حساب الخدمة؟
4. هل تلقّيت عنوان بريد إلكتروني تابعًا لعميل حساب الخدمة لنموذج: nnnnnnn@app_name.google.com.iam.gserviceaccount.com؟
5. هل شاركت حسابك على Hotel Ads Center مع حساب الخدمة بالنقر على زر مشاركة هذا الحساب؟
6. هل أرسلت عنوان البريد الإلكتروني لحساب الخدمة ورقم تعريف الشريك إلى أو مدير حسابك الفني (TAM)؟
7. هل تجتاز مكالمات Travel Partner API رمزًا مميّزًا تم الحصول عليه مؤخرًا في هل تريد الحصول على عنوان Authorization؟
8. هل تم إنشاء رمز الحامل المميز لعنوان Authorization منذ أكثر من ساعة؟

يسرد الجدول التالي بعض الأخطاء الشائعة والحلول الممكنة: