跳到主要内容

APIRequestContext

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

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

Cookie 管理

APIRequestContext 返回自 BrowserContext.APIRequest 和 Page.APIRequest 与相应的 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 请求时提供表单和 multipart 数据。

用法

ApiRequestContext.CreateFormData

返回

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 数据。如果 data 参数是一个对象，它将被序列化为 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 以禁用超时。

返回

DisposeAsync​

添加于: v1.16 apiRequestContext.DisposeAsync

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

用法

await ApiRequestContext.DisposeAsync(options);

参数

  • options ApiRequestContextDisposeOptions? (可选)

    • Reason string? (可选)添加于: v1.45#

      报告给因上下文释放而中断的操作的原因。

返回

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 });

在请求体中发送文件（一个或多个）的常用方法是使用 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 或 Request。

  • options ApiRequestContextFetchOptions? (可选)

    • Data|DataByte|DataObject string? | byte[]? | [object]? (可选)#

      允许设置请求的 post 数据。如果 data 参数是一个对象，它将被序列化为 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 以禁用超时。

返回

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 数据。如果 data 参数是一个对象，它将被序列化为 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 以禁用超时。

返回

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 数据。如果 data 参数是一个对象，它将被序列化为 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 以禁用超时。

返回

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 数据。如果 data 参数是一个对象，它将被序列化为 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 以禁用超时。

返回

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 数据。如果 data 参数是一个对象，它将被序列化为 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 以禁用超时。

返回

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 数据。如果 data 参数是一个对象，它将被序列化为 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 以禁用超时。

返回

StorageStateAsync​

添加于: v1.16 apiRequestContext.StorageStateAsync

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

用法

await ApiRequestContext.StorageStateAsync(options);

参数

  • options ApiRequestContextStorageStateOptions? (可选)

    • IndexedDB bool? (可选)添加于: v1.51#

      设置为 true 以在存储状态快照中包含 IndexedDB。

    • Path string? (可选)#

      要保存存储状态的文件路径。如果 Path 是相对路径，则相对于当前工作目录解析。如果未提供路径，仍将返回存储状态，但不会保存到磁盘。

返回