אימות באמצעות REST

בדף הזה מוסבר איך לבצע אימות כשיוצרים בקשות REST ל-Google API.

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

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

כדי להריץ את הדוגמאות בדף הזה:

  1. התקינו את ה-CLI של Google Cloud.

  2. אם אתם משתמשים בספק זהויות חיצוני (IdP), קודם אתם צריכים להיכנס ל-CLI של gcloud באמצעות המאגר המאוחד לניהול זהויות.

  3. כדי לאתחל את ה-CLI של gcloud, הריצו את הפקודה הבאה: 

    gcloud init

  4. מפעילים את Cloud Resource Manager API ואת Identity and Access Management (IAM) API:

    תפקידים שנדרשים להפעלת ממשקי API

    כדי להפעיל ממשקי API, צריך את תפקיד ה-IAM 'אדמין של Service Usage' (roles/serviceusage.serviceUsageAdmin), שכולל את ההרשאה serviceusage.services.enable. איך מקצים תפקידים 

    gcloud services enable cloudresourcemanager.googleapis.com iam.googleapis.com

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

סוגים של פרטי כניסה

כדי לאמת קריאה ל-REST אפשר להשתמש בפרטי כניסה מהסוגים הבאים:

  • פרטי הכניסה ל-CLI של gcloud.

    הגישה הזו היא הדרך הקלה והבטוחה ביותר לספק פרטי כניסה ל-method ‏REST בסביבת פיתוח מקומית. זאת הגישה המועדפת אם לחשבון המשתמש שלכם יש את ההרשאות הנדרשות לניהול זהויות והרשאות גישה (IAM) ב-method הרצוי לכם.

    פרטי הכניסה ל-gcloud שונים מפרטי הכניסה שאתם מספקים ל-ADC באמצעות ה-CLI של gcloud. למידע נוסף, ראו הגדרת אימות ב-CLI של gcloud והגדרת ADC.

  • פרטי הכניסה שסיפקתם ל-Application Default Credentials ‏(ADC).

    ה-method הזה הוא האפשרות המועדפת לאימות של קריאה ל-REST בסביבת ייצור, כי ה-ADC מוצא פרטי כניסה מהמשאב שבו הקוד פועל (למשל מכונה וירטואלית ב-Compute Engine). תוכלו גם להשתמש ב-ADC כדי לבצע אימות בסביבת פיתוח מקומית. במקרה הזה, ב-CLI של gcloud נוצר קובץ שמכיל את פרטי הכניסה שלכם במערכת הקבצים המקומית.

  • פרטי הכניסה שקיבלתם באמצעות התחזות לחשבון שירות.

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

  • פרטי הכניסה שהוחזרו על ידי שרת המטא-נתונים.

    ה-method הזה פועל רק בסביבות עם גישה לשרת מטא-נתונים. פרטי הכניסה שמוחזרים על ידי שרת המטא-נתונים הם אותם פרטי כניסה ששירות Application Default Credentials יכול למצוא באמצעות חשבון השירות המצורף, אבל אתם שולחים לשרת המטא-נתונים בקשה מפורשת לאסימון הגישה ולאחר מכן מספקים אותו בבקשת ה-REST. כדי לשלוח בקשה לפרטי הכניסה לשרת המטא-נתונים, צריך לשלוח בקשת HTTP GET. ה-method הזה לא מסתמך על Google Cloud CLI.

  • מפתחות API

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

פרטי כניסה ל-CLI של gcloud

