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

這是必要旗標，HttpRoute 資源的名稱。符合模式 projects/*/locations/global/httpRoutes/http_route_name>。
description

string

(非必要) 資源的自由文字說明。長度上限為 1024 個半形字元。
createTime

string (Timestamp format)

僅供輸出。資源建立時間的時間戳記。

採用 RFC3339 世界標準時間「Zulu」格式的時間戳記，精確度達奈秒單位，最多九個小數位數。例如："2014-10-02T15:01:23Z" 和 "2014-10-02T15:01:23.045123456Z"。
updateTime

string (Timestamp format)

僅供輸出。資源更新時間的時間戳記。

採用 RFC3339 世界標準時間「Zulu」格式的時間戳記，精確度達奈秒單位，最多九個小數位數。例如："2014-10-02T15:01:23Z" 和 "2014-10-02T15:01:23.045123456Z"。
hostnames[]

string

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

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

請注意，根據 RFC1035 和 RFC1123 的規定，標籤必須由小寫英數字元或「-」組成，且開頭和結尾須為英數字元。不允許其他標點符號。

與 Mesh 或 Gateway 相關聯的路徑必須有專屬的主機名稱。如果您嘗試附加多個衝突的網域名稱路徑，系統會拒絕設定。

舉例來說，雖然主機名稱 *.foo.bar.com 和 *.bar.com 的路徑可以與相同的 Mesh (或相同範圍內的 Gateway) 建立關聯，但兩個路徑無法同時與 *.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

必須有標頭名稱的標頭。無論標頭是否有值，系統都會進行比對。
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 欄位所參照後端的比例。計算方式如下：- 權重/Sum(這個目的地清單中的權重)。對於非零值，實際比例可能會與此處定義的確切比例有些許差異，具體取決於實作項目支援的精確度。

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

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 的要求都會導向該主機。

gRPC 無 Proxy 的 Mesh 程式庫或附加 Proxy 會管理工作階段 Cookie，但用戶端應用程式程式碼負責將 Cookie 從工作階段中的每個 RPC 複製到下一個。

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

string (Duration format)

這是必要旗標，資料層產生的 Set-Cookie 標頭 Cookie TTL 值。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)

(非必要) 回應主體為位元組。內容大小上限為 4096 位元組。

Base64 編碼字串。

方法

create

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

delete

 刪除單一 HttpRoute。

get

 取得單一 HttpRoute 的詳細資料。

getIamPolicy

 取得資源的存取權控管政策。

list

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

patch

 更新單一 HttpRoute 的參數。

setIamPolicy

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

testIamPermissions

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