Main Content

matlab.net.http.HTTPOptions 类

命名空间: matlab.net.http

用来控制 HTTP 消息交换的选项

描述

使用 HTTPOptions 类为 HTTP 请求消息创建选项。可使用此对象指定在多个请求中保持不变的选项。

创建对象

描述

obj = matlab.net.http.HTTPOptions 创建具有默认属性值的 HTTP 选项。

示例

obj = matlab.net.http.HTTPOptions(Name,Value) 创建 HTTP 选项并由一个或多个名称-值对组参数指定其他属性。Name 是属性名称,Value 是对应的值。您可采用任意顺序指定多个名称-值对组参数,例如 Name1,Value1,...,NameN,ValueN。未指定的属性设置为默认值。

属性

全部展开

凭据是否用于进行身份验证,指定为 truefalse

如果 Authenticate 为 true,则实现服务器或代理请求的受支持的身份验证方法。身份验证基于 Credentials 属性以及 MATLAB® Web 预设项中设置的代理用户名和密码(如果有)。有关 MATLAB 身份验证支持的信息,请参阅Server Authentication

当满足以下任一条件时,响应消息中将包含服务器或代理身份验证质询。

  • Authenticate 为 false。

  • 未找到适合此请求的相应 Credentials 属性。

  • 身份验证失败。

属性:

GetAccess
public
SetAccess
public

数据类型: logical

文件名,指定为字符串标量或字符向量,指示包含根证书的文件的名称和位置。该文件必须采用隐私增强邮件 (PEM) 格式。位置必须在当前文件夹、MATLAB 路径上的文件夹中,或者是文件的完整路径或相对路径。此文件中包含的证书用于验证 HTTPS 连接的服务器证书。由于 HTTPS 连接的安全取决于此文件的完整性,请进行适当的保护。MATLAB 不管理证书或证书文件,但可使用第三方工具来管理 PEM 文件。

默认情况下,当未指定选项时,MATLAB 使用系统提供的证书存储来验证服务器证书。如果 CertificateFilename 设置为 'default',也会出现此行为。

如果 CertificateFilename 为空 (''),则服务器证书的验证关闭。MATLAB 仅验证服务器证书的域名与服务器的域名是否匹配。

如果您遇到使用 'default' 的服务器证书验证失败,则请使用您的系统浏览器检查连接。

如果遇到连接问题,请考虑以下事项:

  • 对于过期或吊销的服务器证书,请联系网站所有者或服务器管理员。

  • 如果缺失根 CA 证书,您可以选择下列方法之一:

    • 将根 CA 证书添加到由 CertificateFilename 表示的文件中。

    • 通过将 CertificateFilename 设置为空 ('') 来禁用证书验证。

  • 如果服务器证书的域名与服务器的域名不匹配,您可以通过创建 matlab.net.http.RequestMessage 对象并将 matlab.net.http.HTTPOptions.VerifyServerName 属性设置为 false 来禁用此验证。

注意

这些选项是临时解决方法,MathWorks 强烈建议您使用有效/正确的服务器证书来解决任何服务器证书验证失败的根本原因。

属性:

GetAccess
public
SetAccess
public

数据类型: char | string

等待初始服务器连接的秒数,指定为非负实数。如果涉及代理,超时应用于与代理的连接;否则,它应用于与服务器的连接。

默认值为 10 秒。如果超过超时期限,ConnectTimeout 将引发错误。要禁用超时,请将 ConnectTimeout 设置为 Inf

ConnectTimeout 决定在尝试与服务器或代理建立连接时等待多久之后引发错误。此超时并不限制接收完整响应需要的时间长短。

通过代理向服务器发送请求时,请考虑使用 ResponseTimeout 来限制等待时间。

某些操作系统具有系统强制执行的最大超时。即使 ConnectTimeout 的值大于最大值,此超时也会生效。例如,在 Windows® 10 上,此超时为 21 秒。

属性:

GetAccess
public
SetAccess
public

如何在 ResponseMessage 中处理从服务器接收的原始有效负载,指定为 truefalse

如果 ConvertResponse 为 true,则

  • 如果指定了 ContentConsumer,则会将 uint8 有效负载传递给 ContentConsumer 作进一步处理。

  • 否则,MATLAB 基于响应消息中的 Content-Type,将 MessageBody.Payload 属性中的有效负载转换为 MATLAB 数据。有关转换规则,请参阅 Data 属性。如果转换成功,则 Data 包含转换后的数据,而 Payload 为空。

