דף זה תורגם על ידי Cloud Translation API.

אימות API

באמצעות OAuth 2.0 תוכלו לאשר את האפליקציה שלכם כשאתם ניגשים לממשקי ה-API של המלונות.

הגדרת OAuth 2.0

OAuth 2.0 מחייב אתכם להזדהות באמצעות חשבון שירות המשויך לחשבון Google שלכם. חשבון השירות שולח את המפתח הפרטי שלכם בתמורה לאסימון גישה מסוג OAuth 2.0. לאחר מכן אפשר להשתמש באסימון הזה בקריאות לממשקי ה-API של מלונות עבור נתונים לקריאה בלבד, כמו נתוני תמחור, מלונות ונתוני אבחון דיווח על פיד מחירי המלונות.

אסימוני גישה תקפים למשך שעה (3,600 שניות).

אם הטמעתם בעבר את ClientLogin, הגישה של OAuth 2.0 דומה, אבל ההבדלים הבאים:

האפליקציה משתמשת בחשבון שירות של Google כדי לגשת ל-API.
אתם מעבירים אסימון גישה מסוג OAuth 2.0 בכותרת ה-HTTP Authorization כשאתם שולחים קריאה ל-API.

כדי להגדיר את החשבון לשימוש ב-OAuth 2.0 עם Travel Partner API, צריך לבצע את השלבים הבאים:

יצירת פרויקט חדש ב-Google Developers Console (DevConsole)
הפעלת גישה אל Travel Partner API של הפרויקט החדש
יצירה של חשבון שירות ופרטי הכניסה שלו
איך מעניקים לחשבון השירות גישה לנתוני המלון

כל אחד מהשלבים האלה מתואר בסעיפים הבאים.

שלב 1: יוצרים פרויקט חדש ב-DevConsole

Google Developers Console (DevConsole) הוא חוויית הפיתוח של Google, שמיועד לניהול ולהצגה של נתוני תעבורת הנתונים, האימות ונתוני החיוב של Google APIs שבהם משתמשים בפרויקטים שלכם.

ב-DevConsole, פרויקט הוא אוסף של הגדרות, פרטי כניסה ומטא-נתונים לגבי האפליקציה או האפליקציות שאתם עובדים עליהן, ומשתמשות בממשקי Google Developer API ובמשאבים של Google Cloud.

ב-DevConsole תוכלו לנהל את ההיבטים האלה של הפרויקט, כמו יצירת פרטי כניסה ל-API, הפעלת ממשקי API וניהול נתוני הצוות ונתוני החיוב המשויכים לפרויקט.

כדי ליצור פרויקט DevConsole חדש:

נכנסים לחשבון Gmail/Google.
פותחים את Google Developer Console. אם זה הפרויקט הראשון שלכם, בתצוגה הראשית מופיע לחצן CREATE PROJECT פשוט:
לוחצים על הלחצן יצירת פרויקט. ב-DevConsole מוצגת תיבת הדו-שיח New Project:

בשדה Project name מזינים שם ידידותי לפרויקט החדש. מתחת לשדה, אפליקציית DevConsole יוצרת בשבילכם מזהה פרויקט, כדי להבטיח שהמזהה יהיה ייחודי בכל הפרויקטים. לדוגמה, אם מזינים "My New Project", DevConsole מקצה מזהה כמו my-new-project-266022.
לוחצים על הלחצן Create כדי ליצור את הפרויקט החדש.
בתפריט הניווט בוחרים באפשרות APIs & Services > Dashboard (ממשקי API ושירותים > מרכז בקרה).

בתמונה הבאה מוצג תפריט הניווט בפינה השמאלית העליונה של DevConsole. תופיע התצוגה של מרכז הבקרה של הפרויקט:

מידע נוסף זמין במאמר ניהול פרויקטים במסוף המפתחים.

כשיוצרים פרויקט חדש, עדיין לא משויכים אליו ממשקי API. בשלב הבא מפעילים את Travel Partner API בפרויקט החדש.

שלב 2: מפעילים את Travel Partner API בפרויקט החדש

