weboptions
Specify parameters for RESTful web service
Description
options = weboptions
returns a default weboptions
object
to specify parameters for a request to a web service. A weboptions
object
can be an optional input argument to the webread
, websave
,
and webwrite
functions. For options not supported by the weboptions
function,
see the Call Web Services from MATLAB Using HTTP.
options = weboptions(
specifies one or
more properties of a Name,Value
)weboptions
object. To remove sensitive
information from code, see loadenv
.
Examples
Default weboptions
Object
Create a default weboptions
object and display the default
values for its properties.
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'
User Name and Password in weboptions Object
Set your web service user name and password in a weboptions
object. You can use the object as an input argument to webread
, websave
, or webwrite
when your web service requires authentication.
options = weboptions('Username','jdoe','Password','mypassword');
The password is obscured when you display the weboptions
object. However, the object stores the password as plain text. You can retrieve the password from the weboptions.Password
property.
options.Password
ans = 'mypassword'
Input Arguments
Name-Value Arguments
Specify optional pairs of arguments as
Name1=Value1,...,NameN=ValueN
, where Name
is
the argument name and Value
is the corresponding value.
Name-value arguments must appear after other arguments, but the order of the
pairs does not matter.
Before R2021a, use commas to separate each name and value, and enclose
Name
in quotes.
Example: weboptions('Timeout',60)
creates a
weboptions
object that sets the timeout connection duration
to 60 seconds.
CharacterEncoding
— Character encoding
'auto'
(default) | string scalar | character vector
The encoding used by webread
to convert web
content to characters, specified as a string scalar or character vector.
Common encodings include 'US-ASCII'
,
'UTF-8'
, 'latin1'
,
'Shift_JIS'
, and'ISO-8859-1'
.
The default encoding depends on the content type. If you get garbled
text, then the webread
encoding might be different
from the encoding used by the document. Try setting
CharacterEncoding
to
UTF-8
.
UserAgent
— User agent identification
['MATLAB ' version]
(default) | string scalar | character vector
User agent identification, specified as a string scalar or character vector indicating the client user agent.
Timeout
— Time out connection duration
5 (default) | positive numeric scalar | Inf
Time out connection duration in seconds, specified as a positive
numeric scalar. The value is the number of seconds to wait to receive
the initial response (header) from the server after sending the last
packet of a request. Timeout
is equivalent to the
ResponseTimeout property in the
matlab.net.http.HTTPOptions
class. The maximum value
is 2147.483647 seconds. Use Inf
to set the maximum
value.
Some operating systems have a maximum timeout enforced by the system.
This timeout takes effect even if the value of
Timeout
is greater than the maximum. For example,
on Windows® 10, this timeout is 21 seconds.
Username
— User identifier
''
(default) | string scalar | character vector
User identifier, specified as a string scalar or character vector for basic and/or digest HTTP authentication (no encryption). For information about Basic HTTP Authentication Scheme, see RFC 7617 on the RFC Editor website. For information about HTTP Digest Access Authentication, see RFC 7616.
Password
— User authentication password
''
(default) | string scalar | character vector
User authentication password, specified as a string scalar or
character vector for basic and/or digest HTTP authentication (no
encryption). If you display a weboptions
object with
Password
set, then the value is displayed as a
character vector containing ‘*’. However, the object stores the value of
Password
as plain text.
KeyName
— Name of key
''
(default) | string scalar | character vector
Name of a key, specified as a string scalar or character vector.
KeyName
is an additional name to add to the HTTP
request header. For example, KeyName
can be a web
service API key name.
Example: weboptions('KeyName','duration','KeyValue',7)
creates a weboptions
object that contains a key name,
duration
, defined by a web
service.
KeyValue
— Value of key
''
(default) | string scalar | character vector | numeric | logical
Value of a key, specified as a string scalar, a character vector, or a
numeric or logical value to add to the HTTP request header.
KeyValue
is the value of a key specified by
KeyName
.
Example: weboptions('KeyName','duration','KeyValue',7)
creates a weboptions
object that contains a key
value, 7
, paired with a key name,
duration
.
HeaderFields
— Names and values of header fields
m-by-2 array of strings or cell array of character vectors
Names and values of header fields, specified as an m-by-2 array of
strings or cell array of character vectors to add to the HTTP request
header. HeaderFields{i,1}
is the name of a field and
HeaderFields{i,2}
is its value.
These header fields add to or replace fields automatically added by
webread
, webwrite
, or
websave
. Normally these fields are added, but
if the name of one of these fields is a case-insensitive match to one of
the fields that would be automatically added, and that field does not
support multiple values (for example, Content-Type), then the value you
specify is used instead. Some fields whose value is necessary to send a
request successfully, such as Connection and Content-Length, cannot be
overridden.
Example: weboptions('HeaderFields',{'Content-Length'
'78';'Content-Type' 'application/json'})
creates a
weboptions
object that contains two header
fields: Content-Length
with value
78
and Content-Type
with value
application/json
.
ContentType
— Content type
'auto'
(default) | string scalar | character vector
Content type, specified as a string scalar or character vector. Use
ContentType
to request that the server
preferentially return data in a particular format.
webread
uses this value to convert the response
to a MATLAB® type. The server returns this content type if possible,
but is not obligated to do so.
| Output Type |
---|---|
| Output type is automatically determined based on the content type specified by the web service. |
| Character vector for content types:
If a web service returns a
MATLAB file with a |
| Numeric or logical matrix for For supported image formats, see Supported File Formats for Import and Export. |
| Numeric matrix for For supported audio formats, see Supported File Formats for Import and Export. |
|
|
| Scalar table object for spreadsheet and CSV ( |
|
|
| Java® Document Object Model (DOM) node for
|
|
|
Example: weboptions('ContentType','text')
creates a
weboptions
object that instructs
webread
to return text, JSON, or XML content as a
character vector.
ContentReader
— Content reader
[]
(default) | function handle
Content reader, specified as a function handle. You can create a
weboptions
object with
ContentReader
specified, and pass the object as
an input argument to webread
. Then
webread
downloads data from a web service and
reads the data with the function specified by the function handle.
webread
ignores ContentType
when ContentReader
is specified.
Example: weboptions('ContentReader',@readtable)
creates a weboptions
object that instructs
webread
to use readtable
to
read content as a table.
MediaType
— Media type
'auto'
(default) | 'application/x-www-form-urlencoded'
| string scalar | character vector | matlab.net.http.MediaType
Media type, specified as a string scalar, a character vector, or a
matlab.net.http.MediaType
object.
MediaType
specifies the type of data
webwrite
sends to the web service. It specifies
the content type that MATLAB specifies to the server, and it controls how the
webwrite
data
argument, if specified, is converted. For more
information, see RFC 6838 Media Type Specifications and Registration
Procedures on the RFC Editor website.
The default value is 'auto'
which indicates that
MATLAB chooses the type based on the input to
webwrite
. If using
PostName/PostValue
argument pairs, then
MATLAB uses
'application/x-www-form-urlencoded'
to send the
pairs. If using a data
argument that is a scalar
string or character vector, then MATLAB assumes it is a form-encoded string and sends it as-is
using 'application/x-www-form-urlencoded'
. If
data
is anything else, then MATLAB converts it to JSON using jsonencode
and uses the content type 'application/json'
.
If you specify a MediaType
containing
'json'
or 'javascript'
, and
data
is a character vector, then it is sent
as-is. All other types, including scalar strings, are converted using
jsonencode
.
If you specify 'application/x-www-form-urlencoded'
,
then PostName/PostValue
pairs are sent form-encoded.
data
, if present, must be a string or character
vector to be sent as-is.
If you specify a MediaType
that contains
'xml'
, and data
is a Document
Object Model object (a Java
org.apache.xerces.dom.DocumentImpl
), then it is
converted to XML. data
, if present, must be a string
or character vector to be sent as-is.
If you specify any other MediaType
, and
data
is a string or character vector, then
weboptions
sends the value as-is.
PostName/PostValue
pairs are accepted only for
MediaType
values 'auto'
and
'application/x-www-form-urlencoded'
, and
character vectors are always sent as-is regardless of the
MediaType
.
You can specify semicolon-separated name=value
parameters within the MediaType
string, for example,
'application/json; odata=verbose'
. Some servers
require this format as part of the Content-Type header field in the
request.
Example: weboptions('MediaType','application/json')
creates a weboptions
object that instructs
webwrite
to encode character vector data as JSON
to post it to a web service.
RequestMethod
— HTTP request method
'auto'
(default) | string scalar | character vector | matlab.net.http.RequestMethod
enumeration
HTTP request method, specified as a string scalar, a character vector,
or a matlab.net.http.RequestMethod
enumeration as one of these
values:
'auto'
webread
andwebsave
use the HTTP GET method.webwrite
uses the HTTP POST method.
'get'
for use with thewebread
andwebsave
functions.'post'
for use with thewebread
,webwrite
, andwebsave
functions.'put'
for use with thewebread
,webwrite
, andwebsave
functions.'delete'
for use with thewebread
,webwrite
, andwebsave
functions.'patch'
for use with thewebread
,webwrite
, andwebsave
functions.
The webread
and websave
functions put the query into the URL regardless of the
RequestMethod
. webwrite
puts
the query into the data regardless of the
RequestMethod
.
Example: weboptions('RequestMethod','post')
creates
a weboptions
object that instructs
webread
, websave
, or
webwrite
to use the HTTP POST method of a web
service.
ArrayFormat
— Format to form-encode query or post values that represent multiple values
'csv'
(default) | 'json'
| 'repeating'
| 'php'
Format to form-encode query or post values that represent multiple
values, specified as 'csv'
,
'json'
, 'repeating'
, or
'php'
. A query or post value contains multiple
values if it is
A numeric, logical, or
datetime
vectorA character array with more than one row
A cell vector, where each element is a numeric, logical, or
datetime
scalar or a character vector with one row
No other data types or dimensions are supported.
This table shows form-encoded conversions for each format, for a query
parameter named 'parameter'
and a query value of
[1 2 3]
. The web service specifies the conversion
to use.
| Form-Encoded Conversion |
---|---|
|
|
|
|
|
|
|
|
To encode a scalar as a one-element array with the
'json'
or 'php'
specifiers,
place the scalar in a one-element cell array.
Example: weboptions('ArrayFormat','repeating')
creates a weboptions
object that instructs
webread
, websave
, or
webwrite
to form-encode any query or post value
with multiple values as repeating query parameters.
CertificateFilename
— File name
'default'
(default) | string scalar | character vector
File name, specified as a string scalar or character vector denoting the name and location of a file containing root certificates. The file must be in privacy-enhanced mail (PEM) format. The location must be in the current folder, in a folder on the MATLAB path, or a full or relative path to a file. The certificates contained in this file are used to validate server certificates for HTTPS connections. Since the security of HTTPS connections depends on the integrity of this file, please protect it appropriately. MATLAB does not manage certificates or certificate files, but there are third-party tools available for managing PEM files.
By default when options are not specified, MATLAB validates server certificates using the system-provided certificate store.
This is also the behavior if CertificateFilename
is set to
'default'
.
If CertificateFilename
is empty (''
), then the
validation of the server certificate is turned off. MATLAB only verifies that the domain name of the server certificate matches that of
the server.
If you encounter a server certificate validation failure using
'default'
, then check the connection using your system
browser.
If you encounter a connection issue, consider the following:
For an expired or revoked server certificate, contact the website owner or server administrator.
For a missing Root CA certificate, you can choose one of the following:
Add the Root CA certificate to the file denoted by
CertificateFilename
.Disable certificate validation by setting
CertificateFilename
to empty (''
).
For a mismatch between the domain name of the server certificate and the domain name of the server, you can disable this validation by creating a
matlab.net.http.RequestMessage
object and setting thematlab.net.http.HTTPOptions.VerifyServerName
property tofalse
.
Note
These options are temporary workarounds and MathWorks strongly recommends that you resolve the root cause of any server certificate validation failure by using a valid/correct server certificate.
Attributes:
- GetAccess
public
- SetAccess
public
Version History
Introduced in R2014b
See Also
webread
| websave
| webwrite
| RequestMethod
| HTTPOptions
Commande MATLAB
Vous avez cliqué sur un lien qui correspond à cette commande MATLAB :
Pour exécuter la commande, saisissez-la dans la fenêtre de commande de MATLAB. Les navigateurs web ne supportent pas les commandes MATLAB.
Select a Web Site
Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .
You can also select a web site from the following list:
How to Get Best Site Performance
Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.
Americas
- América Latina (Español)
- Canada (English)
- United States (English)
Europe
- Belgium (English)
- Denmark (English)
- Deutschland (Deutsch)
- España (Español)
- Finland (English)
- France (Français)
- Ireland (English)
- Italia (Italiano)
- Luxembourg (English)
- Netherlands (English)
- Norway (English)
- Österreich (Deutsch)
- Portugal (English)
- Sweden (English)
- Switzerland
- United Kingdom (English)