本页对应的英文页面已更新,但尚未翻译。 若要查看最新内容,请点击此处访问英文页面。

webread

从 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 请求选项。您可以将此语法与前面语法中的任何输入参数结合使用。

要将数据返回为特定输出类型,请指定 optionsContentType 属性。

要使用函数读取内容,请将 optionsContentReader 属性指定为该函数的句柄。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 将返回音频数据。有关受支持的音频格式,请参阅支持的导入和导出文件格式

示例

全部折叠

从 Hubble Heritage 网站读取木星图像并显示该图像。

url = 'http://heritage.stsci.edu/2007/14/images/p0714aa.jpg';
rgb = webread(url);
whos rgb
  Name         Size                 Bytes  Class    Attributes

  rgb       1000x800x3            2400000  uint8              

调整并显示图像。

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

木星图像来源:NASA、ESA 和 Hubble Heritage Team (STScI/AURA)。(有关使用条款,请参阅 Hubble Heritage Information Center。)

从世界银行气候数据 API 读取美国的温度数据。绘制 1901–2012 年的温度图。

从世界银行读取数据。此 API 返回 JSON 对象形式的数据。

api = 'http://climatedataapi.worldbank.org/climateweb/rest/v1/';
url = [api 'country/cru/tas/year/USA'];
S = webread(url)
S = 

112x1 struct array with fields:

    year
    data

webread 将 JSON 对象转换为结构体数组。每个结构体都包含年份和美国该年的平均温度(以摄氏度为单位)。

显示第一年的温度。

S(1)
ans = 

    year: 1901
    data: 6.6187

绘制平均温度图。将 S.yearS.data 串联成数组并绘制这些数组。

year = [S.year];
data = [S.data];
plot(year,data)
xlabel('Year');
ylabel('Temperature (Celsius)');
title('USA Average Temperatures')
axis tight

世界银行提供的 API 和数据:气候数据 API。(请参阅世界银行:气候数据 API 以了解有关 API 的更多信息;请参阅世界银行:使用条款。)

在 File Exchange 中搜索在过去七天中上传的包含单词 Simulink® 的文件。

指定查询参数。webread 将 Web 服务查询参数名称和值追加到 URL。File Exchange Web 服务定义 termduration 查询参数,而非 webread 函数。

url = 'https://www.mathworks.com/matlabcentral/fileexchange/';
data = webread(url,'term','simulink','duration',7);

webread 以字符数组形式返回搜索结果页的 HTML。

指定一个附加请求选项以通过世界银行气候数据 API 将数据读取到字符数组。

创建一个 weboptions 对象并将其 ContentType 设置为 'text'webread 函数将 JSON 对象转换为字符数组而不是结构体数组。显示字符数组的开头。

api = 'http://climatedataapi.worldbank.org/climateweb/rest/v1/';
url = [api 'country/cru/tas/year/USA'];
options = weboptions('ContentType','text');
data = webread(url,options);
data(1:62)
ans =

[{"year":1901,"data":6.6187487},{"year":1902,"data":6.4643273}

世界银行提供的 API 和数据:气候数据 API。(请参阅世界银行:气候数据 API 以了解有关 API 的更多信息;请参阅世界银行:使用条款。)

发送 HTTP POST 请求以在 File Exchange 中搜索在过去七天中上传的包含单词 Simulink 的文件。

url = 'https://www.mathworks.com/matlabcentral/fileexchange/';
options = weboptions('RequestMethod','post');
data = webread(url,'term','simulink','duration',7,options);

许多 Web 服务除了提供 GET 方法外还提供 POST 方法用于请求数据。

从 NASA Earth Observation (NEO) Web Mapping Service 读取 2004 年 12 月的一幅“Blue Marble:Next Generation”图像。

使用 datetime 对象指定所请求的图像的日期。指定 DFormat 属性,使其格式与 Web 服务请求的格式相匹配。

url = 'http://neowms.sci.gsfc.nasa.gov/wms/wms';
D = datetime(2004,12,01,'Format','yyyy-MM-dd');
rgb = webread(url,'Time',D, ...
     'Service','WMS','Layers','BlueMarbleNG-TB','CRS','CRS:84', ...
     'Format','image/jpeg','Height',256,'Width',512, ...
     'BBOX','-180.0,-90.0,180.0,90.0','Version','1.3.0','Request','GetMap');
imshow(rgb)

webread 转换 datetime 对象,以便它们可以作为 Web 服务查询参数的值。示例中的所有名称-值对组提供了由 NEO Web Mapping Service 指定的查询参数。

Blue Marble:Next Generation + Topography and Bathymetry 图像由 NASA 的 Earth Observatory 提供。NEO Web Mapping Service (WMS) 提供对图像和服务的访问权限。(请参阅 NASA Earth Observations 了解致谢名单和使用条款。有关 WMS 查询参数,请搜索 NASA Earth Observations 网站 WMS 1.3.0 Capabilities。)

输入参数

全部折叠

Web 服务的 URL,指定为字符数组。Web 服务实现 RESTful 接口。有关详细信息,请参阅 RESTful

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

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 的文件列表。

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

可指定 weboptions 对象的 ContentType 属性,并将该对象作为输入参数传递到 webread。然后,webread 会将 data 作为该类型的输出返回。该表列出了您可以在 weboptions 对象中指定的有效内容类型。

ContentType 设定符

输出类型

'auto'(默认值)

基于内容类型自动确定输出类型。

'text'

内容类型的字符向量:

text/plain
text/html
text/xml
application/xml
application/javascript
application/x-javascript
application/x-www-form-urlencoded

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

'image'

image/format 内容的数值或逻辑矩阵。如果第一个输出参数是索引图像,第二个输出参数是颜色图,第三个输出参数是 alpha 通道。

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

'audio'

audio/format 内容的数值矩阵(数值标量采样率作为第二个输出参数)。

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

'binary'

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

'table'

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

'json'

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

'xmldom'

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

'raw'

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

有关作为 weboptions 属性的所有请求选项,请参阅 weboptions

输出参数

全部折叠

从 Web 服务读取的内容,以标量、数组、结构体或表的形式返回。

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

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

音频数据的采样率(以赫兹为单位),以正数值标量的形式返回。

详细信息

全部折叠

RESTful

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

提示

  • 有关 RESTful Web 服务函数不支持的功能,请参阅 HTTP 接口

  • webread 支持 HTTP GET 和 POST 方法。许多 Web 服务同时提供 GET 和 POST 方法用于请求数据。要发送 HTTP POST 请求,请将 optionsRequestMethod 属性指定为 'post'。但是,webread 将查询选项放入 url,而不是放入请求消息的主体。要将查询放入消息主体,请使用 webwrite

  • 对于 HTTP POST 请求,webread 函数仅支持 application/x-www-form-urlencoded 媒体类型。要将 POST 请求与任何其他 Internet 媒体类型的内容一起发送,请使用 webwrite

  • 此函数不会检查文档内容来确定如何处理它。例如,HTML 和 XML 文档通常包含一个 <meta> 标记,指定文档的字符编码。如果该编码与默认的 webread 编码不同,请在 weboptions 中指定正确的 CharacterEncoding 选项。

在 R2014b 中推出