Route

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

深入了解網路。

方法

abort

v1.9 之前版本新增

route.abort

中止路由的請求。

用法

await route.abort();
await 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' - 發生一般性失敗。

回傳

Promise<void>#

continue

v1.9 之前版本新增

route.continue

將路由的請求傳送到網路，可選擇覆寫。

用法

await page.route('**/*', async (route, request) => {
  // Override headers
  const headers = {
    ...request.headers(),
    foo: 'foo-value', // set "foo" header
    bar: undefined, // remove "bar" header
  };
  await route.continue({ headers });
});

參數

options Object (選填)
- headers Object<string, string> (選填)#
  
  如果設定，則變更請求的 HTTP 標頭。標頭值將會轉換為字串。
- method string (選填)#
  
  如果設定，則變更請求方法（例如 GET 或 POST）。
- postData string | Buffer | Serializable (選填)#
  
  如果設定，則變更請求的 post data。
- url string (選填)#
  
  如果設定，則變更請求 URL。新的 URL 必須與原始 URL 具有相同的協定。

回傳

Promise<void>#

詳細資訊

headers 選項適用於路由的請求及其啟動的任何重新導向。但是，url、method 和 postData 僅適用於原始請求，而不會帶到重新導向的請求。

route.continue() 將立即將請求傳送到網路，不會調用其他符合條件的處理常式。如果您希望調用鏈中的下一個符合條件的處理常式，請使用 route.fallback()。

fallback

v1.23 版本新增

route.fallback

繼續路由的請求，可選擇覆寫。此方法類似於 route.continue()，不同之處在於在傳送請求之前，將會先調用其他符合條件的處理常式。

用法

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

await page.route('**/*', async route => {
  // Runs last.
  await route.abort();
});
await page.route('**/*', async route => {
  // Runs second.
  await route.fallback();
});
await page.route('**/*', async route => {
  // Runs first.
  await route.fallback();
});

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

// Handle GET requests.
await page.route('**/*', async route => {
  if (route.request().method() !== 'GET') {
    await route.fallback();
    return;
  }
  // Handling GET only.
  // ...
});

// Handle POST requests.
await page.route('**/*', async route => {
  if (route.request().method() !== 'POST') {
    await route.fallback();
    return;
  }
  // Handling POST only.
  // ...
});

也可以在回退到後續處理常式時修改請求，這樣中間路由處理常式就可以修改請求的 url、method、headers 和 postData。

await page.route('**/*', async (route, request) => {
  // Override headers
  const headers = {
    ...request.headers(),
    foo: 'foo-value', // set "foo" header
    bar: undefined, // remove "bar" header
  };
  await route.fallback({ headers });
});

使用 route.continue() 可立即將請求傳送到網路，在這種情況下，不會調用其他符合條件的處理常式。

參數

options Object (選填)
- headers Object<string, string> (選填)#
  
  如果設定，則變更請求的 HTTP 標頭。標頭值將會轉換為字串。
- method string (選填)#
  
  如果設定，則變更請求方法（例如 GET 或 POST）。
- postData string | Buffer | Serializable (選填)#
  
  如果設定，則變更請求的 post data。
- url string (選填)#
  
  如果設定，則變更請求 URL。新的 URL 必須與原始 URL 具有相同的協定。變更 URL 不會影響路由比對，所有路由都使用原始請求 URL 進行比對。

回傳

Promise<void>#

fetch

v1.29 版本新增

route.fetch

執行請求並取得結果，但不完成請求，以便可以修改回應，然後完成請求。

用法

await page.route('https://dog.ceo/api/breeds/list/all', async route => {
  const response = await route.fetch();
  const json = await response.json();
  json.message['big_red_dog'] = [];
  await route.fulfill({ response, json });
});

參數

options Object (選填)
- headers Object<string, string> (選填)#
  
  如果設定，則變更請求的 HTTP 標頭。標頭值將會轉換為字串。
- maxRedirects number (選填)v1.31 版本新增#
  
  將自動追蹤的最大請求重新導向次數。如果超過次數，將會擲回錯誤。預設值為 20。傳遞 0 以不追蹤重新導向。
- maxRetries number (選填)v1.46 版本新增#
  
  網路錯誤應重試的最大次數。目前僅重試 ECONNRESET 錯誤。不會根據 HTTP 回應代碼重試。如果超過限制，將會擲回錯誤。預設值為 0 - 不重試。
- method string (選填)#
  
  如果設定，則變更請求方法（例如 GET 或 POST）。
- postData string | Buffer | Serializable (選填)#
  
  允許設定請求的 post data。如果 data 參數是物件，它將序列化為 json 字串，並且如果未明確設定，則 content-type 標頭將設定為 application/json。否則，如果未明確設定，則 content-type 標頭將設定為 application/octet-stream。
- timeout number (選填)v1.33 版本新增#
  
  請求逾時時間（毫秒）。預設值為 30000 (30 秒)。傳遞 0 以停用逾時。
- url string (選填)#
  
  如果設定，則變更請求 URL。新的 URL 必須與原始 URL 具有相同的協定。

回傳

Promise<APIResponse>#

詳細資訊

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

fulfill

v1.9 之前版本新增

route.fulfill

使用給定的回應完成路由的請求。

用法

以 404 回應完成所有請求的範例

await page.route('**/*', async route => {
  await route.fulfill({
    status: 404,
    contentType: 'text/plain',
    body: 'Not Found!'
  });
});

提供靜態檔案的範例

await page.route('**/xhr_endpoint', route => route.fulfill({ path: 'mock_data.json' }));

參數

options Object (選填)
- body string | Buffer (選填)#
  
  回應主體。
- contentType string (選填)#
  
  如果設定，則等於設定 Content-Type 回應標頭。
- headers Object<string, string> (選填)#
  
  回應標頭。標頭值將會轉換為字串。
- json Serializable (選填)v1.29 版本新增#
  
  JSON 回應。如果未設定，此方法會將內容類型設定為 application/json。
- path string (選填)#
  
  要回應的檔案路徑。內容類型將從檔案副檔名推斷。如果 path 是相對路徑，則會相對於目前的工作目錄解析。
- response APIResponse (選填)v1.15 版本新增#
  
  用於完成路由請求的 APIResponse。可以使用 fulfill 選項覆寫回應的個別欄位（例如標頭）。
- status number (選填)#
  
  回應狀態碼，預設為 200。

回傳

Promise<void>#

request

v1.9 之前版本新增

route.request

要路由的請求。

用法

route.request();

回傳

Request #

方法​

abort​

continue​

fallback​

fetch​

fulfill​

request​

方法

abort

continue

fallback

fetch

fulfill

request