API からのデータのコンシューム

アプリケーションをビルドしたら、API からのデータのコンシュームを開始できます。SOAP または REST API からデータをコンシュームするには、以下のプロセスを参照してください。

SOAP API からのデータのコンシューム

独自の Anypoint Connector を持たない SOAP API からデータをコンシュームするには、Web サービスコンシューマー用 Anypoint Connector (Web Service Consumer Connector) を設定します。
コネクタは API の WSDL ファイルから取得したホスト、ポート、およびアドレスメタデータを使用して、Mule アプリケーション内からサービスをコンシュームするために必要な接続設定を提供します。

詳細は、「Web Service Consumer Connector」を参照してください。

REST API からのデータのコンシューム

以下のプロセスでは、REST API をコールするための HTTP Request Connector の設定に焦点が当てられています。これは、Mule アプリケーションが REST API をコンシュームする方法の基本構造、必要な最小限の設定、コンシューム方法の例、動的要求の設定方法、HTTP Content-Type とエンコードの管理方法、カスタムヘッダーの操作方法、およびセキュリティ要件を理解するのに役立ちます。

Mule アプリケーション内で REST API からデータをコンシュームするには、HTTP 要求用 Anypoint Connector (HTTP Request Connector) を設定できます。

同じ REST API に何度も接続したり、複雑な認証プロトコルを持つ API を使用したりする場合は、Mule SDK を使用して独自のコネクタを開発することを考慮してください。接続先の API のコネクタが Anypoint Exchange にすでに存在するかどうかを確認します。Anypoint Studio の [Mule Palette (Mule パレット)] を使用して Exchange 内を検索できます。

基本構造

REST API をコンシュームする Mule アプリケーションは次の要素で構成されます。

要求をビルドするように設定された 1 つ以上のメッセージプロセッサー
REST API をコールするように設定された HTTP Request 操作
応答を受け入れて処理するように設定された 1 つ以上のメッセージプロセッサー

Figure 1. REST API のコンシュームフロー。

要求をビルドするアプリケーションの部分と応答を処理するアプリケーションの部分を設定します。

最小限の設定

コンシュームする REST API には、その API を記述する RAML ファイルが必要です。これにより、HTTP Connector はスマート提案をユーザーにあらかじめ提供できます。

RAML ファイルでは、以下を定義します。

Authentication (認証)
アウトバウンド HTTP エンドポイントを設定するためのベース URI
Scope (スコープ)

アプリケーションは認証ログイン情報に基づいて、たとえば、コールを特定のリソースの GET 要求のみに制限したり、リソースへのアクセスを制限したりできます。
リソース

アウトバウンド HTTP エンドポイントのリソースのパスを設定する必要があります。
メソッド

POST を HTTP アウトバウンドエンドポイントのデフォルトメソッドとして受け入れたり、そのデフォルトを、リソースでサポートされているメソッドに変更したりできます。
Input validation (入力規則)

通常、POST および PUT コールの場合、API は、入力形式 (JSON、XML など) がそのスキーマに一致していることを要求します。

Mule Runtime Engine で、以下を定義または設定できます。

Output format (出力形式)

HTTP Request 操作の後、メッセージプロセッサーをフローに含めて、フローで API からの応答を受け入れて使用可能な形式に変換する必要があります。
Redirect (リダイレクト)

API でリダイレクトを使用する場合、HTTP Request 操作でリダイレクトを有効にします。
Timeout (タイムアウト)
Headers for methods (メソッドのヘッダー)

ほとんどの場合、POST、PUT、DELETE 要求にはヘッダーが必要です。
URI およびクエリパラメーター
エラー処理

要求操作の設定方法についての詳細は、HTTP Connector のドキュメントを参照してください。

REST API のコンシュームの例

次の例では、 JSONPlaceholder API をコンシュームします。この例には、HTTP Request Connector の設定のみが示されています。これを正常に機能させるには、フロー内でメッセージをトリガーする 1 つ以上の Mule イベントソースと、応答を受け入れる 1 つ以上のメッセージプロセッサーを設定する必要があります。詳細は、「REST API の例」のドキュメントを参照してください。

この API の例について説明します。

この API は認証を必要としません。
ベース URL は jsonplaceholder.typicode.com です。
この API は開発目的のモック API です。
id=1 のユーザーに関する情報を取得するには要求が次のようになっている必要があることをこのサンプル API 要求は示しています。

https://jsonplaceholder.typicode.com/users/1

URL の各部は次のとおりです。

Protocol (プロトコル): http
API Base URL (API のベース URL): jsonplaceholder.typicode.com
Resource path (リソースパス): /users/1
Query Parameters (クエリパラメーター): この場合は [None (なし)]。

このコールを Mule アプリケーションに実装するには、HTTP Request 操作を設定します。

Anypoint Studio での HTTP Request 操作の設定

