weboptions

指定 RESTful Web 服务的参数

全页折叠

语法

options = weboptions
options = weboptions(Name,Value)

说明

options = weboptions 返回一个默认 weboptions 对象，以指定 Web 服务请求的参数。weboptions 对象可以是 webread、websave 和 webwrite 函数的可选输入参量。有关 weboptions 函数不支持的选项，请参阅 使用 HTTP 从 MATLAB 调用 Web 服务。

示例

options = weboptions(Name,Value) 指定 weboptions 对象的一个或多个属性。要从代码中删除敏感信息，请参阅 loadenv。

示例

示例

默认的 weboptions 对象

创建一个默认的 weboptions 对象并显示其属性的默认值。

options = weboptions
options = 

  weboptions with properties:

      CharacterEncoding: 'auto'
              UserAgent: 'MATLAB 9.7.0.1112323 (R2019b)'
                Timeout: 5
               Username: ''
               Password: ''
                KeyName: ''
               KeyValue: ''
            ContentType: 'auto'
          ContentReader: []
              MediaType: 'auto'
          RequestMethod: 'auto'
            ArrayFormat: 'csv'
           HeaderFields: []
    CertificateFilename: 'default'

weboptions 对象中的用户名和密码

在 weboptions 对象中设置您的 Web 服务用户名和密码。当 Web 服务要求进行身份验证时，您可以将 weboptions 对象用作 webread、websave 或 webwrite 的输入参量。通过使用 secretID 对象保持敏感信息加密。

options = weboptions(Username=secretID("MathWorks.Username"), ...
                     Password=secretID("MathWorks.Password"))
options = 
  weboptions with properties:

      CharacterEncoding: 'auto'
              UserAgent: 'MATLAB 25.1.0.2966447 (R2025a) Update 1'
                Timeout: 5
               Username: MathWorks.Username (secretID)
               Password: MathWorks.Password (secretID)
                KeyName: ''
               KeyValue: ''
            ContentType: 'auto'
          ContentReader: []
              MediaType: 'auto'
          RequestMethod: 'auto'
            ArrayFormat: 'csv'
           HeaderFields: []
    CertificateFilename: 'default'

secretID 对象仅显示标识符名称。

options.Password
ans = 
  secretID with properties:

    Name: "MathWorks.Password"

名称-值参数

全部折叠

以 Name1=Value1,...,NameN=ValueN 的形式指定可选参量对组，其中 Name 是参量名称，Value 是对应的值。名称-值参量必须出现在其他参量之后，但对各个参量对组的顺序没有要求。

在 R2021a 之前，使用逗号分隔每个名称和值，并用引号将 Name 引起来。

示例: weboptions('Timeout',60) 创建一个 weboptions 对象以将超时连接持续时间设置为 60 秒。

webread 将 Web 内容转换为字符所用的编码，指定为字符串标量或字符向量。常用编码有 'US-ASCII'、'UTF-8'、'latin1'、'Shift_JIS' 和'ISO-8859-1'。默认编码取决于内容类型。如果出现乱码文本，则 webread 编码可能与文档使用的编码不同。可以尝试将 CharacterEncoding 设置为 UTF-8。

用户代理标识，指定为指示客户端用户代理的字符串标量或字符向量。

按秒计算的超时连接持续时间，指定为正数值标量。该值是发送请求的最后一个数据包后等待从服务器接收初始响应（标头）的秒数。Timeout 等效于 matlab.net.http.HTTPOptions 类中的 ResponseTimeout 属性。最大值为 2147.483647 秒。使用 Inf 设置最大值。

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

用户标识符，指定为字符串标量或字符向量，用于基本和/或摘要式 HTTP 身份验证（无加密）。有关基本 HTTP 身份验证方案的信息，请参阅 RFC Editor 网站上的 RFC 7617。有关 HTTP 摘要式访问身份验证的信息，请参阅 RFC 7616。

用户身份验证密码，指定为字符串标量或字符向量，用于基本和/或摘要式 HTTP 身份验证（无加密）。如果显示一个已设置 Password 的 weboptions 对象，则值会显示为一个包含 ‘*’ 的字符向量。但是，该对象将 Password 的值存储为纯文本。

键的名称，指定为字符串标量或字符向量。KeyName 是要添加到 HTTP 请求标头的附加名称。例如，KeyName 可以是 Web 服务 API 密钥名。

