Craft Functionsからスプレッドシートのデータを読み書きする

<html><head></head><body>こんにちは。エンジニアの矢澤です。
KARTEでは主要な機能をAPIとして公開しています。APIを利用することで、プログラムからKARTEに対してさまざまな操作ができます。
<a href="https://ecosystem.plaid.co.jp/karte-api" target="_blank" rel="noreferrer">KARTE API</a>
そして、このKARTE APIにKARTE Craft向けの機能が追加されました。実装例も交えて紹介します。
<h1 id="Craft Type App">Craft Type App</h1>
KARTEのAPIでは「アプリ」という単位でAPIの認証情報・権限情報を管理します。通常、プログラムや外部サービスからAPIを利用する際には <code>token</code> というタイプのアプリを作成してアクセストークンを発行します。 
今回、<code>craft</code> というKARTE Craftからのみ利用できるアプリタイプを追加しました。<code>craft</code> タイプのアプリは <code>token</code> タイプのアプリと同様に権限管理と認証情報の発行ができます。ただし、<code>craft</code> タイプのアプリはCraft Functionsのクライアントからのみ利用できます。それ以外の環境から呼び出した場合はエラーとなります。
<img src="https://ik.imagekit.io/plaid/d82cb5a7-d7e3-4915-ac0c-b68b78a6901e/craft-type-app.png" alt="craft-type-app.png">
これまでKARTEのAPIではアクセストークンによる認証のみサポートしていましたが、 <code>craft</code> タイプのアプリによって KARTE Craftを使ってアクセス制御が実装できる ようになりました。例えば次のような制御が実現できます。
<ul>
<li>送信元IPアドレスによるアクセス制限</li>
<li>平日・休日、時間帯別の利用可否の設定</li>
<li>時間単位・ユーザー単位のリクエスト数制限</li>
</ul>
この記事では <code>craft</code> タイプのアプリを使ったアクセス制御の例として、送信元IPによるアクセス制限を実装してみます。
<h1 id="前提条件">前提条件</h1>
今回の実装にあたって以下の機能を利用します。機能有効化の申し込み・費用の問い合わせ等は営業・サクセス担当者にお問い合わせください。
<ul>
<li><a href="https://ecosystem.plaid.co.jp/product/karte-craft" target="_blank" rel="noreferrer">KARTE Craft</a>
<ul>
<li>Growth以上のプランをご契約いただく必要があります。</li>
</ul>
</li>
<li><a href="https://ecosystem.plaid.co.jp/karte-api" target="_blank" rel="noreferrer">KARTE API</a>
<ul>
<li>Freeプランで問題ありません。</li>
</ul>
</li>
</ul>
<h1 id="構成">構成</h1>
送信元IP制限の仕組みを図示すると次のようになります。
<img src="https://ik.imagekit.io/plaid/960f1c65-c175-4852-99c2-e509fc435ba4/ip-restriction-arch-r1.png" alt="ip-restriction-arch-r1.png">
動作を説明します。
<ul>
<li>今回は <a href="https://developers.karte.io/reference/post_v2-track-event-write" target="_blank" rel="noreferrer">Send event to KARTE</a> APIに送信元IP制限を設定します。</li>
<li>APIのユーザーはCraft EndpointにAPIリクエストを行います。
<ul>
<li>現在Craft Endpointはヘッダー情報の送信をサポートしていないので、bodyにアクセストークンを埋め込みます。</li>
<li>APIリクエストは次のようになります。</li>
</ul>
</li>
</ul>
<pre><code class="language-sh hljs">curl -X POST 'https://t.karte.io/hook/{{ Craft Endpoint Path }}' \
-H 'Content-Type: application/json' \
-d '{
 "access_token": "{{ API v2 Access Token }}",
 "request_body": {
 "keys": {
 "user_id": "manabu.yazawa"
 },
 "event": {
 "event_name": "ip_restriction_test_event",
 "values": {
 "from": "plaid_office"
 }
 }
 }
 }'
