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

בדף הזה מופיע מידע כללי על פתרון בעיות ב-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 עם זמן אחזור ארוך

בדומה ל-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.