כדי להשתמש בממשקי ה-API של המלון, צריך להפעיל את Travel Partner API בפרויקט DevConsole החדש.

כדי להפעיל את ממשקי ה-API של מלונות בפרויקט החדש:

עוברים לתצוגה Dashboard (לוח הבקרה) של הפרויקט כפי שמתואר למעלה.
לוחצים על Enable APIs and Services. יוצג דף הפתיחה של ספריית ה-API.
בשדה החיפוש, מתחילים להקליד Travel Partner API. במסוף Google API מוצגת רשימה של ממשקי API שתואמים לטקסט שאתם מקלידים.

נקודה חשובה: Travel Partner API גלוי לשותפים מהימנים בלבד. אם ה-API לא מופיע במהלך החיפוש, פנו למנהל החשבונות הטכני (TAM).
לוחצים על Travel Partner API בטבלת ממשקי ה-API התואמים. ב-DevConsole מוצג תיאור של ה-API.
לוחצים על הלחצן Enable API כדי להפעיל את ה-API הזה בפרויקט.

מידע נוסף זמין במאמר הפעלה והשבתה של ממשקי API.

ממשקי Hotel API מופעלים עכשיו בפרויקט החדש של חשבון Google שלך.

השלב הבא הוא יצירת חשבון שירות ויצירת מפתחות עבורו.

שלב 3: יצירת חשבון שירות ויצירת פרטי הכניסה שלו

חשבונות השירות משמשים לאינטראקציות בין שרת לשרת, כמו האינטראקציות בין אפליקציית אינטרנט לבין נתוני המלונות.

כדי ליצור ולהגדיר חשבון שירות:

בתצוגה הראשית של Google API Console, לוחצים על Credentials בתפריט הניווט השמאלי. ב-DevConsole מוצגת התצוגה Credentials.

בתצוגה Credentials מוצגים מזהי הלקוח ופרטי הכניסה של הפרויקט. האפליקציה שלכם תשתמש במזהה הלקוח כשתבקשו אסימון גישה מסוג OAuth 2.0. לפרויקטים חדשים עדיין לא יהיו לקוחות או פרטי כניסה.
לוחצים על הקישור Credentials in APIs and services.
לוחצים על הלחצן Create credentials ובתפריט הנפתח בוחרים באפשרות Service account key. התצוגה Create account key מופיעה.
בתפריט הנפתח Service account, בוחרים באפשרות New service account.
מזינים שם לחשבון השירות ומזהה של חשבון השירות.

השם יכול להיות כל מה שתרצו, אבל מספר החשבון צריך להיות ייחודי בכל הפרויקטים. DevConsole ייצור מספר חשבון ייחודי על סמך השם שהזנתם.
בוחרים באפשרות P12 לסוג המפתח, כפי שמוצג בהמשך. נדרש ערך P12.
לוחצים על הלחצן Create. DevConsole יוצר זוג מפתחות פרטיים/ציבוריים לפרויקט. המפתח הפרטי נשמר במיקום ברירת המחדל שבו הדפדפן מאחסן את ההורדות. צריך להוריד את הפורמט .p12 (בינארי), בניגוד לפורמט הקובץ .json.

משתמשים במפתח הפרטי בסקריפטים או באפליקציות אחרות שיש להן גישה ל-Travel Partner API.

זהירות: קובץ המפתח הפרטי מכיל מידע אישי רגיש שהלקוחות צריכים לגשת אליהם כדי לקבל אסימון, ולכן צריך לאחסן אותו במקום בטוח.

בסיום יצירת המפתחות, תוצג ב-DevConsole את ההודעה הבאה:
לוחצים על הלחצן הבנתי. DevConsole מחזירה לתצוגה Credentials. כדי לאשר את הפרטים של חשבון השירות ולראות את חשבונות השירות שמשויכים לפרויקט, לוחצים על Manage service accounts בתצוגה הזו.

