Main Content

matlab.net.http.HTTPOptions クラス

パッケージ: matlab.net.http

HTTP メッセージの交換を制御するオプション

このページをすべて展開する

説明

HTTPOptions クラスは、HTTP 要求メッセージのオプションを作成するために使用します。このオブジェクトを使用して、複数の要求で一定のオプションを指定します。

作成

説明

obj = matlab.net.http.HTTPOptions は既定のプロパティ値で HTTP オプションを作成します。

例

obj = matlab.net.http.HTTPOptions(Name,Value) は 1 つ以上の名前と値のペアの引数で指定された追加のプロパティを使用して、HTTP オプションを作成します。Name はプロパティ名で、Value は対応する値です。Name1,Value1,...,NameN,ValueN のように、複数の名前と値のペアの引数を任意の順番で指定できます。未指定のプロパティは既定値に設定されます。

プロパティ

すべて展開する

認証に資格情報を使用するかどうか。true または false として指定します。

Authenticate が true の場合、サーバーまたはプロキシで要求される、サポートされる認証メソッドを実装します。認証は、MATLAB® Web 基本設定で Credentials プロパティとプロキシのユーザー名およびパスワードが設定されている場合、これに基づきます。MATLAB における認証のサポートの詳細については、サーバー認証を参照してください。

以下の条件のいずれかに該当する場合、応答メッセージにはサーバーまたはプロキシの認証チャレンジが含まれます。

  • Authenticate が false である。

  • この要求に適切な Credentials プロパティが見つからない。

  • 認証が失敗した。

属性:

GetAccess
public
SetAccess
public

データ型: logical

ファイル名。ルート証明書を含むファイルの名前と場所を示す 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

データ型: char | string

サーバーの初期接続までの待機時間 (秒)。非負の実数として指定します。プロキシを使用する場合、タイムアウトはプロキシへの接続に適用されます。それ以外の場合は、サーバーへの接続に適用されます。

既定値は 10 秒です。タイムアウト期間が超過すると ConnectTimeout がエラーをスローします。タイムアウトを無効にするには、ConnectTimeout を Inf に設定します。

ConnectTimeout は、エラーをスローする前にサーバーまたはプロキシへの接続試行が完了するまで待機する時間を決定します。このタイムアウトは、完全な応答を受信するまでの時間は制限しません。

プロキシ経由でサーバーに要求を送信する場合は、ResponseTimeout を使用して待機時間を制限することを検討してください。

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

属性:

GetAccess
public
SetAccess
public

ResponseMessage でサーバーから受信した生のペイロードを処理する方法。true または false として指定します。

ConvertResponse が true の場合

  • ContentConsumer が指定されると、さらに処理するために uint8 ペイロードが ContentConsumer に渡されます。

  • それ以外の場合、MATLAB は MessageBody.Payload プロパティのペイロードを、応答メッセージの Content-Type に基づいて MATLAB データに変換します。変換ルールについては、Data プロパティを参照してください。変換が正常に行われると、Data には変換されたデータが含まれ、Payload が空になります。

ConvertResponse が false の場合、指定された ContentConsumer は無視され、動作は Content-Type が文字データを指定するかどうかによって異なります。

  • Content-Type に明示的または既定の charset 属性が含まれる場合、ペイロードはテキストに変換され、これ以上処理されずに Data に格納されます。

  • Content-Type に文字データが指定されていない場合または charset が含まれない場合、MATLAB は Content-Type をサポートせず、Data に生の uint8 ペイロードが含まれます。

SavePayload プロパティも true に設定した場合を除き、すべての場合において Payload プロパティは削除されます。

メッセージがエンコード (圧縮) されて、次のいずれかだった場合、ConvertResponse は無視されます。

  • デコードが失敗した

  • DecodeResponse プロパティが false である

属性:

GetAccess
public
SetAccess
public

データ型: logical

ネットワーク上のデータ パケット間で待機する秒数。非負の実数として指定します。既定値は Inf で、タイムアウトなしを意味します。このタイムアウトは最初の接続の確立後に適用され、低速である可能性があるサーバーとの通信で役立ちます。次に予測されるパケットの送受信を待機している間にこのタイムアウトを超えた場合、MATLAB は接続を閉じてエラーをスローします。この場合、部分データを取得するには matlab.net.http.HTTPException の History プロパティを使用します。

属性:

