APIRequestContext

此 API 用于 Web API 测试。您可以使用它触发 API 端点、配置微服务、准备环境或服务以进行端到端测试。

每个 Playwright 浏览器上下文都关联一个 APIRequestContext 实例，该实例与浏览器上下文共享 Cookie 存储，可以通过 BrowserContext.APIRequest 或 Page.APIRequest 访问。也可以通过调用 ApiRequest.NewContextAsync() 手动创建一个新的 APIRequestContext 实例。

Cookie 管理

由 BrowserContext.APIRequest 和 Page.APIRequest 返回的 APIRequestContext 与相应的 BrowserContext 共享 Cookie 存储。每个 API 请求的 Cookie 头都会填充浏览器上下文中的值。如果 API 响应包含 Set-Cookie 头，它将自动更新 BrowserContext Cookie，并且页面发出的请求将获取这些 Cookie。这意味着如果您使用此 API 登录，您的端到端测试也将登录，反之亦然。

如果您希望 API 请求不干扰浏览器 Cookie，您应该通过调用 ApiRequest.NewContextAsync() 来创建一个新的 APIRequestContext。这样的 APIRequestContext 对象将拥有自己独立的 Cookie 存储。

方法

CreateFormData

添加于：v1.23

apiRequestContext.CreateFormData

创建一个新的 FormData 实例，用于在发出 HTTP 请求时提供表单和多部分数据。

用法

ApiRequestContext.CreateFormData

FormData #

DeleteAsync

添加于：v1.16

apiRequestContext.DeleteAsync

发送 HTTP(S) DELETE 请求并返回其响应。该方法将从上下文中填充请求 Cookie 并从响应中更新上下文 Cookie。该方法将自动遵循重定向。

用法

await ApiRequestContext.DeleteAsync(url, options);

参数

url string #

目标 URL。
options ApiRequestContextDeleteOptions? （可选）
- Data|DataByte|DataObject string? | byte[]? | [object]? （可选）新增于: v1.17#
  
  允许设置请求的 POST 数据。如果数据参数是一个对象，它将被序列化为 JSON 字符串，并且如果未明确设置，content-type 头将设置为 application/json。否则，如果未明确设置，content-type 头将设置为 application/octet-stream。
- FailOnStatusCode bool? （可选）#
  
  是否在除 2xx 和 3xx 之外的响应码时抛出错误。默认情况下，所有状态码都会返回响应对象。
- Form FormData? （可选）新增于: v1.17#
  
  提供一个对象，该对象将使用 application/x-www-form-urlencoded 编码序列化为 HTML 表单并作为此请求正文发送。如果指定此参数，除非明确提供，否则 content-type 头将设置为 application/x-www-form-urlencoded。
  
  FormData 的实例可以通过 ApiRequestContext.CreateFormData 创建。
- Headers IDictionary?<string, string> （可选）#
  
  允许设置 HTTP 头。这些头将应用于获取的请求以及由其发起的任何重定向。
- IgnoreHTTPSErrors bool? （可选）#
  
  发送网络请求时是否忽略 HTTPS 错误。默认为 false。
- MaxRedirects int? （可选）新增于: v1.26#
  
  将自动遵循的最大请求重定向次数。如果超过此数字，将抛出错误。默认为 20。传递 0 表示不遵循重定向。
- MaxRetries int? （可选）新增于: v1.46#
  
  网络错误的最大重试次数。目前只重试 ECONNRESET 错误。不根据 HTTP 响应代码重试。如果超过限制，将抛出错误。默认为 0 - 不重试。
- Multipart FormData? （可选）新增于: v1.17#
  
  提供一个对象，该对象将使用 multipart/form-data 编码序列化为 HTML 表单并作为此请求正文发送。如果指定此参数，除非明确提供，否则 content-type 头将设置为 multipart/form-data。文件值可以作为包含文件名、MIME 类型及其内容的文件类对象传递。
  
  FormData 的实例可以通过 ApiRequestContext.CreateFormData 创建。
- Params IDictionary?<string, [object]> （可选）#
  
  随 URL 发送的查询参数。
- ParamsString string? （可选）添加于：v1.47#
  
  随 URL 发送的查询参数。
