HTTP Request 設定リファレンス

HTTP Request 操作の典型的な使用方法は、デフォルトの GET メソッドを使用した外部 HTTP サービスのコンシュームです。デフォルトでは、GET および OPTIONS メソッドは要求でペイロードを送信しないため、HTTP リクエストボディは空です。他のメッセージでは、リクエストボディとしてメッセージペイロードが送信されます。

要求の送信後、コネクタは応答を受信し、それをアプリケーションのフローの次の要素に渡します。

この要求操作には少なくともホスト URI の設定が必要で、これにはパスが含まれることがあります。この要求操作には次の認証種別を設定できます。

Basic (基本)
OAuth
NT LAN Manager (NTLM)
ダイジェスト

Mule メッセージと HTTP Request のマップ

デフォルトでは、HTTP Request 操作は Mule メッセージペイロードを HTTP リクエストボディとして送信しますが、これは DataWeave スクリプトまたは式を使用してカスタマイズできます。

カスタムパラメーターの追加

リクエストボディに加えて、以下を設定できます。

要求および応答のサイズ制限
ヘッダー
クエリパラメーター
URI パラメーター
複数ヘッダーまたはパラメーターのマップ

HTTP 要求および応答のサイズ制限

デフォルトでは、Mule によって HTTP 要求サイズ、応答サイズ、要求/応答ヘッダーサイズに異なる制限が定義されます。ただし、これらの最大値は wrapper.conf ファイルで対応するプロパティを変更することで変更できます。

最大許容値プロパティデフォルト値 (バイト)

最大許容値	プロパティ	デフォルト値 (バイト)
Request/Response Header Size (要求/応答ヘッダーサイズ)	`mule.http.headerSectionSize`	`8192`
Request Size (要求サイズ)	`org.glassfish.grizzly.nio.transport.TCPNIOTransport.max-receive-buffer-size`	`1048576` (1MB)
Response Size (応答サイズ)	`org.glassfish.grizzly.nio.transport.TCPNIOTransport.max-send-buffer-size`	`1048576` (1MB)

Request/Response Header Size (要求/応答ヘッダーサイズ)

mule.http.headerSectionSize

8192

Request Size (要求サイズ)

org.glassfish.grizzly.nio.transport.TCPNIOTransport.max-receive-buffer-size

1048576 (1MB)

Response Size (応答サイズ)

org.glassfish.grizzly.nio.transport.TCPNIOTransport.max-send-buffer-size

1048576 (1MB)

ヘッダー

[General (一般)] 設定の [Headers (ヘッダー)] を選択してヘッダーを要求に追加します。たとえば、ヘッダー名 HeaderName1 および HeaderName2 を追加し、ヘッダー値 HeaderValue1 および HeaderValue2 を追加します。 DataWeave 式を使用できます。たとえば、#[{'HeaderName1' : 'HeaderValue1', 'HeaderName2' : 'HeaderValue2'}] のようにします。

常に設定する一連のデフォルトヘッダーが存在する場合もあります。たとえば、x-csrf-token: Fetch のような認証ヘッダーを常に送信する場合があります。

設定レベルでデフォルトヘッダーを指定すると、要求のたびにそのヘッダーを指定する必要がなくなります。次に例を示します。

<http:request-config name="requestConfig">
    <http:request-connection host="localhost" port="8081" streamResponse="true" responseBufferSize="1024"/>
    <http:default-headers >
        <http:default-header key="x-csrf-token" value="Fetch" />
    </http:default-headers>
</http:request-config>

この設定を使用すると、実際の要求で指定したヘッダーと共にこのヘッダーがすべてのアウトバウンド要求に追加されます。

デフォルトヘッダーでは式も受け入れられるため、動的値を使用できます。次に例を示します。

<http:request-config name="requestConfig">
    <http:request-connection host="localhost" port="8081" streamResponse="true" responseBufferSize="1024"/>
    <http:default-headers >
        <http:default-header key="custom-role" value="#[vars.role]" />
    </http:default-headers>
</http:request-config>

この方法は役立ち、便利ですが、いくつかの重要な考慮事項があります。設定要素内で式を使用すると、動的設定が構成されます。動的設定のライフサイクルについてはここで説明されていませんが、簡単に言うと、コネクタを使用するたびに設定内のすべての式が評価され、異なる値セットごとに新しい設定インスタンスが作成および初期化されます。

つまり、HTTP Connector の特定の事例では、式で使用する可能性があるすべての値の範囲が確実に小さい場合にのみ、式を含むデフォルトヘッダーを使用することをお勧めします。また、評価ごとに異なる値が生成される可能性がある場合は、HTTP クライアントの複数のインスタンスが作成されてしまいます。これは、(クライアントの初期化で追加の作業が実行されるために) パフォーマンスに影響し、多くのリソースを消費します。このような場合は、デフォルトヘッダーを使用せずに、要求操作自体でヘッダーを指定することをお勧めします。

<http:request config-ref="requestConfig" method="#[attributes.method]" path="#[attributes.maskedRequestPath]">
	<http:headers>#[{'custom-role':vars.role}]</http:headers>
</http:request>

クエリパラメーター

