KARTEを使ってInstagramの投稿をWebサイト上に自由に表示する

<html><head></head><body>こんにちは。エンジニアの矢澤です。
先日<a href="https://ecosystem.plaid.co.jp/product/karte-craft" target="_blank" rel="noreferrer">KARTE Craft</a>という機能をベータ版として公開しました。この機能はKARTE内で発生したさまざまな事象をトリガーとしてユーザーが書いたプログラム（Craft Functions）を実行するものです。
KARTE CraftはKARTEユーザーがKARTEの機能を拡張できるという強力な機能ですが、その性質を理解して使う必要があります。 
KARTE Craftの特徴的な性質のひとつに、「Craft Functions は1回のトリガーに対して少なくとも一回実行される」というものがあります。これは、トリガー発火に対してCraft Functionsが重複して2回以上実行される場合があることを意味しています。
<img src="https://ik.imagekit.io/plaid/0bbe9b33-c2bd-4a5b-a1c4-beb8636c3d08/craft_at_least_once.png" alt="craft_at_least_once.png">
このような性質があるので、Craft Functions内の処理は冪等であることが望ましいです。しかしながら、Craft Functionsを重複なく実行したい場合もあります。例えば <a href="https://craft.developers.karte.io/craft-functions/triggers/line-hook" target="_blank" rel="noreferrer">Craft LINE Hook</a> でLINEメッセージのWebhook先を分岐するパターンでは、フック先へのメッセージ送信が重複するのは避けたいかと思います。
そこで、この記事ではCraft Functionsの実行時に重複排除を行う方法を紹介します。KARTE Craftで新たな機能を実装する際の参考になれば幸いです。
<h1 id="Craft Functions で重複排除を行うアイデア">Craft Functions で重複排除を行うアイデア</h1>
ファンクション実行の重複排除を行う方法は次のとおりです。
<ul>
<li>ファンクションの実行を一意に識別するIDを取得する</li>
<li>ファンクションの実行時に以下を行う
<ul>
<li>外部のデータストアにIDをキーとして問い合わせを行い、レコードが存在したら重複実行とみなして処理を終了する</li>
<li>レコードが存在しない場合はIDをKeyとして外部のデータストアに保存し、処理を継続する</li>
</ul>
</li>
</ul>
<img src="https://ik.imagekit.io/plaid/12ba5e37-b10d-45af-84ec-b1e09e7f55a2/craft_deduplicate_exec.png" alt="craft_deduplicate_exec.png">
これを実装する方法を一つずつ見ていきます。
<h1 id="Craft Functionsの実行を一意に識別する値">Craft Functionsの実行を一意に識別する値</h1>
ファンクション実行時にCraft Functionsが受け取るデータは以下の形式になっています。(参考：<a href="https://craft.developers.karte.io/craft-functions/triggers/data-format" target="_blank" rel="noreferrer">Function実行時に受け取るデータ</a>)
<pre><code class="language-json hljs">{
 "id": "{ リクエスト ID }",
 "kind": "{ トリガーの種類 }",
 "timestamp": "{ トリガー実行時間 }",
 "jsonPayload": "{ Object }"
}
</code></pre>
上記の <code>id</code> はCraft Functionsの実行を一意に識別する値で、リクエストIDと呼んでいます。今回はこの値を使います。
リクエストIDを Craft Functions で取得する際には、次のように関数内で <code>data.id</code> として参照します。
<pre><code class="language-javascript hljs">export default function (data, { MODULES }) {
 const { logger } = MODULES;
 logger.log(`request id = ${data.id}`);
}
</code></pre>
<h1 id="外部のデータストアを準備する">外部のデータストアを準備する</h1>
外部のデータストアについてはAWS、GCP等のパブリッククラウドのサービスを利用しても良いですが、今回はKARTE Craftの Key-Value Store (Craft KVS) を使います。
Craft KVSはKARTE Craftのオプションとして提供している機能で、名前の通りKey-Value Storeとして利用できます。（参考：<a href="https://craft.developers.karte.io/craft-key-value-store/gets-started" target="_blank" rel="noreferrer">Craft Key-Value Store</a>）今回はリクエストIDをキーにデータを書き込めれば良いので、Craft KVSで要件を満たせます。
<h1 id="重複排除を行う">重複排除を行う</h1>
では実際に重複排除を実装してみましょう。Craft Functionsのコードは次の通りです。 
（同じものをGitHubリポジトリに配置しております <a href="https://github.com/plaidev/craft-codes/tree/main/craft-functions/simple-deduplicate" target="_blank" rel="noreferrer">plaidev/craft-codes/craft/simple-deduplicate</a> ）
<pre><code class="language-javascript hljs">// KVSの重複排除用プレフィクス。任意のプレフィクスを指定する。
const DUP_PREFIX = 'functionName';