示例: weboptions('KeyName','duration','KeyValue',7) 会创建一个 weboptions 对象，其中包含由 Web 服务定义的键名 duration。

键的值，指定为要添加到 HTTP 请求标头的字符串标量、字符向量或者数值或逻辑值。KeyValue 是 KeyName 指定的键的值。

示例: weboptions('KeyName','duration','KeyValue',7) 创建一个 weboptions 对象，其中包含键值 7 和配对的键名 duration。

要添加到 HTTP 请求标头中的标头字段的名称和值，指定为 m×2 字符串数组或字符向量元胞数组。HeaderFields{i,1} 是字段名称，HeaderFields{i,2} 是字段值。

这些标头字段将加入到由 webread、webwrite 或 websave 自动添加的字段中，或替换这些自动添加的字段。通常是添加这些字段，但如果其中有任何字段的名称与自动添加的某个字段是不区分大小写的匹配项，并且该字段不支持多个值（例如 Content-Type），则使用您指定的值。有些字段的值是成功发送请求所必需的（如 Connection 和 Content-Length），这些字段不能覆盖。

示例: weboptions('HeaderFields',{'Content-Length' '78';'Content-Type' 'application/json'}) 创建包含两个标头字段的 weboptions 对象：值为 78 的 Content-Length 和值为 application/json 的 Content-Type。

示例: options.HeaderFields = {'Expect',''} 通过将标头字段 (Expect) 的值指定为空字符串来隐藏该字段。这在服务器无法正确处理请求中的标头字段的情况下可能是必需的。

内容类型，指定为字符串标量或字符向量。使用 ContentType 请求服务器优先返回特定格式的数据。webread 使用此值将响应转换为 MATLAB® 类型。服务器会尽可能返回此内容类型，但这不是必须满足的要求。

ContentType 值

输出类型

"auto"（默认值）

输出类型是根据 Web 服务指定的内容类型自动确定的。

"text"

内容类型的字符向量：

  • text/plain

  • text/html

  • text/xml

  • application/xml

  • application/javascript

  • application/x-javascript

  • application/x-www-form-urlencoded

如果 Web 服务返回一个具有 .m 扩展名的 MATLAB 文件，则该函数将以字符向量形式返回该文件的内容。

对于从服务器返回的文本内容，如果服务器或用户未指定字符编码，则函数默认使用 UTF-8。

"image"

image/format 内容的数值或逻辑矩阵。

有关受支持的图像格式，请参阅支持的导入和导出的文件格式。

"audio"

audio/format 内容的数值矩阵。

有关受支持的音频格式，请参阅支持的导入和导出的文件格式。

"binary"

二进制内容的 uint8 列向量，此处的二进制内容是指那些不能作为 char 类型进行处理的内容。

"table"

电子表格和 CSV (text/csv) 内容的标量表格对象。

或者，要从网站读取表数据，请调用 readtable 并将 filename 参量指定为 URL。有关示例，请参阅将 HTML 网页读取为表。

"json"

application/json 内容的 char、数值、逻辑值、结构体或元胞数组。

"xmldom"

text/xml 或 application/xml 内容的 Java® 文档对象模型 (DOM) 节点。如果 ContentType 未指定，则该函数将以字符向量形式返回 XML 内容。

"raw"

"text"、"xmldom" 和 "json" 内容的 char 列向量。该函数将以 uint8 列向量的形式返回所有其他内容类型。

示例: weboptions('ContentType','text') 创建一个 weboptions 对象，以指示 webread 返回字符向量形式的文本、JSON 或 XML 内容。

内容读取器，指定为函数句柄。可创建一个指定了 ContentReader 的 weboptions 对象，并将该对象作为输入参量传递到 webread。然后，webread 从 Web 服务下载数据并使用函数句柄指定的函数读取该数据。当指定 ContentReader 时，webread 将忽略 ContentType。

示例: weboptions('ContentReader',@readtable) 创建一个 weboptions 对象，以指示 webread 使用 readtable 读取表形式的内容。

媒体类型，指定为字符串标量、字符向量或 matlab.net.http.MediaType 对象。MediaType 指定 webwrite 发送到 Web 服务的数据的类型。它指定 MATLAB 为服务器指定的内容类型，还控制如何转换 webwrite data 参量（如果指定）。有关详细信息，请参阅 RFC Editor 网站上的 RFC 6838 Media Type Specifications and Registration Procedures。

