PySide6.QtNetwork.QNetworkRequest

class QNetworkRequest

QNetworkRequest 类保存了一个要通过 QNetworkAccessManager 发送的请求。更多…

概要

方法

注意

本文档可能包含从C++自动翻译到Python的代码片段。我们始终欢迎对代码片段翻译的贡献。如果您发现翻译问题，您也可以通过在我们的https:/bugreports.qt.io/projects/PYSIDE上创建工单来告知我们。

详细描述

QNetworkRequest 是网络访问API的一部分，是保存通过网络发送请求所需信息的类。它包含一个URL和一些可用于修改请求的辅助信息。

class KnownHeaders

已知的头部类型列表，QNetworkRequest 会解析这些类型。每个已知的头部也以其完整的HTTP名称的原始形式表示。

常量

描述

QNetworkRequest.ContentDispositionHeader

对应于HTTP Content-Disposition头，并包含一个包含处置类型（例如，附件）和参数（例如，文件名）的字符串。

QNetworkRequest.ContentTypeHeader

对应于HTTP Content-Type头，包含一个字符串，该字符串包含媒体（MIME）类型和任何辅助数据（例如，字符集）。

QNetworkRequest.ContentLengthHeader

对应于HTTP Content-Length头，并包含传输数据的字节长度。

QNetworkRequest.LocationHeader

对应于HTTP Location头部，包含一个表示数据实际位置的URL，包括重定向情况下的目标URL。

QNetworkRequest.LastModifiedHeader

对应于HTTP Last-Modified头，并包含一个表示内容最后修改日期的QDateTime。

QNetworkRequest.IfModifiedSinceHeader

对应于HTTP的If-Modified-Since头部，并包含一个QDateTime。它通常被添加到QNetworkRequest中。如果资源自该时间以来未更改，服务器应发送304（未修改）响应。

QNetworkRequest.ETagHeader

对应于HTTP ETag头，并包含一个表示内容最后修改状态的QString。

QNetworkRequest.IfMatchHeader

对应于HTTP If-Match头部，并包含一个QStringList。它通常被添加到QNetworkRequest中。如果资源不匹配，服务器应发送412（前提条件失败）响应。

QNetworkRequest.IfNoneMatchHeader

对应于HTTP If-None-Match头，并包含一个QStringList。它通常被添加到QNetworkRequest中。如果资源匹配，服务器应发送304（未修改）响应。

QNetworkRequest.CookieHeader

对应于HTTP Cookie头，并包含一个QList< QNetworkCookie >，表示要发送回服务器的cookies。

QNetworkRequest.SetCookieHeader

对应于HTTP Set-Cookie头，并包含一个QList< QNetworkCookie >，表示服务器发送的要本地存储的cookies。

QNetworkRequest.UserAgentHeader

HTTP客户端发送的用户代理头。

QNetworkRequest.ServerHeader

HTTP客户端接收到的服务器头信息。

另请参阅

header() setHeader() rawHeader() setRawHeader()

class Attribute

QNetworkRequest 和 QNetworkReply 的属性代码。

属性是额外的元数据，用于控制请求的行为，并将进一步的信息从回复传递回应用程序。属性也是可扩展的，允许自定义实现传递自定义值。

下表解释了默认属性代码是什么，与之关联的QVariant类型，如果缺少该属性时的默认值，以及它是否用于请求或回复。

常量

描述

QNetworkRequest.HttpStatusCodeAttribute

仅回复，类型：QMetaType::Int（无默认值）表示从HTTP服务器接收到的HTTP状态码（如200、304、404、401等）。如果连接不是基于HTTP的，则此属性将不存在。

QNetworkRequest.HttpReasonPhraseAttribute

仅适用于回复，类型：QMetaType::QByteArray（无默认值）表示从HTTP服务器接收到的HTTP原因短语（如“Ok”、“Found”、“Not Found”、“Access Denied”等）。这是状态码的人类可读表示（见上文）。如果连接不是基于HTTP的，此属性将不存在。注意：在使用HTTP/2时，不使用原因短语。

