make SaaS その他

make 基本操作編 機能紹介：CustomApps

  • 投稿日

この記事は「make Advent Calendar 2024」10日目の記事です。

このアドベントカレンダーについて

このアドベントカレンダーは25日間でIPaaS製品の「make」について使い方や、実践を学べる連続ブログ企画です。

「おかしん」「ばるす」「たにあん」の3名がリレー形式でお届けします。

25日間のスケジュールは以下の通りです。

日付内容担当
12/1話題のIPaaS製品「make」とはおかしん
12/2makeで作ってみたScenario紹介ばるす
12/3make 基本操作編 機能紹介：Organizationたにあん
12/4make 基本操作編 機能紹介：Scenario、Templateおかしん
12/5make 基本操作編 機能紹介：Connectionsばるす
12/6make 基本操作編 機能紹介：Webhooksたにあん
12/7make 基本操作編 機能紹介：DataStores、DataStructuresおかしん
12/8make 基本操作編 機能紹介：Devicesばるす
12/9make 基本操作編 機能紹介：Functionsたにあん
12/10make 基本操作編 機能紹介：CustomAppsおかしん
12/11make 基本操作編 機能紹介：Flow Control,Tools,Text parserばるす
12/12make ドキュメント動線の話：ResourceHubたにあん
12/13make 検証：Make Bridgeおかしん
12/14make 検証：Make REST APIばるす
12/15make 検証：AI Searchたにあん
12/16make Community Hub：Overviewおかしん
12/17make Community Hub：Academy Courses,Blog Articlesばるす
12/18make Community Hub：Showcase,CustomAppsたにあん
12/19makeの管理運用の話：Github連携おかしん
12/20makeの管理運用の話：実行ログと再実行と停止中リクエスト滞留ばるす
12/21makeの管理運用の話：Connection権限管理たにあん
12/22makeで作ってみた事例：（未定）おかしん
12/23makeで作ってみた事例：（未定）ばるす
12/24makeで作ってみた事例：（未定）たにあん
12/25makeの総論を語るばるす

はじめに

MakeのCustom AppsはMakeで連携されていないサービスを自分で追加する為に利用します。

さっそく作ってみる

本当はSmartHRのSandbox環境Darumaを使って、SmartHRモジュールを作ってみようと思ったのですが、そもそも make のCustom Appsに慣れていないのでいきなり作るのは難しそうでした。というわけで、22日目の「makeで作ってみた事例」で作ることにして、とりあえず本記事ではチュートリアルをなぞっていこうと思います。

https://developers.make.com/custom-apps-documentation/create-your-first-app

アプリを作成

Custom Apps => Create a new appから作成します

とりあえずアイコンなどは無くても作れるので、デフォルトのまま作成します

APIのURLを設定する

今回は make が用意しているデモAPIを使います。BASEタブから baseUrl に https://demo-api.integrokit.com/api/v1 を入力します。

Cmd-SもしくはSave changesから保存しておきます。

モジュールの作成

MODULESタブから作成します

ダイアログが出てくるので、画像の通りに設定します。TemplateはBlank Moduleを設定してください。

「Module action」は「Create」「Read」「Update」「Delete」が選択できます

おそらく、それぞれ「POST」「GET」「PUT（PATCH）」「DELETE」と対応しているんじゃないかと思います。

保存すると「COMMUNICATION」タブが開かれ、サンプルのJSONが入っているはずです。

今回はこれをシンプルなものに変更します{
“url”: “/helloworld”
}

今回は、アプリ作成時のエンドポイントに https://demo-api.integrokit.com/api/v1 を使用したため、このモジュールのリクエスト先は /helloworld を追加した https://demo-api.integrokit.com/api/v1/helloworld になります。

作成したモジュールのテスト

このモジュールはもう利用可能になっているので、シナリオを作成してテストしてみます。モジュールの検索で「helloworld」と打てば先ほど作成したCustom AppおよびHello Worldモジュールが表示されるはずです。

次のモジュールで、Set Variableを選択し、設定してみます

