1. שימוש בממשקי API של Google Workspace
ב-codelab הזה נלמד איך להשתמש בממשקי API של Google Workspace (לשעבר G Suite) בארכיטקטורת REST שמבוססים על HTTP. הדוגמה תבוצע ב-Python כדי לשמור על תמציתיות וזמינות, אבל אפשר גם לבחור להשתמש בשפת הפיתוח המועדפת עליכם. תקבלו הסברים על נושאי מבוא כמו שימוש ב-Developer Console ליצירה ולניהול של פרויקטים, קבלת פרטי כניסה להרשאה והתקנה של ספריות לקוח של API. אחרי שסיימתם עם הפורמליות, תכתבו אפליקציה להצגת 100 הקבצים והתיקיות הראשונים ב-Google Drive באמצעות ה-API שלו.
מה תלמדו
- יצירת פרויקט באמצעות Google/Cloud Developers Console
- השגת פרטי כניסה לאפליקציית OAuth2 ושימוש בהם באפליקציה
- מידע נוסף על שימוש בספריות הלקוח של Google APIs
- כתיבת אפליקציות באמצעות ממשקי API של Google ו-Google Workspace
- קבלת מידע על קבצים ותיקיות באמצעות Google Drive API
הדרישות
- גישה לאינטרנט ולדפדפן אינטרנט
- חשבון Google (יכול להיות שיהיה צורך באישור אדמין לחשבונות Google Workspace)
- היכרות עם מערכות שתואמות ל-POSIX, כמו Linux ו-Mac OS X
- היכולת ליצור קובצי מקור באמצעות עורך קוד או פקודות Shell.
- מיומנויות בסיסיות ב-Python (גרסה 2 או 3), אבל אפשר להשתמש בכל שפה נתמכת
- חלק מהקבצים או התיקיות ב-Google Drive
2. סקר
איך תשתמשו במדריך הזה של Codelab?
איך היית מדרג את חוויית השימוש שלך בכלי הפיתוח ובממשקי ה-API של Google Workspace?
3. סקירה כללית
ב-codelab הזה תלמדו איך:
- הורדת ספריית הלקוח של Google APIs ל-Python
- יצירת פרויקט חדש ב-Google/Cloud Developers Console
- קבלת פרטי הכניסה הנדרשים לאפליקציה
- שימוש בפרטי הכניסה כדי לגשת אל Google Drive API
אם אתם לא רוצים להשתמש ב-Python, אתם יכולים להטמיע את ה-codelab בכלי הפיתוח המועדף עליכם (ספריות לקוח של שפות נתמכות זמינות כאן) ולהתייחס לדוגמאות של Python כאל פסאודו-קוד (ניתן להרצה).
4. אישור סביבת Python
ב-codelab הזה צריך להשתמש בשפת Python (אבל ספריות הלקוח של Google APIs תומכות בשפות רבות, אז אתם יכולים ליצור משהו מקביל בכלי הפיתוח המועדף עליכם ולהשתמש ב-Python כפסאודו-קוד). בפרט, ה-codelab הזה תומך ב-Python 2 וב-Python 3, אבל מומלץ לעבור ל-3.x בהקדם האפשרי.
Cloud Shell הוא כלי נוח שזמין למשתמשים ישירות מ-Cloud Console, ולא נדרשת סביבת פיתוח מקומית. לכן אפשר לבצע את ההדרכה הזו באופן מלא בענן באמצעות דפדפן אינטרנט. Cloud Shell שימושי במיוחד אם אתם מפתחים או מתכננים להמשיך לפתח באמצעות מוצרים וממשקי API של GCP. במקרה הספציפי של ה-codelab הזה, שתי הגרסאות של Python כבר מותקנות מראש ב-Cloud Shell.
ב-Cloud Shell מותקן גם IPython… זהו מתורגמן אינטראקטיבי של Python ברמה גבוהה יותר, ואנחנו ממליצים עליו, במיוחד אם אתם חלק מקהילת מדע הנתונים או למידת המכונה. אם כן, IPython הוא המפרש שמוגדר כברירת מחדל עבור Jupyter Notebooks וגם עבור Colab, Jupyter Notebooks שמתארחים בצוות המחקר של Google.
IPython מעדיף תחילה מפרש של Python 3, אבל אם גרסה 3.x לא זמינה, הוא חוזר ל-Python 2. אפשר לגשת ל-IPython מ-Cloud Shell, אבל אפשר גם להתקין אותו בסביבת פיתוח מקומית. יוצאים באמצעות ^D (Ctrl-d) ומאשרים את ההצעה ליציאה. פלט לדוגמה של הפקודה ipython ייראה כך:
$ ipython Python 3.7.3 (default, Mar 4 2020, 23:11:43) Type 'copyright', 'credits' or 'license' for more information IPython 7.13.0 -- An enhanced Interactive Python. Type '?' for help. In [1]:
אם אתם לא מעדיפים את IPython, אפשר להשתמש במתורגמן אינטראקטיבי רגיל של Python (ב-Cloud Shell או בסביבת הפיתוח המקומית). גם במקרה הזה, יוצאים באמצעות ^D:
$ python Python 2.7.13 (default, Sep 26 2018, 18:42:22) [GCC 6.3.0 20170516] on linux2 Type "help", "copyright", "credits" or "license" for more information. >>> $ python3 Python 3.7.3 (default, Mar 10 2020, 02:33:39) [GCC 6.3.0 20170516] on linux Type "help", "copyright", "credits" or "license" for more information. >>>
בנוסף, מניחים ב-Codelab שמותקן אצלכם pip (כלי לניהול חבילות Python ופתרון יחסי תלות). הוא מגיע בחבילה עם גרסאות 2.7.9 ומעלה או 3.4 ומעלה. אם יש לכם גרסה ישנה יותר של Python, תוכלו לעיין במדריך הזה לקבלת הוראות התקנה. יכול להיות שתצטרכו הרשאות sudo או הרשאות סופר-משתמש, אבל בדרך כלל זה לא המצב. אפשר גם להשתמש ב-pip2 או ב-pip3 באופן מפורש כדי להפעיל את pip לגרסאות ספציפיות של Python.
בהמשך ה-codelab נניח שאתם משתמשים ב-Python 3. אם יש הבדלים משמעותיים בין Python 2 ל-Python 3.x, נספק הוראות ספציפיות ל-Python 2.
*יצירה ושימוש בסביבות וירטואליות
הקטע הזה הוא אופציונלי, והוא נדרש רק למי שצריך להשתמש בסביבה וירטואלית בשביל ה-codelab הזה (כמו שכתוב באזהרה בסרגל הצד למעלה). אם במחשב שלכם מותקן רק Python 3, אתם יכולים פשוט להריץ את הפקודה הזו כדי ליצור סביבה וירטואלית בשם my_env (אפשר לבחור שם אחר אם רוצים):
virtualenv my_env
עם זאת, אם במחשב שלכם מותקנות גם Python 2 וגם Python 3, מומלץ להתקין סביבה וירטואלית של Python 3. אפשר לעשות זאת באמצעות -p flag כך:
virtualenv -p python3 my_env
נכנסים לסביבה הווירטואלית החדשה שיצרתם על ידי 'הפעלה' שלה באופן הבא:
source my_env/bin/activate
כדי לוודא שאתם בסביבה, שימו לב ששם הסביבה מופיע לפני שורת הפקודה של המעטפת, כלומר:
(my_env) $
עכשיו אמורה להיות לכם אפשרות pip install את כל החבילות הנדרשות, להריץ קוד בסביבה הזו וכו'. יתרון נוסף הוא שאם תסתבכו ותגיעו למצב שבו התקנת Python שלכם פגומה וכו', תוכלו למחוק את כל הסביבה הזו בלי להשפיע על שאר המערכת.
5. התקנה של ספריית הלקוח של Google APIs ל-Python
בסדנת הקוד הזו נדרש שימוש בספריית הלקוח של Google APIs ל-Python, כך שתהליך ההתקנה פשוט, או שאולי לא תצטרכו לעשות כלום.
מומלץ להשתמש ב-Cloud Shell כדי להקל על התהליך. אפשר להשלים את כל ההדרכה מדפדפן אינטרנט בענן. סיבה נוספת להשתמש ב-Cloud Shell היא שרבים מכלי הפיתוח הפופולריים והספריות הנדרשות מותקנים מראש.
*התקנה של ספריות לקוח
(אופציונלי) אפשר לדלג על השלב הזה אם אתם משתמשים ב-Cloud Shell או בסביבה מקומית שבה כבר התקנתם את ספריות הלקוח. צריך לעשות את זה רק אם אתם מפתחים באופן מקומי ולא התקנתם את הכלים האלה (או שאתם לא בטוחים שהתקנתם אותם). הדרך הכי קלה היא להשתמש ב-pip (או ב-pip3) כדי לבצע את ההתקנה (כולל עדכון של pip עצמו אם צריך):
pip install -U pip google-api-python-client oauth2client
אישור ההתקנה
הפקודה הזו מתקינה את ספריית הלקוח וגם את כל החבילות שהיא תלויה בהן. בין אם אתם משתמשים ב-Cloud Shell או בסביבה משלכם, כדי לוודא שספריית הלקוח מותקנת, מייבאים את החבילות הנדרשות ומוודאים שאין שגיאות ייבוא (או פלט):
python3 -c "import googleapiclient, httplib2, oauth2client"
אם משתמשים ב-Python 2 (מ-Cloud Shell), תוצג אזהרה שהתמיכה בה הוצאה משימוש:
******************************************************************************* Python 2 is deprecated. Upgrade to Python 3 as soon as possible. See https://cloud.google.com/python/docs/python2-sunset To suppress this warning, create an empty ~/.cloudshell/no-python-warning file. The command will automatically proceed in seconds or on any key. *******************************************************************************
אחרי שתצליחו להריץ את פקודת הייבוא הזו (ללא שגיאות או פלט), תוכלו להתחיל לתקשר עם Google APIs!
סיכום
ב-Codelab הזה מניחים שאתם חדשים בשימוש בממשקי API של Google ו-Google Workspace. אם כבר יש לכם ניסיון ביצירת פרויקטים וביצירת הרשאות משתמש מסוג 'מזהי לקוח של OAuth'. אם כן, יוצרים פרויקט חדש או משתמשים בפרויקט קיים, יוצרים מזהה לקוח OAuth חדש או משתמשים במזהה קיים, מדלגים על שני המודולים הבאים ועוברים ישירות אל 'הצגת הקבצים והתיקיות באפליקציית Drive' או מדלגים אל 'שימוש מתקדם במסוף המפתחים' כדי לעיין בשלבים האלה עם פחות הנחיות.
6. ציון פרויקט ב-מסוף Cloud
כדי להשתמש בממשקי API של Google באפליקציה, צריך פרויקט. הם מנוהלים ב-Google Cloud Developers Console, או בקיצור, devconsole. ב-Codelab הזה נשתמש רק ב-Google Drive API, ולכן יש לנו קישור חד-פעמי לכניסה (למטה בשלב 1) ש:
- מעביר אתכם אל מסוף הפיתוח
- המדריך כולל הסברים על יצירת פרויקט חדש (או בחירת פרויקט קיים), ועל
- הפעלת Drive API באופן אוטומטי
קדימה!
- עוברים אל console.developers.google.com/start/api?id=drive ונכנסים לחשבון Google.
- אם עדיין אין לכם פרויקטים, יוצג לכם המסך הזה שבו תצטרכו לאשר את התנאים וההגבלות של Google APIs:
אחרי שתאשרו את התנאים, ייצור פרויקט חדש בשם My Project וממשק Drive API יופעל באופן אוטומטי. 3. אם כבר יצרתם פרויקט (למשל, ב-codelab הקודם), יוצג המסך הזה: 
כשלוחצים על התפריט הנפתח Create a project (יצירת פרויקט), אפשר לבחור פרויקט קיים או ליצור פרויקט חדש. 
אחרי שתבחרו פרויקט (חדש או קיים), Drive API יופעל בשבילכם באופן אוטומטי. 4. כדי לדעת ש-Drive API הופעל, צריך לחפש את האישור הזה: 
5. לוחצים על Go to credentials (מעבר לפרטי הכניסה) כדי לעבור לשלב הבא.
7. *הרשאה לבקשות API (הרשאת משתמש)
אפשר לדלג על הקטע הזה אם כבר יצרתם פרטי כניסה של הרשאת חשבון משתמש ואתם מכירים את התהליך. היא שונה מהרשאה של חשבון שירות, שמתבססת על טכניקה אחרת, ולכן צריך להמשיך לקרוא.
מבוא להרשאה (בתוספת אימות)
כדי לשלוח בקשות ל-APIs, האפליקציה צריכה לקבל את ההרשאה המתאימה. אימות הוא מילה דומה שמתארת פרטי כניסה – אתם מאמתים את עצמכם כשאתם נכנסים לחשבון Google עם שם משתמש וסיסמה. אחרי האימות, השלב הבא הוא לבדוק אם הקוד שלכם מורשה לגשת לנתונים, כמו קובצי blob ב-Cloud Storage או קבצים אישיים של משתמשים ב-Google Drive.
ממשקי Google API תומכים בכמה סוגים של הרשאות, אבל הסוג הכי נפוץ עבור משתמשי Google Workspace API הוא הרשאת משתמש, כי האפליקציה לדוגמה ב-codelab הזה ניגשת לנתונים ששייכים למשתמשי קצה. משתמשי הקצה האלה צריכים להעניק הרשאה לאפליקציה שלכם לגשת לנתונים שלהם. המשמעות היא שהקוד צריך לקבל פרטי כניסה של OAuth2 לחשבון המשתמש.
כדי לקבל פרטי כניסה של OAuth2 להרשאת משתמש, חוזרים אל API Manager ובוחרים בכרטיסייה Credentials (פרטי כניסה) בסרגל הניווט הימני:
כשתגיעו לשם, תראו את כל פרטי הכניסה שלכם בשלושה קטעים נפרדים:
האפשרות הראשונה היא מפתחות API, השנייה היא מזהי לקוחות ב-OAuth 2.0 והאחרונה היא חשבונות שירות ב-OAuth2. אנחנו משתמשים באפשרות האמצעית.
יצירת פרטי כניסה
בדף Credentials (פרטי כניסה), לוחצים על הלחצן + Create Credentials (יצירת פרטי כניסה) בחלק העליון. לאחר מכן מוצג דו-שיח שבו בוחרים באפשרות OAuth client ID (מזהה לקוח OAuth):
במסך הבא יש 2 פעולות: הגדרת מסך ההסכמה של האפליקציה ובחירת סוג האפליקציה:
אם לא הגדרתם מסך הסכמה, תראו את האזהרה במסוף ותצטרכו להגדיר אותו עכשיו. (אם כבר הגדרתם את מסך ההסכמה, אפשר לדלג על השלבים הבאים).
מסך הסכמה ל-OAuth
לוחצים על 'הגדרת מסך הסכמה' ובוחרים באפליקציה 'חיצונית' (או 'פנימית' אם אתם לקוחות Google Workspace [לשעבר Google Workspace]):
שימו לב: לצורך התרגיל הזה, לא משנה מה תבחרו כי אתם לא מפרסמים את הדוגמה של ה-Codelab. רוב האנשים יבחרו באפשרות 'חיצוני' כדי לעבור למסך מורכב יותר, אבל בפועל צריך למלא רק את השדה 'שם האפליקציה' בחלק העליון:
בשלב הזה צריך רק שם לאפליקציה, אז בוחרים שם שמשקף את ה-codelab שאתם מבצעים ולוחצים על שמירה.
יצירת מזהה לקוח OAuth (אימות חשבון משתמש)
עכשיו חוזרים לכרטיסייה Credentials (פרטי כניסה) כדי ליצור מזהה לקוח OAuth2. כאן מוצגים מזהי לקוח OAuth שונים שאפשר ליצור:
אנחנו מפתחים כלי לשורת פקודה, שהוא אחר, אז בוחרים באפשרות הזו ולוחצים על הלחצן יצירה. בוחרים שם למזהה הלקוח שמשקף את האפליקציה שיוצרים, או פשוט משתמשים בשם ברירת המחדל, שהוא בדרך כלל 'לקוח אחר N'.
שמירת פרטי הכניסה
- מוצגת תיבת דו-שיח עם פרטי הכניסה החדשים. לוחצים על אישור כדי לסגור אותה.
- חוזרים לדף Credentials (פרטי כניסה), גוללים לקטע OAuth2 Client IDs (מזהי לקוח OAuth2), מאתרים את מזהה הלקוח החדש ולוחצים על סמל ההורדה
בקצה השמאלי התחתון.
- תיבת דו-שיח נפתחת לשמירת קובץ בשם
client_secret-LONG-HASH-STRING.apps.googleusercontent.com.json, בדרך כלל בתיקייה Downloads (הורדות). מומלץ לקצר את השם לשם קל יותר כמוclient_secret.json(זה השם שבו נעשה שימוש באפליקציה לדוגמה), ואז לשמור אותו בספרייה או בתיקייה שבהן תיצרו את האפליקציה לדוגמה ב-codelab הזה.
סיכום
עכשיו, כשיש לכם את פרטי הכניסה, אתם יכולים לגשת ל-Drive API מהאפליקציה שלכם. חשוב לזכור שמטרת מזהה הלקוח של OAuth היא שהמשתמשים יצטרכו להעניק לאפליקציה שלכם הרשאה לגשת לנתונים שלהם ב-Google Drive.
NOTE: פרטים נוספים על יצירת פרויקטים, הפעלת ממשקי API וקבלת פרטי כניסה באופן ידני, כלומר ללא שימוש באשף שלמעלה, זמינים אחרי סיום ה-codelab הזה.
8. הצגת האפליקציה של הקבצים והתיקיות ב-Drive
בין אם בסביבת הפיתוח המקומית שלכם ובין אם ב-Cloud Shell, באותה ספרייה שבה נמצא קובץ האישורים client_id.json, יוצרים קובץ Python חדש בשם drive_list.py ומוסיפים את שורות הקוד הבאות:
from __future__ import print_function
from googleapiclient import discovery
from httplib2 import Http
from oauth2client import file, client, tools
SCOPES = 'https://www.googleapis.com/auth/drive.readonly.metadata'
store = file.Storage('storage.json')
creds = store.get()
if not creds or creds.invalid:
flow = client.flow_from_clientsecrets('client_id.json', SCOPES)
creds = tools.run_flow(flow, store)
DRIVE = discovery.build('drive', 'v3', http=creds.authorize(Http()))
files = DRIVE.files().list().execute().get('files', [])
for f in files:
print(f['name'], f['mimeType'])
מבנה האפליקציה
האפליקציה מחולקת לשלושה חלקים עיקריים:
- ייבוא של Python כדי להשתמש בפונקציונליות של הספרייה
- קבלת פרטי כניסה לאפליקציה
- אחזור והצגה של שמות קבצים ותיקיות וסוגי MIME ב-Google Drive של המשתמש
NOTE: אחרי שתסיימו את ה-Codelab הזה, תוכלו לעיין בהסבר מפורט של הקוד, שורה אחר שורה, כדי להעמיק את הידע.
הפעלת האפליקציה
נותנים לקובץ שם כמו drive_list.py. בפעם הראשונה שמריצים את הסקריפט, אין לו הרשאה לגשת לקבצים של המשתמש ב-Drive (שלכם). הפלט אמור להיראות כך כשההרצה מושהית:
$ python3 ./drive_list.py /usr/local/lib/python3.6/site-packages/oauth2client/_helpers.py:255: UserWarning: Cannot access storage.json: No such file or directory warnings.warn(_MISSING_FILE_MESSAGE.format(filename)) Your browser has been opened to visit: https://accounts.google.com/o/oauth2/auth?client_id=LONG-STRING.apps.googleusercontent.com&redirect_uri=http%3A%2F%2Flocalhost%3A8080%2F&scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fdrive.readonly.metadata&access_type=offline&response_type=code If your browser is on a different machine then exit and re-run this application with the command-line parameter --noauth_local_webserver
מסביבת פיתוח מקומית
הסקריפט בשורת הפקודה מושהה כשחלון דפדפן נפתח ומוצגת תיבת הדו-שיח של הרשאות OAuth2:
כאן האפליקציה מבקשת מהמשתמש את ההרשאות שהקוד מבקש (דרך המשתנה SCOPES). במקרה הזה, מדובר ביכולת לראות את המטא-נתונים של הקובץ מ-Google Drive של המשתמש. כן, בהיקפי ההרשאות האלה בקוד מופיעים מזהי URI, אבל הם מתורגמים לשפה שצוינה באזור שלכם בחלון הדו-שיח של תהליך OAuth2. המשתמש צריך לתת הרשאה מפורשת להרשאות המבוקשות, אחרת החלק 'run flow' בקוד יחזיר חריגה והסקריפט לא ימשיך.
NOTE: לחלק מהמשתמשים יש כמה דפדפנים, ויכול להיות שבקשת ההרשאה תופיע בדפדפן שהם לא מעדיפים. במקרה כזה, פשוט מעתיקים את כתובת ה-URL המלאה מחלון הדפדפן שבו לא רוצים להשתמש ומדביקים אותה בסרגל הכתובות של דפדפן שכן רוצים להשתמש בו.
מ-Cloud Shell
אם לא שמתם לב והרצתם את התוכנית ב-Cloud Shell, לא ייפתח חלון דפדפן ותישארו תקועים. הבנתם שהודעת האבחון שמופיעה למטה מיועדת לכם… ההודעה הזו:
If your browser is on a different machine then exit and re-run this application with the command-line parameter --noauth_local_webserver
אם מפעילים פתרונות חכמים בצורה הזו, מקבלים את הפלט הבא:
$ python3 drive_list.py --noauth_local_webserver /usr/local/lib/python3.7/site-packages/oauth2client/_helpers.py:255: UserWarning: Cannot access storage.json: No such file or directory warnings.warn(_MISSING_FILE_MESSAGE.format(filename)) Go to the following link in your browser: https://accounts.google.com/o/oauth2/auth?client_id=xxx.apps.googleusercontent.com&redirect_uri=urn%3Aietf%3Awg%3Aoauth%3A2.0%3Aoob&scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fdrive.readonly.metadata&access_type=offline&response_type=code Enter verification code:
אם תפעלו לפי ההוראות ותעברו לכרטיסייה אחרת בדפדפן עם כתובת ה-URL הזו, תקבלו חוויה כמעט זהה לזו שתוארה למעלה לגבי סביבות פיתוח מקומיות. ההבדל העיקרי הוא שבסוף התהליך מופיע עוד מסך עם קוד האימות שצריך להזין ב-Cloud Shell:
גוזרים את הקוד הזה ומדביקים אותו בחלון המסוף.
סיכום
אחרי שהמשתמש לוחץ על 'אישור' או מדביק את קוד האימות בהנחיה, האפליקציה תפעל (או תמשיך לפעול), ולכן צפוי פלט שכולל קבצים או תיקיות ב-Drive וסוגי MIME שלהם. דוגמה מאחד מחשבונות הבדיקה שלנו:
$ python3 ./drive_list.py Travel expenses application/vnd.google-apps.spreadsheet Gmail Add-ons codelab application/vnd.google-apps.script Google Workspace Developer Intro application/vnd.google-apps.presentation Baseball Sheets application/vnd.google-apps.folder My Resume application/vnd.google-apps.document . . .
שימו לב שבביצועים הבאים לא תתבקשו יותר לאשר הרשאה (כי היא נשמרה במטמון של ספריות האימות), ותועברו ישירות לפלט. לא מרגש לראות את המסמכים שלכם במסוף בפעם הראשונה? לדעתנו כן!
9. סיכום
עכשיו אתם מוכנים לקרוא על תכונות נוספות של Drive API או על ממשקי API אחרים של Google Workspace (Gmail, Google Docs, Sheets, Slides, Calendar) ושל Google APIs (מפות, Analytics, YouTube וכו'). כל הכבוד שהגעת עד הסוף!
הקוד שמופיע ב-Codelab הזה זמין גם במאגר GitHub שלו בכתובת github.com/googlecodelabs/gsuite-apis-intro. (אנחנו שואפים לשמור על סנכרון בין ה-Codelab הזה לבין המאגר). שנמשיך הלאה? בהמשך מפורטים מקורות מידע שונים שיעזרו לכם להעמיק בחומר שמוצג ב-codelab הזה, או אם אתם רוצים להרחיב את הידע ולבדוק דרכים אחרות לגשת לטכנולוגיות של Google באופן פרוגרמטי.
כפי שציינו קודם, אם אתם לא מפתחים ב-Python באופן קבוע, אתם מוזמנים לבצע מחדש את הדוגמה הזו של ה-Codelab בשפת הפיתוח המועדפת עליכם. כאן אפשר למצוא ספריות לקוח לשפות נתמכות.
מחקר נוסף
עכשיו, אחרי שצברתם ניסיון בשימוש ב-Drive API, הנה כמה תרגילים מומלצים שיעזרו לכם לפתח את הכישורים שלכם:
- קובצי ZIP: כותבים אפליקציה שמגבה כמה ארכיוני ZIP ל-Drive, ומבטלת את הדחיסה שלהם תוך כדי כך, כך שכל שם של קובץ ZIP יהיה השם של התיקייה שאליה הקבצים האלה נכנסים. נקודות בונוס: תמיכה בארכיוני ZIP רקורסיביים בתוך קובצי ZIP אחרים עם תיקיות Drive שמוטמעות בתוך תיקיות אחרות. אם אתם מתייאשים, כדאי לעיין באפליקציה לדוגמה של Node.js.
- אלבומי תמונות: כתוב את ההתחלה של כלי ליצירת אלבומי תמונות שמעלה כמה תמונות ל-Google Drive ומארגן אותן בתיקיות נפרדות לפי חותמת זמן ומיקום גיאוגרפי. נקודות בונוס: מציאת ספרייה של מניפולציות על תמונות בקוד פתוח וחיבור כל התמונות בכל תיקייה כדי לייצג אירועים שהיו לכם (טיול, ארוחת ערב וכו').
- סקירת GCP: כתיבת אפליקציה שמקשרת בין Google Workspace לבין Google Cloud Platform (GCP). לכתוב כלי שמגבה קבצי תמונות מ-Google Drive ל-Google Cloud Storage (GCS), פתרון אחר של 'אחסון קבצים בענן'. תאמינו או לא, השימוש ב-GCS יהיה פשוט יותר משימוש ב-Drive, בגלל ספריות הלקוח המתקדמות שלו.
- ניתוח ותיעוד: כדי להרחיב את הפתרון שלכם לתרחיש מספר 3, צריך לנתח כל תמונה מגובה על ידי העברתה אל Google Cloud Vision API וקבלת התוויות המובילות (3, 5, 10) של מה ש-API רואה בתמונות האלה. לכל תמונה, כותבים שורה בגיליון אלקטרוני ב-Google Sheets שמכילה את הניתוח מ-Cloud Vision וגם את המיקום של הגיבוי שלה ב-GCS. אם אתם מתייאשים, כדאי לעיין ב-Python codelab הזה.
10. מקורות מידע נוספים
מאמרי עזרה
- מאמרי העזרה של Google Drive API (API בארכיטקטורת REST ו-Android native SDK/API)
- תיעוד של ממשקי API אחרים של Google Workspace
- מסמכי תיעוד של Google APIs אחרים
- ספריות לקוח של Google APIs
- מסמכי OAuth2
סרטונים קשורים וכלליים
- יצירת פרויקטים חדשים ב-Google API ( פוסט בבלוג וסרטון)
- בדיקת קוד שחוזר על עצמו (boilerplate) של הרשאות ב-Python ( סרטון)
- הצגת הקבצים ב-Google Drive ( סרטון, פוסט בבלוג)
- Google Drive API video library
- סדרת סרטונים של Launchpad Online (קודמת ל...)
- סדרת הסרטונים Google Workspace Dev Show
חדשות ועדכונים
- הבלוג למפתחים של Google Workspace
- מפתחים של Google Workspace Twitter (@GSuiteDevs)
- הניוזלטר החודשי למפתחים של Google Workspace
Codelabs נוספים
רמה למתחילים
- [Apps Script] מבוא ל-Google Apps Script
רמה בינונית
- [Apps Script] CLASP כלי שורת פקודה של Apps Script
- [Apps Script] Gmail Add-ons
- [Apps Script] Docs Add-on & GCP Natural Language API
- [Apps Script] Hangouts Chat bot framework
- [REST APIs] כלי דיווח בהתאמה אישית (Sheets API)
- [REST APIs] Custom slide generator for Github license BigQuery analyzer (Slides+BigQuery APIs)
הגדרות מתקדמות
- [REST APIs] תהליך עבודה לעיבוד תמונות בענן (Drive, Cloud Storage, Cloud Vision, Sheets APIs)
אפליקציות הפניה
- כלי להמרת Markdown ל-Google Slides (API בארכיטקטורת REST של Slides)
11. *הסבר מפורט על האפליקציה
המקטע האופציונלי הזה מיועד ללימוד עצמי אחרי שהסשן מסתיים, כדי להשלים פערים או כדי להמשיך את המחקר.
ייבוא של Python כדי להשתמש בפונקציונליות של הספרייה
from __future__ import print_function
from googleapiclient import discovery
from httplib2 import Http
from oauth2client import file, client, tools
- ההצהרה הראשונה
importמאפשרת להריץ את הקוד הזה ב-Python 2. אפשר להסיר אותה לגמרי אם משתמשים רק ב-Python 3. - אחד מכללי הסגנון של Python הוא להפריד בין ייבוא של ספריות רגילות לבין ייבוא של מודולים של צד שלישי – לכן יש שורה ריקה.
- שלושת הייבואים הבאים מביאים את המחלקות והפונקציות הנדרשות מספריית הלקוח של Google APIs... כולם נחוצים כדי לכתוב את האפליקציה הזו. בקצרה, הנה מה שהם עושים:
-
googleapiclientמתמקד בחיבור ל-Google APIs -
httplib2מספקת לקוח HTTP לשימוש באפליקציה -
oauth2clientעוזר לנו לנהל את פרטי הכניסה של OAuth2
הרשאות וקבלת פרטי כניסה לאפליקציה
SCOPES = 'https://www.googleapis.com/auth/drive.readonly.metadata'
store = file.Storage('storage.json')
creds = store.get()
if not creds or creds.invalid:
flow = client.flow_from_clientsecrets('client_id.json', SCOPES)
creds = tools.run_flow(flow, store)
DRIVE = discovery.build('drive', 'v3', http=creds.authorize(Http()))
SCOPESהרשאות האפליקציה הן ההרשאות שהאפליקציה תבקש מהמשתמש שמריץ אותה. כדי לשמור על נתוני המשתמשים, האפליקציות לא יכולות לפעול בלי לקבל הרשאה- מומלץ להשתמש בהרשאות הכי מגבילות שהאפליקציה צריכה כדי לפעול. למה?
- זה לא מעצבן שאפליקציה מבקשת הרבה הרשאות כשמתקינים או מפעילים אותה? נחשו מה? עכשיו אתם בצד השני של המטבע, ומבקשים מהמשתמשים את כל ההרשאות האלה. שימוש בהיקפי הרשאות מגבילים יותר גורם למשתמשים להרגיש יותר בנוח להתקין את האפליקציה שלכם, כי אתם מבקשים פחות הרשאות גישה.
- רוב ההיקפים נראים כמו כתובות URL ארוכות, והיקף המטא-נתונים של Drive לא שונה.
SCOPES = 'https://www.googleapis.com/auth/drive.readonly.metadata'
- נדרש טוקן כדי שאפליקציות יוכלו לתקשר עם השרתים של Google. אסימונים תקינים שמתקבלים מ-Google יישמרו בקובץ אחסון האסימונים,
storage.json. אם לא שומרים את הטוקנים האלה, צריך לתת הרשאה לאפליקציה בכל פעם שמפעילים פתרונות חכמים.
store = file.Storage('storage.json')
- האפליקציה בודקת קודם אם כבר יש לנו פרטי כניסה תקינים באחסון (ראו את
ifהצהרת התנאי).
creds = store.get()
if not creds or creds.invalid:
- אם אין לכם פרטי כניסה או שהתוקף שלהם פג, צריך ליצור הרשאה חדשה flow [דרך
oauth2client.client.flow_from_clientsecrets()] ממזהה הלקוח ומסוד הלקוח של OAuth בקובץclient_id.jsonשהורדתם].
if not creds or creds.invalid:
flow = client.flow_from_clientsecrets('client_id.json', SCOPES)
- אחרי שיוצרים את התהליך באפליקציה, צריך להפעיל אותו כדי להציג למשתמש את מסך ההרשאות של OAuth2 [באמצעות
oauth2client.tools.run_flow()] שמתואר ומודגם למעלה.
creds = tools.run_flow(flow, store)
- כשמשתמשים לוחצים על אישור, הם מסכימים שהאפליקציה שלכם תיגש למטא-נתונים של הקבצים שלהם ב-Google Drive, ושרתי Google יחזירו טוקנים כדי לגשת ל-API. הם מוחזרים כ-
credsונשמרים במטמון בקובץstorage.json. - בשלב הזה, לאפליקציה שלכם יש פרטי כניסה תקפים לביצוע קריאות ל-API. הפעלת הפקודה
googleapiclient.discovery.build()יוצרת נקודת קצה של שירות ל-API שבו אתם משתמשים. - כדי להשתמש ב-
build(), צריך להעביר את שם ה-API ('drive') ואת הגרסה הרצויה (נכון לעכשיו'v3'). - הפרמטר האחרון הוא לקוח HTTP שמשמש לקריאות מוצפנות ל-API.
DRIVE = discovery.build('drive', 'v3', http=creds.authorize(Http()))
אחזור והצגה של 100 הקבצים או התיקיות הראשונים ב-Drive וסוגי ה-MIME שלהם)
files = DRIVE.files().list().execute().get('files', [])
for f in files:
print(f['name'], f['mimeType'])
- בשורה הבאה של הקוד מתבצעת קריאה לשיטה
list()באוסףfiles()של Drive API כדי ליצור את הבקשה, שמתבצעת מיד באמצעותexecute(). מוחזרת מחרוזת Pythondictשממנה אנחנו מבקשים את המפתח'files'כדי לקבל את השמות של 100 קבצים ותיקיות מ-Google Drive של המשתמש (או פחות אם יש לו פחות קבצים). - למה 100? זו ברירת המחדל מ-
DRIVE.files().list(). אם רוצים לשנות את המספר הזה, למשל ל-10 קבצים או ל-1,000, מוסיפים את הפרמטרpageSizeלבקשה:DRIVE.files().list(pageSize=10). כאן אפשר לעיין באפשרויות נוספות. - החלק האחרון של הסקריפט עובר בלולאה על כל קובץ ומציג את השם ואת סוג ה-MIME של הקובץ.
כתבתם עכשיו את האפליקציה הראשונה שלכם שמשתמשת ב-API של Google בארכיטקטורת REST... מזל טוב! מלבד ההצהרות על ייבוא וקוד ההרשאה, הסקריפט הזה כולל רק כמה שורות קוד (כמו שרואים למעלה). רוב ממשקי ה-API של Google פועלים בצורה דומה, וצריך ליצור נקודות קצה של שירות רק לכל אחד מהם שרוצים להשתמש בו.
שימוש ביותר מממשק API אחד של Google באפליקציה
כן, אפשר בהחלט להשתמש ביותר מממשק API אחד באותה אפליקציה. הנה קטע קוד Python לאפליקציה שעושה שימוש חוזר באותו לקוח HTTP ויוצרת נקודות קצה של שירות לשלושה ממשקי Google API (כן, גם עם 3 SCOPES שונים):
SCOPES = (
'https://www.googleapis.com/auth/drive',
'https://www.googleapis.com/auth/spreadsheets.readonly',
'https://www.googleapis.com/auth/presentations',
)
. . .
HTTP = creds.authorize(Http())
DRIVE = discovery.build('drive', 'v3', http=HTTP)
SHEETS = discovery.build('sheets', 'v4', http=HTTP)
SLIDES = discovery.build('slides', 'v1', http=HTTP)
אנחנו מדמיינים שהקוד הזה יכול להיות חלק מאפליקציה שיוצרת כמה מצגות (Slides API) על סמך נתונים מגיליון אלקטרוני (Sheets API) ומשתמשת בתבנית שקופית שמועתקת (Drive API) לכל מצגת שנוצרת. אפליקציה כזו לא קיימת, אבל אפשר לבנות משהו דומה באמצעות שני קבצים לדוגמה קיימים שצוות Google Workspace יצר כבסיס לבנייה:
- החלפת טקסט ותמונות בשקפים ( פוסט בבלוג וסרטון) – נעשה שימוש ב-Drive API כדי להעתיק חבילת שקפים של תבנית, ואז נעשה שימוש ב-Slides API כדי לשנות את ה-placeholders של הטקסט והתמונות
- יצירת שקפים מנתונים בגיליון אלקטרוני ( פוסט בבלוג וסרטון) – קריאת נתונים מגיליון אלקטרוני (Sheets API) ויצירת שקפים (Slides API) על סמך הנתונים האלה
האתגר שלכם: ליצור את האפליקציה הזו!
12. *שימוש מתקדם במסוף הפיתוח
בקטע האופציונלי הזה נסביר איך ליצור פרויקטים ב-devconsole, להפעיל ממשקי API ולקבל פרטי כניסה, בלי להשתמש באשף כמו שמוסבר למעלה ב-codelab. האפשרות הזו מיועדת למשתמשים ברמת ביניים שנוח להם לבצע את הפעולה באופן ידני או שרוצים ללמוד איך לעשות זאת.
ציון פרויקט ב-מסוף Cloud
בכל פעם שכותבים אפליקציה באמצעות ממשקי Google API, צריך שיהיה פרויקט. אתם יכולים להשתמש בפרויקט קיים או ליצור פרויקט חדש. הפעולה הזו מתבצעת במסוף Cloud. חלק מה-Codelabs מספקים קישור חד-פעמי לכניסה (כלומר, כמו אשף ההגדרה) שמאפשר להתחיל במהירות, בלי לבצע הרבה מהשלבים הנדרשים. אבל לא כולם עושים את זה, ולכן אלה הוראות כלליות ליצירת פרויקטים.
אפשר ליצור פרויקטים מרוב המסכים במסוף Cloud, בתנאי שנכנסתם לחשבון עם פרטי הכניסה שלכם ל-Google ואתם רואים תפריט נפתח של פרויקט בחלק העליון של המסוף. שימו לב שרוב צילומי המסך כאן נלקחו מ-API Manager, שנקרא גם Developers Console (אפשר להגיע אליו בקלות בלחיצה על API manager בסרגל הניווט הימני או על ידי הפניית הדפדפן ישירות אל console.developers.google.com).
- אם עדיין אין לכם פרויקטים, יכול להיות שתועברו אל...
- בדף מרכז השליטה:
- בדף ספרייה:
- או דף ריק לחלוטין:
אם זה קורה לכם, פשוט רעננו את הדפדפן כדי לעבור לדף הספרייה.
- בין אם אתם נמצאים בדף לוח הבקרה או בדף ספרייה, לוחצים על בורר הפרויקטים בראש הדף:
- בשלב הבא תופיע תיבת הדו-שיח של הבורר. לוחצים על סמל הפלוס '+' בצד שמאל כדי ליצור פרויקט חדש:
- אחרי שלוחצים על '+', מופיע הדף פרויקט חדש. כל החשבונות הפרטיים מקבלים 12 פרויקטים כברירת מחדל. לפני שיוצרים את הפרויקט הראשון, צריך לאשר את התנאים וההגבלות של Google APIs:
אחרי שתעשו את זה, השאלות לגבי שליחת אימייל והתנאים וההגבלות לא יופיעו יותר כשתיצרו פרויקטים בעתיד:
יצרתם פרויקט בהצלחה ואתם מוכנים להמשיך ולבחור את ממשקי ה-API שבהם אתם רוצים להשתמש בפרויקט.
הפעלת ממשקי Google APIs
כדי להתחיל להשתמש בממשקי Google API, צריך להפעיל אותם. בדוגמה הבאה אפשר לראות איך מפעילים את Cloud Vision API. ב-codelab הזה, יכול להיות שתשתמשו בממשק API אחד או יותר, ותצטרכו לבצע שלבים דומים כדי להפעיל אותם לפני השימוש.
מ-Cloud Shell
כדי להפעיל את ה-API באמצעות Cloud Shell, משתמשים בפקודה הבאה:
gcloud services enable vision.googleapis.com
מתוך Cloud Console
אפשר גם להפעיל את Vision API ב-API Manager. ב-Cloud Console, עוברים אל API Manager ובוחרים באפשרות Library.
בסרגל החיפוש, מתחילים להקליד 'vision' (ראייה) ואז בוחרים באפשרות Vision API כשהיא מופיעה. יכול להיות שזה ייראה כך בזמן ההקלדה:
בוחרים ב-Cloud Vision API כדי להציג את תיבת הדו-שיח שמופיעה למטה, ואז לוחצים על הלחצן Enable (הפעלה):
עלות
אפשר להשתמש ברוב ממשקי ה-API של Google ללא תשלום, אבל השימוש ב-GCP (מוצרים וממשקי API) כרוך בתשלום. כשמפעילים את Vision API (כמו שמתואר למעלה), יכול להיות שתתבקשו לספק חשבון חיוב פעיל. לפני שמפעילים את Vision API, צריך לעיין בפרטי התמחור שלו. חשוב לזכור שבמוצרים מסוימים של Google Cloud Platform (GCP) יש תוכנית ללא תשלום, ואתם תחויבו רק אם תחרגו מהמגבלות שלה. לצורך ה-codelab, כל קריאה ל-Vision API נספרת במסגרת רמת השימוש החינמית הזו, וכל עוד אתם לא חורגים מהמגבלות שלה (בכל חודש), לא אמורים לחול עליכם חיובים.
חלק מממשקי Google APIs, כלומר: השימוש ב-Google Workspace מכוסה על ידי מינוי חודשי, כך שאין חיוב ישיר על שימוש בממשקי API של Gmail, Google Drive, יומן Google, Docs, Sheets ו-Slides, למשל. יש הבדלים בחיוב בין מוצרי Google השונים, ולכן חשוב לעיין בתיעוד של ה-API כדי לקבל את המידע הזה.
סיכום
ב-codelab הזה צריך להפעיל רק את Google Drive API, לכן פועלים לפי ההוראות שלמעלה ומחפשים את Drive. אחרי ההפעלה, ממשיכים קדימה.
הרשאה לבקשות API (הרשאת משתמש)
מבוא להרשאה (בתוספת אימות)
כדי לשלוח בקשות ל-APIs, האפליקציה צריכה לקבל את ההרשאה המתאימה. אימות הוא מילה דומה שמתארת פרטי כניסה – אתם מאמתים את עצמכם כשאתם נכנסים לחשבון Google עם שם משתמש וסיסמה. אחרי האימות, השלב הבא הוא לבדוק אם הקוד שלכם מורשה לגשת לנתונים, כמו קובצי blob ב-Cloud Storage או קבצים אישיים של משתמשים ב-Google Drive.
ממשקי Google API תומכים בכמה סוגים של הרשאות, אבל הסוג הכי נפוץ עבור משתמשי Google Workspace API הוא הרשאת משתמש, כי האפליקציה לדוגמה ב-codelab הזה ניגשת לנתונים ששייכים למשתמשי קצה. משתמשי הקצה האלה צריכים להעניק הרשאה לאפליקציה שלכם לגשת לנתונים שלהם. המשמעות היא שהקוד צריך לקבל פרטי כניסה של OAuth2 לחשבון המשתמש.
כדי לקבל פרטי כניסה של OAuth2 להרשאת משתמש, חוזרים אל API Manager ובוחרים בכרטיסייה Credentials (פרטי כניסה) בסרגל הניווט הימני:
כשתגיעו לשם, תראו את כל פרטי הכניסה שלכם בשלושה קטעים נפרדים:
האפשרות הראשונה היא מפתחות API, השנייה היא מזהי לקוחות ב-OAuth 2.0 והאחרונה היא חשבונות שירות ב-OAuth2. אנחנו משתמשים באפשרות האמצעית.
יצירת פרטי כניסה
בדף Credentials (פרטי כניסה), לוחצים על הלחצן + Create Credentials (יצירת פרטי כניסה) בחלק העליון. לאחר מכן מוצג דו-שיח שבו בוחרים באפשרות OAuth client ID (מזהה לקוח OAuth):
במסך הבא יש 2 פעולות: הגדרת מסך ההסכמה של האפליקציה ובחירת סוג האפליקציה:
אם לא הגדרתם מסך הסכמה, תראו את האזהרה במסוף ותצטרכו להגדיר אותו עכשיו. (אם כבר הגדרתם את מסך ההסכמה, אפשר לדלג על השלבים הבאים).
מסך הסכמה ל-OAuth
לוחצים על 'הגדרת מסך הסכמה' ובוחרים באפשרות 'חיצונית' (או 'פנימית' אם אתם לקוחות Google Workspace):
שימו לב: לצורך התרגיל הזה, לא משנה מה תבחרו כי אתם לא מפרסמים את הדוגמה של ה-Codelab. רוב האנשים יבחרו באפשרות 'חיצוני' כדי לעבור למסך מורכב יותר, אבל בפועל צריך למלא רק את השדה 'שם האפליקציה' בחלק העליון:
בשלב הזה צריך רק שם לאפליקציה, אז בוחרים שם שמשקף את ה-codelab שאתם מבצעים ולוחצים על שמירה.
יצירת מזהה לקוח OAuth (אימות חשבון משתמש)
עכשיו חוזרים לכרטיסייה Credentials (פרטי כניסה) כדי ליצור מזהה לקוח OAuth2. כאן מוצגים מזהי לקוח OAuth שונים שאפשר ליצור:
אנחנו מפתחים כלי לשורת פקודה, שהוא אחר, אז בוחרים באפשרות הזו ולוחצים על הלחצן יצירה. בוחרים שם למזהה הלקוח שמשקף את האפליקציה שיוצרים, או פשוט משתמשים בשם ברירת המחדל, שהוא בדרך כלל 'לקוח אחר N'.
שמירת פרטי הכניסה
- מוצגת תיבת דו-שיח עם פרטי הכניסה החדשים. לוחצים על אישור כדי לסגור אותה.
- חוזרים לדף Credentials (פרטי כניסה), גוללים לקטע OAuth2 Client IDs (מזהי לקוח OAuth2), מאתרים את מזהה הלקוח החדש ולוחצים על סמל ההורדה
- תיבת דו-שיח נפתחת לשמירת קובץ בשם
client_secret-LONG-HASH-STRING.apps.googleusercontent.com.json, בדרך כלל בתיקייה Downloads (הורדות). מומלץ לקצר את השם לשם קל יותר כמוclient_secret.json(זה השם שבו נעשה שימוש באפליקציה לדוגמה), ואז לשמור אותו בספרייה או בתיקייה שבהן תיצרו את האפליקציה לדוגמה ב-codelab הזה.