QNetworkRequest.RedirectionTargetAttribute

仅适用于回复，类型：QMetaType::QUrl（无默认值）如果存在，表示服务器正在将请求重定向到不同的URL。默认情况下，网络访问API会自动跟随重定向，除非使用了ManualRedirectPolicy。此外，如果使用了UserVerifiedRedirectPolicy，则如果未跟随重定向，将设置此属性。返回的URL可能是相对的。使用QUrl::resolved()将其转换为绝对URL。

QNetworkRequest.ConnectionEncryptedAttribute

仅回复，类型：QMetaType::Bool（默认值：false）表示数据是否通过加密（安全）连接获取。

QNetworkRequest.CacheLoadControlAttribute

仅请求，类型：QMetaType::Int（默认值：PreferNetwork）控制应如何访问缓存。可能的值是CacheLoadControl的值。请注意，默认的QNetworkAccessManager实现不支持缓存。但是，某些后端可能会使用此属性来修改其请求（例如，用于缓存代理）。

QNetworkRequest.CacheSaveControlAttribute

仅请求，类型：QMetaType::Bool（默认值：true）控制获取的数据是否应保存到缓存中以供将来使用。如果值为false，获取的数据将不会自动缓存。如果为true，数据可能会被缓存，前提是它是可缓存的（什么是可缓存的取决于所使用的协议）。

QNetworkRequest.SourceIsFromCacheAttribute

仅回复，类型：QMetaType::Bool（默认值：false）表示数据是否从缓存中获取。

QNetworkRequest.DoNotBufferUploadDataAttribute

仅请求，类型：QMetaType::Bool（默认值：false）指示是否允许QNetworkAccessManager代码缓冲上传数据，例如在执行HTTP POST时。当将此标志与顺序上传数据一起使用时，必须设置ContentLengthHeader头。

QNetworkRequest.HttpPipeliningAllowedAttribute

仅请求，类型：QMetaType::Bool（默认值：false）表示QNetworkAccessManager代码是否允许在此请求中使用HTTP管道。

QNetworkRequest.HttpPipeliningWasUsedAttribute

仅回复，类型：QMetaType::Bool 指示是否使用了HTTP管道化来接收此回复。

QNetworkRequest.CustomVerbAttribute

仅请求，类型：QMetaType::QByteArray 保存要发送的自定义HTTP动词的值（用于GET、POST、PUT和DELETE以外的其他动词）。此动词在调用sendCustomRequest()时设置。

QNetworkRequest.CookieLoadControlAttribute

仅请求，类型：QMetaType::Int（默认：Automatic）指示是否在请求中发送‘Cookie’头。当创建跨域XMLHttpRequest时，如果创建请求的Javascript没有明确将withCredentials设置为true，Qt WebKit会将该属性设置为false。更多信息请参见这里。（此值在4.7中引入。）

QNetworkRequest.CookieSaveControlAttribute

仅请求，类型：QMetaType::Int（默认：Automatic）指示是否保存从服务器接收到的“Cookie”头以响应请求。当创建跨域XMLHttpRequest时，如果创建请求的Javascript未明确将withCredentials设置为true，Qt WebKit将此属性设置为false。有关更多信息，请参见此处。（此值在4.7中引入。）

QNetworkRequest.AuthenticationReuseAttribute

仅请求，类型：QMetaType::Int（默认：Automatic）指示是否在请求中使用缓存的授权凭据（如果可用）。如果设置为Manual并且认证机制为‘Basic’或‘Digest’，Qt将不会发送带有任何缓存的凭据的‘Authorization’ HTTP头，即使它可能有请求URL的凭据。当Qt WebKit创建一个跨域XMLHttpRequest时，如果创建请求的Javascript没有明确将withCredentials设置为true，则此属性设置为Manual。有关更多信息，请参见这里。（此值在4.7中引入。）

QNetworkRequest.BackgroundRequestAttribute