しかし、Custom Appの結果の候補が出てきません。Toolsを削除して、一度実行してみます。

インストールするかどうか聞かれるので、Yesをクリックします。Custom Appsは作成後初めて利用する際はインストールする必要があるみたいです。

再度実行してみます。

結果が返ってきたので、もう一度Toolsを追加してみると、今度は入力候補が出てきました。

ですが、一度実行しないといけないのはモジュールとして不完全です。例えば、Asanaのモジュールであれば、実行前でもこのように候補が出てきます。

これは先ほど作ったモジュールにAPIからのレスポンスの定義がされていない為です。というわけで、モジュールの設定を変更していくのですが、その前に今回実行した結果をダウンロードしておきます。実行結果から「Download output bundles」すると、レスポンスの情報が表示されるので、コピーしておきます。

Custom AppsのモジュールのINTERFACEを開き、OptionsからGeneratorを起動します。

先ほどコピーしておいたものを貼り付けます。

すると、Data structureが表示されるので、これをコピーします。

コピーしたものをINTERFACEの設定に貼り付けて保存します

再度シナリオを作成してみる

先ほど作りかけていたシナリオは削除してもう一度シナリオを作成します。Custom AppsとToolsのモジュールを追加します。

先ほどと違って、一度も実行していないのに、候補が表示されました。

なお、ラベルを変更するとこのように表示されます。

INTERFACEに設定する name については、実際のレスポンスと完全一致している必要があります。Generatorは実際のレスポンスのJSONを解析して、正しい構造のインターフェースを作ってくれるので、まずはGeneratorを使って生成してから label を任意のものに変更するのが使いやすそうです。

今回のように単純なAPIの場合はINTERFACEも手書きが可能かもしれませんが、複雑なAPIの場合はGeneratorが効果を発揮するでしょう。

パラメータを設定できるようにする

さて、今回使ったエンドポイント /helloworld は叩けばそのままHello Worldがかえってきましたが、通常は何かしらのパラメータを付与してリクエストをおくるものです。例えばSmartHRやEntraIDのAPIはユーザーIDやUPN、オブジェクトIDなどを付与するとユーザーの情報をGETすることが可能です。

Custom Appsのモジュールでもそれが可能です。

/helloworld はgreenting とname の2種類のパラメータを取ることが可能です。例えばgreenting="Hello" とname="okash1n" を付与してリクエストすると、{"result":"Hello, okash1n!"} がかえってきます。これらのパラメータをモジュールで受けられるようにします。（通常、APIがどんなパラメータを受けられるかはAPIのドキュメントを参照します）

モジュールのMAPPABLE PARAMETERSに以下を設定します

[
    {
        "name": "greeting",
        "type": "text",
        "label": "Greeting"
    },
    {
        "name": "name",
        "type": "text",
        "label": "Name"
    }
]

これらのパラメータをリクエストに追加します。COMMUNICATIONを開いて、エンドポイントを更新します

{
    "url": "/helloworld?greeting={{parameters.greeting}}&name={{parameters.name}}"
}

もしくは以下の記法でも大丈夫です

{
    "url": "/helloworld",
    "qs" : {
        "greeting": "{{parameters.greeting}}",
        "name": "{{parameters.name}}"
    }
}

シナリオに戻って、モジュールをクリックするとパラメータを入力可能になっています

このモジュールを実行してみると、想定した通りのレスポンスが返ってきていることがわかります。

認証できるようにする

今回使っているAPIは認証なしでも利用できるAPIでしたが、通常我々が利用しているSaaSのAPIはアクセストークンやOAuth2などで認証しないと使えません。

今回使っているエンドポイントも/helloworld は認証なしで使えますが、/books は認証が必要なエンドポイントになっており、https://demo-api.integrokit.com/api/v1/books はそのままアクセスするか、cURL すると以下のエラーレスポンスがかえってきます。

{"error":"Invalid or missing API key"}

makeのCustom Appsでももちろん認証の機構を備えており、CONNECTIONSから設定できます。

Connectionを追加すると、最初はサンプルのJSONが入力されています。

