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

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

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

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

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

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

目次

はじめに

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に以下を設定します

{
    "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

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

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

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

エラーハンドリング

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

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

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

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

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

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

DevToolsを使ったデバッグ

https://chromewebstore.google.com/detail/make-devtool/ainnemkhpnjgkhcdkfbhmlenkhehmfhi

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

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

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

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

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

あとがき

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