כדי להמשיך, צריך לוודא שהשלמת את השלבים המפורטים בקטע דרישות מוקדמות ושאישרנו את הגישה של הפרויקט שלך לממשקי ה-API של'פרופיל העסק ב-Google'.
הפעלת ממשקי ה-API
יש שמונה ממשקי API שמשויכים לפרופיל העסק, וצריך להפעיל אותם במסוף Google API:
- Google My Business API
- My Business Account Management API
- My Business Lodging API
- My Business Place Actions API
- My Business Notifications API
- My Business Verifications API
- My Business Business Information API
- My Business Q&A API
הפעלת ממשק API
אם השלמתם את כל הדרישות המוקדמות וקיבלתם גישה ל-API, אבל עדיין לא הצלחתם להשתמש במקשי הקיצור שסופקו, תוכלו להפעיל את ה-API באופן ידני באמצעות השלבים הבאים.
כדי להפעיל ממשק API בפרויקט:
- פותחים את API Library במסוף Google API. אם מופיעה בקשה, בוחרים פרויקט או יוצרים פרויקט חדש. בספריית ה-API מפורטים כל ממשקי ה-API הזמינים, שמקובצים לפי משפחת מוצרים ופופולריות.
- אם ה-API שרוצים להפעיל לא מופיע ברשימה, מחפשים אותו.
- בוחרים את ה-API שרוצים להפעיל ולוחצים על הלחצן Enable.
- אם תופיע בקשה, מפעילים את החיוב.
- אם מופיעה בקשה, מאשרים את התנאים וההגבלות של ה-API.
אם אתם משתמשים ב-Google Workspace, עליכם לוודא שפרופיל העסק ב-Google מופעל בחשבון שלכם בארגון ב-Google Workspace. אם פרופיל העסק ב-Google מושבת בחשבון שלכם בארגון ב-Google Workspace, תופיע השגיאה 'error 403 - PERMISSION DENIED' (שגיאה 403 – PERMISSION DENIED) כשתנסו להשתמש בממשקי ה-API של GBP.
בקשה למזהה לקוח ב-OAuth 2.0
מכיוון שהאפליקציה שלכם ניגשת לנתונים מוגנים ולא ציבוריים, אתם צריכים מזהה לקוח ב-OAuth 2.0. כך האפליקציה יכולה לבקש הרשאה לגשת לנתוני המיקום של הארגון בשם המשתמשים באפליקציה.
האפליקציה שלכם חייבת לשלוח אסימון OAuth 2.0 עם כל בקשה ל-Business Profile API שמאפשרת גישה לנתונים פרטיים של משתמשים.
אם עדיין לא עשיתם זאת, עוברים לקטע Credentials (פרטי כניסה) במסוף Google API ולוחצים על Create credentials (יצירת פרטי כניסה) > OAuth client ID (מזהה לקוח OAuth) כדי ליצור את פרטי הכניסה ל-OAuth 2.0. אחרי שתיצרו את פרטי הכניסה, תוכלו לראות את מזהה הלקוח בדף Credentials. לוחצים על מזהה הלקוח כדי לראות פרטים כמו סוד הלקוח, כתובות URI להפניה אוטומטית, כתובת המקור של JavaScript וכתובת האימייל.
העקרונות הבסיסיים של REST
יש שתי דרכים להפעיל את ממשקי ה-API:
- שליחה של בקשת HTTP וניתוח התגובות.
- שימוש בספריות לקוח.
אם תחליטו לא להשתמש בספריות לקוח, תצטרכו להכיר את העקרונות הבסיסיים של REST.
REST הוא סגנון של ארכיטקטורת תוכנה שמאפשר גישה נוחה ועקבית לשליחת בקשות ולשינוי של נתונים.
המונח REST הוא קיצור של Representational State Transfer. בהקשר של Google APIs, REST מתייחס לשימוש בפעלים של HTTP כדי לאחזר ולשנות ייצוגים של נתונים ש-Google מאחסנת.
מערכת מבוססת-REST שומרת משאבים במאגר נתונים. לקוח שולח בקשה לשרת לבצע פעולה מסוימת, כמו ליצור, לאחזר, לעדכן או למחוק משאב, והשרת מבצע את הפעולה ושולח תשובה. התגובה הזו היא לרוב ייצוג של המשאב שצוין.
בממשקי ה-RESTful API של Google, הלקוח מציין פעולה באמצעות פועל של HTTP, כמו GET, POST, PUT או DELETE. הלקוח מציין משאב לפי מזהה משאבים אחיד (URI) ייחודי גלובלי, באופן הבא:
https://apiName.googleapis.com/apiVersion/resourcePath?parameters
מכיוון שלכל משאבי ה-API יש מזהה URI ייחודי שאפשר לגשת אליו באמצעות HTTP, ב-REST אפשר לשמור נתונים במטמון והוא מותאם לעבודה עם התשתית המבוזרת של האינטרנט.
תוכלו להיעזר בהגדרות ה-method במשאבי העזרה של תקני HTTP 1.1. הם כוללים מפרטים של GET, POST, PUT ו-DELETE.
REST בממשקי Business Profile API
הפעולות של ממשקי Business Profile API ממופות ישירות לפעלים מסוג REST HTTP.
הפורמט הספציפי של ממשקי ה-API של פרופיל העסק מוצג במזהה ה-URI הבא:
https://apiName.googleapis.com/apiVersion/resourcePath?parameters
הקבוצה המלאה של מזהי ה-URI שמשמשים לכל פעולה נתמכת בממשקי ה-API מופיעה במסמכי העזרה של ממשקי Business Profile API.
נתיבי המשאבים משתנים בהתאם לנקודת הקצה.
לדוגמה, נתיב המשאב לחשבון מופיע כמו בדוגמה הבאה:
accounts/accountId
נתיב המשאב של מיקום מופיע בפורמט הבא:
locations/locationId
העקרונות הבסיסיים של JSON
ממשקי Business Profile API מחזירים נתונים בפורמט JSON.
JavaScript Object Notation (JSON) הוא פורמט נתונים נפוץ ובלתי תלוי בשפה, שבו מבני נתונים שרירותיים מיוצגים באמצעות טקסט פשוט. למידע נוסף: json.org.
שימוש ב-Oauth Playground כדי לשלוח בקשת HTTP פשוטה
אתם יכולים להשתמש ב-OAuth 2.0 Playground כדי להתנסות בממשקי Business Profile API. מאחר שממשקי ה-API של 'פרופיל העסק ב-Google' הם לא ממשקי API ציבוריים, צריך לבצע כמה שלבים נוספים כדי להשתמש בהם ב-Playground. כדי להמשיך, נדרש מזהה לקוח של אפליקציית אינטרנט.
- נכנסים ל-Google API Console ופותחים את הפרויקט. אם אין לכם מזהה לקוח OAuth לאפליקציות אינטרנט, צריך ליצור אותו עכשיו:
- ברשימה הנפתחת Create credentials בוחרים באפשרות OAuth client ID.
- בקטע Application type, לוחצים על Web Application.
מוסיפים את ה-URI הבא כ-URI חוקי להפניה לכתובת אחרת:
https://developers.google.com/oauthplayground
- לוחצים על יצירה.
- מעתיקים את מזהה הלקוח ללוח.
- עוברים אל OAuth 2.0 Playground.
- לוחצים על סמל גלגל השיניים כדי לפתוח את אפשרויות ההגדרה ומבצעים את השינויים הבאים:
- מגדירים את תהליך OAuth ל-צד הלקוח.
- בוחרים באפשרות שימוש בפרטי הכניסה שלכם ב-OAuth.
- מדביקים את מזהה הלקוח ב-OAuth.
- סוגרים את אפשרויות ההגדרה.
בקטע 'שלב 1 – בחירת ממשקי API והענקת הרשאה להם', מדביקים את ההיקף הבא של ממשקי Business Profile API בשדה הזנת היקפים משלכם:
https://www.googleapis.com/auth/business.manage
- לוחצים על Authorize APIs.
- לוחצים על אישור כשמופיעה הבקשה.
-
בקטע 'שלב 2 – הגדרת בקשה ל-API', מדביקים את מזהה ה-URI הבא בשדה Request URI:
https://mybusinessaccountmanagement.googleapis.com/v1/accounts
- לוחצים על שליחת הבקשה. התשובה אמורה לכלול את הסטטוס
200 OK.
מידע נוסף על שליחת בקשות מסוגים שונים זמין במאמר העזרה בנושא ממשקי Business Profile API.
ספריות לקוח
ספריות הלקוח של Business Profile API תומכות בפונקציונליות של Business Profile API. הם מספקים פונקציונליות שקיימת בכל ממשקי Google API, כמו תעבורת HTTP, טיפול בשגיאות, אימות וניתוח JSON.
במאמר ספריות מוסבר איך מורידים ספריות לקוח.