跳到主要內容

APIRequestContext

此 API 用於 Web API 測試。您可以使用它來觸發 API 端點、設定微服務、準備環境或服務以進行端對端測試。

每個 Playwright 瀏覽器內容都與一個 APIRequestContext 實例相關聯,該實例與瀏覽器內容共用 Cookie 儲存空間,並且可以透過 browser_context.requestpage.request 存取。也可以透過呼叫 api_request.new_context() 手動建立新的 APIRequestContext 實例。

Cookie 管理

browser_context.requestpage.request 傳回的 APIRequestContext 與對應的 BrowserContext 共用 Cookie 儲存空間。每個 API 請求都會具有 Cookie 標頭,其中填入來自瀏覽器內容的值。如果 API 回應包含 Set-Cookie 標頭,它將自動更新 BrowserContext Cookie,並且從頁面發出的請求將會提取它們。這表示如果您使用此 API 登入,您的端對端測試將會處於登入狀態,反之亦然。

如果您希望 API 請求不干擾瀏覽器 Cookie,您應該透過呼叫 api_request.new_context() 建立新的 APIRequestContext。此類 APIRequestContext 物件將具有其自己的隔離 Cookie 儲存空間。

import os
from playwright.sync_api import sync_playwright

REPO = "test-repo-1"
USER = "github-username"
API_TOKEN = os.getenv("GITHUB_API_TOKEN")

with sync_playwright() as p:
# This will launch a new browser, create a context and page. When making HTTP
# requests with the internal APIRequestContext (e.g. `context.request` or `page.request`)
# it will automatically set the cookies to the browser page and vice versa.
browser = p.chromium.launch()
context = browser.new_context(base_url="https://api.github.com")
api_request_context = context.request
page = context.new_page()

# Alternatively you can create a APIRequestContext manually without having a browser context attached:
# api_request_context = p.request.new_context(base_url="https://api.github.com")


# Create a repository.
response = api_request_context.post(
"/user/repos",
headers={
"Accept": "application/vnd.github.v3+json",
# Add GitHub personal access token.
"Authorization": f"token {API_TOKEN}",
},
data={"name": REPO},
)
assert response.ok
assert response.json()["name"] == REPO

# Delete a repository.
response = api_request_context.delete(
f"/repos/{USER}/{REPO}",
headers={
"Accept": "application/vnd.github.v3+json",
# Add GitHub personal access token.
"Authorization": f"token {API_TOKEN}",
},
)
assert response.ok
assert await response.body() == '{"status": "ok"}'

方法

delete

新增於:v1.16 apiRequestContext.delete

傳送 HTTP(S) DELETE 請求並傳回其回應。此方法將會從內容填入請求 Cookie,並從回應更新內容 Cookie。此方法將會自動追蹤重新導向。

用法

api_request_context.delete(url)
api_request_context.delete(url, **kwargs)

