REST Resource: projects.locations.grpcRoutes

משאב: GrpcRoute

‫GrpcRoute הוא המשאב שמגדיר איך תנותב תנועת gRPC שמנותבת על ידי משאב Mesh או Gateway.

ייצוג ב-JSON
{
  "name": string,
  "selfLink": string,
  "createTime": string,
  "updateTime": string,
  "labels": {
    string: string,
    ...
  },
  "description": string,
  "hostnames": [
    string
  ],
  "meshes": [
    string
  ],
  "gateways": [
    string
  ],
  "rules": [
    {
      object (RouteRule)
    }
  ]
}
שדות
name

string

מזהה. השם של משאב ה-GrpcRoute. הוא תואם לתבנית projects/*/locations/*/grpcRoutes/<grpc_route_name>

createTime

string (Timestamp format)

פלט בלבד. חותמת הזמן של מועד יצירת המשאב.

השימוש הוא ב-RFC 3339, שבו הפלט שנוצר תמיד יהיה מנורמל ל-Z וישתמש ב-0, 3, 6 או 9 ספרות אחרי הנקודה העשרונית. אפשר להשתמש גם בהיסטים אחרים, לא רק ב-Z. לדוגמה: "2014-10-02T15:01:23Z", ‏ "2014-10-02T15:01:23.045123456Z" או "2014-10-02T15:01:23+05:30".

updateTime

string (Timestamp format)

פלט בלבד. חותמת הזמן של מועד העדכון של המשאב.

השימוש הוא ב-RFC 3339, שבו הפלט שנוצר תמיד יהיה מנורמל ל-Z וישתמש ב-0, 3, 6 או 9 ספרות אחרי הנקודה העשרונית. אפשר להשתמש גם בהיסטים אחרים, לא רק ב-Z. לדוגמה: "2014-10-02T15:01:23Z", ‏ "2014-10-02T15:01:23.045123456Z" או "2014-10-02T15:01:23+05:30".

labels

map (key: string, value: string)

זה שינוי אופציונלי. קבוצה של תגי תוויות שמשויכים למשאב GrpcRoute.

אובייקט שמכיל רשימה של זוגות "key": value. לדוגמה: { "name": "wrench", "mass": "1.3kg", "count": "3" }.

description

string

זה שינוי אופציונלי. תיאור של המשאב בטקסט חופשי. אורך מקסימלי של 1,024 תווים.

hostnames[]

string

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

פורמט: [:]

שם המארח הוא שם הדומיין שמוגדר במלואו של מארח ברשת. ההגדרה הזו תואמת להגדרה של שם מארח ב-RFC 1123, עם שני חריגים בולטים: - אסור להשתמש בכתובות IP. - שם מארח יכול להתחיל בתווית של תו כללי לחיפוש (*.). התווית של התו הכללי לחיפוש חייבת להופיע לבד בתור התווית הראשונה.

שם המארח יכול להיות "מדויק", כלומר שם דומיין בלי הנקודה בסוף של מארח רשת (למשל foo.example.com), או "תו כללי לחיפוש", כלומר שם דומיין עם תווית של תו כללי לחיפוש בתחילת השם (למשל *.example.com).

חשוב לזכור שבהתאם ל-RFC1035 ול-RFC1123, תווית חייבת להכיל תווים אלפאנומריים באותיות קטנות או "-", ולהתחיל ולהסתיים בתו אלפאנומרי. אסור להשתמש בסימני פיסוק אחרים.

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

לדוגמה, אפשר לשייך את הנתיבים של שמות המארחים *.foo.bar.com ו-*.bar.com לאותו נתיב, אבל אי אפשר לשייך שני נתיבים ל-*.bar.com או ל-bar.com.

אם צוינה יציאה, לקוחות gRPC חייבים להשתמש ב-URI של הערוץ עם היציאה כדי להתאים לכלל הזה (כלומר "xds:///service:123"), אחרת הם חייבים לספק את ה-URI בלי יציאה (כלומר "xds:///service").

meshes[]

string

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

כל הפניה לרשת צריכה להתאים לתבנית: projects/*/locations/*/meshes/<mesh_name>

gateways[]

string

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

כל הפניה לשער צריכה להתאים לתבנית: projects/*/locations/*/gateways/<gateway_name>

rules[]

object (RouteRule)

חובה. רשימה של כללים מפורטים שמגדירים איך לנתב את התנועה.

ב-GrpcRoute יחיד, יתבצע GrpcRoute.RouteAction שמשויך ל-GrpcRoute.RouteRule התואם הראשון. צריך לספק לפחות כלל אחד.

RouteRule

מתאר איך לנתב תנועה.

