PySide6.QtNetwork.QNetworkAccessManager

class QNetworkAccessManager

QNetworkAccessManager 类允许应用程序发送网络请求并接收回复。更多…

PySide6.QtNetwork.QNetworkAccessManager 的继承图

概要

方法

虚拟方法

插槽

信号

注意

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

详细描述

警告

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

网络访问API围绕一个QNetworkAccessManager对象构建，该对象保存了它发送请求的常见配置和设置。它包含代理和缓存配置，以及与这些问题相关的信号，以及可用于监视网络操作进度的回复信号。一个QNetworkAccessManager实例应该足以满足整个Qt应用程序的需求。由于QNetworkAccessManager基于QObject，它只能从其所属的线程中使用。

一旦创建了一个QNetworkAccessManager对象，应用程序就可以使用它通过网络发送请求。提供了一组标准函数，这些函数接收一个请求和可选的数据，并各自返回一个QNetworkReply对象。返回的对象用于获取响应相应请求返回的任何数据。

一个简单的网络下载可以通过以下方式完成：

manager = QNetworkAccessManager(self)
manager.finished.connect(
        self.replyFinished)
manager.get(QNetworkRequest(QUrl("http://qt-project.org")))

QNetworkAccessManager 有一个异步的API。当上面的 replyFinished 槽被调用时，它接收的参数是包含下载数据以及元数据（头部信息等）的 QNetworkReply 对象。

注意

请求完成后，用户有责任在适当的时间删除QNetworkReply对象。不要直接在连接到finished()的槽中删除它。您可以使用deleteLater()函数。

注意

QNetworkAccessManager 会将其接收到的请求排队。并行执行的请求数量取决于协议。目前，在桌面平台上，对于HTTP协议，每个主机/端口组合会并行执行6个请求。

一个更复杂的例子，假设经理已经存在，可以是：

request = QNetworkRequest()
request.setUrl(QUrl("http://qt-project.org"))
request.setRawHeader("User-Agent", "MyOwnBrowser 1.0")
reply = manager.get(request)
reply.readyRead.connect(self.slotReadyRead)
reply.errorOccurred.connect(
        self.slotError)
reply.sslErrors.connect(
        self.slotSslErrors)

另请参阅

QNetworkRequest QNetworkReply QNetworkProxy

class Operation

指示此回复正在处理的操作。

常量

描述

QNetworkAccessManager.HeadOperation

检索头部操作（使用head()创建）

QNetworkAccessManager.GetOperation

检索头部并下载内容（使用get()创建）

QNetworkAccessManager.PutOperation

上传内容操作（使用put()创建）

QNetworkAccessManager.PostOperation

通过HTTP POST发送HTML表单的内容进行处理（使用post()创建）

QNetworkAccessManager.DeleteOperation

删除内容操作（通过 deleteResource() 创建）

QNetworkAccessManager.CustomOperation

自定义操作（使用sendCustomRequest()创建）

另请参阅

operation()

__init__([parent=None])
Parameters:

父对象 – QObject

构建一个QNetworkAccessManager对象，该对象是网络访问API的核心，并将parent设置为父对象。

addStrictTransportSecurityHosts(knownHosts)
Parameters:

knownHosts – QHstsPolicy 的列表

将HTTP严格传输安全策略添加到HSTS缓存中。knownHosts包含具有QHstsPolicy信息的已知主机。

注意

过期的策略将从缓存中移除已知的主机，如果之前存在的话。

注意

在处理HTTP响应时，QNetworkAccessManager 还可以更新HSTS缓存，删除或更新现有策略或引入新的 knownHosts。因此，当前的实现是服务器驱动的，客户端代码可以向 QNetworkAccessManager 提供先前已知或发现的策略，但这些信息可以被“Strict-Transport-Security”响应头覆盖。

另请参阅

enableStrictTransportSecurityStore() QHstsPolicy

authenticationRequired(reply, authenticator)
Parameters:

每当最终服务器在交付请求内容之前请求认证时，都会发出此信号。连接到该信号的槽应填充内容（可以通过检查reply对象来确定）的凭据到authenticator对象中。

QNetworkAccessManager 将在内部缓存凭据，并在服务器再次需要身份验证时发送相同的值，而不会发出 authenticationRequired() 信号。如果服务器拒绝这些凭据，则会再次发出此信号。

注意

要使请求不发送凭据，您不得在authenticator对象上调用setUser()或setPassword()。这将导致finished()信号与带有错误AuthenticationRequiredError的QNetworkReply一起发出。

注意

无法使用QueuedConnection连接到此信号，因为如果信号返回时验证器未填充新信息，连接将失败。

