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

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

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

  • צוין בבקשה: הפרויקט לצורכי מכסה שצוין בבקשה. (כשמשתמשים בספריות לקוח, אפשר גם להשתמש במשתני סביבה בבקשות).

  • מפתח API: אם משתמשים במפתח API כדי לספק פרטי כניסה לבקשה, הפרויקט שמשויך למפתח ה-API משמש כפרויקט המכסה.

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

  • חשבון שירות: אם החשבון הראשי של הקריאה ל-API הוא חשבון שירות, כולל באמצעות התחזות, הפרויקט שמשויך לחשבון השירות משמש כפרויקט המכסה.

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

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

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

  1. באופן פרוגרמטי
  2. משתנה הסביבה
  3. פרטי הכניסה שמשמשים לאימות הבקשה

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

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

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

ספריית לקוח

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

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

‫CLI של gcloud

אפשר להגדיר את פרויקט המכסה לכל הפקודות ב-CLI של gcloud באמצעות המאפיין billing/quota_project בהגדרות האישיות של ה-CLI של gcloud. אפשר גם להגדיר את פרויקט המכסה לפקודה ספציפית באמצעות הדגל --billing-project, שמקבל קדימות על פני מאפיין ההגדרה.

מידע נוסף על הגדרות אישיות של gcloud CLI זמין במסמכי התיעוד של gcloud config. מידע נוסף על הדגל --billing-project זמין במאמרי העזרה בנושא --billing-project.

בקשת REST

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

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

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

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

משתנה הסביבה תלוי בשפה:

שפה משתנה הסביבה
C++‎

GOOGLE_CLOUD_CPP_USER_PROJECT

C#‎

GOOGLE_CLOUD_QUOTA_PROJECT

Go

GOOGLE_CLOUD_QUOTA_PROJECT

Java

GOOGLE_CLOUD_QUOTA_PROJECT

Node.js

GOOGLE_CLOUD_QUOTA_PROJECT

Python

GOOGLE_CLOUD_QUOTA_PROJECT

PHP

GOOGLE_CLOUD_QUOTA_PROJECT

Ruby לא זמין

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

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

  • חשבון שירות – הפרויקט שמשויך לחשבון השירות משמש כפרויקט המכסה.
  • פרטי כניסה של משתמש – בסביבת פיתוח מקומית, Application Default Credentials מאתר את פרטי הכניסה של המשתמש בקובץ ה-ADC המקומי. בקובץ הזה אפשר גם לציין פרויקט מכסה. אם הפרויקט מוגדר בקובץ ההגדרות של Google Cloud CLI ויש לכם את ההרשאות הנדרשות בפרויקט הזה, פרויקט המכסה מוגדר כברירת מחדל כשיוצרים את קובץ ה-ADC המקומי. אפשר גם להגדיר את פרויקט מכסת ה-ADC באמצעות הפקודה auth application-default set-quota-project.
  • מפתחות API – כשמשתמשים במפתח API כדי לספק פרטי כניסה לבקשה, הפרויקט שמשויך למפתח ה-API משמש כפרויקט המכסה.

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

כדי לקבל את ההרשאה שנדרשת להגדרת פרויקט כפרויקט מכסה או לשימוש בפרויקט מכסה בבקשה, צריך לבקש מהאדמין להקצות לכם ב-IAM את התפקיד צרכן של שימוש בשירות (roles/serviceusage.serviceUsageConsumer) בפרויקט. להסבר על מתן תפקידים, ראו איך מנהלים את הגישה ברמת הפרויקט, התיקייה והארגון.

התפקיד המוגדר מראש הזה כולל את ההרשאה serviceusage.services.use, שנדרשת כדי להגדיר פרויקט כפרויקט מכסת המכסות, או כדי להשתמש בפרויקט מכסת המכסות הזה בבקשה.

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

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

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

הגדרת משתמש המכסה

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

כברירת מחדל, המערכת משתמשת בישות המאומתת. אם אין חשבון משתמש מאומת, המערכת משתמשת בכתובת ה-IP של הלקוח.

אם אתם צריכים לבטל את המכסה למשתמש, אתם יכולים להגדיר את הפרמטר quotaUser דרך פרמטרים של מערכת ב-Cloud API. אם מציינים את quotaUser או X-Goog-Quota-User, צריך להשתמש במפתח API תקין עם הגבלות על כתובות IP כדי לזהות את הפרויקט שמוגדרת בו מכסה. אחרת, המערכת מתעלמת מהפרמטר quotaUser.

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

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