- Timeout [float]? （可选）#
  
  请求超时时间（毫秒）。默认为 30000 (30 秒)。传递 0 表示禁用超时。

APIResponse #

DisposeAsync

添加于：v1.16

apiRequestContext.DisposeAsync

ApiRequestContext.GetAsync() 和类似方法返回的所有响应都存储在内存中，以便您以后可以调用 ApiResponse.BodyAsync()。此方法会丢弃其所有资源，调用已释放的 APIRequestContext 上的任何方法都将抛出异常。

用法

await ApiRequestContext.DisposeAsync(options);

参数

options ApiRequestContextDisposeOptions? （可选）
- Reason string? (可选)新增于: v1.45#
  
  报告给因上下文处置而中断的操作的原因。

void #

FetchAsync

添加于：v1.16

apiRequestContext.FetchAsync

发送 HTTP(S) 请求并返回其响应。该方法将从上下文中填充请求 cookie，并从响应中更新上下文 cookie。该方法将自动遵循重定向。

用法

JSON 对象可以直接传递给请求。

var data = new Dictionary<string, object>() {
  { "title", "Book Title" },
  { "body", "John Doe" }
};
await Request.FetchAsync("https://example.com/api/createBook", new() { Method = "post", DataObject = data });

在请求主体中发送文件(s)的常用方法是将它们作为表单字段与 multipart/form-data 编码一起上传，通过指定 multipart 参数。

var file = new FilePayload()
{
    Name = "f.js",
    MimeType = "text/javascript",
    Buffer = System.Text.Encoding.UTF8.GetBytes("console.log(2022);")
};
var multipart = Context.APIRequest.CreateFormData();
multipart.Set("fileField", file);
await Request.FetchAsync("https://example.com/api/uploadScript", new() { Method = "post", Multipart = multipart });

参数

urlOrRequest string | Request #

目标 URL 或从中获取所有参数的请求。
options ApiRequestContextFetchOptions? （可选）
- Data|DataByte|DataObject string? | byte[]? | [object]? （可选）#
  
  允许设置请求的 POST 数据。如果数据参数是一个对象，它将被序列化为 JSON 字符串，并且如果未明确设置，content-type 头将设置为 application/json。否则，如果未明确设置，content-type 头将设置为 application/octet-stream。
- FailOnStatusCode bool? （可选）#
  
  是否在除 2xx 和 3xx 之外的响应码时抛出错误。默认情况下，所有状态码都会返回响应对象。
- Form FormData? （可选）#
  
  提供一个对象，该对象将使用 application/x-www-form-urlencoded 编码序列化为 HTML 表单并作为此请求正文发送。如果指定此参数，除非明确提供，否则 content-type 头将设置为 application/x-www-form-urlencoded。
  
  FormData 的实例可以通过 ApiRequestContext.CreateFormData 创建。
- Headers IDictionary?<string, string> （可选）#
  
  允许设置 HTTP 头。这些头将应用于获取的请求以及由其发起的任何重定向。
- IgnoreHTTPSErrors bool? （可选）#
  
  发送网络请求时是否忽略 HTTPS 错误。默认为 false。
- MaxRedirects int? （可选）新增于: v1.26#
  
  将自动遵循的最大请求重定向次数。如果超过此数字，将抛出错误。默认为 20。传递 0 表示不遵循重定向。
- MaxRetries int? （可选）新增于: v1.46#
  
  网络错误的最大重试次数。目前只重试 ECONNRESET 错误。不根据 HTTP 响应代码重试。如果超过限制，将抛出错误。默认为 0 - 不重试。
- Method string? （可选）#
  
  如果设置，则更改获取方法（例如 PUT 或 POST）。如果未指定，则使用 GET 方法。
- Multipart FormData? （可选）#
  
  提供一个对象，该对象将使用 multipart/form-data 编码序列化为 HTML 表单并作为此请求正文发送。如果指定此参数，除非明确提供，否则 content-type 头将设置为 multipart/form-data。文件值可以作为包含文件名、MIME 类型及其内容的文件类对象传递。
  
  FormData 的实例可以通过 ApiRequestContext.CreateFormData 创建。
- Params IDictionary?<string, [object]> （可选）#
  
  随 URL 发送的查询参数。
