# MuleSoft Training: 14Nov2022DevelopmentFundentals
###### tags: `MuleSoftTraining`

[TOC]

Anypoint Platform 開発基礎コース(2日間 / 5日間)にようこそ!

## モジュール0: トレーニングの準備
[開発:基礎コース セットアップマニュアル](
https://salesforce.quip.com/hhk2ABFZZawE)

- [ ] 1. training.mulesoft.com からファイルのダウンロード
- XXX_studentManual_XXX.pdf(受講者マニュアル) // 復習用
- :star: XXX **_studentFiles_** XXX.zip (受講者ファイル) // *このファイルを最も使用します!*
- (5日間)APDevFundamentals4.4_studentFiles_xxx.zip
- XXX_studentSlides_JA_XXX.zip(受講者スライド)// 復習用
- [ ] 2. [Anypoint Platform アカウント
](https://salesforce.quip.com/QQN7Acqju0il)
- ※ユーザー名とパスワードをお忘れなく！
- ※アカウントには有効期限があります。必ずコースの直前に作成してください。
- [ ] 3. [Anypoint Studio](https://www.mulesoft.com/lp/dl/studio)
- [起動確認](https://salesforce.quip.com/tTDHAkFqrNb2)
- [トラブルシューティング](https://salesforce.quip.com/n2iFAKKHMM1A)
- [ ] 4. [Adavanced REST Client](http://install.advancedrestclient.com/install)
- [Postman](https://www.postman.com/downloads/) などももちろんOKです!
- [ ] 5. [Salesforce開発者アカウント](https://salesforce.quip.com/U8mfAzhdbDOq#WfLAAA7PY1C)
- 5日間参加する方のみ必要です! (3日目に再度ご案内します)
- [ ] 6. [VMの接続(事前に用意を依頼された方のみ)](https://use.cloudshare.com/Class/ahpcb)
- Username : ご自身のメールアドレス
- Password：メールで別途送信

## モジュール1 API 主導の接続性 (API-led Connectivity)
### 今日の課題
- IT に求められている変化の量とスピードに、対応することができない (時間・人員・コストの制約 etc..)
- イノベーションを起こすための足枷に
- 求められる変化の量・スピードは、これらも多く・速くなっていくことが予想されている

そこで MuleSoft は *IT 資産　（アセット） の再利用* に着目した運用モデルを提案　>

### :star:API主導の接続性(API-led Connectivity)

- *再利用*にフォーカスを置いた、３階層に分けた API 設計の考え方（MVCの考え方に近い）
- それぞれの API は、マイクロサービスとして独立しているため、セキュリティや保護、機能追加の観点から管理がしやすい
#### エクスペリエンスAPI層
- API クライアント (呼び出し元)　に応じた違いを吸収する (データ型、データのフォーマット、セキュリティ etc..)
#### プロセスAPI層
- ビジネスロジック: システム API や他のプロセス API からのデータを処理する
#### システムAPI層
- システムからデータを取得する、システムのデータを更新するなど、バックエンドシステムと繋がるAPI
- 必要に応じて、プロセスAPIで処理がしやすいように、統一のデータ型 (CDM) への変換を行う。　
- 例:) 「Salesforceの顧客情報」と「SAPの顧客情報」 のフィールド名、カラム名、データ型を統一
- プロセスAPIの肥大化を防ぎ、システムAPIはより再利用がしやすくなる

### C4E (Center for Enablement)
Anypoint Platform をより活用し、アセット (資産) の *再利用* を促進するためのチーム作り

### API
- REST API / RESTful API
- HTTP
- HTTPメソッド:GET/PUT/POST
- JSON/HTTP
- URI:リソース
- SOAP API
- AWS API Gateway
- 連携、受け皿
- Twitter API
- Slack API
- Google Map
- Google

### REST(ful) API とは?
キーワード: JSON (XML), HTTP, URL(URI)に "リソース名" が含まれる
- GET: /companies
- GET: /companies?location=FR&industory=retail
- ? や &: *クエリパラメータ*。主にフィルタリングに使用する
- GET: /companies/3
- 3: *URIパラメータ*「ID が "3" の会社情報だけ欲しい」
- POST: /companies
- データの作成
- PUT: /companies/3
- データの更新

### MLB REST API (https://api.mlb.com)(架空)
- GET:/teams
- 全ての MLB のチーム
- GET:/teams?state=CA
- カリフォルニアにあるチーム
- GET:/teams/24(/teams/{teamId})
- エンゼルス！
- GET: /teams/24/players/409 (/teams/{teamId}/players/{palyerId})
- 大谷選手!
- GET: /teams/24/players?position=picther (/teams/{teamId}/players)
- エンゼルスのピッチャー
- GET: /teams/24/players?position=picther&position2=outfielder
- 大谷選手!

### JSON
JSON: キー/バリューペア

{
  "age": 31,
  "first_name": "Aaron"
} 

{ } - オブジェクト
[ ] - 配列
リテラル: String, Null, Number, Boolean...

application/JSON

{
   "firstname": "Shohei",
   "lastname": "Ohtani",
   "ID": 409,
   "playerNo": 17,
   "nationality": "JP",
   "position": ["picther", "outfielder" ],
   "salary": 3000000,
   "age": 27,
   "isMarried": false
}

### HTTP ステータスコード
2XX:
- 200: OK
- 201: Created (データが作成された)

4XX:
- 400: BAD REQUEST
- 403: Forbitten
- 404: NOT FOUND

5XX:
- 500: Server Side Error
- 503: Service Unavailable

#### HTTPステータスコード関連資料
- https://http.cat/
- https://httpstatusdogs.com/

### American Flights API
1. 保護されていない API
- 実装 URL
- GET: http://training4-american-ws.cloudhub.io/api/flights

2. 保護されている API (Id/Secret の認証情報 + レート制限)
- プロキシURL
- http://training4-american-api.us-e1.cloudhub.io/flights
- 認証情報
- client_id : `d846d01ea59640108779eaaa532d00ca`
- client_secret: `F7C5ecA48EBA449399b4B140416849B0`


Q. enum - SFO, LAX, CLE とは
A. enum は「列挙型」で、「このうちのどれかを受け付ける」という意味になります。今回のAmerican APIでは「SFO」「LAX」「CLE」の3つの「destination(行先)」から、パラメータを指定できます。
※指定が必須ではないため、指定しなければ全ての行先を含むフライト情報が返されます。

## モジュール2: Anypoint Platform の概要
### Catalyst (Knowledgehub)
ベストプラクティスを集めたレポジトリ
- https://knowledgehub.mulesoft.com/s/
- [日本語] https://knowledgehub.mulesoft.com/s/global-search/%40uri#q=JP&sort=relevancy
- [翻訳ツール] https://www.deepl.com/ja/translator

### Exchange
- アセット(資産)を公開し、社内(時には社外)に共有するためのレポジトリ
- REST API, テンプレート, サンプル、API 仕様を作成するためのフラグメント etc...

### Design Center
1. API Deigner
API を "設計" するツール (仕様)

2. Flow Designer
API を開発する Web ツール (Anypoint Studio で開発する機会の方が断然多いか?)

### Mule アプリケーション
- Java ベース
- 各Mule アプリケーションは、XML として管理される
- jar ファイルとしてパッケージ化
- Mule ランタイムが、アプリケーション(jar)を実行
- 複数のフローで構成される

ホスト: training4-american-api.us-e1.cloudhub.io
ポート: 80
プロトコル: HTTP

## モジュール3: API の設計
Anypoint Platform > Design Center >**API Designer** を使用して API を設計する

### REST API を設計するための言語 (ツール)
- RAML 1.0
- https://raml.org/
- https://github.com/raml-org/raml-spec/blob/master/versions/raml-10/raml-10.md/
- OAS 2.0 (Swagger) / 3.0

### Spec-Driven Development (仕様駆動型開発)
なぜ？
- その API の役割や機能について合意をとる
- フィードバックをもらって改善する
- データ型、エンドポイント名、フィールド名、パラメータ (必須 or not)、などについての事前確認
- 仕様通りのバリデーションを自動適用
- Studio にインポートして、土台となるスケルトン (インタフェースフロー)を自動で生成する
- Exchange に公開したタイミングで
- API ポータルが自動生成される
- API コンソールが自動生成される
- モッキングサービスが自動生成される
- MS2-Delay, MS2-Example
- [シミュレーションヘッダー(動作ヘッダー)](https://docs.mulesoft.com/jp/design-center/apid-behavioral-headers) により実際に近いモック呼び出しが可能
- コネクタの自動生成 (REST Connect)

### Versioning (バージョン管理)
Semantic Verrsioning (セマンティックバージョニング)
X.Y.Z　(1.0.0)

X = Major Version - 後方互換性が保たれない大きな変更
1.2.1 vs 2.0.0

Y = Minor Version - 機能追加など、後方互換性が保たれる範囲での変更
1.2.1 vs 1.3.0

Z = Patch Version - バグ修正など、軽微な変更
1.2.1 vs 1.2.2

### AmericanFlights SAPI RAML (Sample)

#%RAML 1.0
title: American Flights SAPI

types: #データ型の定義
  AmericanFlight: !include exchange_modules/68ef9520-24e9-4cf2-b2f5-620025690913/training-american-flight-data-type/1.0.1/AmericanFlightDataType.raml 

/flights:
  get:
    displayName: getFlights(フライト情報の取得)
    description: アメリカン航空のフライト情報を取得する
    queryParameters:
      destination?:
        # #でコメントを残せます。
        # ? = required: false
        description: 目的地でフィルタリングするためのクエリパラメータ
        enum:
          - SFO
          - CLE
          - LAX
    responses: # レスポンス
      200: # OK
        body:
          application/json:
            # !include  -> 外部のramlを参照する
            example: !include exchange_modules/68ef9520-24e9-4cf2-b2f5-620025690913/training-american-flights-example/1.0.1/AmericanFlightsExample.raml
            type: AmericanFlight[] # [] = 配列
  post:
    displayName: createFlight(フライト情報の作成)
    description: アメリカン航空のフライト情報を作成する
    body: # リクエストボディ
      application/json:
        type: AmericanFlight
        example: !include examples/AmericanFlightNoIDExample.raml
    responses: # レスポンス
      201: # Created
        body:
          application/json:
            example:
              message: flight has been added!(but not really... でも本当は追加していない..)

  /{ID}: # {}は動的に変わるURIパラメータを示しています
    get:
      displayName: getFlightById(IDを使用して、フライト情報の取得)
      responses:
        200:
          body:
            application/json:
              type: AmericanFlight
              example: !include examples/AmericanFlightExample.raml

### Public portal

## モジュール4 API の開発
### Mule アプリケーションとは
- フロー (flow) の集合体
- Java ベースのアプリケーション
- XMLでコードが生成される
- DataWeave や XML を触る際には、コーディングを行う場合もあるが、基本的にはローコードで開発を進めることが可能
- Mule ランタイムエンジンが、jarファイルとしてパッケージ(Maven)されたMuleアプリケーションを実行する

### フロー(flow) とは

- 関数やメソッドのように、意味のある単位で分けられた、再利用・再呼び出し可能なスコープ
- Mule アプリケーションは、複数のフローで成り立っている
- HTTP Listner のようにフローが開始されるトリガーを「イベントソース」、それ以外 (Transform Message, DB Select, Set Payload...) を「イベントプロセッサ」と呼んでいる
- フローが呼び出されるタイミングで、Mule イベントが生成される

### Mule Event とは
Mule アプリケーションが、フロー内で扱うデータオブジェクト (Java オブジェクト)
- Mule Event
- Mule Message
- Attributes (属性: データの付随情報 (クエリパラメータ、ヘッダー、URI パラメータ))
- GET:/customers?id=48493
- `#[attributes.queryParams.id]` >>> 48493
- GET:/customers/48493
- `#[attributes.uriParams.id]` >>> 48493
- `#[attributes.headers.method]` >>> POST, GET, PUT

- Payload (ペイロード: データの本体)
- `#[payload]` >>> "hello world!"
- `#[payload.year]` >>> 2020

- vars (variables, 変数)
- `#[vars.hogeFlag]` >>> true
- `#[vars.tranId]` >>> 41674810
- `#[vars.theResult]`


### Anypoint Studio: jar ファイルのインポート方法
1. Anypoint Studio > 画面左側 (ファイルエクスプローラー) > 右クリック > Import
2. "mule" と検索して、　”packaed mule applications (jar)” を選択
3. インポートする jar を選択

### Training DB(MySQL)の接続情報

ホスト: iltdb.learn.mulesoft.com
ポート: 3306
ユーザー: mule
パスワード: mule
データベース: training

### Transform Message

%dw 2.0
output application/json
---
payload

### Tooling Instance が止まってしまう
- 主な原因: マシンのスペック
- RAM 8GB以上(16GB だとおそらく起きない)
- CPU 2.0Ghz以上
- 主な解決策: マシンのスペックが上記を満たしているのであれば、Anypoint Studio とマシンの再起動をお試しください。

`application/csv`

ID,code,price,departureDate,origin,destination,emptySeats
1,rree0001,541,2016-01-20T09:00:00,MUA,LAX,0
2,eefd0123,300,2016-01-25T09:00:00,MUA,CLE,7
3,ffee0192,300,2016-01-20T09:00:00,MUA,LAX,0
4,rree1000,200,2016-01-20T09:00:00,MUA,CLE,5
5,rree1093,142,2016-02-11T09:00:00,MUA,SFO,1
6,ffee1112,954,2016-01-20T09:00:00,MUA,CLE,100
7,eefd1994,676,2016-01-01T09:00:00,MUA,SFO,0
8,ffee2000,300,2016-02-20T09:00:00,MUA,SFO,30
9,eefd3000,900,2016-02-01T09:00:00,MUA,SFO,0
10,eefd4511,900,2016-01-15T09:00:00,MUA,LAX,100
11,rree4567,456,2016-01-20T09:00:00,MUA,SFO,100

## モジュール5 API のデプロイ・保護・管理
### Mule アプリケーションのデプロイ環境 (ランタイムプレーン)
- CloudHub
- MuleSoftがホストする Mule ランタイム実行環境
- CloudHub ワーカーというクラウド上の仮想マシンで、Mule ランタイムをホストし、そこで Mule アプリケーションを実行する
- 内部的に AWS を使用 (CloudHub ワーカーは、AWS 上の VM (EC2 インスタンス))
- 管理のリソースを最小に抑えることができる(多くの部分を MuleSoft が管理)
- Customer-hosted Mule ランタイム
- お客様のデータセンター、オンプレミス、プライベートクラウド (AWS, Azure, GCP)で実行する
- 設定に柔軟性がある分、お客様が管理・設定することが多い
- Runtime Fabric (RTF)
- Docker, kubernates を用いた Mule ランタイム実行環境
- k8s の実行インフラはお客様が用意・管理
- Docker イメージや k8s クラスタを構成するためのスクリプトは MuleSoftが提供
- 2種類の RTF
- RTF VM
- AWS, Azure, オンプレミス etc ,,
- RTF on Self-managed k8s (自社管理のkubernatesでホストする RTF)
- EKS, AKS, GKE などの管理型 kubernates サービス

### Runtime Manager
- Mule アプリケーションのデプロイやMuleランタイムの管理を行う

### API Manager
- API を保護するためのポリシーやプロキシの設定・管理を行う

### API Proxy
- 実装を保護するためのアプリケーション
下記の2種類の方法
![](https://i.imgur.com/Y4jsGtG.png

**よくある質問**
Proxyと API実装の間のコネクションについて、Retryポリシーが適用可能なのか。 (outbound)

Answer
- DefaultとしてProxy上に設定はない。ただCustom Policyにて実装可能。
- Custom Policyは、CatalystとしてGithubに乗せられていたりするが基本的に必要に応じて自分達で実装。
- 下記のPolicyが例のRetryのためのもの（Circuit Breaker）
https://github.com/mulesoft-catalyst/circuit-breaker-policy-mule-4

1. Proxy with Endpoint
- 今回のコースで扱った方法
- 実装アプリケーションとは別のアプリケーション(Proxy アプリケーション)を作成・管理
- 実装の URL とは、別の URL が存在する
API クライアント -> Proxy URL > 実装 URL
2. Basic Endpoint
- 実装アプリケーションの内部で、APIの保護ポリシーを実行する

### Endpoint with Proxy (プロキシアプリケーション + 実装アプリケーション)
+ Mule/ non-Mule アプリケーションのどちらもサポート + 「API 実装」 と 「セキュリティ / ポリシー」 との クリアな分離
+ Anypoint Studio 上で 「Autodiscovery Config 設定」をする必要がない
- 追加のリソースが必要 (API Proxy アプリケーションのデプロイ, $$$)
- 管理する App の増加
- そのままでは バイパス可能? -> API 実装 URL に直接アクセスできないよう、考慮が必要
- 通過するアプリケーションが増える -> latency が高くなる ?

### Basic Endpoint (実装一体型プロキシ)
+ URLが 1つ (実装URL = プロキシ URL) なので、簡単にバイパスすることができない
+ 追加の vCore を使わない ($$$)
+ 別アプリケーションに通信する必要がない -> 追加の latency 生じさせる場所が少ない
+ プロキシ アプリケーションをわざわざ別で管理する必要がない
- non-Mule アプリケーション のサポートなし- Anypoint Studio 上で 「Autodiscovery Config 設定」をする必要あり

### Gate Keeper
https://docs.mulesoft.com/jp/api-manager/2.x/gatekeeper

### オンプレ Proxy アプリケーションのためのプロキシ設定
Configuring API Gateway to Point to a Proxy
https://docs.mulesoft.com/api-manager/1.x/configuring-proxy-access-to-an-api

### RAML Sample with Client Auth

#%RAML 1.0
title: American Flights SAPI
traits: #特性
  client-id-required:
    description: ヘッダーに client_id と client_secret が必須。Exchange > 各ページの3点ボタンから 「Request Access」 で権限を申請してください。
    headers:
      client_id:
        type: string
      client_secret:
        type: string
    responses:
      401:
        description: Unauthorized, The client_id or client_secret are not valid or the client does not have access.
      429:
        description: The client used all of its request quota for the current period.
      500:
        description: An error occurred, see the specific message (Only if it is a WSDL endpoint).
      503:
        description: Contracts Information Unreachable.

types: # データ型の宣言
  AmericanFlight: !include exchange_modules/68ef9520-24e9-4cf2-b2f5-620025690913/training-american-flight-data-type/1.0.1/AmericanFlightDataType.raml

/flights:
  is:
    - client-id-required
  get:
    displayName: getFlgihts (フライト情報の取得)
    queryParameters:
      destination?: # '?' >>> required: false と同等。
        description: 行先(destination)に応じて、フライト情報をフィルタリングする
        enum: #列挙型
          - SFO　
          - LAX
          - CLE
    responses: #レスポンス
      200: #OK
        body:
          application/json:
            type: AmericanFlight[] # [] = 配列
            example: !include exchange_modules/68ef9520-24e9-4cf2-b2f5-620025690913/training-american-flights-example/1.0.1/AmericanFlightsExample.raml

  post:
    displayName: postFlgihts (フライト情報の作成)
  
  /{ID}:
    is:
      - client-id-required
    get:
      displayName: getFlgihtsByID (ID を指定したフライト情報の取得)
      responses: #レスポンス
        200: #OK
          body:
            application/json:
              type: AmericanFlight
              example: !include examples/AmericanFlightExample.raml


Consumer：http://training-american-flights-sapi-yoshida.us-e2.cloudhub.io

Implementation URL：http://training-american-flights-sapi-yoshida.us-e2.cloudhub.io/api

## モジュール6 Mule Event


### Set Payload
Mule Event > Mule Message の payload (データの本体・本文) を設定するために使用するプロセッサ

### HTTP コネクタ > HTTP Request オペレーション
HTTP プロトコルを使用した通信を行う

### Set Variable
Mule Event > Variable

### DataWeave Playground
https://developer.mulesoft.com/learn/dataweave/

### 空の Logger

{
  payload=hello world!
  mediaType=application/java; charset=UTF-8
  attributes=org.mule.extension.http.api.HttpRequestAttributes
{
   Request path=/hello
   Raw request path=/hello
   Method=GET
   Listener path=/hello
   Local Address=/127.0.0.1:8081
   Query String=
   Relative Path=/hello
   Masked Request Path=null
   Remote Address=/127.0.0.1:53645
   Request Uri=/hello
   Raw request Uri=/hello
   Scheme=http
   Version=HTTP/1.1
   Headers=[
      host=localhost:8081
   ]
   Query Parameters=[]
   URI Parameters=[]
}
  attributesMediaType=*/*
}

### Connection idle timeout vs Response timeout
* Connection idle timeout (返すエラー：connection closed)
* HTTPやTCPのConnectionが成立している場合、アクセスがなくてもConnectionを有効に維持するための最大の時間
* Mule Default : 30秒
* Response timeout (返すエラー：timeout exceeded)
* Responseを待つための最大の時間
* Mule Default : 10秒
* Reference : https://docs.mulesoft.com/jp/http-connector/1.5/http-documentation

## モジュール7 プロジェクト

### Maven
Java のアプリケーションのパッケージ、依存関係の管理
https://maven3.kengo-toda.jp/primer

### global.xml
コネクタの設定など、共通の設定は別xmlに切り出す

### yaml
config.yaml (dev-config.yaml, prod-config.yaml)
> 設定を一箇所にまとめる + 環境ごとに切り替える

#### yamlのLocationについて
- 基本的にsrc/main/resourcesの下に置くべき。
- 他のパスにおいても動作そのものはOKだが、Best Practiceとしてsrc/main/resourcesがおすすめ。
- Absoluteとして指定することも可能。

##### 関連Doc
https://docs.mulesoft.com/jp/mule-runtime/4.4/configuring-properties
*これらのファイルは、Mule プロジェクト内の ​src/main/resources​ に配置されている必要があります。または、絶対パスを使用することもできます。*

## モジュール8 様々な　Web Service の呼び出し
### United
REST API > HTTP Request オペレーション

### Delta
SOAP API > Web Service Consumer

### American
- REST API + Connector > American Fights SAPI コネクタ!!!
(API 仕様から自動生成)
- インポートするだけでコンシュームできたので一番楽だった。→ 再利用促進の観点でExchangeにアセットが多ければ多いほど開発速度が速くなることが考えられる。

## モジュール9 ルーター
### *Choice*
if, else if, else..

### *Scather-Gather*
非同期・マルチスレッド、全てのルートを実行する

### FIrst Successful
成功したら次のプロセッサへ
失敗したら次のルートを試行する

### Round Robin
順番に各ルートを実行

### Validation モジュール
検証のためのモジュール。失敗したらエラーをスロー