跳转到主要内容

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' - 发生一般性故障。

返回

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 具有相同的协议。

返回

详情

Headers 选项适用于路由请求及其发起的任何重定向。然而，Url、Method 和 PostData 仅适用于原始请求，不会延续到重定向请求。

Route.ContinueAsync() 将立即发送请求到网络，其他匹配的处理程序将不会被调用。如果您希望调用链中下一个匹配的处理程序，请使用 Route.FallbackAsync()。

警告

无法使用此方法覆盖 Cookie 头。如果提供了值，它将被忽略，并且将从浏览器的 cookie 存储中加载 cookie。要设置自定义 cookie，请使用 BrowserContext.AddCookiesAsync()。

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[]? （可选）#

      如果设置，则更改请求的 post 数据。

    • Url string? （可选）#

      如果设置，则更改请求 URL。新 URL 必须与原始 URL 具有相同的协议。更改 URL 不会影响路由匹配，所有路由都使用原始请求 URL 进行匹配。

返回

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 具有相同的协议。

返回

详情

请注意，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。

返回

Request​

v1.9 之前添加 route.Request

待路由的请求。

用法

Route.Request

返回