webread

R2026a

从 RESTful Web 服务读取内容

全页折叠

语法

data = webread(url)

data = webread(url,QueryName1,QueryValue1,...,QueryNameN,QueryValueN)

data = webread(___,options)

[data,colormap,alpha] = webread(___)

[data,Fs] = webread(___)

描述

data = webread(url) 从 url 指定的 Web 服务读取内容并在 data 中返回内容。

Web 服务提供了一个 RESTful 接口，可以返回具有 Internet 媒体类型格式（例如 JSON、XML、图像或文本）的数据。

示例

data = webread(url,QueryName1,QueryValue1,...,QueryNameN,QueryValueN) 将查询参数追加到 url，由一对或多对参数名称和值指定。要将查询放入消息主体，请使用 webwrite。Web 服务定义查询参数。

示例

data = webread(___,options) 添加由 weboptions 对象 options 指定的其他 HTTP 请求选项。除了上述语法中的任何输入参量组合之外，您还可以指定此参量。

要将数据返回为特定输出类型，请指定 options 的 ContentType 属性。

要使用函数读取内容，请将 options 的 ContentReader 属性指定为该函数的句柄。webread 从 Web 服务下载数据并使用指定的函数读取这些数据：

如果指定了一个返回多个输出参量的函数句柄，则 webread 将返回所有输出参量。
如果指定了一个不返回任何输出参量的函数句柄（例如视频文件的 Image Processing Toolbox™ 函数 @implay），则 webread 将不返回任何输出参量。

示例

[data,colormap,alpha] = webread(___) 从 url 指定的 Web 服务中读取图像，并在 data 中返回该图像。您可以使用上述语法仅返回图像。使用此语法可返回与该图像关联的颜色图和 alpha 通道。

如果 HTTP 响应具有用于指定图像媒体类型的 Content-Type 标头字段且 imread 支持该图像格式，则 webread 将返回一个图像。有关受支持的图像格式，请参阅支持的导入和导出的文件格式。

[data,Fs] = webread(___) 从 url 指定的 Web 服务中读取音频数据，并在 data 中返回这些数据。您可以使用上述语法仅返回音频数据。使用此语法可返回音频数据的采样率（以赫兹为单位）。

如果 HTTP 响应具有用于指定音频媒体类型的 Content-Type 标头字段且 audioread 支持该音频格式，则 webread 将返回音频数据。有关受支持的音频格式，请参阅支持的导入和导出的文件格式。

示例

全部折叠

从网站读取图像

打开实时脚本

从网站读取图像数据。

httpsUrl = "https://requestserver.mathworks.com";
imageUrl = strcat(httpsUrl, "/assets/computerVision.jpg");
rgb = webread(imageUrl);
whos rgb

  Name        Size                Bytes  Class    Attributes

  rgb       360x640x3            691200  uint8

调整大小并显示图像。

rgb = imresize(rgb, 0.6);
imshow(rgb)

Figure contains an axes object. The axes object contains an object of type image.

读取天气数据

打开实时脚本

从 CSV 数据文件中读取温度。

httpsUrl = "https://requestserver.mathworks.com";
dataUrl = strcat(httpsUrl,"/assets/weatherStation.csv");
data = webread(dataUrl);
time = [data.Time];
temp = [data.TempF];

绘制温度数据图。

plot(time,temp)
xlabel("Time")
ylabel("Temperature (Fahrenheit)")
title("Temperature Over Time");
axis padded

Figure contains an axes object. The axes object with title Temperature Over Time, xlabel Time, ylabel Temperature (Fahrenheit) contains an object of type line.

指定 Web 服务查询参数

打开实时脚本

您可以使用查询参数选择数据库记录。

首先，通过显示字段来查看一个雇员数据库的结构体。

httpsUrl = "https://requestserver.mathworks.com";
employeeUrl = strcat(httpsUrl,"/employee");
fieldnames(webread(employeeUrl))

ans = 6×1 cell array
    "'id'"
    "'firstName'"
    "'lastName'"
    "'occupation'"
    "'age'"
    "'city'"

然后，使用 firstName 和 lastName 查询参数选择一个雇员的记录。

jSmith = webread(employeeUrl,"firstName","John","lastName","Smith")

jSmith = struct with fields:
            id: 1
     firstName: 'John'
      lastName: 'Smith'
    occupation: 'Software Engineer'
           age: '32'
          city: 'Boston'

指定请求选项

打开实时脚本

您可以以特定类型形式返回数据。

