ドキュメンテーション

最新のリリースでは、このページがまだ翻訳されていません。 このページの最新版は英語でご覧になれます。

weboptions

RESTful Web サービスのパラメーターの指定

説明

options = weboptions は、Web サービスへの要求でパラメーターを指定するための、既定の weboptions オブジェクトを返します。weboptions オブジェクトは、関数 webreadwebsave および webwrite のオプションの入力引数にすることもできます。関数 weboptions によってサポートされていないオプションについては、HTTP インターフェイスを参照してください。

options = weboptions(Name,Value) は、weboptions オブジェクトの 1 つ以上のプロパティを指定します。

既定の weboptions オブジェクト

既定の weboptions オブジェクトを作成し、そのプロパティの既定値を表示します。

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'

weboptions オブジェクトのユーザー名とパスワード

weboptions オブジェクトに Web サービスのユーザー名とパスワードを設定します。Web サービスで認証が必要な場合、このオブジェクトを webreadwebsave または webwrite への入力引数として使用できます。

options = weboptions('Username','jdoe','Password','mypassword');

weboptions オブジェクトの表示時にはパスワードは隠されています。しかし、オブジェクトにはパスワードがプレーン テキストで格納されます。パスワードは weboptions.Password プロパティから取得できます。

options.Password
ans = 
'mypassword'

入力引数

すべて折りたたむ

名前と値のペアの引数

オプションの Name,Value の引数ペアをコンマ区切りで指定します。Name は引数名で、Value は対応する値です。Name は引用符で囲まなければなりません。Name1,Value1,...,NameN,ValueN のように、複数の名前と値のペアの引数を任意の順序で指定できます。

例: weboptions('Timeout',60) は、タイムアウト接続期間を 60 秒に設定する weboptions オブジェクトを作成します。

webread で Web コンテンツを文字に変換するために使用するエンコード。string スカラーまたは文字ベクトルとして指定します。一般的なエンコードには、'US-ASCII''UTF-8''latin1''Shift_JIS'、および 'ISO-8859-1' が含まれます。既定のエンコードはコンテンツ タイプによって異なります。文字化けする場合は、webread のエンコードがドキュメントで使用されているエンコードと異なっている可能性があります。CharacterEncodingUTF-8 に設定してみてください。

ユーザー エージェントの識別。クライアント ユーザー エージェントを示す string スカラーまたは文字ベクトルとして指定します。

秒単位のタイムアウト接続期間。正の数値スカラーとして指定します。最大値は 2147.483647 秒です。最大値を設定するには Inf を使用します。

一部のオペレーティング システムでは、タイムアウトの最大値がシステムによって適用されます。このタイムアウトは、Timeout の値が最大値より大きい場合でも有効です。たとえば、Windows® 10 では、このタイムアウトは 21 秒です。

ユーザー識別子。基本 HTTP 認証 (暗号化なし) の string スカラーまたは文字ベクトルとして指定します。

ユーザー認証パスワード。基本 HTTP 認証 (暗号化なし) の string スカラーまたは文字ベクトルとして指定します。Password プロパティを設定した weboptions オブジェクトを表示する場合、値は '*' を含む文字ベクトルとして表示されます。ただし、オブジェクトは Password プロパティの値をプレーン テキストとして格納します。

キーの名前。string スカラーまたは文字ベクトルとして指定します。KeyName は HTTP 要求ヘッダーに付加する追加の名前です。たとえば、KeyName は Web サービス API キーの名前にすることができます。

例: weboptions('KeyName','duration','KeyValue',7) は Web サービスによって定義されたキー名 duration を含む weboptions オブジェクトを作成します。

キーの値。HTTP 要求ヘッダーに追加する string スカラー、文字ベクトル、数値または logical 値として指定します。KeyValueKeyName で指定されたキーの値です。

例: weboptions('KeyName','duration','KeyValue',7) は、キー名 duration とキー値 7 のペアを含む weboptions オブジェクトを作成します。

ヘッダー フィールドの名前と値。HTTP リクエスト ヘッダーに追加する m 行 2 列の string の配列または文字ベクトルの cell 配列として指定します。HeaderFields{i,1} はフィールドの名前で、HeaderFields{i,2} はその値です。

これらのヘッダー フィールドは、webreadwebwrite または websave により自動的に追加されたフィールドに追加されるか、これらのフィールドを置き換えます。通常、これらのフィールドは追加されますが、これらのフィールドのいずれかの名前が、自動的に追加されるフィールドのいずれかと大文字と小文字の区別なしで一致し、そのフィールドが複数の値をサポートしない場合 (Content-Type など)、ユーザーが指定した値が代わりに使用されます。一部のフィールド (Connection や Content-Length など) は、要求を正常に送信するために必須の値をもつため、上書きできません。

