send

类: matlab.net.http.RequestMessage
命名空间: matlab.net.http

发送 HTTP 请求消息并接收响应

全页展开

语法

[response,completedrequest,history] = send(request,uri)
[response,completedrequest,history] = send(request,uri,options,consumer)

说明

[response,completedrequest,history] = send(request,uri) 向 uri 指定的 Web 服务发送 request 消息，并返回 response（如果有）。如果未指定 request.Method 属性，则 send 方法会将该属性设置为 'GET'。

默认情况下，send 会验证消息的标头及其他部分在语义上是否正确并完成 uri。此方法还为格式正确的请求填写任何必需的标头字段。如果 request.Body 是尚未设置 Payload 属性的 MessageBody，则 send 会调用适当的转换函数，将任何 request.Body.Data 转换为表示要发送的 HTTP 有效负载的字节向量，就像 MessageBody.Data 的说明中那样。通常，'GET' 请求不包含数据，但无论 RequestMethod 是什么，此方法都会发送 Body。如果服务器在其响应中返回数据并且未指定 consumer，则 send 会将该数据转换为 MATLAB® 数据并保存在 response.Body.Data 中。有关数据转换的详细信息，请参阅 MessageBody.Data。

如果 request.Body 是 ContentProvider，MATLAB 将调用该提供程序以获取要发送的数据。

如果标头中已经包含此方法通常会添加的某个字段，send 将验证该字段是否具有期望的值。您可以按如下所示覆盖默认行为。

  • 要按原样发送消息，而不检查或更改标头，请在发送之前将 request.Completed 属性设置为 true。如果您使用 complete 方法来完成请求，则为 uri 和 options 指定的值应该与您提供给 complete 的值相同，否则可能会产生不可预测的结果。即使设置了 Completed，RequestLine 中未指定的字段也会填入默认值。

  • 要允许 send 方法检查和更改标头，但禁止添加可能会由 send 或 ContentProvider 添加的特定标头字段，请将该字段添加到 request.Header 中并为其指定空值 ([])。例如，send 会自动添加 User-Agent 标头字段。如果您不希望出现这种行为，请将 HeaderField('User-Agent') 添加到标头中。具有空值的标头字段不会包含在消息中。Host 和 Connection 字段无法禁止。

  • 要覆盖 send 方法为给定标头字段添加的值，请在发送或完成消息之前添加您自己的该字段实例。但是，这不会覆盖 ContentProvider 可能添加的标头字段。然而，对于某些标头字段类型，如果值无效，send 仍可能会拒绝该消息。要阻止对给定字段的值进行任何检查，或者要覆盖 ContentProvider 添加的字段，请将 matlab.http.field.GenericField 类型的字段添加到标头中并指定所需的名称和值。send 和 ContentProvider 都不会添加与任何 GenericField 标头同名的标头字段，也不会检查它们的正确性。

  • 要发送未经转换的原始二进制数据，您可以将 uint8 向量插入到 Body.Data 或 Body.Payload 中。唯一的区别在于 Body.Data 中的数据会根据消息中的 Content-Type 字段进行转换，而 Body.Payload 不会。如果 Body.Payload 为空，即使已设置 Completed，send 也始终会尝试转换非空 Body.Data。有关转换规则，请参阅 MessageBody.Data。

示例

[response,completedrequest,history] = send(request,uri,options,consumer) 为处理 request 和 response 消息提供了更多选项。

示例

输入参数

全部展开

请求消息，指定为 matlab.net.http.RequestMessage 对象。

消息目标，指定为 matlab.net.URI 对象或者可被构造函数接受的字符串或字符向量。如果值为 URI 对象，则它必须指定主机。如果是字符串且不包含任何方案，则假定为 'http'。例如，'www.somewebsite.com' 和 '//www.somewebsite.com' 都被视为 'http://www.somewebsite.com'。

用于处理请求消息和响应消息的其他选项，指定为 matlab.net.http.HTTPOptions 对象。如果未指定或者值为空，则 send 使用默认选项。

处理返回的有效负载的内容使用程序，指定为 matlab.net.http.io.ContentConsumer 对象或指定为返回 ContentConsumer 的函数的句柄。

send 方法在数据被收到时调用 ContentConsumer，以实时处理或存储数据缓冲区。consumer 可将数据存储在 response.Body.Data 中或以其他方式处理。例如，使用程序可将数据显示在图窗窗口或保存到文件中。如果指定使用程序，MATLAB 不会自动设置 MessageBody.Data，但如果 options.SavePayload 为 true，则它会将 MessageBody.Payload 设置为未转换的有效负载。例如，FileConsumer 将数据保存到文件中，而不是保存在 MessageBody.Data 中。

