העברת נתונים אל שירות לקצה העורפי וממנו

כשלקוח API שולח בקשה ל-API שנפרס ב-API Gateway, הלקוח יכול להעביר חלק מהפרטים הבאים או את כולם כחלק מהבקשה:

• כותרות של בקשות
• פרמטרים של שאילתה
• נתוני טופס
• מטענים ייעודיים (payloads) בפורמט XML או JSON
• נתיבים של בקשות

בתגובה לבקשת ה-API, שירות לקצה העורפי יכול להחזיר נתונים ללקוח ה-API, כולל:

• כותרות תגובה
• מטענים ייעודיים (payloads) בפורמט XML או JSON

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

איך נתוני הבקשה מועברים לשירות לקצה העורפי?

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

איך נתוני התגובה מוחזרים ללקוח ה-API?

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

איך כתובת ה-URL של הבקשה מועברת לשירות הקצה העורפי?

כתובת האתר שמשמשת לשליחת בקשה לשירות הקצה העורפי נשלטת על ידי התוסף x-google-backend. בקטע הזה מתוארות האפשרויות להגדרת כתובת ה-URL של שירות לקצה העורפי.

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

במפרט OpenAPI שבו אתם משתמשים כדי ליצור הגדרת API, אתם משתמשים בתוסף x-google-backend כדי לציין את כתובת ה-URL של שירות לקצה העורפי. לדוגמה, מציינים את שירות לקצה העורפי בפורמט:

בק-אנד	x-google-backend
פונקציות Cloud Run	x-google-backend: address: https://GCP_REGION-PROJECT_ID.cloudfunctions.net/hello
Cloud Run	אחת מהאפשרויות הבאות: x-google-backend: address: APP_URL x-google-backend: address: DETERMINISTIC_URL
סביבה רגילה של App Engine	x-google-backend: address: https://PROJECT_ID.appspot.com

בדוגמאות האלו:

• ‫APP_URL מציין את כתובת ה-URL בפועל של שירות Cloud Run (הנתיב המלא של ה-API שנקרא), שנקראת גם כתובת URL לא דטרמיניסטית. לדוגמה: https://hello-abc1def2gh-uc.a.run.app.
• ‫DETERMINISTIC_URL היא כתובת ה-URL הדטרמיניסטית של הקצה העורפי של שירות Cloud Run.

הערה: אם אתם מתכננים להשתמש בכתובת URL דטרמיניסטית כדי ליצור גרסאות של העורף של שירות Cloud Run, אתם צריכים לציין אחת מהאפשרויות הבאות:

• ‫Open API 2.0: השדה jwt_audience בקטע address מתחת ל-x-google-backend
• ‫Open API 3.0: השדה jwtAudience בקטע address מתחת ל-x-google-api-management

הערך בשדה jwt_audience או jwtAudience צריך להיות שם המארח של שירות Cloud Run. לדוגמה, עבור OpenAPI 2.0:

...
  x-google-backend:
      address: https://VERSION_TAG---SERVICE_HOSTNAME/PATH
      jwt_audience: https://SERVICE_HOSTNAME
...

אם השדה jwt_audience או השדה jwtAudience לא מופיעים, ערך ברירת המחדל של השדה הוא הערך של השדה address עבור טענת הקהל של JWT. אם משתמשים בכתובת ה-URL של תג הגרסה ל-address ולא מציינים jwt_audience או jwtAudience, יכול להיות ש-Cloud Run יחזיר הצהרת קהל לא צפויה של JWT.

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

נתיב	נתיב עם פרמטרים
paths: /hello:	paths: /hello/{name}:

יצירת כתובת ה-URL של שירות הקצה העורפי מבקשת API

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

האפשרות path_translation בתוסף x-google-backend תומכת בשתי שיטות לתרגום נתיבים:

• ‫APPEND_PATH_TO_ADDRESS: כתובת ה-URL של שירות הקצה העורפי נוצרת על ידי צירוף נתיב המשאב מהבקשה של הלקוח לכתובת ה-URL של address של התוסף x-google-backend.

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

• ‫CONSTANT_ADDRESS: כתובת ה-URL של שירות לקצה העורפי קבועה, כפי שהוגדרה על ידי כתובת ה-URL של התוסף x-google-backend address. אם בקשת הלקוח מכילה נתיב למשאב, הנתיב למשאב מתווסף לכתובת ה-URL של שירות לקצה העורפי באמצעות פרמטרים של שאילתה.

  בדרך כלל משתמשים בשיטה הזו בפונקציות Cloud Run.

לדוגמה:

• APPEND_PATH_TO_ADDRESS
  • address: https://PROJECT_ID.appspot.com
  • ללא פרמטרים של נתיב OpenAPI:
    • נתיב OpenAPI: /hello
    • נתיב המשאב של בקשת לקוח ה-API: ‏ /hello
    • כתובת ה-URL של הבקשה לשירות לקצה העורפי: https://PROJECT_ID.appspot.com/hello
  • עם פרמטרים של נתיב OpenAPI:
    • נתיב OpenAPI: /hello/{name}
    • נתיב המשאב של בקשת לקוח ה-API: ‏ /hello/Dave
    • כתובת ה-URL של הבקשה לשירות לקצה העורפי: https://PROJECT_ID.appspot.com/hello/Dave
• CONSTANT_ADDRESS
  • address: https://GCP_REGION-PROJECT_ID.cloudfunctions.net/hello
  • ללא פרמטרים של נתיב OpenAPI
    • נתיב OpenAPI: /hello
    • נתיב המשאב של בקשת לקוח ה-API: ‏ /hello
    • כתובת ה-URL של הבקשה לשירות לקצה העורפי: https://GCP_REGION-PROJECT_ID.cloudfunctions.net/hello
  • עם פרמטרים של נתיב OpenAPI
    • נתיב OpenAPI: /hello/{name}
    • נתיב המשאב של בקשת לקוח ה-API: ‏ /hello/Dave
    • כתובת ה-URL של הבקשה לשירות לקצה העורפי: https://GCP_REGION-PROJECT_ID.cloudfunctions.net/hello?name=Dave

הגדרת path_translation

הגדרת path_translation כחלק מהגדרת x-google-backend:

x-google-backend:
  address: https://GCP_REGION-PROJECT_ID.cloudfunctions.net/hello
  path_translation: [ APPEND_PATH_TO_ADDRESS | CONSTANT_ADDRESS ]`

ערך ברירת המחדל של path_translation תלוי במיקום שבו מגדירים את x-google-backend במפרט OpenAPI:

• כשמשתמשים ב-x-google-backend ברמה העליונה של מפרט OpenAPI, ערך ברירת המחדל של path_translation הוא APPEND_PATH_TO_ADDRESS.

• כשמשתמשים ב-x-google-backend ברמת הפעולה של מפרט OpenAPI, ברירת המחדל של path_translation היא CONSTANT_ADDRESS.