Documentation

This is machine translation

Translated by Microsoft
Mouseover text to see original. Click the button below to return to the English verison of the page.

Note: This page has been translated by MathWorks. Please click here
To view all translated materals including this page, select Japan from the country navigator on the bottom of this page.

weboptions

Specify parameters for RESTful web service

Syntax

options = weboptions
options = weboptions(Name,Value)

Description

example

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 HTTP Interface.

example

options = weboptions(Name,Value) specifies one or more properties of a weboptions object.

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.2.0.556344 (R2017a)'
                Timeout: 5
               Username: ''
               Password: ''
                KeyName: ''
               KeyValue: ''
            ContentType: 'auto'
          ContentReader: []
              MediaType: 'application/x-www-form-urlencoded'
          RequestMethod: 'auto'
            ArrayFormat: 'csv'
           HeaderFields: []
    CertificateFilename: 'C:\Program Files\MATLAB\R2017a\sys\certificates\ca\rootcerts.pem'

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

collapse all

Name-Value Pair Arguments

Specify optional comma-separated pairs of Name,Value arguments. Name is the argument name and Value is the corresponding value. Name must appear inside single quotes (' '). You can specify several name and value pair arguments in any order as Name1,Value1,...,NameN,ValueN.

Example: weboptions('Timeout',60) creates a weboptions object that sets the timeout connection duration to 60 seconds.

collapse all

Character encoding, specified as a string or character vector. Common encodings include 'US-ASCII', 'UTF-8', 'latin1', 'Shift_JS', and'ISO-8859-1'.

User agent identification, specified as a string or character vector indicating the client user agent.

Timeout connection duration in seconds, specified as a positive numeric scalar. The maximum value is 2147.483647 seconds. Use Inf to set the maximum value.

User identifier, specified as a string or character vector for basic HTTP authentication (no encryption).

User authentication password, specified as a string or character vector for basic HTTP authentication (no encryption). If you display a weboptions object with the Password property set, the value is displayed as a character vector containing ‘*’. However, the object stores the value of the Password property as plain text.

Name of a key, specified as a string 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.

Value of a key, specified as a string, 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.

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.

Content type, specified as a string or character vector. Content type is used to convert the response from the server to a particular type. You can define the ContentType property of a weboptions object, and pass the object as an input argument to webread. Then webread returns data as that type of content. The table lists the valid content types.

ContentType Specifier

Output Type

'auto' (default)

Output type automatically determined based on content type.

'text'

Character vector for content types:

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

If 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. If the first output argument is an indexed image, the second output argument is the colormap, and the third output argument is the alpha channel.

For supported image formats, see Supported File Formats for Import and Export.

'audio'

Numeric matrix for audio/format content with numeric scalar sampling rate as a second output argument.

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, for application/json content.

'xmldom'

Java® Document Object Model (DOM) node for text/xml or application/xml content. If 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 a uint8 column vector.

Example: weboptions('ContentType','text') creates a weboptions object that instructs webread to return text, JSON, or XML content as a character vector.

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.

Media type, specified as a string or character vector. Media type determines the type of content (media) to send to the server. See Internet Media Types for a complete list of media types.

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.

HTTP request method, specified as a string, a character vector, or a matlab.net.http.RequestMethod enumeration as one of these values:

  • 'auto'

    • webread and websave use the HTTP GET method.

    • webwrite uses the HTTP POST method.

  • 'get' for use with the webread and websave functions.

  • 'post' for use with the webread, webwrite, and websave functions.

  • 'put' for use with the webread, webwrite, and websave functions.

  • 'delete' for use with the webread, webwrite, and websave functions.

  • 'patch' for use with the webread, webwrite, and websave 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.

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, 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.

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 instructs webread, websave, or webwrite to form-encode any query or post value with multiple values as repeating query parameters.

File name of root certificates, specified as a string or character vector denoting the location of a file containing certificates. The file is 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. If you specify the value 'default', then CertificateFilename is set to the MATLAB certificate file at:

fullfile(matlabroot,'sys','certificates','ca','rootcerts.pem')

If you request an HTTPS connection, then the certificate from the server is validated against the certification authority certificates in the PEM file. Standard HTTPS mechanisms use this validation to validate the signature on the server certificate and the entire certificate chain. If verification fails, a connection is not allowed. You can disable the verification in cases where the server's certificate does not match the URI used to access it, by creating a matlab.net.http.RequestMessage and setting the matlab.net.http.HTTPOptions.VerifyServerName property to false. Use this option if you are confident that you are communicating directly with the intended server.

To add certificates to rootcerts.pem, copy the file to a working folder, edit the file, and add your certificates to it. PEM files are ASCII files which are easily modified. Since security of HTTPS connections depends on the integrity of this file, protect it appropriately. MATLAB does not manage certificates or certificate files, but there are third-party tools for managing PEM files.

If CertificateFilename is empty, then MATLAB checks if the certificate domain of the server matches the host name of the server and that it is not expired. The signature is not validated.

Set CertificateFilename to empty ('') only if you cannot establish a connection due to a missing or expired certificate.

Introduced in R2014b

Was this topic helpful?