סקירה כללית על פתרון בעיות

בדף הזה מופיע מידע כללי על פתרון בעיות ב-API Gateway.

אי אפשר להריץ פקודות של gcloud api-gateway

כדי להריץ את הפקודות gcloud api-gateway ..., צריך לעדכן את Google Cloud CLI ולהפעיל את שירותי Google הנדרשים. מידע נוסף מופיע במאמר הגדרת סביבת הפיתוח.

הפקודה gcloud api-gateway api-configs create מציינת שחשבון השירות לא קיים

אם מריצים את הפקודה gcloud api-gateway api-configs create ... ומופיעה שגיאה מהסוג הבא:

ERROR: (gcloud.api-gateway.api-configs.create) FAILED_PRECONDITION:
Service Account "projects/-/serviceAccounts/service_account_email" does not exist

מריצים מחדש את הפקודה, אבל הפעם כוללים את האפשרות --backend-auth-service-account כדי לציין במפורש את כתובת האימייל של חשבון השירות שבו רוצים להשתמש:

gcloud api-gateway api-configs create CONFIG_ID \
  --api=API_ID --openapi-spec=API_DEFINITION \
  --backend-auth-service-account=SERVICE_ACCOUNT_EMAIL

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

קביעת המקור של תגובות שגיאה ב-API

אם בקשות ל-API שפרסתם מובילות לשגיאה (קודי סטטוס HTTP‏ 400 עד 599), יכול להיות שלא יהיה ברור מהתגובה עצמה אם השגיאה נובעת מהשער או מהקצה העורפי. כדי לדעת את זה:

  1. עוברים לדף Logs Explorer ובוחרים את הפרויקט.

    כניסה לדף Logs Explorer

  2. כדי לסנן את משאב השער הרלוונטי, משתמשים בשאילתת היומן הבאה:

    resource.type="apigateway.googleapis.com/Gateway"
resource.labels.gateway_id="GATEWAY_ID"
resource.labels.location="GCP_REGION"

    כאשר:

    • ‫GATEWAY_ID מציין את שם השער.
    • ‫GCP_REGION הוא Google Cloud האזור שבו נפרס שער.

  3. מחפשים את רשומת היומן שתואמת לתגובת השגיאה של HTTP שרוצים לבדוק. לדוגמה, סינון לפי httpRequest.status.

  4. בודקים את התוכן של השדה jsonPayload.responseDetails.

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

בקשת API מחזירה שגיאת HTTP 403

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

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

אם הגדרתם את ה-API ואת שירות לקצה העורפי באותו פרויקט ב-Google Cloud, צריך לוודא שחשבון השירות קיבל את התפקיד Editor או את התפקיד שנדרש לגישה לשירות לקצה העורפי. לדוגמה, אם שירות לקצה העורפי מיושם באמצעות פונקציות של Cloud Run, צריך לוודא שהתפקיד Cloud Function Invoker מוקצה לחשבון השירות.

בקשת API מחזירה שגיאת HTTP 401 או 500

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

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

אם חשבון השירות נמחק או מושבת אחרי פריסת השער, יכול להיות שיתרחש רצף האירועים הבא:

  1. מיד אחרי שחשבון השירות נמחק או מושבת, יכול להיות שתראו תגובות HTTP 401 ביומני השער שלכם. אם השדה jsonPayload.responseDetails מוגדר לערך "via_upstream" ב-jsonPayload של רשומת היומן, המשמעות היא שהשגיאה נגרמת בגלל מחיקה או השבתה של חשבון השירות.

  2. יכול להיות שתוצג גם שגיאת HTTP 500 ללא רשומה תואמת ביומני הרישום של API Gateway. אם אין בקשות לשער מיד אחרי המחיקה או ההשבתה של חשבון השירות, יכול להיות שלא תראו את התגובות מסוג HTTP 401, אבל שגיאות HTTP 500 ללא יומני שער API תואמים מצביעות על כך שחשבון השירות של השער כבר לא פעיל.

אם ה-backend של הבקשה שנכשלה הוא API אחר של Google Cloud (כמו bigquery.googleapis.com), יופיעו תגובות HTTP 401 ביומני השער עם השדה jsonPayload.responseDetails שמוגדר ל-"via_upstream". הסיבה לכך היא ש-API Gateway מבצע אימות לבק-אנד באמצעות אסימון מזהה, בעוד שממשקי API אחרים Google Cloud דורשים אסימון גישה.

בקשת API מחזירה שגיאת HTTP 500 עבור שיטה שמוגבלת על ידי מכסה

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

HTTP/2 500
{"code":500,"message":"Failed to call Service Control Quota."}

השגיאה הזו מתרחשת בדרך כלל כשקוראים לשיטה שהוגדרה לה מכסה, אבל מדדי המכסה כבר לא קיימים ב-API. ב-gRPC gateway, אותו כשל מוחזר כקוד הסטטוס של gRPC‏ Internal.

בודקים את הסיבה ביומני השער

  1. עוברים לדף Logs Explorer ובוחרים את הפרויקט.

    כניסה לדף Logs Explorer

  2. מריצים את השאילתה הבאה ביומן:

    resource.type="apigateway.googleapis.com/Gateway"
