Route

每当使用Page.RouteAsync()或BrowserContext.RouteAsync()设置网络路由时，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​

将路由的请求发送到网络，可选择性地进行覆盖。

用法

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? (optional)

  • 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​

继续路由请求并可选地覆盖某些参数。该方法与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? (optional)

  • Headers IDictionary?<string, string> (可选)#

    如果设置，将更改请求的HTTP头信息。头值将被转换为字符串。

  • Method string? (可选)#

    如果设置，将更改请求方法（例如GET或POST）。

  • PostData byte[]? (可选)#

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

  • Url string? (可选)#

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

返回

• void#

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? (optional)

  • 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​

使用给定的响应完成路由的请求。

用法

一个返回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? (optional)

  • 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。可以使用fulfill选项覆盖响应的各个字段（如headers）。

  • Status int? (可选)#

    响应状态码，默认为 200。

返回

• void#

请求​

一个需要被路由的请求。

用法

Route.Request

返回

• Request#