REST Resource: projects.locations.httpRoutes

資源：HttpRoute

HttpRoute 資源會定義 Mesh 或 Gateway 資源應如何轉送 HTTP 流量。

JSON 表示法 
{
  "name": string,
  "selfLink": string,
  "description": string,
  "createTime": string,
  "updateTime": string,
  "hostnames": [
    string
  ],
  "meshes": [
    string
  ],
  "gateways": [
    string
  ],
  "labels": {
    string: string,
    ...
  },
  "rules": [
    {
      object (RouteRule)
    }
  ]
}
欄位
name

string

ID。HttpRoute 資源的名稱。符合模式 projects/*/locations/global/httpRoutes/http_route_name>。
description

string

(選用步驟) 資源的自由格式文字說明。長度上限為 1024 個字元。
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"。
hostnames[]

string

這是必要旗標，主機名稱定義一組主機，這些主機應與 HTTP 主機標頭比對，以選取要處理要求的 HttpRoute。主機名稱是網路主機的完整網域名稱，如 RFC 1123 所定義，但有以下例外狀況：- 不允許使用 IP。- 主機名稱可加上萬用字元標籤 (*.) 前置字元。萬用字元標籤必須單獨顯示為第一個標籤。

主機名稱可以是「精確」名稱，也就是沒有網路主機結尾點的網域名稱 (例如 foo.example.com)，也可以是「萬用字元」名稱，也就是在網域名稱前面加上單一萬用字元標籤 (例如 *.example.com)。

請注意，根據 RFC1035 和 RFC1123，標籤只能使用小寫英數字元或「-」，開頭和結尾須為英數字元。不得使用其他標點符號。

與 Mesh 或閘道相關聯的路徑必須有不重複的主機名稱。如果嘗試附加多個主機名稱衝突的路徑，系統會拒絕設定。

舉例來說，主機名稱 *.foo.bar.com 和 *.bar.com 的路徑可以與同一個網格 (或相同範圍內的閘道) 建立關聯，但兩個路徑無法都與 *.bar.com 或 bar.com 建立關聯。
meshes[]

string

(選用步驟) 網格會定義這個 HttpRoute 所附加的網格清單，做為轉送網格服務要求的轉送規則之一。

每個網格參照都應符合以下模式：projects/*/locations/global/meshes/<mesh_name>

附加的網格應為 SIDECAR 類型
gateways[]

string

(選用步驟) 閘道會定義這個 HttpRoute 所附加的閘道清單，做為轉送規則之一，用來轉送閘道服務的要求。