resource.labels.gateway_id="GATEWAY_ID"
jsonPayload.responseDetails="service_control_quota_error"
httpRequest.status=500

    כאשר GATEWAY_ID מציין את שם השער.

    המסננים של השאילתה מבוססים על קוד הסטטוס וגם על jsonPayload.responseDetails, כי API Gateway משתמש באותו ערך responseDetails לכל דחייה של מכסה. אם בקשה חורגת מהמכסה באופן לגיטימי, הערך שמוחזר הוא אותו ערך עם httpRequest.status של 429.

  3. בודקים את השדות jsonPayload.apiConfig ו-jsonPayload.apiMethod של כל רשומה תואמת. הם מזהים את הגדרת ה-API ואת השיטה שהגדרת המכסה שלה לא תקינה.

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

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

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

לדוגמה, הרצף הבא משאיר את השער הראשון פגום:

  1. יוצרים הגדרת API‏ config-v1, שמצהירה על המדד quota-metric-v1, ופורסים אותה ב-gateway-1.
  2. יוצרים הגדרת API‏ config-v2 לאותו API, שמצהירה על המדד quota-metric-v2, ומפרסים אותה אל gateway-2.

‫gateway-2 פועל, אבל הבקשות לשיטות של gateway-1 שמוגבלות על ידי מכסת השימוש מתחילות להיכשל, כי quota-metric-v1 כבר לא מוגדר עבור ה-API.

השינויים הבאים יכולים לגרום לשגיאות בכל שער שעדיין פרוס עם הגדרת API קודמת:

  • שינוי שם או הסרה של מדד.
  • שינוי המדד שאליו חלה מגבלת המכסה.
  • שינוי המדד שנקרא בעלויות של מכסת שימוש לכל שיטה (x-google-quota למסמכי OpenAPI או quota.metric_rules להגדרות שירות gRPC).

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

השוואה בין הגדרות המכסה שפריסתן הושלמה

  1. מציגים את רשימת השערים ואת הגדרות ה-API שכל אחד מהם משרת:

    gcloud api-gateway gateways list \
 --format="table(name.basename(),apiConfig)"

  2. מציגים את הגדרות ה-API של ה-API המושפע, כשההגדרה האחרונה שנוצרה מוצגת ראשונה:

    gcloud api-gateway api-configs list --api=API_ID \
 --format="table(name.basename(),createTime:sort=1:reverse)"

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

  3. הצגת הגדרת ה-API שממנה נוצרה הגדרת ה-API:

    gcloud api-gateway api-configs describe CONFIG_ID --api=API_ID \
 --view=FULL --format="value(openapiDocuments[0].document.contents)" \
 | tr '_-' '/+' | base64 --decode

    הפקודה tr נדרשת כי השדה contents מקודד ב-base64url, ו-base64 --decode לא יכול לקרוא אותו ישירות.

    ב-gRPC API, הגדרת המכסה נמצאת בהגדרת השירות ולא במסמך OpenAPI, ולכן צריך להחליף את openapiDocuments[0].document.contents ב-managedServiceConfigs[0].contents.

  4. מריצים את הפקודה משלב 3 עבור הגדרת ה-API בחלק העליון של הרשימה משלב 2, ואז עבור כל אחת מהגדרות ה-API האחרות שמופיעות בשלב 1 כהגדרות שעדיין פרוסות בשער.

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

שחזור של הגדרת מכסה תקינה

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

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

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

בקשות API עם זמן אחזור ארוך

בדומה ל-Cloud Run ולפונקציות Cloud Run, ל-API Gateway יש השהיה של 'הפעלה במצב התחלתי (cold start)'. אם השער לא קיבל תעבורת נתונים במשך 15 עד 20 דקות, בקשות שנשלחות לשער במהלך 10 עד 15 השניות הראשונות של ההפעלה במצב התחלתי (cold start) יחוו זמן טעינה של 3 עד 5 שניות.

אם הבעיה נמשכת אחרי תקופת ההפעלה הראשונית, כדאי לבדוק את יומני הבקשות של שירותי ה-Backend שהגדרתם בהגדרות ה-API. לדוגמה, אם שירות לקצה העורפי מיושם באמצעות פונקציות Cloud Run, כדאי לבדוק את הרשומות ב-Cloud Logging של יומן הבקשות של Cloud Functions שמשויך לשירות.

לא ניתן להציג את פרטי היומן

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

כדי להשתמש ב-API Gateway, צריך להפעיל את השירותים הבאים של Google Cloud :

שם שם השירות
API Gateway API apigateway.googleapis.com
Service Management API servicemanagement.googleapis.com
Service Control API servicecontrol.googleapis.com

כדי להפעיל את השירותים הנדרשים:

מסוף Google Cloud

  1. במסוף Google Cloud , נכנסים לדף APIs & Services > API Library.

    לדף API Library

  2. בדף API Library, מזינים את שם ה-API הנדרש בסרגל החיפוש.
  3. בתוצאות החיפוש, בוחרים את דף ה-API.
  4. בדף ה-API, לוחצים על הפעלה.
  5. חוזרים על השלבים האלה לכל אחד מהשירותים שמפורטים בטבלה הקודמת.

Google Cloud CLI

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

gcloud services enable apigateway.googleapis.com
gcloud services enable servicemanagement.googleapis.com
gcloud services enable servicecontrol.googleapis.com

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