例: weboptions('HeaderFields',{'Content-Length' '78';'Content-Type' 'application/json'}) は、2 つのヘッダー フィールドを含む weboptions オブジェクトを作成します。Content-Length の値は 78 で、Content-Type の値は application/json です。

コンテンツ タイプ。string スカラーまたは文字ベクトルとして指定します。ContentType を使用してサーバーが特定の形式で選択的にデータを返すように要求します。webread はこの値を使用して、MATLAB® 型に応答を変換します。可能であれば、サーバーはこのコンテンツ タイプを返しますが、必須ではありません。

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 コンテンツの数値または論理行列。最初の出力引数がインデックス付きイメージの場合、2 番目の出力引数はカラーマップ、 3 番目の出力引数はアルファ チャネルです。

サポートされるイメージ形式については、インポートとエクスポートでサポートされるファイル形式を参照してください。

'audio'

audio/format コンテンツの数値行列。2 番目の出力引数にサンプリング レートを数値スカラーとして含みます。

サポートされるオーディオ形式については、インポートとエクスポートでサポートされるファイル形式を参照してください。

'binary'

バイナリ コンテンツ (つまり char 型として処理されないコンテンツ) の uint8 の列ベクトル。

'table'

スプレッドシートおよび CSV (text/csv) コンテンツのスカラー テーブル オブジェクト。

'json'

application/json コンテンツの char、数値、論理値、構造体または cell 配列。

'xmldom'

text/xml または application/xml コンテンツの Java® ドキュメント オブジェクト モデル (DOM) ノード。指定しない場合、関数は XML コンテンツを文字ベクトルとして返します。

'raw'

'text''xmldom' および 'json' コンテンツの char の列ベクトル。関数はその他のすべてのコンテンツ タイプを uint8 の列ベクトルとして返します。

例: weboptions('ContentType','text') は、テキスト、JSON または XML コンテンツを文字ベクトルとして返すように webread に指示する weboptions オブジェクトを作成します。

コンテンツ リーダー。関数ハンドルとして指定します。ContentReader を指定して weboptions オブジェクトを作成し、オブジェクトを入力引数として webread に渡すことができます。続いて、webread は Web サービスからデータをダウンロードし、関数ハンドルで指定された関数を使用してデータを読み取ります。webread は、ContentReader が指定されている場合 ContentType を無視します。

例: weboptions('ContentReader',@readtable) はコンテンツをテーブルとして読み取るために readtable を使用するように webread に指示する weboptions オブジェクトを作成します。

メディア タイプ。string スカラー、文字ベクトル、または matlab.net.http.MediaType オブジェクトとして指定します。MediaType は、webwrite が Web サービスに送信するデータのタイプを指定します。これは、MATLAB がサーバーに対して指定するコンテンツ タイプを示し、webwritedata 引数が指定されている場合はその変換方法を制御します。

メディア タイプの完全な一覧については、Media Types を参照してください。

既定値は 'auto' であり、webwrite への入力に基づいて MATLAB でタイプが選択されます。PostName/PostValue の引数のペアを使用している場合、MATLAB は 'application/x-www-form-urlencoded' を使用してペアを送信します。スカラー string または文字ベクトルである data 引数を使用している場合は、MATLAB はフォーム エンコードされた文字列と想定し、'application/x-www-form-urlencoded' を使用してそのまま送信します。data がそれ以外の場合は、MATLAB は jsonencode を使用して JSON に変換し、コンテンツ タイプ 'application/json' を使用します。

'json' または 'javascript' を含む MediaType を指定した場合、data が文字ベクトルであればそのまま送信されます。スカラー string など、それ以外のタイプの場合は、いずれも jsonencode を使用して変換されます。

'application/x-www-form-urlencoded' を指定した場合、PostName/PostValue のペアがフォーム エンコードされて送信されます。data がある場合は、そのまま送信される string または文字ベクトルでなければなりません。

'xml' を含む MediaType を指定した場合、data がドキュメント オブジェクト モデル オブジェクト (Java org.apache.xerces.dom.DocumentImpl) であれば XML に変換されます。data がある場合は、そのまま送信される string または文字ベクトルでなければなりません。

他の任意の MediaType が指定され、data が string または文字ベクトルである場合、weboptions は値をそのまま送信します。

PostName/PostValue のペアは MediaType の値 'auto' および 'application/x-www-form-urlencoded' でのみ受け入れられ、文字ベクトルは MediaType に関係なく常にそのまま送信されます。

