שליחת קריאה לממשקי API מפרויקט ב-Google Cloud

1. לפני שמתחילים

ב-Codelab הזה נסביר איך ליצור פרויקט בענן ב-Google Cloud ואז להפעיל ממשקי Google Cloud API מהפרויקט הזה.

דרישות מוקדמות

• יכולת להתמצא במסוף Google Cloud.

מה תלמדו

• איך יוצרים פרויקט ב-Google Cloud
• איך מגדירים חשבון לחיוב
• איך מגדירים את Cloud Shell
• איך מפעילים API.
• איך מאשרים API באמצעות מפתח API.
• איך נותנים הרשאה ל-API באמצעות חשבון שירות.

הדרישות

• חשבון Google, כמו חשבון Gmail או חשבון Google Workspace.
• גישה לחשבון לחיוב ב-Cloud או לכרטיס אשראי שבאמצעותו אפשר להירשם לתוכנית תקופת הניסיון בחינם.

2. להגדרה

בקטע הזה מוסבר איך ליצור פרויקט בענן ב-Google Cloud, להגדיר חשבון לחיוב ולהגדיר את Cloud Shell.

יצירת פרויקט בענן ב-Google Cloud והגדרת חשבון לחיוב

הערה: אם עדיין אין לכם חשבון Gmail או חשבון Google Workspace, אתם צריכים ליצור חשבון כזה קודם.

1. נכנסים אל Cloud Console ובוחרים פרויקט או יוצרים פרויקט חדש.

אזהרה: אם תשתמשו מחדש בפרויקט ותשלימו את ה-Codelab הזה, יכול להיות שתאפשרו למשתמשים מסוימים לגשת למשאבים באותו פרויקט אם הם לא יושבתו בסיום.

חשוב לזכור את מזהה הפרויקט שמופיע מתחת לשדה שם הפרויקט. המזהה הוא שם ייחודי בכל הפרויקטים ב-Google Cloud (השם שלמעלה כבר תפוס), והוא יופיע בהמשך ה-codelab הזה בתור PROJECT_ID.

הערה: אם אתם משתמשים בחשבון Gmail, אתם יכולים להשאיר את המיקום שמוגדר כברירת מחדל לללא ארגון. אם אתם משתמשים בחשבון Google Workspace, אתם צריכים לבחור מיקום שמתאים לארגון שלכם.

2. לאחר מכן, צריך להפעיל את החיוב במסוף Cloud כדי להשתמש במשאבים של Google Cloud.

למרות שה-codelab הזה לא אמור לעלות הרבה, אם בכלל, כדאי לפעול לפי ההוראות שבקטע ניקוי כדי להשבית את המשאבים ולמנוע עלויות מעבר ל-codelab הזה. שימו לב שמשתמשים חדשים ב-Google Cloud זכאים לתקופת ניסיון בחינם בשווי 300$.

הגדרת Cloud Shell

בשיעור Codelab הזה נשתמש ב-Cloud Shell, סביבת שורת פקודה שפועלת ב-Google Cloud. ‫Cloud Shell היא מכונה וירטואלית שמבוססת על Debian, שטעונים בה כל הכלים הדרושים למפתחים. יש בה ספריית בית בנפח מתמיד של 5GB, מה שמשפר מאוד את ביצועי הרשת והאימות. המשמעות היא שכל מה שצריך בשביל ה-codelab הזה הוא דפדפן.

כדי להפעיל את Cloud Shell מ-Cloud Console:

1. לוחצים על הפעלת Cloud Shell.

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

אחרי שמתחברים ל-Cloud Shell, אפשר לראות שהאימות כבר בוצע ושהפרויקט כבר מוגדר ל-PROJECT_ID.

2. יצירת רשימה של חשבונות עם פרטי כניסה:

gcloud auth list

הפלט הבא אמור להתקבל:

Credentialed accounts:
 - <MY_ACCOUNT>@<MY_DOMAIN>.com (active)

הערה: כלי ה-CLI‏ gcloud מותקן מראש ב-Cloud Shell, והוא עוזר לכם ליצור ולנהל משאבי Google Cloud. מידע נוסף מופיע במאמר סקירה כללית של כלי gcloud.

3. כדי לראות רשימה של הפרויקטים, מזינים את הפקודה הזו.

gcloud config list project

הפלט הבא אמור להתקבל:

[core]
project = <PROJECT_ID>

אם מסיבה כלשהי הפרויקט לא מוגדר, מריצים את הפקודה הזו כדי להגדיר את הפרויקט.

gcloud config set project <PROJECT_ID>

‫PROJECT_ID הוא המזהה שבו השתמשתם בשלבי ההגדרה. אפשר גם לחפש אותו במרכז הבקרה של מסוף Cloud:

ב-Cloud Shell מוגדרים גם כמה משתני סביבה כברירת מחדל, שיכולים להיות שימושיים כשמריצים פקודות בעתיד.

4. כדי לראות את מזהה הפרויקט, מזינים את הפקודה הבאה.

echo $GOOGLE_CLOUD_PROJECT

הפלט הבא אמור להתקבל:

<PROJECT_ID>

5. לבסוף, מגדירים את אזור ברירת המחדל ואת הגדרת הפרויקט.

gcloud config set compute/zone us-central1-f

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

הערה: כשמריצים את כלי ה-CLI‏ gcloud במכונה, הגדרות התצורה נשמרות במעבר בין סשנים. אבל אם אתם מריצים אותו ב-Cloud Shell, אתם צריכים לחזור על ההגדרות בכל סשן חדש ובכל התחברות מחדש.

