Main Content

matlab.net.URI 类

命名空间: matlab.net

统一资源标识符 (URI)

描述

matlab.net.URI 类可构造 Internet 统一资源标识符 (URI),如 Web 地址或 URL。Internet URI 是一个字符串,可分为几个组成部分。每一部分由 URI 类的一个属性来表示。以下文本显示了属性及其关联的标点符号,为清楚起见,各部分之间用空格分隔。空格不会出现在编码的 URI 中。关联的标点符号不是属性值的一部分。

Scheme: //Authority /Path(1) /Path(2) ... /Path(end) ?Query #Fragment

其中 Authority 包含以下属性:

UserInfo@ Host :Port

可使用 matlab.net.URI stringchar 方法创建 Internet URI。这些方法通过向非空属性中添加标点符号并对保留的字符进行转义,从而对属性进行编码。

所有属性都是可选的。但是,不同的用法可能要求必须设置某些属性。

要从输出字符串中消除某个属性及其标点符号,请将该属性值设置为 []

创建对象

描述

obj = matlab.net.URI 创建一个空 URI。

示例

obj = matlab.net.URI(destination) 创建由 destination 指定的 URI。

示例

obj = matlab.net.URI(destination,queryVector)Query 属性设置为 queryVectorQuery 值追加到已在 destination 中指定的任何查询参数的末尾。

obj = matlab.net.URI(destination,queryName,queryValue)Query 属性添加一个或多个 queryName,queryValue 参数。

obj = matlab.net.URI(destination,queryVector,queryName,queryValue)Query 属性中添加 queryVectorqueryName,queryValue 参数。

obj = matlab.net.URI(___,format) 指定当数组出现在 queryValue 参数中时的输出格式。您可以使用上述语法中的任何输入参数。