另请参阅

proxyAuthenticationRequired() setUser() setPassword()

autoDeleteReplies()
Return type:

布尔

如果QNetworkAccessManager当前配置为自动删除QNetworkReplies，则返回true，否则返回false。

cache()
Return type:

QAbstractNetworkCache

返回用于存储从网络获取的数据的缓存。

另请参阅

setCache()

clearAccessCache()

刷新身份验证数据和网络连接的内部缓存。

此函数对于进行自动测试非常有用。

另请参阅

clearConnectionCache()

clearConnectionCache()

刷新网络连接的内部缓存。与clearAccessCache()不同，认证数据会被保留。

另请参阅

clearAccessCache()

connectToHost(hostName[, port=80])
Parameters:

  • hostName – str

  • port – int

启动与由hostName指定的主机的连接，端口为port。此函数有助于在发出HTTP请求之前完成与主机的TCP握手，从而降低网络延迟。

注意

此函数没有报告错误的可能性。

另请参阅

connectToHostEncrypted() get() post() put() deleteResource()

connectToHostEncrypted(hostName[, port=443[, sslConfiguration=QSslConfiguration.defaultConfiguration()]])
Parameters:

使用sslConfiguration在端口port上启动与hostName指定的主机的连接。此函数有助于在发出HTTPS请求之前完成与主机的TCP和SSL握手，从而降低网络延迟。

注意

预连接一个HTTP/2连接可以通过在sslConfiguration上调用setAllowedNextProtocols()来完成，其中包含QSslConfiguration::ALPNProtocolHTTP2在允许的协议列表中。当使用HTTP/2时，每个主机一个连接就足够了，即每个主机多次调用此方法不会使网络事务更快。

注意

此函数没有报告错误的可能性。

另请参阅

connectToHost() get() post() put() deleteResource()

connectToHostEncrypted(hostName, port, sslConfiguration, peerName)
Parameters:

  • hostName – str

  • port – int

  • sslConfiguration – QSslConfiguration

  • peerName – str

这是一个重载函数。

使用sslConfiguration和peerName设置为用于证书验证的主机名，在端口port上启动与hostName指定的主机的连接。此函数有助于在发出HTTPS请求之前完成与主机的TCP和SSL握手，从而降低网络延迟。

注意

可以通过在sslConfiguration上调用setAllowedNextProtocols()来预连接HTTP/2连接，其中包含QSslConfiguration::ALPNProtocolHTTP2在允许的协议列表中。当使用HTTP/2时，每个主机只需要一个连接，即每个主机多次调用此方法不会使网络事务更快。

注意

此函数没有报告错误的可能性。

另请参阅

connectToHost() get() post() put() deleteResource()

cookieJar()
Return type:

QNetworkCookieJar

返回用于存储从网络获取的cookie以及即将发送的cookie的QNetworkCookieJar。

另请参阅

setCookieJar()

createRequest(op, request[, outgoingData=None])
Parameters:
Return type:

QNetworkReply

返回一个新的QNetworkReply对象来处理操作op和请求originalReq。对于Get和Head请求，设备outgoingData始终为0，但在这些操作中传递给post()和put()的值（QByteArray变体将传递一个QBuffer对象）。

默认实现调用cookiesForUrl()在通过setCookieJar()设置的cookie jar上，以获取要发送到远程服务器的cookies。

返回的对象必须处于打开状态。

deleteResource(request)
Parameters:

请求 – QNetworkRequest

Return type:

QNetworkReply

发送请求以删除由request的URL标识的资源。

注意

此功能目前仅适用于HTTP，执行HTTP DELETE请求。

另请参阅

get() post() put() sendCustomRequest()

enableStrictTransportSecurityStore(enabled[, storeDir=""])
Parameters:

  • enabled – 布尔值

  • storeDir – str

如果 enabled 是 true，内部的 HSTS 缓存将使用持久存储来读取和写入 HSTS 策略。storeDir 定义了此存储的位置。默认位置由 QStandardPaths::CacheLocation 定义。如果没有可写的 QStandartPaths::CacheLocation 并且 storeDir 是空字符串，存储将位于程序的工作目录中。

注意

如果在启用持久存储时HSTS缓存已经包含HSTS策略，这些策略将被保留在存储中。如果缓存和存储都包含相同的已知主机，缓存中的策略被认为是最新的（因此将覆盖存储中的先前值）。如果不希望出现这种行为，请在启用严格传输安全之前启用HSTS存储。默认情况下，HSTS策略的持久存储是禁用的。

另请参阅

isStrictTransportSecurityStoreEnabled() setStrictTransportSecurityEnabled() standardLocations()

