ドキュメンテーション

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

send

クラス: matlab.net.http.RequestMessage
パッケージ: matlab.net.http

HTTP 要求メッセージの送信と応答の受信

説明

[response,completedrequest,history] = send(request,uri)request メッセージを uri で指定された Web サービスに送信し、response がある場合はこれを返します。request.Method プロパティが指定されていない場合、send メソッドはプロパティを 'GET' に設定します。

既定では、send はメッセージのヘッダーと他の部分のセマンティクスの正確性を検証し、uri を完了します。また、メソッドは正しい形式の要求になるように必要なヘッダー フィールドを埋めます。request.BodyMessageBody であり、その Payload プロパティがまだ設定されていない場合、MessageBody.Data の説明と同じように、send は適切な変換関数を呼び出して任意の request.Body.Data を送信対象の HTTP ペイロードを表すバイト ベクトルに変換します。通常、'GET' 要求にデータは含まれませんが、RequestMethod に関係なくメソッドは Body を送信します。サーバーがその応答でデータを返し、consumer が指定されない場合、send はそのデータを MATLAB® データに変換し、response.Body.Data に保存します。データ変換の詳細については、MessageBody.Data を参照してください。

request.BodyContentProvider の場合、MATLAB は送信対象のデータを取得するためにプロバイダーを呼び出します。

ヘッダーにメソッドが通常追加するフィールドが既に含まれている場合、send はフィールドに期待値があることを検証します。既定の動作を以下のようにオーバーライドできます。

  • 何も確認せずにそのまま、またはヘッダーを変更してメッセージを送信するには、request.Completed 送信前にプロパティを true に設定します。complete メソッドを使用して要求を完了した場合は、complete に指定した urioptions と同じ値を指定しなければなりません。そうしないと、予測できない結果が生じる可能性があります。Completed が設定されている場合でも、RequestLine 内の未指定のフィールドは既定値で埋められます。

  • send メソッドでヘッダーをチェックして変更できるようにしても、send または ContentProvider によって追加される可能性がある特定のヘッダー フィールドの追加を抑制するには、そのフィールドを空の値 ([]) とともに request.Header に追加します。たとえば、send によって User-Agent ヘッダー フィールドが自動的に追加されます。この動作を希望しない場合は、ヘッダーに HeaderField('User-Agent') を追加してください。空の値をもつヘッダー フィールドはメッセージに含まれません。Host フィールドと Connection フィールドを抑制することはできません。

  • 与えられたヘッダー フィールドに send メソッドが追加する値をオーバーライドするには、メッセージを送信または完了する前に、そのフィールドのユーザー独自のインスタンスを追加します。ただし、ContentProvider によって追加される可能性があるヘッダー フィールドはこれによってオーバーライドされません。しかし、ヘッダー フィールドのタイプによっては、値が有効でない場合に send でメッセージが拒否される可能性もあります。特定のフィールド値のチェックを妨げたり、ContentProvider によって追加されるフィールドをオーバーライドするには、目的の名前と値をもつヘッダーに matlab.http.field.GenericField のフィールド タイプを追加します。send または ContentProvider のどちらも、GenericField ヘッダーと同じ名前をもつどのヘッダー フィールドも追加しません。また、その正確性もチェックしません。

  • 変換せずに生のバイナリ データを送信するために、uint8 ベクトルを Body.Data または Body.Payload のいずれかに挿入できます。唯一の違いは、Body.Data 内のデータがメッセージ内の Content-Type フィールドを基準に変換される一方、Body.Payload はそうではない点です。Body.Payload が空の場合、Completed が既に設定されていても、send は常に空でない Body.Data を変換しようとします。変換ルールの詳細については、MessageBody.Data を参照してください。

[response,completedrequest,history] = send(request,uri,options,consumer) は、request メッセージと response メッセージの処理に関する追加オプションを提供します。

入力引数

すべて展開する

要求メッセージ。matlab.net.http.RequestMessage オブジェクトとして指定します。

メッセージの送信先。matlab.net.URI オブジェクト、またはコンストラクターで受け入れ可能な string または文字ベクトルとして指定します。値が URI オブジェクトの場合、Host という名前を付けなければなりません。これが文字列であり、Scheme を含まない場合、'http' が想定されます。たとえば、'www.somewebsite.com''//www.somewebsite.com' はどちらも 'http://www.somewebsite.com' として扱われます。

要求メッセージと応答メッセージを処理するための追加オプション。matlab.net.http.HTTPOptions オブジェクトとして指定します。指定しない場合または値が空の場合、send は既定のオプションを使用します。

返されるペイロードを処理するコンテンツ コンシューマー。matlab.net.http.io.ContentConsumer オブジェクトまたは ContentConsumer を返す関数へのハンドルとして指定します。

send メソッドは、データのバッファーを処理または保存するために、データが受信される際に ContentConsumer をリアルタイムで呼び出します。consumer は他の方法でデータを response.Body.Data またはハンドルに保存できます。たとえば、コンシューマーはデータを Figure ウィンドウに表示したりファイルに保存したりできます。コンシューマーが指定されると、MATLAB は自動的に MessageBody.Data を設定しませんが、options.SavePayload が true の場合、MessageBody.Payload を未変換のペイロードに設定します。たとえば、FileConsumer はデータを MessageBody.Data ではなくファイルに保存します。