Studio の [Mule Palette (Mule パレット)] から、HTTP Request Connector をアプリケーションに追加します。
[HTTP Request Configuration (HTTP 要求設定)] ウィンドウで、[Host (ホスト)] の値として jsonplaceholder.typicode.com を指定します。
[Port (ポート)] の値を 80 に設定します。
[OK] をクリックします。

Figure 2. [Host (ホスト)] と [Port (ポート)] を含む [HTTP Request configuration (HTTP 要求設定)]。

HTTP Request 操作のプロパティエディター > [General (一般)] タブから [Request (要求)] セクションに移動して、[Path (パス)] 項目に /users/1 を追加します。
最初のステップでホストを指定することで識別を開始した URL は、このパスの指定により完了します。

[Method (メソッド)] ドロップダウンリストからメソッドを選択します (この例では GET)。
アプリケーションを保存します。

Figure 3. HTTP 要求の GET メソッドとパス。

XML での HTTP Request 操作の設定

次の XML コードは、例の HTTP Request 操作の設定を示しています。

<http:request-config name="HTTP_Request_configuration">
    <http:request-connection host="jsonplaceholder.typicode.com" />
  </http:request-config>

<flow name="basic_tutorialFlow1">

    <...>

    <http:request method="GET" doc:name="Request" config-ref="HTTP_Request_configuration" path="/users/1"/>
</flow>

JSON 応答の例

JSONPlaceholder API の例の JSON 応答の構造は次のとおりです。

{
  "userId": 1,
  "id": 3,
  "title": "fugiat veniam minus",
  "completed": false
}

HTTP Request 操作の [Advanced (詳細)] タブでデータを変換できます。また、対象変数を定義することもできます (デフォルトは [Payload (ペイロード)])。

この API に RAML ファイルが関連付けられている場合、その RAML ファイルをコネクタの設定要素で参照できます。これを設定し、コールする動詞とアセットを選択したら、Studio は出力に対応するメタデータを公開します。フローの他の要素とのインテグレーションが簡略化されます。

DataWeave 式を使用した動的要求の設定

ほとんどのユースケースで、API へのコールをメッセージのデータに基づいて動的に変更することが求められます。この動的要求は、DataWeave 式を使用して設定できます。

「REST API のコンシュームの例」に記載されている設定例では、要求は URL 内でハードコード化されていました。

https://jsonplaceholder.typicode.com/users/1

次の GET 要求の例では、コールは、DataWeave 式 #[payload.user_id] を使用してメッセージのペイロードからユーザー ID を抽出するように Mule Runtime Engine に指示しています。

https://jsonplaceholder.typicode.com/users/#[payload.user_id]

Anypoint Studio での動的要求の設定