כדי להריץ את הדוגמה הבאה, צריכה להיות לכם ההרשאה resourcemanager.projects.get בפרויקט. ההרשאה resourcemanager.projects.get כלולה בתפקידים שונים, כמו תפקיד Browser‏ (roles/browser).

  1. כדי להוסיף אסימון גישה שנוצר באמצעות פרטי הכניסה שלכם, משתמשים בפקודה gcloud auth print-access-token.

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

    לפני שמשתמשים בנתוני הבקשה, צריך להחליף את הנתונים הבאים:

    • PROJECT_ID: מזהה הפרויקט או השם שלך ב- Google Cloud .

    כדי לשלוח את הבקשה אתם צריכים לבחור אחת מהאפשרויות הבאות:

    curl

    מריצים את הפקודה הבאה: 

    curl -X GET \
         -H "Authorization: Bearer $(gcloud auth print-access-token)" \
         "https://cloudresourcemanager.googleapis.com/v3/projects/PROJECT_ID"

    PowerShell

    מריצים את הפקודה הבאה: 

    $cred = gcloud auth print-access-token
    $headers = @{ "Authorization" = "Bearer $cred" }

    Invoke-WebRequest `
        -Method GET `
        -Headers $headers `
        -Uri "https://cloudresourcemanager.googleapis.com/v3/projects/PROJECT_ID" | Select-Object -Expand Content

    הפרטים של הפרויקט יוחזרו מהפקודה.

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

Application Default Credentials

כדי להריץ את הדוגמה הבאה, לחשבון המשתמש שמשויך לפרטי הכניסה שאתם מספקים ל-ADC צריכה להיות ההרשאה resourcemanager.projects.get בפרויקט. ההרשאה resourcemanager.projects.get כלולה בתפקידים שונים, כמו תפקיד Browser‏ (roles/browser).

  1. מספקים פרטי כניסה ל-ADC.

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

  2. כדי לשלוח בקשת REST באמצעות ADC, הבקשה צריכה לכלול את אסימון הגישה. תוכלו לקבל את אסימון הגישה באמצעות הפקודה gcloud auth application-default print-access-token.

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

    לפני שמשתמשים בנתוני הבקשה, צריך להחליף את הנתונים הבאים:

    • PROJECT_ID: מזהה הפרויקט או השם שלך ב- Google Cloud .

    כדי לשלוח את הבקשה אתם צריכים לבחור אחת מהאפשרויות הבאות:

    curl

    מריצים את הפקודה הבאה: 

    curl -X GET \
         -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
         "https://cloudresourcemanager.googleapis.com/v3/projects/PROJECT_ID"

    PowerShell

    מריצים את הפקודה הבאה: 

    $cred = gcloud auth application-default print-access-token
    $headers = @{ "Authorization" = "Bearer $cred" }

    Invoke-WebRequest `
        -Method GET `
        -Headers $headers `
        -Uri "https://cloudresourcemanager.googleapis.com/v3/projects/PROJECT_ID" | Select-Object -Expand Content

    הפרטים של הפרויקט יוחזרו מהפקודה.

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

חשבון שירות שבוצעה אליו התחזות

הדרך הכי פשוטה להתחזות לחשבון שירות כדי ליצור אסימון גישה היא באמצעות ה-CLI של gcloud. עם זאת, אם אתם צריכים ליצור את האסימון באופן פרוגרמטי, או אם אתם לא רוצים להשתמש ב-CLI של gcloud, אתם יכולים להשתמש בהתחזות כדי ליצור אסימון לטווח קצר.

אפשר לקרוא מידע נוסף על התחזות לחשבון שירות במאמר שימוש בהתחזות לחשבון שירות.

  1. בודקים מהן ההרשאות הנדרשות.

    • לחשבון המשתמש שבו רוצים להשתמש כדי לבצע את ההתחזות צריכה להיות ההרשאה iam.serviceAccounts.getAccessToken בחשבון השירות שאליו הוא מתחזה (נקרא גם חשבון השירות שנושא את ההרשאות). ההרשאה iam.serviceAccounts.getAccessToken כלולה בתפקיד 'יצירת אסימונים בחשבון שירות' (roles/iam.serviceAccountTokenCreator). אם אתם משתמשים בחשבון משתמש, אתם צריכים להוסיף את ההרשאה הזו גם אם הוקצה לכם התפקיד 'בעלים' (roles/owner) בפרויקט. מידע נוסף מופיע במאמר בנושא הגדרה של ההרשאות הנדרשות.

  2. מאתרים או יוצרים את חשבון השירות שנושא את ההרשאות – חשבון השירות שאתם רוצים להתחזות אליו.

    לחשבון השירות שנושא את ההרשאות צריכות להיות ההרשאות הנדרשות לביצוע הפעלת ה-method של ה-API.

gcloud

  1. כדי להכניס אסימון גישה לחשבון השירות שנושא את ההרשאות לתוך בקשת ה-REST, משתמשים בפקודה gcloud auth print-access-token עם הדגל --impersonate-service-account.

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

כדי להריץ את הדוגמה הזו, צריך לשייך לחשבון השירות שאליו מתחזים את ההרשאה resourcemanager.projects.get. ההרשאה resourcemanager.projects.get כלולה בתפקידים שונים, כמו תפקיד Browser‏ (roles/browser).

מחליפים את הפרטים הבאים:

  • PRIV_SA: כתובת האימייל של חשבון השירות שנושא את ההרשאות. לדוגמה, my-sa@my-project.iam.gserviceaccount.com.

  • PROJECT_ID: מזהה הפרויקט או השם שלך ב- Google Cloud .

curl -X GET \
    -H "Authorization: Bearer $(gcloud auth print-access-token --impersonate-service-account=PRIV_SA)" \
    "https://cloudresourcemanager.googleapis.com/v3/projects/PROJECT_ID"

טוקן לטווח קצר

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

שרת מטא-נתונים

כדי לקבל אסימון גישה משרת המטא-נתונים, צריך ליצור את הקריאה ל-REST באמצעות אחד מהשירותים שיש להם גישה לשרת המטא-נתונים:

