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

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

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

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

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

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

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