- ParamsString string? （可选）添加于：v1.47#
  
  随 URL 发送的查询参数。
- Timeout [float]? （可选）#
  
  请求超时时间（毫秒）。默认为 30000 (30 秒)。传递 0 表示禁用超时。

APIResponse #

GetAsync

添加于：v1.16

apiRequestContext.GetAsync

发送 HTTP(S) GET 请求并返回其响应。该方法将从上下文中填充请求 Cookie 并从响应中更新上下文 Cookie。该方法将自动遵循重定向。

用法

请求参数可以通过 params 选项配置，它们将被序列化为 URL 搜索参数。

var queryParams = new Dictionary<string, object>()
{
  { "isbn", "1234" },
  { "page", 23 },
};
await request.GetAsync("https://example.com/api/getText", new() { Params = queryParams });

参数

url string #

目标 URL。
options ApiRequestContextGetOptions? （可选）
- Data|DataByte|DataObject string? | byte[]? | [object]? （可选）新增于: v1.26#
  
  允许设置请求的 POST 数据。如果数据参数是一个对象，它将被序列化为 JSON 字符串，并且如果未明确设置，content-type 头将设置为 application/json。否则，如果未明确设置，content-type 头将设置为 application/octet-stream。
- FailOnStatusCode bool? （可选）#
  
  是否在除 2xx 和 3xx 之外的响应码时抛出错误。默认情况下，所有状态码都会返回响应对象。
- Form FormData? （可选）新增于: v1.26#
  
  提供一个对象，该对象将使用 application/x-www-form-urlencoded 编码序列化为 HTML 表单并作为此请求正文发送。如果指定此参数，除非明确提供，否则 content-type 头将设置为 application/x-www-form-urlencoded。
  
  FormData 的实例可以通过 ApiRequestContext.CreateFormData 创建。
- Headers IDictionary?<string, string> （可选）#
  
  允许设置 HTTP 头。这些头将应用于获取的请求以及由其发起的任何重定向。
- IgnoreHTTPSErrors bool? （可选）#
  
  发送网络请求时是否忽略 HTTPS 错误。默认为 false。
- MaxRedirects int? （可选）新增于: v1.26#
  
  将自动遵循的最大请求重定向次数。如果超过此数字，将抛出错误。默认为 20。传递 0 表示不遵循重定向。
- MaxRetries int? （可选）新增于: v1.46#
  
  网络错误的最大重试次数。目前只重试 ECONNRESET 错误。不根据 HTTP 响应代码重试。如果超过限制，将抛出错误。默认为 0 - 不重试。
- Multipart FormData? （可选）新增于: v1.26#
  
  提供一个对象，该对象将使用 multipart/form-data 编码序列化为 HTML 表单并作为此请求正文发送。如果指定此参数，除非明确提供，否则 content-type 头将设置为 multipart/form-data。文件值可以作为包含文件名、MIME 类型及其内容的文件类对象传递。
  
  FormData 的实例可以通过 ApiRequestContext.CreateFormData 创建。
- Params IDictionary?<string, [object]> （可选）#
  
  随 URL 发送的查询参数。
- ParamsString string? （可选）添加于：v1.47#
  
  随 URL 发送的查询参数。
- Timeout [float]? （可选）#
  
  请求超时时间（毫秒）。默认为 30000 (30 秒)。传递 0 表示禁用超时。

APIResponse #

HeadAsync

添加于：v1.16

apiRequestContext.HeadAsync

发送 HTTP(S) HEAD 请求并返回其响应。该方法将从上下文中填充请求 Cookie 并从响应中更新上下文 Cookie。该方法将自动遵循重定向。

用法

await ApiRequestContext.HeadAsync(url, options);

参数

url string #

目标 URL。
options ApiRequestContextHeadOptions? （可选）
- Data|DataByte|DataObject string? | byte[]? | [object]? （可选）新增于: v1.26#
  
  允许设置请求的 POST 数据。如果数据参数是一个对象，它将被序列化为 JSON 字符串，并且如果未明确设置，content-type 头将设置为 application/json。否则，如果未明确设置，content-type 头将设置为 application/octet-stream。
- FailOnStatusCode bool? （可选）#
  
  是否在除 2xx 和 3xx 之外的响应码时抛出错误。默认情况下，所有状态码都会返回响应对象。