</code></pre>
<ul>
<li>Craft Functionsで以下の処理を実行します。
<ul>
<li>送信元IPアドレスによるアクセス制御
<ul>
<li>許可対象のIPに含まれていれば処理を続けます</li>
<li>含まれていない場合はエラーを返します</li>
</ul>
</li>
<li>Craft Type App専用クライアントを使ってAPIをコール</li>
<li>API実行結果を返却</li>
</ul>
</li>
</ul>
<h1 id="実装手順">実装手順</h1>
実装の手順を紹介します。
<h2 id="API v2 Craft Type App の作成">API v2 Craft Type App の作成</h2>
サポートサイトを参考にアプリを作成します。 
<a href="https://support.karte.io/post/5RwTOxJDAbNG8zqN7VBOt8" target="_blank" rel="noreferrer">API v2画面 | ドキュメント / ストア / API | KARTEサポートサイト</a>
<ul>
<li>アプリの種類として「CRAFT」を選択します</li>
<li>API実行に必要なScopeを追加します。今回は <code>track.event.write</code> を追加します。</li>
<li>アプリ作成直後に表示されるアクセストークンを控えておきます。</li>
</ul>
<h2 id="Craft Functions の作成">Craft Functions の作成</h2>
以下のページを参考にCraft Functionsのファンクションを作成します。 
<a href="https://developers.karte.io/docs/create-craft-funcitons" target="_blank" rel="noreferrer">Craft Functionsを作成する</a>
<ul>
<li>ファンクションのコードはGitHubにアップロードしました。index.jsをcodeに、modules.jsonをmodulesに貼り付けてください。
<ul>
<li><a href="https://github.com/plaidev/craft-codes/tree/main/craft-functions/apiv2-ip-restriction" target="_blank" rel="noreferrer">craft-codes/craft-functions/apiv2-ip-restriction at main · plaidev/craft-codes</a></li>
</ul>
</li>
<li><code>ALLOWED_IPS</code> 変数にアクセス許可対象のIPアドレスを記載します。</li>
</ul>
<pre><code class="language-js hljs">// 許可対象のIPを配列形式で設定する
const ALLOWED_IPS = [
 "192.168.0.1",
 "172.17.0.1",
 // ...
];
</code></pre>
<ul>
<li>[保存]を選択し、ファンクションを作成します。</li>
</ul>
ファンクションの作成が終了して <code>SUCCESS</code> になったことを確認したら、当該ファンクションの [エンドポイント設定] を開いてエンドポイントを作成します。<a href="https://developers.karte.io/docs/craft-endpoint#%E8%A8%AD%E5%AE%9A%E6%89%8B%E9%A0%86" target="_blank" rel="noreferrer">Craft Endpoint</a>を参考に作成したら、エンドポイントのURLを控えておきます。
<h1 id="動作確認">動作確認</h1>
実際に動作確認してみます。許可対象のIPアドレスを持つ拠点からCraft Endpointに対してHTTPリクエストを実行すると、次のようにSend event to KARTE APIの正常レスポンスが返却されます。
<pre><code class="hljs">&gt; curl -X POST 'https://t.karte.io/hook/{{ Craft Endpoint Path }}' \
 -H 'Content-Type: application/json' \
 -d '{
 "access_token": "{{ API v2 Access Token }}",
 "request_body": {
 "keys": {
 "user_id": "manabu.yazawa"
 },
 "event": {
 "event_name": "ip_restriction_test_event",
 "values": {
 "from": "plaid_office"
 }
 }
 }
 }'
{"id":"35fa4e2b-5ff1-4ec4-8ea9-5c95b0766d6a"}
</code></pre>
一方、許可対象外のIPからリクエストを行うと、次のようにエラーメッセージが返却されます。
<pre><code class="hljs">{"craft_status_code":401,"message":"unauthorized"}
</code></pre>
<h1 id="まとめ">まとめ</h1>
KARTEのAPIに追加されたKARTE Craft向けのアプリタイプとして <code>craft</code> タイプを公開しました。<code>craft</code> タイプのアプリを使うことで、KARTE CraftでAPIのアクセス制御ができるようになります。KARTE API単体では実現できない要件がある場合はこちらを検討してみてください！
<hr>
プレイドでは、世の中にインパクトを与える新しいソリューションを一緒につくる仲間を募集しています！ 
ぜひ気軽にお問い合わせください。
↓ パートナー企業になりたい
<ul>
<li><a href="https://ecosystem.plaid.co.jp/" target="_blank" rel="noreferrer">CustomerData-Driven Solution を一緒に創りませんか？ | PLAID Ecosystem</a></li>
</ul>
↓ PLAIDで働きたい
<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>
</ul>
</body></html>

KARTEのAPI v2にはKARTE Craft経由でのみ呼び出し可能な craft アプリタイプがあります。この記事では craft タイプのアプリを利用して、KARTE APIの送信元IP制限を実装します。

KARTE Craftを使ってKARTE APIの送信元IP制限を実装する