تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

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

استخدام 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، يُرجى تنفيذ الخطوات التالية:

إنشاء مشروع جديد على Google Developers Console (DevConsole)
تفعيل إمكانية الوصول إلى Travel Partner API للمشروع الجديد
إنشاء حساب خدمة وبيانات الاعتماد الخاصة به
منح حساب الخدمة إذن الوصول إلى بيانات فنادقك

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

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

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

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

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

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

سجِّل الدخول إلى حسابك على Gmail أو Google.
افتح Google Developer Console. إذا كان هذا هو مشروعك الأول، تعرض طريقة العرض الرئيسية زر إنشاء مشروع بسيطًا:
انقر على الزر إنشاء مشروع. تعرض DevConsole مربع الحوار مشروع جديد:

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

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

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

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

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

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

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

انتقل إلى طريقة عرض لوحة البيانات لمشروعك كما هو موضح أعلاه.
انقر على تفعيل واجهات برمجة التطبيقات والخدمات. وسيؤدي ذلك إلى عرض صفحة الترحيب بمكتبة واجهة برمجة التطبيقات
في حقل البحث، ابدأ كتابة Travel Partner API. تعرض وحدة التحكم في واجهة Google API قائمة بواجهات برمجة التطبيقات التي تتطابق مع ما تكتبه.

نقطة رئيسية: يظهر Travel Partner API للشركاء الموثوق بهم فقط. في حال عدم العثور على واجهة برمجة التطبيقات عند البحث، يُرجى التواصل مع المدير التقني للحسابات (TAM).
انقر على Travel Partner API في جدول واجهات برمجة التطبيقات المطابقة. تعرض DevConsole وصفًا حول واجهة برمجة التطبيقات.
انقر على الزر تفعيل واجهة برمجة التطبيقات لتفعيل واجهة برمجة التطبيقات هذه لمشروعك.

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

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

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

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

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

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

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

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

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

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

تنبيه: يحتوي ملف المفتاح الخاص على بيانات حسّاسة يجب أن يصل إليها العملاء للحصول على رمز مميّز، لذا يجب تخزينه في مكان آمن.

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

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

لمزيد من المعلومات، راجِع استخدام OAuth 2.0 من خادم إلى خادم.

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

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

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

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

في نافذة متصفِّح جديدة، افتح Hotel Center.
على بانر Hotel Center من Google، انقر على رمز إضافة مستخدم لفتح مربّع حوار المشاركة.
في الحقل إضافة المزيد من الأشخاص، أدخِل عنوان البريد الإلكتروني لحساب الخدمة الذي تريد إضافته إلى Hotel Center.
أبقِ خيار إشعار الأشخاص محدّدًا.
من القائمة المنسدلة، اختَر إدارة.
انقر على الزر دعوة.
بعد إضافة مستخدمين إلى 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
$

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

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

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

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

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

خطأ	الوصف
Invalid credentials	قد يعني هذا عددًا من الأشياء. إذا ظهر لك هذا الخطأ، تحقَّق مما يلي: لقد حدّدت عنوان `Authorization` مع رمز حامل مميّز صالح. عمر الرمز المميز للحامل أقل من ساعة. الرمز المميز صالح لمدة ساعة واحدة فقط. لقد حدّدت اسم الشريك الصحيح (باستخدام مَعلمة سلسلة طلب البحث `partner` ). القيمة هي رقم تعريف الشريك الفريد الخاص بك، وليست اسم الشريك الذي يظهر في Hotel Ads Center. إذا كنت لا تعرف رقم تعريف الشريك، يُرجى التواصل مع المدير التقني للحسابات (TAM).
Not found	من المرجح أن تكون نقطة النهاية غير صحيحة. تأكّد من إرسال طلب `GET`، ومن أنّ عنوان URL للطلب صالح (متوافق مع بنية واجهة برمجة التطبيقات التي تحاول الوصول إليها).
Invalid string value	يحتوي جزء واحد أو أكثر من نقطة النهاية على بنية غير صالحة. على سبيل المثال، قد تكون ارتكبت خطأً إملائيًا في جزء من المسار. تأكَّد من أنّك استخدمت الشُرط السفلية والأحرف اللاتينية الكبيرة والصياغة الصحيحة في المسار بالكامل.
Unsupported output format	غالبًا ما يحدث هذا الخطأ عند استخدام واجهة برمجة التطبيقات لإعداد التقارير. عليك تحديد `"alt=csv"` في عنوان URL لطلب `GET`. لا تتيح واجهة برمجة التطبيقات لإعداد التقارير استخدام JSON.
AccessTokenRefreshError/Invalid grant	عند تشغيل نموذج تطبيق Python، قد يعود سبب هذا الخطأ إلى أحد الأسباب التالية: عنوان البريد الإلكتروني لحساب الخدمة غير صحيح. راجِع حساب البريد الإلكتروني في Google Developer Console وتأكَّد من أنّه مصرَّح له بالوصول إلى واجهة برمجة التطبيقات. لا يمكن لعنوان البريد الإلكتروني الوصول إلى واجهة برمجة التطبيقات. تحقَّق من أنّ عنوان البريد الإلكتروني مسموح له بالوصول إلى بيانات فنادقك (تتم مشاركتها من خلال Hotel Center). ملف المفتاح ليس الملف الصحيح لحساب الخدمة. استخدِم DevConsole لتنزيل شهادة `.p12` جديدة وتأكّد من أن تطبيق Python يشير إلى الشهادة الصحيحة.
HotelAdsAPIConnection object has no attribute credentials	عند تشغيل نموذج تطبيق Python، يكون المسار إلى ملف `.p12` غير صحيح.
Invalid scope	عند تشغيل نموذج تطبيق Python، يجب أن يكون نطاق واجهة برمجة التطبيقات `https://www.googleapis.com/auth/travelpartner`.
Forbidden	رقم تعريف الحساب الذي تستخدمه هو رقم تعريف غير مصرّح لك بالوصول إليه. إذا كنت تملك حسابًا فرعيًا، قد لا تتمكّن من الوصول إلى رقم تعريف الحساب الرئيسي أو الجذر.