如果 ConvertResponse 为 false,则忽略指定的 ContentConsumer,且行为取决于 Content-Type 是否指定字符数据。

  • 如果 Content-Type 具有一个显式或默认的字符集属性,则有效负载将转换为文本并存储在 Data 中,而不会进一步处理。

  • 如果 Content-Type 未指定字符数据或者不存在字符集,并且 MATLAB 不支持 Content-Type,则 Data 中包含原始 uint8 有效负载。

所有情况下都会删除 Payload 属性,除非您将 SavePayload 属性也设置为 true

如果消息已编码(压缩)并且出现以下情况之一,则忽略 ConvertResponse

  • 解码失败

  • DecodeResponse 属性为 false

属性:

GetAccess
public
SetAccess
public

数据类型: logical

网络上数据包之间等待的秒数,指定为非负实数。默认值为 Inf,表示没有超时。此超时在建立初始连接时会强制应用,有助于与速度可能较慢的服务器进行通信。如果在等待发送或接收下一个预期数据包时超过此超时,MATLAB 将关闭连接并引发错误。在这种情况下,请使用 matlab.net.http.HTTPException History 属性获取任何不完整数据。

属性:

GetAccess
public
SetAccess
public

是否解码压缩数据,指定为 truefalse。解码是指当服务器返回压缩(编码)的数据后,对响应的有效负载进行解压(解码)。解码基于 Content-Type 字段,在转换之前发生。

当存在指定压缩算法的 Content-Encoding 字段时,将对响应进行编码。MATLAB 支持的内容编码值有 gzipx-gzipdeflate。值 identity 表示没有编码,相当于消息没有 Content-Encoding 字段。如果 MATLAB 不支持 Content-Encoding 类型,即使 DecodeResponse 为 true,也不会发生解码。

如果 DecodeResponse 为 false 并且有效负载已编码,则:

  • MessageBody.Payload 属性包含未编码的原始有效负载。

  • MessageBody.Data 属性保留为空。

  • 无论 ConvertResponse 属性设置为何值,都不会发生转换。

如果您使用无法处理压缩数据的 ContentConsumer,则对于压缩响应,请不要将此值设置为 false,除非您同时将 ConvertResponse 设置为 false 以禁用该使用程序。MATLAB 提供的使用程序中只有 FileConsumerBinaryConsumer 能够处理压缩数据。

属性:

GetAccess
public
SetAccess
public

数据类型: logical

身份验证凭据,指定为一个或多个 matlab.net.http.Credentials 对象。默认值为默认的 matlab.net.http.Credentials 对象。使用默认的 Credentials 对象可允许在 Windows 上基于 Kerberos 和 NTLM 等方案进行身份验证。这些方案不需要指定用户名或密码。

仅当 Authenticate 属性为 true 时,才使用 Credentials。您必须指定至少一个 Credentials 对象才能进行身份验证。如果您将 Credentials 设置为空,则不会进行身份验证。

当您在同一个会话中多次访问同一台服务器时,要获得最好的性能,可为每个请求指定相同的 Credentials 向量或相同的 HTTPOptions 对象。Credentials 中包含缓存的信息,可加快后续身份验证。

如果您提供 Credentials 以用于代理,并且您希望用这些 Credentials 覆盖 Web 预设项窗口中指定的另一用户名和密码,则请在此 HTTPOptions 对象的 ProxyURI 属性中指定代理的主机和端口,或在预设项窗口中清除使用包含身份验证的代理选项。

属性:

GetAccess
public
SetAccess
public

在初始连接后保持服务器连接打开的秒数,指定为 0Inf。使用此属性以支持通过同一连接发送多个连续的消息。Inf 值(默认值)支持持久连接,即只要服务器可用就保持连接打开。值为 0 表示在每个消息后关闭连接。不支持其他值。

KeepAliveTimeout 属性对操作是否成功没有影响。MATLAB 总会保持连接打开足够长时间,以获得预期的服务器响应,除非超过其他超时。但是,采用 0 值会严重影响向同一服务器发送多条短消息的性能。

属性:

GetAccess
public
SetAccess
public

允许重定向给定请求的次数,指定为整数。默认重定向次数为 20。设置为 0 可禁用重定向。设置为 Inf 可允许无限重定向。