- Form FormData? （可选）新增于: v1.26#
  
  提供一个对象，该对象将使用 application/x-www-form-urlencoded 编码序列化为 HTML 表单并作为此请求正文发送。如果指定此参数，除非明确提供，否则 content-type 头将设置为 application/x-www-form-urlencoded。
  
  FormData 的实例可以通过 ApiRequestContext.CreateFormData 创建。
- Headers IDictionary?<string, string> （可选）#
  
  允许设置 HTTP 头。这些头将应用于获取的请求以及由其发起的任何重定向。
- IgnoreHTTPSErrors bool? （可选）#
  
  发送网络请求时是否忽略 HTTPS 错误。默认为 false。
- MaxRedirects int? （可选）新增于: v1.26#
  
  将自动遵循的最大请求重定向次数。如果超过此数字，将抛出错误。默认为 20。传递 0 表示不遵循重定向。
- MaxRetries int? （可选）新增于: v1.46#
  
  网络错误的最大重试次数。目前只重试 ECONNRESET 错误。不根据 HTTP 响应代码重试。如果超过限制，将抛出错误。默认为 0 - 不重试。
- Multipart FormData? （可选）新增于: v1.26#
  
  提供一个对象，该对象将使用 multipart/form-data 编码序列化为 HTML 表单并作为此请求正文发送。如果指定此参数，除非明确提供，否则 content-type 头将设置为 multipart/form-data。文件值可以作为包含文件名、MIME 类型及其内容的文件类对象传递。
  
  FormData 的实例可以通过 ApiRequestContext.CreateFormData 创建。
- Params IDictionary?<string, [object]> （可选）#
  
  随 URL 发送的查询参数。
- ParamsString string? （可选）添加于：v1.47#
  
  随 URL 发送的查询参数。
- Timeout [float]? （可选）#
  
  请求超时时间（毫秒）。默认为 30000 (30 秒)。传递 0 表示禁用超时。

APIResponse #

PatchAsync

添加于：v1.16

apiRequestContext.PatchAsync

发送 HTTP(S) PATCH 请求并返回其响应。该方法将从上下文中填充请求 Cookie 并从响应中更新上下文 Cookie。该方法将自动遵循重定向。

用法

await ApiRequestContext.PatchAsync(url, options);

参数

url string #

目标 URL。
options ApiRequestContextPatchOptions? （可选）
- Data|DataByte|DataObject string? | byte[]? | [object]? （可选）#
  
  允许设置请求的 POST 数据。如果数据参数是一个对象，它将被序列化为 JSON 字符串，并且如果未明确设置，content-type 头将设置为 application/json。否则，如果未明确设置，content-type 头将设置为 application/octet-stream。
- FailOnStatusCode bool? （可选）#
  
  是否在除 2xx 和 3xx 之外的响应码时抛出错误。默认情况下，所有状态码都会返回响应对象。
- Form FormData? （可选）#
  
  提供一个对象，该对象将使用 application/x-www-form-urlencoded 编码序列化为 HTML 表单并作为此请求正文发送。如果指定此参数，除非明确提供，否则 content-type 头将设置为 application/x-www-form-urlencoded。
  
  FormData 的实例可以通过 ApiRequestContext.CreateFormData 创建。
- Headers IDictionary?<string, string> （可选）#
  
  允许设置 HTTP 头。这些头将应用于获取的请求以及由其发起的任何重定向。
- IgnoreHTTPSErrors bool? （可选）#
  
  发送网络请求时是否忽略 HTTPS 错误。默认为 false。
- MaxRedirects int? （可选）新增于: v1.26#
  
  将自动遵循的最大请求重定向次数。如果超过此数字，将抛出错误。默认为 20。传递 0 表示不遵循重定向。
- MaxRetries int? （可选）新增于: v1.46#
  
  网络错误的最大重试次数。目前只重试 ECONNRESET 错误。不根据 HTTP 响应代码重试。如果超过限制，将抛出错误。默认为 0 - 不重试。