与默认的 MATLAB 响应数据转换相比，使用 ContentConsumer 为转换或存储响应数据提供了更大的灵活性。有关对收到的数据进行的默认转换的说明，请参阅 MessageBody.Data。要查看 MATLAB 提供的 ContentConsumer 类型列表，请键入：

mp = ?matlab.net.http.io.ContentConsumer;
{mp.ContainingPackage.ClassList.Name}'

此外，软件开发人员可以创建自己的 ContentConsumer 子类，以便在收到数据的同时对数据进行处理。

consumer 仅在接受消息时才使用，是否接受消息取决于多种因素，例如 response 中的 Content-Type 标头以及 response.StatusCode 是否为 OK。对于是否接受消息，每个 consumer 都有其自己的标准。

如果有效负载是使用支持的编码方式压缩的，并且未指定 options 或者 options.DecodePayload 为 true，则使用程序将获取解压缩的数据。如果有效负载被压缩并且 options.DecodePayload 为 false，或者有效负载是使用不受支持的编码方式压缩的，则不使用该使用程序，而且不会对数据进行默认处理。

在未使用使用程序的所有情况下，将按照未指定 consumer 那样处理和转换有效负载。

如果 consumer 是函数句柄，则仅当 MATLAB 确定响应具有有效负载后才会调用该函数，对使用程序进行实例化。

指定 consumer 但不指定 options 时，请为 options 添加占位符 [] 以使用默认选项。

输出参量

全部展开

从服务器接收到的消息，以 matlab.net.http.ResponseMessage 对象形式返回。如果涉及到重定向和/或身份验证，则 MATLAB 与代理或服务器之间可能会发生请求和响应的中间交换。

接收 response 参量之前所发送的请求，以 matlab.net.http.RequestMessage 对象形式返回。send 方法会为 completedrequest 参量补充身份验证或重定向信息。

如果 request.Body 是 ContentProvider，则 completedrequest.Body 通常为空，因为 ContentProvider 有效负载未保存。但是，如果 options.SavePayload 为 true，则 completedrequest.Body 是 Payload 中包含数据（以 uint8 向量形式从提供程序发送）的 MessageBody。在某些情况下，当请求的 Content-Type 指示它基于字符时，MessageBody.Data 属性中将包含以字符串形式表示的有效负载。

发送 HTTP 请求后，检查 completedrequest 参量可了解发送的内容。服务器可能发送多条消息，例如，如果发生了重定向或身份验证交换。如果有多条消息，则 completedrequest 会包含最后一个请求。要查看第一条消息或中间的消息，请检查 history 参量。

要多次发送同一个请求，请调用 RequestMessage.complete 方法：

[completedrequest,target] = complete(request,uri)

然后使用以下输出参量调用 send 方法：

resp = send(completedrequest,target)

消息日志，返回为了满足此 send 请求而交换的 matlab.net.http.LogRecord 对象的向量。如果您只有一个请求和响应，history 参量将只包含一条记录。当出现包含多个消息的身份验证时，历史记录中可以包含针对每次重定向的多条日志记录。

使用历史记录可获取响应消息中的所有 Set-Cookie 标头。您可以在后续请求中将这些标头发送回服务器。

历史记录中的最后一个记录包含与 completedrequest 和 response 参量相同的属性，但 Body 属性除外。要记录消息主体，请在 options 参量中指定 SavePayload 属性。

历史记录对进行调试也很有用。

示例

全部展开

打开脚本

发送 HTTP 消息以读取 MathWorks 联系技术支持网页，并显示消息状态代码。

import matlab.net.*
import matlab.net.http.*
r = RequestMessage;
uri = URI('https://www.mathworks.com/support/contact_us');
resp = send(r,uri);
status = resp.StatusCode

status = 

    OK
打开脚本

通过将 HTTP 选项 MaxRedirects 设置为零，防止消息从 mathworks.com 网站重定向。然后显示状态代码信息。

import matlab.net.*
import matlab.net.http.*
r = RequestMessage;
uri = URI('https://www.mathworks.com/support/contact_us');
options = HTTPOptions('MaxRedirects',0);
[resp,~,hist] = send(r,uri,options);
status = getReasonPhrase(resp.StatusCode)

status =

    'Moved Permanently'

错误的处理方式

始终检查 response Status 属性以确定请求是否被接受。出错情况包括：

  • MException - 消息格式不正确，无法完成。

  • HTTPException - 消息已完成，但 Web 服务不可访问或者未在 options 指定的超时期限内做出响应。

  • response 的 Status 属性 - Web 服务做出响应并返回 HTTP 错误状态。send 正常返回，将 Status 属性设置为从服务器返回的错误。

版本历史记录

在 R2016b 中推出

另请参阅

| | | | | | |