REST Resource: projects.locations.httpRoutes

資源：HttpRoute

HttpRoute 資源定義 Mesh 或閘道資源應如何轉送 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/*/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，標籤只能使用小寫英數字元或「-」，開頭和結尾須為英數字元。不得使用其他標點符號。

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

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

string

選用。「網格」會定義這個 HttpRoute 附加的網格清單，做為轉送網格所提供要求的路由規則之一。

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

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

string

選用。「閘道」定義這個 HttpRoute 附加的閘道清單，做為轉送閘道所提供要求的路由規則之一。

每個閘道參照都必須符合以下模式：projects/*/locations/*/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 欄位所參照後端的要求比例。計算方式如下：權重/總和(這份目的地清單中的權重)。對於非零值，根據實作支援的精確度，與此處定義的確切比例可能會有誤差。

如果只指定一個 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。

reset：如果目的地服務完全沒有回應 (中斷連線/重設/讀取逾時)，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 後置字串。Cloud Run 目的地目前不支援鏡像功能。

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 無 Proxy 網格程式庫或 Sidecar Proxy 會管理工作階段 Cookie，但用戶端應用程式程式碼負責將 Cookie 從工作階段中的每個 RPC 複製到下一個 RPC。

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

string (Duration format)

這是必要旗標，資料層產生的 Set-Cookie 標頭 Cookie 存留時間值。Cookie 的生命週期可設為 0 到 86400 秒 (24 小時) 之間的值 (含 0 和 86400)。

如要使用工作階段 Cookie 並停用 Cookie 效期，請將這個值設為 0s。

以秒為單位的時間長度，最多 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

 傳回呼叫端對指定資源所擁有的權限。