encrypted(reply)
Parameters:

回复 – QNetworkReply

当SSL/TLS会话成功完成初始握手时，会发出此信号。此时，尚未传输任何用户数据。该信号可用于对证书链执行额外的检查，例如在网站证书更改时通知用户。reply参数指定了哪个网络回复负责。如果回复不符合预期标准，则应通过连接到该信号的槽调用abort()来中止它。可以使用sslConfiguration()方法检查正在使用的SSL配置。

在内部，QNetworkAccessManager 可能会打开到服务器的多个连接，以便允许它并行处理请求。这些连接可能会被重用，这意味着不会发出 encrypted() 信号。这意味着你只能保证在 QNetworkAccessManager 的生命周期内，第一次连接到站点时接收到此信号。

另请参阅

encrypted() encrypted()

finished(reply)
Parameters:

回复 – QNetworkReply

每当一个待处理的网络回复完成时，就会发出此信号。reply参数将包含指向刚刚完成的回复的指针。此信号与finished()信号同时发出。

查看 finished() 以了解对象将处于的状态信息。

注意

不要删除连接到这个信号的槽中的reply对象。使用deleteLater()。

另请参阅

finished() error()

get(request)
Parameters:

请求 – QNetworkRequest

Return type:

QNetworkReply

发送请求以获取目标request的内容，并返回一个新的QNetworkReply对象，该对象已打开以供读取，每当有新数据到达时，会发出readyRead()信号。

内容以及相关的头部信息将被下载。

get(request, data)
Parameters:
Return type:

QNetworkReply

这是一个重载函数。

注意

带有消息体的GET请求不会被缓存。

注意

如果请求被重定向，只有在状态码为307或308时，消息体才会被保留。

get(request, data)
Parameters:
Return type:

QNetworkReply

这是一个重载函数。

注意

带有消息体的GET请求不会被缓存。

注意

如果请求被重定向，只有在状态码为307或308时，消息体才会被保留。

head(request)
Parameters:

请求 – QNetworkRequest

Return type:

QNetworkReply

发布一个请求以获取request的网络头信息，并返回一个新的QNetworkReply对象，该对象将包含这些头信息。

该函数以相关的HTTP请求（HEAD）命名。

isStrictTransportSecurityEnabled()
Return type:

布尔

如果启用了HTTP严格传输安全（HSTS），则返回true。默认情况下，HSTS是禁用的。

isStrictTransportSecurityStoreEnabled()
Return type:

布尔

如果HSTS缓存使用永久存储来加载和存储HSTS策略，则返回true。

post(request, multiPart)
Parameters:
Return type:

QNetworkReply

这是一个重载函数。

将multiPart消息的内容发送到由request指定的目的地。

这可以用于通过HTTP发送MIME多部分消息。

post(request, data)
Parameters:
Return type:

QNetworkReply

向由request指定的目标发送HTTP POST请求，并返回一个新的QNetworkReply对象，该对象已打开以供读取，并将包含服务器发送的回复。data设备的内容将被上传到服务器。

data 必须打开以供读取，并且必须保持有效，直到为此回复发出 finished() 信号。

注意

在HTTP和HTTPS以外的协议上发送POST请求是未定义的，并且很可能会失败。

另请参阅

get() put() deleteResource() sendCustomRequest()

post(request, data)
Parameters:
Return type:

QNetworkReply

这是一个重载函数。

将data字节数组的内容发送到由request指定的目的地。

preSharedKeyAuthenticationRequired(reply, authenticator)
Parameters:

如果SSL/TLS握手协商了一个PSK加密套件，因此需要PSK认证，则会发出此信号。reply对象是正在协商此类加密套件的QNetworkReply。

使用PSK时，客户端必须向服务器发送有效的身份和有效的预共享密钥，以便SSL握手继续进行。应用程序可以通过根据其需求填充传递的authenticator对象，在连接到该信号的槽中提供此信息。

注意

忽略此信号，或未能提供所需的凭据，将导致握手失败，从而导致连接中止。

注意

authenticator 对象由回复拥有，应用程序不得删除。

另请参阅

QSslPreSharedKeyAuthenticator

proxy()
Return type:

QNetworkProxy

返回使用此QNetworkAccessManager对象发送请求时将使用的QNetworkProxy。代理的默认值为DefaultProxy。

proxyAuthenticationRequired(proxy, authenticator)
Parameters:

每当代理请求身份验证且QNetworkAccessManager无法找到有效的缓存凭据时，会发出此信号。连接到该信号的槽应填充代理proxy在authenticator对象中的凭据。