[General (一般)] > [Request (要求)] > [Query Parameters (クエリパラメーター)] で、プラスアイコン (+) をクリックしてパラメーターを要求に追加します。パラメーターの名前と値を入力するか、DataWeave 式を使用して名前と値を定義します。

URI パラメーター

要求のパスにプレースホルダー (/customer/{customerId} など) を使用する場合は、URI パラメーターを設定します。URI パラメーターを設定するには、[Path (パス)] 項目にプレースホルダーを中括弧で囲んで入力します。[URI Parameters (URI パラメーター)] を選択し、[+] をクリックして名前と値を入力します。

たとえば、名前と値として customerId と 20 を入力します。

または、名前項目と値項目で DataWeave 式を使用します。

アプリケーションが実行されると、http://www.example.com/customer/20 への GET 要求が実行されます。

動的パラメーターおよびヘッダー

設計時に要求で何個のクエリパラメーターやヘッダーが必要かわからない場合、DataWeave と変数マップを使用して動的にパラメーターまたはヘッダーを要求に割り当てます。

たとえば、customMap という名前のマップ変数を作成し、DataWeave を使用して値のマップを割り当ててから、その変数を使用して要求のヘッダーをセットアップできます。

#[vars.customMap ++ {'HeaderName1' : 'HeaderValue1'}]

URI パラメーターを動的に設定するには、パラメーターのマップを返す DataWeave 式を使用します。次に例を示します。

[Path (パス)] を設定: /test/{p1}/{p2}
URI パラメーター名: p1 と p2
URI パラメーター値: #[vars.customMap]
要求の前に、p1 がすでに設定されていると想定: #[vars.customMap ++ {'p2': 'customer'}]

コネクタは要求ごとにパラメーターを解決し、要求で指定された順序に従って現在のメッセージのコンテキストで DataWeave 式を評価します。同じパラメーターが複数回定義されている場合、最新の値が使用されます。

POST 要求での form (フォーム) パラメーターの送信

POST 要求でパラメーターを送信するには、[General (一般)] > [Request (要求)] で、POST メソッドを選択します。 [Body (本文)] で、Mule メッセージのペイロードを、送信するパラメーターの名前と値を指定した application/x-www-form-urlencoded として作成します。次に例を示します。

#[output application/x-www-form-urlencoded --- {'key1':'value1', 'key2':'value2'}]

POST 要求が Content-Type: application/x-www-form-urlencoded で指定したホストの場所に送信されます。本文は「key1=value1&key2=value2」です。

HTTP 応答と Mule メッセージのマップ

HTTP 応答は、HTTP 要求が Mule メッセージにマップされるのと似た方法で、Mule メッセージにマップされます。

次の要素は HTTP 応答に適用されません。

クエリパラメーター
URI パラメーター
HTTP 要求 URI に関連するインバウンド属性

さらに、HTTP Request 操作では、応答受信時に次の属性が Mule メッセージに追加されます。

attributes.statusCode: HTTP 応答の状況コード
attributes.reasonPhrase: HTTP 応答の理由を示す語句

ラウンドロビン方式の要求

この要求操作は、設定されたホストにラウンドロビン DNS を使用して接続します。Mule Runtime Engine は、指定されたホストに関連付けられているすべての IP アドレスを解決し、要求をすべての返された IP 間に分散することで負荷分散を行います。

認証が必要なリソースに接続するとき、外部サービスはサービスのホスト下の IP アドレス間でセッション情報を複製する必要があります。そうしないと、要求が認証されずに拒否される可能性があります。

Mule Runtime 開始時にサービスホスト名を mule.http.disableRoundRobin システムプロパティに追加するために必要なセッション維持を外部リソースが処理しない場合は、次のようにします。

./mule -M-Dmule.http.disableRoundRobin=serverhostname.com

この設定により、要求は、設定されたホストに接続するときにラウンドロビン DNS を使用しません。

HTTP 応答の検証

HTTP Request 操作は、HTTP 応答を受信すると状況コードで応答を検証します。デフォルトでは、状況コードが 400 以上の場合はエラーをスローします。そのため、サーバーが 404 (リソースが見つかりません) や 500 (内部サーバーエラー) を返した場合、失敗となり、エラー処理がトリガーされます。

HTTP 要求コール中に例外がスローされたときに HTTP レスポンス本文の詳細な概要を確認するには、Mule エラードキュメントで次の例を確認してください。

[General (一般)] > [Response (応答)] > [Response Validator (応答検証)] を設定して、有効な HTTP 応答コードのセットを変更できます。

注意: コネクタはデフォルトの検証を使用します。この検証は、状況コードが 400 以上の場合はエラーをスローします。
Success Status Code Validator (成功状況コード検証): この要素内に定義されているすべての状況コードは有効とみなされます。その他の状況コードの場合、要求はエラーをスローします。
Failure Status Code Validator (失敗状況コード検証): この要素内に定義されているすべての状況コードは無効とみなされ、エラーがスローされます。その他の状況コードの場合、要求は有効とみなされます。

