אימות לשימוש ב-REST

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

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

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

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

  1. Install the Google Cloud CLI.

  2. Configure the gcloud CLI to use your federated identity.

    For more information, see Sign in to the gcloud CLI with your federated identity.

  3. To initialize the gcloud CLI, run the following command: 

    gcloud init

  4. Enable the Cloud Resource Manager and Identity and Access Management (IAM) APIs:

    Roles required to enable APIs

    To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles. 

    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: מזהה הפרויקט או השם שלכם ב- Cloud de Confiance by S3NS .

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

    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.

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

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

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

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

    • PROJECT_ID: מזהה הפרויקט או השם שלכם ב- Cloud de Confiance by S3NS .

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

    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.s3ns.iam.gserviceaccount.com.

  • PROJECT_ID: מזהה הפרויקט או השם שלכם ב- Cloud de Confiance by S3NS .

curl -X GET \
    -H "Authorization: Bearer $(gcloud auth print-access-token --impersonate-service-account=PRIV_SA)" \
    "https://cloudresourcemanager.s3nsapis.fr/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: מזהה הפרויקט או השם שלכם ב- Cloud de Confiance by S3NS .
    curl -X GET \
    -H "Authorization: Bearer ACCESS_TOKEN" \
    "https://cloudresourcemanager.s3nsapis.fr/v3/projects/PROJECT_ID"

מפתחות API

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

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

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

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

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

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

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

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

  • ‫PROJECT_ID: השם או המזהה של הפרויקט ב- Cloud de Confiance by S3NS שישמש כפרויקט לחיוב.

תוכן בקשת 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 כדי לראות מה קורה כשלא מציינים את הפרויקט לחיוב.

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