引數

  • url str#

    目標 URL。

  • data str | bytes | Serializable (選用)新增於:v1.17#

    允許設定請求的 post 資料。如果 data 參數是物件,它將會序列化為 json 字串,並且如果未明確設定,content-type 標頭將會設定為 application/json。否則,如果未明確設定,content-type 標頭將會設定為 application/octet-stream

  • fail_on_status_code bool (選用)#

    是否在 2xx 和 3xx 以外的回應代碼上擲回例外。預設會針對所有狀態代碼傳回回應物件。

  • form Dict[str, str | float | bool] (選用)新增於:v1.17#

    提供一個物件,該物件將使用 application/x-www-form-urlencoded 編碼序列化為 html 表單,並作為此請求的主體傳送。如果指定此參數,除非明確提供,否則 content-type 標頭將會設定為 application/x-www-form-urlencoded

  • headers Dict[str, str] (選用)#

    允許設定 HTTP 標頭。這些標頭將適用於擷取的請求以及由此請求啟動的任何重新導向。

  • ignore_https_errors bool (選用)#

    是否在傳送網路請求時忽略 HTTPS 錯誤。預設為 false

  • max_redirects int (選用)新增於:v1.26#

    將自動追蹤的最大請求重新導向次數。如果超過次數,將會擲回錯誤。預設為 20。傳遞 0 以不追蹤重新導向。

  • max_retries int (選用)新增於:v1.46#

    應重試網路錯誤的最大次數。目前僅重試 ECONNRESET 錯誤。不會根據 HTTP 回應代碼重試。如果超過限制,將會擲回錯誤。預設為 0 - 不重試。

  • multipart Dict[str, str | float | bool | [ReadStream] | Dict] (選用)新增於:v1.17#

    • name str

      檔案名稱

    • mimeType str

      檔案類型

    • buffer bytes

      檔案內容

    提供一個物件,該物件將使用 multipart/form-data 編碼序列化為 html 表單,並作為此請求的主體傳送。如果指定此參數,除非明確提供,否則 content-type 標頭將會設定為 multipart/form-data。檔案值可以作為包含檔案名稱、mime 類型及其內容的類檔案物件傳遞。

  • params Dict[str, str | float | bool] | str (選用)#

    要與 URL 一起傳送的查詢參數。

  • timeout float (選用)#

    請求逾時時間,以毫秒為單位。預設為 30000 (30 秒)。傳遞 0 以停用逾時。

傳回


dispose

新增於:v1.16 apiRequestContext.dispose

api_request_context.get() 和類似方法傳回的所有回應都儲存在記憶體中,以便您稍後可以呼叫 api_response.body()。此方法會捨棄其所有資源,在已處置的 APIRequestContext 上呼叫任何方法都會擲回例外。

用法

api_request_context.dispose()
api_request_context.dispose(**kwargs)

引數

  • reason str (選用)新增於:v1.45#

    要報告給內容處置中斷的操作的原因。

傳回


fetch

新增於:v1.16 apiRequestContext.fetch

傳送 HTTP(S) 請求並傳回其回應。此方法將會從內容填入請求 Cookie,並從回應更新內容 Cookie。此方法將會自動追蹤重新導向。

用法

JSON 物件可以直接傳遞到請求

data = {
"title": "Book Title",
"body": "John Doe",
}
api_request_context.fetch("https://example.com/api/createBook", method="post", data=data)

在請求主體中傳送檔案的常用方法是以 multipart/form-data 編碼將其作為表單欄位上傳,方法是指定 multipart 參數

api_request_context.fetch(
"https://example.com/api/uploadScript", method="post",
multipart={
"fileField": {
"name": "f.js",
"mimeType": "text/javascript",
"buffer": b"console.log(2022);",
},
})

引數

  • url_or_request str | Request#

    目標 URL 或 Request,用於從中取得所有參數。

  • data str | bytes | Serializable (選用)#

    允許設定請求的 post 資料。如果 data 參數是物件,它將會序列化為 json 字串,並且如果未明確設定,content-type 標頭將會設定為 application/json。否則,如果未明確設定,content-type 標頭將會設定為 application/octet-stream

  • fail_on_status_code bool (選用)#

    是否在 2xx 和 3xx 以外的回應代碼上擲回例外。預設會針對所有狀態代碼傳回回應物件。

  • form Dict[str, str | float | bool] (選用)#

    提供一個物件,該物件將使用 application/x-www-form-urlencoded 編碼序列化為 html 表單,並作為此請求的主體傳送。如果指定此參數,除非明確提供,否則 content-type 標頭將會設定為 application/x-www-form-urlencoded

  • headers Dict[str, str] (選用)#

    允許設定 HTTP 標頭。這些標頭將適用於擷取的請求以及由此請求啟動的任何重新導向。

  • ignore_https_errors bool (選用)#

    是否在傳送網路請求時忽略 HTTPS 錯誤。預設為 false

  • max_redirects int (選用)新增於:v1.26#

    將自動追蹤的最大請求重新導向次數。如果超過次數,將會擲回錯誤。預設為 20。傳遞 0 以不追蹤重新導向。

  • max_retries int (選用)新增於:v1.46#

    應重試網路錯誤的最大次數。目前僅重試 ECONNRESET 錯誤。不會根據 HTTP 回應代碼重試。如果超過限制,將會擲回錯誤。預設為 0 - 不重試。

  • method str (選用)#

    如果設定,則變更擷取方法 (例如 PUTPOST)。如果未指定,則會使用 GET 方法。

  • multipart Dict[str, str | float | bool | [ReadStream] | Dict] (選用)#

    • name str

      檔案名稱

    • mimeType str

      檔案類型

    • buffer bytes

      檔案內容

    提供一個物件,該物件將使用 multipart/form-data 編碼序列化為 html 表單,並作為此請求的主體傳送。如果指定此參數,除非明確提供,否則 content-type 標頭將會設定為 multipart/form-data。檔案值可以作為包含檔案名稱、mime 類型及其內容的類檔案物件傳遞。

  • params Dict[str, str | float | bool] | str (選用)#

    要與 URL 一起傳送的查詢參數。

  • timeout float (選用)#

    請求逾時時間,以毫秒為單位。預設為 30000 (30 秒)。傳遞 0 以停用逾時。