类型: QMetaType::Bool (默认: false) 表示这是一个后台传输，而不是用户发起的传输。根据平台的不同，后台传输可能会受到不同的策略限制。

QNetworkRequest.Http2AllowedAttribute

仅请求，类型：QMetaType::Bool（默认值：true）指示QNetworkAccessManager代码是否允许在此请求中使用HTTP/2。这适用于SSL请求或如果设置了Http2CleartextAllowedAttribute的‘明文’HTTP/2。

QNetworkRequest.Http2WasUsedAttribute

仅回复，类型：QMetaType::Bool（默认值：false）指示是否使用HTTP/2接收此回复。（此值在5.9中引入。）

QNetworkRequest.EmitAllUploadProgressSignalsAttribute

仅请求，类型：QMetaType::Bool（默认值：false）指示是否应发出所有上传信号。默认情况下，uploadProgress信号仅在100毫秒间隔内发出。（此值在5.5中引入。）

QNetworkRequest.OriginalContentLengthAttribute

仅适用于回复，类型为 QMetaType::Int。当数据被压缩且请求被标记为自动解压缩时，保存原始内容长度属性在被无效化并从头部移除之前的值。（此值在5.9版本中引入。）

QNetworkRequest.RedirectPolicyAttribute

仅请求，类型：QMetaType::Int，应为RedirectPolicy值之一（默认：NoLessSafeRedirectPolicy）。（此值在5.9中引入。）

QNetworkRequest.Http2DirectAttribute

仅请求，类型：QMetaType::Bool（默认值：false）如果设置，此属性将强制QNetworkAccessManager使用HTTP/2协议，而无需初始的HTTP/2协议协商。使用此属性意味着事先知道特定服务器支持HTTP/2。如果设置了Http2CleartextAllowedAttribute，该属性可以与SSL或“明文”HTTP/2一起使用。如果指定了HTTP/2直接连接，但服务器不支持HTTP/2，QNetworkAccessManager将放弃，而不会尝试回退到HTTP/1.1。如果同时设置了Http2AllowedAttribute和Http2DirectAttribute，Http2DirectAttribute优先。（此值在5.11中引入。）

QNetworkRequest.AutoDeleteReplyOnFinishAttribute

仅请求，类型：QMetaType::Bool（默认值：false）如果设置，此属性将使QNetworkAccessManager在发出“finished”信号后删除QNetworkReply。（此值在5.14中引入。）

QNetworkRequest.ConnectionCacheExpiryTimeoutSecondsAttribute

仅适用于请求，类型：QMetaType::Int 用于设置在最后一个待处理请求处理完毕后，与服务器的TCP连接（HTTP1和HTTP2）应在何时关闭。（此值在6.3版本中引入。）

QNetworkRequest.Http2CleartextAllowedAttribute

仅请求，类型：QMetaType::Bool（默认值：false）如果设置，此属性将告诉QNetworkAccessManager尝试升级到明文HTTP/2（也称为h2c）。在Qt 7之前，可以通过设置QT_NETWORK_H2C_ALLOWED环境变量将此属性的默认值覆盖为true。如果未设置Http2AllowedAttribute，则忽略此属性。（此值在6.3中引入。）

QNetworkRequest.UseCredentialsAttribute

仅请求，类型：QMetaType::Bool（默认值：false）指示是否应使用凭据进行底层的XMLHttpRequest跨站点Access-Control请求。对同源请求没有影响。这仅影响WebAssembly平台。（此值在6.5中引入。）

QNetworkRequest.FullLocalServerNameAttribute

仅请求，类型：QMetaType::String 保存用于底层 QLocalSocket 的完整本地服务器名称。当 QLocalSocket 对于简单名称的行为不够时，QNetworkAccessManager 使用此属性连接到特定的本地服务器。QNetworkRequest 中的 URL 仍必须使用 unix+http: 或 local+http: 方案。URL 中的主机名将用于 HTTP 请求中的 Host 头。（此值在 6.8 中引入。）

QNetworkRequest.User

