原生 Route

原生 API 目录 · 手册目录

方法与属性索引

• abort
• continue_
• fallback
• fetch
• fulfill
• on
• once
• remove_listener
• request

abort

同步

def abort(self, error_code: Optional[str] = None) -> None

Route.abort

Aborts the route's request.

Parameters

异步

async def abort(self, error_code: Optional[str] = None) -> None

Route.abort

Aborts the route's request.

Parameters

continue_

同步

def continue_(self, *, headers: Optional[Dict[str, str]] = None, method: Optional[str] = None, post_data: Union[str, bytes, Any, NoneType] = None, url: Optional[str] = None, patchrightInitScript: Optional[bool] = None) -> None

Route.continue_

Sends route's request to the network with optional overrides.

Usage

def handle(route, request):
    # override headers
    headers = {
        **request.headers,
        "foo": "foo-value", # set "foo" header
        "bar": None # remove "bar" header
    }
    route.continue_(headers=headers)

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

Details

The headers option applies to both the routed request and any redirects it initiates. However, url, method, and post_data only apply to the original request and are not carried over to redirected requests.

route.continue_() will immediately send the request to the network, other matching handlers won't be invoked. Use route.fallback() If you want next matching handler in the chain to be invoked.

NOTE Some request headers are forbidden and cannot be overridden (for example, Cookie, Host, Content-Length and others, see this MDN page for full list). If an override is provided for a forbidden header, it will be ignored and the original request header will be used.

To set custom cookies, use browser_context.add_cookies().

Parameters

异步

async def continue_(self, *, headers: Optional[Dict[str, str]] = None, method: Optional[str] = None, post_data: Union[str, bytes, Any, NoneType] = None, url: Optional[str] = None, patchrightInitScript: Optional[bool] = None) -> None

Route.continue_

Sends route's request to the network with optional overrides.

Usage

async def handle(route, request):
    # override headers
    headers = {
        **request.headers,
        "foo": "foo-value", # set "foo" header
        "bar": None # remove "bar" header
    }
    await route.continue_(headers=headers)

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

Details

The headers option applies to both the routed request and any redirects it initiates. However, url, method, and post_data only apply to the original request and are not carried over to redirected requests.

route.continue_() will immediately send the request to the network, other matching handlers won't be invoked. Use route.fallback() If you want next matching handler in the chain to be invoked.

NOTE Some request headers are forbidden and cannot be overridden (for example, Cookie, Host, Content-Length and others, see this MDN page for full list). If an override is provided for a forbidden header, it will be ignored and the original request header will be used.

To set custom cookies, use browser_context.add_cookies().

Parameters

fallback

同步

def fallback(self, *, headers: Optional[Dict[str, str]] = None, method: Optional[str] = None, post_data: Union[str, bytes, Any, NoneType] = None, url: Optional[str] = None, patchrightInitScript: Optional[bool] = None) -> None

Route.fallback

Continues route's request with optional overrides. The method is similar to route.continue_() with the difference that other matching handlers will be invoked before sending the request.

Usage

When several routes match the given pattern, they run in the order opposite to their registration. That way the last registered route can always override all the previous ones. In the example below, request will be handled by the bottom-most handler first, then it'll fall back to the previous one and in the end will be aborted by the first registered route.

page.route("**/*", lambda route: route.abort())  # Runs last.
page.route("**/*", lambda route: route.fallback())  # Runs second.
page.route("**/*", lambda route: route.fallback())  # Runs first.

Registering multiple routes is useful when you want separate handlers to handle different kinds of requests, for example API calls vs page resources or GET requests vs POST requests as in the example below.

# Handle GET requests.
def handle_get(route):
    if route.request.method != "GET":
        route.fallback()
        return
  # Handling GET only.
  # ...

# Handle POST requests.
def handle_post(route):
    if route.request.method != "POST":
        route.fallback()
        return
  # Handling POST only.
  # ...

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

One can also modify request while falling back to the subsequent handler, that way intermediate route handler can modify url, method, headers and postData of the request.

def handle(route, request):
    # override headers
    headers = {
        **request.headers,
        "foo": "foo-value", # set "foo" header
        "bar": None # remove "bar" header
    }
    route.fallback(headers=headers)

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

Use route.continue_() to immediately send the request to the network, other matching handlers won't be invoked in that case.

Parameters

异步

async def fallback(self, *, headers: Optional[Dict[str, str]] = None, method: Optional[str] = None, post_data: Union[str, bytes, Any, NoneType] = None, url: Optional[str] = None, patchrightInitScript: Optional[bool] = None) -> None

Route.fallback

