send

クラス: matlab.net.http.RequestMessage
名前空間: matlab.net.http

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

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

構文

[response,completedrequest,history] = send(request,uri)
[response,completedrequest,history] = send(request,uri,options,consumer)

説明

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

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

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

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

  • 何も確認せずにそのまま、またはヘッダーを変更してメッセージを送信するには、request.Completed 送信前にプロパティを true に設定します。complete メソッドを使用して要求を完了した場合は、complete に指定した uri と options と同じ値を指定しなければなりません。そうしないと、予測できない結果が生じる可能性があります。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.StatusCode が OK かどうかなどのさまざまな要因に基づいて、メッセージを受け入れる場合にのみ使用します。各 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.Body が ContentProvider の場合、ContentProvider ペイロードは保存されないため、completedrequest.Body は通常、空です。ただし、options.SavePayload が true の場合、completedrequest.Body は MessageBody であり、その 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 で指定されたタイムアウト期間内に応答しない。

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

バージョン履歴

R2016b で導入

参考

| | | | | | |