创建一个 weboptions 对象并将其 ContentType 设置为 "text"。使用指定的选项，webread 函数将 JSON 数据转换为字符数组。

httpUrl = "http://requestserver.mathworks.com";
employeeUrl = strcat(httpUrl,"/employee");
options = weboptions("ContentType","text");
sBrown = webread(employeeUrl,"firstName","Sarah",options)

sBrown = 
'[{"id":2,"firstName":"Sarah","lastName":"Brown","occupation":"Software Engineer","age":"28","city":"New York"}]'

输入参数

全部折叠

`url` — Web 服务的 URL
字符向量 | 字符串标量

Web 服务的 URL，指定为字符向量或字符串标量。包括传输协议。仅支持 http 和 https。Web 服务实现 RESTful 接口。有关详细信息，请参阅 RESTful。

示例: webread("https://www.mathworks.com/matlabcentral") 读取网页并以字符数组中返回其 HTML。

`QueryName1,QueryValue1,...,QueryNameN,QueryValueN` — Web 服务查询参数
参数名称和值的对组

Web 服务查询参数，指定为参数名称和值的一个或多个对组。QueryName 参量必须为指定查询参数名称的字符向量或字符串标量。QueryValue 参量必须是字符向量、字符串标量或者用于指定查询参数值的数值、逻辑值或 datetime 值。数值、逻辑值和 datetime 值可以置于数组中。Web 服务定义它接受参数作为请求的一部分。

当您将 QueryValue 指定为 datetime 值时，必须指定其 Format 属性，以便它与 Web 服务要求的格式一致。如果 Format 属性包含时区或偏移量，而 datetime 值未设置时区，则 webread 会将 "Local" 指定为时区。

当 QueryValue 在一个数组中包含多个值时，可能需要指定 weboptions 对象的 ArrayFormat 属性，以根据 Web 服务需要的方式对该数组进行表单编码。

示例: webread("https://www.mathworks.com/matlabcentral/fileexchange/","term","webread") 检索上传至 File Exchange 且包含函数 webread 的文件列表。File Exchange Web 服务会定义 term 参数。

`options` — 其他 HTTP 请求选项
`weboptions` 对象

其他 HTTP 请求选项，指定为 weboptions 对象。

如果指定 weboptions 对象的 ContentType 属性，并将该对象作为输入参量传递给 webread，则 webread 返回 data 作为该类型的输出。该表列出了您可以在 weboptions 对象中指定的有效内容类型。

