הגדרה בסיסית

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

הפעלת ממשקי ה-API

יש שמונה ממשקי API שמשויכים ל'פרופיל העסק ב-Google' וצריך להפעיל אותם ב-Google API Console:

  • Google My Business API
  • My Business Account Management API
  • ממשק API של My Business Lodging
  • ממשק ה-API של My Business Place Actions
  • My Business Notifications API
  • ממשק API לאימות העסק שלי
  • ממשק ה-API של פרטי העסק שלי
  • ממשק ה-API לשאלות ותשובות של העסק שלי

הפעלת API

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

כדי להפעיל API לפרויקט:

  1. פותחים את ספריית ה-API ב-Google API Console. אם מתבקשים לבחור פרויקט, בוחרים פרויקט חדש או יוצרים פרויקט חדש. בספריית ה-API מפורטים כל ממשקי ה-API הזמינים, מקובצים לפי משפחת המוצרים ופופולריות.
  2. אם ממשק ה-API שאתם רוצים להפעיל לא מופיע ברשימה, תוכלו להשתמש בחיפוש כדי למצוא אותו.
  3. בוחרים את ממשק ה-API שרוצים להפעיל ולוחצים על הלחצן Enable.
  4. אם מתבקשים, מפעילים את החיוב.
  5. אם מתבקשים, מאשרים את התנאים וההגבלות של ה-API.

אם אתם משתמשים ב-Google Workspace, עליכם לוודא שפרופיל העסק ב-Google מופעל בחשבון שלכם בארגון ב-Google Workspace. אם פרופיל העסק ב-Google מושבת לחשבון שלכם בארגון Google Workspace, תוצג לכם ההודעה 'שגיאה 403 - PERMISSION DENIED' כשמשתמשים בממשקי ה-API של GBP.

בקשת מזהה לקוח ב-OAuth 2.0

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

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

כדי ליצור את פרטי הכניסה ב-OAuth 2.0, נכנסים לקטע Credentials (פרטי כניסה) ב-Google API Console, אם עדיין לא עשיתם זאת. כדי ליצור את פרטי הכניסה, לוחצים על Create credentials > OAuth client ID. אחרי שיוצרים את פרטי הכניסה, מזהה הלקוח יופיע בדף Credentials. לוחצים על מזהה הלקוח כדי לקבל פרטים כמו סוד לקוח, מזהי URI להפניה אוטומטית, כתובות מקורות של JavaScript וכתובת אימייל.

העקרונות הבסיסיים של REST

יש שתי דרכים להפעיל את ממשקי ה-API:

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

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

המונח REST הוא קיצור של Representational State Transfer. בהקשר של ממשקי ה-API של Google, REST מתייחס לשימוש בפעלים של HTTP כדי לאחזר ולשנות ייצוגים של נתונים ש-Google מאחסנת.

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

בממשקי RESTful API של Google, הלקוח מציין פעולה עם פועל של HTTP, כמו GET, POST, PUT או DELETE. הלקוח מציין משאב לפי מזהה משאב אחיד (URI) ייחודי וגלובלי בפורמט הבא:

https://apiName.googleapis.com/apiVersion/resourcePath?parameters

מאחר שלכל משאבי ה-API יש מזהה URI ייחודי שאפשר לגשת אליו באמצעות HTTP, ב-REST אפשר לשמור נתונים במטמון והוא מותאם לעבודה עם התשתית המבוזרת של האינטרנט.

תוכלו להיעזר בהגדרות השיטה במסמכי התיעוד של תקני HTTP 1.1. הם כוללים מפרטים של GET, POST, PUT ו- DELETE.

REST בממשקי ה-API של פרופיל העסק

הפעולות של ממשקי ה-API של פרופיל העסק ממופות ישירות לפעלים מסוג REST HTTP.

הפורמט הספציפי של ממשקי ה-API של פרופיל העסק מוצג ב-URI הבא:

https://apiName.googleapis.com/apiVersion/resourcePath?parameters

הקבוצה המלאה של מזהי URI שמשמשים לכל פעולה נתמכת בממשקי ה-API מופיעה במסמכי התיעוד של הפנייה של ממשקי ה-API של 'פרופיל העסק ב-Google'.

נתיבי המשאבים משתנים בהתאם לנקודת הקצה.

לדוגמה, נתיב המשאב לחשבון מופיע בדוגמה הבאה:

accounts/accountId

נתיב המשאב של מיקום מסוים מופיע בצורה הבאה:

locations/locationId

העקרונות הבסיסיים של JSON

ממשקי ה-API של פרופיל העסק מחזירים נתונים בפורמט JSON.

JavaScript Object Notation (JSON) הוא פורמט נתונים נפוץ ובלתי תלוי בשפה, שבו מבני נתונים שרירותיים מיוצגים באמצעות טקסט פשוט. למידע נוסף: json.org.

שליחה של בקשת HTTP פשוטה

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

  1. נכנסים אל Google API Console ופותחים את הפרויקט. אם אין לך מזהה לקוח OAuth לאפליקציות אינטרנט, עליך ליצור מזהה כזה עכשיו:
    1. ברשימה הנפתחת יצירת פרטי כניסה, בוחרים באפשרות מזהה לקוח OAuth.
    2. בקטע Application type (סוג אפליקציה), לוחצים על Web Application (אפליקציית אינטרנט).

    3. מוסיפים את הקוד הבא כ-URI חוקי להפניה אוטומטית:

       https://developers.google.com/oauthplayground
    4. לוחצים על יצירה.
  2. מעתיקים את מזהה הלקוח ללוח.
  3. נכנסים למגרש המשחקים של OAuth 2.0.
  4. לחץ על סמל גלגל השיניים כדי לפתוח את אפשרויות התצורה ולבצע את השינויים הבאים:
    1. מגדירים את תהליך OAuth לצד הלקוח.
    2. בוחרים באפשרות שימוש בפרטי הכניסה שלך ב-OAuth.
    3. מדביקים את מזהה הלקוח ב-OAuth.
  5. סגירת אפשרויות התצורה.

  6. בקטע 'שלב 1 – בחירה והרשאה של ממשקי API', מדביקים את ההיקף הבא של ממשקי ה-API של פרופיל העסק בשדה הזנת היקפים משלך:

    https://www.googleapis.com/auth/business.manage
  7. לוחצים על Authorize APIs.
  8. לוחצים על אישור כשמופיעה בקשה לכך.

  9. בקטע 'שלב 2 - הגדרת בקשה ל-API' מדביקים את ה-URI הבא בשדה URI של בקשה: 

    https://mybusinessaccountmanagement.googleapis.com/v1/accounts
  10. לוחצים על שליחת הבקשה. התגובה צריכה להציג את הסטטוס 200 OK.

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

ספריות לקוח

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

כדי להוריד ספריות לקוח, אפשר לעיין בספריות.