weboptions

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

ページ内をすべて折りたたむ

構文

options = weboptions
options = weboptions(Name,Value)

説明

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

例

options = weboptions(Name,Value) は、weboptions オブジェクトの 1 つ以上のプロパティを指定します。機密情報をコードから削除するには、loadenv を参照してください。

例

例

既定の weboptions オブジェクト

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

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'

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

weboptions オブジェクトに Web サービスのユーザー名とパスワードを設定します。Web サービスで認証が必要な場合、weboptions オブジェクトを webread、websave または webwrite への入力引数として使用できます。secretID オブジェクトを使用して機密情報の暗号化を維持してください。

options = weboptions(Username=secretID("MathWorks.Username"), ...
                     Password=secretID("MathWorks.Password"))
options = 
  weboptions with properties:

      CharacterEncoding: 'auto'
              UserAgent: 'MATLAB 25.2.0.2978516 (R2025b)'
                Timeout: 5
               Username: MathWorks.Username (secretID)
               Password: MathWorks.Password (secretID)
                KeyName: ''
               KeyValue: ''
            ContentType: 'auto'
          ContentReader: []
              MediaType: 'auto'
          RequestMethod: 'auto'
            ArrayFormat: 'csv'
           HeaderFields: []
    CertificateFilename: 'default'

secretID オブジェクトは識別子名のみを表示します。

options.Password
ans = 
  secretID with properties:

    Name: "MathWorks.Password"

名前と値の引数

すべて折りたたむ

オプションの引数のペアを Name1=Value1,...,NameN=ValueN として指定します。ここで、Name は引数名で、Value は対応する値です。名前と値の引数は他の引数の後に指定しなければなりませんが、ペアの順序は重要ではありません。

R2021a より前では、コンマを使用してそれぞれの名前と値を区切り、Name を引用符で囲みます。

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

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

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

秒単位のタイムアウト接続期間。正の数値スカラーとして指定します。この値は、要求の最後のパケットを送信してから、サーバーの初期応答 (ヘッダー) を受信するまで待機する秒数です。Timeout は、matlab.net.http.HTTPOptions クラスの ResponseTimeout プロパティと等価です。最大値は 2147.483647 秒です。最大値を設定するには Inf を使用します。

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

ユーザー識別子。基本 HTTP 認証またはダイジェスト HTTP 認証 (暗号化なし) の string スカラーまたは文字ベクトルとして指定します。基本 HTTP 認証スキームの詳細については、RFC Editor Web サイトで RFC 7617 を参照してください。HTTP ダイジェスト アクセス認証の詳細については、RFC 7616 を参照してください。

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

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

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

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

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

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

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

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

例: options.HeaderFields = {'Expect',''} の値を空の string として指定すると、ヘッダー フィールド (Expect) が非表示になります。これは、サーバーがリクエストのヘッダー フィールドを正しく処理できない場合に必要になる可能性があります。

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

ContentType 値

出力タイプ

"auto" (既定)

Web サービスで指定されたコンテンツ タイプに応じて自動的に出力タイプが決定されます。

"text"

コンテンツ タイプを表す文字ベクトル:

  • text/plain

  • text/html

  • text/xml

  • application/xml

  • application/javascript

  • application/x-javascript

  • application/x-www-form-urlencoded

Web サービスから拡張子 .m をもつ MATLAB ファイルが返される場合、この関数はそのコンテンツを文字ベクトルとして返します。

サーバーから返されるテキスト コンテンツについて、サーバーまたはユーザーによって文字エンコードが指定されていない場合、関数は UTF-8 を既定で使用します。

"image"

image/format コンテンツの数値または logical 行列。

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

"audio"

audio/format コンテンツの数値行列。

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

"binary"

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

"table"

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

あるいは、Web サイトからテーブル データを読み取るには、filename 引数を URL として指定して readtable を呼び出します。例については、HTML Web ページを table として読み取りを参照してください。

"json"

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

"xmldom"

text/xml または application/xml コンテンツの Java® ドキュメント オブジェクト モデル (DOM) ノード。ContentType が指定されていない場合、関数は 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 がサーバーに対して指定するコンテンツ タイプを示し、webwrite の data 引数が指定されている場合はその変換方法を制御します。詳細については、RFC Editor Web サイトで RFC 6838 Media Type Specifications and Registration Procedures を参照してください。

既定値は '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'

    • webread と websave は HTTP GET メソッドを使用。

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

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

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

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

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

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

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

例: weboptions('RequestMethod','post') は、webread、websave または 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') は、複数の値をもつすべてのクエリまたはポスト値を反復クエリ パラメーターとしてフォーム エンコードするように webread、websave または webwrite に指示をする weboptions オブジェクトを作成します。

ファイル名。ルート証明書を含むファイルの名前と場所を示す string スカラーまたは文字ベクトルとして指定します。ファイルは Privacy-Enhanced Mail (PEM) 形式でなければなりません。場所は、現在のフォルダー内、MATLAB パス上のフォルダー内またはファイルへの絶対パスか相対パスでなければなりません。このファイルに含まれている証明書は HTTPS 接続用のサーバー証明書を検証するために使用されます。HTTPS 接続のセキュリティはこのファイルの信頼性に依存するため、このファイルを適切に保護してください。MATLAB は証明書または証明書ファイルを管理しませんが、PEM ファイルの管理に使用可能なサードパーティ製のツールがあります。

既定では、オプションが指定されていない場合、MATLAB はシステムによって提供された証明書ストアを使用してサーバー証明書を検証します。これも、CertificateFilename が 'default' に設定されている場合の動作です。

CertificateFilename が空 ('') の場合、サーバー証明書の検証がオフになっています。MATLAB は、サーバー証明書のドメイン名がサーバーのドメイン名と一致することのみを検証します。

'default' の使用時にサーバー証明書の検証に失敗する場合、システム ブラウザーを使用して接続をチェックします。

接続に関する問題が発生する場合は、次を検討してください。

  • サーバー証明書の期限が切れているか取り消されている場合、Web サイトの所有者またはサーバー管理者に連絡してください。

  • ルート CA 証明書がない場合、次のいずれかを選択できます。

    • CertificateFilename で示されたファイルにルート CA 証明書を追加する。

    • CertificateFilename を空 ('') に設定することで、証明書の検証を無効にする。

  • サーバー証明書のドメイン名とサーバーのドメイン名が一致していない場合、matlab.net.http.RequestMessage オブジェクトを作成して matlab.net.http.HTTPOptions.VerifyServerName プロパティを false に設定することでこの検証を無効にできます。

メモ

こうしたオプションは一時的な回避方法であり、サーバー証明書の検証が失敗する根本原因を、有効なまたは正しいサーバー証明書を使用して解決するよう強く推奨します。

属性:

GetAccess

public

SetAccess

public

バージョン履歴

R2014b で導入

参考

| | | |

トピック