如果 MaxRedirects 不为零,则在每个重定向响应中从服务器收到的 Cookie 会复制到重定向的消息中。在 MaxRedirects 之后,响应消息将包含下一个重定向消息。

属性:

GetAccess
public
SetAccess
public

进度监视器处理程序,指定为 matlab.net.http.ProgressMonitor 对象的函数句柄。如果 UseProgressMonitor 为 true,MATLAB 将调用 ProgressMonitor 函数以报告传输的进度。如果 UseProgressMonitor 为 false 或 ProgressMonitorFcn 为空,则不报告进度。

属性:

GetAccess
public
SetAccess
public

数据类型: function_handle

代理服务器的地址,指定为 matlab.net.URI 对象或者 host:port//host:port 形式的字符串。

仅当 UseProxy 属性为 true 时,才会使用 ProxyURIProxyURI 将覆盖 MATLAB Web 预设项中指定的代理,以及在 Windows 系统设置中设置的任何代理。

属性:

GetAccess
public
SetAccess
public

发送请求的最后一个数据包后等待从服务器接收初始响应(标头)的秒数,指定为非负实数。默认值为 Inf,表示没有超时。如果超过此超时,则 MATLAB 将关闭连接并引发错误。

通过代理向服务器发送请求时,请使用 ResponseTimeout 限制等待时间,因为 ConnectTimeout 仅应用于代理连接时间。

ResponseTimeout 等效于 weboptions 设置的 Timeout 属性。

属性:

GetAccess
public
SetAccess
public

是否保存有效负载,指定为 truefalse。有效负载是指从服务器接收或发送给服务器的原始字节,保存在 MessageBody.Payload 属性中。

在请求消息中,将 SavePayload 设置为 true 可在转换数据之后保存有效负载。在响应消息中,会在转换之前一直保存这些字节。

SavePayload 可作为调试工具使用。例如,服务器无法处理某个请求的主体时,或者将响应主体转换为 MATLAB 类型发生故障时。将 SavePayload 设置为 true 可能会占用大量内存,因为有效负载至少等于转换的数据大小。

要检索响应有效负载而不进行转换,请将 ConvertResponse 属性设置为 false 并读取 MessageBody.Data

如果在处理消息的过程中发生 HTTPException,则在故障点之前接收到的有效负载位于 HTTPException.History(end).Response.Body.Payload 中。

如果 RequestMessage.BodyContentProvider 对象,则 MATLAB 将提供程序转换的数据保存在 Body.Payload 中。

属性:

GetAccess
public
SetAccess
public

数据类型: logical

是否显示进度,指定为 truefalse。如果将 UseProgressMonitor 设置为 true,将使用由 ProgressMonitorFcn 属性指定的函数报告传输进度。

属性:

GetAccess
public
SetAccess
public

数据类型: logical

是否使用代理,指定为 truefalse

如果 UseProxy 为 true,则 MATLAB 按以下优先顺序选择一个代理。

  • ProxyURI 属性中的值(如果有)。

  • MATLAB Web 预设项中指定的代理(如果有)。

  • 您系统首选项中指定的代理(仅限于 Windows)。

当满足以下任一条件时,所有请求将不通过代理而直接发送给目标 URI。

  • UseProxy 为 false。

  • UseProxy 为 true 但 ProxyURI 为空,且预设项中未设置代理。

UseProxy 为 true 时,MATLAB 会自动将消息转给代理。

属性:

GetAccess
public
SetAccess
public

数据类型: logical

服务器名称与证书是否匹配,指定为 truefalse

在使用 https 协议的安全连接中,MATLAB 会验证证书中的服务器名称与请求的 URI 或上次重定向请求的 URI 中的 Host 属性是否匹配。此验证可确保您是在与真正要访问的服务器进行通信。要在服务器证书与用来访问它的 URI 不匹配时禁用验证,可将此属性设置为 false。例如,您要访问使用某个 IP 地址或 “localhost” 的服务器,而且确信自己正在与要访问的服务器直接通信。

属性:

GetAccess
public
SetAccess
public

数据类型: logical

示例

全部折叠

将连接超时延长至 20 秒。

可以更改发送给服务器(在变量 url 中指定)的请求消息(在变量 request 中指定)的默认超时选项。

options = matlab.net.http.HTTPOptions('ConnectTimeout',20);
response = request.send(url,options);

版本历史记录

在 R2016b 中推出