- Multipart FormData? （可选）#
  
  提供一个对象，该对象将使用 multipart/form-data 编码序列化为 HTML 表单并作为此请求正文发送。如果指定此参数，除非明确提供，否则 content-type 头将设置为 multipart/form-data。文件值可以作为包含文件名、MIME 类型及其内容的文件类对象传递。
  
  FormData 的实例可以通过 ApiRequestContext.CreateFormData 创建。
- Params IDictionary?<string, [object]> （可选）#
  
  随 URL 发送的查询参数。
- ParamsString string? （可选）添加于：v1.47#
  
  随 URL 发送的查询参数。
- Timeout [float]? （可选）#
  
  请求超时时间（毫秒）。默认为 30000 (30 秒)。传递 0 表示禁用超时。

APIResponse #

PostAsync

添加于：v1.16

apiRequestContext.PostAsync

发送 HTTP(S) POST 请求并返回其响应。该方法将从上下文中填充请求 Cookie 并从响应中更新上下文 Cookie。该方法将自动遵循重定向。

用法

JSON 对象可以直接传递给请求。

var data = new Dictionary<string, object>() {
  { "firstName", "John" },
  { "lastName", "Doe" }
};
await request.PostAsync("https://example.com/api/createBook", new() { DataObject = data });

要向服务器发送表单数据，请使用 form 选项。其值将以 application/x-www-form-urlencoded 编码编码到请求主体中（有关如何使用 multipart/form-data 表单编码发送文件，请参见下文）。

var formData = Context.APIRequest.CreateFormData();
formData.Set("title", "Book Title");
formData.Set("body", "John Doe");
await request.PostAsync("https://example.com/api/findBook", new() { Form = formData });

在请求正文中发送文件的一种常见方式是将它们作为表单字段以上传，使用 multipart/form-data 编码。使用 FormData 构造请求正文并将其作为 multipart 参数传递给请求

var file = new FilePayload()
{
    Name = "f.js",
    MimeType = "text/javascript",
    Buffer = System.Text.Encoding.UTF8.GetBytes("console.log(2022);")
};
var multipart = Context.APIRequest.CreateFormData();
multipart.Set("fileField", file);
await request.PostAsync("https://example.com/api/uploadScript", new() { Multipart = multipart });

参数

url string #

目标 URL。
options ApiRequestContextPostOptions? （可选）
- Data|DataByte|DataObject string? | byte[]? | [object]? （可选）#
  
  允许设置请求的 POST 数据。如果数据参数是一个对象，它将被序列化为 JSON 字符串，并且如果未明确设置，content-type 头将设置为 application/json。否则，如果未明确设置，content-type 头将设置为 application/octet-stream。
- FailOnStatusCode bool? （可选）#
  
  是否在除 2xx 和 3xx 之外的响应码时抛出错误。默认情况下，所有状态码都会返回响应对象。
- Form FormData? （可选）#
  
  提供一个对象，该对象将使用 application/x-www-form-urlencoded 编码序列化为 HTML 表单并作为此请求正文发送。如果指定此参数，除非明确提供，否则 content-type 头将设置为 application/x-www-form-urlencoded。
  
  FormData 的实例可以通过 ApiRequestContext.CreateFormData 创建。
- Headers IDictionary?<string, string> （可选）#
  
  允许设置 HTTP 头。这些头将应用于获取的请求以及由其发起的任何重定向。
- IgnoreHTTPSErrors bool? （可选）#
  
  发送网络请求时是否忽略 HTTPS 错误。默认为 false。
- MaxRedirects int? （可选）新增于: v1.26#
  
  将自动遵循的最大请求重定向次数。如果超过此数字，将抛出错误。默认为 20。传递 0 表示不遵循重定向。
- MaxRetries int? （可选）新增于: v1.46#
  
  网络错误的最大重试次数。目前只重试 ECONNRESET 错误。不根据 HTTP 响应代码重试。如果超过限制，将抛出错误。默认为 0 - 不重试。
- Multipart FormData? （可选）#
  
  提供一个对象，该对象将使用 multipart/form-data 编码序列化为 HTML 表单并作为此请求正文发送。如果指定此参数，除非明确提供，否则 content-type 头将设置为 multipart/form-data。文件值可以作为包含文件名、MIME 类型及其内容的文件类对象传递。
  
  FormData 的实例可以通过 ApiRequestContext.CreateFormData 创建。
