از OAuth 2.0 برای تأیید برنامه خود هنگام دسترسی به APIهای هتل استفاده کنید.
راه اندازی OAuth 2.0
OAuth 2.0 مستلزم این است که خود را با استفاده از یک حساب سرویس مرتبط با حساب Google خود شناسایی کنید. حساب سرویس کلید خصوصی شما را در ازای توکن دسترسی OAuth 2.0 ارسال می کند. سپس می‌توانید از این نشانه در تماس‌های با APIهای هتل برای داده‌های فقط خواندنی ، مانند داده‌های قیمت‌گذاری، هتل و گزارش‌های تشخیصی درباره فید قیمت هتل خود استفاده کنید.
توکن های دسترسی برای یک ساعت (3600 ثانیه) خوب هستند.
اگر قبلا ClientLogin را اجرا کرده اید، رویکرد OAuth 2.0 مشابه است، با تفاوت های زیر:
- برنامه شما از یک حساب سرویس Google برای دسترسی به API استفاده می کند.
- هنگام فراخوانی APIها، یک نشانه دسترسی OAuth 2.0 را در سرصفحه
AuthorizationHTTP ارسال می کنید.
برای تنظیم حساب خود برای استفاده از OAuth 2.0 با Travel Partner API ، این مراحل را انجام دهید:
هر یک از این مراحل در بخش های بعدی توضیح داده شده است.
مرحله 1: یک پروژه DevConsole جدید ایجاد کنید
Google Developers Console ("DevConsole") تجربه برنامه‌نویس Google برای مدیریت و مشاهده داده‌های ترافیک، احراز هویت و اطلاعات صورت‌حساب برای APIهای Google است که پروژه‌های شما استفاده می‌کنند.
در DevConsole، پروژه مجموعه‌ای از تنظیمات، اعتبارنامه‌ها و ابرداده‌های مربوط به برنامه یا برنامه‌هایی است که روی آن کار می‌کنید و از APIهای برنامه‌نویس Google و منابع Google Cloud استفاده می‌کنند.
DevConsole جایی است که شما این جنبه‌های پروژه خود را مدیریت می‌کنید، مانند تولید اعتبار API، فعال کردن API، و مدیریت تیم و اطلاعات صورت‌حساب مرتبط با پروژه‌تان.
برای ایجاد یک پروژه DevConsole جدید:
به حساب Gmail/Google خود وارد شوید.
کنسول برنامه نویس Google را باز کنید. اگر این اولین پروژه شما است، نمای اصلی یک دکمه ساده CREATE PROJECT را نشان می دهد:
روی دکمه CREATE PROJECT کلیک کنید. DevConsole کادر گفتگوی New Project را نمایش می دهد:
در قسمت ورودی نام پروژه یک نام مناسب برای پروژه جدید خود وارد کنید. در زیر فیلد، DevConsole یک شناسه پروژه برای شما ایجاد می‌کند و اطمینان می‌دهد که شناسه در همه پروژه‌ها منحصربه‌فرد است. به عنوان مثال، اگر «پروژه جدید من» را وارد کنید، DevConsole یک شناسه مانند
my-new-project-266022اختصاص می‌دهد.برای ایجاد پروژه جدید خود روی دکمه Create کلیک کنید.
از منوی پیمایش برای انتخاب APIs & Services > Dashboard استفاده کنید.
تصویر زیر منوی ناوبری را در سمت چپ بالای DevConsole نشان می دهد. این نمای داشبورد پروژه شما را نشان می دهد:
برای اطلاعات بیشتر، به مدیریت پروژه‌ها در Developers Console مراجعه کنید.
هنگامی که یک پروژه جدید ایجاد می کنید، هنوز هیچ API مرتبط با آن وجود ندارد. در مرحله بعد، Travel Partner API برای پروژه جدید خود فعال خواهید کرد.
مرحله 2: Travel Partner API برای پروژه جدید فعال کنید
برای استفاده از APIهای هتل، باید Travel Partner API در پروژه DevConsole جدید خود فعال کنید.
برای فعال کردن APIهای هتل برای پروژه جدید خود:
همانطور که در بالا توضیح داده شد به نمای داشبورد پروژه خود بروید.
روی Enable APIs and Services کلیک کنید. این صفحه خوش آمدگویی کتابخانه API را نمایش می دهد.
در قسمت جستجو، شروع به تایپ Travel Partner API کنید. Google API Console لیستی از APIهایی را نشان می دهد که با آنچه شما تایپ می کنید مطابقت دارند.
روی Travel Partner API در جدول APIهای منطبق کلیک کنید. DevConsole توضیحاتی در مورد API نمایش می دهد.
روی دکمه Enable API کلیک کنید تا این API برای پروژه شما فعال شود.
برای اطلاعات بیشتر، به فعال کردن و غیرفعال کردن API ها مراجعه کنید.
APIهای هتل اکنون برای پروژه جدید حساب Google شما فعال شده است.
مرحله بعدی ایجاد یک حساب کاربری سرویس و ایجاد کلید برای آن است.
مرحله 3: یک حساب کاربری ایجاد کنید و اعتبار آن را ایجاد کنید
حساب های سرویس توسط تعاملات سرور به سرور مانند تعاملات بین یک برنامه وب و داده های هتل شما استفاده می شود.
برای ایجاد و پیکربندی یک حساب سرویس:
در نمای اصلی Google API Console، روی Credentials در ناوبری سمت چپ کلیک کنید. DevConsole نمای اعتبارنامه را نمایش می دهد.
نمای Credentials شناسه های مشتری و اعتبارنامه های پروژه شما را نشان می دهد. برنامه شما هنگام درخواست رمز دسترسی OAuth 2.0 از شناسه مشتری استفاده می کند. پروژه های جدید هنوز هیچ مشتری یا اعتباری نخواهند داشت.
روی پیوند اعتبارنامه‌ها در APIها و خدمات کلیک کنید.
روی دکمه Create credentials کلیک کنید و از منوی کشویی گزینه Service account key را انتخاب کنید. نمای کلید ایجاد حساب کاربری نمایش داده می شود.
از منوی کشویی حساب سرویس ، حساب سرویس جدید را انتخاب کنید.
نام حساب سرویس و شناسه حساب سرویس را وارد کنید.
نام می تواند هر چیزی باشد که شما می خواهید، اما شناسه حساب باید در همه پروژه ها منحصر به فرد باشد. DevConsole بر اساس نامی که وارد کرده اید، یک شناسه حساب منحصر به فرد برای شما ایجاد می کند.
P12 را برای نوع کلید، مانند شکل زیر انتخاب کنید. P12 مورد نیاز است .
روی دکمه Create کلیک کنید. DevConsole یک جفت کلید خصوصی/عمومی برای پروژه شما ایجاد می کند. کلید خصوصی در مکان پیش فرضی که مرورگر شما دانلودها را ذخیره می کند، ذخیره می شود. شما باید فرمت
.p12(باینری) را بر خلاف فرمت فایل.jsonدانلود کنید .شما از کلید خصوصی در اسکریپت ها یا سایر برنامه های کاربردی خود استفاده می کنید که به Travel Partner API دسترسی دارند.
DevConsole پس از اتمام تولید کلیدها، اعلان زیر را نمایش می دهد:
روی دکمه OK, got it کلیک کنید. DevConsole شما را به نمای Credentials برمی گرداند. برای تأیید جزئیات مربوط به حساب سرویس خود و دیدن حساب های خدمات مرتبط با پروژه خود، روی مدیریت حساب های خدماتی در این نما کلیک کنید.
حساب سرویس اکنون دارای اعتبار زیر است:
- شناسه مشتری: یک شناسه منحصربه‌فرد که برنامه شما هنگام درخواست نشانه دسترسی OAuth 2.0 از آن استفاده می‌کند.
- آدرس ایمیل: یک آدرس ایمیل ایجاد شده برای حساب سرویس، به شکل " account_name @ project_name .google.com.iam.gserviceaccount.com".
- اثر انگشت گواهی: شناسه کلید خصوصی که دانلود کرده اید.
برای اطلاعات بیشتر، به استفاده از OAuth 2.0 برای برنامه های کاربردی سرور به سرور مراجعه کنید.
مرحله 4: به حساب خدمات اجازه دسترسی به اطلاعات مرکز هتل خود را بدهید
مرحله آخر این است که حساب سرویس جدید را با دسترسی به مرکز هتل خود ارائه دهید. حساب سرویس با آدرس ایمیل ایجاد شده ای که در مرحله قبل ایجاد کردید شناسایی می شود. با استفاده از تنظیمات اشتراک‌گذاری مرکز هتل، دسترسی به این حساب را فراهم می‌کنید.
برای دسترسی یک حساب سرویس به داده های مرکز هتل خود:
اگر دسترسی مناسبی برای افزودن کاربران به حساب ندارید، با استفاده از فرم تماس با ما با تیم Google Hotels تماس بگیرید و از ما بخواهید که مالکیت حساب شما را تنظیم کنیم. می‌توانید درخواست کنید که یک یا چند ایمیل به مالک ارسال شود. برای اطلاعات بیشتر در مورد دسترسی به مرکز هتل، به لینک مرکز هتل و تبلیغات گوگل مراجعه کنید.
در یک پنجره مرورگر جدید، مرکز هتل را باز کنید.
در بنر Hotel Center by Google ، روی نماد افزودن کاربر کلیک کنید تا گفتگوی اشتراک‌گذاری باز شود.
در قسمت افزودن افراد بیشتر ، آدرس ایمیل حساب خدماتی را که می‌خواهید به مرکز هتل خود اضافه کنید وارد کنید.
گزینه Notify people را انتخاب نگه دارید.
از منوی کشویی، مدیریت را انتخاب کنید.
روی دکمه دعوت کلیک کنید.
پس از اینکه کاربران را به مرکز هتل خود اضافه کردید، حساب سرویس شما باید در عرض 24 ساعت برای دسترسی به API فعال شود.
پس از اینکه Google به شما اطلاع داد که دسترسی API برای حساب سرویس شما فعال شده است، می توانید با OAuth دسترسی به API را شروع کنید.
با استفاده از OAuth 2.0
برای دسترسی به API، برنامه شما باید خود را با آدرس ایمیل و کلید خصوصی ایجاد شده حساب سرویس در گوگل شناسایی کند. مکانیسم احراز هویت Google این کلید را با یک نشانه دسترسی OAuth 2.0 که در هدر Authorization در تماس‌های API برنامه خود ارسال می‌کنید، مبادله می‌کند.
توکن‌های دسترسی (همچنین به عنوان توکن‌های حامل نیز شناخته می‌شوند) بخشی از استاندارد OAuth 2.0 هستند. سینتکس برای تعیین یک نشانه دسترسی در هدر HTTP عبارت است از:
Authorization: Bearer *oauth2_access_token*
مثال زیر نمونه هدرهای HTTP درخواستی را نشان می‌دهد که به گزارش‌های API دسترسی دارد:
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
برای ایجاد یک نشانه دسترسی، یک برنامه کاربردی به هر زبانی که انتخاب می کنید ایجاد کنید. مثال زیر توکن را در پایتون تولید می کند. سپس می‌توانید هنگام دسترسی به Travel Partner API از این نشانه در سرصفحه‌های Authorization درخواست‌های خود استفاده کنید.
#!/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>
هنگام توسعه برنامه خود، مطمئن شوید که بهترین روش ها را برای استفاده ایمن از کلیدهای API دنبال کنید.
نمونه اسکریپت پایتون یک توکن حامل هدر Authorization را خروجی می‌دهد، همانطور که مثال زیر نشان می‌دهد:
$ python sample.py Authorization: Bearer ya29.42424242sample_420icu8122KSvoh4T42cRoG3rW1lc0Q $
از ارزش توکن در درخواست های خود استفاده کنید. برای 1 ساعت بعد از تولید خوب است.
عیب یابی
به مشکل بر می خورید؟ بررسی سریع موارد زیر ممکن است مشکل را حل کند.
- آیا پروژه ای در کنسول برنامه نویس گوگل ایجاد کردید؟
- آیا Travel Partner API پیدا کردید و فعال کردید؟
- آیا پس از کلیک بر روی ایجاد شناسه مشتری و انتخاب حساب سرویس، یک فایل
.p12یک کلید خصوصی را دانلود کردید؟ - آیا آدرس ایمیل شناسه مشتری حساب سرویس یک فرم را دریافت کردید:
nnnnnnn@app_name.google.com.iam.gserviceaccount.com؟ - آیا با کلیک روی دکمه اشتراک‌گذاری این حساب ، حساب مرکز تبلیغات هتل خود را با حساب خدمات به اشتراک گذاشته‌اید؟
- آیا آدرس ایمیل حساب سرویس و شناسه شریک خود را برای مدیر حساب فنی خود (TAM) ارسال کردید؟
- آیا تماس‌های Travel Partner API شما در حال ارسال رمزی هستند که اخیراً در سرصفحه
Authorizationدریافت کرده‌اید؟ - آیا نشانه حامل هدر
Authorizationشما بیش از 1 ساعت قدمت دارد؟
جدول زیر برخی از خطاهای رایج و رزولوشن های احتمالی را فهرست می کند:
| خطا | شرح |
|---|---|
| Invalid credentials | این می تواند به معنای چند چیز باشد. اگر با این خطا مواجه شدید، بررسی کنید:
|
| Not found | به احتمال زیاد نقطه پایانی شما نادرست است. بررسی کنید که درخواست GET ارسال می‌کنید و URL درخواست معتبر است (با نحو API که می‌خواهید به آن دسترسی پیدا کنید مطابقت دارد). |
| Invalid string value | یک یا چند قسمت از نقطه پایانی دارای نحو نامعتبر است. برای مثال، ممکن است قسمتی از مسیر را اشتباه نوشته باشید. بررسی کنید که در کل مسیر خود از زیرخط، حروف بزرگ و جمله بندی صحیح استفاده کرده اید. |
| Unsupported output format | این خطا معمولاً هنگام استفاده از Reports API رخ می دهد. شما باید "alt=csv" در URL درخواست GET خود مشخص کنید. API Reports از JSON پشتیبانی نمی کند. |
| AccessTokenRefreshError/Invalid grant | هنگام اجرای نمونه برنامه پایتون، این خطا ممکن است ناشی از موارد زیر باشد:
|
| HotelAdsAPIConnection object has no attribute credentials | هنگام اجرای نمونه برنامه پایتون، مسیر فایل .p12 شما نادرست است. |
| Invalid scope | هنگام اجرای نمونه برنامه پایتون، محدوده API باید https://www.googleapis.com/auth/travelpartner باشد. |
| Forbidden | شناسه حسابی که استفاده می‌کنید، شناسه‌ای است که مجوز دسترسی به آن را ندارید. اگر صاحب حساب فرعی هستید، ممکن است نتوانید به شناسه حساب والد یا ریشه دسترسی داشته باشید. |