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

تقدّم هذه المستندات تعليمات مفصّلة حول كيفية إعداد OAuth2.0 في تطبيقك عند الوصول إلى واجهات برمجة التطبيقات الخاصة بالفنادق، مثل واجهة برمجة التطبيقات مع "شريك السفر" وواجهة برمجة التطبيقات الخاصة بخلاصات الأسعار. يُرجى الاطّلاع على استخدام بروتوكول 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 في عنوان HTTP Authorization عند استدعاء واجهات برمجة التطبيقات.

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

  1. إنشاء مشروع جديد في "وحدة تحكّم Google Cloud"

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

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

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

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

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

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

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

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

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

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

    fig1

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

    fig2

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

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

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

    fig3

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

    fig4

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

    • معرّف العميل: هو معرّف فريد يستخدمه تطبيقك عند طلب رمز مميز للوصول إلى OAuth 2.0.
    • عنوان البريد الإلكتروني: هو عنوان بريد إلكتروني تم إنشاؤه لحساب الخدمة، ويكون بالتنسيق "account_name@project_name.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

تتيح واجهة برمجة التطبيقات مع "شريك السفر" لشركاء الإقامة استرداد معلومات 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

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

ملاحظات مهمة

يُرجى الانتباه إلى الاختلافات المهمة في تعليمات التفويض الخاصة بواجهة برمجة التطبيقات Price Feeds.

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

  2. لا يلزم تفعيل Price Feeds API في Google Cloud Console ويمكن تجاهل هذه الخطوة. ما عليك سوى إنشاء حساب خدمة ومفتاح واحدين، ثم استخدام حساب الخدمة والمفتاح نفسيهما لمنح مشروع &quot;خلاصات الأسعار &quot; إذن الوصول إلى بياناتك على Hotel Center. اتّبِع الخطوات المتبقية المذكورة في عملية إعداد OAuth 2.0 لإكمال عملية ضبط واجهة برمجة التطبيقات.

الحصول على رمز الدخول عبر OAuth2.0 إلى "خلاصات الأسعار"

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

نطاق تحميل أسعار الإقامة هو: "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. هل أرسلت عنوان البريد الإلكتروني لحساب الخدمة ومعرّف الشريك إلى المدير التقني للحسابات (TAM)؟
  7. هل تمرِّر طلبات البيانات من واجهة برمجة التطبيقات رمزًا مميزًا تم الحصول عليه مؤخرًا في العنوان Authorization؟
  8. هل مرّ أكثر من ساعة على إنشاء الرمز المميّز؟

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

خطأ الوصف
Invalid credentials قد يعني ذلك عدة أمور. في حال ظهور هذا الخطأ، تأكَّد مما يلي:
  • لقد حدّدت عنوان Authorization مع رمز مميّز صالح لحامل الإذن.
  • لم يمرّ على إصدار رمز الدخول المميز أكثر من ساعة. يبقى الرمز المميّز صالحًا لمدة ساعة واحدة فقط.
  • لقد حدّدت اسم الشريك الصحيح (باستخدام مَعلَمة سلسلة طلب البحث partner ). القيمة هي رقم تعريف الشريك الفريد، وليس اسم الشريك الذي يظهر في مركز إعلانات الفنادق. إذا كنت لا تعرف رقم تعريف الشريك، يُرجى التواصل مع مدير الحساب الفني (TAM).
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 رقم تعريف الحساب الذي تستخدمه لا تملك إذنًا بالوصول إليه. إذا كنت مالك حساب فرعي، قد لا تتمكّن من الوصول إلى معرّف الحساب الرئيسي أو حساب الجذر.