QNetworkAccessManager 将在内部缓存凭据。下次代理请求认证时，QNetworkAccessManager 将自动发送相同的凭据，而不会再次发出 proxyAuthenticationRequired 信号。

如果代理拒绝了凭证，QNetworkAccessManager 将再次发出信号。

proxyFactory()
Return type:

QNetworkProxyFactory

返回此QNetworkAccessManager对象用于确定请求使用的代理的代理工厂。

请注意，此函数返回的指针由QNetworkAccessManager管理，可能随时被删除。

另请参阅

setProxyFactory() proxy()

put(request, multiPart)
Parameters:
Return type:

QNetworkReply

这是一个重载函数。

将multiPart消息的内容发送到由request指定的目的地。

这可以用于通过HTTP发送MIME多部分消息。

put(request, data)
Parameters:
Return type:

QNetworkReply

将data的内容上传到目标request，并返回一个新的QNetworkReply对象，该对象将开放以供回复。

data 在调用此函数时必须已打开以供读取，并且必须保持有效，直到为此回复发出 finished() 信号。

从返回的对象中是否可以读取内容取决于协议。对于HTTP，服务器可能会发送一个小的HTML页面，指示上传是否成功。其他协议可能会在其回复中包含内容。

注意

对于HTTP，此请求将发送一个PUT请求，大多数服务器不允许这样做。表单上传机制，包括通过HTML表单上传文件的机制，使用POST机制。

另请参阅

get() post() deleteResource() sendCustomRequest()

put(request, data)
Parameters:
Return type:

QNetworkReply

这是一个重载函数。

将data字节数组的内容发送到由request指定的目的地。

redirectPolicy()
Return type:

RedirectPolicy

返回创建新请求时使用的重定向策略。

sendCustomRequest(request, verb, multiPart)
Parameters:
Return type:

QNetworkReply

这是一个重载函数。

向由request的URL标识的服务器发送自定义请求。

将multiPart消息的内容发送到由request指定的目的地。

这可以用于发送自定义动词的MIME多部分消息。

sendCustomRequest(request, verb[, data=None])
Parameters:
Return type:

QNetworkReply

向由request的URL标识的服务器发送自定义请求。

用户有责任根据HTTP规范向服务器发送有效的verb。

此方法提供了发送除通过get()或post()等提供的常见动词之外的其他动词的手段，例如发送HTTP OPTIONS命令。

如果 data 不为空，data 设备的内容将被上传到服务器；在这种情况下，数据必须处于可读取状态，并且必须保持有效，直到为此回复发出 finished() 信号。

注意

此功能目前仅适用于HTTP(S)。

另请参阅

get() post() put() deleteResource()

sendCustomRequest(request, verb, data)
Parameters:
Return type:

QNetworkReply

这是一个重载函数。

将data字节数组的内容发送到由request指定的目的地。

setAutoDeleteReplies(autoDelete)
Parameters:

autoDelete – 布尔值

启用或禁用自动删除QNetworkReplies。

将shouldAutoDelete设置为true等同于在所有未来传递给此QNetworkAccessManager实例的QNetworkRequests上设置AutoDeleteReplyOnFinishAttribute属性为true，除非该属性已在QNetworkRequest上明确设置。

setCache(cache)
Parameters:

缓存 – QAbstractNetworkCache

将管理器的网络缓存设置为指定的cache。该缓存用于管理器分发的所有请求。

使用此函数将网络缓存对象设置为实现附加功能的类，例如将cookie保存到永久存储中。

注意

QNetworkAccessManager 拥有 cache 对象的所有权。

QNetworkAccessManager 默认情况下没有设置缓存。Qt 提供了一个简单的磁盘缓存，QNetworkDiskCache，可以使用它。

另请参阅

cache() CacheLoadControl

setCookieJar(cookieJar)
Parameters:

cookieJar – QNetworkCookieJar

将管理器的cookie jar设置为指定的cookieJar。该cookie jar由管理器分发的所有请求使用。

使用此函数将cookie jar对象设置为实现附加功能的类，例如将cookie保存到永久存储中。

注意

QNetworkAccessManager 拥有 cookieJar 对象的所有权。

如果 cookieJar 与此 QNetworkAccessManager 在同一线程中，它将设置 cookieJar 的父对象，以便在删除此对象时也删除 cookie jar。如果你想在不同的 QNetworkAccessManager 对象之间共享 cookie jar，你可能希望在调用此函数后将 cookie jar 的父对象设置为 0。