משתמשים בכלי שורת הפקודה כמו curl כדי לקבל אסימון גישה, ומכניסים אותו לבקשת ה-REST.

  1. שולחים לשרת המטא-נתונים שאילתה לאסימון גישה:

    curl "http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/default/token" \
    -H "Metadata-Flavor: Google"

    בתגובה לבקשה מוחזרת תשובה שדומה לדוגמה הבאה:

    {
      "access_token":"ya29.AHES6ZRN3-HlhAPya30GnW_bHSb_QtAi85nHq39HE3C2LTrCARA",
      "expires_in":3599,
      "token_type":"Bearer"
 }

  2. מוסיפים את אסימון הגישה לבקשת ה-REST, ומחליפים את הפרטים הבאים:

    • ACCESS_TOKEN: אסימון הגישה שהוחזר בשלב הקודם.
    • PROJECT_ID: מזהה הפרויקט או השם שלך ב- Google Cloud .
    curl -X GET \
    -H "Authorization: Bearer ACCESS_TOKEN" \
    "https://cloudresourcemanager.googleapis.com/v3/projects/PROJECT_ID"

מפתחות API

כדי לכלול מפתח API בקריאה ל-API בארכיטקטורת REST, משתמשים בכותרת ה-HTTP‏ x-goog-api-key, כמו בדוגמה הבאה:

curl -X POST \
    -H "X-goog-api-key: API_KEY" \
    -H "Content-Type: application/json; charset=utf-8" \
    -d @request.json \
    "https://translation.googleapis.com/language/translate/v2"

אם אי אפשר להשתמש בכותרת HTTP, אפשר להשתמש בפרמטר השאילתה key. עם זאת, השיטה הזו כוללת את מפתח ה-API בכתובת ה-URL, ולכן המפתח חשוף לגניבה באמצעות סריקות של כתובות URL.

בדוגמה הבאה מוצג אופן השימוש בפרמטר השאילתה key עם בקשת Cloud Natural Language API עבור documents.analyzeEntities. מחליפים את הערך API_KEY במחרוזת המפתח של מפתח ה-API.

POST https://language.googleapis.com/v1/documents:analyzeEntities?key=API_KEY

הגדרה של פרויקט לצורכי מכסה בבקשת REST

בחלק מממשקי API לא ניתן להשתמש בפרטי כניסה של משתמשים, אם לא מגדירים גם את הפרויקט שמחויב על השימוש ומשמש למעקב אחרי המכסות. אם בתגובה לקריאה ל-API מוחזרת הודעת שגיאה שבה כתוב שאין תמיכה בפרטי הכניסה של המשתמשים או שלא הוגדרה מכסה בפרויקט, אתם צריכים להגדיר במפורש את המכסה בפרויקט. כדי להגדיר את המכסה בפרויקט, הבקשה צריכה לכלול את הכותרת x-goog-user-project.

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

כדי להשתמש בפרויקט לחיוב צריך ב-IAM את ההרשאה serviceusage.services.use. ההרשאה serviceusage.services.use כלולה בתפקיד 'Service Usage Consumer' ב-IAM. אם אין לכם את ההרשאה serviceusage.services.use לאף פרויקט, צרו קשר עם אדמין האבטחה או עם Project Owner שיוכל להקצות לכם את התפקיד Service Usage Consumer בפרויקט.

בדוגמה הבאה נשתמש ב-Cloud Translation API כדי לתרגם את המילה 'hello' לספרדית. ‏Cloud Translation API הוא ממשק API שצריך לציין בו מכסה בפרויקט. כדי להריץ את הדוגמה, אתם צריכים ליצור קובץ בשם request.json עם תוכן הבקשה.

לפני שמשתמשים בנתוני הבקשה, צריך להחליף את הנתונים הבאים:

  • PROJECT_ID: השם או המזהה של הפרויקט ב- Google Cloud שישמש כפרויקט לחיוב.

תוכן בקשת JSON: 

{
  "q": "hello",
  "source": "en",
  "target": "es"
}

כדי לשלוח את הבקשה עליכם לבחור אחת מהאפשרויות הבאות:

curl

שומרים את גוף הבקשה בקובץ בשם request.json ומריצים את הפקודה הבאה: 

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "x-goog-user-project: PROJECT_ID" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://translation.googleapis.com/language/translate/v2"

PowerShell

שומרים את גוף הבקשה בקובץ בשם request.json ומריצים את הפקודה הבאה: 

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred"; "x-goog-user-project" = "PROJECT_ID" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://translation.googleapis.com/language/translate/v2" | Select-Object -Expand Content

בקשת התרגום מסתיימת בהצלחה. כדאי לנסות להריץ את הפקודה בלי כותרת ה-HTTP‏ x-goog-user-project כדי לראות מה קורה כשלא מציינים את הפרויקט לחיוב.

המאמרים הבאים