Anypoint Studio を使用して同じ操作を実行するには、目的の DataWeave 式 (この場合は #['/users/' ++ payload.user_id]) を使用してパス設定を変更します。

Figure 4. [Path (パス)] 項目で DataWeave 式を使用して動的要求を設定。

クエリパラメーター、URI パラメーター、または HTTP メソッドでも動的要求を設定できます。また、設定プロパティを使用して、このいずれかの動的要求を設定することもできます。

XML での動的要求の設定

次の XML 形式のサンプルコードは、動的要求の設定を示しています。

  <http:request-config name="HTTP_Request_configuration">
    <http:request-connection host="jsonplaceholder.typicode.com" />
  </http:request-config>
  <flow name="basic_tutorialFlow1">
    <...>
    <set-payload value='#[{user_id: "10"}]'/>
    <http:request method="GET" config-ref="HTTP_Request_configuration" path="#['/users/' ++ payload.user_id]"/>
  </flow>

HTTP Content-Type およびエンコード

POST 要求を送信すると、Mule Runtime Engine は、本文の Content-Type とエンコードに関する次のルールに従います。

Content (コンテンツ)

ルール

String、char[]`、Reader または同様のコンテンツ*

* エンドポイントでエンコードが明示的に設定されている場合、Mule Runtime Engine はそのエンコードを使用します。 * エンドポイントでエンコードが明示的に設定されていない場合、Mule Runtime Engine はメッセージプロパティ Content-Type からエンコードを決定します。 * Content-Type メッセージプロパティが設定されていない場合、Mule Runtime Engine は Mule コンテキストのデフォルト設定を使用します。 * Content-Type の場合、Mule Runtime Engine はメッセージプロパティ Content-Type を送信しますが、実際のエンコードが設定されます。

バイナリコンテンツ

エンコードは関連しません。Mule Runtime Engine は Content-Type を次のように設定します。

Content-Type プロパティがメッセージで設定されている場合、Mule Runtime Engine は、定義されているコンテンツタイプを使用します。
Content-Type プロパティがメッセージで設定されていない場合、Mule Runtime Engine は「application/octet-stream」を Content-Type として設定します。

カスタムヘッダー

API によっては、要求と共にカスタムヘッダー (開発者キーなど) を渡す必要があります。クエリパラメーターと同様に、HTTP Connector でヘッダーを要求に追加できます。
たとえば、コンシュームしている API が開発者キーを必要とする場合、ヘッダー名 accessKey を使用して、そのキーを要求のヘッダーとして指定します。
Anypoint Studio を使用して、プロパティを追加してカスタムヘッダーを設定できます。

Anypoint Studio でのカスタムヘッダー

Studio でカスタムヘッダーを設定するには、次の手順を参照してください。

HTTP Request 操作のプロパティエディターで、[Headers (ヘッダー)] タブを選択します。
[Add (追加)] をクリックします。
[Name (名前)] と [Value (値)] を定義します。どちらも、式またはプロパティプレースホルダーを使用して定義できます。

Figure 5. HTTP Request 操作のプロパティエディターで、[Custom Headers (カスタムヘッダー)] を設定します。

セキュリティ要件

コールしている API が複雑な認証プロトコルを必要とする場合、独自のコネクタをビルドしてその API をコンシュームできます。それ以外の場合は、基本認証ログイン情報を設定するか、グローバル HTTPS Connector を設定して、API のセキュリティ要件を満たすことができます。

基本認証

コールしている REST API が基本認証ログイン情報の提供を要求する場合、アウトバウンド HTTP エンドポイントの設定内で基本認証ログイン情報を指定できます。

Studio で [HTTP Request configuration (HTTP 要求設定)] ウィンドウに移動します。
[Authentication (認証)] で [Basic Authentication (基本認証)] を選択します。
ユーザー名とパスワードを入力します。これらをプロパティプレースホルダーとして設定することもできます。
[OK] をクリックします。

HTTPS 設定

コンシュームしている REST API が、HTTPS を介して受信要求が到着することを要求する場合、Mule アプリケーションでグローバル HTTPS 要求コネクタを設定し、そのコネクタを要求操作で参照できます。
次の例では、HTTPS 要求コネクタを設定し、Java キーストアファイル (JKS) を作成し、TLS を設定します。

HTTPS 用 HTTP Request Connector の設定

[HTTP Request Configuration (HTTP 要求設定)] ウィンドウで、[General (一般)] タブ > [Connection Configuration (接続設定)] セクションに移動します。
[Protocol (プロトコル)] で [HTTPS] を選択します。
[OK] をクリックします。

Figure 6. HTTPS 要求コネクタの設定。

キーストアファイルの作成

Java インストールの bin ディレクトリにある Java keytool を使用して、通信を認証するためのキーストアファイルを作成します。

コマンドラインを使用して、使用しているマシンの Java インストールディレクトリに移動します。
次のコマンドを実行します。

keytool -genkey -alias mule -keyalg RSA -keystore keystore.jks

2 つのパスワードを作成するように促されたら作成し、後で使用するために覚えておきます。
このアクションにより、keystore.jks という名前の jks ファイルがローカルディレクトリに作成されます。
keystore.jks ファイルを配置します。
- Studio を使用する場合、keystore.jks ファイルを Studio の Package Explorer の appname/src/main/resources ディレクトリに配置します。
- Mule Runtime Engine で XML を使用し、ファイルを複数のアプリケーションで使用する場合、MULE_HOME/conf ディレクトリにファイルを配置します。
- Mule Runtime Engine で XML を使用し、ファイルをこのアプリケーション内で使用する場合、yourappname/src/main/resources ディレクトリにファイルを配置します。

グローバル HTTPS 要求コネクタでキーストアを参照します。
次に、このコネクタはフロー内で HTTP アウトバウンドエンドポイントにより参照されます。

TLS を設定する

以下の手順に従って、TLS を設定します。

Studio で、[Global Elements (グローバル要素)] ビューに移動します。
[Create (作成)] を選択し、「TLS Context (TLS コンテキスト)」を検索します。
[Key Store Configuration (キーストア設定)] セクションで、キーストア設定の [Type (種別)] をドロップダウンメニューから選択します。たとえば、デフォルトの種別である [JKS] (Java キーストア) を選択します。
キーストアを appname/src/main/resources ディレクトリに配置している場合は、[Path (パス)] にキーストアの名前を指定し、それ以外の場合は "/keystore.jks" を指定します。
[Key Password (キーパスワード)] と [Password (パスワード)] には、キーストアファイルの作成時に作成したパスワードを入力します。
[OK] をクリックします。

Figure 7. TLS を設定します。

[HTTP Request configuration (HTTP 要求設定)] ウィンドウに移動します。
[TLS Configuration (TLS 設定)] で [Global Reference (グローバル参照)] と、以前作成した [TLS context (TLS コンテキスト)] 値を選択します。
TLS コンテキストはインラインで作成することもできます。

Figure 8. HTTP 要求設定での TLS の設定。

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

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

Anypoint Platform：開発基礎 (無料)

MuleSoft Forum Japan