- Params IDictionary?<string, [object]> （可选）#
  
  随 URL 发送的查询参数。
- ParamsString string? （可选）添加于：v1.47#
  
  随 URL 发送的查询参数。
- Timeout [float]? （可选）#
  
  请求超时时间（毫秒）。默认为 30000 (30 秒)。传递 0 表示禁用超时。

APIResponse #

PutAsync

添加于：v1.16

apiRequestContext.PutAsync

发送 HTTP(S) PUT 请求并返回其响应。该方法将从上下文中填充请求 Cookie 并从响应中更新上下文 Cookie。该方法将自动遵循重定向。

用法

await ApiRequestContext.PutAsync(url, options);

参数

url string #

目标 URL。
options ApiRequestContextPutOptions? （可选）
- Data|DataByte|DataObject string? | byte[]? | [object]? （可选）#
  
  允许设置请求的 POST 数据。如果数据参数是一个对象，它将被序列化为 JSON 字符串，并且如果未明确设置，content-type 头将设置为 application/json。否则，如果未明确设置，content-type 头将设置为 application/octet-stream。
- FailOnStatusCode bool? （可选）#
  
  是否在除 2xx 和 3xx 之外的响应码时抛出错误。默认情况下，所有状态码都会返回响应对象。
- Form FormData? （可选）#
  
  提供一个对象，该对象将使用 application/x-www-form-urlencoded 编码序列化为 HTML 表单并作为此请求正文发送。如果指定此参数，除非明确提供，否则 content-type 头将设置为 application/x-www-form-urlencoded。
  
  FormData 的实例可以通过 ApiRequestContext.CreateFormData 创建。
- Headers IDictionary?<string, string> （可选）#
  
  允许设置 HTTP 头。这些头将应用于获取的请求以及由其发起的任何重定向。
- IgnoreHTTPSErrors bool? （可选）#
  
  发送网络请求时是否忽略 HTTPS 错误。默认为 false。
- MaxRedirects int? （可选）新增于: v1.26#
  
  将自动遵循的最大请求重定向次数。如果超过此数字，将抛出错误。默认为 20。传递 0 表示不遵循重定向。
- MaxRetries int? （可选）新增于: v1.46#
  
  网络错误的最大重试次数。目前只重试 ECONNRESET 错误。不根据 HTTP 响应代码重试。如果超过限制，将抛出错误。默认为 0 - 不重试。
- Multipart FormData? （可选）#
  
  提供一个对象，该对象将使用 multipart/form-data 编码序列化为 HTML 表单并作为此请求正文发送。如果指定此参数，除非明确提供，否则 content-type 头将设置为 multipart/form-data。文件值可以作为包含文件名、MIME 类型及其内容的文件类对象传递。
  
  FormData 的实例可以通过 ApiRequestContext.CreateFormData 创建。
- Params IDictionary?<string, [object]> （可选）#
  
  随 URL 发送的查询参数。
- ParamsString string? （可选）添加于：v1.47#
  
  随 URL 发送的查询参数。
- Timeout [float]? （可选）#
  
  请求超时时间（毫秒）。默认为 30000 (30 秒)。传递 0 表示禁用超时。

APIResponse #

StorageStateAsync

添加于：v1.16

apiRequestContext.StorageStateAsync

返回此请求上下文的存储状态，包含当前 cookie 和如果传递给构造函数的本地存储快照。

用法

await ApiRequestContext.StorageStateAsync(options);

参数

options ApiRequestContextStorageStateOptions? （可选）
- IndexedDB bool? （可选）添加于: v1.51#
  
  设置为 true 以在存储状态快照中包含 IndexedDB。
- Path string? （可选）#
  
  要保存存储状态的文件路径。如果 Path 是相对路径，则它相对于当前工作目录解析。如果未提供路径，存储状态仍将返回，但不会保存到磁盘。

string #

方法​

CreateFormData​

DeleteAsync​

DisposeAsync​

FetchAsync​

GetAsync​

HeadAsync​

PatchAsync​

PostAsync​

PutAsync​

StorageStateAsync​

方法

CreateFormData

DeleteAsync

DisposeAsync

FetchAsync

GetAsync

HeadAsync

PatchAsync

PostAsync

PutAsync

StorageStateAsync