ייצוג ב-JSON
{
  "matches": [
    {
      object (RouteMatch)
    }
  ],
  "action": {
    object (RouteAction)
  }
}
שדות
matches[]

object (RouteMatch)

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

action

object (RouteAction)

חובה. כלל מפורט שמגדיר איך לנתב את התנועה. חובה למלא את השדה הזה.

RouteMatch

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

ייצוג ב-JSON
{
  "headers": [
    {
      object (HeaderMatch)
    }
  ],
  "method": {
    object (MethodMatch)
  }
}
שדות
headers[]

object (HeaderMatch)

זה שינוי אופציונלי. מציינת אוסף של כותרות להתאמה.

method

object (MethodMatch)

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

MethodMatch

מציין התאמה לשיטה.

ייצוג ב-JSON
{
  "type": enum (Type),
  "grpcService": string,
  "grpcMethod": string,
  "caseSensitive": boolean
}
שדות
type

enum (Type)

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

grpcService

string

חובה. שם השירות שצריך להתאים. אם לא מציינים שירות, המערכת תתאים את כל השירותים.

grpcMethod

string

חובה. שם ה-method שרוצים להתאים. אם לא מציינים שיטה, תהיה התאמה לכל השיטות.

caseSensitive

boolean

זה שינוי אופציונלי. מציין שההתאמות תלויות אותיות רישיות (case-sensitive). ערך ברירת המחדל הוא true. אסור להשתמש ב-caseSensitive עם סוג של REGULAR_EXPRESSION.

סוג

סוג ההתאמה.

טיפוסים בני מנייה (enum)
TYPE_UNSPECIFIED לא צוין.
EXACT ההתאמה תהיה רק לשם המדויק שצוין.
REGULAR_EXPRESSION הפרשנות של grpcMethod ו-grpcService תהיה כביטויים רגולריים. יש תמיכה בתחביר RE2.

HeaderMatch

התאמה לאוסף של כותרות.

ייצוג ב-JSON
{
  "type": enum (Type),
  "key": string,
  "value": string
}
שדות
type

enum (Type)

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

key

string

חובה. מפתח הכותרת.

value

string

חובה. ערך הכותרת.

סוג

סוג ההתאמה.

טיפוסים בני מנייה (enum)
TYPE_UNSPECIFIED לא צוין.
EXACT התאמה רק לערך המדויק שצוין.
REGULAR_EXPRESSION התאמה לנתיבים שתואמים לקידומת שצוינה בערך. יש תמיכה בתחביר RE2.

RouteAction

מציינת איך לנתב תנועה תואמת.

ייצוג ב-JSON
{
  "destinations": [
    {
      object (Destination)
    }
  ],
  "faultInjectionPolicy": {
    object (FaultInjectionPolicy)
  },
  "timeout": string,
  "retryPolicy": {
    object (RetryPolicy)
  },
  "statefulSessionAffinity": {
    object (StatefulSessionAffinityPolicy)
  },
  "idleTimeout": string
}
שדות
destinations[]

object (Destination)

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

faultInjectionPolicy

object (FaultInjectionPolicy)

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

לקוחות שהוגדרו עם faultInjectionPolicy יתעלמו מ-timeout ומ-retryPolicy

timeout

string (Duration format)

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

משך זמן בשניות עם עד תשע ספרות אחרי הנקודה העשרונית, שמסתיים ב-"s". לדוגמה: "3.5s".

retryPolicy

object (RetryPolicy)

זה שינוי אופציונלי. מציינת את מדיניות הניסיונות החוזרים שמשויכת לנתיב הזה.

statefulSessionAffinity

object (StatefulSessionAffinityPolicy)

זה שינוי אופציונלי. מציין זיקה לסשן (session affinity) עם שמירת מצב (stateful) שמבוססת על קובצי Cookie.

idleTimeout

string (Duration format)

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

משך זמן בשניות עם עד תשע ספרות אחרי הנקודה העשרונית, שמסתיים ב-"s". לדוגמה: "3.5s".

יעד

היעד שאליו תנותב התנועה.

ייצוג ב-JSON
{

  // Union field destination_type can be only one of the following:
  "serviceName": string
  // End of list of possible types for union field destination_type.
  "weight": integer
}
שדות
שדה של איחוד destination_type. מציין את סוג היעד שאליו תנותב התנועה. הערך destination_type יכול להיות רק אחד מהבאים:
serviceName

string

חובה. כתובת ה-URL של שירות היעד שאליו תנותב התנועה. חייב להפנות אל BackendService או אל ServiceDirectoryService.

weight

integer

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

אם מציינים רק serviceName אחד והמשקל שלו גדול מ-0, 100% מהתנועה מועברת לקצה העורפי הזה.

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

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

