weboptions - Specify parameters for RESTful web service - MATLAB (original) (raw)

Specify parameters for RESTful web service

Syntax

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.

example

options = weboptions([Name,Value](#namevaluepairarguments)) specifies one or more properties of a weboptions object. To remove sensitive information from code, see loadenv.

example

Examples

Default `weboptions` Object

Create a default weboptions object and display the default values for its properties.

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.

Input Arguments

collapse all

Name-Value Arguments

Specify optional pairs of arguments asName1=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 aweboptions 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 settingCharacterEncoding toUTF-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 theResponseTimeout property in thematlab.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 ofTimeout 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 withPassword set, then the value is displayed as a character vector containing ‘*’. However, the object stores the value ofPassword 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 byKeyName.

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 andHeaderFields{i,2} is its value.

These header fields add to or replace fields automatically added bywebread, webwrite, orwebsave. 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 aweboptions object that contains two header fields: Content-Length with value78 and Content-Type with valueapplication/json.

`ContentType` — Content type

'auto' (default) | string scalar | character vector

Content type, specified as a string scalar or character vector. UseContentType 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.

ContentType Value	Output Type
"auto" (default)	Output type is automatically determined based on the content type specified by the web service.
"text"	Character vector for content types: text/plaintext/htmltext/xmlapplication/xmlapplication/javascriptapplication/x-javascriptapplication/x-www-form-urlencodedIf a web service returns a MATLAB file with a .m extension, the function returns its content as a character vector.
"image"	Numeric or logical matrix for image/format content.For supported image formats, see Supported File Formats for Import and Export.
"audio"	Numeric matrix for audio/format content.For supported audio formats, see Supported File Formats for Import and Export.
"binary"	uint8 column vector for binary content (that is, content not to be treated as type char).
"table"	Scalar table object for spreadsheet and CSV (text/csv) content.
"json"	char, numeric, logical, structure, or cell array forapplication/json content.
"xmldom"	Java® Document Object Model (DOM) node fortext/xml orapplication/xml content. IfContentType is not specified, the function returns XML content as a character vector.
"raw"	char column vector for "text","xmldom", and"json" content. The function returns any other content type as auint8 column vector.

Example: weboptions('ContentType','text') creates aweboptions object that instructswebread 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 aweboptions object withContentReader specified, and pass the object as an input argument to webread. Thenwebread 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 instructswebread 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 amatlab.net.http.MediaType object.MediaType specifies the type of datawebwrite sends to the web service. It specifies the content type that MATLAB specifies to the server, and it controls how thewebwrite 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 towebwrite. If usingPostName/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'. Ifdata 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', anddata is a character vector, then it is sent as-is. All other types, including scalar strings, are converted usingjsonencode.

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 Javaorg.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, anddata is a string or character vector, thenweboptions sends the value as-is.

PostName/PostValue pairs are accepted only forMediaType values 'auto' and'application/x-www-form-urlencoded', and character vectors are always sent as-is regardless of theMediaType.

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 instructswebwrite 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, and websave functions.
'put' for use with thewebread, webwrite, and websave functions.
'delete' for use with thewebread, webwrite, and websave functions.
'patch' for use with thewebread, webwrite, and websave functions.

The webread and websave functions put the query into the URL regardless of theRequestMethod. webwrite puts the query into the data regardless of theRequestMethod.

Example: weboptions('RequestMethod','post') creates a weboptions object that instructswebread, websave, orwebwrite 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 vector
A character array with more than one row
A cell vector, where each element is a numeric, logical, ordatetime 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.

ArrayFormat Specifier	Form-Encoded Conversion
'csv' (default)	parameter=1,2,3
'json'	parameter=[1,2,3]
'repeating'	parameter=1&parameter=2&parameter=3
'php'	parameter[]=1&parameter[]=2&parameter[]=3

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 instructswebread, websave, orwebwrite 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 byCertificateFilename.
- Disable certificate validation by settingCertificateFilename 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 amatlab.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

weboptions - Specify parameters for RESTful web service - MATLAB (original) (raw)

Syntax

Description

Examples

Default weboptions Object

User Name and Password in weboptions Object

Input Arguments

Name-Value Arguments

CharacterEncoding — Character encoding

UserAgent — User agent identification

Timeout — Time out connection duration

Username — User identifier

Password — User authentication password

KeyName — Name of key

KeyValue — Value of key

HeaderFields — Names and values of header fields

ContentType — Content type

ContentReader — Content reader

MediaType — Media type

RequestMethod — HTTP request method

ArrayFormat — Format to form-encode query or post values that represent multiple values

CertificateFilename — File name

Attributes:

Version History

Default `weboptions` Object

`CharacterEncoding` — Character encoding

`UserAgent` — User agent identification

`Timeout` — Time out connection duration

`Username` — User identifier

`Password` — User authentication password

`KeyName` — Name of key

`KeyValue` — Value of key

`HeaderFields` — Names and values of header fields

`ContentType` — Content type

`ContentReader` — Content reader

`MediaType` — Media type

`RequestMethod` — HTTP request method

`ArrayFormat` — Format to form-encode query or post values that represent multiple values

`CertificateFilename` — File name