این سند دستورالعمل‌های گام‌به‌گام برای راه‌اندازی OAuth2.0 در برنامه‌تان هنگام دسترسی به میاناهای برنامه‌سازی کاربردی هتل مانند Travel Partner API و Price Feeds API را ارائه می‌دهد. برای صدور مجوز برای برنامه‌تان، به استفاده از OAuth 2.0 برای دسترسی به Google APIs مراجعه کنید.
راه‌اندازی OAuth 2.0
OAuth 2.0 از شما می‌خواهد که هویت خود را بااستفاده از حساب سرویس مرتبط با «حساب Google» خود تأیید کنید. حساب سرویس کلید خصوصی شما را در ازای کد دسترسی OAuth 2.0 ارسال می‌کند. سپس می‌توانید از این توکن در فراخوانی‌های میاناهای برنامه‌سازی کاربردی هتل برای داده‌های فقط خواندنی، مانند قیمت‌گذاری، هتل، و داده‌های گزارش تشخیص خرابی درباره فید قیمت هتل خود استفاده کنید.
کدهای دسترسی برای یک ساعت (۳۶۰۰ ثانیه) معتبر هستند.
اگر قبلاً ClientLogin را پیاده‌سازی کرده‌اید، رویکرد OAuth 2.0 مشابه است، با تفاوت‌های زیر:
- برنامه شما از حساب سرویس Google برای دسترسی به API استفاده می‌کند.
- هنگام فراخوانی میاناهای برنامه‌سازی کاربردی، کد دسترسی OAuth 2.0 را در سرصفحه HTTP
Authorizationارسال می‌کنید.
برای راه‌اندازی حسابتان جهت استفاده از OAuth 2.0 با هر Hotels API، این مراحل را انجام دهید:
هریک از این مراحل در بخش‌های زیر توضیح داده شده است.
مرحله ۱: ایجاد پروژه جدید در کنسول Google Cloud
از کنسول Google Cloud برای مدیریت و مشاهده داده‌های ترافیک، اصالت‌سنجی، و اطلاعات صورت‌حساب برای Google APIهایی که پروژه‌هایتان استفاده می‌کنند استفاده می‌شود.
در کنسول Google Cloud، پروژه مجموعه‌ای از تنظیمات، اعتبارنامه‌ها، و فراداده‌های مربوط به برنامه‌ای است که روی آن کار می‌کنید و از Google Developer API و منابع Google Cloud استفاده می‌کند.
از کنسول Google Cloud برای تولید اطلاعات کاربری API، فعال کردن API، و مدیریت اطلاعات تیم و صورت‌حساب مرتبط با پروژه‌تان نیز استفاده می‌شود.
برای ایجاد پروژه جدید در کنسول Google Cloud:
به سیستم Gmail یا «حساب Google» خود وارد شوید.
کنسول Google Cloud را باز کنید. اگر این اولین پروژه شما است، نمای اصلی دکمه ایجاد پروژه را نشان می‌دهد:
روی دکمه ایجاد پروژه کلیک کنید. کنسول Google Cloud کادر گفتگوی پروژه جدید را نمایش می‌دهد:
نامی دوستانه برای پروژه جدیدتان در فیلد ورودی نام پروژه وارد کنید. در زیر فیلد، کنسول Google Cloud شناسه پروژه‌ای برای شما تولید می‌کند و مطمئن می‌شود که این شناسه در بین همه پروژه‌ها یکتا باشد. برای مثال، اگر «پروژه جدید من» را وارد کنید، کنسول Google Cloud شناسه‌ای مثل
my-new-project-266022اختصاص می‌دهد.روی دکمه ایجاد کلیک کنید تا پروژه جدیدتان ایجاد شود.
از منو پیمایش برای انتخاب میاناهای برنامه‌سازی کاربردی و سرویس‌ها > داشبورد استفاده کنید.
تصویر زیر منو پیمایش را در بالا سمت راست کنسول Google Cloud نشان می‌دهد. با این کار، نمای داشبورد برای پروژه‌تان نمایش داده می‌شود:
برای اطلاعات بیشتر، به ایجاد و مدیریت پروژه‌ها مراجعه کنید.
مرحله ۲: ایجاد حساب سرویس و تولید اطلاعات اعتباری آن
حساب‌های سرویس برای تعاملات سرور به سرور استفاده می‌شوند، مانند تعاملات بین یک برنامه وب و داده‌های هتل شما.
برای ایجاد و پیکربندی حساب سرویس:
در نمای اصلی «کنسول Google API»، روی اطلاعات کاربری در پیمایش سمت راست کلیک کنید. کنسول Google Cloud نمای اعتبارنامه‌ها را نمایش می‌دهد.
نمای اطلاعات اعتباری شناسه‌های مشتری و اطلاعات اعتباری پروژه‌تان را نمایش می‌دهد. برنامه شما هنگام درخواست کد دسترسی OAuth 2.0 از شناسه کارخواه استفاده می‌کند. پروژه‌های جدید هنوز هیچ مشتری یا اطلاعات اعتباری‌ای ندارند.
روی پیوند اعتبارنامه‌ها در میاناهای برنامه‌سازی کاربردی و سرویس‌ها کلیک کنید.
روی دکمه ایجاد اطلاعات کاربری کلیک کنید و کلید حساب سرویس را از فیلتر انتخاب کنید. نمای ایجاد کلید حساب سرویس نمایش داده می‌شود.
از فیلتر حساب سرویس، حساب سرویس جدید را انتخاب کنید.
نام حساب سرویس و شناسه حساب سرویس را وارد کنید.
نام می‌تواند هر چیزی باشد، اما شناسه حساب باید در همه پروژه‌ها منحصربه‌فرد باشد. کنسول Google Cloud براساس نامی که وارد کرده‌اید، شناسه حساب یکتایی برای شما تولید می‌کند.
JSON را برای نوع کلید انتخاب کنید. JSON الزامی است.
روی دکمه ایجاد کلیک کنید. کنسول Google Cloud جفت کلید خصوصی یا عمومی برای پروژه‌تان تولید می‌کند. کلید خصوصی در مکان پیش‌فرضی که مرورگرتان بارگیری‌ها را ذخیره می‌کند ذخیره می‌شود. باید فایل قالب
.JSONرا بارگیری کنید.از کلید خصوصی در اسکریپت‌ها یا برنامه‌های دیگری که به میانای برنامه‌سازی کاربردی شما دسترسی دارند استفاده می‌کنید.
وقتی تولید کلیدها به‌پایان رسید، کنسول Google Cloud پیام «حساب سرویس ایجاد شد» را نمایش می‌دهد.
روی دکمه بسیارخوب، متوجه شدم کلیک کنید. کنسول Google Cloud شما را به نمای اطلاعات کاربری برمی‌گرداند. برای تأیید جزئیات مربوط به حساب خدماتتان و دیدن حساب خدمات مرتبط با پروژه‌تان، در این نما روی مدیریت حساب‌های خدمات کلیک کنید.
اکنون حساب سرویس دارای اعتبارنامه‌های زیر است:
- شناسه کارخواه: شناسه یکتایی که برنامه‌تان هنگام درخواست کد دسترسی OAuth 2.0 استفاده می‌کند.
- نشانی ایمیل: نشانی ایمیل تولیدشده برای حساب سرویس، به‌صورت «account_name@project_name.google.com.iam.gserviceaccount.com».
- اثر انگشت‌های گواهینامه: شناسه کلید خصوصی که بارگیری کردید.
برای اطلاعات بیشتر، به استفاده از OAuth 2.0 برای برنامه‌های سرور به سرور مراجعه کنید.
مرحله ۳: به حساب سرویس اجازه دهید به داده‌های Hotel Center شما دسترسی داشته باشد
مرحله نهایی این است که به حساب سرویس جدید اجازه دسترسی به Hotel Center خود را بدهید. حساب خدمات با نشانی ایمیل تولیدشده‌ای که در مرحله قبل ایجاد کردید شناسایی می‌شود. بااستفاده از تنظیمات هم‌رسانی مرکز هتل، دسترسی به این حساب را فراهم می‌کنید.
اگر دسترسی مناسب برای افزودن کاربر به حساب را ندارید، بااستفاده از فرم تماس با ما با تیم «هتل‌های Google» تماس بگیرید و درخواست کنید مالکیت حسابتان را راه‌اندازی کنند. می‌توانید درخواست کنید یک یا چند ایمیل برای مالک ارسال شود. برای اطلاعات بیشتر درباره دسترسی به Hotel Center، به پیوند دادن Hotel Center و Google Ads مراجعه کنید.
برای دادن دسترسی حساب سرویس به داده‌های Hotel Center:
در پنجره مرورگر جدیدی، Hotel Center را باز کنید.
در برنمای Hotel Center از Google، روی نماد افزودن کاربر کلیک کنید تا کادر گفتگوی هم‌رسانی باز شود.
در فیلد افزودن افراد بیشتر، نشانی ایمیل حساب سرویسی را که می‌خواهید به Hotel Center اضافه کنید وارد کنید.
گزینه اطلاع به افراد را انتخاب‌شده نگه دارید.
مدیریت را از فیلتر انتخاب کنید.
روی دکمه دعوت کلیک کنید.
پس‌از افزودن کاربران به Hotel Center، حساب سرویس شما باید ظرف حدود ۲۴ ساعت برای دسترسی به میانای برنامه‌سازی کاربردی فعال شود.
پس‌از اینکه Google به شما اطلاع داد که دسترسی به API برای حساب سرویس شما فعال شده است، می‌توانید با OAuth 2.0 به API دسترسی پیدا کنید.
نحوه استفاده از OAuth 2.0
برای دسترسی به API، برنامه شما باید با نشانی ایمیل و کلید خصوصی تولیدشده حساب سرویس،
خود را به 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"
هنگام ایجاد اعتبارنامه باید حساب خدمات را مشخص کنید. به ایجاد حساب سرویس و تولید اطلاعات اعتباری آن مراجعه کنید.
هنگام توسعه برنامه‌تان، حتماً روال‌های مطلوب را برای اصالت‌سنجی برنامه‌تان بااستفاده از کلیدهای میانای API دنبال کنید. بیشتر بدانید.
مثال
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 را فعال کنید.
مراحل زیر را برای فعال کردن دسترسی به Travel Partners API دنبال کنید:
به نمای «داشبورد» پروژه‌تان بروید.
روی فعال کردن میاناهای برنامه‌سازی کاربردی و سرویس‌ها کلیک کنید. با این کار، صفحه خوشامدگویی «کتابخانه میانای برنامه‌سازی کاربردی» نمایش داده می‌شود.
در فیلد جستجو، شروع به تایپ کردن «Travel Partner API» کنید، سپس کنسول فهرستی از APIهایی را که با آنچه تایپ می‌کنید مطابقت دارند نمایش می‌دهد.
روی API منطبق در جدول کلیک کنید. کنسول Google Cloud شرحی درباره آن API نمایش می‌دهد.
روی دکمه فعال کردن میانای برنامه‌سازی کاربردی کلیک کنید تا این میانای برنامه‌سازی کاربردی برای پروژه‌تان فعال شود.
برای اطلاعات بیشتر، به فعال و غیرفعال کردن سرویس‌ها مراجعه کنید.
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 مجوز دریافت کنید.
نکات مهم
به تفاوت‌های مهم در دستورالعمل‌های صدور مجوز برای Price Feeds API توجه کنید.
شرکا باید بااستفاده از همان دستورالعمل‌های ارائه‌شده در راه‌اندازی OAuth 2.0، پروژه Price Feeds OAuth2.0 جدیدی در کنسول Google Cloud ایجاد کنند.
فعال کردن Price Feeds API در کنسول Google Cloud لازم نیست و می‌توانید آن را نادیده بگیرید. فقط به یک حساب سرویس و کلید نیاز دارید و سپس از همان حساب سرویس و کلید برای اعطای دسترسی پروژه «فیدهای قیمت» به داده‌های Hotel Center خود استفاده کنید. مراحل باقی‌مانده ذکرشده در راه‌اندازی OAuth2.0 را دنبال کنید تا پیکربندی میانای برنامه‌سازی کاربردی‌تان تکمیل شود.
دریافت کد دسترسی OAuth2.0 برای فیدهای قیمت
مرحله بعدی دریافت کد دسترسی OAuth2.0 با دامنه بارگذاری قیمت اقامتگاه بااستفاده از فایل کلید حساب سرویس است. با دنبال کردن دستورالعمل‌های ارائه‌شده در
آماده‌سازی برای برقراری تماس API تفویض‌شده
می‌توانید درخواست‌های ارسال‌شده به پروژه «فیدهای قیمت» خود را مجاز کنید
و سپس کد دسترسی را از اطلاعات اعتباری به‌دست‌آمده استخراج کنید و آن را در
سرصفحه 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/<acc>ount_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 |
عیب‌یابی
با مشکلی مواجه شده‌اید؟ بررسی سریع موارد زیر ممکن است مشکل را حل کند.
- آیا پروژه‌ای در کنسول Google Cloud ایجاد کرده‌اید؟
- آیا این سرویس را در پروژه‌تان فعال کرده‌اید؟
- آیا پس‌از کلیک کردن روی ایجاد شناسه کارخواه و انتخاب حساب سرویس، فایل
.JSON(کلید خصوصی) را بارگیری کردید؟ - آیا نشانی ایمیل شناسه مشتری حساب سرویس را به این شکل دریافت کردید:
nnnnnnn@app_name.google.com.iam.gserviceaccount.com؟ - آیا با کلیک کردن روی دکمه هم‌رسانی این حساب، حساب مرکز آگهی‌های هتل خود را با حساب سرویس هم‌رسانی کردید؟
- آیا نشانی ایمیل حساب سرویس و شناسه شریکتان را به مدیر فنی حساب (TAM) ارسال کرده‌اید؟
- آیا فراخوانی‌های میانای برنامه‌سازی کاربردی شما یک توکن اخیراً دریافت‌شده را در
سرصفحه
Authorizationارسال می‌کند؟ - آیا بیش‌از ۱ ساعت از عمر توکن شما می‌گذرد؟
جدول زیر برخی‌از خطاهای رایج و راه‌حل‌های احتمالی را فهرست می‌کند:
| خطا | شرح |
|---|---|
| Invalid credentials | این می‌تواند معانی مختلفی داشته باشد. اگر با این خطا مواجه شدید،
بررسی کنید که:
|
| Not found | نقطه پایانی شما احتمالاً بدشکل است. بررسی کنید که درخواست GET ارسال می‌کنید و نشانی وب درخواست معتبر است (با نحو میانای برنامه‌سازی کاربردی که می‌خواهید به آن دسترسی پیدا کنید مطابقت دارد). |
| Invalid string value | یک یا چند بخش از نقطه پایانی حاوی نحو نامعتبر است. برای مثال، ممکن است بخشی از مسیر را اشتباه تایپ کرده باشید. بررسی کنید که از زیرخط، حروف بزرگ، و عبارت‌بندی صحیح در کل مسیر استفاده کرده باشید. |
| Unsupported output format | این خطا معمولاً هنگام استفاده از Reports API رخ می‌دهد. باید
"alt=csv" را در نشانی وب درخواست GET
خود مشخص کنید. Reports API از JSON پشتیبانی نمی‌کند. |
| AccessTokenRefreshError/Invalid grant | هنگام اجرای برنامه، این خطا ممکن است به‌دلیل موارد زیر رخ دهد:
|
| HotelAdsAPIConnection object has no attribute credentials | هنگام اجرای برنامه، مسیر فایل .JSON شما
نادرست است. |
| Invalid scope | هنگام اجرای برنامه، گستره میانای برنامه‌سازی کاربردی شما باید یکی از موارد زیر باشد:
|
| Forbidden | شناسه حسابی که استفاده می‌کنید شناسه‌ای است که برای دسترسی به آن مجوز ندارید. اگر مالک حساب فرعی هستید، ممکن است نتوانید به شناسه حساب اصلی یا ریشه دسترسی داشته باشید. |