跳到主要内容

Route

每当通过 page.route() 或 browser_context.route() 设置网络路由时，Route 对象允许你处理该路由。

了解更多关于网络的信息。

方法​

abort​

v1.9 之前添加 route.abort

中止该路由的请求。

用法

route.abort()
route.abort(**kwargs)

参数

  • error_code str (可选)#

    可选的错误码。默认为 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' - 发生了通用故障。

返回值

continue_​

v1.9 之前添加 route.continue_

将路由的请求发送到网络，并可选择覆盖部分参数。

用法

def handle(route, request):
    # 覆盖请求头
    headers = {
        **request.headers,
        "foo": "foo-value", # 设置 "foo" 请求头
        "bar": None # 移除 "bar" 请求头
    }
    route.continue_(headers=headers)

page.route("**/*", handle)

参数

  • headers Dict[str, str] (可选)#

    如果设置，则更改请求的 HTTP 头。头部的值会被转换为字符串。

  • method str (可选)#

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

  • post_data str | bytes | Dict (可选)#

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

  • url str (可选)#

    如果设置，则更改请求的 URL。新 URL 必须与原始 URL 使用相同的协议。

返回值

详细说明

headers 选项会同时应用于被路由的请求及其发起的任何重定向。但 url、method 和 post_data 只会应用于原始请求，不会传递到重定向的请求中。

route.continue_() 会立即将请求发送到网络，其他匹配的处理器不会被调用。如果你希望调用链中的下一个匹配处理器，请使用 route.fallback()。

注意

无法通过此方法覆盖 Cookie 请求头。如果提供了该值，将被忽略，Cookie 会从浏览器的 Cookie 存储中加载。要设置自定义 Cookie，请使用 browser_context.add_cookies()。

fallback​

v1.23 之后添加 route.fallback

继续路由的请求，并可选择覆盖部分参数。该方法与 route.continue_() 类似，不同之处在于，在发送请求之前，其他匹配的处理器也会被调用。

用法

当多个路由匹配给定的模式时，它们会按照注册顺序的相反顺序运行。这样，最后注册的路由总是可以覆盖之前的所有路由。在下面的示例中，请求会首先由最底部的处理器处理，然后回退到上一个，最后会被第一个注册的路由中止。

page.route("**/*", lambda route: route.abort())  # 最后执行。
page.route("**/*", lambda route: route.fallback())  # 第二个执行。
page.route("**/*", lambda route: route.fallback())  # 第一个执行。

注册多个路由在你希望用不同的处理器处理不同类型的请求时非常有用，例如 API 调用与页面资源，或 GET 请求与 POST 请求，见下例。

# 处理 GET 请求。
def handle_get(route):
    if route.request.method != "GET":
        route.fallback()
        return
    # 只处理 GET。
    # ...

# 处理 POST 请求。
def handle_post(route):
    if route.request.method != "POST":
        route.fallback()
        return
    # 只处理 POST。
    # ...

page.route("**/*", handle_get)
page.route("**/*", handle_post)

你也可以在回退到下一个处理器时修改请求，这样中间的路由处理器可以修改请求的 url、method、headers 和 postData。

def handle(route, request):
    # 覆盖请求头
    headers = {
        **request.headers,
        "foo": "foo-value", # 设置 "foo" 请求头
        "bar": None # 移除 "bar" 请求头
    }
    route.fallback(headers=headers)

page.route("**/*", handle)

使用 route.continue_() 可以立即将请求发送到网络，此时不会再调用其他匹配的处理器。

参数

  • headers Dict[str, str] (可选)#

    如果设置，则更改请求的 HTTP 头。头部的值会被转换为字符串。

  • method str (可选)#

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

  • post_data str | bytes | Dict (可选)#

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

  • url str (可选)#

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

返回值

fetch​

v1.29 之后添加 route.fetch

执行请求并获取结果，但不会立即 fulfill 响应，因此可以在 fulfill 前对响应进行修改。

用法

def handle(route):
    response = route.fetch()
    json = response.json()
    json["message"]["big_red_dog"] = []
    route.fulfill(response=response, json=json)

page.route("https://dog.ceo/api/breeds/list/all", handle)

参数

  • headers Dict[str, str] (可选)#

    如果设置，则更改请求的 HTTP 头。头部的值会被转换为字符串。

  • max_redirects int (可选) v1.31 之后添加#

    自动跟随的最大重定向次数。如果超过该数量会抛出错误。默认为 20。传递 0 表示不跟随重定向。

  • max_retries int (可选) v1.46 之后添加#

    网络错误最大重试次数。目前仅会重试 ECONNRESET 错误。不会根据 HTTP 响应码重试。如果超过限制会抛出错误。默认为 0，即不重试。

  • method str (可选)#

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

  • post_data str | bytes | Dict (可选)#

    设置请求的 post 数据。如果 data 参数是对象，会被序列化为 json 字符串，并且如果未显式设置，则 content-type 头会被设置为 application/json。否则如果未显式设置，content-type 头会被设置为 application/octet-stream。

  • timeout float (可选) v1.33 之后添加#

    请求超时时间（毫秒）。默认为 30000（30 秒）。传递 0 表示不设置超时。

  • url str (可选)#

    如果设置，则更改请求的 URL。新 URL 必须与原始 URL 使用相同的协议。

返回值

详细说明

注意，headers 选项会应用于被 fetch 的请求及其发起的所有重定向。如果你只想让 headers 作用于原始请求而不作用于重定向，请使用 route.continue_()。

fulfill​

v1.9 之前添加 route.fulfill

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

用法

以下示例将所有请求 fulfill 为 404 响应：

page.route("**/*", lambda route: route.fulfill(
    status=404,
    content_type="text/plain",
    body="not found!"))

以下示例用于返回静态文件：

page.route("**/xhr_endpoint", lambda route: route.fulfill(path="mock_data.json"))

参数

  • body str | bytes (可选)#

    响应体内容。

  • content_type str (可选)#

    如果设置，等同于设置 Content-Type 响应头。

  • headers Dict[str, str] (可选)#

    响应头。头部的值会被转换为字符串。

  • json Dict (可选) v1.29 之后添加#

    JSON 响应。如果未设置 content type，会自动设置为 application/json。

  • path Union[str, pathlib.Path] (可选)#

    用于响应的文件路径。content type 会根据文件扩展名自动推断。如果 path 是相对路径，则会以当前工作目录为基准解析。

  • response APIResponse (可选) v1.15 之后添加#

    用于 fulfill 路由请求的 APIResponse。可以通过 fulfill 选项覆盖响应的各个字段（如 headers）。

  • status int (可选)#

    响应状态码，默认为 200。

返回值

属性​

request​

v1.9 之前添加 route.request

要被路由的请求。

用法

route.request

返回值