FaultInjectionPolicy

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

ייצוג ב-JSON
{
  "delay": {
    object (Delay)
  },
  "abort": {
    object (Abort)
  }
}
שדות
delay

object (Delay)

המפרט להוספת השהיה לבקשות של לקוחות.

abort

object (Abort)

המפרט לביטול בקשות של לקוחות.

השהיה

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

ייצוג ב-JSON
{
  "fixedDelay": string,
  "percentage": integer
}
שדות
fixedDelay

string (Duration format)

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

משך זמן בשניות עם עד תשע ספרות אחרי הנקודה העשרונית, שמסתיים ב-"s". לדוגמה: "3.5s".

percentage

integer

אחוז התנועה שבה יוזרק עיכוב.

הערך צריך להיות בין [0, 100]

ביטול

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

ייצוג ב-JSON
{
  "httpStatus": integer,
  "percentage": integer
}
שדות
httpStatus

integer

קוד הסטטוס של HTTP שמשמש לביטול הבקשה.

הערך צריך להיות בין 200 ל-599 (כולל).

percentage

integer

אחוז התנועה שתבוטל.

הערך צריך להיות בין [0, 100]

RetryPolicy

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

ייצוג ב-JSON
{
  "retryConditions": [
    string
  ],
  "numRetries": integer
}
שדות
retryConditions[]

string

  • ‫connect-failure: הנתב ינסה שוב במקרה של כשלים בחיבור לשירותים לקצה העורפי, למשל בגלל זמן קצוב לתפוגה של החיבור.
  • refused-stream: הנתב ינסה שוב אם שירות הקצה העורפי יאפס את הסטרימינג עם קוד השגיאה REFUSED_STREAM. סוג האיפוס הזה מציין שאפשר לנסות שוב בבטחה.
  • cancelled: הנתב ינסה שוב אם קוד הסטטוס של gRPC בכותרת התגובה מוגדר כ-cancelled
  • ‫deadline-exceeded: הנתב ינסה שוב אם קוד הסטטוס של gRPC בכותרת התגובה מוגדר כ-deadline-exceeded
  • resource-exhausted: הנתב ינסה שוב אם קוד הסטטוס של gRPC בכותרת התגובה מוגדר כ-resource-exhausted
  • unavailable: הנתב ינסה שוב אם קוד הסטטוס של gRPC בכותרת התגובה מוגדר כ-unavailable
numRetries

integer (uint32 format)

מציינת את מספר הניסיונות החוזרים המותרים. המספר הזה חייב להיות גדול מ-0. אם לא מצוין ערך, ברירת המחדל היא 1.

StatefulSessionAffinityPolicy

המפרט של זיקה לסשן (session affinity) עם שמירת מצב (stateful) שמבוססת על קובצי Cookie, שבה מישור הנתונים מספק "קובץ Cookie זמני" בשם GSSA שמקודד מארח יעד ספציפי, וכל בקשה שמכילה את קובץ ה-Cookie הזה תופנה למארח הזה כל עוד מארח היעד פועל ותקין.

ספריית הרשת בלי שרת Proxy של gRPC או קובץ העזר החיצוני ינהלו את קובץ ה-Cookie הזמני, אבל קוד אפליקציית הלקוח אחראי להעתקת קובץ ה-Cookie מכל קריאה לשירות מרוחק (RPC) בסשן לקריאה הבאה.

ייצוג ב-JSON
{
  "cookieTtl": string
}
שדות
cookieTtl

string (Duration format)

חובה. ערך ה-TTL של קובץ ה-Cookie לכותרת Set-Cookie שנוצרה על ידי מישור הנתונים. אפשר להגדיר את משך החיים של קובץ ה-cookie לערך בין 0 ל-86,400 שניות (24 שעות), כולל.

כדי להשתמש בקובץ Cookie זמני ולהשבית את התפוגה של קובצי Cookie, צריך להגדיר את הערך ל-0s.

משך זמן בשניות עם עד תשע ספרות אחרי הנקודה העשרונית, שמסתיים ב-"s". לדוגמה: "3.5s".

Methods

create

יצירת GrpcRoute חדש בפרויקט ובמיקום נתונים.

delete

מחיקה של GrpcRoute יחיד.

get

אחזור פרטים של GrpcRoute יחיד.

list

הצגת רשימה של GrpcRoutes בפרויקט ובמיקום נתונים.

patch

עדכון הפרמטרים של GrpcRoute יחיד.

setIamPolicy

מגדירה את מדיניות בקרת הגישה במשאב שצוין.

testIamPermissions

הפונקציה מחזירה את ההרשאות שיש לפונקציית קריאה חוזרת (caller) במשאב שצוין.