特殊类型。可以通过QVariants传递从User到UserMax类型的附加信息。网络访问的默认实现将忽略此范围内的任何请求属性，并且不会在回复中生成此范围内的任何属性。此范围保留用于QNetworkAccessManager的扩展。

QNetworkRequest.UserMax

特殊类型。请参阅用户。
class CacheLoadControl

控制QNetworkAccessManager的缓存机制。

常量

描述

QNetworkRequest.AlwaysNetwork

始终从网络加载，不检查缓存是否有有效条目（类似于浏览器中的“重新加载”功能）；此外，强制中间缓存重新验证。

QNetworkRequest.PreferNetwork

默认值；如果缓存条目比网络条目旧，则从网络加载。这将永远不会从缓存中返回过时数据，但会重新验证已过时的资源。

QNetworkRequest.PreferCache

如果缓存可用，则从缓存加载，否则从网络加载。请注意，这可能会从缓存中返回可能过时（但未过期）的项目。

QNetworkRequest.AlwaysCache

仅从缓存加载，如果项目未缓存则指示错误（即离线模式）
class LoadControl

指示请求的加载机制的某个方面是否已被手动覆盖，例如通过Qt WebKit。

常量

描述

QNetworkRequest.Automatic

默认值：表示默认行为。

QNetworkRequest.Manual

表示行为已被手动覆盖。
class Priority

此枚举列出了可能的网络请求优先级。

常量

描述

QNetworkRequest.HighPriority

高优先级

QNetworkRequest.NormalPriority

普通优先级

QNetworkRequest.LowPriority

低优先级
class RedirectPolicy

指示网络访问API是否应自动遵循HTTP重定向响应。

常量

描述

QNetworkRequest.ManualRedirectPolicy

不跟随任何重定向。

QNetworkRequest.NoLessSafeRedirectPolicy

默认值：仅允许“http”->”http”、“http” -> “https”或“https” -> “https”重定向。

QNetworkRequest.SameOriginRedirectPolicy

要求相同的协议、主机和端口。注意，http://example.com 和 http://example.com:80 在此策略下会失败（隐式/显式端口被视为不匹配）。

QNetworkRequest.UserVerifiedRedirectPolicy

客户端通过处理redirected()信号来决定是否跟随每个重定向，在QNetworkReply对象上发出redirectAllowed()以允许重定向或中止/完成它以拒绝重定向。例如，这可以用于询问用户是否接受重定向，或根据某些应用程序特定的配置来决定。

注意

当Qt处理重定向时，出于遗留和兼容性原因，当服务器返回301或302响应时，它将使用GET方法发出重定向请求，无论原始方法是什么，除非原始方法是HEAD。

class TransferTimeoutConstant

一个常量，可用于启用具有预设值的传输超时。

常量

描述

QNetworkRequest.DefaultTransferTimeoutConstant

传输超时时间，单位为毫秒。如果在调用setTimeout()时没有传递参数，则使用此值。

另请参阅

QNetworkRequest::DefaultTransferTimeout

__init__()

构造一个没有请求URL的QNetworkRequest对象。使用setUrl()来设置一个URL。

另请参阅

url() setUrl()

__init__(other)
Parameters:

其他 – QNetworkRequest

创建 other 的副本。

__init__(url)
Parameters:

url – QUrl

构造一个QNetworkRequest对象，其中url作为要请求的URL。

另请参阅

url() setUrl()

attribute(code[, defaultValue=None])
Parameters:

  • code – 属性

  • defaultValue – 对象

Return type:

对象

返回与代码code关联的属性。如果属性未设置，则返回defaultValue。

注意

此函数不应用Attribute中列出的默认值。

另请参阅

setAttribute() Attribute

decompressedSafetyCheckThreshold()
Return type:

整数

返回用于检查存档炸弹的阈值。

如果回复的解压缩大小小于此值，Qt 将直接解压缩它，而无需进一步检查。

hasRawHeader(headerName)
Parameters:

headerName – str

Return type:

布尔

如果原始头 headerName 存在于这个网络请求中，则返回 true。

注意

在Qt 6.7之前的版本中，此函数仅接受QByteArray。

另请参阅

rawHeader() setRawHeader()

header(header)
Parameters:

头部 – KnownHeaders

Return type:

对象

如果此请求中存在已知的网络头header，则返回其值。如果不存在，则返回QVariant()（即无效的变体）。

headers()
Return type:

QHttpHeaders

返回在此网络请求中设置的标头。

另请参阅

setHeaders()

http1Configuration()
Return type:

QHttp1Configuration

返回QNetworkAccessManager当前用于此请求的底层HTTP/1连接的参数。

另请参阅

setHttp1Configuration

http2Configuration()
Return type:

QHttp2Configuration

返回QNetworkAccessManager当前用于此请求及其底层HTTP/2连接的参数。这可能是应用程序先前设置的配置或默认配置。

QNetworkAccessManager 使用的默认值为：

  • 连接级流量控制的窗口大小为2147483647个八位字节

  • 流级别流量控制的窗口大小为214748364八位字节

  • 最大帧大小为16384

默认情况下，服务器推送是禁用的，霍夫曼压缩和字符串索引是启用的。

另请参阅

setHttp2Configuration

maximumRedirectsAllowed()
Return type:

整数

返回此请求允许跟随的最大重定向次数。

__ne__(other)
Parameters:

其他 – QNetworkRequest

Return type:

布尔

如果此对象与 other 不相同，则返回 false。

另请参阅

operator==()

__eq__(other)
Parameters:

其他 – QNetworkRequest

Return type:

布尔

如果此对象与other相同（即，如果它们具有相同的URL、相同的头部和相同的元数据设置），则返回true。

另请参阅

operator!=()

originatingObject()
Return type:

QObject

返回发起此网络请求的对象的引用；如果未设置或对象已被销毁，则返回None。

另请参阅

setOriginatingObject()

peerVerifyName()
Return type:

字符串

返回为证书验证设置的主机名，由setPeerVerifyName设置。默认情况下，返回一个空字符串。

另请参阅

setPeerVerifyName

priority()
Return type:

优先级

返回此请求的优先级。

另请参阅

setPriority()

rawHeader(headerName)
Parameters:

headerName – str

Return type:

QByteArray

返回头部 headerName 的原始形式。如果不存在这样的头部，则返回一个空的 QByteArray，这可能与存在但没有内容的头部无法区分（使用 hasRawHeader() 来查找头部是否存在）。

原始头信息可以通过setRawHeader()或setHeader()来设置。

注意

在Qt 6.7之前的版本中，此函数仅接受QByteArray。

另请参阅

header() setRawHeader()

rawHeaderList()
Return type:

.list of QByteArray

返回在此网络请求中设置的所有原始标头的列表。列表按标头设置的顺序排列。

setAttribute(code, value)
Parameters:

  • code – 属性

  • value – 对象

将属性与代码 code 关联的值设置为 value。如果属性已经设置，则丢弃之前的值。特别地，如果 value 是无效的 QVariant，则取消设置该属性。

另请参阅

attribute() Attribute

setDecompressedSafetyCheckThreshold(threshold)
Parameters:

threshold – int

设置用于存档炸弹检查的threshold。

一些支持的压缩算法可以在一个极小的压缩文件中编码一个极其庞大的解压缩文件。这只有在解压缩内容极其单调的情况下才可能实现，而对于以善意传输的真实文件来说，这种情况很少见：利用如此高压缩比的文件通常是缓冲区溢出攻击的有效载荷，或者是拒绝服务（通过占用过多内存）攻击。因此，解压缩后文件大小特别大，尤其是从极小的压缩形式解压缩出来的文件，最好作为可疑的恶意软件予以拒绝。

如果回复的解压缩大小超过此阈值（默认情况下为10 MiB，即10 * 1024 * 1024），Qt将检查压缩比：如果压缩比不合理（GZip和Deflate为40:1，Brotli和ZStandard为100:1），则回复将被视为错误。将阈值设置为-1将禁用此检查。