ContentConsumer を使用すると、MATLAB 既定の応答データ変換よりも柔軟に応答データを変換または保存できるようになります。受信データに対する既定の変換の詳細については、MessageBody.Data を参照してください。MATLAB が提供する ContentConsumer タイプのリストについては、以下を入力します。

mp = ?matlab.net.http.io.ContentConsumer;
{mp.ContainingPackage.ClassList.Name}'

また、ソフトウェア開発者は、受信中のデータを処理するために独自の ContentConsumer サブクラスを作成できます。

consumer は、response 内の Content-Type ヘッダーや、response.StatusCodeOK かどうかなどのさまざまな要因に基づいて、メッセージを受け入れる場合にのみ使用します。各 consumer にはメッセージを受け入れるための独自の条件があります。

サポートされているエンコードでペイロードが圧縮されていて、options が指定されていないか、options.DecodePayload が true の場合、コンシューマーは圧縮解除されたデータを取得します。ペイロードが圧縮されていて options.DecodePayload が false であるか、ペイロードがサポートされていないエンコードで圧縮されている場合、コンシューマーは使用されず、データの既定の処理はありません。

コンシューマーが使用されないすべてのケースにおいて、consumer が指定されていないかのようにペイロードは処理されて変換されます。

consumer が関数ハンドルである場合、コンシューマーをインスタンス化するために関数が呼び出されるのは、応答にペイロードがあることが MATLAB で判別された後のみです。

consumer を指定しても options を指定しない場合、options 用にプレースホルダー [] 引数を追加して、既定のオプションを使用します。

出力引数

すべて展開する

サーバーから受信したメッセージ。matlab.net.http.ResponseMessage オブジェクトとして返されます。リダイレクトや認証が発生する場合に MATLAB とプロキシまたはサーバー間で中間要求と中間応答が交換される場合があります。

response 引数を受信する前に送信された要求。matlab.net.http.RequestMessage オブジェクトとして返されます。send メソッドは、認証情報またはリダイレクト情報で completedrequest 引数を増補します。

request.BodyContentProvider の場合、ContentProvider ペイロードは保存されないため、completedrequest.Body は通常、空です。ただし、options.SavePayload が true の場合、completedrequest.BodyMessageBody であり、その Payload にはプロバイダーから送信された uint8 ベクトルとしてのデータがあります。場合によっては、要求の Content-Type が文字ベースであることを示すときに、MessageBody.Data プロパティに string で表されるペイロードが含まれることがあります。

HTTP 要求の送信後、completedrequest 引数を調べて送信された内容を確認します。サーバーは、リダイレクトや認証の交換が発生した場合などに、複数のメッセージを送信することがあります。複数のメッセージがある場合、completedrequest には最後の要求が含まれます。最初または中間のメッセージを表示するには history 引数を確認します。

同じ要求を複数回送信するには RequestMessage.complete メソッドを呼び出します。

[completedrequest,target] = complete(request,uri)

次に、これらの出力引数で send メソッドを呼び出します。

resp = send(completedrequest,target)

メッセージのログ。この send 要求を満たすために交換された matlab.net.http.LogRecord オブジェクトのベクトルとして返されます。1 つの要求と応答がある場合、history 引数には 1 つのレコードが含まれます。認証に複数のメッセージが含まれる場合、履歴にはリダイレクトごとの複数のログ レコードを含めることができます。

履歴は、応答メッセージからすべての Set-Cookie ヘッダーを取得するために使用します。これらのヘッダーを後続の要求でサーバーに送り返すことができます。

履歴の最後のレコード には、Body プロパティを除き、completedrequest 引数および response 引数と同じ プロパティが含まれます。メッセージ本文のログを作成するには、options 引数で SavePayload プロパティを指定します。

履歴はデバッグでも役に立ちます。

すべて展開する

MathWorks サポートへのお問い合わせの Web ページを読み取る HTTP メッセージを送信し 、メッセージのステータス コードを表示します。

import matlab.net.*
import matlab.net.http.*
r = RequestMessage;
uri = URI('https://www.mathworks.com/support/contact_us');
resp = send(r,uri);
status = resp.StatusCode
status = 

    OK

mathworks.com Web サイトからのメッセージをリダイレクトしないようにするには、HTTP オプション MaxRedirects をゼロに設定します。次にステータス コードの情報を表示します。

import matlab.net.*
import matlab.net.http.*
r = RequestMessage;
uri = URI('https://www.mathworks.com/support/contact_us');
options = HTTPOptions('MaxRedirects',0);
[resp,~,hist] = send(r,uri,options);
status = getReasonPhrase(resp.StatusCode)
status =

    'Moved Permanently'

エラー処理

要求が受け入れられたかどうかを判別するために、常に response Status プロパティをチェックします。エラー条件は、次のとおりです。

  • MException — メッセージが適切な形式ではなく、完了できない。

  • HTTPException — メッセージは完了したが、Web サービスが到達不能、または options で指定されたタイムアウト期間内に応答しない。

  • responseStatus プロパティ — Web サービスが応答して HTTP エラー ステータスを返す。send は正常に戻り、Status プロパティをサーバーから返されたエラーに設定する。

R2016b で導入