傳回


get

新增於:v1.16 apiRequestContext.get

傳送 HTTP(S) GET 請求並傳回其回應。此方法將會從內容填入請求 Cookie,並從回應更新內容 Cookie。此方法將會自動追蹤重新導向。

用法

可以使用 params 選項設定請求參數,它們將會序列化為 URL 搜尋參數

query_params = {
"isbn": "1234",
"page": "23"
}
api_request_context.get("https://example.com/api/getText", params=query_params)

引數

  • url str#

    目標 URL。

  • data str | bytes | Serializable (選用)新增於:v1.26#

    允許設定請求的 post 資料。如果 data 參數是物件,它將會序列化為 json 字串,並且如果未明確設定,content-type 標頭將會設定為 application/json。否則,如果未明確設定,content-type 標頭將會設定為 application/octet-stream

  • fail_on_status_code bool (選用)#

    是否在 2xx 和 3xx 以外的回應代碼上擲回例外。預設會針對所有狀態代碼傳回回應物件。

  • form Dict[str, str | float | bool] (選用)新增於:v1.26#

    提供一個物件,該物件將使用 application/x-www-form-urlencoded 編碼序列化為 html 表單,並作為此請求的主體傳送。如果指定此參數,除非明確提供,否則 content-type 標頭將會設定為 application/x-www-form-urlencoded

  • headers Dict[str, str] (選用)#

    允許設定 HTTP 標頭。這些標頭將適用於擷取的請求以及由此請求啟動的任何重新導向。

  • ignore_https_errors bool (選用)#

    是否在傳送網路請求時忽略 HTTPS 錯誤。預設為 false

  • max_redirects int (選用)新增於:v1.26#

    將自動追蹤的最大請求重新導向次數。如果超過次數,將會擲回錯誤。預設為 20。傳遞 0 以不追蹤重新導向。

  • max_retries int (選用)新增於:v1.46#

    應重試網路錯誤的最大次數。目前僅重試 ECONNRESET 錯誤。不會根據 HTTP 回應代碼重試。如果超過限制,將會擲回錯誤。預設為 0 - 不重試。

  • multipart Dict[str, str | float | bool | [ReadStream] | Dict] (選用)新增於:v1.26#

    • name str

      檔案名稱

    • mimeType str

      檔案類型

    • buffer bytes

      檔案內容

    提供一個物件,該物件將使用 multipart/form-data 編碼序列化為 html 表單,並作為此請求的主體傳送。如果指定此參數,除非明確提供,否則 content-type 標頭將會設定為 multipart/form-data。檔案值可以作為包含檔案名稱、mime 類型及其內容的類檔案物件傳遞。

  • params Dict[str, str | float | bool] | str (選用)#

    要與 URL 一起傳送的查詢參數。

  • timeout float (選用)#

    請求逾時時間,以毫秒為單位。預設為 30000 (30 秒)。傳遞 0 以停用逾時。

傳回


head

新增於:v1.16 apiRequestContext.head