obj = matlab.net.URI(___,'literal') 指示 destination 已编码。复制并粘贴已编码的 URI(例如从浏览器的地址栏中)时,可以使用此选项。当您直接读取此 URI 的属性时,您会看到解码的版本。'literal' 选项不允许您构造非法 URI。它可以防止对 '%' 字符进行重新编码。必须始终进行编码的字符(例如 HostPath 中的 '\'' ')仍然采用百分号编码形式。

此选项不会影响 Query (matlab.net.QueryParameter) 参数。

输入参数

全部展开

目标,指定为用来指定整个 URI 或其一部分的字符串或字符向量,或者指定为 matlab.net.URI 对象。如果 destinationmatlab.net.URI 对象,则 destination 必须是唯一的参数。

示例: https://user:pwd@www.mathworks.com:8000/product/matlab?abc=def&this=that#xyz 所有属性

示例: Host 和 Scheme 属性:https://www.mathworks.com

示例: 仅 Host://www.mathworks.com

示例: Host 和 Path://www.mathworks.com/products/matlab/

示例: 仅 Path:products/matlab/live-editor

示例: Host 和 Query://www.mathworks.com/search/site_search.html?q=weboptions

查询属性,指定为 matlab.net.QueryParameter 对象的向量。查询的形式为:

name1=value1&name2=value2&name3=value3

示例: matlab.net.QueryParameter('hl','en','ie','utf8','num',50)

查询名称,指定为字符串或字符向量。Web 服务定义它接受的 queryName,queryValue 对组作为请求的一部分。不要编码 queryName 中的字符。

查询值,指定为字符数组、数值、逻辑值或者 datetime 值或数组。不要编码 queryValue 中的字符。

输出格式,当数组出现在 queryValue 参数中时,指定为 matlab.net.ArrayFormat 对象。要查看允许的值,请参阅 ArrayFormat

format 参数不影响 queryVector 参数值的格式。

属性

全部展开

URI 方案,有时称为协议,出现在 :// 字符之前,指定为字符串或字符向量。Scheme 始终返回字符串。如果不为空,则 Scheme 必须为 httphttps。但是,此约定并不是强制的。MATLAB® 不支持其他方案,如 file

示例: http

示例: https

用户信息,指定为字符串或字符向量。UserInfo 出现在 Host 属性之前,后跟一个 @ 字符。string 方法将对特殊字符进行百分号 (%) 编码。设置 UserInfo 时,不要对值进行编码。

示例: name

示例: name:password

主机名,指定为字符串或字符向量。值采用域名系统 (DNS) 格式,或者类似于 Internet 协议版本 4 (IPv4) 或版本 6 (IPv6) 地址。string 方法将对 URI 的主机部分中不允许使用的字符进行百分号 (%) 编码。句点字符 (.) 保持不变。设置 Host 时,不要对值进行编码。

示例: www.mathworks.com

示例: 2222:7344:0db8:0000:0100:8a2e:0370:85a3 IPv6 地址

端口号,指定为 0-65535 范围内的一个数字,或者代表该范围内数字的字符串或字符向量,以 uint16 形式存储。

示例: 8000

路径段,指定为字符串、字符串向量、字符向量或字符向量元胞数组。结果始终为字符串向量。要查看已编码路径的值,请使用 EncodedPath 属性。

URI 中的路径由 EncodedPath 属性指定。EncodedPath 是由 / 字符分隔的一系列路径段,每个段是 Path 的一个成员。

Path(1)/Path(2)/Path(3)/.../Path(end)

/ 字符不会出现在 Path 中,但包含在 EncodedPath 中。例如,

uri = matlab.net.URI;
uri.Path = {'products' 'matlab'};
P = uri.Path
P = 
    "products"    "matlab"
EP = uri.EncodedPath
EP = products/matlab

如果您将 Path 设置为字符向量或包含 / 字符的标量字符串,则其值会在 / 字符处被拆分为多个路径段。结果与指定字符串向量或字符向量元胞数组相同。

uri.Path = 'products/matlab';
P = uri.Path
P = 
    "products"    "matlab"

Path 段的数量始终比 EncodedPath 中的 / 字符数多一个。任何路径段都可以是空字符串。如果 Path(1) 为空字符串,则 EncodedPath/ 开头。如果 Path(end) 为空字符串,则 EncodedPath/ 结尾。

uri.Path = '/products/matlab/';
EP = uri.EncodedPath
EP = /products/matlab/

Path 设置为非标量字符串或元胞数组时,URI 的路径部分中不允许使用的字符在 EncodedPath 中将采用百分号 (%) 编码。要包括 # 字符,

uri.Path = {'foo#bar'};EP = uri.EncodedPath
EP = foo%23bar

不要对 # 字符进行编码。否则,已编码的字符将被再次编码。

uri.Path = {'foo%23Fbar'};
EP = uri.EncodedPath
EP = foo%2523Fbar

Path 可以是相对路径或绝对路径。绝对路径是具有多个路径段且第一个路径段为空的路径。它被编码为以 / 字符开头的字符串,后跟第二个字符串。绝对路径的定义对应于 Internet Engineering Task Force (IETF®) 网站上的 RFC 3986 Uniform Resource Identifier (URI):Generic Syntax, section 3.3 Path 中定义的 path-absolute。相对路径是第一个字符串不为空的路径。它的编码不带前导 /。例如,创建一个绝对路径:

uri1 = matlab.net.URI;
uri1.Path = {'' 'products' 'matlab'};
EP = uri1.EncodedPath
EP = /products/matlab

创建一个相对路径:

uri2 = matlab.net.URI;
uri2.Path = {'products' 'matlab'};
EP = uri2.EncodedPath
EP = products/matlab

如果 URI 中包含 SchemeHostUserInfoPort 属性,且 Path 不为空,则 EncodedPath 会有一个前导 // 字符将 Path 与其他属性分隔开来。因此,仅对于那些不包含 SchemeHostUserInfoPort 属性的 URI,绝对路径和相对路径之间才有区别。例如,uri1 是一个绝对路径。

uri1.EncodedPath
ans = /products/matlab

设置 Host

uri1.Host = 'www.mathworks.com';
disp(string(uri1))
//www.mathworks.com/products/matlab

设置相对路径 uri2Host

uri2.EncodedPath
ans = products/matlab
uri2.Host = 'www.mathworks.com';
disp(string(uri2))
//www.mathworks.com/products/matlab

要创建一个 URI,并使其路径指向根目录,请将 Path 设置为 string.empty["" ""]

uri.Path = {'products' 'matlab' ''};
EP = uri.EncodedPath
EP = products/matlab/

要将 Path 设置为某个文件夹,请在向量末尾添加一个空字符串。此约定将向 EncodedPath 中添加一个尾部 /

uri.Path = {'products' 'matlab' ''};
EP = uri.EncodedPath
EP = products/matlab/

URI 的查询,指定为 matlab.net.QueryParameter 对象的向量或指定为字符串,其中包含已编码的查询和一个可选的前导 ? 字符。

次级资源的指向值,指定为字符串或字符向量。string 方法将对 URI 的 fragment 部分中不允许使用的字符进行百分号 (%) 编码。设置 Fragment 时,不要对值进行编码。

示例: 在 URI https://www.mathworks.com/help/matlab/ref/weboptions.html#examples 中,Fragment 属性为 examples

URI 是否为绝对路径,指定为 truefalse。绝对 URI 具有非空 Scheme 属性。如果 URI 不是绝对路径,则是相对路径。要查看 absolute-URI 的定义,请参阅 Internet Engineering Task Force (IETF) 网站上的 RFC 3986 Uniform Resource Identifier (URI):Generic Syntax, Section 4.3 Absolute URI。

绝对 URI 中的 Path 属性始终被视为绝对路径,而 EncodedPath 属性始终包含一个前导 / 字符。要发送消息,URI 必须为绝对路径,还必须包含一个非空 Host 属性。

数据类型: logical

URI 中已编码的权限部分,指定为字符串或字符向量,包含相关联的标点符号,仅在属性非空时才会出现。EncodedAuthority 的格式为 UserInfo@Host:Port。设置 EncodedAuthority 是设置 UserInfoHostPort 属性的捷径,但您必须对特殊字符进行编码。

示例: 在 URI https://user:pwd@www.mathworks.com:8000/product/matlab?abc=def&this=that#xyz 中,EncodedAuthority 属性为 user:pwd@www.mathworks.com:8000

已编码的路径,指定为字符串或字符向量。读取此属性可获得 Path 属性的已编码字符串,与已编码的 URI 中显示的一样。如果您的路径已编码为字符串,请设置 EncodedPath 属性,而不是 Path 属性,以防止再次编码。读取 EncodedPath 时,如果 Path 不为 [] 并且 URI 中的 Path 前面有非空组成部分,则它会有一个前导 /

EncodedPath 设置为空数组(''[]string.empty)等同于将 Path 设置为该值。

如果已编码的 URI 中没有 Path 属性,EncodedPath 将返回空字符串 ""。但 EncodedPath 在任何情况下都不会是空数组。

示例: 在 URI https://www.mathworks.com/solutions/robotics 中,EncodedPath 属性为 /solutions/robotics

已编码的查询,指定为字符串或字符向量。EncodedQuery 返回的值与对 Query 属性调用 string 方法返回的值相同。设置 EncodedQuery 等同于设置 Query 属性。

示例: 在 URI https://www.mathworks.com/support/search_results.html?q=+weboptions+product:"MATLAB+Compiler" 中,EncodedQuery 属性为 q=+weboptions+product:%22MATLAB+Compiler%22

已编码的完整 URI,指定为字符串或字符向量。EncodedURI 返回的值与 matlab.net.URI.string 方法返回的值相同。设置 EncodedURI 等同于调用带 'literal' 参数的 URI 构造函数。

方法

全部展开

示例

全部折叠

创建一个 URI。

U = matlab.net.URI('https://www.mathworks.com');
U.Query = matlab.net.QueryParameter('q','weboptions');
U.Path = 'search/site_search.html';

显示包含 weboptions 的搜索结果。

 web(char(U))
U = matlab.net.URI('//www.mathworks.com/products/simulink/');
U.EncodedURI
ans = 

  string

    "//www.mathworks.com/products/simulink/"

版本历史记录

在 R2016b 中推出