目次
はじめに
アップデイティットの毛利です。
先日、弊社から「EDITROOM」というBtoB向けの文書作成クラウドサービスをリリースしました。
データの収集・検証から、文書作成・配布までの一連を自動化するだけでなく、REST APIを用いたサービス連携の実現を目指しています。
本記事では、EDITROOM で提供する REST API 群を用い、
有名なノーコードサービスである Zapier との連携について、実例を紹介できればと思います。
前提知識
本記事は、主に Zapier の使い方に視点を置いた記事を心がけます。
――ですので、EDITROOMを使用する箇所については、適宜自分の利用したいサービスに読みかえていただければ、と思います。
また、以下の知見を有していると読み進めやすいです。
- Zapier の使い方
- 最低限 Zap の構築方法を把握していること
- REST API の使い方
- cURL や Postman で触ったことがあれば尚良し
前提条件・準備
- Zapier アカウント
- Webhooks Appを使用するため、実運用をするには有料枠への課金が必要です。
- また、無料枠でも、Zap 構築中のテスト実行として動作を見ることは可能です。
- EDITROOM アカウント
-
初めてサービスを利用する方向けの初期セットアップ
を完了させて、REST API を実行できるようにしておいてください。
-
初めてサービスを利用する方向けの初期セットアップ
作業
ユースケース
次の一連の動作をZapierで動かせるようにしてみます。
- Zapierで作成したイベント発火用メールアドレスにメールを投げる。
- メールの中身からIDを取り出して、ZapierからEDITROOMにAPIを発火する。
- API結果をメールを送ってきたユーザーに戻す。
Zapier上での作業
1. イベント用メールアドレスの設定
「＋ Create Zap」から新規作成した直後から進めます。
今回は、「New Inbound Email」を指定します。
ここで、Zapier側で自動的にイベント用メールアドレスが発行されます。
（サブドメインにはモザイクをかけています）
このアドレスに実際に使用するパラメータを本文に載せてメールを送ってみます。
パラメータは、EDITROOMの result-check API で利用する文字列を与えます。
75tmf89jq3eim6aqetdejrb1a4
これは、文書生成リクエスト時に発行されるユニークIDです（進行上テキトーな値ですが）。
実際にメールを送った後、「Test trigger」を押してください。
このように、実際に送られたメールをベースに詳細パラメータを形成してくれます。
「body_plain」や「stripped_text」の結果が、メール本文をプレーンに表示しているもののようなので、
文字化けなどの不具合が起きてなさそうであれば、そのまま「Continue」を押して続けます。
また、今回のメールの本文に自由なJSONを載せて送るような場合、それをそのまま横流しするのは危険です。
データを受けた側はJSONをオブジェクト変換するなりした上で、要求したパラメータを抽出して、残りは破棄する方が安全です。
2. EDITROOM APIの発火
前述の通り、Zapier公式が提供するWebhookイベントは、Premium Appとなっているため、実際の運用では課金が必要です。
GETメソッドを指定します。
パラメータの設定は、次の画像の通りです。
EDITROOMに投げるために必要な設定は、大きく３つあります。
- URLを正しくセットする。
- クエリパラメータに前述のIDを「request_id」としてセットする。
- APIキーを使った認証方式を取っているため、ヘッダーにAPIキーをセットする。
テスト実行の結果に「content_id」が含まれていれば、このZapの作成は完了です。
3. リクエストしたメール送信者にメールを返す.
さきほどの結果をメールで送り返します。
送信先は、最初のイベントの結果の中に「From」情報が吐き出されているのでこれを利用します。
Subjectには、一応今回受けたリクエストのIDを入れておきます。
Bodyに、さきほどの結果を入力します。
テスト実行による、メール受信結果です。
期待通りの動作になっていますので、これでこのZapの作成は完了となります。
（実運用をするためには、この後Publish操作をする必要があります。）
より確実な動作とするために
今回、メールの本文の値をそのまま使用しましたが、複数の値が混ざった状態や、フッターなどのゴミデータが含まれてしまった場合に対応することができていません。
実際、企業によっては、メールを送るときには自動的にフッターが含まれてしまい、それを排除することが難しい場合もあり、やはり本文の再整形は望まれる機能です。
幸いにも、ZapierにはJavaScript/Pythonコードを直接実行して結果を得る「Code by Zapier」という機能があるので、これに値を流し込んで整形するのが良いかなと考えます。
Code by Zapier (JavaScript)
さて、前回メールをテスト送信したときに、与えた本文はIDだけでしたが、次のようにフッターが外せないケースを想定します。
前回同様に、「本文の頭にIDが書かれている」ことを前提として、話を進めていきます。
このメールを送信した後、メール受信イベントのテスト実行を更新すると、フッター付きの値でテストパラメータを置き換えることができます。
Zapの１と２の間の「＋」ボタンを押して、「Code by Zapier」を呼び出してください。今回は、JavaScriptを使用します。
今回、暫定的に以下のコードを使用します。これは、単純に本文の先頭行だけを抽出するコードです。
const body = `${inputData["mail_body"]}`;
const body_split = body.split(/\r\n|\n/);
const request_id = body_split[0];
const response = { request_id };
return response;
テスト実行をすると、変数「request_id」に必要な値が入っていることが確認できました。
あとは、この値を後続のイベントで使用する箇所で置き換えていくだけです。
所感
今回は、想定される一番シンプルな実例を解説しました。
「外部サービスとの連携」というのは、自社開発をする上で非常に負担の大きい開発箇所でもあるため、こういったカタチで広がっていくのは夢があって良いですね。
一方で、Zapierの機能において、初見では絶対にわからない挙動や仕様があって、提示された道しるべから気持ちでも逸れると地獄を見る印象があります。
（e.g. POSTメソッド投げるときのJSONパラメータ指定で、オブジェクトをネストした場合のパラメータの定義方法）
（e.g. Code by Zapierのタイムアウトが超シビア）
（e.g. 明かに問題なさそうなJSON文字列をパースできない)
また、Zapierは、その仕組みから大量のリクエストを捌くのには向いておらず、実行頻度の高い操作をZapierで構築してしまうと、すぐにTasksの上限に達してしまいます。
例えば、週末／月末にレポートを作成するときの発火用としては良いかもしれない。一方で、あるプログラムのエラーを転送するような運用すると、エラー頻度が突然高まった時、上限に達してエラーが転送されなくなる可能性があります。
そのあたりを見極めたうえで、利用するのが良いと思いました。
おわりに
再度の紹介となりますが、先日、弊社から「EDITROOM」というBtoB向けの文書作成クラウドサービスをリリースしました。
特に、定期的に文書を作る人的コストや作業にかかる拘束時間の長さを改善するのに、このサービスが大きな一助になると自負しております。
もし、ご興味がありましたら、トライアルをご利用いただければ幸いです。