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

تقدّم هذه المستندات تعليمات مفصّلة لإعداد OAuth2.0 في تطبيقك عند الوصول إلى واجهات برمجة تطبيقات الفنادق، مثل Travel Partner API وPrice Feeds API. يُرجى الاطّلاع على مقالة استخدام بروتوكول OAuth 2.0 للوصول إلى Google APIs لتفويض تطبيقك.

إعداد OAuth 2.0

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

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

إذا سبق لك استخدام ClientLogin، فإنّ نهج OAuth 2.0 مشابه، مع الاختلافات التالية:

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

لإعداد حسابك لاستخدام بروتوكول OAuth 2.0 مع أي Hotels API، عليك اتّباع الخطوات التالية:

  1. إنشاء مشروع جديد في Google Cloud Console

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

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

يرد وصف كل خطوة من هذه الخطوات في الأقسام التالية.

الخطوة 1: إنشاء مشروع جديد في Google Cloud Console

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

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

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

لإنشاء مشروع جديد على Google Cloud Console، اتّبِع الخطوات التالية:

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

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

    fig1

  3. انقر على الزر إنشاء مشروع. تعرِض Google Cloud Console مربّع حوار مشروع جديد:

    fig2

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

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

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

    fig3

    تعرض الصورة التالية قائمة التنقّل في أعلى يمين وحدة تحكّم Google Cloud. يؤدي ذلك إلى عرض عرض لوحة البيانات لمشروعك:

    fig4

لمزيد من المعلومات، يُرجى الاطّلاع على مقالة إنشاء المشاريع وإدارتها.

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

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

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

  1. في العرض الرئيسي لوحدة تحكّم واجهة Google API، انقر على بيانات الاعتماد في ملف التنقّل على يمين الصفحة. تعرِض Google Cloud Console عرض المعلومات المُعتمَدة.

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

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

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

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

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

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

  6. اختَر JSON لنوع المفتاح. يجب استخدام تنسيق JSON.

  7. انقر على الزر إنشاء. تُنشئ وحدة تحكّم Google Cloud مفتاحَي تشفير خاص أو عام لمشروعك. يتم حفظ المفتاح الخاص في الموقع التلقائي الذي يخزّن فيه المتصفّح الملفات التي يتم تنزيلها. يجب تنزيل ملف بتنسيق .JSON.

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

    تعرِض Google Cloud Console رسالة "تم إنشاء حساب الخدمة" عند انتهاء إنشاء المفاتيح.

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

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

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

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

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

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

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

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

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

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

    fig8

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

  4. اترك الخيار إشعار المستخدمين محدّدًا.

  5. انقر على إدارة من الفلتر.

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

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

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

كيفية استخدام بروتوكول OAuth 2.0

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

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

المستويات

في ما يلي SCOPES لواجهة برمجة التطبيقات Hotels API:

Travel Partner API: ‏ "https://www.googleapis.com/auth/travelpartner"

Price Feeds API: ‏ "https://www.googleapis.com/auth/travel-partner-price-upload"

يجب تحديد حساب الخدمة عند إنشاء بيانات الاعتماد. راجِع مقالة إنشاء حساب خدمة وإنشاء بيانات اعتماده.

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

مثال

from google.oauth2 import service_account
from google.auth.transport.requests import Request

# You can use a single or multiple scopes
SCOPES =
['https://www.googleapis.com/auth/travel-partner-price-upload','https://www.googleapis.com/auth/travelpartner']
SERVICE_ACCOUNT_FILE = 'service_account_key_file.json'

cred = service_account.Credentials.from_service_account_file(
                        SERVICE_ACCOUNT_FILE,
                        scopes=SCOPES)
cred.refresh(Request())
headers = {}
cred.apply(headers)

Travel Partner API

تتيح Travel Partner API لشركاء الفنادق استرداد معلومات Hotel Center وتغيير بيانات Hotel Center لإدارة الحسابات الكبيرة أو المعقّدة.

اتّبِع تعليمات إعداد بروتوكول OAuth 2.0 للحصول على إذن باستخدام Travel Partner API.

عند إنشاء مشروع جديد لواجهة برمجة التطبيقات Travel Partners API، عليك تفعيل إذن الوصول إلى مشروعك الجديد على Google Cloud Console.

اتّبِع الخطوات التالية لتفعيل إمكانية الوصول إلى Travel Partners API:

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

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

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

  4. انقر على واجهة برمجة التطبيقات المطابقة في الجدول. تعرِض وحدة تحكّم Google Cloud وصفًا عن واجهة برمجة التطبيقات هذه.

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

لمزيد من المعلومات، يُرجى الاطّلاع على تفعيل الخدمات وإيقافها.

تم تفعيل Travel Partner API الآن للمشروع الجديد في حسابك على Google.

نطاق واجهة برمجة التطبيقات Travel Partner API هو: "https://www.googleapis.com/auth/travelpartner"

نقطة النهاية لواجهة برمجة التطبيقات Travel Partner API هي: "https://travelpartner.googleapis.com/v3/accounts/<account_id>/<path>"

Price Feeds API

تسمح واجهة برمجة التطبيقات Price Feeds API لشركاء الفنادق بتقديم بيانات أسعار مخصّصة لكل فندق. يمكن لشركاء الفنادق في Google استخدام بروتوكول OAuth2.0 للمصادقة والتفويض بأنفسهم عند تحميل الأسعار إلى Google. اتّبِع تعليمات إعداد بروتوكول OAuth 2.0 للحصول على إذن لاستخدام Price Feeds API.

نقاط يجب تذكّرها