GetAccess
public
SetAccess
public

圧縮データをデコードするかどうか。true または false として指定します。デコードとは、サーバーから圧縮 (エンコードされた) データが返されたときに応答ペイロードを解凍 (デコード) することです。デコードは、Content-Type フィールドに基づいて変換前に行われます。

応答は、圧縮アルゴリズムを指定する Content-Encoding フィールドがある場合にエンコードされます。MATLAB はコンテンツ コーディング値 gzip、x-gzip および deflate をサポートします。値 identity はエンコードがないことを意味します。これは Content-Encoding フィールドのないメッセージと等価です。MATLAB で Content-Encoding タイプがサポートされない場合、DecodeResponse が true であってもデコードは行われません。

DecodeResponse が false で、かつペイロードがエンコードされている場合、次のようになります。

  • MessageBody.Payload プロパティにエンコードされていない生のペイロードが含まれる。

  • MessageBody.Data プロパティが空のままになる。

  • ConvertResponse プロパティの設定にかかわらず、変換が行われない。

圧縮データを処理できない ContentConsumer を使用している場合は、ConvertResponse も false に設定してコンシューマーの使用を抑制しない限り、圧縮応答に対してこの値を false に設定しないでください。MATLAB が提供するコンシューマーで、FileConsumer と BinaryConsumer のみが圧縮データを処理できます。

属性:

GetAccess
public
SetAccess
public

データ型: logical

認証資格情報。1 つ以上の matlab.net.http.Credentials オブジェクトとして指定します。既定値は、既定の matlab.net.http.Credentials オブジェクトです。既定の Credentials オブジェクトを使用して、Windows 上で Kerberos、NTLM などのスキームによる認証を許可します。これらのスキームでは、ユーザー名またはパスワードを指定する必要がありません。

Credentials は、Authenticate プロパティが true の場合にのみ使用されます。認証を実行するには、少なくとも 1 つの Credentials オブジェクトを指定しなければなりません。Credentials を空に設定すると、認証は実行されません。

セッション中に同じサーバーに複数回アクセスする場合、パフォーマンスを最大限にするために各要求に同じ Credentials ベクトルまたは同じ HTTPOptions オブジェクトを指定します。Credentials には後続の認証を高速化するキャッシュされた情報が含まれます。

プロキシと共に使用する Credentials を指定し、それらの Credentials により [基本設定] ウィンドウの [Web の基本設定] で指定されている別のユーザー名とパスワードをオーバーライドする場合は、この HTTPOptions オブジェクトの ProxyURI プロパティにプロキシのホストとポートを指定するか、[基本設定] ウィンドウの [認証でプロキシを使用] オプションをオフにします。

属性:

GetAccess
public
SetAccess
public

最初の接続後にサーバー接続を開いたままにする秒数。0 または Inf として指定します。このプロパティを使用して、同一の接続で複数の連続メッセージを送信できます。Inf 値 (既定) は、サーバーが可能な限り接続を開いたままにする持続的な接続を有効にします。0 値は、各メッセージの後で接続を閉じます。その他の値はサポートされません。

KeepAliveTimeout プロパティは動作の成功に影響しません。MATLAB は、他のタイムアウトを超えない限り、サーバーからの予測された応答を取得するために常に十分に長い時間、接続を開いたままにします。ただし、0 値は、同じサーバーに多くの短いメッセージを送信するときのパフォーマンスに深刻な影響を与えることがあります。

属性:

GetAccess
public
SetAccess
public

リダイレクトの許容数。任意の要求に対して、整数として指定します。リダイレクトの既定数は 20 です。リダイレクトを無効にするには 0 に設定します。無制限のリダイレクトを許可するには Inf に設定します。

MaxRedirects が非ゼロの場合、各リダイレクト応答でサーバーから受信したクッキーは、リダイレクトされるメッセージにコピーされます。MaxRedirects の後、応答メッセージには次のリダイレクト メッセージが含まれます。

属性:

GetAccess
public
SetAccess
public

進行状況モニター ハンドラー。matlab.net.http.ProgressMonitor オブジェクトへの関数ハンドルとして指定します。UseProgressMonitor が true の場合、MATLAB は関数 ProgressMonitor を呼び出して転送の進行状況を報告します。UseProgressMonitor が false の場合、または ProgressMonitorFcn が空の場合、進行状況は報告されません。