לחשבון השירות משויכים עכשיו פרטי הכניסה הבאים:
- Client ID: מזהה ייחודי שהאפליקציה משתמשת בו כדי לבקש אסימון גישה מסוג OAuth 2.0.
- כתובת אימייל: כתובת האימייל שנוצרה לחשבון השירות, בפורמט הבא: "account_name@project_name.google.com.iam.gserviceaccount.com".
- טביעות אצבע לאישור: המזהה של המפתח הפרטי שהורדתם.

מידע נוסף זמין במאמר שימוש ב-OAuth 2.0 לאפליקציות משרת לשרת.

שלב 4: מעניקים לחשבון השירות גישה לנתונים שלכם ב-Hotel Center

השלב האחרון הוא לתת לחשבון השירות החדש גישה ל-Hotel Center. חשבון השירות מזוהה באמצעות כתובת האימייל שיצרתם בשלב הקודם. כדי לתת גישה לחשבון הזה, משתמשים בהגדרות השיתוף של Hotel Center.

כדי לתת לחשבון שירות גישה לנתונים שלכם ב-Hotel Center:

אם אין לכם גישה מתאימה כדי להוסיף משתמשים לחשבון, תוכלו לפנות לצוות של 'Google בתי מלון' באמצעות הטופס ליצירת קשר ולבקש מאיתנו להגדיר בעלות על החשבון. אפשר לבקש שליחה של הודעת אימייל אחת או יותר לבעלים. מידע נוסף על הגישה ל-Hotel Center זמין במאמר קישור בין Hotel Center לבין Google Ads.

בחלון דפדפן חדש, פותחים את Hotel Center.
בבאנר של Hotel Center by Google, לוחצים על סמל הוספת המשתמש כדי לפתוח את תיבת הדו-שיח של השיתוף.
בשדה Add more people (הוספת אנשים נוספים), מזינים את כתובת האימייל של חשבון השירות שרוצים להוסיף ל-Hotel Center.
משאירים את האפשרות שליחת הודעה לאנשים מסומנת.
בתפריט הנפתח, בוחרים באפשרות ניהול.
לוחצים על הלחצן הזמנה.
אחרי שתוסיפו משתמשים ל-Hotel Center, הגישה ל-API בחשבון השירות אמורה להיות מופעלת תוך כ-24 שעות.

אחרי ש-Google תודיע לכם שהגישה ל-API מופעלת בחשבון השירות שלכם, תוכלו להתחיל לגשת ל-API באמצעות OAuth.

שימוש ב-OAuth 2.0

כדי לגשת ל-API, האפליקציה שלכם צריכה להזדהות בפני Google באמצעות כתובת האימייל והמפתח הפרטי שנוצרו על ידי חשבון השירות. מנגנון האימות של Google מחליף את המפתח הזה באסימון גישה מסוג OAuth 2.0 שמעבירים בכותרת Authorization בקריאות ל-API של האפליקציה.