3. הפעלת API מפרויקט

בשיעור Codelab הזה נדגים איך משתמשים בממשק API לדוגמה (Natural Language API) כדי למצוא ישויות (כמו אנשים, מקומות ואירועים) בטקסט, ואיך להעריך את הסנטימנט (רמת החיבה) של הטקסט הזה. תלמדו איך:

• מפעילים את ממשקי ה-API של Google Cloud.
• קבלת הרשאה ל-API באמצעות מפתחות API וחשבונות שירות.
• קוראים ל-API באמצעות curl וספריות לקוח.

הפעלת API

1. בתפריט הראשי במסוף Cloud, בוחרים באפשרות APIs & Services.

2. בחלק העליון של המסך, לוחצים על + ENABLE APIS AND SERVICES.

3. בשלב הזה, אפשר לסנן ולעיין בממשקי ה-API, או לעבור ישירות לממשק API באמצעות התיבה Search. מחפשים את Natural Language ובוחרים באפשרות Cloud Natural Language API.

4. לוחצים על TRY THIS API (התנסות עם ה-API).

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

יצירת מפתח API

מכיוון שאתם משתמשים ב-curl כדי לשלוח בקשה ל-Natural Language API, אתם צריכים ליצור מפתח API כדי להעביר אותו בכתובת ה-URL של הבקשה.

1. ב-Cloud Console, בוחרים באפשרות תפריט הניווט > APIs & Services > Credentials.

2. לוחצים על CREATE CREDENTIALS ואז בוחרים באפשרות API key:

3. מעתיקים את מפתח ה-API שנוצר ולוחצים על סגירה.

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

1. בשורה של הפקודה Cloud Shell, מייצאים את מפתח ה-API.

export API_KEY=<YOUR_API_KEY>

מחליפים את <YOUR_API_KEY> במפתח שיצרתם קודם.

2. יוצרים בקשה ל-API בכלי לעריכת Cloud Shell או בכלי לעריכת Linux, כמו Vim או Emacs. פרטים על הפרמטרים זמינים במאמר בנושא שיטה: documents.analyzeEntities. שומרים את הפלט בקובץ בשם request.json:

{
  "document":{
    "type":"PLAIN_TEXT",
    "content":"Google, headquartered in Mountain View (1600 Amphitheatre Pkwy, Mountain View, CA 940430), unveiled the new Android phone for $799 at the Consumer Electronic Show. Sundar Pichai said in his keynote that users love their new Android phones."
  },
  "encodingType":"UTF8"
}

3. מפעילים את ה-API עם פרטי הבקשה.

curl "https://language.googleapis.com/v1/documents:analyzeEntities?key=${API_KEY}" \
  -s -X POST -H "Content-Type: application/json" --data-binary @request.json

4. מריצים מחדש את הפקודה, מפנים את הפלט לקובץ ובודקים את התוצאה. פרטים על הפלט של קובץ ה-JSON מופיעים גם במאמר בנושא שיטה: documents.analyzeEntities.
5. כדי לשנות את הטקסט לניתוח בקובץ request.json, מחליפים את הערך content בטקסט הרצוי.

4. הרשאה עם חשבון שירות

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

1. חוזרים לקטע Credentials בתפריט APIs & Services.
2. לוחצים על Create Credentials, אבל הפעם בוחרים באפשרות Service Account.

3. מזינים שם של חשבון שירות שמתאר את המטרה שלו, כמו Natural Language Service Account. המערכת מציעה מזהה. אפשר גם להוסיף תיאור. בהמשך, כשתלמדו עוד על חשבונות שירות, תוכלו להעניק לחשבון השירות גישה לפרויקטים ולהעניק למשתמשים גישה לחשבון השירות. אבל כרגע, פשוט לוחצים על Done כדי ליצור את חשבון השירות.
4. כדי ליצור צמד מפתחות לשימוש בחשבון השירות, לוחצים על כדי לערוך את חשבון השירות.

פרטי חשבון השירות מוצגים.

5. מעתיקים את כתובת האימייל של חשבון השירות וחוזרים אל Cloud Shell.
6. ב-Cloud Shell, יוצרים צמד מפתחות לחשבון השירות ומגדירים משתנה סביבה שיצביע עליו:

gcloud iam service-accounts keys create ~/key.json \
  --iam-account <your service account email>
export GOOGLE_APPLICATION_CREDENTIALS="/home/$USER/key.json"

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

7. עכשיו אפשר להפעיל את ה-API באמצעות הפקודה:

gcloud ml language analyze-entities --content="Michelangelo Caravaggio, Italian painter, is known for 'The Calling of Saint Matthew'." 

התוצאה צריכה להיות זהה לתוצאה הקודמת.

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

5. הסרת המשאבים

לא מומלץ להשתמש במפתח API ללא הגבלות בפרויקטים. אם מישהו יקבל גישה אליו, הוא יוכל להשתמש בו ללא צורך באימות נוסף.

כדי למחוק את מפתח ה-API הזה:

1. לוחצים על תפריט הניווט > ממשקי API ושירותים > פרטי כניסה.
2. בקטע מפתחות API, בוחרים את המפתח שרוצים למחוק ולוחצים על מחיקה.
3. באופן דומה, במקום לדאוג שהמפתח הפרטי של חשבון השירות לא מוגן, בקטע Service Accounts בוחרים את חשבון השירות שרוצים למחוק ולוחצים על Delete.

6. מזל טוב

מעולה! למדתם איך ליצור פרויקט בענן של Google ואיך להפעיל API מתוך הפרויקט.