`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，了解作为 weboptions 属性列出的所有请求选项。

输出参量

全部折叠

`data` — Web 服务中的内容
标量 | 数组 | 结构体 | 表 | 元胞数组

来自 Web 服务的内容，以标量、数组、结构体、表或元胞数组的形式返回。

`colormap` — 与索引图像关联的颜色图
数值数组

与索引图像关联的颜色图，以数值数组的形式返回。

`alpha` — 与索引图像关联的 Alpha 通道
数值数组

与索引图像关联的 Alpha 通道，以数值数组的形式返回。

`Fs` — 音频数据的采样率（以赫兹为单位）
正数值标量

音频数据的采样率（以赫兹为单位），以正数值标量的形式返回。

详细信息

全部折叠

RESTful

REST 表示表述性状态转移 (representational state transfer)，即 Web 服务的一种常用架构样式。RESTful 接口提供标准的 HTTP 方法，例如 GET、PUT、POST 或 DELETE。

提示

有关 RESTful Web 服务函数不支持的功能，请参阅使用 HTTP 从 MATLAB 调用 Web 服务。
Web 服务 API 仅支持 HTTP 1.1。
webread 支持 HTTP GET 和 POST 方法。许多 Web 服务同时提供 GET 和 POST 方法用于请求数据。要发送 HTTP POST 请求，请将 options 的 RequestMethod 属性指定为 "post"。但是，webread 将查询选项放入 url，而不是放入请求消息的主体。要将查询放入消息主体，请使用 webwrite。
对于 HTTP POST 请求，webread 函数仅支持 application/x-www-form-urlencoded 媒体类型。要将 POST 请求与任何其他 Internet 媒体类型的内容一起发送，请使用 webwrite。
此函数不会检查 Web 文档内容来确定如何处理它。例如，HTML 和 XML 文档通常包含一个 <meta> 标记，指定文档的字符编码。如果该编码与默认的 webread 编码不同，请在 weboptions 中指定预期的 CharacterEncoding 选项。
有关如何指定代理服务器设置的信息，请参阅代理服务器身份验证。

扩展功能

全部展开

基于线程的环境
使用 MATLAB® `backgroundPool` 在后台运行代码或使用 Parallel Computing Toolbox™ `ThreadPool` 加快代码运行速度。

webread 函数完全支持基于线程的环境。有关详细信息，请参阅在基于线程的环境中运行 MATLAB 函数。

版本历史记录

在 R2014b 中推出

全部展开

R2024a: Ctrl+C 键停止执行 MATLAB 命令

在执行此函数时按下 Ctrl+C 键会停止执行 MATLAB 命令。此行为与其他 MATLAB 功能处理 Ctrl+C 的方式一致，如使用键盘快捷方式导航 MATLAB 中所述。

以前，该函数会引发自定义异常，用户可以在 try/catch 代码块中捕获该异常。如果您的代码包含 try/catch 代码块，您可以通过删除它们来更新代码。

下表显示在 R2024a 之前和从 R2024a 开始按下 Ctrl+C 键时不同结果的示例。

更新前	更新后
try d = webread(myURL) % User presses Ctrl+C catch ME rethrow(ME); end K>> ME ME = HTTPException with properties: ...	d = webread(myURL) % User presses Ctrl+C Operation terminated by user during matlab.internal.webservices.urlencode>validateURL

更新前

更新后

try 
    d = webread(myURL) % User presses Ctrl+C
catch ME 
    rethrow(ME);
end

K>> ME 

ME = 
  HTTPException with properties: 
...

d = webread(myURL)
% User presses Ctrl+C

Operation terminated by user during
matlab.internal.webservices.urlencode>validateURL

另请参阅

函数

websave | weboptions | webwrite | datetime | jsondecode | audioread | imread | readtable | xmlread

webread

语法

描述

示例

从网站读取图像

读取天气数据

指定 Web 服务查询参数

指定请求选项

输入参数

`url` — Web 服务的 URL
字符向量 | 字符串标量

`QueryName1,QueryValue1,...,QueryNameN,QueryValueN` — Web 服务查询参数
参数名称和值的对组

`options` — 其他 HTTP 请求选项
`weboptions` 对象

输出参量

`data` — Web 服务中的内容
标量 | 数组 | 结构体 | 表 | 元胞数组

`colormap` — 与索引图像关联的颜色图
数值数组

`alpha` — 与索引图像关联的 Alpha 通道
数值数组

`Fs` — 音频数据的采样率（以赫兹为单位）
正数值标量

详细信息

RESTful

提示

扩展功能

基于线程的环境
使用 MATLAB® `backgroundPool` 在后台运行代码或使用 Parallel Computing Toolbox™ `ThreadPool` 加快代码运行速度。

版本历史记录

R2024a: Ctrl+C 键停止执行 MATLAB 命令

另请参阅

函数

主题

外部网站

webread

语法

描述

示例

从网站读取图像

读取天气数据

指定 Web 服务查询参数

指定请求选项

输入参数

url — Web 服务的 URL 字符向量 | 字符串标量

QueryName1,QueryValue1,...,QueryNameN,QueryValueN — Web 服务查询参数 参数名称和值的对组

options — 其他 HTTP 请求选项 weboptions 对象

输出参量

data — Web 服务中的内容 标量 | 数组 | 结构体 | 表 | 元胞数组

colormap — 与索引图像关联的颜色图 数值数组

alpha — 与索引图像关联的 Alpha 通道 数值数组

Fs — 音频数据的采样率（以赫兹为单位） 正数值标量

详细信息

RESTful

提示

扩展功能

基于线程的环境 使用 MATLAB® backgroundPool 在后台运行代码或使用 Parallel Computing Toolbox™ ThreadPool 加快代码运行速度。

版本历史记录

R2024a: Ctrl+C 键停止执行 MATLAB 命令

另请参阅

函数

主题

外部网站

`url` — Web 服务的 URL
字符向量 | 字符串标量

`QueryName1,QueryValue1,...,QueryNameN,QueryValueN` — Web 服务查询参数
参数名称和值的对组

`options` — 其他 HTTP 请求选项
`weboptions` 对象

`data` — Web 服务中的内容
标量 | 数组 | 结构体 | 表 | 元胞数组

`colormap` — 与索引图像关联的颜色图
数值数组

`alpha` — 与索引图像关联的 Alpha 通道
数值数组

`Fs` — 音频数据的采样率（以赫兹为单位）
正数值标量

基于线程的环境
使用 MATLAB® `backgroundPool` 在后台运行代码或使用 Parallel Computing Toolbox™ `ThreadPool` 加快代码运行速度。