每個閘道參照都應符合以下模式：projects/*/locations/global/gateways/<gateway_name>
labels

map (key: string, value: string)

(選用步驟) 與 HttpRoute 資源相關聯的標籤標記集。

包含 "key": value 組合清單的物件。範例：{ "name": "wrench", "mass": "1.3kg", "count": "3" }。
rules[]

object (RouteRule)

這是必要旗標，定義流量轉送和處理方式的規則。系統會根據規則指定的 RouteMatch 依序比對規則。

RouteRule

指定如何比對流量，以及比對流量時如何轉送流量。

JSON 表示法 
{
  "matches": [
    {
      object (RouteMatch)
    }
  ],
  "action": {
    object (RouteAction)
  }
}
欄位
matches[]

object (RouteMatch)

比對清單會定義比對規則與傳入 HTTP 要求時使用的條件。每項比對都是獨立的，也就是說，只要符合「任一」比對條件，就會套用這項規則。

如未指定相符欄位，這項規則會無條件比對流量。

如要設定預設規則，請在規則清單結尾新增未指定相符項的規則。
action

object (RouteAction)

詳細規則，定義如何轉送相符的流量。

RouteMatch

RouteMatch 定義用於比對要求的規格。如果設定多個比對類型，只要所有比對類型都相符，這個 RouteMatch 就會相符。

JSON 表示法 
{
  "ignoreCase": boolean,
  "headers": [
    {
      object (HeaderMatch)
    }
  ],
  "queryParameters": [
    {
      object (QueryParameterMatch)
    }
  ],

  // Union field PathMatch can be only one of the following:
  "fullPathMatch": string,
  "prefixMatch": string,
  "regexMatch": string
  // End of list of possible types for union field PathMatch.
}
欄位
ignoreCase

boolean

指定 prefixMatch 和 fullPathMatch 比對是否區分大小寫。預設值為 false。
headers[]

object (HeaderMatch)

指定要比對的 HTTP 要求標頭清單。必須符合所有提供的標頭。
queryParameters[]

object (QueryParameterMatch)

指定要比對的查詢參數清單。必須符合「所有」查詢參數。

聯集欄位 PathMatch。

PathMatch 只能是下列其中一項：
fullPathMatch

string

HTTP 要求路徑值應與這個值完全相符。

請只使用 fullPathMatch、prefixMatch 或 regexMatch 其中一個。
prefixMatch

string

HTTP 要求路徑值開頭必須為指定的 prefixMatch。prefixMatch 開頭必須為「/」。

請只使用 fullPathMatch、prefixMatch 或 regexMatch 其中一個。
regexMatch

string

移除原始網址提供的所有查詢參數和錨點後，HTTP 要求路徑值必須符合 regexMatch 指定的規則運算式。如要瞭解規則運算式文法，請參閱 https://github.com/google/re2/wiki/Syntax

請只使用 fullPathMatch、prefixMatch 或 regexMatch 其中一個。

HeaderMatch

指定如何根據 HTTP 要求標頭選取轉送規則。

JSON 表示法 
{
  "header": string,
  "invertMatch": boolean,

  // Union field MatchType can be only one of the following:
  "exactMatch": string,
  "regexMatch": string,
  "prefixMatch": string,
  "presentMatch": boolean,
  "suffixMatch": string,
  "rangeMatch": {
    object (IntegerRange)
  }
  // End of list of possible types for union field MatchType.
}
欄位
header

string

要比對的 HTTP 標頭名稱。
invertMatch

boolean

如果指定，系統會在檢查前反轉比對結果。預設值為 false。

聯集欄位 MatchType。

MatchType 只能是下列其中一項：
exactMatch

string

標頭的值應與 exactMatch 的內容完全相符。
regexMatch

string

標頭的值必須符合 regexMatch 中指定的規則運算式。如要瞭解規則運算式文法，請參閱：https://github.com/google/re2/wiki/Syntax
prefixMatch

string

標頭的值開頭必須是 prefixMatch 的內容。
presentMatch

boolean

必須存在具有 headerName 的標頭。無論標頭是否有值，都會進行比對。
suffixMatch

string

標頭值必須以 suffixMatch 的內容結尾。
rangeMatch

object (IntegerRange)

如果指定，當要求標頭值在範圍內時，規則就會相符。

IntegerRange

表示整數值範圍。

JSON 表示法 
{
  "start": integer,
  "end": integer
}
欄位
start

integer

範圍的起始值 (含)
end

integer

範圍的結尾 (不含)

QueryParameterMatch

規格，用於比對要求中的查詢參數。

JSON 表示法 
{
  "queryParameter": string,

  // Union field MatchType can be only one of the following:
  "exactMatch": string,
  "regexMatch": string,
  "presentMatch": boolean
  // End of list of possible types for union field MatchType.
}
欄位
queryParameter

string

要比對的查詢參數名稱。

聯集欄位 MatchType。

MatchType 只能是下列其中一項：
exactMatch

string

查詢參數的值必須與 exactMatch 的內容完全相符。

只能設定 exactMatch、regexMatch 或 presentMatch 其中之一。
regexMatch

string

查詢參數的值必須符合 regexMatch 指定的規則運算式。如要瞭解規則運算式文法，請參閱 https://github.com/google/re2/wiki/Syntax

只能設定 exactMatch、regexMatch 或 presentMatch 其中之一。
presentMatch

boolean

指定如果要求包含查詢參數，QueryParameterMatcher 就會相符，無論參數是否有值。

只能設定 exactMatch、regexMatch 或 presentMatch 其中之一。

RouteAction

轉送流量和套用相關政策的規格。

JSON 表示法 
{
  "destinations": [
    {
      object (Destination)
    }
  ],
  "redirect": {
    object (Redirect)
  },
  "faultInjectionPolicy": {
    object (FaultInjectionPolicy)
  },
  "requestHeaderModifier": {
    object (HeaderModifier)
  },
  "responseHeaderModifier": {
    object (HeaderModifier)
  },
  "urlRewrite": {
    object (URLRewrite)
  },
  "timeout": string,
  "retryPolicy": {
    object (RetryPolicy)
  },
  "requestMirrorPolicy": {
    object (RequestMirrorPolicy)
  },
  "corsPolicy": {
    object (CorsPolicy)
  },
  "statefulSessionAffinity": {
    object (StatefulSessionAffinityPolicy)
  },
  "directResponse": {
    object (HttpDirectResponse)
  },
  "idleTimeout": string
}
欄位
destinations[]

object (Destination)

流量應轉送至的目的地。
redirect

object (Redirect)

如果已設定，系統會根據這個欄位設定導向要求。
faultInjectionPolicy

object (FaultInjectionPolicy)

導入流量的錯誤植入規格，用於測試用戶端對後端服務故障的彈性。在錯誤植入期間，當用戶端將要求傳送至後端服務時，系統會先針對一定比例的要求產生延遲，然後再將這些要求傳送至後端服務。同樣地，也可以針對一定比例的要求，中止來自用戶端的要求。

如果用戶端已設定 faultInjectionPolicy，系統會忽略 timeout 和 retryPolicy
requestHeaderModifier

object (HeaderModifier)

這項規格用於在將相符要求傳送至目的地之前，修改要求標頭。如果 Destination 和 RouteAction 都設定了 HeaderModifiers，系統會合併這些值。系統不會解決兩者之間的衝突。
responseHeaderModifier

object (HeaderModifier)

規格：在將回應傳回用戶端前，先修改回應的標頭。如果 Destination 和 RouteAction 都設定了 HeaderModifiers，系統會合併這些值。系統不會解決兩者之間的衝突。
urlRewrite

object (URLRewrite)

在將要求轉送至目的地前，重新編寫網址的規格。
timeout

string (Duration format)

指定所選路徑的逾時時間。逾時時間的計算方式為：從要求完全處理完畢 (即串流結束) 到回應完全處理完畢之間的時間。逾時包括所有重試。

時間長度以秒為單位，最多可有 9 個小數位數，並應以「s」結尾，例如："3.5s"。
retryPolicy

object (RetryPolicy)

指定與這條路徑相關聯的重試政策。
requestMirrorPolicy

object (RequestMirrorPolicy)

指定政策，說明如何將預定傳送至路徑目的地的要求，以陰影方式傳送至另一個鏡像目的地。Proxy 不會等待影子目的地回應，就會傳回回應。將流量傳送至影子服務前，主機/授權標頭會加上 -shadow 後置字串。
corsPolicy

object (CorsPolicy)

允許用戶端跨來源要求的規格。
statefulSessionAffinity

object (StatefulSessionAffinityPolicy)

(選用步驟) 指定以 Cookie 為基礎的有狀態工作階段相依性。
directResponse

object (HttpDirectResponse)

(選用步驟) 無論要求為何，都會傳回的靜態 HTTP 回應物件。
idleTimeout

string (Duration format)

(選用步驟) 指定所選路徑的閒置逾時時間。閒置逾時是指上游或下游連線沒有傳送或接收任何位元組的期間。如未設定，預設閒置逾時時間為 1 小時。如果設為 0 秒，系統會停用逾時。

時間長度以秒為單位，最多可有 9 個小數位數，並應以「s」結尾，例如："3.5s"。

目的地

要求應轉送至的目的地規格。

JSON 表示法 
{
  "serviceName": string,
  "weight": integer,
  "requestHeaderModifier": {
    object (HeaderModifier)
  },
  "responseHeaderModifier": {
    object (HeaderModifier)
  }
}
欄位
serviceName

string

要將流量轉送至的 BackendService 網址。
weight

integer

指定轉送至 serviceName 欄位所參照後端的請求比例。計算方式為：- weight/Sum(weights in this destination list)。如果值不為零，則可能與這裡定義的確切比例有些許差異，視實作支援的精確度而定。

如果只指定一個 serviceName，且權重大於 0，則 100% 的流量會轉送至該後端。

如果為任一服務名稱指定權重，則必須為所有服務名稱指定權重。

如果所有服務都未指定權重，系統會將流量平均分配給所有服務。
requestHeaderModifier

object (HeaderModifier)

(選用步驟) 這項規格用於在將相符要求傳送至目的地之前，修改要求標頭。如果 Destination 和 RouteAction 都設定了 HeaderModifiers，系統會合併這些值。系統不會解決兩者之間的衝突。
responseHeaderModifier

object (HeaderModifier)

(選用步驟) 規格：在將回應傳回用戶端前，先修改回應的標頭。如果 Destination 和 RouteAction 都設定了 HeaderModifiers，系統會合併這些值。系統不會解決兩者之間的衝突。

HeaderModifier

修改 HTTP 要求和 HTTP 回應中 HTTP 標頭的規格。

JSON 表示法 
{
  "set": {
    string: string,
    ...
  },
  "add": {
    string: string,
    ...
  },
  "remove": [
    string
  ]
}
欄位
set

map (key: string, value: string)

使用指定的地圖完全覆寫/取代標頭，其中鍵是標頭名稱，值是標頭值。

包含 "key": value 組合清單的物件。範例：{ "name": "wrench", "mass": "1.3kg", "count": "3" }。
add

map (key: string, value: string)

使用指定的地圖新增標頭，其中鍵是標頭名稱，值是標頭的值。

包含 "key": value 組合清單的物件。範例：{ "name": "wrench", "mass": "1.3kg", "count": "3" }。
remove[]

string

移除清單中指定的標頭 (依標頭名稱比對)。

重新導向

重新導向流量的規格。

JSON 表示法 
{
  "hostRedirect": string,
  "pathRedirect": string,
  "prefixRewrite": string,
  "responseCode": enum (ResponseCode),
  "httpsRedirect": boolean,
  "stripQuery": boolean,
  "portRedirect": integer
}
欄位
hostRedirect

string

重新導向回應中使用的主機，而非要求中提供的主機。
pathRedirect

string

重新導向回應中使用的路徑，而非要求中提供的路徑。pathRedirect 無法與 prefixRedirect 一併提供。請提供其中一項，或兩者皆不提供。如果兩者皆未提供，系統會使用原始要求的路徑進行重新導向。
prefixRewrite

string

表示在重新導向期間，相符前置字元 (或路徑) 應替換為這個值。這個選項可根據要求動態建立網址。
responseCode

enum (ResponseCode)

重新導向時要使用的 HTTP 狀態碼。
httpsRedirect

boolean

如果設為 true，重新導向要求中的網址配置會設為 https。如果設為 false，重新導向要求會沿用要求本身的網址配置。

預設值為 false。
stripQuery

boolean

如果設為 true，系統會先移除原始網址的任何隨附查詢部分，再重新導向要求。如果設為 false，系統會保留原始網址的查詢部分。

預設值為 false。
portRedirect

integer

重新導向要求中使用的連接埠，而非要求中提供的連接埠。

ResponseCode

支援的 HTTP 回應代碼。

列舉
RESPONSE_CODE_UNSPECIFIED 預設值
MOVED_PERMANENTLY_DEFAULT 對應 301。
FOUND 對應 302。
SEE_OTHER 對應至 303。
TEMPORARY_REDIRECT 對應於 307。在這種情況下，要求方法會保留。
PERMANENT_REDIRECT 對應於 308。在這種情況下，要求方法會保留。

FaultInjectionPolicy

導入流量的錯誤植入規格，用於測試用戶端對目的地服務故障的彈性。在故障注入期間，當用戶端將要求傳送至目的地時，用戶端 Proxy 會針對一定比例的要求導入延遲，然後再將這些要求傳送至目的地服務。同樣地，用戶端 Proxy 也可以針對一定比例的要求中止要求。

JSON 表示法 
{
  "delay": {
    object (Delay)
  },
  "abort": {
    object (Abort)
  }
}
欄位
delay

object (Delay)

將延遲時間插入用戶端要求的規格。
abort

object (Abort)

中止用戶端要求的規格。

延遲時間

指定用戶端要求在傳送至目的地前，如何因故障注入而延遲。

JSON 表示法 
{
  "fixedDelay": string,
  "percentage": integer
}
欄位
fixedDelay

string (Duration format)

指定固定延遲時間，然後轉送要求。

時間長度以秒為單位，最多可有 9 個小數位數，並應以「s」結尾，例如："3.5s"。
percentage

integer

要注入延遲的流量百分比。

值必須介於 [0, 100] 之間

取消

指定如何中止用戶端要求，做為故障注入的一部分，再傳送至目的地。

JSON 表示法 
{
  "httpStatus": integer,
  "percentage": integer
}
欄位
httpStatus

integer

用於終止要求的 HTTP 狀態碼。

這個值必須介於 200 至 599 之間 (含)。
percentage

integer

要中止的流量百分比。

值必須介於 [0, 100] 之間

URLRewrite

在將要求轉送至目的地之前，修改要求網址的規格。

JSON 表示法 
{
  "pathPrefixRewrite": string,
  "hostRewrite": string
}
欄位
pathPrefixRewrite

string

將要求轉送至所選目的地之前，系統會將要求路徑相符的部分替換成這個值。
hostRewrite

string

將要求轉送至所選目的地之前，系統會將要求的主機標頭替換成這個值。

RetryPolicy

重試的規格。

JSON 表示法 
{
  "retryConditions": [
    string
  ],
  "numRetries": integer,
  "perTryTimeout": string
}
欄位
retryConditions[]

string

指定套用這項重試政策的一或多項條件。有效值包括：5xx：如果目的地服務傳回任何 5xx 回應碼，或完全沒有回應 (例如中斷連線、重設、讀取逾時、連線失敗和拒絕串流)，Proxy 就會嘗試重試。

gateway-error：與 5xx 相似，但只適用於回應代碼 502、503、504。

重設：如果目的地服務完全沒有回應 (中斷連線/重設/讀取逾時)，Proxy 會嘗試重試

connect-failure：Proxy 會在連線至目的地失敗時重試，例如連線逾時。

retriable-4xx：Proxy 會針對可重試的 4xx 回應代碼重試。目前唯一支援重試的錯誤是 409。

refused-stream：如果目的地以 REFUSED_STREAM 錯誤代碼重設串流，Proxy 會重試。這類重設表示可以安全地重試。
numRetries

integer

指定允許的重試次數。這個數字必須大於 0，如未指定，則預設為 1。
perTryTimeout

string (Duration format)

指定每次重試的逾時時間 (不得為零)。

時間長度以秒為單位，最多可有 9 個小數位數，並應以「s」結尾，例如："3.5s"。

RequestMirrorPolicy

指定將要求複製到獨立鏡像目的地服務的政策。Proxy 不會等待影子服務的回應。將流量傳送至影子服務前，主機/授權標頭會加上 -shadow 後置字串。

JSON 表示法 
{
  "destination": {
    object (Destination)
  },
  "mirrorPercent": number
}
欄位
destination

object (Destination)

要求要鏡像複製到的目的地。系統會忽略目的地權重。
mirrorPercent

number

(選用步驟) 要求鏡像至所需目的地的百分比。

CorsPolicy

允許用戶端跨來源要求的規格。

JSON 表示法 
{
  "allowOrigins": [
    string
  ],
  "allowOriginRegexes": [
    string
  ],
  "allowMethods": [
    string
  ],
  "allowHeaders": [
    string
  ],
  "exposeHeaders": [
    string
  ],
  "maxAge": string,
  "allowCredentials": boolean,
  "disabled": boolean
}
欄位
allowOrigins[]

string

指定允許執行 CORS 要求的來源清單。如果來源符合 allowOrigins 中的項目或 allowOriginRegexes 中的項目，系統就會允許該來源。
allowOriginRegexes[]

string

指定符合允許來源的規則運算式模式。如要瞭解規則運算式文法，請參閱 https://github.com/google/re2/wiki/Syntax。
allowMethods[]

string

指定 Access-Control-Allow-Methods 標頭的內容。
allowHeaders[]

string

指定 Access-Control-Allow-Headers 標頭的內容。
exposeHeaders[]

string

指定 Access-Control-Expose-Headers 標頭的內容。
maxAge

string

指定預檢要求結果可快取的時間長度 (以秒為單位)。這會轉譯為 Access-Control-Max-Age 標頭。
allowCredentials

boolean

為因應預檢要求，將此屬性設為 true 代表實際要求可以包含使用者憑證。這會轉譯成 Access-Control-Allow-Credentials 標頭。

預設值是 false。
disabled

boolean

如果為 true，系統會停用 CORS 政策。預設值為 false，表示 CORS 政策有效。

StatefulSessionAffinityPolicy

以 Cookie 為基礎的有狀態工作階段相依性規格，其中資料平面會提供名為「GSSA」的「工作階段 Cookie」，該 Cookie 會編碼特定目的地主機，只要目的地主機保持運作且健康狀態良好，包含該 Cookie 的每個要求都會導向該主機。

gRPC 無代理程式網格程式庫或 Sidecar 代理程式會管理工作階段 Cookie，但用戶端應用程式碼必須負責將工作階段中每個 RPC 的 Cookie 複製到下一個 RPC。

JSON 表示法 
{
  "cookieTtl": string
}
欄位
cookieTtl

string (Duration format)

這是必要旗標，資料層產生的 Set-Cookie 標頭的 Cookie 存留時間值。Cookie 的效期可設為介於 1 到 86400 秒 (24 小時) 之間，含首尾值。

時間長度以秒為單位，最多可有 9 個小數位數，並應以「s」結尾，例如："3.5s"。

HttpDirectResponse

要傳回的靜態 HTTP 回應物件。

JSON 表示法 
{
  "status": integer,

  // Union field HttpBody can be only one of the following:
  "stringBody": string,
  "bytesBody": string
  // End of list of possible types for union field HttpBody.
}
欄位
status

integer

這是必要旗標，要以 HTTP 回應的形式傳回的狀態。必須是正整數。
聯集欄位 HttpBody。要以 HTTP 回應形式傳回的主體。HttpBody 只能是下列其中一項：
stringBody

string

(選用步驟) 回應主體 (字串)。內文長度上限為 1024 個半形字元。
bytesBody

string (bytes format)

(選用步驟) 以位元組表示的回應主體。主體大小上限為 4096B。

Base64 編碼字串。

方法

create

 在指定專案和位置中建立新的 HttpRoute。

delete

 刪除單一 HttpRoute。

get

 取得單一 HttpRoute 的詳細資料。

list

 列出指定專案和位置中的 HttpRoute。

patch

 更新單一 HttpRoute 的參數。

setIamPolicy

 設定指定資源的存取權控管政策。

testIamPermissions

 傳回呼叫者在指定資源上擁有的權限。