属性:

GetAccess
public
SetAccess
public

データ型: function_handle

プロキシ サーバーのアドレス。matlab.net.URI オブジェクト、または host:port または //host:port 形式の string として指定します。

ProxyURI は UseProxy プロパティが true の場合にのみ使用されます。ProxyURI は、MATLAB Web 基本設定で指定されたプロキシと Windows システム設定で設定されたプロキシをオーバーライドします。

属性:

GetAccess
public
SetAccess
public

要求の最後のパケットを送信した後、サーバーからの初期応答 (ヘッダー) を受信するまで待機する秒数。非負の実数として指定します。既定値は Inf で、タイムアウトなしを意味します。このタイムアウトを超えた場合、MATLAB は接続を閉じてエラーをスローします。

プロキシ経由でサーバーに要求を送信するときに待機時間を制限するには、ResponseTimeout を使用します。これは、ConnectTimeout がプロキシ接続時間にのみ適用されるためです。

ResponseTimeout は、weboptions により設定される Timeout プロパティと等価です。

属性:

GetAccess
public
SetAccess
public

ペイロードを保存するかどうか。true または false として指定します。ペイロードはサーバーとの間で送受信された生のバイトで、MessageBody.Payload プロパティに保存されます。

要求メッセージでは、SavePayload を true に設定するとデータの変換後にペイロードが保存されます。応答メッセージでは、バイトは変換前に保存されます。

SavePayload はデバッグ ツールとして使用します。たとえば、サーバーが要求の本文を処理できない場合、あるいは応答の本文を MATLAB タイプに変換できない場合などです。ペイロードは少なくとも変換済みデータと同じサイズであるため、SavePayload を true に設定すると、膨大なメモリ容量を消費する可能性があります。

応答ペイロードを変換せずに取得するには、ConvertResponse プロパティを false に設定し、代わりに MessageBody.Data を読み取ります。

メッセージの処理中に HTTPException が発生すると、障害時点までに受信したペイロードは HTTPException.History(end).Response.Body.Payload にあります。

RequestMessage.Body が ContentProvider オブジェクトの場合、MATLAB はプロバイダーの変換されたデータを Body.Payload に保存します。

属性:

GetAccess
public
SetAccess
public

データ型: logical

進行状況を表示するかどうか。true または false として指定します。UseProgressMonitor を true に設定し、ProgressMonitorFcn プロパティで指定される関数を使用して転送の進行状況を報告します。

属性:

GetAccess
public
SetAccess
public

データ型: logical

プロキシを使用するかどうか。true または false として指定します。

UseProxy が true の場合、MATLAB は次のプロキシのうち最初に該当するものを選択します。

  • ProxyURI プロパティの値 (ある場合)。

  • MATLAB Web 基本設定で指定されたプロキシ (指定されている場合)。

  • システム設定で指定されたプロキシ (Windows のみ)。

次のいずれかが true の場合、すべての要求はプロキシなしで送信先 URI に直接送信されます。

  • UseProxy が false である。

  • UseProxy が true であるが、ProxyURI が空で、基本設定で設定されているプロキシがない。

UseProxy が true の場合、MATLAB はメッセージをプロキシへ自動的に迂回させます。

属性:

GetAccess
public
SetAccess
public

データ型: logical

サーバー名が証明書と一致するかどうか。true または false として指定します。

https プロトコルを使用したセキュリティで保護された接続では、MATLAB は証明書内のサーバー名が、要求された URI、または最後にリダイレクト要求された URI の Host プロパティと一致するかどうかを検証します。この検証により、対象のサーバーと通信していることが確認できます。サーバーの証明書が、サーバーへのアクセスに使用する URI と一致しない場合にこの検証を無効にするには、このプロパティを false に設定します。たとえば、IP アドレスまたは "localhost" を使用してサーバーにアクセスする場合や、対象のサーバーと直接通信している確信がある場合などです。

属性:

GetAccess
public
SetAccess
public

データ型: logical

例

すべて折りたたむ

接続タイムアウトを 20 秒に増やします。

変数 url で指定されたサーバーに送信される、変数 request で指定された要求メッセージの既定の接続タイムアウト オプションを変更します。

options = matlab.net.http.HTTPOptions('ConnectTimeout',20);
response = request.send(url,options);

バージョン履歴

R2016b で導入

参考

| | | | | |

トピック