路由

每当使用 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[]? (可选)#
  
  如果设置，则更改请求的发布数据。
- Url string? (可选)#
  
  如果设置，则更改请求 URL。新 URL 必须与原始 URL 具有相同的协议。

返回值

void #

详细信息

请注意，任何覆盖，例如 Url 或 Headers 仅适用于正在路由的请求。如果此请求导致重定向，则覆盖将不会应用于新的重定向请求。如果您想通过重定向传播标头，请使用 Route.FetchAsync() 和 Route.FulfillAsync() 的组合。

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、方法、标头和 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[]? (可选)#
  
  如果设置，则更改请求的发布数据。
- 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[]? (可选)#
  
  如果设置，则更改请求的发布数据。
- 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