/**
 * ファンクションの重複実行を検知します。
 * @param {string} id - Craft Functionsの実行を一意に識別するID. (data.id)
 * @param {Object} kvs - MODULES.kvs
 * @param {*} prefix - Function識別用のプレフィクス
 * @returns {Promise&lt;boolean&gt;} - すでに実行中であれば true を返却する。未実行であればKVSにレコードを書き込んでfalseを返却する。
 */
async function isDuplicatedExec(id, kvs, prefix) {
 const key = `${prefix}_${id}`;
 const v = await kvs.get({key});

 if (v[key] != null) {
 return true;
 }

 try {
 const unixtimeMs = new Date().getTime();
 await kvs.checkAndWrite({
 key,
 value: { id, prefix },
 operator: '&lt;',
 unixtimeMs,
 });
 return false;
 } catch(e) {
 // 書き込みが衝突した場合、すでに実行中のファンクションが存在するので true を返す
 if (e.status === 409) {
 return true;
 }
 throw e;
 }
}

export default async function(data, {MODULES}) {
 const { logger, kvs } = MODULES;

 if (await isDuplicatedExec(data.id, kvs, DUP_PREFIX)) {
 logger.warn('duplicated execution.', data);
 return;
 }

 logger.log(`executed. (id=${data.id})`);
}
</code></pre>
短いコードですが処理を追いかけます。
Craft Functionsのエントリーポイントは <code>export default async function()</code> です。この関数内で <code>isDuplicatedExec()</code> を呼び出して重複排除を行います。
<pre><code class="language-javascript hljs">export default async function(data, {MODULES}) {
 const { logger, kvs } = MODULES;

 if (await isDuplicatedExec(data.id, kvs, DUP_PREFIX)) {
 logger.warn('duplicated execution.', data);
 return;
 }

 // 省略
}
</code></pre>
<code>isDuplicatedExec()</code> はCloud FunctionsのリクエストID、kvsモジュール、識別用のプレフィクスを受け取り、当該ファンクションが既に実行中/実行済みであれば <code>true</code> を返却します。 
識別用のプレフィクスを受け取るのは、Craft KVSのテーブルがKARTEプロジェクトで共通になっているためです。 実行するCloud Functions固有の値をプレフィクスとして持たせることで、kvs内で識別ができるようにします。
<pre><code class="language-javascript hljs">/**
 * ファンクションの重複実行を検知します。
 * @param {string} id - Craft Functionsの実行を一意に識別するID. (data.id)
 * @param {Object} kvs - MODULES.kvs
 * @param {*} prefix - Function識別用のプレフィクス
 * @returns {Promise&lt;boolean&gt;} - すでに実行中であれば true を返却する。未実行であればKVSにレコードを書き込んでfalseを返却する。
 */
