Route

每當使用 Page.route() 或 BrowserContext.route() 設定網路路由時，Route 物件允許處理該路由。

方法

abort

在 v1.9 之前新增

route.abort

中止路由的請求。

用法

Route.abort();
Route.abort(errorCode);

引數

errorCode String (選填)#

選填的錯誤代碼。預設為 failed，可以是下列其中之一
- 'aborted' - 操作已中止（由於使用者動作）
- 'accessdenied' - 拒絕存取網路以外的資源的權限
- 'addressunreachable' - IP 位址無法連線。這通常表示沒有到達指定主機或網路的路由。
- 'blockedbyclient' - 用戶端選擇封鎖請求。
- 'blockedbyresponse' - 請求失敗，因為回應與未滿足的要求一起傳遞（例如，「X-Frame-Options」和「Content-Security-Policy」祖先檢查）。
- 'connectionaborted' - 連線因未收到傳送資料的 ACK 而逾時。
- 'connectionclosed' - 連線已關閉（對應於 TCP FIN）。
- 'connectionfailed' - 連線嘗試失敗。
- 'connectionrefused' - 連線嘗試遭到拒絕。
- 'connectionreset' - 連線已重設（對應於 TCP RST）。
- 'internetdisconnected' - 網際網路連線已中斷。
- 'namenotresolved' - 無法解析主機名稱。
- 'timedout' - 操作逾時。
- 'failed' - 發生一般性失敗。

傳回

void #

fallback

新增於：v1.23

route.fallback

繼續路由的請求，並帶有選填的覆寫。此方法類似於 Route.resume()，不同之處在於，在傳送請求之前，將先呼叫其他相符的處理常式。

用法

當多個路由符合給定的模式時，它們會以與其註冊相反的順序執行。這樣，最後註冊的路由始終可以覆寫所有先前的路由。在下面的範例中，請求將首先由最底層的處理常式處理，然後它將回退到先前的處理常式，最後將被第一個註冊的路由中止。

page.route("**/*", route -> {
  // Runs last.
  route.abort();
});

page.route("**/*", route -> {
  // Runs second.
  route.fallback();
});

page.route("**/*", route -> {
  // Runs first.
  route.fallback();
});

當您希望不同的處理常式處理不同種類的請求時，註冊多個路由非常有用，例如 API 呼叫與頁面資源或 GET 請求與 POST 請求，如下面的範例所示。

// Handle GET requests.
page.route("**/*", route -> {
  if (!route.request().method().equals("GET")) {
    route.fallback();
    return;
  }
  // Handling GET only.
  // ...
});

// Handle POST requests.
page.route("**/*", route -> {
  if (!route.request().method().equals("POST")) {
    route.fallback();
    return;
  }
  // Handling POST only.
  // ...
});

也可以在回退到後續處理常式時修改請求，這樣中繼路由處理常式就可以修改請求的 url、方法、標頭和 postData。

page.route("**/*", route -> {
  // Override headers
  Map<String, String> headers = new HashMap<>(route.request().headers());
  headers.put("foo", "foo-value"); // set "foo" header
  headers.remove("bar"); // remove "bar" header
  route.fallback(new Route.ResumeOptions().setHeaders(headers));
});

使用 Route.resume() 立即將請求傳送到網路，在這種情況下，不會呼叫其他相符的處理常式。

引數

options Route.FallbackOptions (選填)
- setHeaders Map<String, String> (選填)#
  
  如果設定，則變更請求 HTTP 標頭。標頭值將轉換為字串。
- setMethod String (選填)#
  
  如果設定，則變更請求方法（例如 GET 或 POST）。
- setPostData String | byte[] (選填)#
  
  如果設定，則變更請求的 post data。
- setUrl String (選填)#
  
  如果設定，則變更請求 URL。新的 URL 必須與原始 URL 具有相同的協定。變更 URL 不會影響路由比對，所有路由都使用原始請求 URL 進行比對。

傳回

void #

fetch

新增於：v1.29

route.fetch

執行請求並擷取結果，而無需滿足請求，以便可以修改回應然後滿足請求。

用法

page.route("https://dog.ceo/api/breeds/list/all", route -> {
  APIResponse response = route.fetch();
  JsonObject json = new Gson().fromJson(response.text(), JsonObject.class);
  JsonObject message = itemObj.get("json").getAsJsonObject();
  message.set("big_red_dog", new JsonArray());
  route.fulfill(new Route.FulfillOptions()
    .setResponse(response)
    .setBody(json.toString()));
});