يُرجى ملاحظة الاختلافات المهمة في تعليمات التفويض لواجهة برمجة التطبيقات "خلاصات الأسعار".

  1. على الشركاء إنشاء مشروع جديد لخلاصات الأسعار باستخدام بروتوكول OAuth 2.0 في Google Cloud Console باستخدام التعليمات نفسها الواردة في إعداد بروتوكول OAuth 2.0.

  2. NOT مطلوبًا تفعيل Price Feeds API في Google Cloud Console ويمكن تجاهله. ما عليك سوى استخدام حساب خدمة ومفتاح واحدَين، ثم استخدام حساب الخدمة ومفتاحه نفسهما لمنح مشروع "خلاصات الأسعار " إذن الوصول إلى بياناتك في Hotel Center. اتّبِع الخطوات المتبقّية المذكورة في إعداد OAuth2.0 لإكمال عملية ضبط واجهة برمجة التطبيقات.

الحصول على رمز الوصول OAuth2.0 لمغذّيات الأسعار

الخطوة التالية هي الحصول على رمز مميز للوصول إلى OAuth2.0 باستخدام نطاق تحميل سعر الإقامة باستخدام ملف مفتاح حساب الخدمة. يمكنك تفويض الطلبات المرسَلة إلى مشروع "خلاصات الأسعار" من خلال اتّباع التعليمات الواردة في التحضير لإجراء طلب مفوَّض من واجهة برمجة التطبيقات، ثم استخراج الرمز المميّز للوصول من بيانات الاعتماد التي تم الحصول عليها وضبطه في "Authorization" HTTP header.

نطاق تحميل أسعار الإقامة هو: "https://www.googleapis.com/auth/travel-partner-price-upload"

تحميل الأسعار

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

  • ضبط رمز الوصول في عنوان HTTP "Authorization"
curl -X POST -H "Authorization: Bearer <access token>"
www.google.com/travel/lodging/uploads/accounts/<account_id>/ota/hotel_rate_amount_notif --data-binary @<price_feed_file_location>

اختبار إعداد OAuth2.0 لواجهة برمجة التطبيقات Price Feeds API

يمكنك اختبار إعدادات OAuth2.0 من خلال تحميل ملف فارغ أو ملف يحتوي على بيانات أسعار حقيقية إلى أي من مسارات التحميل. استخدِم الجدول للتحقّق من حالة ردّ HTTP.

حالة استجابة HTTP الرسالة
200 Successful (OK)
401 Service account creation or access token fetch was not successful
403 Service account access wasn't granted to the Hotel Center account or both the service account key and access token has expired

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

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

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

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

خطأ الوصف
Invalid credentials قد يعني ذلك عدة أشياء. إذا واجهت هذا الخطأ، تأكَّد مما يلي:
  • حدّدت رأس Authorization يتضمّن رمزًا مميّزًا حاملاً صالحًا.
  • يجب أن يكون رمز المرور صالحًا منذ أقل من ساعة. يبقى الرمز المميّز صالحًا لمدة ساعة واحدة فقط.
  • حدّدت اسم الشريك الصحيح (باستخدام مَعلمة سلسلة طلب البحث partner ). القيمة هي معرّف الشريك الفريد، وليس اسم الشريك الذي يظهر في Hotel Ads Center. إذا لم يكن رقم تعريف الشريك معروفًا لك، يُرجى التواصل مع المدير الفني لحسابك.
Not found من المرجّح أنّ نقطة النهاية مكتوبة بشكلٍ غير صحيح. تأكَّد من إرسال طلب GET وأنّ عنوان URL للطلب صالح (يتوافق مع بنية واجهة برمجة التطبيقات التي تحاول الوصول إليها).
Invalid string value يحتوي جزء واحد أو أكثر من نقطة النهاية على بنية غير صالحة. على سبيل المثال، قد تكون قد أخطأت في كتابة جزء من المسار. تأكَّد من استخدام علامات ال подчеркивание والكتابة بالأحرف اللاتينية الكبيرة والصياغة الصحيحة في المسار بأكمله.
Unsupported output format يحدث هذا الخطأ في أغلب الأحيان عند استخدام Reports API. يجب تحديد "alt=csv" في عنوان URL لطلب GET الخاص بك. لا تتوافق Reports API مع تنسيق JSON.
AccessTokenRefreshError/Invalid grant عند تشغيل تطبيقك، قد يحدث هذا الخطأ لأحد السببين التاليين:
  • عنوان البريد الإلكتروني لحساب الخدمة غير صحيح. تحقَّق من حساب البريد الإلكتروني في وحدة تحكّم Google Cloud وتأكَّد من أنّه مفوَّض بالوصول إلى واجهة برمجة التطبيقات.
  • لا يملك عنوان البريد الإلكتروني إذن الوصول إلى واجهة برمجة التطبيقات. تحقّق مما إذا كان عنوان البريد الإلكتروني مفوَّضًا بالوصول إلى بيانات الفنادق التي تتم مشاركتها من خلال Hotel Center.
  • ملف المفاتيح ليس الملف الصحيح لحساب الخدمة. استخدِم Google Cloud Console لتنزيل شهادة .JSON جديدة وتأكَّد من أنّ تطبيقك يشير إلى الشهادة الصحيحة.
HotelAdsAPIConnection object has no attribute credentials عند تشغيل التطبيق، يكون مسار ملف .JSON غير صحيح.
Invalid scope عند تشغيل التطبيق، يجب أن يكون نطاق واجهة برمجة التطبيقات أحد النطاقَين التاليَين:
  • "https://www.googleapis.com/auth/travelpartner"
  • "https://www.googleapis.com/auth/travel-partner-price-upload"
Forbidden رقم تعريف الحساب الذي تستخدمه ليس لديك إذن بالوصول إليه. إذا كنت مالك حساب فرعي، قد لا تتمكّن من الوصول إلى رقم تعريف الحساب الرئيسي أو الجذر.