HTTP Connector の使用の移行

Mule 4.1 の標準サポートは 2020 年 11 月 2 日に終了しました。このバージョンの Mule は、拡張サポートが終了する 2022 年 11 月 2 日にその すべてのサポート​が終了しました。

このバージョンの Mule を使用する CloudHub には新しいアプリケーションをデプロイできなくなります。許可されるのはアプリケーションへのインプレース更新のみになります。

標準サポートが適用されている最新バージョンの Mule 4 にアップグレード​することをお勧めします。これにより、最新の修正とセキュリティ機能強化を備えたアプリケーションが実行されます。

HTTP Connector のほとんどの部分は、Mule 4 モデルに適合されています。

  • 設定プロパティは接続コンポーネントに移行されています (可能な場合)。

  • メッセージプロセッサは、適切な操作にリファクタリングされています。

  • アウトバウンドプロパティ (​http.status​ など) は排除され、明示的なプロパティになりました。

  • インバウンドプロパティ (​http.queryParams​ など) も排除され、HTTP 固有のメッセージ属性になりました。

  • スレッドがすべて Mule Runtime レベルで処理されるようになったため、スレッド設定も排除されています。

  • application/x-www-form-urlencoded​ と ​multipart/*​ のメディア種別の特別処理が排除され、DataWeave になりました。

  • RAML メタデータのサポートが HTTP 要求操作から排除され、REST になりました。

HTTP リスナ

HTTP リスナは、応答ビルダーの設定と、設定プロパティの特定の接続コンポーネントへのカプセル化にのみ大きな変更が行われています。

Configuration (設定)

次のプロパティやコンポーネントは、内部の ​http:listener-connection​ コンポーネントで定義することになりました。

  • host

  • port

  • protocol

  • usePersistentConnections

  • connectionIdleTimeout

  • TLS Context

Mule 3 の例
<http:listener-config name="listenerConfig" host="localhost" port="8081" basePath="api/v2" protocol="HTTPS">
  <tls:context>
    <tls:trust-store path="cacerts.jks" password="changeit"/>
    <tls:key-store path="keystore.jks" keyPassword="changeit" password="changeit"/>
  </tls:context>
</http:listener-config>
Mule 4 の例
<http:listener-config name="listenerConfig" basePath="api/v2">
  <http:listener-connection host="localhost" port="8081" protocol="HTTPS">
    <tls:context>
        <tls:trust-store path="cacerts.jks" password="changeit"/>
        <tls:key-store path="keystore.jks" keyPassword="changeit" password="changeit"/>
    </tls:context>
  </http:listener-connection>
</http:listener-config>

リスナ

HTTP リスナのプロパティは、​http:response-builder​ と ​http:error-response-builder​ を除いて同じままです。. これらは名前が ​http:response​ と ​http:error-response​ に変更されたほか、アウトバウンドプロパティの暗黙的な処理へのサポートが排除され、ヘッダーを 1 つの式で定義することになりました。さらに、発信 HTTP メッセージ本文を 1 つの式で定義できる、新しい ​http:body​ コンポーネントをサポートします。

Mule 3 の例

次の例では、暗黙的なアウトバウンドプロパティ (​Mule 3.6.0​)、1 つのヘッダー参照 (​Mule 3.7.0​)、式参照 (​Mule 3.8.0​、​Mule 3.9.0​) を使用してセットアップされた応答で多数の ​User-Agent​ ヘッダーが送信されます。他方、エラー応答は ​Date​ ヘッダーと、​User-Agent​ のアウトバウンドプロパティを特長とします。

<flow name="listener">
  <http:listener config-ref="listenerConfig" path="/">
    <http:response-builder statusCode="201" reasonPhrase="everything works!">
      <http:header headerName="User-Agent" value="Mule 3.7.0"/>
      <http:headers expression="['User-Agent': ['Mule 3.8.0', 'Mule 3.9.0']]"/>
    </http:response-builder>
    <http:error-response-builder statusCode="500" reasonPhrase="something went wrong">
      <http:header headerName="Date" value="#[server.dateTime]"/>
    </http:error-response-builder>
  </http:listener>
  ...
  <set-property propertyName="User-Agent" value="Mule 3.6.0"/>
</flow>
Mule 4 の例

statusCode​ と ​reasonPhrase​ プロパティは同じままですが、すべてのヘッダーが DataWeave 式を使用して明示的に追加されるようになりました。注意すべき重要な点は、アウトバウンドプロパティの ​http.status​ と ​http.reason​ を使用する代わりに、明示的な ​statusCode​ と​reasonPhrase​ も指定する必要があることです。

<flow name="listener">
  <http:listener config-ref="listenerConfig" path="/">
    <http:response statusCode="201" reasonPhrase="everything works!">
      <http:headers>
        #[{
          'User-Agent' : 'Mule 3.6.0',
          'User-Agent' : 'Mule 3.7.0',
          'User-Agent' : 'Mule 3.8.0',
          'User-Agent' : 'Mule 3.9.0'
          }]
      </http:headers>
    </http:response>
    <http:error-response statusCode="500" reasonPhrase="something went wrong">
      <http:headers>
        #[{
          'User-Agent': 'Mule 3.6.0',
          'Date': now()
        }]
      </http:headers>
    </http:error-response>
  </http:listener>
  ...
</flow>

属性

HTTP リスナは、Mule の新しいメッセージ構造に従って、すべての要求メタデータを特定の HTTP 要求属性を介して提供するようになりました。以下は、Mule 3 とは異なるやり方で、メタデータにアクセスする新しい方法を示しています。

メタデータ Mule 3 Mule 4

メソッド

#[inboundProperties.'http.method']

#[attributes.method]

パス

#[inboundProperties.'http.listener.path']

#[attributes.listenerPath]

相対パス

#[inboundProperties.'http.relative.path']

#[attributes.relativePath]

要求 URI

#[inboundProperties.'http.request.uri']

#[attributes.requestUri]

クエリ文字列

#[inboundProperties.'http.query.string']

#[attributes.queryString]

クエリパラメータ

#[inboundProperties.'http.query.params']

#[attributes.queryParams]

URI パラメータ

#[inboundProperties.'http.uri.params']

#[attributes.uriParams]

バージョン

#[inboundProperties.'http.version']

#[attributes.version]

スキーマ

#[inboundProperties.'http.scheme']

#[attributes.scheme]

ヘッダー

#[inboundProperties]

#[attributes.headers]

リモートアドレス

#[inboundProperties.'http.remote.address']

#[attributes.remoteAddress]

クライアント証明書

#[inboundProperties.'http.client.cert']

#[attributes.clientCertificate]

HTTP ヘッダーはインバウンドプロパティに直接マップされていましたが、専用オブジェクトが導入されました。以下は、ヘッダーを取得する方法の例を示しています。

  • Mule 3: #[inboundProperties.'host']

  • Mule 4: #[attributes.headers.'host']

HTTP 要求

HTTP リスナと同様、HTTP 要求操作の変更の大半は、設定プロパティの接続コンポーネント内へのカプセル化と、要求作成プロセスに関連しています。

Configuration (設定)

次のプロパティやコンポーネントは、内部の ​http:request-connection​ コンポーネントで定義することになりました。

  • host

  • port

  • protocol

  • usePersistentConnections

  • maxConnections

  • connectionIdleTimeout

  • streamResponse

  • responseBufferSize

  • HTTP Authentication

  • HTTP Proxy

  • TLS Context

  • TCP クライアントソケットのプロパティ

Mule 3 の例
<http:request-config name="requestConfig" host="localhost" port="8081" protocol="HTTPS" enableCookies="false">
  <tls:context>
    <tls:trust-store path="trustStore" password="changeit"/>
    <tls:key-store path="clientKeystore" keyPassword="changeit" password="changeit"/>
  </tls:context>
</http:request-config>
Mule 4 の例
<http:request-config name="requestConfig" enableCookies="false">
  <http:request-connection host="localhost" port="8081" protocol="HTTPS">
    <tls:context>
      <tls:trust-store path="trustStore" password="changeit"/>
      <tls:key-store path="clientKeystore" keyPassword="changeit" password="changeit"/>
    </tls:context>
  </http:request-connection>
</http:request-config>

RAML メタデータのサポートは排除されました。REST Connect で、指定した RAML の特定の再利用可能なコネクタを生成できるようになったためです。

HTTP Authentication

HTTP 認証設定が ​http:request-connection​ コンポーネントの一部になったほか、​http:authentication​ コンポーネント内にも配置する必要があります。 この変更は、サポートされている全種類の認証 (基本、ダイジェスト、NTLM、OAuth2) に適用されます。

Mule 3 の例
<http:request-config name="basicConfig" host="localhost" port="8081">
  <http:basic-authentication username="#[flowVars.user]" password="#[flowVars.password]" preemptive="#[flowVars.preemptive]" />
</http:request-config>
Mule 4 の例
<http:request-config name="basicConfig">
  <http:request-connection host="localhost" port="8081">
    <http:authentication>
      <http:basic-authentication username="#[vars.user]" password="#[vars.password]" preemptive="#[vars.preemptive]" />
    </http:authentication>
  </http:request-connection>
</http:request-config>

HTTP Proxy

HTTP Authentication コンポーネントと同様に、HTTP プロキシを設定する場合、あらゆる種類のプロキシにラッピング ​http:proxy-config​ コンポーネントが必要になりました。

Mule 3 の例
<http:request-config name="proxyConfig" host="localhost" port="8081" basePath="basePath">
  <http:proxy host="localhost" port="8082" username="cniehaus" password="324B21" />
</http:request-config>
Mule 4 の例
<http:request-config name="proxyConfig" basePath="basePath">
  <http:request-connection host="localhost" port="8081">
    <http:proxy-config>
      <http:proxy host="localhost" port="8082" username="cniehaus" password="324B21" />
    </http:proxy-config>
  </http:request-connection>
</http:request-config>

TCP クライアントソケットのプロパティ

Mule 3 では、TCP クライアントソケットのプロパティが TCP トランスポートに基づいて定義されていました。Mule 4 ではこのトランスポートがソケットコネクタになったため、プロパティを設定する必要があります。また、これらのプロパティは ​http:client-socket-properties​ コンポーネントでラップする必要があります。

Mule 3 の例
<http:request-config name="tcpConfig" host="localhost" port="8081" >
    <tcp:client-socket-properties connectionTimeout="1000" keepAlive="true"
                                  receiveBufferSize="1024" sendBufferSize="1024"
                                  sendTcpNoDelay="true" timeout="1000" linger="1000" />
</http:request-config>
Mule 4 の例
<http:request-config name="tcpConfig">
  <http:request-connection host="localhost" port="8081">
    <http:client-socket-properties>
        <sockets:tcp-client-socket-properties connectionTimeout="1000" keepAlive="true"
                                              receiveBufferSize="1024" sendBufferSize="1024"
                                              sendTcpNoDelay="true" clientTimeout="1000" linger="1000" />
    </http:client-socket-properties>
  </http:request-connection>
</http:request-config>

要求

HTTP 要求のプロパティは、​source​ (式と変換をサポートする ​http:body​ コンポーネントに置き換え) と ​http:request-builder​ (削除済み) を除いて同じままです。ヘッダー、クエリ、URI のパラメータは DataWeave 式で明示的に定義するようになりました。

Mule 3 の例
<flow name="request">
  ...
  <set-property propertyName="Host" value="www.example.com"/>
  <http:request config-ref="requestConfig" path="song/{id}" method="GET" source="#[flowVars.customSource]">
    <http:request-builder>
      <http:header headerName="Transfer-Encoding" value="chunked" />
      <http:uri-param paramName="id" value="#[flowVars.songId]" />
      <http:query-params expression="#[flowVars.params]" />
    </http:request-builder>
  </http:request>
  ...
</flow>
Mule 4 の例
<flow name="request">
  ...
  <http:request config-ref="requestConfig" path="song/{id}" method="GET">
    <http:body>
      #[vars.customSource]
    </http:body>
    <http:headers>
      #[{
        'Host': 'www.example.com'
        'Transfer-Encoding' : 'chunked'
      }]
    </http:headers>
    <http:uri-params>
      #[{ 'id' : vars.songId }]
    </http:uri-params>
    <http:query-params>
      #[vars.params]
    </http:query-params>
  </http:request>
  ...
</flow>

属性

HTTP 要求も HTTP リスナと同様に、すべての応答メタデータを特定の HTTP 応答属性を介して提供するようになりました。以下は、Mule 3 とは異なるやり方で、メタデータにアクセスする新しい方法を示しています。

メタデータ Mule 3 Mule 4

状況コード

#[inboundProperties.'http.status']

#[attributes.statusCode]

理由を示す語句

#[inboundProperties.'http.reason']

#[attributes.reasonPhrase]

ヘッダー

#[inboundProperties]

#[attributes.headers]

ヘッダーが HTTP リスナの場合と同じように処理されています。

HTTP 静的リソースハンドラ

HTTP 静的リソースハンドラが、Mule 4 の操作モデルに適合され、​http:load-static-resource​ という名前に変更されました。. resourceBase​ プロパティも ​resourceBasePath​ という名前に変更されています。

Mule 3 の例
<flow name="main-http-root">
  <http:listener config-ref="listenerConfig" path="*"/>
  <http:static-resource-handler resourceBase="site" defaultFile="index.html"/>
</flow>
Mule 4 の例
<flow name="main-http-root">
  <http:listener config-ref="listenerConfig" path="*"/>
  <http:load-static-resource resourceBasePath="site" defaultFile="index.html" />
</flow>

この操作は HTTP リスナ取得元と併用することのみを意図していますが、リスナの HTTP 要求属性を参照して、この操作をフローのどの時点でも使用できるようにする ​attributes​ プロパティも導入されています。

HTTP 基本セキュリティ検索条件

HTTP 基本セキュリティ検索条件は、DataWeave を ​securityProviders​ プロパティの取得元としてサポートすることと、リスナの HTTP 要求属性を参照して、この操作をフローのどの時点でも使用できるようにする ​attributes​ プロパティを導入したこと以外は変更されていません (HTTP load static resource 操作と同じです)。

Mule 3 の例
<flow name="listenerBasicAuth">
  <http:listener config-ref="listenerConfigBasicAuth" path="/basic" />
  <http:basic-security-filter realm="mule-realm" securityProviders="provider1,provider2"/>
  <set-payload value="Ok"/>
</flow>
Mule 4 の例
<flow name="listenerBasicAuth">
  <http:listener config-ref="listenerConfigBasicAuth" path="/basic"/>
  <http:basic-security-filter realm="mule-realm" securityProviders="#['provider1', 'provider2']"/>
  <set-payload value="Ok"/>
</flow>

完全な設定例については、​「Spring セキュリティの LDAP プロバイダの設定」​を参照してください。

HTTP MIME タイプ解析

Mule 3 の HTTP Connector の特長は、​application/x-www-form-urlencoded​ や ​multipart/form-data​ タイプ (および他のサブタイプ) の本文を受信したときに、要求や応答を解析するオプションがあることでした。アウトバウンド要求や応答に解析対象のオブジェクトがあると、一貫性を維持する目的でこうしたタイプの本文に戻されていました。 他方、DataWeave 2.0 でこれらの MIME タイプが処理されるようになったため、Mule 4 では HTTP 解析が排除され、HTTP コンポーネントは常にバイナリデータストリームを提供し、また必要とするようになっています。 解析対象であったタイプの使用を移行する方法については、以下を参照してください。

application/x-www-form-urlencoded

Mule 3 では、​Map​ ペイロードを ​application/x-www-form-urlencoded​ コンテンツと同様に使用できました。アウトバウンドトラフィックの場合、​Map​ ペイロードが存在すれば、各キー - 値ペアを使用して ​application/x-www-form-urlencoded​ 本文が生成されることを意味しました。インバウンドトラフィックの場合は、その本文の各キー - 値ペアが ​Map​ に配置されることを意味しました。

現在は、DataWeave で ​application/x-www-form-urlencoded​ の読み取りや書き取りができることから、HTTP のさまざまな MIME タイプを簡単かつ一貫した方法で処理できるようになりました。

Mule 3 の例

この例では、​song=Snow+Poems&artist=TQP​ のペイロードが送信され、保存されていた ID を記した応答 (​song=Snow+Poems&artist=TQP&id=49​) が返されます。

<flow name="urlForm">
  <set-payload value="#[{'song': 'Snow Poems', 'artist' : 'TQP'}]"/>
  <http:request config-ref="config" path="song" method="POST" />
  <set-payload value="#[payload.id]"/>
</flow>
Mule 4 の例

コンテンツを読み取るための構文は同じままですが、実際にデータを変換しているため、出力種別を指定しなければならなくなった点のみが異なります。

<flow name="urlForm">
  ...
  <http:request config-ref="config" path="song" method="POST">
    <http:body>
      #[
      %dw 2.0
      output application/x-www-form-urlencoded
      ---
      {
        song: "Snow Poems",
        artist: "TQP"
      }]
    </http:body>
  </http:request>
  <set-payload value="#[output text/plain --- payload.id]"/>
  ...
</flow>

キーにはいくつかの値を追加できます。このデータにアクセスするには、スターセレクタを使用して、関連するすべての値のコレクションを取得する必要があります。たとえば、​#[payload.*artist]​ は ​Under Pressure​ という歌で ​David Bowie​ と ​Queen​ を記載したリストを返します。

multipart/*

Mule 3 では、Mule メッセージの添付ファイルを、マルチパートコンテンツと同様に使用していました。 アウトバウンドトラフィックの場合、添付ファイルが存在すれば、それらが ​multipart/form-data​ 本文の一部として使用されることを意味しました。インバウンドトラフィックの場合は、その本文の各部が Mule メッセージの添付ファイルにマッピングされることを意味しました。

Mule 4 では、Mule メッセージにファイルが添付されることがなくなりました。代わりに、JSON または XML コンテンツと同様に、DataWeave を使用してマルチパートコンテンツの読み取りや書き込みを行うことができます。

Mule 3 の例

この例では、2 つの主要な JSON 部分がある ​multipart/form-data​ 本文を受け取ります。1 つは注文で、もう 1 つは注文を生成したパートナーです。パートナー名をログに記録すると、注文 ID が保存され、注文を受けたことを伝える簡単なメッセージと、その注文用に生成された領収書 PDF について記載した ​multipart/form-data​ 応答が生成されます。

<flow name="parts">
  <http:listener config-ref="listenerConfig" path="orders"/>
  <set-variable variableName="partner" value="#[message.inboundAttachments.partner.dataSource.inputStream]" mimeType="application/json"/>
  <dw:transform-message>
    <dw:set-variable variableName="partnerName"><![CDATA[
      %dw 1.0
      %output application/java
      ---
      flowVars.partner.name
    ]]></dw:set-variable>
  </dw:transform-message>
  <logger message="Received order from #[flowVars.partnerName]." level="INFO"/>
  <set-payload value="#[message.inboundAttachments.order.dataSource.inputStream]" mimeType="application/json"/>
  <dw:transform-message>
    <dw:set-variable variableName="orderId"><![CDATA[
      %dw 1.0
      %output application/java
      ---
      payload.id
    ]]></dw:set-variable>
  </dw:transform-message>
  <!-- Generate PDF receipt -->
  <set-attachment attachmentName="order" value="#['Order ' + flowVars.orderId +' received. Receipt available.']" contentType="text/plain"/>
  <set-attachment attachmentName="receipt" value="#[payload]" contentType="application/pdf"/>
</flow>
Mule 4 の例

今後は添付ファイルの処理に伴う煩わしさから開放され、​content​ キーワードを使用して名前で各部にアクセスするだけです。マルチパート応答は、DataWeave を使用して HTTP レスポンスボディに生成されます (このボディ内で簡単にカスタマイズできます)。

<flow name="parts">
  <http:listener config-ref="listenerConfig" path="orders">
    <http:response>
      <http:body><![CDATA[
      #[
      %dw 2.0
      output multipart/form-data
      ---
      {
        parts : {
          order : {
            headers : {
              "Content-Type": "text/plain"
            },
            content : "Order " ++ vars.orderId ++ " received. Receipt available."
          },
          receipt : {
            headers : {
              "Content-Disposition" : {
                "name" : "receipt",
                "filename": "receipt.pdf"
              },
              "Content-Type" : payload.^mimeType
            },
            content : payload
          }
        }
      }]
    ]]></http:body>
    </http:response>
  </http:listener>
  <logger message="#[output text/plain --- 'Received order from ' ++ payload.parts.partner.content.name]"/>
  <set-variable variableName="orderId" value="#[output text/plain --- payload.parts.order.content.id]"/>
  <!-- Generate PDF receipt -->
</flow>

ここで注意すべき重要な点は、​http:body​ 機能を活用していますが、最終的な変換コンポーネントを使用してもおそらく同じ結果が得られることです。 境界が自動生成されるため、正しいコンテンツタイプのヘッダーが生成されます。詳細は、​「Multipart Format (Form-Data) (マルチパート形式 (フォームデータ))」​を参照してください。 == 関連情報