引數

options Route.FetchOptions (選填)
- setHeaders Map<String, String> (選填)#
  
  如果設定，則變更請求 HTTP 標頭。標頭值將轉換為字串。
- setMaxRedirects int (選填)新增於：v1.31#
  
  將自動追蹤的最大請求重新導向次數。如果超過此數字，將會擲回錯誤。預設為 20。傳遞 0 以不追蹤重新導向。
- setMaxRetries int (選填)新增於：v1.46#
  
  網路錯誤應重試的最大次數。目前僅重試 ECONNRESET 錯誤。不會根據 HTTP 回應代碼重試。如果超過限制，將會擲回錯誤。預設為 0 - 不重試。
- setMethod String (選填)#
  
  如果設定，則變更請求方法（例如 GET 或 POST）。
- setPostData String | byte[] (選填)#
  
  如果設定，則變更請求的 post data。
- setTimeout double (選填)新增於：v1.33#
  
  請求逾時時間（毫秒）。預設為 30000 (30 秒)。傳遞 0 以停用逾時。
- setUrl String (選填)#
  
  如果設定，則變更請求 URL。新的 URL 必須與原始 URL 具有相同的協定。

傳回

APIResponse #

詳細資訊

請注意，setHeaders 選項將適用於擷取的請求以及它啟動的任何重新導向。如果您只想將 setHeaders 應用於原始請求，而不是重新導向，請改為查看 Route.resume()。

fulfill

在 v1.9 之前新增

route.fulfill

使用給定的回應滿足路由的請求。

用法

以 404 回應滿足所有請求的範例

page.route("**/*", route -> {
  route.fulfill(new Route.FulfillOptions()
    .setStatus(404)
    .setContentType("text/plain")
    .setBody("Not Found!"));
});

提供靜態檔案的範例

page.route("**/xhr_endpoint", route -> route.fulfill(
  new Route.FulfillOptions().setPath(Paths.get("mock_data.json"))));

引數

options Route.FulfillOptions (選填)
- setBody String (選填)#
  
  選填的回應本文，以文字形式。
- setBodyBytes byte[] (選填)新增於：v1.9#
  
  選填的回應本文，以原始位元組形式。
- setContentType String (選填)#
  
  如果設定，則等於設定 Content-Type 回應標頭。
- setHeaders Map<String, String> (選填)#
  
  回應標頭。標頭值將轉換為字串。
- setPath Path (選填)#
  
  要回應的檔案路徑。內容類型將從檔案副檔名推斷。如果 path 是相對路徑，則會相對於目前的工作目錄解析。
- setResponse APIResponse (選填)新增於：v1.15#
  
  APIResponse，用於滿足路由的請求。回應的個別欄位（例如標頭）可以使用滿足選項覆寫。
- setStatus int (選填)#
  
  回應狀態碼，預設為 200。

傳回

void #

request

在 v1.9 之前新增

route.request

要路由的請求。

用法

Route.request();

傳回

Request #

resume

在 v1.9 之前新增

route.resume

將路由的請求傳送到網路，並帶有選填的覆寫。

用法

page.route("**/*", route -> {
  // Override headers
  Map<String, String> headers = new HashMap<>(route.request().headers());
  headers.put("foo", "foo-value"); // set "foo" header
  headers.remove("bar"); // remove "bar" header
  route.resume(new Route.ResumeOptions().setHeaders(headers));
});

引數

options Route.ResumeOptions (選填)
- setHeaders Map<String, String> (選填)#
  
  如果設定，則變更請求 HTTP 標頭。標頭值將轉換為字串。
- setMethod String (選填)#
  
  如果設定，則變更請求方法（例如 GET 或 POST）。
- setPostData String | byte[] (選填)#
  
  如果設定，則變更請求的 post data。
- setUrl String (選填)#
  
  如果設定，則變更請求 URL。新的 URL 必須與原始 URL 具有相同的協定。

傳回

void #

詳細資訊

setHeaders 選項同時適用於路由的請求及其啟動的任何重新導向。但是，setUrl、setMethod 和 setPostData 僅適用於原始請求，而不適用於重新導向的請求。

Route.resume() 將立即將請求傳送到網路，而不會呼叫其他相符的處理常式。如果您希望呼叫鏈中的下一個相符處理常式，請使用 Route.fallback()。

方法​

abort​

fallback​

fetch​

fulfill​

request​

resume​

方法

abort

fallback

fetch

fulfill

request

resume