אסימוני גישה (שנקראים גם אסימונים למוכ"ז) הם חלק מתקן OAuth 2.0. התחביר לציון אסימון גישה בכותרת HTTP הוא:

Authorization: Bearer *oauth2_access_token*

בדוגמה הבאה מוצגות כותרות HTTP לדוגמה של בקשה שניגשת ל-Reports 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

כדי ליצור אסימון גישה, יוצרים אפליקציה בכל שפה. הדוגמה הבאה יוצרת את האסימון ב-Python. לאחר מכן אפשר להשתמש באסימון הזה בכותרות 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>

כשמפתחים את האפליקציה, חשוב לפעול לפי השיטות המומלצות לשימוש מאובטח במפתחות API.

הסקריפט לדוגמה של Python מפיק את אסימון ה-Bearer של הכותרת Authorization, כמו בדוגמה הבאה:

$ python sample.py
Authorization: Bearer ya29.42424242sample_420icu8122KSvoh4T42cRoG3rW1lc0Q
$

שימוש בערך של האסימון בבקשות שלך. הוא תקף למשך שעה אחרי שיוצרים אותו.

פתרון בעיות

נתקלת בבעיות? בדיקה מהירה של הפריטים הבאים עשויה לפתור את הבעיה.

האם יצרתם פרויקט ב-Google Developer Console?
האם מצאת את Travel Partner API והפעלת אותה?
הורדתם קובץ .p12, שהוא מפתח פרטי אחרי שלחצתם על Create client ID ובחרתם באפשרות Service account?
האם קיבלת כתובת אימייל של מזהה לקוח של חשבון שירות מתוך טופס: nnnnnnn@app_name.google.com.iam.gserviceaccount.com?
האם שיתפתם את חשבון Hotel Ads Center עם חשבון השירות על ידי לחיצה על הלחצן Share this account?
האם שלחתם את כתובת האימייל של חשבון השירות ואת מזהה השותף למנהל החשבונות הטכני (TAM)?
האם הקריאות של Travel Partner API מעבירות אסימון שהתקבל לאחרונה בכותרת Authorization?
האם האסימון 'מנפיק' של הכותרת Authorization נוצר לפני יותר משעה?

בטבלה הבאה מפורטות כמה שגיאות נפוצות ופתרונות אפשריים:

שגיאה	תיאור
Invalid credentials	יכולים להיות לכך כמה סיבות. אם תיתקלו בשגיאה הזו, בדקו את הדברים הבאים: ציינת כותרת `Authorization` עם אסימון למוכ"ז חוקי. האסימון למוכ"ז נוצר לפני פחות משעה. אסימון תקף לשעה אחת בלבד. ציינת את שם השותף הנכון (עם הפרמטר `partner` של מחרוזת השאילתה). הערך הזה הוא מזהה השותף הייחודי, ולא שם השותף שמופיע ב-Hotel Ads Center. אם לא יודעים את מזהה השותף, אפשר לפנות למנהל החשבונות הטכני (TAM).
Not found	סביר להניח שהפורמט של נקודת הקצה שגוי. צריך לוודא כששולחים בקשת `GET` ושכתובת ה-URL של הבקשה תקינה (היא תואמת לתחביר של ה-API שאליו ניסית לגשת).
Invalid string value	חלק אחד או יותר של נקודת הקצה מכילים תחביר לא חוקי. לדוגמה, יכול להיות שהאיות של חלק מהנתיב שגוי. צריך לוודא שהשתמשת בקווים תחתונים, באותיות רישיות ובניסוח הנכון בכל הנתיב.
Unsupported output format	השגיאה הזו מופיעה בדרך כלל כשמשתמשים ב-Reports API. צריך לציין את `"alt=csv"` בכתובת ה-URL של הבקשה ל-`GET`. ה-Reports API לא תומך ב-JSON.
AccessTokenRefreshError/Invalid grant	כשמריצים את אפליקציית Python לדוגמה, יכול להיות שהשגיאה הזו נגרמת מהסיבות הבאות: כתובת האימייל של חשבון השירות שגויה. צריך לבדוק את חשבון האימייל ב-Google Developer Console ולוודא שיש לו הרשאה לגשת ל-API. לכתובת האימייל אין גישה ל-API. מוודאים שלכתובת האימייל הזו יש הרשאה לגשת לנתוני המלונות שלכם (משותף דרך Hotel Center). קובץ המפתח הוא לא הקובץ הנכון לחשבון השירות. משתמשים ב-DevConsole כדי להוריד אישור `.p12` חדש, ומוודאים שאפליקציית Python מפנה אל האישור הנכון.
HotelAdsAPIConnection object has no attribute credentials	כשמריצים את אפליקציית Python לדוגמה, הנתיב לקובץ `.p12` שגוי.
Invalid scope	כשמריצים את אפליקציית Python לדוגמה, היקף ההרשאות של ה-API חייב להיות `https://www.googleapis.com/auth/travelpartner`.
Forbidden	מספר החשבון שבו השתמשת הוא חשבון שאין לך הרשאה לגשת אליו. אם הוגדרת כבעלים של חשבון משנה, יכול להיות שלא תהיה לך גישה למספר של חשבון ההורה או של החשבון הבסיסי (root).