MediaType の文字列内でセミコロン区切りの name=value パラメーターを、たとえば 'application/json; odata=verbose' のように指定できます。一部のサーバーでは、この形式が、要求の Content-Type ヘッダー フィールドの一部として求められます。

例: weboptions('MediaType','application/json') は、文字ベクトル データを JSON としてエンコードして Web サービスに送るように webwrite に指示する weboptions オブジェクトを作成します。

HTTP 要求メソッド。以下の値のいずれかからなる string スカラー、文字ベクトル、または matlab.net.http.RequestMethod 列挙値として指定します。

  • 'auto'

    • webreadwebsave は HTTP GET メソッドを使用。

    • webwrite は HTTP POST メソッドを使用。

  • 'get' は関数 webread および websave と共に使用。

  • 'post' は関数 webreadwebwrite および websave と共に使用。

  • 'put' は関数 webreadwebwrite および websave と共に使用。

  • 'delete' は関数 webreadwebwrite および websave と共に使用。

  • 'patch' は関数 webreadwebwrite および websave と共に使用。

関数 webread および websaveRequestMethod にかかわらずクエリを URL に挿入します。webwriteRequestMethod にかかわらずクエリをデータに挿入します。

例: weboptions('RequestMethod','post') は、webreadwebsave または webwrite に対して Web サービスの HTTP POST メソッドを使用するよう指示をする、weboptions オブジェクトを作成します。

複数の値を表現するクエリまたはポスト値をフォーム エンコードする形式。'csv''json''repeating' または 'php' として指定します。クエリまたはポスト値が以下の場合、複数の値が含まれます。

  • 数値、論理値または datetime ベクトル

  • 複数の行をもつ文字配列

  • 各要素が数値、論理値、datetime スカラー、または 1 行の文字ベクトルである cell ベクトル

上記以外のデータ型または次元はサポートされません。

次の表は、クエリ パラメーターを 'parameter'、クエリ値を [1 2 3] とした場合の各形式でのフォーム エンコードされた変換を示します。使用する変換は Web サービスにより指定されます。

ArrayFormat 指定子

フォーム エンコードされた変換

'csv' (既定)

parameter=1,2,3

'json'

parameter=[1,2,3]

'repeating'

parameter=1&parameter=2&parameter=3

'php'

parameter[]=1&parameter[]=2&parameter[]=3

スカラーを 'json' または 'php' 指定子を使用して 1 要素配列としてエンコードするには、スカラーを 1 要素の cell 配列に含めます。

例: weboptions('ArrayFormat','repeating') は、複数の値をもつすべてのクエリまたはポスト値を反復クエリ パラメーターとしてフォーム エンコードするように webreadwebsave または webwrite に指示をする weboptions オブジェクトを作成します。

ルート証明書のファイル名。証明書を含むファイルの場所を示す string または文字ベクトルとして指定します。ファイルは、Privacy-Enhanced Mail (PEM) 形式です。場所は、現在のフォルダー内、MATLAB パス上のフォルダー内またはファイルへの絶対パスか相対パスでなければなりません。値 'default' を指定した場合、CertificateFilename は、MATLAB に付属の証明書ファイルのパスに設定されます。パスを判別するには、空の weboptions または HTTPOptions オブジェクトを作成し、CertificateFilename の既定値を確認します。

HTTPS 接続を要求した場合、サーバーからの証明書が PEM ファイル内の認証機関証明書に対して検証されます。標準の HTTPS メカニズムは、この検証を使用してサーバー証明書のシグネチャと証明書チェーン全体を検証します。検証が失敗すると、接続は許可されません。サーバーの証明書が、サーバーへのアクセスに使用する URI と一致しない場合は、matlab.net.http.RequestMessage を作成し、matlab.net.http.HTTPOptions.VerifyServerName プロパティを false に設定することで、検証を無効にできます。このオプションは、対象のサーバーと直接通信している確信がある場合に使用してください。

証明書を rootcerts.pem に追加するには、ファイルを作業フォルダーにコピーし、ファイルを編集し、証明書をそれに追加します。PEM ファイルは、容易に変更できる ASCII ファイルです。HTTPS 接続のセキュリティはこのファイルの信頼性に依存するため、このファイルを適切に保護してください。MATLAB は証明書または証明書ファイルを管理しませんが、PEM ファイルを管理するためのサードパーティ製のツールがあります。

CertificateFilename が空の場合、MATLAB は、サーバーの証明書ドメインがサーバーのホスト名と一致するかどうか、それが期限切れでないかを確認します。シグネチャは検証されません。

CertificateFilename は、証明書の欠落または期限切れが原因で接続を確立できない場合にのみ、空 ('') に設定します。

属性:

GetAccess

public

SetAccess

public

R2014b で導入