1. שימוש בממשקי API של Google Workspace
בשיעור Codelab הזה נסביר איך להשתמש בממשקי RESTful API מבוססי HTTP של Google Workspace (לשעבר G Suite). הדוגמה תבוצע ב-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 3 ל-Python 2, נספק הוראות ספציפיות ל-Python 2.
*יצירה ושימוש בסביבות וירטואליות
הקטע הזה הוא אופציונלי ונדרש רק למי שחייב להשתמש בסביבה וירטואלית בשביל שיעור ה-Codelab הזה (כפי שמופיע באזהרה בסרגל הצד שלמעלה). אם במחשב שלכם מותקנת רק גרסת Python 3, אתם יכולים פשוט להריץ את הפקודה הבאה כדי ליצור סביבת Virtualenv בשם my_env (אפשר לבחור שם אחר אם רוצים):
virtualenv my_env
עם זאת, אם במחשב שלכם מותקנות גם Python 2 וגם Python 3, מומלץ להתקין סביבה וירטואלית של Python 3. אפשר לעשות זאת באמצעות -p flag כך:
virtualenv -p python3 my_env
נכנסים לסביבת ה-virtualenv החדשה שיצרתם על ידי 'הפעלה' שלה באופן הבא:
source my_env/bin/activate
כדי לוודא שאתם בסביבה, בודקים אם שם הסביבה מופיע לפני שורת הפקודה של המעטפת, כלומר:
(my_env) $
עכשיו תוכלו pip install את כל החבילות הנדרשות, להריץ קוד בסביבה הזו וכו'. יתרון נוסף הוא שאם תסתבכו ותגיעו למצב שבו התקנת Python שלכם פגומה וכו', תוכלו למחוק את כל הסביבה הזו בלי להשפיע על שאר המערכת.
5. התקנה של ספריית הלקוח של Google APIs ל-Python
בשיעור Codelab הזה נדרש שימוש בספריית הלקוח של 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. *******************************************************************************
אחרי שתצליחו להריץ את פקודת הייבוא הזו (ללא שגיאות או פלט), תוכלו להתחיל לתקשר עם ממשקי ה-API של Google.
סיכום
זהו שיעור Codelab למתחילים, ולכן אנחנו מניחים שאתם חדשים בשימוש בממשקי API של Google ו-Google Workspace. אם כבר יש לכם ניסיון ביצירת פרויקטים וביצירת מזהי לקוח OAuth להרשאת משתמש. אם כן, יוצרים פרויקט חדש או משתמשים בפרויקט קיים, יוצרים מזהה לקוח OAuth חדש או משתמשים במזהה קיים, מדלגים על שני המודולים הבאים ועוברים ישירות אל 'הצגת קבצים ותיקיות באפליקציית Drive' או מדלגים אל 'שימוש מתקדם במסוף המפתחים' כדי לעיין בשלבים האלה עם פחות הנחיות.
6. ציון פרויקט ב-מסוף Cloud
כדי להשתמש בממשקי Google API, צריך פרויקט. הם מנוהלים ב-Google Cloud Developers Console, או פשוט ב-devconsole. בשיעור Codelab הזה נשתמש רק ב-Google Drive API, ולכן יש לנו קישור חד-פעמי לכניסה (למטה בשלב 1) ש:
- מעבר אל מסוף הפיתוח
- המדריך כולל הסברים על יצירת פרויקט חדש (או בחירת פרויקט קיים), ועל
- הפעלת Drive API באופן אוטומטי
קדימה!
- עוברים אל console.developers.google.com/start/api?id=drive ונכנסים לחשבון Google.
- אם עדיין אין לכם פרויקטים, יוצג לכם המסך הבא שבו תצטרכו לאשר את התנאים וההגבלות של Google APIs:
אחרי שתאשרו את התנאים, ייצור פרויקט חדש בשם '*הפרויקט שלי*', וממשק Drive API יופעל באופן אוטומטי. 3. אם כבר יצרתם פרויקט (למשל, ב-Codelab הקודם?), יוצג המסך הבא:
כשלוחצים על התפריט הנפתח **יצירת פרויקט**, בוחרים פרויקט קיים או יוצרים פרויקט חדש.
אחרי שתבחרו פרויקט (חדש או קיים), 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 שתוכלו ליצור:
אנחנו מפתחים כלי לשורת פקודה, שהוא אחר, אז בוחרים באפשרות הזו ולוחצים על הלחצן יצירה. בוחרים שם למזהה הלקוח שמשקף את האפליקציה שיוצרים, או פשוט משתמשים בשם ברירת המחדל, שהוא בדרך כלל Other client N (לקוח אחר 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 (מפות, 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 intro
רמה בינונית
- [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 API)
אפליקציות לדוגמה
- כלי להמרת Markdown ל-Google Slides (Slides REST API)
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 של הקובץ.
כתבתם עכשיו את האפליקציה הראשונה שלכם שמשתמשת ב-Google REST API... מזל טוב! מלבד שורות הייבוא וקוד ההרשאה, הסקריפט הזה כולל רק כמה שורות קוד (כמו שרואים למעלה). רוב ממשקי Google API פועלים בצורה דומה, וצריך ליצור נקודות קצה של שירות רק לכל אחד מהם שרוצים להשתמש בו.
שימוש ביותר מממשק 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:
אחרי שתעשו את זה, השאלות לגבי שליחת אימיילים והתנאים וההגבלות לא יופיעו כשתיצרו פרויקטים בעתיד:
5. אם יצרתם בעבר לפחות פרויקט אחד, אחרי שתתחברו תועברו אל לוח הבקרה של הפרויקט האחרון שעבדתם עליו. משם, יוצרים פרויקט חדש כמו שבוחרים באפשרות **בחירת פרויקט** > **+**. 6. אחרי שיוצרים את הפרויקט החדש, חוזרים לדף **מרכז הבקרה**:
יצרתם פרויקט בהצלחה ואתם מוכנים להמשיך. עכשיו צריך לבחור את ממשקי ה-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 שתוכלו ליצור:
אנחנו מפתחים כלי לשורת פקודה, שהוא אחר, אז בוחרים באפשרות הזו ולוחצים על הלחצן יצירה. בוחרים שם למזהה הלקוח שמשקף את האפליקציה שיוצרים, או פשוט משתמשים בשם ברירת המחדל, שהוא בדרך כלל Other client N (לקוח אחר N).
שמירת פרטי הכניסה
- מופיעה תיבת דו-שיח עם פרטי הכניסה החדשים. לוחצים על אישור כדי לסגור אותה.
- חוזרים לדף Credentials (פרטי כניסה), גוללים למטה לקטע OAuth2 Client IDs (מזהי לקוח OAuth2), מאתרים את מזהה הלקוח החדש ולוחצים על סמל ההורדה
בקצה השמאלי התחתון.
- תיבת דו-שיח תיפתח כדי לשמור קובץ בשם
client_secret-LONG-HASH-STRING.apps.googleusercontent.com.json, כנראה בתיקייה Downloads. מומלץ לקצר את השם למשהו קל יותר כמוclient_secret.json(זה השם שבו נעשה שימוש באפליקציה לדוגמה), ואז לשמור אותו בספרייה או בתיקייה שבה תיצרו את האפליקציה לדוגמה ב-codelab הזה.