استخدِم OAuth 2.0 للسماح بتطبيقك عند الوصول إلى واجهات برمجة تطبيقات الفنادق.
إعداد OAuth 2.0
يتطلب OAuth 2.0 أن تعرِّف نفسك باستخدام حساب خدمة مرتبطًا بحسابك على Google. يرسل حساب الخدمة مفتاحك الخاص مقابل رمز الدخول عبر OAuth 2.0. ويمكنك بعد ذلك استخدام هذا الرمز المميّز في استدعاءات واجهات برمجة تطبيقات الفنادق للحصول على بيانات للقراءة فقط، مثل بيانات تقارير الأسعار والفنادق وبيانات التشخيص حول خلاصة أسعار الفندق.
تصلح رموز الدخول لمدة ساعة (3,600 ثانية).
إذا سبق لك تنفيذ ClientLogin، سيكون أسلوب OAuth 2.0 مشابهًا، مع الاختلافات التالية:
- يستخدم تطبيقك حساب خدمة Google للوصول إلى واجهة برمجة التطبيقات.
- أنّك تدخِل رمز دخول OAuth 2.0 في عنوان HTTP يتضمّن
Authorizationعند استدعاء واجهات برمجة التطبيقات.
لإعداد حسابك على استخدام OAuth 2.0 مع Travel Partner API، اتّبِع الخطوات التالية:
يتم وصف كل خطوة من هذه الخطوات في الأقسام التالية.
الخطوة 1: إنشاء مشروع DevConsole جديد
Google Developers Console (المعروفة اختصارًا باسم "DevConsole") هي تجربة مطوّري البرامج من Google لإدارة وعرض بيانات الزيارات والمصادقة ومعلومات الفوترة لواجهات Google APIs التي تستخدمها مشاريعك.
في DevConsole، المشروع عبارة عن مجموعة من الإعدادات وبيانات الاعتماد والبيانات الوصفية حول التطبيق أو التطبيقات التي تعمل عليها والتي تستخدم واجهات برمجة التطبيقات Google Developer API وموارد Google Cloud.
وDevConsole هي المكان الذي تدير فيه هذه الجوانب من مشروعك، مثل إنشاء بيانات اعتماد واجهة برمجة التطبيقات، وتفعيل واجهات برمجة التطبيقات، وإدارة معلومات الفريق والفوترة المرتبطة بمشروعك.
لإنشاء مشروع جديد على DevConsole:
سجِّل الدخول إلى حسابك على Gmail أو Google.
افتح Google Developer Console. إذا كان هذا هو مشروعك الأول، ستعرض طريقة العرض الرئيسية زر إنشاء مشروع بسيطًا:
انقر على الزر إنشاء مشروع. تعرض DevConsole مربع الحوار مشروع جديد:
أدخِل اسمًا يسهل الوصول إليه لمشروعك الجديد في حقل إدخال اسم المشروع. أسفل الحقل، ينشئ 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 في جدول واجهات برمجة التطبيقات المطابقة. تعرض DevConsole وصفًا حول واجهة برمجة التطبيقات.
انقر على الزر Enable API (تفعيل واجهة برمجة التطبيقات) لتفعيل واجهة برمجة التطبيقات هذه لمشروعك.
لمزيد من المعلومات، يُرجى الرجوع إلى تفعيل واجهات برمجة التطبيقات وإيقافها.
تم تفعيل واجهات برمجة تطبيقات الفنادق الآن للمشروع الجديد في حسابك على 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: منح حساب الخدمة إذن الوصول إلى بياناتك في "مركز إدارة معلومات الفنادق"
تتمثّل الخطوة الأخيرة في منح حساب الخدمة الجديد إذن الوصول إلى مركز إدارة معلومات الفنادق. يتم تحديد حساب الخدمة من خلال عنوان البريد الإلكتروني الذي أنشأته في الخطوة السابقة. يمكنك الوصول إلى هذا الحساب باستخدام إعدادات المشاركة في مركز إدارة معلومات الفنادق.
لمنح حساب خدمة إذن الوصول إلى بيانات "مركز إدارة معلومات الفنادق":
إذا لم يكن لديك الإذن بالوصول المناسب لإضافة مستخدمين إلى الحساب، يُرجى التواصل مع فريق "الفنادق على Google" باستخدام نموذج التواصل معنا وطلب إعداد الملكية لحسابك. يمكنك طلب إرسال رسالة إلكترونية واحدة أو أكثر إلى أحد المالكين. لمزيد من المعلومات عن الوصول إلى "مركز إدارة معلومات الفنادق"، يُرجى الرجوع إلى ربط حساب Hotel Center وحساب "إعلانات Google".
في نافذة متصفّح جديدة، افتح مركز إدارة معلومات الفنادق.
في بانر "مركز إدارة معلومات الفنادق" من Google، انقر على رمز إضافة مستخدم لفتح مربّع حوار المشاركة.
في حقل إضافة المزيد من الأشخاص، أدخِل عنوان البريد الإلكتروني لحساب الخدمة الذي تريد إضافته إلى مركز إدارة معلومات الفنادق.
أبقِ خيار إشعار الأشخاص محدَّدًا.
من القائمة المنسدلة، اختَر إدارة.
انقر على الزر دعوة.
بعد إضافة مستخدمين إلى مركز إدارة معلومات الفنادق، من المُفترَض أن يتمكّن حساب الخدمة من الوصول إلى واجهة برمجة التطبيقات خلال 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
لإنشاء رمز دخول، أنشئ تطبيقًا بأي لغة تختارها.
ينشئ المثال التالي الرمز المميز في بايثون. يمكنك بعد ذلك استخدام هذا الرمز المميّز في عناوين 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؟
- هل عثرت على Travel Partner API وفعّلتها؟
- هل نزّلت ملف
.p12- مفتاح خاص بعد النقر على إنشاء معرِّف عميل واختيار حساب الخدمة؟ - هل حصلت على عنوان بريد إلكتروني لمعرِّف العميل لحساب الخدمة لنموذج:
nnnnnnn@app_name.google.com.iam.gserviceaccount.com؟ - هل شاركت حسابك على مركز إعلانات الفنادق مع حساب الخدمة بالنقر على زر مشاركة هذا الحساب؟
- هل أرسلت عنوان البريد الإلكتروني لحساب الخدمة ورقم تعريف الشريك إلى المدير الفني لحسابك (TAM)؟
- هل تمرر مكالمات Travel Partner API رمزًا مميزًا تم الحصول عليه مؤخرًا في عنوان
Authorization؟ - هل تم إنشاء رمز الحامل المميز للعنوان
Authorizationمنذ أكثر من ساعة واحدة؟
يسرد الجدول التالي بعض الأخطاء الشائعة والحلول المحتملة:
| خطأ | الوصف |
|---|---|
| Invalid credentials | قد يعني هذا عدة أشياء. إذا ظهر لك هذا الخطأ، تحقَّق مما يلي:
|
| Not found | من المرجح أن تكون نقطة النهاية مكتوبة بشكلٍ غير صحيح. تأكَّد من إرسال طلب
GET، ومن أنّ عنوان URL الخاص بالطلب صالح (يتوافق مع بنية واجهة برمجة التطبيقات التي تحاول الوصول إليها). |
| Invalid string value | يحتوي جزء واحد أو أكثر من نقاط النهاية على بنية غير صالحة. على سبيل المثال، قد تكون قد أخطأت في كتابة جزء من المسار. تأكَّد من استخدام الشرطات السفلية والكتابة بالأحرف الكبيرة والصياغة الصحيحة في المسار بالكامل. |
| Unsupported output format | غالبًا ما يحدث هذا الخطأ عند استخدام Reports API. يجب
تحديد "alt=csv" في عنوان URL الخاص بطلب
GET. لا تتيح واجهة برمجة التطبيقات Reports API استخدام JSON. |
| AccessTokenRefreshError/Invalid grant | عند تشغيل نموذج تطبيق Python، قد يعود سبب هذا الخطأ إلى ما يلي:
|
| HotelAdsAPIConnection object has no attribute credentials | عند تشغيل نموذج تطبيق Python، يكون المسار إلى ملف .p12 غير صحيح. |
| Invalid scope | عند تشغيل نموذج تطبيق Python، يجب أن يكون نطاق واجهة برمجة التطبيقات هو https://www.googleapis.com/auth/travelpartner. |
| Forbidden | رقم تعريف الحساب الذي تستخدمه ليس لديك الإذن بالوصول إليه. إذا كنت صاحب حساب فرعي، قد لا تتمكّن من الوصول إلى رقم تعريف الحساب الرئيسي أو الجذر. |