傳送 HTTP(S) HEAD 請求並傳回其回應。此方法將會從內容填入請求 Cookie,並從回應更新內容 Cookie。此方法將會自動追蹤重新導向。

用法

api_request_context.head(url)
api_request_context.head(url, **kwargs)

引數

  • url str#

    目標 URL。

  • data str | bytes | Serializable (選用)新增於:v1.26#

    允許設定請求的 post 資料。如果 data 參數是物件,它將會序列化為 json 字串,並且如果未明確設定,content-type 標頭將會設定為 application/json。否則,如果未明確設定,content-type 標頭將會設定為 application/octet-stream

  • fail_on_status_code bool (選用)#

    是否在 2xx 和 3xx 以外的回應代碼上擲回例外。預設會針對所有狀態代碼傳回回應物件。

  • form Dict[str, str | float | bool] (選用)新增於:v1.26#

    提供一個物件,該物件將使用 application/x-www-form-urlencoded 編碼序列化為 html 表單,並作為此請求的主體傳送。如果指定此參數,除非明確提供,否則 content-type 標頭將會設定為 application/x-www-form-urlencoded

  • headers Dict[str, str] (選用)#

    允許設定 HTTP 標頭。這些標頭將適用於擷取的請求以及由此請求啟動的任何重新導向。

  • ignore_https_errors bool (選用)#

    是否在傳送網路請求時忽略 HTTPS 錯誤。預設為 false

  • max_redirects int (選用)新增於:v1.26#

    將自動追蹤的最大請求重新導向次數。如果超過次數,將會擲回錯誤。預設為 20。傳遞 0 以不追蹤重新導向。

  • max_retries int (選用)新增於:v1.46#

    應重試網路錯誤的最大次數。目前僅重試 ECONNRESET 錯誤。不會根據 HTTP 回應代碼重試。如果超過限制,將會擲回錯誤。預設為 0 - 不重試。

  • multipart Dict[str, str | float | bool | [ReadStream] | Dict] (選用)新增於:v1.26#

    • name str

      檔案名稱

    • mimeType str

      檔案類型

    • buffer bytes

      檔案內容

    提供一個物件,該物件將使用 multipart/form-data 編碼序列化為 html 表單,並作為此請求的主體傳送。如果指定此參數,除非明確提供,否則 content-type 標頭將會設定為 multipart/form-data。檔案值可以作為包含檔案名稱、mime 類型及其內容的類檔案物件傳遞。

  • params Dict[str, str | float | bool] | str (選用)#

    要與 URL 一起傳送的查詢參數。

  • timeout float (選用)#

    請求逾時時間,以毫秒為單位。預設為 30000 (30 秒)。傳遞 0 以停用逾時。

傳回


patch

新增於:v1.16 apiRequestContext.patch

傳送 HTTP(S) PATCH 請求並傳回其回應。此方法將會從內容填入請求 Cookie,並從回應更新內容 Cookie。此方法將會自動追蹤重新導向。

用法

api_request_context.patch(url)
api_request_context.patch(url, **kwargs)