async function isDuplicatedExec(id, kvs, prefix) {
 //省略
}
</code></pre>
<code>isDuplicatedExec()</code> 内では、プレフィクスとリクエストIDを組み合わせたキーで Craft KVS に問い合わせを行い、キーに対応するデータが存在すれば重複実行とみなして <code>true</code> を返却します。存在しない場合はそのキーでCraft KVSにデータを書き込み、処理を終了します。
<pre><code class="language-javascript hljs"> const key = `${prefix}_${id}`;
 const v = await kvs.get({key});

 if (v[key] != null) {
 return true;
 }
</code></pre>
データ書き込みの際には競合を防ぐために <code>kvs.checkAndWrite()</code> で書き込みを行っています。 <code>kvs.checkAndWrite()</code> はデータの書き込みを行う際に <code>unixtimeMs</code> (時刻) <code>operator</code> (比較方法) を渡して、データの最終更新時刻と <code>unixtimeMs</code> を比較します。ここでは <code>unixtimeMs</code> に書き込み直前の時刻を、<code>operator</code> に <code>&lt;</code> を渡しているので、
(データの最終更新時刻) &lt; (書き込み直前の時刻)
の場合に書き込みが行われます。これを満たさない、つまり (データ最終更新時刻) &gt;= (書き込む直前の時刻) の場合は競合する書き込みが発生しているということなので、実行が重複しているとみなせます。
条件を満たさない場合は <code>status</code> に409という値を持つエラーが発生するため、エラーハンドリングでstatusを検証します。409だったら別の実行で書き込まれたとみなして <code>true</code> を返しています。
<pre><code class="language-javascript hljs"> try {
 const unixtimeMs = new Date().getTime();
 await kvs.checkAndWrite({
 key,
 value: { id, prefix },
 operator: '&lt;',
 unixtimeMs,
 });
 return false;
 } catch(e) {
 // 書き込みが衝突した場合、すでに実行中のファンクションが存在するので true を返す
 if (e.status === 409) {
 return true;
 }
 throw e;
 }
</code></pre>
このようにして、リクエストIDとCraft KVSを使って重複実行を排除します。
<h1 id="まとめ">まとめ</h1>
今回はCraft Functionsの重複実行を防ぐ方法として、Craft KVSを使った実装を紹介しました。この実装は Craft LINE Hookを使ったLINE Message Hookの分岐をはじめとする外部サービスへのメッセージ送信やユーザーへの通知のような、重複実行が好ましくない処理を行う際に役立ちます。 
Craft KVSを使った重複排除はCraft Functionsの実行以外にも応用ができるので、KARTE Craftの実装パターンの一つとして覚えていただければと思います！
<hr>
プレイドでは、ソリューションを一緒に作っていく仲間を募集しております！プレイドのテクノロジーを駆使し、お客様に新しい価値を提供できるソリューションを一緒に作っていきましょう！
<ul>
<li><a href="https://recruit.plaid.co.jp/requisitions/general-customer-engineer" target="_blank" rel="noreferrer">Customer Engineer | 募集ポジション | 株式会社プレイド</a></li>
<li><a href="https://recruit.plaid.co.jp/requisitions/product-engineer" target="_blank" rel="noreferrer">Product Engineer | 募集ポジション | 株式会社プレイド</a></li>
<li><a href="https://blog.plaid.co.jp/n/nd8a70f686885" target="_blank" rel="noreferrer">2協業案件のリードに、PdMとしての役割も。経験が複利で増えるカスタマーエンジニアの多面性｜PLAID</a></li>
<li><a href="https://blog.plaid.co.jp/n/n6d87538d003f" target="_blank" rel="noreferrer">幅広く活用できるプロダクトの価値を顧客に届ける「カスタマーエンジニア」の道を選択した3人のキャリアを聞きました｜PLAID</a></li>
</ul>
</body></html>

KARTE CraftはKARTEで発生した事象をトリガーに汎用のプログラム（Craft Functions）を実行しますが、1回のトリガーに対してプログラムが重複して実行されることがあります。この記事ではCraft KVSを使ってCraft Functionsの重複実行を防ぐ方法を紹介します。

KARTE Craftでファンクションの重複実行を防ぐ