成功応答として受け入れ可能な状況コードを設定するには、[General (一般)] > [Response (応答)] > [Response Validator (応答検証)] で、[Success Status Code Validator (成功状況コード検証)] を選択します。 [Values (値)] に、受け入れ可能な状況コードのカンマ区切りリストを入力します。例: 200,201。 HTTP 応答の状況コードがそれ以外の場合、失敗となり、エラーが発生します。

失敗状況コードの範囲は、2 つの ASCII ピリオド文字 (..) で定義されます。500 ～ 599 の値は失敗とみなされ、エラーが発生します。HTTP 応答の状況コードがそれ以外の場合、成功とみなされます。

対象の設定

デフォルトでは、リクエストボディは受信 Mule メッセージの [payload] から取得され、応答は出力 Mule メッセージの [payload] として次へ送信されます。このデフォルトの動作は、[General (一般)] > [Request (要求)] > [Body (本文)] および [General (一般)] > [Output (出力)] > [Target Variable (対象変数)] 属性で変更できます。この属性を使用して、出力データの場所をペイロード以外 (変数など) に指定できます。

要求ストリーミングの設定

デフォルトでは、ペイロードの種別がストリームの場合、ストリーミングを使用して要求が送信されます。このデフォルトの動作を変更できます。[General (一般)] > [Request (要求)] > [Request Streaming (要求ストリーミング)] で次のいずれかの値を選択します。

AUTO (自動) (デフォルト): 動作はペイロード種別に応じて異なります。ストリーミングは、ペイロードが InputStream の場合は有効になり、それ以外の場合は無効になります。
ALWAYS (常時): ペイロード種別に関係なく常にストリーミングが有効になります。
NEVER (なし): ペイロードがストリームの場合も含め、ストリーミングしません。

ストリーミングの場合、要求には Content-Length ヘッダーが含まれません。含まれるのは Transfer-Encoding ヘッダーで、本文はストリーミングが完全にコンシュームされるまでチャンクで送信されます。

応答ストリーミングの設定

大きなペイロードを要求する場合、HTTP 要求設定で streamResponse 属性を設定することで、応答をストリーミングするように選択できます。

デフォルトでは、streamResponse 属性は false に設定されています。この属性を true に設定すると、Mule がチャンクをメモリ内バッファに保存して、応答をストリームとして処理できるようになります。バッファサイズは responseBufferSize 属性を使用して設定できますが、デフォルトサイズは 10 KB です。

<http:request-config name="requestConfig">
    <http:request-connection host="localhost" port="8081" streamResponse="true" responseBufferSize="1024"/>
</http:request-config>

問題を回避するには、ストリーミング時に応答をコンシュームすることが重要です。

再試行メカニズム

HTTP Connector では、外部 HTTP サービスのコンシュームの試行回数を設定できる再試行メカニズムが使用されます。HTTP Connector はこのメカニズムを使用して HTTP クライアントを HTTP サービスに再接続します。HTTP Connector では TCP 接続が管理されないため、このメカニズムでソケットは再接続されません。

HTTP Request 操作では、再試行のために再接続戦略は使用しません。再接続戦略は、ConnectionException がキャッチされた場合に Mule SDK で接続を再確立するために使用するメカニズムです。これは、HTTP リクエスターにより作成された HTTP サービスへの接続には影響しません。接続についての詳細は、接続のドキュメントを参照してください。

HTTP リクエスターが外部 HTTP サービスのコンシュームを試行できる回数 (再試行回数) を設定するには、Until Successful スコープか、リクエスターの組み込み再試行メカニズムを使用できます。

Until Successful スコープ
Until Successful スコープは、内部のコンポーネントが成功するか、または最大再試行回数に達するまで、内部のコンポーネントを順番に処理します。次のように、このスコープで HTTP リクエスターを囲むと、最大再試行回数 maxRetries とその間隔 millisBetweenRetries を設定できます。

<until-successful maxRetries="5" millisBetweenRetries="10000">
    <http:request method="GET" config-ref="requestConfig" />
</until-successful>

スコープについての詳細は、「Until Successful スコープ」を参照してください。

組み込みメカニズム
HTTP リクエスターは、Remotely Closed 種別のエラーを受信すると、デフォルトで冪等性メソッド PUT、DELETE、GET、HEAD、OPTIONS、TRACE を失敗するまで自動的に 3 回再試行します。
そのため、このメカニズムで 2 つのシステムプロパティを設定できます。
- -M-Dmule.http.client.maxRetries=5
  このシステムプロパティでは、HTTP リクエスターが失敗するまでの再試行回数を設定できます。また、その値を 0 に設定して、組み込みメカニズムを使用しないようにすることもできます。
- -M-Dmule.http.client.retryOnAllMethods=true
  このシステムプロパティを使用すると、組み込みメカニズムが冪等性メソッドだけでなくすべてのメソッドに拡張されます。

これらのプロパティについての詳細は、「システムプロパティ」を参照してください。POST などの非冪等性メソッドがデフォルトで再試行されない理由については、RFC 7230 を参照してください。

ガートナーが MuleSoft をリーダーとして評価

Salesforce のフルパワーを解放する API 活用術

Anypoint Platform：開発基礎 (無料)

MuleSoft Forum Japan