QNetworkAccessManager 默认情况下不实现任何自己的cookie策略：它接受服务器发送的所有cookie，只要它们格式正确并满足最低安全要求（cookie域与请求的域匹配，cookie路径与请求的路径匹配）。为了实现您自己的安全策略，请重写 cookiesForUrl() 和 setCookiesFromUrl() 虚函数。当 QNetworkAccessManager 检测到新cookie时，会调用这些函数。

setProxy(proxy)
Parameters:

代理 – QNetworkProxy

设置将来请求中使用的代理为proxy。这不会影响已经发送的请求。如果代理需要认证，将会发出proxyAuthenticationRequired()信号。

使用此函数设置的代理将用于由QNetworkAccessManager发出的所有请求。在某些情况下，可能需要根据发送的请求类型或目标主机选择不同的代理。如果是这种情况，您应该考虑使用setProxyFactory()。

setProxyFactory(factory)
Parameters:

factory – QNetworkProxyFactory

设置此类的代理工厂为factory。代理工厂用于确定用于给定请求的更具体的代理列表，而不是尝试对所有请求使用相同的代理值。

所有由QNetworkAccessManager发送的查询都将具有类型UrlRequest。

例如，代理工厂可以应用以下规则：

  • 如果目标地址在本地网络中（例如，如果主机名不包含点或者它是组织范围内的IP地址），则返回 NoProxy

  • 如果请求是FTP，返回一个FTP代理

  • 如果请求是HTTP或HTTPS，则返回一个HTTP代理

  • 否则，返回一个SOCKSv5代理服务器

对象 factory 的生命周期将由 QNetworkAccessManager 管理。它会在必要时删除该对象。

注意

如果使用setProxy()设置了特定的代理，则不会使用工厂。

另请参阅

proxyFactory() setProxy() QNetworkProxyQuery

setRedirectPolicy(policy)
Parameters:

策略 – RedirectPolicy

将管理器的重定向策略设置为指定的policy。此策略将影响管理器创建的所有后续请求。

使用此函数可以在管理级别启用或禁用HTTP重定向。

注意

创建请求时，QNetworkRequest::RedirectAttributePolicy 具有最高优先级，其次是管理器的策略。

默认值为 NoLessSafeRedirectPolicy。建议依赖手动重定向处理的客户端在其代码中显式设置此策略。

setStrictTransportSecurityEnabled(enabled)
Parameters:

enabled – 布尔值

如果 enabled 是 true，QNetworkAccessManager 遵循 HTTP 严格传输安全策略（HSTS，RFC6797）。在处理请求时，QNetworkAccessManager 会自动将“http”方案替换为“https”，并为 HSTS 主机使用安全传输。如果明确设置，端口 80 将被端口 443 替换。

当启用HSTS时，对于每个通过安全传输接收到的包含HSTS头的HTTP响应，QNetworkAccessManager将更新其HSTS缓存，要么记住具有有效策略的主机，要么移除具有过期或禁用HSTS策略的主机。

setTransferTimeout(timeout)
Parameters:

timeout – int

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

另请参阅

milliseconds) transferTimeout() transferTimeoutAsDuration()

sslErrors(reply, errors)
Parameters:

如果在设置过程中SSL/TLS会话遇到错误，包括证书验证错误，则会发出此信号。errors参数包含错误列表，reply是遇到这些错误的QNetworkReply。

为了表明错误不是致命的并且连接应该继续进行，应该从连接到该信号的槽中调用ignoreSslErrors()函数。如果不调用它，SSL会话将在交换任何数据（包括URL）之前被终止。

此信号可用于向用户显示错误消息，提示安全性可能受到威胁，并显示SSL设置（请参阅sslConfiguration()以获取）。如果用户在分析远程证书后决定继续，插槽应调用ignoreSslErrors()。

strictTransportSecurityHosts()
Return type:

QHstsPolicy的列表

返回HTTP严格传输安全策略的列表。如果HSTS缓存从“Strict-Transport-Security”响应头更新，此列表可能与最初通过addStrictTransportSecurityHosts()设置的列表不同。

supportedSchemes()
Return type:

字符串列表

列出访问管理器支持的所有URL方案。

重新实现此方法以在QNetworkAccessManager子类中提供您自己支持的方案。例如，当您的子类提供对新协议的支持时，这是必要的。

supportedSchemesImplementation()
Return type:

字符串列表

列出访问管理器支持的所有URL方案。

你不应该直接调用这个函数；请使用supportedSchemes()代替。

由于二进制兼容性约束，supportedSchemes() 方法（在 Qt 5.2 中引入）在 Qt 5 中不是虚函数，但现在它是。请重写 supportedSchemes 方法而不是这个方法。

另请参阅

supportedSchemes()

transferTimeout()
Return type:

整数

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

另请参阅

setTransferTimeout()