默认值为 'auto'，表示由 MATLAB 根据 webwrite 的输入来选择类型。如果使用 PostName/PostValue 参量对组，则 MATLAB 使用 'application/x-www-form-urlencoded' 发送对组。如果使用的 data 参量是标量字符串或字符向量，则 MATLAB 会假定它是表单编码的字符串，并使用 'application/x-www-form-urlencoded' 按原样进行发送。如果 data 是其他类型，则 MATLAB 会使用 jsonencode 将其转换为 JSON，并使用内容类型 'application/json'。

如果指定包含 'json' 或 'javascript' 的 MediaType，并且 data 是字符向量，则会按原样发送。所有其他类型（包括标量字符串）都使用 jsonencode 进行转换。

如果您指定 'application/x-www-form-urlencoded'，将按照表单编码方式发送 PostName/PostValue 对组。data（如果存在）必须是字符串或字符向量才能按原样发送。

如果您指定包含 'xml' 的 MediaType，并且 data 是文档对象模型对象 (Java org.apache.xerces.dom.DocumentImpl)，则会将其转换为 XML。data（如果存在）必须是字符串或字符向量才能按原样发送。

如果指定任何其他 MediaType，并且 data 是字符串或字符向量，则 weboptions 按原样发送值。

只有值为 'auto' 和 'application/x-www-form-urlencoded' 的 MediaType 接受 PostName/PostValue 对组，而且不管 MediaType 为何值，字符向量始终按原样发送。

您可以在 MediaType 字符串内指定以分号分隔的 name=value 参数，例如 'application/json; odata=verbose'。某些服务器要求此格式作为请求中 Content-Type 标头字段的一部分。

示例: weboptions('MediaType','application/json') 创建一个 weboptions 对象，该对象指示 webwrite 将字符向量数据编码为 JSON 格式以将其发布到 Web 服务。

HTTP 请求方法，指定为字符串标量、字符向量，或作为下列值之一的 matlab.net.http.RequestMethod 枚举：

  • 'auto'

    • webread 和 websave 使用 HTTP GET 方法。

    • webwrite 使用 HTTP POST 方法。

  • 'get' 与 webread 和 websave 函数结合使用。

  • 'post' 与 webread、webwrite 和 websave 函数结合使用。

  • 'put' 与 webread、webwrite 和 websave 函数结合使用。

  • 'delete' 与 webread、webwrite 和 websave 函数结合使用。

  • 'patch' 与 webread、webwrite 和 websave 函数结合使用。

webread 和 websave 函数将查询放入 URL，而不考虑 RequestMethod。webwrite 函数将查询放入数据，而不考虑 RequestMethod。

示例: weboptions('RequestMethod','post') 创建一个 weboptions 对象，该对象指示 webread、websave 或 webwrite 使用 Web 服务的 HTTP POST 方法。

对表示多个值的查询或 post 值进行表单编码所采用的格式，指定为 'csv'、'json'、'repeating' 或 'php'。如果查询或 post 值是以下各项之一，则它包含多个值：

  • 数值、逻辑值或 datetime 向量

  • 包含多行的字符数组

  • 元胞向量，其中每个元素是一个数值、逻辑值、datetime 标量，或仅包含一行数据的字符向量

不支持任何其他数据类型或维度。

下表针对名为 'parameter' 且查询值为 [1 2 3] 的查询参数显示了每种格式的表单编码转换。Web 服务指定要使用的转换。

ArrayFormat 设定符

表单编码转换

'csv'（默认值）

parameter=1,2,3

'json'

parameter=[1,2,3]

'repeating'

parameter=1&parameter=2&parameter=3

'php'

parameter[]=1&parameter[]=2&parameter[]=3

要使用 'json' 或 'php' 设定符将标量编码为一元数组，请将该标量放在一元元胞数组中。

示例: weboptions('ArrayFormat','repeating') 会创建一个 weboptions 对象，该对象指示 webread、websave 或 webwrite 对使用多个值作为重复查询参数的任何查询或 post 值进行表单编码。

文件名，指定为字符串标量或字符向量，指示包含根证书的文件的名称和位置。该文件必须采用隐私增强邮件 (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

版本历史记录

在 R2014b 中推出

另请参阅

| | | |

主题