引數

  • url str#

    目標 URL。

  • data str | bytes | Serializable (選用)#

    允許設定請求的 post 資料。如果 data 參數是物件,它將會序列化為 json 字串,並且如果未明確設定,content-type 標頭將會設定為 application/json。否則,如果未明確設定,content-type 標頭將會設定為 application/octet-stream

  • fail_on_status_code bool (選用)#

    是否在 2xx 和 3xx 以外的回應代碼上擲回例外。預設會針對所有狀態代碼傳回回應物件。

  • form Dict[str, str | float | bool] (選用)#

    提供一個物件,該物件將使用 application/x-www-form-urlencoded 編碼序列化為 html 表單,並作為此請求的主體傳送。如果指定此參數,除非明確提供,否則 content-type 標頭將會設定為 application/x-www-form-urlencoded

  • headers Dict[str, str] (選用)#

    允許設定 HTTP 標頭。這些標頭將適用於擷取的請求以及由此請求啟動的任何重新導向。

  • ignore_https_errors bool (選用)#

    是否在傳送網路請求時忽略 HTTPS 錯誤。預設為 false

  • max_redirects int (選用)新增於:v1.26#

    將自動追蹤的最大請求重新導向次數。如果超過次數,將會擲回錯誤。預設為 20。傳遞 0 以不追蹤重新導向。

  • max_retries int (選用)新增於:v1.46#

    應重試網路錯誤的最大次數。目前僅重試 ECONNRESET 錯誤。不會根據 HTTP 回應代碼重試。如果超過限制,將會擲回錯誤。預設為 0 - 不重試。

  • multipart Dict[str, str | float | bool | [ReadStream] | Dict] (選用)#

    • name str

      檔案名稱

    • mimeType str

      檔案類型

    • buffer bytes

      檔案內容

    提供一個物件,該物件將使用 multipart/form-data 編碼序列化為 html 表單,並作為此請求的主體傳送。如果指定此參數,除非明確提供,否則 content-type 標頭將會設定為 multipart/form-data。檔案值可以作為包含檔案名稱、mime 類型及其內容的類檔案物件傳遞。

  • params Dict[str, str | float | bool] | str (選用)#

    要與 URL 一起傳送的查詢參數。

  • timeout float (選用)#

    請求逾時時間,以毫秒為單位。預設為 30000 (30 秒)。傳遞 0 以停用逾時。

傳回


post

新增於:v1.16 apiRequestContext.post

傳送 HTTP(S) POST 請求並傳回其回應。此方法將會從內容填入請求 Cookie,並從回應更新內容 Cookie。此方法將會自動追蹤重新導向。

用法

JSON 物件可以直接傳遞到請求

data = {
"title": "Book Title",
"body": "John Doe",
}
api_request_context.post("https://example.com/api/createBook", data=data)

若要將表單資料傳送至伺服器,請使用 form 選項。其值將會使用 application/x-www-form-urlencoded 編碼編碼到請求主體中 (請參閱下方如何使用 multipart/form-data 表單編碼來傳送檔案)

formData = {
"title": "Book Title",
"body": "John Doe",
}
api_request_context.post("https://example.com/api/findBook", form=formData)

在請求主體中傳送檔案的常用方法是以 multipart/form-data 編碼將其作為表單欄位上傳。使用 [FormData] 建構請求主體,並將其作為 multipart 參數傳遞至請求

api_request_context.post(
"https://example.com/api/uploadScript'",
multipart={
"fileField": {
"name": "f.js",
"mimeType": "text/javascript",
"buffer": b"console.log(2022);",
},
})

引數

  • url str#

    目標 URL。

  • data str | bytes | Serializable (選用)#

    允許設定請求的 post 資料。如果 data 參數是物件,它將會序列化為 json 字串,並且如果未明確設定,content-type 標頭將會設定為 application/json。否則,如果未明確設定,content-type 標頭將會設定為 application/octet-stream

  • fail_on_status_code bool (選用)#

    是否在 2xx 和 3xx 以外的回應代碼上擲回例外。預設會針對所有狀態代碼傳回回應物件。

  • form Dict[str, str | float | bool] (選用)#

    提供一個物件,該物件將使用 application/x-www-form-urlencoded 編碼序列化為 html 表單,並作為此請求的主體傳送。如果指定此參數,除非明確提供,否則 content-type 標頭將會設定為 application/x-www-form-urlencoded

  • headers Dict[str, str] (選用)#

    允許設定 HTTP 標頭。這些標頭將適用於擷取的請求以及由此請求啟動的任何重新導向。

  • ignore_https_errors bool (選用)#

    是否在傳送網路請求時忽略 HTTPS 錯誤。預設為 false

  • max_redirects int (選用)新增於:v1.26#

    將自動追蹤的最大請求重新導向次數。如果超過次數,將會擲回錯誤。預設為 20。傳遞 0 以不追蹤重新導向。

  • max_retries int (選用)新增於:v1.46#

    應重試網路錯誤的最大次數。目前僅重試 ECONNRESET 錯誤。不會根據 HTTP 回應代碼重試。如果超過限制,將會擲回錯誤。預設為 0 - 不重試。

  • multipart Dict[str, str | float | bool | [ReadStream] | Dict] (選用)#

    • name str

      檔案名稱

    • mimeType str

      檔案類型

    • buffer bytes

      檔案內容

    提供一個物件,該物件將使用 multipart/form-data 編碼序列化為 html 表單,並作為此請求的主體傳送。如果指定此參數,除非明確提供,否則 content-type 標頭將會設定為 multipart/form-data。檔案值可以作為包含檔案名稱、mime 類型及其內容的類檔案物件傳遞。

  • params Dict[str, str | float | bool] | str (選用)#

    要與 URL 一起傳送的查詢參數。

  • timeout float (選用)#

    請求逾時時間,以毫秒為單位。預設為 30000 (30 秒)。傳遞 0 以停用逾時。

