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

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

בשיעור הזה תלמדו איך ליצור פרויקט ב-Google Cloud ואז לקרוא ל-Google Cloud APIs מהפרויקט הזה.

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

• יכולת לנווט במסוף 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 ובוחרים או יוצרים פרויקט.

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

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

הערה: אם משתמשים בחשבון 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:

1. לוחצים על Activate Cloud Shell.

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

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

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

gcloud auth list

הפלט הבא אמור להופיע:

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

הערה: הכלי gcloud CLI מותקן מראש ב-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. בוחרים באפשרות APIs & (ממשקי API &) שירותים מהתפריט הראשי במסוף Cloud.

2. בוחרים באפשרות + ENABLE APIS AND SERVICES בחלק העליון של המסך.

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

4. לוחצים על TRY this API.

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

יצירה של מפתח API

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

1. במסוף Cloud, בוחרים באפשרות Navigation menu > ממשקי API שירותים > פרטי כניסה.

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 Editor או באמצעות עורך Linux כמו Vim או Emacs. תוכלו למצוא את פרטי הפרמטרים בקטע Method: 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 מופיעים גם בקטע Method: documents.analyzeEntities.
5. כדי לשנות את הטקסט לניתוח בקובץ request.json, מחליפים את הערך content בטקסט לבחירתכם.

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

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

1. חוזרים לקטע Credentials (פרטי כניסה) במאמר APIs & תפריט בשירותים.
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. באופן דומה, במקום לחשוש שהמפתח הפרטי של חשבון השירות לא יהיה מוגן, בקטע חשבונות שירות, בוחרים את חשבון השירות שרוצים למחוק ואז לוחצים על מחיקה.

6. מזל טוב

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