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

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

בשיעור הזה תלמדו איך ליצור פרויקט ב-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 הזה, יכול להיות שתאפשרו למשתמשים מסוימים לגשת למשאבים באותו פרויקט אם הם לא יושבתו בסיום.

זוכרים את מזהה הפרויקט שמופיע מתחת לשדה Project name. המזהה הוא שם ייחודי בכל הפרויקטים ב-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 Keys (מפתחות API), בוחרים את המפתח שרוצים למחוק ולוחצים על Delete (מחיקה).
3. באופן דומה, במקום לדאוג שהמפתח הפרטי של חשבון השירות לא מוגן, בקטע Service Accounts בוחרים את חשבון השירות שרוצים למחוק ולוחצים על Delete.

6. מזל טוב

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