傳回


put

新增於:v1.16 apiRequestContext.put

傳送 HTTP(S) PUT 請求並傳回其回應。此方法將會從內容填入請求 Cookie,並從回應更新內容 Cookie。此方法將會自動追蹤重新導向。

用法

api_request_context.put(url)
api_request_context.put(url, **kwargs)

引數

  • url str#

    目標 URL。

  • data str | bytes | Serializable (選用)#

    允許設定請求的 post 資料。如果 data 參數是物件,它將會序列化為 json 字串,並且如果未明確設定,content-type 標頭將會設定為 application/json。否則,如果未明確設定,content-type 標頭將會設定為 application/octet-stream

  • fail_on_status_code bool (選用)#

    是否在 2xx 和 3xx 以外的回應代碼上擲回例外。預設會針對所有狀態代碼傳回回應物件。

  • form Dict[str, str | float | bool] (選用)

    提供一個物件,該物件將使用 application/x-www-form-urlencoded 編碼序列化為 html 表單,並作為此請求的主體傳送。如果指定此參數,除非明確提供,否則 content-type 標頭將會設定為 application/x-www-form-urlencoded

  • headers Dict[str, str] (選填)#

    允許設定 HTTP 標頭。這些標頭將適用於擷取的請求以及由此請求啟動的任何重新導向。

  • ignore_https_errors bool (選填)#

    是否在傳送網路請求時忽略 HTTPS 錯誤。預設為 false

  • max_redirects int (選用)新增於:v1.26#

    將自動追蹤的最大請求重新導向次數。如果超過次數,將會擲回錯誤。預設為 20。傳遞 0 以不追蹤重新導向。

  • max_retries int (選用)新增於:v1.46#

    應重試網路錯誤的最大次數。目前僅重試 ECONNRESET 錯誤。不會根據 HTTP 回應代碼重試。如果超過限制,將會擲回錯誤。預設為 0 - 不重試。

  • multipart Dict[str, str | float | bool | [ReadStream] | Dict] (選填)#

    • name str

      檔案名稱

    • mimeType str

      檔案類型

    • buffer bytes

      檔案內容

    提供一個物件,該物件將使用 multipart/form-data 編碼序列化為 html 表單,並作為此請求的主體傳送。如果指定此參數,除非明確提供,否則 content-type 標頭將會設定為 multipart/form-data。檔案值可以作為包含檔案名稱、mime 類型及其內容的類檔案物件傳遞。

  • params Dict[str, str | float | bool] | str (選填)#

    要與 URL 一起傳送的查詢參數。

  • timeout float (選填)#

    請求逾時時間,以毫秒為單位。預設為 30000 (30 秒)。傳遞 0 以停用逾時。

傳回


storage_state

新增於:v1.16 apiRequestContext.storage_state

傳回此請求上下文的儲存狀態,如果已傳遞至建構函式,則包含目前的 Cookie 和本機儲存體快照。

用法

api_request_context.storage_state()
api_request_context.storage_state(**kwargs)

引數

  • path Union[str, pathlib.Path] (選填)#

    儲存儲存狀態的檔案路徑。如果 path 是相對路徑,則會相對於目前的工作目錄解析。如果未提供路徑,儲存狀態仍會傳回,但不會儲存到磁碟。

傳回