Continues route's request with optional overrides. The method is similar to route.continue_() with the difference that other matching handlers will be invoked before sending the request.

Usage

When several routes match the given pattern, they run in the order opposite to their registration. That way the last registered route can always override all the previous ones. In the example below, request will be handled by the bottom-most handler first, then it'll fall back to the previous one and in the end will be aborted by the first registered route.

await page.route("**/*", lambda route: route.abort())  # Runs last.
await page.route("**/*", lambda route: route.fallback())  # Runs second.
await page.route("**/*", lambda route: route.fallback())  # Runs first.

Registering multiple routes is useful when you want separate handlers to handle different kinds of requests, for example API calls vs page resources or GET requests vs POST requests as in the example below.

# Handle GET requests.
async def handle_get(route):
    if route.request.method != "GET":
        await route.fallback()
        return
  # Handling GET only.
  # ...

# Handle POST requests.
async def handle_post(route):
    if route.request.method != "POST":
        await route.fallback()
        return
  # Handling POST only.
  # ...

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

One can also modify request while falling back to the subsequent handler, that way intermediate route handler can modify url, method, headers and postData of the request.

async def handle(route, request):
    # override headers
    headers = {
        **request.headers,
        "foo": "foo-value", # set "foo" header
        "bar": None # remove "bar" header
    }
    await route.fallback(headers=headers)

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

Use route.continue_() to immediately send the request to the network, other matching handlers won't be invoked in that case.

Parameters

fetch

同步

def fetch(self, *, headers: Optional[Dict[str, str]] = None, max_redirects: Optional[int] = None, max_retries: Optional[int] = None, method: Optional[str] = None, post_data: Union[str, bytes, Any, NoneType] = None, timeout: Union[float, datetime.timedelta, NoneType] = None, url: Optional[str] = None) -> 'APIResponse'

Route.fetch

Performs the request and fetches result without fulfilling it, so that the response could be modified and then fulfilled.

Usage

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)

Details

Note that headers option will apply to the fetched request as well as any redirects initiated by it. If you want to only apply headers to the original request, but not to redirects, look into route.continue_() instead.

Parameters

Returns

APIResponse

异步

async def fetch(self, *, headers: Optional[Dict[str, str]] = None, max_redirects: Optional[int] = None, max_retries: Optional[int] = None, method: Optional[str] = None, post_data: Union[str, bytes, Any, NoneType] = None, timeout: Union[float, datetime.timedelta, NoneType] = None, url: Optional[str] = None) -> 'APIResponse'

Route.fetch

Performs the request and fetches result without fulfilling it, so that the response could be modified and then fulfilled.

Usage

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

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

Details

Note that headers option will apply to the fetched request as well as any redirects initiated by it. If you want to only apply headers to the original request, but not to redirects, look into route.continue_() instead.

Parameters

Returns

APIResponse

fulfill

同步

def fulfill(self, *, body: Union[str, bytes, NoneType] = None, content_type: Optional[str] = None, headers: Optional[Dict[str, str]] = None, json: Optional[Any] = None, path: Union[pathlib.Path, str, NoneType] = None, response: Optional[ForwardRef('APIResponse')] = None, status: Optional[int] = None) -> None

Route.fulfill

Fulfills route's request with given response.

Usage

An example of fulfilling all requests with 404 responses:

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

An example of serving static file:

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

Parameters

异步

async def fulfill(self, *, body: Union[str, bytes, NoneType] = None, content_type: Optional[str] = None, headers: Optional[Dict[str, str]] = None, json: Optional[Any] = None, path: Union[pathlib.Path, str, NoneType] = None, response: Optional[ForwardRef('APIResponse')] = None, status: Optional[int] = None) -> None

Route.fulfill

Fulfills route's request with given response.

Usage

An example of fulfilling all requests with 404 responses:

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

An example of serving static file:

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

Parameters

on

同步

def on(self, event: Any, f: Any) -> None

Registers the function f to the event name event.

异步

def on(self, event: Any, f: Any) -> None

Registers the function f to the event name event.

once

同步

def once(self, event: Any, f: Any) -> None

The same as self.on, except that the listener is automatically removed after being called.

异步

def once(self, event: Any, f: Any) -> None

The same as self.on, except that the listener is automatically removed after being called.

remove_listener

同步

def remove_listener(self, event: Any, f: Any) -> None

Removes the function f from event.

异步

def remove_listener(self, event: Any, f: Any) -> None

Removes the function f from event.

request

属性，直接读取；异步入口也不加 await。

Route.request: Request

Route.request

A request to be routed.

Returns

Request