אימות API

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

הגדרת OAuth 2.0

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

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

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

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

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

  1. יצירת פרויקט חדש ב-Google Developers Console (DevConsole)

  2. הפעלת הגישה אל Travel Partner API בפרויקט החדש

  3. איך יוצרים חשבון שירות ופרטי הכניסה שלו

  4. איך נותנים לחשבון השירות גישה לנתוני המלון

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

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

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

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

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

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

  1. נכנסים לחשבון Gmail/Google.

  2. פותחים את Google Developer Console. אם זה הפרויקט הראשון שלכם, בתצוגה הראשית מופיע לחצן CREATE PROJECT:

    fig1

  3. לוחצים על הלחצן CREATE PROJECT. ב-DevConsole מופיעה תיבת הדו-שיח New Project:

    fig2

    מזינים שם ידידותי לפרויקט החדש בשדה הקלט Project name. מתחת לשדה, ה-DevConsole יוצר מזהה פרויקט בשבילכם, כדי להבטיח שהמזהה יהיה ייחודי בכל הפרויקטים. לדוגמה, אם מזינים "My New Project", DevConsole מקצה מזהה כמו my-new-project-266022.

  4. לוחצים על הלחצן יצירה כדי ליצור את הפרויקט החדש.

  5. משתמשים בתפריט הניווט כדי לבחור באפשרות APIs & Services (ממשקי API ושירותים) > Dashboard (מרכז בקרה).

    fig3

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

    fig4

למידע נוסף, קראו את המאמר ניהול פרויקטים ב-Developer Console.

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

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

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

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

  1. עוברים לתצוגת מרכז השליטה של הפרויקט כפי שמתואר למעלה.

  2. לוחצים על Enable APIs and services. הלחיצה תפתח את דף הפתיחה של ספריית ה-API.

  3. מתחילים להקליד Travel Partner API בשדה החיפוש. Google API Console מציג רשימה של ממשקי API שתואמים את הטקסט שאתה מקליד.

  4. לוחצים על Travel Partner API בטבלה של ממשקי ה-API התואמים. ב-DevConsole מוצג תיאור של ה-API.

  5. כדי להפעיל את ה-API בפרויקט, לוחצים על הלחצן Enable API.

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

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

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

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

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

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

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

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

  2. לוחצים על הקישור Credentials in APIs and services.

  3. לוחצים על Create credentials ובתפריט הנפתח בוחרים באפשרות Service account key. תופיע התצוגה יצירת מפתח של חשבון שירות.

  4. בתפריט הנפתח Service account, בוחרים באפשרות New service account (חשבון שירות חדש).

  5. צריך להזין את השם של חשבון השירות ואת מספר חשבון השירות.

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

  6. בוחרים את סוג המפתח P12, כמו שמוצג בהמשך. חובה לציין את P12.

    fig5

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

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

    בסיום יצירת המפתחות תוצג ב-DevConsole ההודעה הבאה:

    fig6

  8. לוחצים על הלחצן הבנתי. ייפתחו על ידי 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.

  1. פותחים את Hotel Center בחלון דפדפן חדש. fig7

  2. כדי לפתוח את תיבת הדו-שיח של השיתוף, בבאנר של Hotel Center by Google לוחצים על סמל הוספת המשתמש.

    fig8

  3. בשדה Add more people (הוספת אנשים), מזינים את כתובת האימייל של חשבון השירות שרוצים להוסיף ל-Hotel Center.

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

  5. בתפריט הנפתח, בוחרים באפשרות Manage (ניהול).

  6. לוחצים על הלחצן שליחת הזמנה.

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

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

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

פתרון בעיות

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

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

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

שגיאה התיאור
Invalid credentials יכולות להיות לכך כמה סיבות. אם נתקלתם בשגיאה הזו, עליכם לבדוק את הפרטים הבאים:
  • ציינת כותרת Authorization עם אסימון למוכ"ז חוקי.
  • האסימון למוכ"ז הוא לפני פחות משעה. אסימון תקף רק לשעה אחת.
  • ציינת את שם השותף הנכון (באמצעות הפרמטר של מחרוזת השאילתה partner). הערך הוא מזהה השותף הייחודי שלכם, ולא שם השותף שמופיע ב-Hotel Ads Center. אם אתם לא יודעים מה מזהה השותף, פנו למנהל החשבונות הטכני.
Not found סביר להניח שהפורמט של נקודת הקצה (endpoint) שגוי. צריך לוודא ששולחים בקשת 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 מספר החשבון שלך הוא מספר שאין לך הרשאה לגשת אליו. אם יש לך חשבון משנה, ייתכן שלא תהיה לך גישה למספר החשבון הראשי או לחשבון הבסיס.