今回のAPIでは以下をそれぞれCOMMUNICATIONとPARAMETERSに入力します

COMMUNICATION

{
	"headers": {
	"api-token": "{{parameters.apiKey}}"
		},
	"log": {
		"sanitize": ["request.headers.api-token"]
	}
}

log.sanitize はログに出力しないものを指定しています。後述するDev Toolsのコンソールで実行時のログが取れるのですが、 log.sanitize を全く使用しない場合はログそのものが出力されません。また、log.sanitize を使用した場合は、指定したもの以外がログに出力されます。ログはデバッグの為に出力する必要がありますが、セキュリティ上の理由から、ログにトークンなどが出るkとは避けなければいけない為、この設定が重要になります。（ブラウザのコンソールログに出力されるということはAPIにアクセス可能な誰もがログの内容を取得できるからです）

詳しくはこちらを参考してください。

PARAMETERS

[
    {
        "name": "apiKey",
        "type": "password",
        "label": "API Key",
        "editable": true,
        "required": true
    }
]

Custome Appで作成したConnectionを使えるようにする

まずはCustom AppのBASEタブで、JSONを修正します

APIキーを受け付けられるモジュールを新たに追加します。MODULESから新しくモジュールを追加して/books のエンドポイントのモジュールを追加します。ほとんどの設定はHello World のモジュールと共通なので、Copy code from existing module で設定します。

残念ながらデモAPIには詳しいリファレンスが無いので/books エンドポイントがどんなパラメータを受け付けられるか、APIキーはどうやって発行するのか、が不明なので、「こんな感じだろう」で設定します。

MAPPABLE PARAMETERS

[
    {
        "name": "name",
        "type": "text",
        "label": "Name"
    }
]

次にCOMMUNICATION

{
    "url": "/books?name={{parameters.name}}"
}

さらにConnectionには先ほど作ったConnectionをAttachします

新しくシナリオを作成します

残念ながら、正しいAPIキーを取得する術が無いので、このモジュールを使うことはできませんでした。

利用イメージはなんとなく分かったんじゃないかと思います。

エラーハンドリング

さて、先ほどは適当なAPIキーを入力したので、エラーが発生していました

この401エラーのBody「Invalid or missing API key」はどのようにして表示されたかというと、Custom AppsのBASEの設定内容に依存しています。

試しにここを変更してみます

そうするとエラーは以下のようになりました

エラーハンドリング用のJSONを書くことで、makeのUI上で簡単にエラーハンドリングができるようになります。

詳しくはこちらをご覧ください

DevToolsを使ったデバッグ

Make DevTool – Chrome Web Store
Inspect your scenarios in Make at a glance!
chromewebstore.google.com

こちらを追加してからCmd-Opt-IでChrome Dev Toolsを開くと「make」のタブが追加されます

エラーもこのように表示されます。

これはおそらく、パラメータに指定した2バイト文字でエラーが出ています。パラメータを修正するとエラーが認証のエラーに変わりました。

先ほどの節において、Custom AppsのBASEのJSONでエラーハンドリングを設定できると書きましたが、どんなエラーが返ってくるのかが設定段階では分からない場合もあるかと思います。そんな場合でもDev Toolsの拡張機能を使うことで、エラー内容を把握できるので、その内容を参考にしてエラーハンドリングを設定していくという使い方ができます。

そのほかにも「Scenario Debugger」などの機能がありますが、内容が膨大になるので、公式ドキュメントをご参考ください。

あとがき

いかがでしたでしょうか？makeでカスタムアプリを作成する方法とそのデバッグ方法をざっくりと解説しました。できれば22日目に実際にSmartHRなどのAPIを使ってカスタムアプリを作ってみたいと思います（願望）。お楽しみに！

okash1n

香川大学医学部医学科中退→SES・情シス・SREを経てクラウドネイティブ入社。趣味はIT。

・有限会社脇屋 代表取締役
・一般社団法人日本ビジネステクノロジー協会 代表理事
・一般社団法人 SRE NEXT 理事
・情シスSlack、BTCONJP、SRENEXT運営

記事一覧