Route

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

方法

AbortAsync

在 v1.9 之前新增

route.AbortAsync

中止路由的請求。

用法

await Route.AbortAsync(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 #

ContinueAsync

在 v1.9 之前新增

route.ContinueAsync

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

用法

await page.RouteAsync("**/*", async route =>
{
    var headers = new Dictionary<string, string>(route.Request.Headers) { { "foo", "bar" } };
    headers.Remove("origin");
    await route.ContinueAsync(new() { Headers = headers });
});

參數

options RouteContinueOptions? (選用)
- Headers IDictionary?<string, string> (選用)#
  
  如果設定，則變更請求的 HTTP 標頭。標頭值將轉換為字串。
- Method string? (選用)#
  
  如果設定，則變更請求方法 (例如 GET 或 POST)。
- PostData byte[]? (選用)#
  
  如果設定，則變更請求的 POST 資料。
- Url string? (選用)#
  
  如果設定，則變更請求 URL。新的 URL 必須與原始 URL 具有相同的協議。

回傳

void #

詳細資訊

Headers 選項適用於路由請求及其啟動的任何重新導向。但是，Url、Method 和 PostData 僅適用於原始請求，不會延續到重新導向的請求。

Route.ContinueAsync() 將立即將請求發送到網路，不會調用其他匹配的處理程序。如果您希望調用鏈中的下一個匹配處理程序，請使用 Route.FallbackAsync()。

FallbackAsync

在 v1.23 中新增

route.FallbackAsync

繼續路由的請求，並可選擇覆寫。此方法類似於 Route.ContinueAsync()，不同之處在於在發送請求之前，將調用其他匹配的處理程序。

用法

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

await page.RouteAsync("**/*", route => {
    // Runs last.
    await route.AbortAsync();
});

await page.RouteAsync("**/*", route => {
    // Runs second.
    await route.FallbackAsync();
});

await page.RouteAsync("**/*", route => {
    // Runs first.
    await route.FallbackAsync();
});

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

// Handle GET requests.
await page.RouteAsync("**/*", route => {
    if (route.Request.Method != "GET") {
        await route.FallbackAsync();
        return;
    }
    // Handling GET only.
    // ...
});

// Handle POST requests.
await page.RouteAsync("**/*", route => {
    if (route.Request.Method != "POST") {
        await route.FallbackAsync();
        return;
    }
    // Handling POST only.
    // ...
});

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

await page.RouteAsync("**/*", async route =>
{
    var headers = new Dictionary<string, string>(route.Request.Headers) { { "foo", "foo-value" } };
    headers.Remove("bar");
    await route.FallbackAsync(new() { Headers = headers });
});

使用 Route.ContinueAsync() 立即將請求發送到網路，在這種情況下，不會調用其他匹配的處理程序。

參數

options RouteFallbackOptions? (選用)
- Headers IDictionary?<string, string> (選用)#
  
  如果設定，則變更請求的 HTTP 標頭。標頭值將轉換為字串。
- Method string? (選用)#
  
  如果設定，則變更請求方法 (例如 GET 或 POST)。
- PostData byte[]? (選用)#
  
  如果設定，則變更請求的 POST 資料。
- Url string? (選用)#
  
  如果設定，則變更請求 URL。新的 URL 必須與原始 URL 具有相同的協議。變更 URL 不會影響路由匹配，所有路由都使用原始請求 URL 進行匹配。

回傳

void #

FetchAsync

在 v1.29 中新增

route.FetchAsync

執行請求並獲取結果，但不滿足它，以便可以修改響應然後滿足它。

用法

await page.RouteAsync("https://dog.ceo/api/breeds/list/all", async route =>
{
    var response = await route.FetchAsync();
    dynamic json = await response.JsonAsync();
    json.message.big_red_dog = new string[] {};
    await route.FulfillAsync(new() { Response = response, Json = json });
});

參數

options RouteFetchOptions? (選用)
- Headers IDictionary?<string, string> (選用)#
  
  如果設定，則變更請求的 HTTP 標頭。標頭值將轉換為字串。
- MaxRedirects int? (選用)在 v1.31 中新增#
  
  將自動追蹤的最大請求重新導向次數。如果超過次數，將拋出錯誤。預設值為 20。傳遞 0 以不追蹤重新導向。
- MaxRetries int? (選用)在 v1.46 中新增#
  
  網路錯誤應重試的最大次數。目前僅重試 ECONNRESET 錯誤。不根據 HTTP 響應代碼重試。如果超過限制，將拋出錯誤。預設值為 0 - 不重試。
- Method string? (選用)#
  
  如果設定，則變更請求方法 (例如 GET 或 POST)。
- PostData byte[]? (選用)#
  
  如果設定，則變更請求的 POST 資料。
- Timeout [float]? (選用)在 v1.33 中新增#
  
  請求逾時時間，以毫秒為單位。預設值為 30000 (30 秒)。傳遞 0 以停用逾時。
- Url string? (選用)#
  
  如果設定，則變更請求 URL。新的 URL 必須與原始 URL 具有相同的協議。

回傳

APIResponse #

詳細資訊

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

FulfillAsync

在 v1.9 之前新增

route.FulfillAsync

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

用法

滿足所有請求並返回 404 響應的範例

await page.RouteAsync("**/*", route => route.FulfillAsync(new ()
{
    Status = 404,
    ContentType = "text/plain",
    Body = "Not Found!"
}));

提供靜態檔案的範例

await page.RouteAsync("**/xhr_endpoint", route => route.FulfillAsync(new() { Path = "mock_data.json" }));

參數

options RouteFulfillOptions? (選用)
- Body string? (選用)#
  
  選用的響應正文，以文字形式。
- BodyBytes byte[]? (選用)在 v1.9 中新增#
  
  選用的響應正文，以原始位元組形式。
- ContentType string? (選用)#
  
  如果設定，則等於設定 Content-Type 響應標頭。
- Headers IDictionary?<string, string> (選用)#
  
  響應標頭。標頭值將轉換為字串。
- Json [object]? (選用)在 v1.29 中新增#
  
  JSON 響應。如果未設定內容類型，此方法將設定為 application/json。
- Path string? (選用)#
  
  要響應的檔案路徑。內容類型將從檔案擴展名推斷出來。如果 path 是相對路徑，則相對於當前工作目錄解析。
- Response APIResponse? (選用)在 v1.15 中新增#
  
  用於滿足路由請求的 APIResponse。響應的各個欄位 (例如標頭) 可以使用滿足選項覆寫。
- Status int? (選用)#
  
  響應狀態代碼，預設為 200。

回傳

void #

Request

在 v1.9 之前新增

route.Request

要路由的請求。

用法

Route.Request

回傳

Request #

方法​

AbortAsync​

ContinueAsync​

FallbackAsync​

FetchAsync​

FulfillAsync​

Request​

方法

AbortAsync

ContinueAsync

FallbackAsync

FetchAsync

FulfillAsync

Request