setHeader(header, value)
Parameters:

将已知头header的值设置为value，覆盖任何先前设置的头。此操作还会设置等效的原始HTTP头。

setHeaders(newHeaders)
Parameters:

newHeaders – QHttpHeaders

这是一个重载函数。

setHttp1Configuration(configuration)
Parameters:

配置 – QHttp1Configuration

从configuration设置请求的HTTP/1参数。

setHttp2Configuration(configuration)
Parameters:

配置 – QHttp2Configuration

从configuration设置请求的HTTP/2参数。

注意

必须在发出请求之前设置配置。

注意

HTTP/2 在单个 HTTP/2 连接中复用多个流。这意味着 QNetworkAccessManager 将使用发送到同一主机的系列请求中第一个请求的配置。

另请参阅

http2Configuration QNetworkAccessManager QHttp2Configuration

setMaximumRedirectsAllowed(maximumRedirectsAllowed)
Parameters:

maximumRedirectsAllowed – int

设置此请求允许的最大重定向次数为maxRedirectsAllowed。

setOriginatingObject(object)
Parameters:

对象 – QObject

允许设置对发起请求的object的引用。

例如，Qt WebKit 将发起请求的 QWebFrame 设置为原始对象。

另请参阅

originatingObject()

setPeerVerifyName(peerName)
Parameters:

peerName – str

将peerName设置为证书验证的主机名，而不是用于TCP连接的主机名。

另请参阅

peerVerifyName

setPriority(priority)
Parameters:

优先级 – Priority

将此请求的优先级设置为priority。

注意

priority 只是网络访问管理器的提示。它可以使用它，也可以不使用。目前它用于HTTP，以决定哪个请求应该首先发送到服务器。

另请参阅

priority()

setRawHeader(headerName, value)
Parameters:

警告

本节包含从C++自动翻译到Python的代码片段，可能包含错误。

将标头 headerName 设置为值 headerValue。如果 headerName 对应于已知标头（参见 KnownHeaders），原始格式将被解析，并且相应的“已处理”标头也将被设置。

例如：

request.setRawHeader(QByteArray("Last-Modified"), QByteArray("Sun, 06 Nov 1994 08:49:37 GMT"))

还会将已知的头部 LastModifiedHeader 设置为解析日期的 QDateTime 对象。

注意

设置相同的头部两次会覆盖之前的设置。为了实现同名HTTP头部的多重行为，你应该将两个值连接起来，用逗号（“,”）分隔，并设置一个单一的原始头部。

另请参阅

KnownHeaders setHeader() hasRawHeader() rawHeader()

setSslConfiguration(configuration)
Parameters:

配置 – QSslConfiguration

将此网络请求的SSL配置设置为config。适用的设置包括私钥、本地证书、TLS协议（例如TLS 1.3）、CA证书以及SSL后端允许使用的加密套件。

setTransferTimeout(timeout)
Parameters:

timeout – int

将timeout设置为传输超时时间，单位为毫秒。

另请参阅

milliseconds) transferTimeout() transferTimeoutAsDuration()

setUrl(url)
Parameters:

url – QUrl

设置此网络请求所引用的URL为url。

另请参阅

url()

sslConfiguration()
Return type:

QSslConfiguration

返回此网络请求的SSL配置。默认情况下，这与defaultConfiguration()相同。

swap(other)
Parameters:

其他 – QNetworkRequest

将此网络请求与 other 交换。此函数非常快且永远不会失败。

transferTimeout()
Return type:

整数

返回用于传输的超时时间，单位为毫秒。

如果 transferTimeoutAsDuration() .count() 无法用 int 表示，此函数将返回 INT_MAX/INT_MIN 代替。

另请参阅

setTransferTimeout() transferTimeoutAsDuration()

url()
Return type:

QUrl

返回此网络请求所引用的URL。

另请参阅

setUrl()