Solution Blog

Kazuhisa Fukuda

Kazunori Kamiya

Yusuke Kobayashi

Masamichi Kanakubo

Kazuki Shimizu

Shin Yamamoto

Yuichiro Kohata

Shiori Megumi

Kai Murakami

Shogo Michihata

Yuji Yoshida

Akihiro Nakano

Kasumi Shimamoto

Daikichi Sasamori

Yuusuke Hasegawa

Jumpei Ikegami

Manabu Yazawa

Yusuke Yajima

Kippei Wada

Ikumi Watanabe

Jumpei Koshio

<p>こんにちは、Customer Engineerのkazです！最近、『チ。-地球の運動について-』に夢中になっています。学生時代に感じた物理への憧れを思い出させてくれる作品で、ぜひ皆さんにもおすすめしたいです。私はピャスト伯が好きです。</p>
<p>さて、近年企業が顧客理解を深めるためにアンケートやレビューなどの1st Partyデータを活用することが一般的になっています。しかし、膨大な量のフリーテキスト回答データを人手で分析するのは大変な作業です。</p>
<p>KARTE Craft AI Modules では、アンケートなどで収集された自由記述データに対して、文意の成分ごとの大きさをベクトルサイズで表現する機能を提供します。これにより、肯定的な感情を含む回答を効率的に抽出したり、回答の傾向を数値化することができます。</p>
<p>具体的な活用事例としては、大規模アンケートの感情分析や、商品・サービスに対するユーザーの評価把握などが考えられます。KARTE Craftのこの機能を使えば、膨大なテキストデータの中から重要なインサイトを見出すことができるでしょう。</p>
<p>ぜひ、KARTE Craft AIモジュールを活用して、テキストデータの高度な分析に挑戦してみてください。</p>
<h2>アウトプットイメージ</h2>
<p>最終的なアウトプットイメージは次の通りです。<br>
今回は、一例として食品についてのレビューに「商品に満足している」「商品に不満がある」という文意が、それぞれどの程度含まれているかを分析しました。</p>
<p>分析を実行すると、スプレッドシーに入力されているテキストごとに、Craft Functions変数で指定したキーワードの文意の含有量が計算され、 Google スプレッドシートに出力されます。</p>
<p><img src="https://ik.imagekit.io/plaid/4ee22366-446e-452e-8653-dbfaa0fdf048/Monosnapsurvey_demo_data-Google%E3%82%B9%E3%83%95%E3%82%9A%E3%83%AC%E3%83%83%E3%83%88%E3%82%99%E3%82%B7%E3%83%BC%E3%83%882024-04-0514-40-59.png" alt="Monosnapsurvey_demo_data-Googleスプレッドシート2024-04-0514-40-59.png"></p>
<p>文意の大きさは 0~1 の数値で 1 に近いほど文意が強いことを表しています。<br>
一例として2行目の商品レビューを例にデータを読み解いてみると、文意の大きさは</p>
<ul>
<li>「商品に満足している」: 0.392</li>
<li>「商品に不満がある」：0.301</li>
</ul>
<p>となっています。そのため、このレビューは「商品に満足している」という意味合いの強いレビューだと解釈することができます。このように、この分析によるアウトプットは膨大な量のフリーテキストから定量的に文意を抽出することで、回答の傾向を数値化するのに役立つでしょう。</p>
<h2>注意点</h2>
<p>前提として、次の点に注意をしてください。</p>
<ul>
<li>KARTE Craft Functions, KARTE Craft AI Modules を利用していることを前提としています。</li>
<li>Google SpreadSheet API を使用することを推奨しています。</li>
<li>本ソリューションは Google Spread Sheet API を通わずに使用することも可能ですが、配布しているテンプレートは SpreadSheet を使ってデータの入出力を行うように作られているため、Spread Sheet APIを使用しない場合は Functions を適宜カスタマイズしてご利用ください。</li>
</ul>
<h2>設定手順</h2>
<p>設定の手順は次の通りです。</p>
<ol>
<li>API v2 アプリを作成する</li>
<li>API v2 アプリの アクセストークンを Craft Secret Manager に登録する</li>
<li>Googleサービスアカウントを作成する</li>
<li>GoogleサービスアカウントのJSONキーファイルの中身を Craft Secret Manager に登録する</li>
<li>Googleサービスアカウントに対象スプレッドシートへの権限を付与する</li>
<li>Craft Functionsのファンクションを作成する</li>
<li>Craft Functionsのエンドポイントを作成する</li>
</ol>
<p>順番に見てみましょう。</p>
<h3>1. API v2 アプリを作成する</h3>
<p>KARTEのAPIを利用するために、API v2アプリを作成します。<br>
<img src="https://ik.imagekit.io/plaid/a1b20746-4140-441d-8e46-3a5a74dc11ab/create_API_v2_App.png" alt="create_API_v2_App.png"></p>
<ul>
<li>[ストア &gt; API v2設定] からアプリを新規作成</li>
<li>[アプリタイプ] を <code>Craft</code> に設定</li>
<li>必要なscopeを追加
<ul>
<li><code>beta.craft.aimodules.openai.embeddings</code></li>
</ul>
</li>
<li>アプリを保存し、一度だけ表示されるアクセストークンをメモしておく</li>
</ul>
<h3>2. API v2 アプリの アクセストークンを Craft Secret Manager に登録する</h3>
<p>API v2 アプリのアクセストークンをCraft Functionsから安全に利用するために、Craft Secret Manager に登録します。</p>
<p><img src="https://ik.imagekit.io/plaid/6f229ee9-39aa-4e47-be81-f615f3b448f8/create_craft_secret.png" alt="create_craft_secret.png"></p>
<ul>
<li>[Craft &gt; シークレット] からシークレットを新規作成</li>
<li>[名前] に、わかりやすい名前を入力</li>
<li>メモしておいたAPI v2 アプリのアクセストークンを [シークレットの値] に入力し、作成</li>
<li>シークレット名をメモしておく</li>
</ul>
<h3>3. Googleサービスアカウントを作成する</h3>
<p>GoogleのサービスでAPIを利用するために、Googleサービスアカウントを作成します。</p>
<ul>
<li>Google Cloudのコンソール画面を開く
<ul>
<li>アカウントやプロジェクトが無い場合は作成してください</li>
</ul>
</li>
<li>[IAMと管理 &gt; サービスアカウント &gt; サービスアカウントを作成] から適当な名称のサービスアカウントを作成</li>
</ul>
<p><img src="https://ik.imagekit.io/plaid/227adf6a-c6bc-42ea-8235-8f3c762422eb/%E3%82%B9%E3%82%AF%E3%83%AA%E3%83%BC%E3%83%B3%E3%82%B7%E3%83%A7%E3%83%83%E3%83%882023-08-1413.15.34.png" alt="スクリーンショット2023-08-1413.15.34.png"></p>
<ul>
<li>作成したサービスアカウントを選択し、[キー &gt; 鍵を追加 &gt; 新しい鍵を作成] からJSON形式のキーファイルをダウンロード</li>
</ul>
<p><img src="https://ik.imagekit.io/plaid/faefbf7a-98af-4a2f-a672-e436f2e8cf0c/%E3%82%B9%E3%82%AF%E3%83%AA%E3%83%BC%E3%83%B3%E3%82%B7%E3%83%A7%E3%83%83%E3%83%882023-08-1413.16.12.png" alt="スクリーンショット2023-08-1413.16.12.png"></p>
<p>ダウンロードしたキーファイルは、後の手順で利用します。</p>
<h3>4. GoogleサービスアカウントのJSONキーファイルの中身を Craft Secret Manager に登録する</h3>
<p>Googleサービスアカウントの認証情報をCraft Functionsから安全に利用するために、Craft Secret Manager に登録します。</p>
<p><img src="https://ik.imagekit.io/plaid/1cb0539c-a074-47aa-b2f4-569647617236/create_service_account_secret.png" alt="create_service_account_secret.png"></p>
<ul>
<li>[Craft &gt; シークレット] からシークレットを新規作成</li>
<li>[名前] に、わかりやすい名前を入力</li>
<li>ダウンロードしたJSONキーファイルの中身を [シークレットの値] にそのまま入力し、作成</li>
<li>シークレット名をメモしておく</li>
</ul>
<h3>5. Googleサービスアカウントに対象スプレッドシートへの権限を付与する</h3>
<p>Google Sheets APIを有効化したとしても、個別のスプレッドシートに対して自由にアクセスできるわけではありません。スプレッドシート毎に、対象のGoogleサービスアカウントに対して権限を付与する必要があります。</p>
<ul>
<li>対象スプレッドシートを開き、右上の [共有]ボタンをクリック</li>
</ul>
<p><img src="https://ik.imagekit.io/plaid/1d490492-2ff5-409a-97e2-8f256b0eee49/%E3%82%B9%E3%82%AF%E3%83%AA%E3%83%BC%E3%83%B3%E3%82%B7%E3%83%A7%E3%83%83%E3%83%882023-08-1514.20.04.png" alt="スクリーンショット2023-08-1514.20.04.png"></p>
<ul>
<li>ダウンロードしたキーファイルに含まれるclient_emailの値を入力し、権限には [編集者] を選択して [送信]</li>
</ul>
<h3>6. Craft Functionsのファンクションを作成する</h3>
<p>Craft Functionsのファンクションを作成します。作成手順は次の通りです。</p>
<p><img src="https://ik.imagekit.io/plaid/f54845aa-6834-475f-ad9d-dfaf4b0ef4c5/create_craft_functions.png" alt="create_craft_functions.png"></p>
<ul>
<li>[Craft &gt; ファンクション &gt; 新規作成 &gt; テンプレートから作成] を選択</li>
<li>「 <strong>自由回答テキストに含まれる文意を Text Embedding で成分ごとにスコア化する</strong> 」というテンプレートを検索し[取得]ボタンをクリック</li>
<li>[反映] ボタンをクリック</li>
<li>[変数] タブで次の変数の値を設定する
<ul>
<li><code>LOG_LEVEL</code>
<ul>
<li>出力するログのレベル</li>
</ul>
</li>
<li><code>CRAFT_APP_TOKEN_SECRET_NAME</code>
<ul>
<li>API v2 アプリのアクセストークンを登録したシークレットの名前です。</li>
</ul>
</li>
<li><code>EMBEDDING_KEYWORDS</code>
<ul>
<li>に用いるキーワード</li>
<li>複数指定する場合はカンマ区切りで指定します。
<ul>
<li>例：<code>商品に満足している,商品に不満がある</code></li>
</ul>
</li>
</ul>
</li>
<li><code>SERVICE_ACCOUNT_KEY_SECRET</code>
<ul>
<li>Googleサービスアカウントを登録したシークレットの名前</li>
</ul>
</li>
<li><code>SPREADSHEET_ID</code>
<ul>
<li>GoogleスプレッドシートID</li>
<li>スプレッドシートのURLの <code>https://docs.google.com/spreadsheets/d/#{SPREADSHEET_ID}/</code> より取得できる英数字です。</li>
</ul>
</li>
<li><code>SHEET_NAME</code>
<ul>
<li>連携対象のGoogleスプレッドシートのシート名</li>
<li>例：<code>Sheet1</code></li>
</ul>
</li>
<li><code>TEXT_EMBEDDING_MODEL</code>
<ul>
<li>Text Embedding に使用するモデル名</li>
<li>現在使用できるモデルは <a href="https://developers.karte.io/reference/post_v2beta-craft-aimodules-openai-embeddings">Developer Portal - Enterprise grade embeddings</a> の <code>BODY PARAMS</code> より確認できます。</li>
</ul>
</li>
</ul>
</li>
<li>[保存] する</li>
<li>デプロイ完了後、[設定 &gt; ファンクションの有効化] にチェックを付ける</li>
</ul>
<p>なお、テンプレートのソースコードはGitHubで公開しています。<br>
<a href="https://github.com/plaidev/craft-codes/tree/main/craft-functions/survey-text-embedding-scoring">craft-codes/craft-functions/survey-text-embedding-scoring at main · plaidev/craft-codes</a></p>
<h2>7. Craft Functionsのエンドポイントを作成する</h2>
<p>作成したファンクションを外部から実行できるようにするためのエンドポイントを作成します。</p>
<p><img src="https://ik.imagekit.io/plaid/d76f89a5-49ec-425a-909c-729c7469bfa2/create_craft_functions_endpoint.png" alt="create_craft_functions_endpoint.png"></p>
<ul>
<li>作成したファンクションの編集画面から [設定 &gt; エンドポイント &gt; 作成] をクリック</li>
<li>表示されたエンドポイントURLをメモしておく</li>
</ul>
<h2>実際に動かしてみる</h2>
<p>実際に動作を確認してみましょう。まずスプレッドシートのA1に <code>input</code> というヘッダを作成し、続くA列のセルに分析したいテキストデータを入力します。</p>
<p><img src="https://ik.imagekit.io/plaid/443c9b62-01f7-4b3b-b660-143bbc5e0d6e/Monosnapsurvey_demo_data-Google%E3%82%B9%E3%83%95%E3%82%9A%E3%83%AC%E3%83%83%E3%83%88%E3%82%99%E3%82%B7%E3%83%BC%E3%83%882024-04-0516-19-46.png" alt="Monosnapsurvey_demo_data-Googleスプレッドシート2024-04-0516-19-46.png"></p>
<p>つづいて、[変数] タブの <code>EMBEDDING_KEYWORDS</code> に文意の大きさを測定したいキーワードを入力し、[保存]します。</p>
<p>最後に、ターミナルなどの適当な実行環境からエンドポイントへのリクエストを送信します。</p>
<pre><code class="language-bash">curl https://t.karte.io/hook/xxxxxxxx/craft/xxxxxxxx
</code></pre>
<p>問題なく設定できていれば、次のような表示が実現できるはずです。</p>
<p><img src="https://ik.imagekit.io/plaid/4ee22366-446e-452e-8653-dbfaa0fdf048/Monosnapsurvey_demo_data-Google%E3%82%B9%E3%83%95%E3%82%9A%E3%83%AC%E3%83%83%E3%83%88%E3%82%99%E3%82%B7%E3%83%BC%E3%83%882024-04-0514-40-59.png" alt="Monosnapsurvey_demo_data-Googleスプレッドシート2024-04-0514-40-59.png"></p>
<p>なおKARTE Datahubの<a href="https://developers.karte.io/docs/datahub-federation-table">フェデレーションテーブル</a>機能を使うことで、スプレッドシート上のデータに対してDatahubからSQLクエリを発行し、スプレッドシート上のデータを直接抽出することができます。その結果をDatahubのダッシュボードで可視化したり、紐付けテーブルにエクスポートしてKARTE上のユーザーに紐付けてセグメント条件に利用したりといった活用もできます。</p>
<h2>補遺1：スコアの算出の仕方</h2>
<p>文意の大きさを算出する際、本ソリューションでは以下の流れで数値計算を行なっています。</p>
<ol>
<li>Craft Functions変数で指定したキーワードを Text Embeddings によりベクトル化</li>
<li>スプレッドシートから入力されたテキストを Text Embeddings によりベクトル化</li>
<li>2つのベクトルのコサイン類似度を計算したものを文意の大きさとして採用</li>
</ol>
<h2>補遺2：ユークリッド距離を使って文意の大きさを算出する</h2>
<p>ユークリッド距離を使って文意の大きさを算出することもできます。ユークリッド距離を用いた文意の大きさの算出を有効化するには Craft Functions の[コード]の中から以下の行を検索し、該当行のコメントアウト、及びコメントインを行った上で[保存]してください。</p>
<pre><code class="language-javascript">async function outputData(sheets, scores) {
  const scoresFlatten = scores.slice(1).map(score =&gt; {
    const wk = [
      score.input,
      // コサイン類似度によりスコアリング
      ...score.scores.map(_score =&gt; _score.scoreDotProduct),
      // ユークリッド距離によりスコアリング
      // （使用するには、コサイン類似度によるスコアリングをコメントアウトし、以下の行をコメントインする）
      // ...score.scores.map(_score =&gt; _score.scoreEuclideanDistance),
    ];
    return wk;
  });
  const header = ['input', ...EMBEDDING_KEYWORDS.split(',')];

  // A1行にデータを出力
  updateSsValues(sheets, `${SHEET_NAME}!A1:Z`, [header, ...scoresFlatten]);
}
</code></pre>
<p>ユークリッド距離を使った算出では、埋め込みベクトル同士の幾何学的な距離（L2ノルム）を文書同士の類似度とみなします。ユークリッド距離を尺度とする場合、数値が0に近いほど元の文書の文意に近いと解釈します。コサイン類似度とは類似度の大小関係が逆になる点に注意してください。また、算出される数値の値域は 0~2 の間となります。</p>
<h2>おわりに</h2>
<p>今回は、KARTE Craft AIモジュールを使ったアンケートデータの高度な分析について紹介しました。大量のテキストデータの中から、感情情報や傾向を効率的に抽出できる強力な機能だと言えるでしょう。</p>
<p>アンケートを活用して顧客理解を深めることは、企業にとって重要な取り組みです。KARTE Craft AIモジュールを活用すれば、そのプロセスを大幅に効率化できます。ぜひ、この機能を活用して、アンケートデータの高度な分析に挑戦してみてください。</p>
<p>より深い顧客洞察が得られることで、製品・サービスの改善にもつながるはずです。KARTE Craft AIモジュールを最大限活用し、顧客理解を深めていきましょう！</p>
<hr>
<p>プレイドでは、世の中にインパクトを与える新しいソリューションを一緒につくる仲間を募集しています！ぜひ気軽にお問い合わせください。</p>
<p>↓ パートナー企業になりたい</p>
<ul>
<li><a href="https://ecosystem.plaid.co.jp/">CustomerData-Driven Solution を一緒に創りませんか？ | PLAID Ecosystem</a></li>
</ul>
<p>↓ PLAIDで働きたい</p>
<ul>
<li><a href="https://recruit.plaid.co.jp/requisitions/general-customer-engineer">Customer Engineer | 募集ポジション | 株式会社プレイド</a></li>
<li><a href="https://recruit.plaid.co.jp/requisitions/product-engineer">Product Engineer | 募集ポジション | 株式会社プレイド</a></li>
</ul>


自由記述のテキストに含まれる感情の強さを、ベクトル埋め込みにより肯定的/否定的などの感情ごとにスコア化します。

AIがテキストの意味的要素を数値化！KARTE Craft AI Modulesを使ったテキスト分析

Craft FunctionsからGoogle Analytics Data APIを利用し、GA4のファネル分析レポートを作成する方法を紹介します。

Craft FunctionsからGoogle Analytics Data APIを利用し、GA4のファネル分析レポートを作成する方法

<p>こんにちは、Customer EngineerのUGです！最近、肩の筋トレの成果が出てきて喜んでいます！</p>
<p>みなさんはWebページに来訪してくれたユーザーが花粉がたくさん飛んでいるエリアからアクセスして来た時に花粉症対策用の製品のレコメンドしたりしたいと考えたことは有りませんか？そこまでピンポイントなことは考えていなくても、ユーザーアクセスしているエリアの花粉情報を使ってなんか施策が考えられるかもなぁくらいは思ったことがあるのではないでしょうか？今回はGoogle Maps Platformの新機能である<a href="https://developers.google.com/maps/documentation/pollen/overview?hl=ja">Pollen API</a>を使って、Webブラウザ側から取得したユーザーの緯度経度のエリアの花粉情報をKARTEにイベントとして連携してみたいと思います！</p>
<h2>アウトプットイメージ</h2>
<p>最終的なアウトプットイメージは次の通りです。下記の画像のようにユーザーのアクセスしてきたエリアの花粉情報がイベントとしてKARTE側に発生している状態になります。<br>
<img src="https://ik.imagekit.io/plaid/a29eaf2f-7eb2-4862-93b3-97bd3261faf7/%E3%82%B9%E3%82%AF%E3%83%AA%E3%83%BC%E3%83%B3%E3%82%B7%E3%83%A7%E3%83%83%E3%83%882024-03-1617.21.24.png" alt="スクリーンショット2024-03-1617.21.24.png"></p>
<p>位置情報を利用する前に下記のようなダイアログでエンドユーザーに許諾を取ります。<br>
<img src="https://ik.imagekit.io/plaid/04581ac8-8397-42f7-8acb-15164106335a/%E3%82%B9%E3%82%AF%E3%83%AA%E3%83%BC%E3%83%B3%E3%82%B7%E3%83%A7%E3%83%83%E3%83%882024-02-2615.45.44.png" alt="スクリーンショット2024-02-2615.45.44.png"></p>
<p>構成図は次の通り。<br>
<img src="https://ik.imagekit.io/plaid/c673bc32-7b0c-4787-a57c-f61be62c3f7d/%E3%82%B9%E3%82%AF%E3%83%AA%E3%83%BC%E3%83%B3%E3%82%B7%E3%83%A7%E3%83%83%E3%83%882024-03-1618.09.55.png" alt="スクリーンショット2024-03-1618.09.55.png"></p>
<p>Webブラウザから緯度経度情報を取得してCraft Functionsに連携します。その情報を下にGoogle Maps PlatformのPollen APIを利用して、花粉情報を取得してKARTEイベントを発生させます。今回のブログでは緯度経度をWebブラウザ側から連携するためにKARTE Actionのスクリプト配信を利用します。スクリプト配信でなくとも今回のCraft Functionsは利用可能です。</p>
<h2>注意点</h2>
<p>前提として、次の点に注意をしてください。</p>
<ul>
<li>CraftのGrowthプラン以上を利用していることを前提としています</li>
<li>KARTE Webのスクリプト配信を利用していることを前提としています
<ul>
<li>スクリプト配信を利用しなくても今回のCraft Functionsは利用可能ですが今回のブログではスクリプト配信を利用することを前提に話していきます</li>
</ul>
</li>
<li>Google Maps Platformの利用を前提としています
<ul>
<li>リクエスト数に応じて<a href="https://developers.google.com/maps/billing/gmp-billing?hl=ja#geocoding">課金が発生する可能性</a>があります</li>
</ul>
</li>
</ul>
<h2>設定手順</h2>
<p>設定の手順は次の通りです。</p>
<ol>
<li>Craft Functionsのファンクションを作成する</li>
<li>Craft Functionsのエンドポイントを作成する</li>
<li>API v2 アプリを作成する</li>
<li>API v2 アプリの アクセストークンを Craft Secret Manager に登録する</li>
<li>Google Cloud PlatformでAPIキーを発行する</li>
<li>KARTE Actionからスクリプト接客を配信する</li>
</ol>
<p>順番に見てみましょう。</p>
<h3>1. Craft Functionsのファンクションを作成する</h3>
<p>Craft Functionsのファンクションを作成します。作成手順は次の通りです。</p>
<p><img src="https://ik.imagekit.io/plaid/f54845aa-6834-475f-ad9d-dfaf4b0ef4c5/create_craft_functions.png" alt="create_craft_functions.png"></p>
<ul>
<li>[Craft &gt; ファンクション &gt; 新規作成 &gt; テンプレートから作成] を選択</li>
<li>「 <strong>ブラウザ側から緯度経度の情報を取得して、Craft functionsからGoogle Maps PlatformのPollen APIを利用して花粉情報を取得してKARTEイベントを発生させる</strong> 」というテンプレートを検索し[取得]ボタンをクリック</li>
<li>[反映] ボタンをクリック</li>
<li>[変数] タブで次の変数の値を設定する
<ul>
<li><code>LOG_LEVEL</code>
<ul>
<li>出力するログのレベルです。ERROR/WARN/INFO/DEBUGから指定してください</li>
</ul>
</li>
<li><code>KARTE_APP_TOKEN_SECRET</code>
<ul>
<li>KARTE API v2アプリのtokenを登録したシークレット名を指定してください</li>
</ul>
</li>
<li><code>GOOGLE_MAPS_APIKEY</code>
<ul>
<li>Google Cloud Platformで発行したAPI Keyを指定してください</li>
</ul>
</li>
<li><code>EVENT_NAME</code>
<ul>
<li>KARTEで発生させるイベント名を指定してください</li>
</ul>
</li>
<li><code>FIELD</code>
<ul>
<li>イベント内で花粉情報を連携する際のフィールド名を指定してください</li>
</ul>
</li>
<li>[設定 &gt; ファンクションの有効化] にチェックを付けて [保存]</li>
</ul>
</li>
</ul>
<p>なお、テンプレートのソースコードはGitHubで公開しています。<br>
<a href="https://github.com/plaidev/craft-codes/tree/main/craft-functions/pollen-api">craft-codes/craft-functions/pollen-api at main · plaidev/craft-codes</a></p>
<h3>2. Craft Functionsのエンドポイントを作成する</h3>
<p>作成したファンクションを外部から実行できるようにするためのエンドポイントを作成します。</p>
<p><img src="https://ik.imagekit.io/plaid/d76f89a5-49ec-425a-909c-729c7469bfa2/create_craft_functions_endpoint.png" alt="create_craft_functions_endpoint.png"></p>
<ul>
<li>作成したファンクションの編集画面から [設定 &gt; エンドポイント &gt; 作成] をクリック</li>
<li>表示されたエンドポイントURLをメモしておく</li>
</ul>
<h3>3. API v2 アプリを作成する</h3>
<p>KARTEのAPIを利用するために、API v2アプリを作成します。<br>
<img src="https://ik.imagekit.io/plaid/a1b20746-4140-441d-8e46-3a5a74dc11ab/create_API_v2_App.png" alt="create_API_v2_App.png"></p>
<ul>
<li>[ストア &gt; API v2設定] からアプリを新規作成</li>
<li>[アプリタイプ] を <code>token</code> に設定</li>
<li>必要なscopeを追加
<ul>
<li><code>track.event.write</code></li>
</ul>
</li>
<li>アプリを保存し、一度だけ表示されるアクセストークンをメモしておく</li>
</ul>
<h3>4. API v2 アプリの アクセストークンを Craft Secret Manager に登録する</h3>
<p>API v2 アプリのアクセストークンをCraft Functionsから安全に利用するために、Craft Secret Manager に登録します。</p>
<p><img src="https://ik.imagekit.io/plaid/6f229ee9-39aa-4e47-be81-f615f3b448f8/create_craft_secret.png" alt="create_craft_secret.png"></p>
<ul>
<li>[Craft &gt; シークレット] からシークレットを新規作成</li>
<li>[名前] に、わかりやすい名前を入力</li>
<li>メモしておいたAPI v2 アプリのアクセストークンを [シークレットの値] に入力し、作成</li>
<li>シークレット名をメモしておく</li>
</ul>
<h3>5. Google Cloud PlatformでAPIキーを発行する</h3>
<p>Google Maps APIを利用するために、GCPにてAPIキーを発行します。<br>
GCPを利用したことがない方に関してはプロジェクトの作成から始めてください。参考までに<a href="https://cloud.google.com/resource-manager/docs/creating-managing-projects?hl=ja">GCPの公式ドキュメントはこちら</a>になります。</p>
<ul>
<li>[APIとサービス &gt; 認証情報 &gt; 認証情報を作成] からAPIキーを作成する</li>
<li>作成したAPIキーが以下のAPIを利用できるか確認してください
<ul>
<li>Pollen API</li>
</ul>
</li>
</ul>
<p>参考までに私が作成した際のコンソールの画面は下記になります。<br>
<img src="https://ik.imagekit.io/plaid/56a350ca-1bcf-477d-b5b0-c455bec7446d/%E3%82%B9%E3%82%AF%E3%83%AA%E3%83%BC%E3%83%B3%E3%82%B7%E3%83%A7%E3%83%83%E3%83%882024-03-1618.19.29.png" alt="スクリーンショット2024-03-1618.19.29.png"></p>
<h3>6. KARTE Actionからスクリプト接客を配信する</h3>
<p>Webブラウザから緯度経度情報をCraft Functionsに連携するために、KARTE Actionの接客サービスからスクリプト配信します。</p>
<ul>
<li>[KARTE Action &gt; 接客サービス] からスクリプト配信の接客を作成する</li>
<li>緯度経度を取得したいページとタイミングで配信する</li>
</ul>
<p>スクリプトの例として今回のブログの検証では下記のスクリプトを配信しています。参考スクリプトと接客アクションの編集画面は以下になります。<br>
<img src="https://ik.imagekit.io/plaid/935bb34f-1d7a-4e3c-8541-63cfe829619d/%E3%82%B9%E3%82%AF%E3%83%AA%E3%83%BC%E3%83%B3%E3%82%B7%E3%83%A7%E3%83%83%E3%83%882024-02-2813.59.08.png" alt="スクリーンショット2024-02-2813.59.08.png"></p>
<pre><code>if (navigator.geolocation) {
    navigator.geolocation.getCurrentPosition(sendPositionToServer, handleError);
} else {
    alert(&quot;Geolocation is not supported by this browser.&quot;);
}

function sendPositionToServer(position) {
    var latitude = position.coords.latitude;
    var longitude = position.coords.longitude;

    var endpoint = &quot;xxx&quot;;  // 送信先のCraft Functionsのエンドポイントを指定

    // HTTP POSTリクエストの設定
    fetch(endpoint, {
        method: &quot;POST&quot;,
        headers: {
            &quot;Content-Type&quot;: &quot;application/json&quot;,
        },
        body: JSON.stringify({
            latitude: latitude,
            longitude: longitude,
            visitor_id: &quot;#{visitor_id}&quot;,
        }),
    })
    .then(function(response) {
        if (!response.ok) {
            throw new Error(&quot;Network response was not ok&quot;);
        }
        return response.json();
    })
    .then(function(data) {
        console.log(&quot;Server response:&quot;, data);
    })
    .catch(function(error) {
        console.error(&quot;Error during fetch operation:&quot;, error);
    });
}

function handleError(error) {
    console.error(&quot;Error getting geolocation:&quot;, error.message);
}

</code></pre>
<p>問題なければ以下のように緯度経度取得のためのダイアログが表示されます。<br>
<img src="https://ik.imagekit.io/plaid/04581ac8-8397-42f7-8acb-15164106335a/%E3%82%B9%E3%82%AF%E3%83%AA%E3%83%BC%E3%83%B3%E3%82%B7%E3%83%A7%E3%83%83%E3%83%882024-02-2615.45.44.png" alt="スクリーンショット2024-02-2615.45.44.png"></p>
<h2>実際に動かしてみる</h2>
<p>実際に動作を確認してみましょう。<br>
まずはスクリプト配信をしているページでユーザーが訪問したら以下のようなダイアログが表示されます。<br>
<img src="https://ik.imagekit.io/plaid/04581ac8-8397-42f7-8acb-15164106335a/%E3%82%B9%E3%82%AF%E3%83%AA%E3%83%BC%E3%83%B3%E3%82%B7%E3%83%A7%E3%83%83%E3%83%882024-02-2615.45.44.png" alt="スクリーンショット2024-02-2615.45.44.png"></p>
<p>Craft Functions側でエラーが発生しなければ下記のようなイベントが発生するはずです。<br>
<img src="https://ik.imagekit.io/plaid/a29eaf2f-7eb2-4862-93b3-97bd3261faf7/%E3%82%B9%E3%82%AF%E3%83%AA%E3%83%BC%E3%83%B3%E3%82%B7%E3%83%A7%E3%83%83%E3%83%882024-03-1617.21.24.png" alt="スクリーンショット2024-03-1617.21.24.png"></p>
<h2>おわりに</h2>
<p>今回はWebブラウザ側から取得したユーザーの緯度経度のエリアの花粉情報をCraft Functions × Google Maps PlatformのPollen APIで取得してKARTEのに連携してみました。</p>
<p>これによりユーザーが花粉の多い地域からアクセスしてきた場合に花粉対策商品をレコメンドするといったような事が可能になります！これからのシーズン花粉症で苦しむ方も多いと思いますので是非活用してみてください！</p>
<hr>
<p>プレイドでは、世の中にインパクトを与える新しいソリューションを一緒につくる仲間を募集しています！ぜひ気軽にお問い合わせください。</p>
<p>↓ パートナー企業になりたい</p>
<ul>
<li><a href="https://ecosystem.plaid.co.jp/">CustomerData-Driven Solution を一緒に創りませんか？ | PLAID Ecosystem</a></li>
</ul>
<p>↓ PLAIDで働きたい</p>
<ul>
<li><a href="https://recruit.plaid.co.jp/requisitions/general-customer-engineer">Customer Engineer | 募集ポジション | 株式会社プレイド</a></li>
<li><a href="https://recruit.plaid.co.jp/requisitions/product-engineer">Product Engineer | 募集ポジション | 株式会社プレイド</a></li>
</ul>


KARTE Webのスクリプト配信機能を利用してブラウザ側から緯度経度の情報をCraft functionsに連携して、その情報を元にGoogle Maps PlatformのPollen APIを利用して花粉情報を取得してKARTEイベントを発生させるSolution

「緯度経度」からCraft Functions × Google Maps PlatformのPollen APIで「花粉情報」を取得してKARTEに連携する

Craft FunctionsからGoogle Analytics Data APIを利用し、GA4のユーザーセグメント分析レポートを作成する方法の紹介です。Google Analytics Data APIを使うと、GA4のデータ分析を簡単に行うことができ、今回はユーザーセグメント分析の方法をご紹介します。

Craft FunctionsからGoogle Analytics Data APIを利用し、GA4のユーザーセグメント分析レポートを作成する方法

<p>こんにちは、Customer Engineerの島本です！</p>
<p>先日友達と築地にあるトーセイホテル ココネ築地銀座プレミアに行ってきました！サウナよりも湯船に浸かっている時にどこからか吹いてくる冷風が気持ちよかったです。<br>
<img src="https://ik.imagekit.io/plaid/9cdd01c2-38c0-4f90-ba2a-ae3fadb22528/IMG_1719.jpg" alt="IMG_1719.jpg"></p>
<p>さて、Craft Functionsを使用すると、社内外のさまざまなシステムから情報を取得し、KARTEとの連携をスムーズに行うことができます。ただし、1 実行あたりの起動時間の上限が 10 秒という制約や、KARTE のサーバーサイドAPIのリクエスト制限があるため、複数件レコードを一括で連携するには設計上で工夫が必要でした。</p>
<p>しかし、Craft Functionsを使用してGoogle Cloud Storage にファイル保存することで、複数件レコードを一括で連携することができます！</p>
<h2>構成図</h2>
<p>構成図は次の通り。<br>
<img src="https://ik.imagekit.io/plaid/14fa7717-737d-4ff0-b5ab-ad5dcb5b35aa/blog%E7%94%A8.png" alt="blog用.png"></p>
<p>また、そもそも保存先のGCS の用意ができないという方もいると思いますが、<a href="https://developers.karte.io/docs/about-datahub">KARTE Datahub</a> をご利用頂いている場合は、KARTE からGCS バケットを払い出すことができます！<br>
今回はKARTE が払い出したGCS バケットを利用する方法で紹介します。</p>
<h2>注意点</h2>
<p>取得するデータサイズが大きくなると、APIからデータを取得する時間およびGCS への書き込み時間が伸びて、Craft Functions の実行時間制限を超過する可能性があります。</p>
<p>また、取得したデータがメモリサイズを超過することにより、Craft Functions が異常終了する可能性もあります。実際に処理できるデータ量を検証の上で本ソリューションの利用を検討してください。</p>
<h2>設定手順</h2>
<p>設定の手順は次の通りです。</p>
<ol>
<li>KARTE が払い出したGCS バケットへの権限付与を有効化する</li>
<li>Googleサービスアカウントを払い出す</li>
<li>サービスアカウントに対象バケットへの権限を付与する</li>
<li>サービスアカウントのJSONキーファイルの中身を Craft Secret Manager に登録する</li>
<li>Craft Functions でそのサービスアカウントを使ってファイルを保存する</li>
</ol>
<p>順番に見てみましょう。</p>
<h3>1. KARTE が払い出したGCS バケットへの権限付与を有効化する</h3>
<p>まず、KARTE Datahub の管理画面からGCS バケットへの権限付与を有効化します。</p>
<ul>
<li>グローバルナビゲーションの[データハブ設定]を開く</li>
<li>[サービスアカウント管理]のタブを開く</li>
<li>[GCSバケットへの権限付与済みGoogleサービスアカウント]の部分で、[権限付与]ボタンが表示されているか確認</li>
</ul>
<p><img src="https://ik.imagekit.io/plaid/895df45f-3a23-4868-a17c-4f42a9813625/%E3%82%B9%E3%82%AF%E3%83%AA%E3%83%BC%E3%83%B3%E3%82%B7%E3%83%A7%E3%83%83%E3%83%882024-04-0123.19.18.png" alt="スクリーンショット2024-04-0123.19.18.png"></p>
<p>有効化されていない場合は、営業担当にお問い合わせください。</p>
<h3>2. Googleサービスアカウントを作成する</h3>
<p>払い出しGCS バケットへの権限付与をするGoogleサービスアカウントを払い出します。</p>
<ul>
<li>[Datahub設定] &gt; [サービスアカウント管理]タブを開く</li>
<li>[払い出しGoogleサービスアカウント]の[Googleサービスアカウント作成]ボタンを押す</li>
<li>ダウンロードするkeyFileのキータイプを次の選択肢から選ぶ
<ul>
<li>JSON(推奨)</li>
<li>P12</li>
</ul>
</li>
<li>認証用のkeyFileが自動でダウンロードされる
<ul>
<li><strong>一度しかダウンロードできないため、大切に保管してください</strong></li>
</ul>
</li>
</ul>
<p><img src="https://ik.imagekit.io/plaid/836ee1fa-2e98-4aa6-ad9e-6fdc698db791/%E3%82%B9%E3%82%AF%E3%83%AA%E3%83%BC%E3%83%B3%E3%82%B7%E3%83%A7%E3%83%83%E3%83%882024-04-0123.23.35.png" alt="スクリーンショット2024-04-0123.23.35.png"></p>
<p>ダウンロードしたkeyFileは、後の手順で利用します。</p>
<h3>3. サービスアカウントに対象バケットへの権限を付与する</h3>
<p>払い出したサービスアカウントに対して権限を付与します。</p>
<ul>
<li>[GCSバケットへの権限付与済みGoogleサービスアカウント]の領域で、[権限付与]ボタンを押す</li>
<li>プルダウンから、先ほど払い出したサービスアカウントを選択する</li>
</ul>
<p><img src="https://ik.imagekit.io/plaid/fe23e8b4-3690-474d-8689-59656e6a2343/%E3%83%86%E3%82%99%E3%83%BC%E3%82%BF%E3%83%8F%E3%83%95%E3%82%99%E8%A8%AD%E5%AE%9A_-_%E7%A4%BE%E5%86%85%E6%A4%9C%E8%A8%BC%E7%94%A8_kasumi_shimamoto_-_KARTE.png" alt="データハブ設定_-社内検証用_kasumi_shimamoto-_KARTE.png"></p>
<h3>4. サービスアカウントのJSONキーファイルの中身を Craft Secret Manager に登録する</h3>
<p>Googleサービスアカウントの認証情報をCraft Functions から安全に利用するために、Craft Secret Manager に登録します。</p>
<p><img src="https://ik.imagekit.io/plaid/1cb0539c-a074-47aa-b2f4-569647617236/create_service_account_secret.png" alt="create_service_account_secret.png"></p>
<ul>
<li>[Craft &gt; シークレット] からシークレットを新規作成</li>
<li>[名前] に、わかりやすい名前を入力</li>
<li>ダウンロードしたJSONキーファイルの中身を [シークレットの値] にそのまま入力し、作成</li>
<li>シークレット名をメモしておく</li>
</ul>
<h3>5. Craft Functions でそのサービスアカウントを使ってファイルを保存する</h3>
<p>最後に、実際にCraft Functionsから外部APIを叩いて、GCS バケットに保存してみます。<br>
今回は情報を取得するAPIとして、<a href="https://jsonplaceholder.typicode.com/">JSONPlaceholder</a> を利用します。</p>
<p>作成手順は次の通りです。<br>
<img src="https://ik.imagekit.io/plaid/f54845aa-6834-475f-ad9d-dfaf4b0ef4c5/create_craft_functions.png" alt="create_craft_functions.png"></p>
<ul>
<li>[Craft &gt; ファンクション &gt; 新規作成 &gt; テンプレートから作成] を選択</li>
<li>「 <strong>外部APIから取得したデータをGoogle Cloud Storageにファイル保存する</strong> 」というテンプレートを検索し[取得]ボタンをクリック</li>
<li>[反映] ボタンをクリック</li>
<li>[変数] タブで次の変数の値を設定する
<ul>
<li><code>LOG_LEVEL</code>
<ul>
<li>出力するログのレベルです</li>
</ul>
</li>
<li><code>SERVICE_ACCOUNT_KEY_SECRET</code>
<ul>
<li>先ほど作成したシークレットの名前を指定します</li>
</ul>
</li>
<li><code>API_ENDPOINT</code>
<ul>
<li>データ取得元である外部サービスのAPIエンドポイントです</li>
<li>例：https://jsonplaceholder.typicode.com/posts</li>
</ul>
</li>
<li><code>BUCKET_NAME</code>
<ul>
<li>保存する先のGCS のバケット名です</li>
<li>例：karte-data-{{api_key}}
<ul>
<li>{{api_key}}の部分は、実際のapi_keyに置き換えてください</li>
</ul>
</li>
</ul>
</li>
<li><code>FILE_PATH</code>
<ul>
<li>保存するファイルのパスです</li>
<li>例：test/demo_data.json</li>
</ul>
</li>
</ul>
</li>
<li>[保存] する</li>
<li>デプロイ完了後、[設定 &gt; ファンクションの有効化] にチェックを付ける</li>
</ul>
<p>なお、サンプルコードは、下記URLで公開しています。<br>
<a href="https://github.com/plaidev/craft-codes/tree/main/craft-functions/fetch-external-api-and-save-file-to-gcs">craft-codes/craft-functions/fetch-external-api-and-save-file-to-gcs at main · plaidev/craft-codes</a></p>
<p>以下、重要な点をかいつまんで説明します。</p>
<p>サンプルコードでは、GCS バケット上のファイルをKARTE Datahub に連携したいケースを想定して、Datahub で取り込み可能な改行区切りのJSON データに加工しています。</p>
<p>実際に利用する際には、APIのレスポンスデータ形式に合わせて変更してください。</p>
<pre><code>function formatDataToJSONLines(responseData) {
  return responseData.map(obj =&gt; JSON.stringify(obj)).join('\n');
}
</code></pre>
<p>下記関数でバケット名、ファイルのパスを指定してGCS バケットにファイルをアップロードしています。</p>
<pre><code>async function uploadDataToStorage(bucketName, filePath, jsonLinesData, jsonKey, logger) {
  const storage = new Storage({ credentials: jsonKey });
  const bucket = storage.bucket(bucketName);

  const blob = bucket.file(filePath);
  const stream = blob.createWriteStream({
    metadata: {
      contentType: 'application/json',
    },
  });

  return new Promise((resolve, reject) =&gt; {
    stream.on('error', err =&gt; {
      logger.error('Upload Error:', err);
      reject(err);
    });

    stream.on('finish', () =&gt; {
      logger.log(`Uploaded: ${filePath}`);
      resolve();
    });

    stream.end(jsonLinesData);
  });
}
</code></pre>
<p>とても簡単ですね！</p>
<p>最後に定期的にAPI からデータを取得するために、Craft Scheduler の設定をします。</p>
<p><img src="https://ik.imagekit.io/plaid/1a603aa3-3952-4232-ba1a-b4575047dedd/%E3%82%B9%E3%82%AF%E3%83%AA%E3%83%BC%E3%83%B3%E3%82%B7%E3%83%A7%E3%83%83%E3%83%882024-02-1318.25.41.png" alt="スクリーンショット2024-02-1318.25.41.png"></p>
<ul>
<li>Craft Functionsの<code>設定タブ</code>を開きます</li>
<li>スケジュールを有効化し、cron形式（JST）で実行時間を指定します</li>
</ul>
<p>設定は以上になります。</p>
<h2>実際に動かしてみる</h2>
<p>実際に動作を確認してみましょう！</p>
<p>前述のサンプルコードに必要な定数を入力した内容でCraft Functionsを作成し、実際に実行してみます。</p>
<p><img src="https://ik.imagekit.io/plaid/3fabf6ee-50c0-4ab5-a195-5ad77a389c16/%E3%83%86%E3%82%99%E3%82%B9%E3%82%AF%E3%83%88%E3%83%83%E3%83%95%E3%82%9A_%E2%80%94_-zsh_%E2%80%94_173%C3%9746.png" alt="デスクトップ_—-zsh—_173×46.png"></p>
<p>gsutilを使ってGCS バケット上に保存されていることを確認できました！</p>
<p><img src="https://ik.imagekit.io/plaid/b19f0ee2-7122-409a-aa43-ef9e617ca054/%E3%82%B9%E3%82%AF%E3%83%AA%E3%83%BC%E3%83%B3%E3%82%B7%E3%83%A7%E3%83%83%E3%83%882024-03-2610.03.39.png" alt="スクリーンショット2024-03-2610.03.39.png"><br>
また、ファイルの中身も改行区切りのJSON データで保存されていることが確認できます。<br>
これで問題なくKARTE Datahub に連携できますね！</p>
<h2>おわりに</h2>
<p>今回は外部APIから取得したデータをGoogle Cloud Storageにファイル保存する方法について紹介しました。</p>
<p>このソリューションを活用すれば、社内外のさまざまなシステムから情報を取得してKARTE Datahub に連携することができるため、できることの幅が広がりますね！ぜひ皆さんも試してみてください！</p>
<hr>
<p>プレイドでは、世の中にインパクトを与える新しいソリューションを一緒につくる仲間を募集しています！ぜひ気軽にお問い合わせください。</p>
<p>↓ パートナー企業になりたい</p>
<ul>
<li><a href="https://ecosystem.plaid.co.jp/">CustomerData-Driven Solution を一緒に創りませんか？ | PLAID Ecosystem</a></li>
</ul>
<p>↓ PLAIDで働きたい</p>
<ul>
<li><a href="https://recruit.plaid.co.jp/requisitions/general-customer-engineer">Customer Engineer | 募集ポジション | 株式会社プレイド</a></li>
<li><a href="https://recruit.plaid.co.jp/requisitions/product-engineer">Product Engineer | 募集ポジション | 株式会社プレイド</a></li>
</ul>


外部APIから取得したデータを改行区切りのJSON形式に整形し、Google Cloud Storageにファイル保存します。

外部APIから取得したデータをGoogle Cloud Storageにファイル保存する

<p>こんにちは。エンジニアの矢澤です。今回はKARTE Craftの新機能である <strong>ファンクションのIPを固定する</strong> 機能 (固定IP機能) を紹介します。</p>
<p>KARTE CraftはKARTEと外部サービスをリアルタイムに連携できますが、サービスによっては <strong>送信元IP制限</strong> でアクセス元を制限している場合があります。これまでCraft FunctionsのIPアドレスは固定ではありませんでしたが、今回のアップデートにより、KARTEプロジェクトごとに払い出した固定のIPアドレスで通信ができるようになります。</p>
<p>この記事では固定IPアドレス機能の設定方法を紹介し、実際にIPアドレスが固定されていることを検証します。</p>
<h1>「ファンクションのIPアドレスを固定する」機能とは</h1>
<p>機能を試す前に、簡単に固定IP機能の概要を説明します。</p>
<h2>IPアドレスとは</h2>
<p>ネットワークに接続されている多くの端末（コンピュータやスマートフォンなど）は<strong>IPアドレス</strong>を使って他の端末やサービスに接続します。特に、インターネットに接続する際には <strong>グローバルIPアドレス</strong> と呼ばれるIPアドレスが割り当てられます。Craft Functionsも例外ではなく、インターネット上のサービスへの接続時にはグローバルIPアドレスを使って通信を行います。</p>
<h2>送信元IP制限と固定IP機能</h2>
<p>インターネット上のサービスがアクセス元を制限する方法には、ID/パスワードやアクセス用のトークンを使った認証など様々な方式があります。その中の一つに、上で説明したIPアドレスを使ってアクセス許可・拒否を行う <strong>送信元IP制限</strong> という方法があります。</p>
<p>インターネット上のサービスにおける送信元IP制限では、アクセス元のグローバルIPアドレスを許可リスト (もしくは拒否リスト) として保持しておき、リストに当てはまる (当てはまらない) グローバルIPアドレスからの接続のみを許可します。このようなシステムに接続するクライアントは、<strong>固定のグローバルIPアドレス</strong> を使って当該サービスに接続する必要があります。</p>
<p>冒頭で話した通り、KARTE Craftはこれまで <strong>外部接続時のIPアドレスが固定であることを保証していません</strong> でしたが、今回のアップデートで固定のグローバルIPアドレスが利用できるようになりました。これによって送信元IP制限がかけられたシステムにも接続できるようになりました。</p>
<p><img src="https://ik.imagekit.io/plaid/a4f11edf-eea0-4e62-913e-19dfda15b344/%E3%82%B9%E3%82%AF%E3%83%AA%E3%83%BC%E3%83%B3%E3%82%B7%E3%83%A7%E3%83%83%E3%83%882023-10-2514.22.39.png" alt="スクリーンショット2023-10-2514.22.39.png"></p>
<h1>設定してみる</h1>
<p>ここからは実際に固定IP機能を有効化し、実際にIPアドレスが固定されていることを確かめていきます。</p>
<p>操作手順はドキュメント（<a href="https://craft.developers.karte.io/craft-functions/static-ip">ファンクションのIPアドレスを固定する</a>）にも書いてありますので、興味のある方は併せてご確認ください。</p>
<h2>固定IP機能の有効化</h2>
<p>固定IP機能はKARTE CraftのEnterpriseプランから利用できます。利用の際にはプレイドの営業もしくはカスタマーサクセス担当者までご連絡ください。</p>
<h2>固定IPを利用する</h2>
<p>固定IP機能が有効化されると、KARTEプロジェクトに1つのIPアドレスが払い出されます。管理画面の [Craft] &gt; [設定] からIPアドレスが確認できます。</p>
<p><img src="https://ik.imagekit.io/plaid/0d907a7a-25df-47f4-95da-ba27e1d7afcc/%E3%82%B9%E3%82%AF%E3%83%AA%E3%83%BC%E3%83%B3%E3%82%B7%E3%83%A7%E3%83%83%E3%83%882023-10-2513.31.14.png" alt="スクリーンショット2023-10-2513.31.14.png"></p>
<p>ファンクションがこのIPアドレスを使うためには、ファンクションの設定で「ファンクションの外部IPアドレスを固定する」にチェックを入れて保存する必要があります。。</p>
<p><img src="https://ik.imagekit.io/plaid/7bb8d51e-2408-48d0-9d9f-e2b77864dc62/%E3%82%B9%E3%82%AF%E3%83%AA%E3%83%BC%E3%83%B3%E3%82%B7%E3%83%A7%E3%83%83%E3%83%882023-10-2513.35.16.png" alt="スクリーンショット2023-10-2513.35.16.png"></p>
<h2>ファンクションをデプロイして動作を検証する</h2>
<p>今回は検証用に <a href="https://httpbin.org/#/">httpbin.org</a> を使って送信元IPを確認します。httpbin.org はシンプルなHTTP APIを提供しており、その一つに送信元のグローバルIPアドレスを返却する <code>/ip</code> というエンドポイントがあります。今回はファンクションから <code>https://httpbin.org/ip</code> にリクエストを行い、その値をログとして出力することで、ファンクションが利用するグローバルIPアドレスを確認します。</p>
<p>実際のコードは次のとおりです：</p>
<pre><code class="language-js">const LOG_LEVEL = 'DEBUG';

export default async function (data, { MODULES }) {
  const { initLogger } = MODULES;
  const logger = initLogger({logLevel: LOG_LEVEL});

  const res = await fetch('https://httpbin.org/ip');
  const origin = await res.json();
  logger.log(origin);
}
</code></pre>
<p>このコードをファンクションとして保存します。</p>
<ul>
<li>modulesは <code>{}</code> としておきます。</li>
<li>ファンクション画面右上の「有効化」にチェックを入れておきます。</li>
<li>保存時に設定タブで「ファンクションの外部IPアドレスを固定する」にチェックを入れます。</li>
</ul>
<p>ファンクションの保存に成功したら、Craft EndpointもしくはCraft Schedulerで起動します。</p>
<ul>
<li><a href="https://craft.developers.karte.io/craft-functions/triggers/scheduler">Craft Scheduler</a></li>
<li><a href="https://craft.developers.karte.io/craft-functions/triggers/endpoint">Craft Endpoint</a></li>
</ul>
<p>ファンクションが起動すると次のようにログが記録されます。</p>
<p><img src="https://ik.imagekit.io/plaid/eaea79ee-0deb-4579-a7f3-994a80b8fcc6/%E3%82%B9%E3%82%AF%E3%83%AA%E3%83%BC%E3%83%B3%E3%82%B7%E3%83%A7%E3%83%83%E3%83%882023-10-2513.17.26.png" alt="スクリーンショット2023-10-2513.17.26.png"></p>
<p>ログの <code>origin</code> の値がファンクションの送信元IPです。ここではマスクしていますが、ファンクションの固定IP設定が有効であれば、プロジェクトに払い出された固定IPアドレスが表示されます。このようにして、固定IP設定によってIPアドレスが固定されることが確認できました。</p>
<h1>おわりに</h1>
<p>今回は新機能である固定IP機能を紹介しました。企業の内部システムはトークンベースのアクセス制限に加えて送信元IPによる制御を行っていることがあります。このアップデートにより、KARTEと企業システムとの連携の可能性がより広がりましたので、是非とも有効活用していただきたいと思います！</p>
<p>改めてですが、固定IP機能はKARTE CraftのEnterpriseプランからの提供となります。利用に際してはプレイドの営業・サクセスにお問い合わせください。</p>
<hr>
<p>プレイドでは、世の中にインパクトを与える新しいソリューションを一緒につくる仲間を募集しています！<br>
ぜひ気軽にお問い合わせください。</p>
<p>↓ パートナー企業になりたい</p>
<ul>
<li><a href="https://ecosystem.plaid.co.jp/">CustomerData-Driven Solution を一緒に創りませんか？ | PLAID Ecosystem</a></li>
</ul>
<p>↓ PLAIDで働きたい</p>
<ul>
<li><a href="https://recruit.plaid.co.jp/requisitions/general-customer-engineer">Customer Engineer | 募集ポジション | 株式会社プレイド</a></li>
<li><a href="https://recruit.plaid.co.jp/requisitions/product-engineer">Product Engineer | 募集ポジション | 株式会社プレイド</a></li>
</ul>


Craft Functionsの外部リクエスト用IPアドレスを固定する機能（固定IP機能）をリリースしました。この記事では実際に設定を行い、ファンクションのIPアドレスが固定されることを確認します。

「Craft FunctionsのIPアドレスを固定する」機能をリリースしました！

<p>こんにちは、Customer Engineerの島本です！<br>
こないだ同僚に誘われて7月にオープンしたHUBHUB御徒街に行ってきたのですが、貸し切りでフィンランドサウナを楽しみつつ、電車の音を聞きながら整う空間が面白かったです！<br>
<img src="https://ik.imagekit.io/plaid/d39818f2-235b-4807-beb4-50e88d068f1a/IMG_1546.jpg" alt="IMG_1546.jpg"></p>
<p>さて、KARTE では<a href="https://support.karte.io/post/37WjobkPgizqvwhIY97dpH">ユーザーに対して表示回数やクリック回数に応じた接客サービスの配信停止条件</a>を設定できますが、ユーザーに対してではなく、「<strong>接客サービスに対して配信数やクリック数に応じた配信停止条件を指定したい</strong>」と思ったことはありませんか？</p>
<p>例えば次のようなケースです。</p>
<ul>
<li>KARTE の接客サービスを広告枠として活用していて、配信数やクリック数が一定の閾値に達したら停止したい</li>
<li>KARTE のアンケート接客でアンケート回答数が一定の閾値に達したら停止したい</li>
</ul>
<p>KARTE とDatahub を駆使して実現することも出来ますが、Datahub の特性上データの更新がバッチになるため、接客を停止するのに最短でも1時間のラグが出てしまいます。</p>
<p>しかし、<a href="https://solution.plaid.co.jp/202310-craft-counter">Craft Counter</a> を使うことで<strong>リアルタイム</strong>に接客を停止することを実現できます！<br>
今回はCraft Counter を使用して「配信数やクリック数に応じた接客サービスの自動停止」を実装する手順を紹介します。</p>
<h1>アウトプットイメージ</h1>
<p>接客サービス側のアクション設定で配信制御をしたい項目（配信数やクリック数）と上限回数を設定できるように実装しました。<br>
<img src="https://ik.imagekit.io/plaid/6b9d1026-afdd-42b9-8321-1a56a6fbe32f/%E3%82%B9%E3%82%AF%E3%83%AA%E3%83%BC%E3%83%B3%E3%82%B7%E3%83%A7%E3%83%83%E3%83%882023-10-1717.16.41.png" alt="スクリーンショット2023-10-1717.16.41.png"></p>
<h1>処理の流れ</h1>
<p>全体の処理の流れは、次の通りです。<br>
<img src="https://ik.imagekit.io/plaid/f18a3e31-4618-408e-bdf0-54b6d63a865b/Untitled-2023-07-28-0049.png" alt="Untitled-2023-07-28-0049.png"></p>
<p>接客サービス機能とCraft Functionsの連携では、次の2つの機能を利用します。</p>
<ul>
<li><a href="https://craft.developers.karte.io/craft-functions/triggers/endpoint">Craft Endpoint トリガー</a>
<ul>
<li>Craft Functionを実行するためのHTTPエンドポイント</li>
</ul>
</li>
<li><a href="https://developers.karte.io/reference/post_v2beta-action-campaign-toggleenabled">Toggle campaign's enabled status API</a>
<ul>
<li>接客サービスの公開・非公開を制御するAPI</li>
</ul>
</li>
</ul>
<h1>実装手順</h1>
<p>実装の手順は次の通りです。</p>
<ol>
<li>API v2 アプリを作成する</li>
<li>API v2 アプリの アクセストークンを Craft Secret Manager に登録する</li>
<li>Craft Functionsを作成する</li>
<li>Craft Functionsのエンドポイントを作成する</li>
<li>Functionと連携する接客を作成する</li>
</ol>
<p>順番に見てみましょう。</p>
<h2>1. API v2 アプリを作成する</h2>
<p>まず、Toggle campaign's enabled status API を利用するためのAPI v2アプリを作成します。<br>
<img src="https://ik.imagekit.io/plaid/bfe2f6a8-b78c-4c95-ad91-db59ecc03a9b/image(5).png" alt="image(5).png"></p>
<ul>
<li>[ストア &gt; API v2設定] からアプリを新規作成</li>
<li>[アプリタイプ] を <code>token</code> に設定</li>
<li>必要なscopeを追加
<ul>
<li><code>beta.action.campaign.toggleEnabled</code>: API に必要</li>
</ul>
</li>
<li>アプリを保存し、一度だけ表示されるアクセストークンを控えておく</li>
</ul>
<p>「アプリタイプ」は後から変更できないため、誤って作成した場合は、アプリを再度作成し直してください。</p>
<h2>2. API v2 アプリの アクセストークンを Craft Secret Manager に登録する</h2>
<p>API v2 アプリのアクセストークンを Craft Secret Manager のシークレットとして登録します。それにより、秘匿すべきアクセストークンをファンクション上に直接記述する必要が無くなります。<br>
<img src="https://ik.imagekit.io/plaid/116765b1-4d21-4d74-8d3e-e5a4e4431e5b/image(6).png" alt="image(6).png"></p>
<ul>
<li>[Craft &gt; シークレット] からシークレットを新規作成</li>
<li>控えておいたアクセストークンを貼り付けて、適当な名前を付けて保存</li>
</ul>
<p>作成したシークレットの名前は、最後に作成するCraft Functions のファンクション中に記載します。</p>
<h2>3. Craft Functionsを作成する</h2>
<p>次に、接客サービスからのリクエストを受け付けるCraft FunctionsのFunctionを作成します。サンプルとなるソースコードは、GitHubで公開しています。<br>
<a href="https://github.com/plaidev/craft-codes/tree/main/craft-functions/stop-campaign-by-imp-click">craft-codes/craft-functions/stop-campaign-by-imp-click at main · plaidev/craft-codes</a></p>
<p>作成手順は次の通りです。</p>
<ul>
<li>[Craft &gt; ファンクション] からファンクションを新規作成</li>
<li>サンプルコードからコードやモジュールをコピー</li>
<li>Functionを有効化して保存</li>
</ul>
<p>サンプルコードでは次の機能が実装されています。</p>
<ul>
<li>接客サービスID毎の配信数 or クリック数をCraft Counter 上でincrement する</li>
<li>Craft Counter 上でincrement する際に上限値と比較し、上限値を超えていた場合にToggle campaign's enabled status API にリクエストを送信する</li>
</ul>
<p>increment する項目（配信数 or クリック数）と上限値については接客サービス側で設定するため、後ほど説明します。また、上記処理には数秒程度の時間を要するため、この実装方法では上限値に達した際に接客を即座に停止できないことに留意してください。</p>
<h2>4. Craft Functionsのエンドポイントを作成する</h2>
<p>Craft Functionsが作成できたら、接客側から実行出来るようにするためのエンドポイントを作成します。</p>
<p><img src="https://ik.imagekit.io/plaid/a1c8021e-4690-40ad-8e91-2efb5cad5176/image(7).png" alt="image(7).png"></p>
<ul>
<li>作成したファンクションの編集画面で [設定] タブを開く</li>
<li>[エンドポイント] 欄の [作成] ボタンを押す</li>
</ul>
<p>作成したエンドポイントのURLは接客サービス側の実装で利用するので手元に控えておきます。</p>
<h2>5. Functionと連携する接客を作成する</h2>
<p>最後に、配信数やクリック数に応じて自動停止したい接客サービスを実装します。細かい接客サービスの設定方法は割愛して、アクションのHTML/JavaScriptのサンプル実装を掲載します。</p>
<h3>アクションのJavaScript例</h3>
<p><strong>実装のポイント</strong></p>
<ul>
<li>配信を停止したい条件に合わせてCraft 側に接客サービスIDと上限値のデータを含めてリクエストを送信</li>
<li>クリック数に応じた配信停止を行いたい場合は、クリックしたタイミングでリクエストを送信する必要があるため、widget.method を使ってHTML とバインドするイベントハンドラを定義</li>
</ul>
<pre><code>// POSTリクエストを送信するためのデータ
var postData = {
    campaignId: &quot;#{campaign_id}&quot;, 
    limitNumber: #{limitNumber}
};

// FunctionsのエンドポイントURL
var endpointUrl = &quot;#{craft_endpoint}&quot;; 

// 条件分岐(クリックの場合)
widget.method(&quot;clicked&quot;, function(e){
    if( #{click} ){
        craftPost();
    }
});

// ウィジェットを表示
widget.show();

// 条件分岐（表示回数の場合）
if( #{impression} ){
    craftPost();
}

// POSTリクエスト処理関数
function craftPost() {
    fetch(endpointUrl, {
        method: &quot;POST&quot;,
        mode: &quot;cors&quot;,
        headers: {
            &quot;Content-Type&quot;: &quot;application/json&quot;, 
        },
        body: JSON.stringify(postData), 
    })
    .then(function(result) {
        if (!result.ok) {
            throw new Error(result);
        }
    })
    .catch(function(error) {
        // エラーハンドリング
        console.error(&quot;エラー:&quot;, error);
    });
}

</code></pre>
<h3>アクションのHTML例</h3>
<p><strong>実装のポイント</strong></p>
<ul>
<li>クリック数に応じた配信停止を行いたい場合は、先程widget.method で定義したイベントハンドラをkrt-on に指定</li>
</ul>
<pre><code>&lt;div class=&quot;banner-wrapper&quot;&gt;
    &lt;a krt-on:click=&quot;clicked&quot; href=&quot;#{href}&quot;&gt;
        &lt;img src=&quot;#{img}&quot; class=&quot;banner-image&quot;&gt;
    &lt;/a&gt;
&lt;/div&gt;
</code></pre>
<h3>アクションの静的変数の設定例</h3>
<p>JavaScript やHTML 内で変数を呼び出しているため、以下の通りに<a href="https://support.karte.io/post/3TPVVSzxiA6U3MYNRj25JJ">静的変数</a>を設定します。</p>
<p><img src="https://ik.imagekit.io/plaid/cd419c60-6de2-4831-8a89-910952467c20/%E3%82%B9%E3%82%AF%E3%83%AA%E3%83%BC%E3%83%B3%E3%82%B7%E3%83%A7%E3%83%83%E3%83%882023-10-170.27.46.png" alt="スクリーンショット2023-10-170.27.46.png"></p>
<p>以上で設定は完了です！</p>
<h1>実際に動かしてみる</h1>
<p>では、実際に動かしてみましょう！！！！<br>
今回は160×600のバナーを表示回数 10回で自動停止するように設定してみました。<br>
<img src="https://ik.imagekit.io/plaid/1c79eb83-f4d2-47d1-9a29-4e0faf1b6de0/%E3%82%B9%E3%82%AF%E3%83%AA%E3%83%BC%E3%83%B3%E3%82%B7%E3%83%A7%E3%83%83%E3%83%882023-10-171.02.11.png" alt="スクリーンショット2023-10-171.02.11.png"></p>
<p>Craft Functions のLog Level を DEBUG にすると、接客が配信される度に該当の接客サービスIDとincrement した数と指定した上限値を確認することができます。<br>
そして、increment した数が上限値に達して接客サービスが停止した際に表示される&quot;Campaign has been successfully stopped.&quot;というログを確認することが出来ました！</p>
<p><img src="https://ik.imagekit.io/plaid/ff31e4da-65d2-4be8-b782-20a514da4cb3/%E3%82%B9%E3%82%AF%E3%83%AA%E3%83%BC%E3%83%B3%E3%82%B7%E3%83%A7%E3%83%83%E3%83%882023-10-171.10.51.png" alt="スクリーンショット2023-10-171.10.51.png"></p>
<p>接客サービス側も確認してみると、該当接客が停止していますね！！！<br>
<img src="https://ik.imagekit.io/plaid/5400f362-f2a0-4071-baca-358a7a446a8c/%E3%82%B9%E3%82%AF%E3%83%AA%E3%83%BC%E3%83%B3%E3%82%B7%E3%83%A7%E3%83%83%E3%83%882023-10-171.11.52.png" alt="スクリーンショット2023-10-171.11.52.png"></p>
<h1>おわりに</h1>
<p>今回は「配信数やクリック数に応じた接客サービスの自動停止」をCraft Counterで実装する方法について紹介しました。</p>
<p>これまでKARTE はWeb 接客として活用いただくことが多かったのですが、冒頭お伝えした通り、この仕組みを活用することでKARTE を新たな広告サービスとして提供することもできるようになります。</p>
<p>さらに、KARTE で収集している1st Party Customer Data を活用することで、精度の高いターゲティングが可能となり、広告の効果的な配信が実現できるため、昨今注目されているリテールメディアも簡単に構築できるのです。</p>
<p>今までKARTE で蓄積してきたデータを新たなビジネスチャンスとして活用できるなんて可能性が広がりますね！</p>
<hr>
<p>プレイドでは、世の中にインパクトを与える新しいソリューションを一緒につくる仲間を募集しています！<br>
ぜひ気軽にお問い合わせください。</p>
<p>↓ パートナー企業になりたい</p>
<ul>
<li><a href="https://ecosystem.plaid.co.jp/">CustomerData-Driven Solution を一緒に創りませんか？ | PLAID Ecosystem</a></li>
</ul>
<p>↓ PLAIDで働きたい</p>
<ul>
<li><a href="https://recruit.plaid.co.jp/requisitions/general-customer-engineer">Customer Engineer | 募集ポジション | 株式会社プレイド</a></li>
<li><a href="https://recruit.plaid.co.jp/requisitions/product-engineer">Product Engineer | 募集ポジション | 株式会社プレイド</a></li>
</ul>


Craft Counter を使った「配信数やクリック数に応じた接客サービスの自動停止」の方法について紹介します。

「配信数やクリック数に応じた接客サービスの自動停止」をCraft Counterで実装する

<p>こんにちは、Customer Engineerのgamiです！最近は、「 <a href="https://www.asken.jp/">あすけん</a> 」で食べたものを記録すると減量できるかという実験をしています。</p>
<p>さて、KARTEを利用している企業の方からよく実現方法を相談される施策として、 <strong>「クーポン在庫の順次払い出し」</strong> があります。外部のクーポンシステムからクーポンコードの在庫を予め出力しておき、クーポン取得条件を満たしたユーザーに対してWeb上で順番にクーポンコードを払い出していく、といった内容です。</p>
<p>この「クーポン在庫の順次払い出し」においてクリアすべき最も大きな課題は、 <strong>「同一クーポンコードを複数ユーザーに払い出さないようにする」</strong> という点です。素朴に実装すると、同時にアクセスした複数のユーザーに対して同じクーポンコードを払い出してしまうリスクがあります。それを回避するための制御を実現するには、KARTEの基本機能だけでは足りず、KARTE Craftによる実装が必要になります。</p>
<p>今回は、先日リリースされた <a href="https://solution.plaid.co.jp/202310-craft-counter">Craft Counter</a> の特性をうまく利用して「クーポン在庫を順次払い出すAPI」を実装する方法について紹介します。</p>
<h1>アウトプットイメージ</h1>
<p>最終的なアウトプットイメージは、次の通りです。シンプルな例として、ポップアップのボタンをクリックしたユーザーにユニークなクーポンコードを払い出す、という接客サービスを実装します。</p>
<p><img src="https://ik.imagekit.io/plaid/d2e71351-c0ac-4716-8d03-81d92a207ad2/%E3%82%B9%E3%82%AF%E3%83%AA%E3%83%BC%E3%83%B3%E3%82%B7%E3%83%A7%E3%83%83%E3%83%882023-10-1620.03.57.png" alt="スクリーンショット2023-10-1620.03.57.png"></p>
<p>接客サービスの裏側では、Craft Functions + Craft Counter + Craft kvsを駆使して「クーポン在庫を順次払い出すAPI」を実装します。構成図は次の通りです。</p>
<p><img src="https://ik.imagekit.io/plaid/7ce93748-635c-4658-b35e-c926af7ef107/%E3%82%B9%E3%82%AF%E3%83%AA%E3%83%BC%E3%83%B3%E3%82%B7%E3%83%A7%E3%83%83%E3%83%882023-10-1620.08.54.png" alt="スクリーンショット2023-10-1620.08.54.png"></p>
<h1>API設計</h1>
<p>今回は、Craft Functionsを使って接客サービスのJavaScriptから利用できる「クーポン在庫を順次払い出すAPI」を実装する形になります。リクエストとレスポンスの内容は、次のように設計しました。</p>
<p><strong>リクエスト</strong></p>
<table>
<thead>
<tr>
<th>パラメータ</th>
<th>サンプル値</th>
<th>説明</th>
</tr>
</thead>
<tbody>
<tr>
<td>user_id</td>
<td><code>&quot;user001&quot;</code></td>
<td>配信先user_id。同一ユーザーによる不正取得防止に利用</td>
</tr>
<tr>
<td>coupon_group_id</td>
<td><code>&quot;shop001&quot;</code></td>
<td>クーポン群を区別するID。クーポン在庫を管理する単位毎に任意のIDを設定する</td>
</tr>
</tbody>
</table>
<p><strong>レスポンス</strong></p>
<table>
<thead>
<tr>
<th>パラメータ</th>
<th>サンプル値</th>
<th>説明</th>
</tr>
</thead>
<tbody>
<tr>
<td>coupon_code</td>
<td><code>&quot;dummycouponcode42&quot;</code></td>
<td>取得したクーポンコード</td>
</tr>
<tr>
<td>error</td>
<td>-</td>
<td>エラー発生時はエラー内容を返す</td>
</tr>
</tbody>
</table>
<h1>データ設計</h1>
<p>今回の実装サンプルでは、Craft kvsとCraft Counterでそれぞれ次のようなデータを管理します。</p>
<p><strong>Craft kvs</strong></p>
<ul>
<li><strong>クーポンコード</strong>
<ul>
<li>実際にユーザーに表示するクーポンコード。事前に別Functionを通じて格納しておく</li>
<li>key
<ul>
<li><code>${COUPON_CODE_PREFIX}_${couponGroupId}_${couponIndex}</code></li>
<li>（※サンプルコードではhotspotを避けるためにhash値をprefixに付与）</li>
</ul>
</li>
<li>value（例）
<ul>
<li><code>{&quot;key&quot;:&quot;coupon-code_shop001_1&quot;, &quot;coupon_code&quot;:&quot;xxxxx&quot;}</code></li>
</ul>
</li>
</ul>
</li>
<li><strong>ユーザー毎のクーポンコード前回取得日時</strong>
<ul>
<li>簡易的な不正取得検知に利用（後述）</li>
<li>key
<ul>
<li><code>${COUPON_USER_STATUS_PREFIX}_${couponGroupId}_${hashedUserId}</code></li>
<li>（※サンプルコードではhotspotを避けるためにhash値をprefixに付与）</li>
</ul>
</li>
<li>value（例）
<ul>
<li><code>{ coupon_acquisition_date: &quot;2023-10-17T00:00:00Z&quot; }</code></li>
</ul>
</li>
</ul>
</li>
</ul>
<p><strong>Craft Counter</strong></p>
<ul>
<li><strong>現在払い出し済みの通し番号</strong>
<ul>
<li>現在何番目のクーポンコードまで払い出しているかを管理</li>
<li>key
<ul>
<li><code>${COUPON_INDEX_PREFIX}_${couponGroupId}</code></li>
</ul>
</li>
</ul>
</li>
</ul>
<p>さて、クーポンコードを順次上から払い出すためには、事前にクーポンコードに通し番号を振っておき、整理券的にそれをユーザーに払い出していくことになります。この「リクエストに応じて1から順に数字を出力する」という用途は、まさにCraft Counterが得意とするところです。</p>
<p><a href="https://solution.plaid.co.jp/202310-craft-counter">先日のCraft Counterの紹介記事</a> で説明した通り、Craft Counterには次の特徴があります。</p>
<ul>
<li>特徴1: valueにはnumber 型の整数値しか格納できない</li>
<li>特徴2: 秒間数十回以上のカウントアップ・ダウンリクエストに対応可能</li>
<li>特徴3: increment処理がアトミックに行われる</li>
</ul>
<p>今回のユースケースでは、まず特徴2によって同時に多数のクーポンコード取得リクエストが来た場合でも問題なく処理を捌くことができます。また、特徴3にある「increment処理がアトミックに行われる」という性質により、冒頭に書いた「同一クーポンコードを複数ユーザーに払い出さないようにする」という課題を簡単にクリアすることができます。詳細はCraft Counterの紹介記事をご覧ください。</p>
<h1>手順</h1>
<p>「クーポン在庫を順次払い出すAPI」を実装する手順は次の通りです。</p>
<ol start="0">
<li>Craft kvsにクーポンコード在庫を格納しておく</li>
<li>クーポン払い出し用のCraft Functionsを作成する</li>
<li>Craft Functionsのエンドポイントを作成する</li>
<li>クーポンコード取得用接客サービスを作成する</li>
</ol>
<p>順番に説明します。</p>
<h2>0. Craft kvsにクーポンコード在庫を格納しておく</h2>
<p>すでに構成図で示したように、まずは準備としてクーポンコードの在庫をCraft kvsに格納しておく必要があります。</p>
<p><img src="https://ik.imagekit.io/plaid/7ce93748-635c-4658-b35e-c926af7ef107/%E3%82%B9%E3%82%AF%E3%83%AA%E3%83%BC%E3%83%B3%E3%82%B7%E3%83%A7%E3%83%83%E3%83%882023-10-1620.08.54.png" alt="スクリーンショット2023-10-1620.08.54.png"></p>
<p>一般的に、Craft kvsにまとまったデータを格納する方法は次の通りです。</p>
<ul>
<li>格納したいデータをDatahubデータセットにアップロードする</li>
<li>Craft kvsに入稿したい形式に合わせて、対象データを抽出するためのDatahubクエリを作成する</li>
<li>Datahubジョブフローから呼び出してCraft kvsを更新するためのCraft Functionsを作成する</li>
<li>作成したDatahubクエリの結果をそのFunctionに連携するためのDatahubジョブフローを作成し、実行する</li>
</ul>
<p>詳細の手順やCraft kvs更新用のFunction実装については、下記の記事をご覧ください。</p>
<p><a href="https://solution.plaid.co.jp/202310-datahub-to-kvs">Datahubクエリの結果をCraft kvsに格納してみた</a></p>
<p>なお今回想定されているデータ形式は次の通りです。</p>
<table>
<thead>
<tr>
<th>key</th>
<th>value</th>
</tr>
</thead>
<tbody>
<tr>
<td>xxxx_coupon-code_shop001_1</td>
<td><code>{&quot;key&quot;:&quot;coupon-code_shop001_1&quot;, &quot;coupon_code&quot;:&quot;xxxxx&quot;}</code></td>
</tr>
<tr>
<td>yyyy_coupon-code_shop001_2</td>
<td><code>{&quot;key&quot;:&quot;coupon-code_shop001_2&quot;, &quot;coupon_code&quot;:&quot;yyyyy&quot;}</code></td>
</tr>
<tr>
<td>zzzz_coupon-code_shop001_3</td>
<td><code>{&quot;key&quot;:&quot;coupon-code_shop001_3&quot;, &quot;coupon_code&quot;:&quot;zzzzz&quot;}</code></td>
</tr>
</tbody>
</table>
<p>※xxxx,yyyy,zzzzはkvsのhotspotを避けるためにkeyに付与するhash値</p>
<p>検証のためのダミーデータが欲しい場合は、次のようなDatahubクエリを利用するのが便利です。</p>
<pre><code class="language-sql">WITH dummy_array AS (
  SELECT GENERATE_ARRAY(1, 1000) AS arr
)
SELECT
  CONCAT('coupon-code_shop001_', coupon_index) AS key
  , CONCAT('dummycouponcode', coupon_index) AS coupon_code
FROM dummy_array, UNNEST(arr) AS coupon_index
ORDER BY coupon_index
</code></pre>
<p>なお、最終的にkvsに格納される際のkeyの形式については、前項の「データ設計」の「クーポンコード」で記載した形式に合わせる必要があります。特に今回はサンプルコードではmurmurhashを使ってkeyをhash化してprefixに付与することで、kvsのパフォーマンスが下がらないようにしています。「Datahubクエリの結果をCraft kvsに格納してみた」で提供されるテンプレートでkvsを更新する場合、Craft Functionsの <code>APPEND_HASH_PREFIX</code> という変数をtrueにして利用すると自動でhash prefixが付与されるようになります。</p>
<p>Datahubジョブフローを実行してCraft kvsにクーポンコード在庫を格納できたら、事前準備はOKです。</p>
<h2>1. クーポン払い出し用のCraft Functionsを作成する</h2>
<p>まずは接客サービスからのリクエストを受け付けるCraft FunctionsのFunctionを作成します。サンプルとなるソースコードは、GitHubで公開しています。</p>
<p><a href="https://github.com/plaidev/craft-codes/tree/main/craft-functions/coupon-dispenser">craft-codes/craft-functions/coupon-dispenser at main · plaidev/craft-codes</a></p>
<p>作成手順は次の通りです。</p>
<ul>
<li>[Craft &gt; ファンクション] からファンクションを新規作成</li>
<li>サンプルコードからコードやモジュールをコピー</li>
<li>Functionを有効化して保存</li>
</ul>
<p>なお、最近リリースされたファンクション一覧画面の <strong>「テンプレートから作成」</strong> を選んで検索することで、管理画面上から上記と同じサンプルコードを簡単に利用することもできます。便利ですね！</p>
<p>サンプルコードでは次の機能が実装されています。</p>
<ul>
<li>リクエストbodyから <code>coupon_group_id</code> や <code>user_id</code> を取り出す</li>
<li>変数で設定された時間間隔よりも短い頻度で対象のクーポンを取得しようとしている <code>user_id</code> の場合、不正取得としてエラーを返却する</li>
<li>対象のクーポンについて、Craft Counterで管理された「現在払い出し済みの通し番号」をincrementし、increment後の通し番号を取得する</li>
<li>取得した通し番号に対応するクーポンコードをCraft kvsから取得する</li>
<li>取得したクーポンコードをレスポンスする</li>
</ul>
<p>ここで注意が必要なのは、クーポンコードの不正取得対策です。サンプルコードでは簡易的に「短い間隔で何度もクーポン取得しようとしているuser_idはエラーにする」という対策を実装しています。しかし、仮にCraft FunctionsのエンドポイントURLが悪意のあるユーザーに特定された場合にuser_idをランダムに生成してエンドポイントにリクエストを送ることでクーポンコードを複数取得できてしまうという問題があります。 <strong>実際にこのサンプルコードを利用する場合は、サイト側で払い出される独自の認証用tokenを使ったユーザー認証の仕組みを追加で組み込むか、実際にクーポンコードを利用するアプリケーション側で不正利用対策がされているか、いずれかの対応を推奨しています。</strong></p>
<h2>2. Craft Functionsのエンドポイントを作成する</h2>
<p>Craft Functionsが作成できたら、アンケート接客で実行出来るようにするためのエンドポイントを作成します。</p>
<ul>
<li>作成したファンクションの編集画面で [設定] タブを開く</li>
<li>[エンドポイント] 欄の [作成] ボタンを押す</li>
</ul>
<p>作成したエンドポイントのURLは接客サービス側の実装で利用するので手元に控えておきます。</p>
<h2>3. クーポンコード取得用接客サービスを作成する</h2>
<p>最後に、上記で作成した「クーポン在庫を順次払い出すAPI」を利用する側の実装を行います。今回はKARTEで配信した接客サービスのJavaScriptを介して、エンドユーザーのブラウザから直接リクエストを送信してみましょう。細かい接客サービスの設定方法は割愛して、アクションのJavaScriptのサンプル実装を掲載します。</p>
<p><img src="https://ik.imagekit.io/plaid/d2e71351-c0ac-4716-8d03-81d92a207ad2/%E3%82%B9%E3%82%AF%E3%83%AA%E3%83%BC%E3%83%B3%E3%82%B7%E3%83%A7%E3%83%83%E3%83%882023-10-1620.03.57.png" alt="スクリーンショット2023-10-1620.03.57.png"></p>
<h3>クーポンコード取得用アクションのJavaScript例</h3>
<ul>
<li>実装内容
<ul>
<li>ユーザーがボタンを押したらCraftエンドポイントにリクエストを送信し、 <code>isLoading</code> を <code>true</code> にする</li>
<li>レスポンスが返ってきたら、取得できたクーポンコードを動的変数に格納し、 <code>isLoading</code> を <code>false</code> にした上でステートを1から2に切り替える</li>
</ul>
</li>
</ul>
<pre><code class="language-js">var CRAFT_ENDPOINT_URL = 'https://t.karte.io/hook/xxxxxxxxxx/craft/xxxxxxxxxx';
var COUPON_GROUP_ID = 'shop001'; // クーポン在庫の管理単位を特定するためのID

widget.setVal('isLoading', false);

widget.method('getCoupon', function() {
    // リクエスト完了までローディング表示
    widget.setVal('isLoading', true);

    // クーポンコード取得リクエストを送信
    fetchData(function(item, error) {
        widget.setVal('coupon_code', item.coupon_code);
        if (error) widget.setVal('error', error.toString());
        widget.setVal('isLoading', false);
        widget.setState(2);
    });
});

widget.show();

function fetchData(cb) {
    var payload = {
        user_id: &quot;#{user_id}&quot;,
        coupon_group_id: COUPON_GROUP_ID
    };
    fetch(
        CRAFT_ENDPOINT_URL,
        {
            method: 'POST',
            headers: {
              &quot;Content-Type&quot;: &quot;application/json&quot;,
            },
            body: JSON.stringify(payload),
        }
    )
    .then(function(response) {
        return response.json();
    })
    .then(function(item) {
        cb(item);
    })
    .catch(function(err) {
        cb(null, err);
    })
}
</code></pre>
<p>対応するHTML/CSS側では、次の実装が必要となります。実装内容は簡単なので、サンプルコードは割愛します。</p>
<ul>
<li><code>isLoading</code> が <code>true</code> の場合のみローディング時のUIが表示されるようにする</li>
<li>リクエスト完了後に表示されるステート2で <code>coupon_code</code> の値を表示する</li>
</ul>
<h1>実際に動かしてみる</h1>
<p>実際に接客サービスを配信して動作を確認してみましょう。問題なく実装できていれば、次のようにボタン押下後に異なるクーポンコードが順番に表示されるはずです。</p>
<p><img src="https://ik.imagekit.io/plaid/d2e71351-c0ac-4716-8d03-81d92a207ad2/%E3%82%B9%E3%82%AF%E3%83%AA%E3%83%BC%E3%83%B3%E3%82%B7%E3%83%A7%E3%83%83%E3%83%882023-10-1620.03.57.png" alt="スクリーンショット2023-10-1620.03.57.png"></p>
<h1>おわりに</h1>
<p>今回はCraft kvsとCraft Counterをうまく組み合わせて「クーポン在庫順次払い出し施策」を実装する方法について紹介しました。</p>
<p>ちなみに今回の施策をCraft Counterを使わずCraft kvsだけで実装することも可能です。しかし、前述したCraft Counterの特徴により、 <strong>クーポンコードの通し番号を順次漏れなくダブり無く払い出すという用途にはCraft Counterを利用した方がシンプルに実装できます。</strong></p>
<p>施策内容としても、特定の行動を取ってくれたユーザーに対して直接的なリワードを提供できるというのは強力です。クーポンコードの不正取得には十分に対策をした上で、ぜひ活用してみてください！</p>
<hr>
<p>プレイドでは、世の中にインパクトを与える新しいソリューションを一緒につくる仲間を募集しています！<br>
ぜひ気軽にお問い合わせください。</p>
<p>↓ パートナー企業になりたい</p>
<ul>
<li><a href="https://ecosystem.plaid.co.jp/">CustomerData-Driven Solution を一緒に創りませんか？ | PLAID Ecosystem</a></li>
</ul>
<p>↓ PLAIDで働きたい</p>
<ul>
<li><a href="https://recruit.plaid.co.jp/requisitions/general-customer-engineer">Customer Engineer | 募集ポジション | 株式会社プレイド</a></li>
<li><a href="https://recruit.plaid.co.jp/requisitions/product-engineer">Product Engineer | 募集ポジション | 株式会社プレイド</a></li>
</ul>


KARTEで「クーポン在庫の順次払い出し」施策を実現する方法について紹介します。KARTE Craft側は、先日リリースされたCraft Counterの特性をうまく利用してシンプルに実装することができます。

クーポン在庫を順次払い出すAPIをKARTE Craftで実装してみた

<p>こんにちは、Customer Engineerの道畑です！最近は「雨と君と」という漫画のたぬき(犬)にドはまりしています！ハマりすぎて自宅のデスクがたぬき(犬)の人形だらけです(笑)。</p>
<p>さて、今回はDatahubで実行したクエリの実行結果をCraft Key-Value Store (Craft KVS)に格納してみました。</p>
<p>Craft Functionsを使ってユーザー固有の接客を実装したいとき、事前に接客情報をCraft KVSに登録しておく必要があります。例えば、ユーザーに固有のクーポンを払い出したいときなどです。初期導入時のコストとハードルを少しでも下げるために、カラム名を変更するだけで使える汎用的なCraft Functionsを作成しました。カラム名を変更するだけで実行できるようにしたので、是非コピペして試してみてください！</p>
<h1>全体像</h1>
<p>実現する処理の全体像は、次の通りです。<br>
DatahubのJobflowからクエリを実行して、実行結果をCraft Functionに渡して、それをCraft KVSに格納するというとてもシンプルなものです。<br>
<img src="https://ik.imagekit.io/plaid/520c53ab-40d2-4ac3-b265-94e3aa45c176/%E6%A7%8B%E6%88%90%E5%9B%B3.jpg" alt="構成図.jpg"></p>
<h1>実装手順</h1>
<p>実装の手順は次の通りです。</p>
<ol>
<li>Craft KVSに格納したいデータを取得できるSQLを書く</li>
<li>Craft KVSに格納するCraft Functionsを作る</li>
<li>SQLの結果をCraft Functionsに渡すJobflowを作成する</li>
</ol>
<p>順番に説明します。</p>
<h2>1. Craft KVSに格納したいデータを取得できるSQLを書く</h2>
<p>まずはSQLを作成します。「Datahub &gt; クエリ &gt; 作成 &gt; クエリを作成」から下記のようにクエリを作成してください。</p>
<pre><code>SELECT
  coupon_id,
  already_used,
  user_id
FROM
  `prd-karte-per-client.xxxx_table名`
</code></pre>
<p>今回はクーポン情報を管理しているテーブルを丸ごと抽出するSQLをテスト用に用意しました。このテーブルは「coupon_id」が一意キーとなるようにテーブルが作られています。「coupon_id」はCraft KVSでもキーになるように後述のサンプルコードを作成しています。一番最初のSELECT項目がCraft KVSのキーになることをご注意ください。例えば、user_idをCraft KVSのキーにしたい場合は次の様にSQLを作成します。</p>
<p>例)user_idをCraft KVSのキーにしたい場合のSQL</p>
<pre><code>SELECT
  user_id,
  already_used,
  coupon_id
FROM
  `prd-karte-per-client.xxxx_table名`
</code></pre>
<h2>2. Craft kvsに格納するCraft Functionsを作る</h2>
<p>次に、実行したクエリ結果をCraft KVSに格納するCraft Functionsを作ります。次のコードを利用して、Craft Functionsを新規作成します。</p>
<p><a href="https://github.com/plaidev/craft-codes/tree/main/craft-functions/datahub-to-kvs">craft-codes/craft-functions/datahub-to-kvs at main · plaidev/craft-codes</a></p>
<p>実際に利用する際には以下の2つに気をつけてください。</p>
<ol>
<li>「HEADER_COLUMNS」の部分は、SQLのカラムに合わせて修正してください。</li>
<li>「MINUTES_TO_EXPIRE 」はCraft KVSにデータを保存する期間を保持しています。必要に応じて変更してください。<a href="https://craft.developers.karte.io/reference/craft-key-value-store/index.html#write">詳しくはこちらをご確認ください。</a></li>
</ol>
<p>「modules」は次のキャプチャの様に空欄でOKです。</p>
<p><img src="https://ik.imagekit.io/plaid/a7b2ab6a-7067-4e25-85bd-ebf52bdde7a7/%E3%82%B9%E3%82%AF%E3%83%AA%E3%83%BC%E3%83%B3%E3%82%B7%E3%83%A7%E3%83%83%E3%83%882023-09-2612.05.18.png" alt="スクリーンショット2023-09-2612.05.18.png"></p>
<p>Datahubからデータが渡された想定でこちらのCraft Functionsを実行すると、下記のようにCraft KVSに格納されます。「Key」に該当レコードの1つ目のカラム情報が入り、「Value」に「{カラム名：レコード情報}」がカンマ区切りで格納されます。</p>
<h6>テーブル情報</h6>
<table>
<thead>
<tr>
<th>coupon_id</th>
<th>already_used</th>
<th>user_id</th>
</tr>
</thead>
<tbody>
<tr>
<td>coupon_id01</td>
<td>FALSE</td>
<td>U-001</td>
</tr>
<tr>
<td>coupon_id02</td>
<td>FALSE</td>
<td>U-002</td>
</tr>
<tr>
<td>coupon_id03</td>
<td>FALSE</td>
<td>U-003</td>
</tr>
<tr>
<td>coupon_id04</td>
<td>FALSE</td>
<td>U-004</td>
</tr>
</tbody>
</table>
<h6>Craft KVS格納イメージ</h6>
<table>
<thead>
<tr>
<th>Key</th>
<th>Value</th>
</tr>
</thead>
<tbody>
<tr>
<td>coupon_id01</td>
<td>{&quot;coupon_id&quot;:&quot;coupon_id01&quot;,&quot;already_used&quot;:&quot;false&quot;,&quot;user_id&quot;:&quot;U-001&quot;}</td>
</tr>
<tr>
<td>coupon_id02</td>
<td>{&quot;coupon_id&quot;:&quot;coupon_id02&quot;,&quot;already_used&quot;:&quot;false&quot;,&quot;user_id&quot;:&quot;U-002&quot;}</td>
</tr>
<tr>
<td>coupon_id03</td>
<td>{&quot;coupon_id&quot;:&quot;coupon_id03&quot;,&quot;already_used&quot;:&quot;false&quot;,&quot;user_id&quot;:&quot;U-003&quot;}</td>
</tr>
<tr>
<td>coupon_id04</td>
<td>{&quot;coupon_id&quot;:&quot;coupon_id04&quot;,&quot;already_used&quot;:&quot;false&quot;,&quot;user_id&quot;:&quot;U-004&quot;}</td>
</tr>
</tbody>
</table>
<h2>3. SQLの結果をCraft Functionsに渡すJobflowを作成する</h2>
<p>最後に、作成したSQLとCraft Functionsを繋ぐJobflowを作成します。Jobflowを下記の内容で新規作成してください。</p>
<ul>
<li>エクスポート元：作成したクエリ</li>
<li>エクスポート先：外部サービス</li>
<li>接続先：Craft</li>
<li>function名：作成したCraft Functions</li>
<li>行ごとにqueue をpublishする：チェックを入れる</li>
</ul>
<p>「行ごとにqueue をpublishする」のチェックを忘れると、今回作成したCraft Functionsでは正しく動作しないので気をつけてください。</p>
<p><img src="https://ik.imagekit.io/plaid/5ad2b621-10ab-4d66-89f9-a0bf63f75347/%E3%82%B9%E3%82%AF%E3%83%AA%E3%83%BC%E3%83%B3%E3%82%B7%E3%83%A7%E3%83%83%E3%83%882023-09-2612.25.32.png" alt="スクリーンショット2023-09-2612.25.32.png"></p>
<p>このJobflowを実行するとSQLの実行結果をCraft FunctionsでCraft KVSに格納できます。<br>
<img src="https://ik.imagekit.io/plaid/ea854668-0d07-4499-bb53-85379ea22e6d/%E3%82%B9%E3%82%AF%E3%83%AA%E3%83%BC%E3%83%B3%E3%82%B7%E3%83%A7%E3%83%83%E3%83%882023-09-2613.06.08.png" alt="スクリーンショット2023-09-2613.06.08.png"></p>
<h1>おわりに</h1>
<p>今回はDatahubクエリの結果をCraft KVSに格納する方法をご紹介しました。Craft KVSにはCraft Functionsからしかアクセスできないという制約がありますが、今回のサンプルコードを使えばDatahubクエリの結果をジョブフローの設定だけで簡単にCraft KVSにエクスポートできます。Craft FunctionsからDatahubのデータを参照できるに近しい動きができるようになるので、ぜひ皆さん使ってみてください！</p>
<hr>
<p>プレイドでは、世の中にインパクトを与える新しいソリューションを一緒につくる仲間を募集しています！<br>
ぜひ気軽にお問い合わせください。</p>
<p>↓ パートナー企業になりたい</p>
<ul>
<li><a href="https://ecosystem.plaid.co.jp/">CustomerData-Driven Solution を一緒に創りませんか？ | PLAID Ecosystem</a></li>
</ul>
<p>↓ PLAIDで働きたい</p>
<ul>
<li><a href="https://recruit.plaid.co.jp/requisitions/general-customer-engineer">Customer Engineer | 募集ポジション | 株式会社プレイド</a></li>
<li><a href="https://recruit.plaid.co.jp/requisitions/product-engineer">Product Engineer | 募集ポジション | 株式会社プレイド</a></li>
</ul>


Datahubで実行したクエリ結果をCraft kvsに格納する方法をご紹介します！

Datahubクエリの結果をCraft kvsに格納してみた

Datahubクエリの結果をCraft KVSに格納してみた

<p>こんにちは、Customer Engineerのgamiです！最近、藤子・F・不二雄のSF短編集を読み始めました。</p>
<p>さて、先日「<a href="https://solution.plaid.co.jp/202308-Craft">アンケート結果をリアルタイムで表示してみた</a>」という記事が公開されました。記事の内容としては、下記のような「回答後に集計結果がリアルタイム表示されるアンケート」をCraft Functions + Craft kvsで実装するというものでした。<br>
<img src="https://ik.imagekit.io/plaid/0eaeef2d-5350-43ad-9e68-839da76dcf22/%E3%82%B9%E3%82%AF%E3%83%AA%E3%83%BC%E3%83%B3%E3%82%B7%E3%83%A7%E3%83%83%E3%83%882023-09-2510.13.28.png" alt="スクリーンショット2023-09-2510.13.28.png"></p>
<p>実は、こうした「項目別に何らかの数値をカウントする」という用途の場合、Craft kvsよりも先日リリースされた <a href="https://solution.plaid.co.jp/202310-craft-counter">Craft Counter</a> の方が適しています。</p>
<p>特に複数人がほぼ同時にリクエストを送ってくる可能性のある場合、Craft Counterの方が高いパフォーマンスを発揮でき、リクエストに失敗するリスクが軽減されます。</p>
<p>そこで今回は、Craft kvsの代わりにCraft Counterを使って「回答後に集計結果がリアルタイム表示されるアンケート」を実装する方法について紹介します。</p>
<h1>アウトプットイメージ</h1>
<p>最終的なアウトプットイメージは、先日の記事と同様です。私が検証したアンケート接客サービスでは、 <s>スタイル実装をサボって</s> 便宜的に次のような表示を実現しました。</p>
<p><img src="https://ik.imagekit.io/plaid/c7442a35-e418-4c8f-9776-1eda5b5b90ba/%E3%82%B9%E3%82%AF%E3%83%AA%E3%83%BC%E3%83%B3%E3%82%B7%E3%83%A7%E3%83%83%E3%83%882023-09-2510.19.26.png" alt="スクリーンショット2023-09-2510.19.26.png"></p>
<p>構成図は次の通り。<br>
<img src="https://ik.imagekit.io/plaid/edd35c9d-bdb4-475e-867c-d8db588cc08c/%E3%82%B9%E3%82%AF%E3%83%AA%E3%83%BC%E3%83%B3%E3%82%B7%E3%83%A7%E3%83%83%E3%83%882023-09-2510.23.41.png" alt="スクリーンショット2023-09-2510.23.41.png"></p>
<h1>API設計</h1>
<p>今回は、Craft Functionsを使って接客サービスのJavaScriptから利用できる「アンケート集計API」を実装する形になります。リクエストとレスポンスの内容は、次のように設計しました。</p>
<h2>read時</h2>
<p><strong>リクエスト</strong></p>
<table>
<thead>
<tr>
<th>パラメータ</th>
<th>サンプル値</th>
<th>説明</th>
</tr>
</thead>
<tbody>
<tr>
<td>action</td>
<td><code>&quot;read&quot;</code></td>
<td>read時は'read'固定</td>
</tr>
<tr>
<td>enqueteId</td>
<td><code>&quot;a1234567890b1234567890c1&quot;</code></td>
<td>アンケートを区別するID。今回は接客サービスIDを利用</td>
</tr>
<tr>
<td>choiceIds</td>
<td><code>[&quot;apple&quot;, &quot;banana&quot;, &quot;cherry&quot;]</code></td>
<td>全選択肢IDのリスト</td>
</tr>
</tbody>
</table>
<p><strong>レスポンス</strong></p>
<table>
<thead>
<tr>
<th>パラメータ</th>
<th>サンプル値</th>
<th>説明</th>
</tr>
</thead>
<tbody>
<tr>
<td>result</td>
<td><code>{ apple: 42, banana: 24, cherry: 8}</code></td>
<td>取得した集計結果</td>
</tr>
<tr>
<td>error</td>
<td>-</td>
<td>エラー</td>
</tr>
</tbody>
</table>
<h2>write</h2>
<p><strong>リクエスト</strong></p>
<table>
<thead>
<tr>
<th>パラメータ</th>
<th>サンプル値</th>
<th>説明</th>
</tr>
</thead>
<tbody>
<tr>
<td>action</td>
<td><code>&quot;write&quot;</code></td>
<td>write時は'write'固定</td>
</tr>
<tr>
<td>enqueteId</td>
<td><code>&quot;a1234567890b1234567890c1&quot;</code></td>
<td>アンケートを区別するID。今回は接客サービスIDを利用</td>
</tr>
<tr>
<td>selectedChoiceId</td>
<td><code>&quot;apple&quot;</code></td>
<td>ユーザーが選択した選択肢ID</td>
</tr>
</tbody>
</table>
<p><strong>レスポンス</strong></p>
<table>
<thead>
<tr>
<th>パラメータ</th>
<th>サンプル値</th>
<th>説明</th>
</tr>
</thead>
<tbody>
<tr>
<td>result</td>
<td><code>&quot;write succeeded.&quot;</code></td>
<td>リクエスト成功時のメッセージ</td>
</tr>
<tr>
<td>error</td>
<td>-</td>
<td>エラー</td>
</tr>
</tbody>
</table>
<h1>手順</h1>
<p>手順は次の通りです。</p>
<ol>
<li>Craft Functionsを作成する</li>
<li>Craft Functionsのエンドポイントを作成する</li>
<li>Functionと連携するアンケート接客を作成する</li>
</ol>
<p>順番に説明します。</p>
<h2>1. Craft Functionsを作成する</h2>
<p>まずは接客サービスからのリクエストを受け付けるCraft FunctionsのFunctionを作成します。サンプルとなるソースコードは、GitHubで公開しています。</p>
<p><a href="https://github.com/plaidev/craft-codes/tree/main/craft-functions/realtime-enquete">craft-codes/craft-functions/realtime-enquete at main · plaidev/craft-codes</a></p>
<p>作成手順は次の通りです。</p>
<ul>
<li>[Craft &gt; ファンクション] からファンクションを新規作成</li>
<li>サンプルコードからコードやモジュールをコピー</li>
<li>Functionを有効化して保存</li>
</ul>
<p>サンプルコードでは次の機能が実装されています。</p>
<ul>
<li>read時
<ul>
<li>Craft Counterから選択肢ID毎の回答数を取得し、適切な形に加工した上で「アンケート集計結果」としてレスポンスする</li>
</ul>
</li>
<li>write時
<ul>
<li>ユーザーが回答した選択肢IDの回答数をCraft Counter上でincrementする</li>
</ul>
</li>
</ul>
<p>なお今回の実装では、集計結果の取得（read）と回答データの送信（write）を別々のリクエストとして処理することにしています。集計結果の取得には数秒程度の時間を要するので、アンケート表示時に予めread用のリクエストを飛ばしておくことで、アンケート回答後に素早くアンケート集計結果を表示できるようになります。readとwriteでFunction実行が2回発生するのでFunction実行数は2倍消費してしまいますが、今回はユーザー体験を重視してこのような実装にしています。</p>
<p>また、readとwriteで2つのFunctionに分けて実装するというパターンも考えられますが、管理のしやすさを考えて今回は1つのFunctionにread/writeの両方の処理を実装しています。</p>
<h2>2. Craft Functionsのエンドポイントを作成する</h2>
<p>Craft Functionsが作成できたら、アンケート接客で実行出来るようにするためのエンドポイントを作成します。</p>
<ul>
<li>作成したファンクションの編集画面で [設定] タブを開く</li>
<li>[エンドポイント] 欄の [作成] ボタンを押す</li>
</ul>
<p>作成したエンドポイントのURLは接客サービス側の実装で利用するので手元に控えておきます。</p>
<h2>3. Functionと連携するアンケート接客を作成する</h2>
<p>最後に、上記で作成したお手製アンケート集計APIを利用するアンケート接客サービスを実装します。細かい接客サービスの設定方法は割愛して、アクションのHTML/JavaScriptのサンプル実装を掲載します。</p>
<h3>アンケートアクションのJavaScript例</h3>
<ul>
<li>実装のポイント
<ul>
<li>配信直後にCraft側にreadリクエストを送信</li>
<li>ユーザーがアンケート回答したらwriteリクエストを送信</li>
<li>readリクエストとアンケート回答の両方が完了したタイミングでステートを変更し、集計結果を表示
<ul>
<li>このとき、表示のために次の計算をフロントエンドで実施している
<ul>
<li>ユーザーが回答した選択肢を+1する</li>
<li>全選択肢の回答数の総計を計算する</li>
</ul>
</li>
</ul>
</li>
</ul>
</li>
</ul>
<pre><code class="language-js">var CRAFT_ENDPOINT_URL = 'https://t.karte.io/hook/xxxxxxxxxxx/craft/xxxxxxxxxxxxxx';

// 設問の選択肢群を登録
var ALL_CHOICES = [
    { id: &quot;apple&quot;, name: &quot;りんご&quot; },
    { id: &quot;banana&quot;, name: &quot;バナナ&quot; },
    { id: &quot;cherry&quot;, name: &quot;さくらんぼ&quot; }
];
widget.setVal('ALL_CHOICES', ALL_CHOICES);

var fetchResultDone = false; // すでにreadが完了しているか？
var selectedChoiceId = null; // 回答した選択肢ID
widget.method('sendChoice', sendChoice);
widget.setVal('result', null);

// 結果取得に時間がかかるので、回答前にprefetchする
fetchResult();

widget.show();

// read
function fetchResult() {
    _post({
        enqueteId: '#{campaign_id}',
        action: 'read',
        choiceIds: ALL_CHOICES.map(function(choice) { return choice.id }),
    })
    .then(function(body) {
        console.log('read done: '+JSON.stringify(body));
        var result = body.result;
        fetchResultDone = true;
        widget.setVal('result', result);

        // 結果取得完了時にすでに回答済みの場合、ユーザー回答分を加算して即座に結果表示
        if (selectedChoiceId) {
            calcResult(selectedChoiceId);
            widget.setState(2);
        }
    });
}

// write
function sendChoice(choice) {
    console.log('sendChoice start');
    selectedChoiceId = choice;
    // 回答時に結果取得完了済みの場合、ユーザー回答分を加算して結果表示
    if (fetchResultDone) {
        calcResult(selectedChoiceId);
        widget.setState(2);
    }
    // 回答データの送信は非同期に行う
    _post({
        enqueteId: '#{campaign_id}', // アンケートIDには接客サービスIDを利用
        action: 'write',
        selectedChoiceId: choice,
    })
    .then(function(body) {
        console.log('write done: '+JSON.stringify(body));
    });
}

function calcResult(choice) {
    var result = widget.getVal('result');
    // 取得した結果にユーザーの回答を加算
    result[selectedChoiceId]++;
    // 合計値を計算
    result.__total = Object.keys(result).reduce(function(total, key) {
        total += result[key];
        return total;
    }, 0);
    widget.setVal('result', result);
}

function _post(body) {
    return fetch(CRAFT_ENDPOINT_URL, {
        method: 'POST',
        headers: {'Content-Type': 'application/json'},
        body: JSON.stringify(body),
    }).then(function(res) {
        if (res.ok) {
            return res.json();
        } else {
            return;
        }
    });
}
</code></pre>
<h3>アンケートアクションのHTML例</h3>
<ul>
<li>実装のポイント
<ul>
<li>全選択肢IDのリストが格納された定数ALL_CHOICESをkrt-forでループして選択肢毎のボタンを描画</li>
<li>Craft側から取得した集計結果を動的変数resultに格納して結果表示に利用</li>
</ul>
</li>
</ul>
<pre><code class="language-html">&lt;div class=&quot;wrapper&quot;&gt;
    &lt;section krt-if=&quot;state == 1&quot;&gt;
        &lt;div class=&quot;card _edged border-4&quot;&gt;
            &lt;div class=&quot;card-body&quot;&gt;
                &lt;!-- 画像 --&gt;
                &lt;figure class=&quot;card-image&quot; style=&quot;width:128px&quot;&gt;
                    &lt;img src=&quot;#{image}&quot; alt=&quot;&quot;&gt;
                &lt;/figure&gt;

                &lt;!-- 見出し --&gt;
                &lt;h1 class=&quot;card-heading text-center&quot;&gt;
                    #{heading}
                &lt;/h1&gt;

                &lt;!-- 詳細テキスト --&gt;
                &lt;p class=&quot;card-detail&quot;&gt;
                    #{detail}
                &lt;/p&gt;

                &lt;!-- ボタン --&gt;
                &lt;div class=&quot;card-button&quot;&gt;
                    &lt;button krt-for=&quot;choice in ALL_CHOICES&quot; krt-on:click=&quot;sendChoice(choice.id)&quot;&gt;{{choice.name}}&lt;/button&gt;
                &lt;/div&gt;
            &lt;/div&gt;
        &lt;/div&gt;
    &lt;/section&gt;
    &lt;section krt-if=&quot;state == 2&quot;&gt;
        &lt;div class=&quot;card _edged border-4&quot;&gt;
            &lt;div class=&quot;card-body&quot;&gt;
                &lt;!-- 画像 --&gt;
                &lt;figure class=&quot;card-image&quot; style=&quot;width:128px&quot;&gt;
                    &lt;img src=&quot;#{image}&quot; alt=&quot;&quot;&gt;
                &lt;/figure&gt;

                &lt;!-- 見出し --&gt;
                &lt;h1 class=&quot;card-heading text-center&quot;&gt;
                    #{heading}
                &lt;/h1&gt;

                &lt;!-- 詳細テキスト --&gt;
                &lt;p class=&quot;card-detail&quot;&gt;
                    #{detail}
                &lt;/p&gt;

                &lt;div class=&quot;card-button&quot;&gt;
                    &lt;p krt-for=&quot;choice in ALL_CHOICES&quot;&gt;{{choice.name}}: 約{{Math.round(result[choice.id] / result.__total * 100)}} % （{{result[choice.id]}}件）&lt;/p&gt;
                &lt;/div&gt;
            &lt;/div&gt;
        &lt;/div&gt;
    &lt;/section&gt;
&lt;/div&gt;
</code></pre>
<p>本来はエラーハンドリングやローディング処理の実装もすべきですが、今回は実装例ということで割愛しています。</p>
<h1>実際に動かしてみる</h1>
<p>実際に動作を確認してみましょう。</p>
<h2>Craft側の検証</h2>
<p>記事構成の都合上、接客サービス作成までまとめて紹介しましたが、本来はまずCraft Functions自体の動作を手元のプログラム等から確認するのがおすすめです。同時アクセス時の負荷検証も、手元のプログラムから同時多発的にリクエスト送信を試みることで実現できます。</p>
<p>たとえば次のようなNode.jsプログラムをjsファイルとして保存しローカルのnodeコマンドで実行することで、Craft側の検証ができます。</p>
<pre><code class="language-js">// Craft側検証用のjsファイル
const request = require('request');

// 共通
const ENDPOINT = '';
const d = {
    enqueteId: 'dummyCampaignId',
}
const allChoiceIds = [&quot;apple&quot;, &quot;banana&quot;, &quot;cherry&quot;];

// read用
d.action = 'read';
d.choiceIds = allChoiceIds;

// write用
// d.action = 'write';
// d.selectedChoiceId = 'apple'; // コメントアウトするとランダムに選択される

// 実行回数
let cnt = 10;
while(cnt &gt; 0) {
    exec_req(d);    
    cnt--;
}

function exec_req(d) {
    const b = {};
    b.action = d.action;
    b.enqueteId = d.enqueteId;

    if (d.action === 'write') {
        b.selectedChoiceId = d.selectedChoiceId || getRandomChoiceId(allChoiceIds);
    } else {
        b.choiceIds = d.choiceIds;
    }

    request({
      url: ENDPOINT,
      method: 'POST',
      headers: {'Content-Type': 'application/json'},
      body: JSON.stringify(b)
    }, (err, res, body) =&gt; {
        if (b.action === 'write') {
            console.log(`action: ${b.action}, enqueteId: ${b.enqueteId}, selectedChoiceId: ${JSON.stringify(b.selectedChoiceId)},  result: ${body}`);
        } else {
            console.log(`action: ${b.action}, enqueteId: ${b.enqueteId}, result: ${body}`);
        }
    });
}

function getRandomChoiceId(allChoiceIds) {
    return allChoiceIds[Math.floor(Math.random() * allChoiceIds.length)];
}
</code></pre>
<h2>接客サービスの検証</h2>
<p>Craft側の動作に問題がなければ、接客サービスの表示確認をしてみましょう。次のように回答後に集計結果が表示できるはずです。</p>
<p><img src="https://ik.imagekit.io/plaid/e728df6a-20aa-457c-9898-21875161b973/%E3%82%B9%E3%82%AF%E3%83%AA%E3%83%BC%E3%83%B3%E3%82%B7%E3%83%A7%E3%83%83%E3%83%882023-09-259.46.59.png" alt="スクリーンショット2023-09-259.46.59.png"></p>
<h1>おわりに</h1>
<p>今回はCraft kvsの代わりにCraft Counterで「回答後に集計結果がリアルタイム表示されるアンケート」を実装する方法について紹介しました。</p>
<p>実際にCraft kvsと比較してみても、Craft Counterは「高速に何らかの値をincrementする」という処理に対してかなりのパフォーマンスを発揮します。Craft kvsと比べると保持できる値の柔軟性は落ちますが、ぜひこうした用途ではCraft Counterを選択するのを強くおすすめします。</p>
<p>なお、今回はアンケート毎に1つの設問しかない状態を想定しました。そのためCraft Counterのkeyの持ち方を「アンケートID×選択肢ID」にしています。たとえば「1つのアンケートに複数の設問を設けたい」といったカスタマイズがしたければ、Craft Counterのkeyの持ち方を「アンケートID×設問ID×選択肢ID」にすることで対応できます。</p>
<p>ぜひCraft Counterを使って複雑なアンケート施策を実現してみてください！</p>
<hr>
<p>プレイドでは、世の中にインパクトを与える新しいソリューションを一緒につくる仲間を募集しています！<br>
ぜひ気軽にお問い合わせください。</p>
<p>↓ パートナー企業になりたい</p>
<ul>
<li><a href="https://ecosystem.plaid.co.jp/">CustomerData-Driven Solution を一緒に創りませんか？ | PLAID Ecosystem</a></li>
</ul>
<p>↓ PLAIDで働きたい</p>
<ul>
<li><a href="https://recruit.plaid.co.jp/requisitions/general-customer-engineer">Customer Engineer | 募集ポジション | 株式会社プレイド</a></li>
<li><a href="https://recruit.plaid.co.jp/requisitions/product-engineer">Product Engineer | 募集ポジション | 株式会社プレイド</a></li>
</ul>


高パフォーマンスなカウンター用データベースであるCraft Counterを使って「回答後に集計結果がリアルタイム表示されるアンケート」を実装する方法について紹介します。

「回答後に集計結果がリアルタイム表示されるアンケート」をCraft Counterで実装する

<p>こんにちは、Customer Engineerのgamiです。</p>
<p>先日 <a href="https://solution.plaid.co.jp/202310-craft-function-renewal">Craft Functionsのエディタ画面リニューアル&amp;変数機能リリース</a> が行われたばかりですが、またもや新機能の発表です！この度、Craft Functions内で利用できる高速なカウンター <strong>「Craft Counter」</strong> が利用可能になりました。</p>
<h1>Craft Counterとは？</h1>
<p>今回リリースされたCraft Counterは、key とそれに紐づくvalueからなるKey-Value Storeです。</p>
<p>Craftファミリーにはすでに <a href="https://craft.developers.karte.io/craft-key-value-store/gets-started">Craft KVS</a> というKey-Value Storeがありますが、それと比べてCraft Counterには次のような特徴があります。</p>
<ul>
<li>特徴1: valueにはnumber 型の整数値しか格納できない</li>
<li>特徴2: 秒間数十回以上のカウントアップ・ダウンリクエストに対応可能</li>
<li>特徴3: increment処理がアトミックに行われる</li>
</ul>
<p>今回の記事では、この3つの特徴について詳しく説明します。</p>
<h2>特徴1: valueにはnumber 型の整数値しか格納できない</h2>
<p>Craft KVSではvalueに任意のオブジェクトを指定してwriteすることができました。</p>
<pre><code class="language-js">export default async function (data, { MODULES }) {
  const { kvs } = MODULES;
  const value = { foo: &quot;bar&quot;, baz: 42};

  await kvs.write({ key: &quot;key1&quot;, value });
};
</code></pre>
<p>一方、Craft Counterではvalueに整数値しか指定することができません。</p>
<pre><code class="language-js">export default async function (data, { MODULES }) {
  const { counter } = MODULES;
  const value = 1000;
  await counter.set({ key: &quot;key1&quot;, value });
}
</code></pre>
<p>&quot;Counter&quot; という名前だけあって、数値をカウントする用途で利用されるデータベースということです。</p>
<h2>特徴2: 秒間数十回以上のカウントアップ・ダウンリクエストに対応可能</h2>
<p>ここまでの説明では単にCraft Counterの方ができることが少ないように見えます。その代わりとして、Craft Counterはパフォーマンスの面で強みがあります。</p>
<p>特にCraft Counterでは <code>increment()</code>  メソッドがサポートされており、 <strong>「複数のクライアントから同時多発的に飛んできたリクエストを余すことなくカウントする」</strong> という用途に特化しています。</p>
<pre><code class="language-js">export default async function (data, { MODULES }) {
  const { counter } = MODULES;
  await counter.set({ key: &quot;key1&quot;, value: 0 }); // 0
  count n1 = await counter.increment({ key: &quot;key1&quot; }); // 1
  count n2 = await counter.increment({ key: &quot;key1&quot; }); // 2
  // ...
}
</code></pre>
<p>なお、<code>counter.increment()</code>を呼び出すとincrement後の数値が返されます。現在の数値を取得して+1して更新する場合、Craft KVSでは<code>kvs.get()</code>と<code>kvs.write()</code>をそれぞれ呼ぶ必要がありますが、<code>counter.increment()</code>では1回のリクエストでまとめて実現できます。便利ですね。</p>
<p>さて、たとえばKARTEの施策ニーズとして、次のようにユーザー横断の集計をリアルタイムに実施したいケースがあります。</p>
<ul>
<li><strong>特定接客サービスの表示数</strong> をカウントし、一定数を超えたら自動停止したい</li>
<li>選択式のアンケートを配信し、 <strong>全アンケート回答</strong> をリアルタイムに集計してユーザーに表示したい</li>
<li>アイテム詳細ページで <strong>「いま何人が見てます」</strong> と表示したい</li>
</ul>
<p>こうしたケースでは、サイト来訪しているアクティブなユーザー数が急に増えた場合に、集計を担うFunctionにもリクエストが集中します。その際のデータベースにCraft KVSを採用することもできますが、 <strong>「高速に数をカウントアップしたい」</strong> というケースではCraft Counterの方が高いパフォーマンスが期待できるというわけです。</p>
<p>実際、私も同様の施策をCraft KVSとCraft Counterの両方で実装して簡単な負荷検証をしたところ、Craft KVSでは負荷が高まりtimeoutになってしまうケースでも、Craft Counterでは高速にリクエストを捌くことができました。</p>
<p>（なお、便宜上「秒間数十回以上」と書きましたが、より高いパフォーマンスが求められる場合はご相談ください。）</p>
<h2>特徴3: increment処理がアトミックに行われる</h2>
<p>最後の特徴は、increment処理がアトミックに行われるということです。具体例とともに紹介します。</p>
<p>Craft Counterの他の代表的なユースケースとして、 <strong>「クーポンコードの順次払い出し」</strong> に利用するというものがあります。具体的には次のような施策です。</p>
<ul>
<li>事前にクーポンコードの在庫を用意し、1番から始まる通し番号を付与しておく</li>
<li>サイト来訪中に特定の条件を満たしたエンドユーザーに対して、1番から順にクーポンコードを払い出し、サイトに配信した接客サービス上に表示する</li>
</ul>
<p>これをCraftで実装するとき、すべてCraft KVSを使うと次のようになります。</p>
<ul>
<li>事前にクーポンコード在庫を通し番号付きでCraft KVSに格納しておく</li>
<li>接客サービスのJavaScriptからエンドポイントトリガー経由でアクセスできるCraft Functionsを実装する
<ul>
<li>Craft KVS上で管理する「現在の通し番号」をgetし、+1してからwriteする</li>
<li>その「現在の通し番号」に対応するクーポンコードをCraft KVSから取得してレスポンスする</li>
</ul>
</li>
</ul>
<p><img src="https://ik.imagekit.io/plaid/39b376ca-c8cd-430f-992e-6556cd134814/%E3%82%B9%E3%82%AF%E3%83%AA%E3%83%BC%E3%83%B3%E3%82%B7%E3%83%A7%E3%83%83%E3%83%882023-10-0318.25.56.png" alt="スクリーンショット2023-10-0318.25.56.png"></p>
<p>ここで注意が必要なのは、 <strong>ほぼ同時にアクセスしてきた複数ユーザーに対して同一の通し番号が割り当てられないようにする必要がある</strong> という点です。</p>
<p>仮にCraft KVSで「通し番号を1から順番に重複なく払い出す」ということを実現する場合、 <a href="https://craft.developers.karte.io/reference/craft-key-value-store/index.html#checkandwrite">checkAndWrite()</a> を利用することになります。</p>
<pre><code class="language-js">export default async function (data, { MODULES }) {
  const { kvs } = MODULES;
  const key = 'coupon_index';
  const v = await kvs.get({ key });
  const { current_index, created_at } = v[key];
  await kvs.checkAndWrite({
    key,
    value: { index: current_index+1 }, // 予めCraft KVSから取得した通し番号に+1してwriteする
    operator: '&lt;=',
    unixtimeMs: new Date(created_at).getTime() // 書き込み時点の更新日が元のレコードの更新日以前なら書き込む
  });
}
</code></pre>
<p><code>checkAndWrite()</code> はKVS内の更新対象のレコードの更新日時（ <code>created_at</code> ）をチェックして、更新日時が意図と反する場合にエラーを投げてくれます。今回の例ではレコード取得した時点よりも後に他のリクエストで同一レコードが更新されてしまった場合、重複実行エラーにすることができます。これにより排他制御を実装でき、「通し番号を1から順番に重複なく払い出す」ということが実現できます。</p>
<p>しかし、重複実行エラーになったリクエストに対しては、再度クーポンコード取得処理を呼ぶ必要があります。このretry処理実装が必要になるのが、Craft KVSを使った実装パターンの大変な点でした。</p>
<p>他方、Craft Counterでは実装する場合は  <code>counter.increment()</code> を利用します。前述のように、Craft KVSでは <code>get()</code> と <code>write()</code> の両方が必要でしたが、クーポン通し番号の取得と更新を1つのメソッド呼び出しで実現できます。</p>
<pre><code class="language-js">export default async function (data, { MODULES }) {
  const { counter } = MODULES;
  const key = 'coupon_index';
  const current_index = await counter.increment({ key }); // +1して、+1した後の値を返す
}
</code></pre>
<p>そしてCraft Counterの <code>increment()</code> は「アトミックに行われる」という特徴があります。言い換えると、 <strong>あるincrement処理の途中で別のincrement処理が割り込むことができない</strong> ようになっています。そのため、ほぼ同時に2人のユーザーがクーポンコードの通し番号を取得した場合であっても、increment処理は順次行われます。</p>
<p>要するに、 <code>counter.increment()</code> を利用するだけで自然と「通し番号を1から順番に重複なく払い出す」という要件が実現され、 <strong>独自にretry処理を実装しなくてもよくなります</strong> 。非同期処理のretryは実装難易度も高いので、個人的にはかなり嬉しいポイントでした。</p>
<p>以上です！その他、Craft Counterの仕様詳細をまとめたドキュメントがすでに公開されています。気になる方はぜひご覧ください。</p>
<p><a href="https://craft.developers.karte.io/craft-counter/gets-startedr">Craft Counter</a></p>
<h1>おわりに</h1>
<p>今回は新しくリリースされたCraft Counterの特徴を3つ紹介しました。特に高いパフォーマンスが求められるケースや排他処理の実装が必要なケースでは、Craft KVSよりもCraft Counterの方が適しています。</p>
<p>なお現時点で <strong>Craft CounterはCraftのGrowthプラン以上を契約頂いているプロジェクトで利用可能</strong> です。現在は利用開始に際してプレイド側での初期設定が必要となりますので、利用を希望される方はサポートや営業担当までご連絡ください。</p>
<p>また本ブログでもCraft Counterを使ったソリューションの記事をいくつか公開予定です。お楽しみに！</p>
<hr>
<p>プレイドでは、世の中にインパクトを与える新しいソリューションを一緒につくる仲間を募集しています！<br>
ぜひ気軽にお問い合わせください。</p>
<p>↓ パートナー企業になりたい</p>
<ul>
<li><a href="https://ecosystem.plaid.co.jp/">CustomerData-Driven Solution を一緒に創りませんか？ | PLAID Ecosystem</a></li>
</ul>
<p>↓ PLAIDで働きたい</p>
<ul>
<li><a href="https://recruit.plaid.co.jp/requisitions/general-customer-engineer">Customer Engineer | 募集ポジション | 株式会社プレイド</a></li>
<li><a href="https://recruit.plaid.co.jp/requisitions/product-engineer">Product Engineer | 募集ポジション | 株式会社プレイド</a></li>
</ul>


Craft Functions内で利用できる高速なカウンター「Craft Counter」がリリースされました。この記事では、新しいデータベースであるCraft Counterの特徴を3つお伝えします。

高パフォーマンスなカウンター用データベース 「Craft Counter」 がリリースされました

高パフォーマンスなカウンター用データベース 「Craft Counter」 がリリースされました🎉

<p>こんにちは。エンジニアの矢澤です。</p>
<p>表題にしれっと書いていますが、KARTE Craftに<a href="https://craft.developers.karte.io/craft-functions/modules/retryable-error">ファンクションの再実行機能</a>が追加されました！この記事では再実行機能の使い方を説明し、実例として、以前ブログに書いた「ユーザー行動をトリガーにWebhookを飛ばす」コードの再実装版を紹介します。</p>
<p><a href="https://solution.plaid.co.jp/202306-craft-webhook">Web上のユーザー行動をトリガーにして外部にWebhookリクエストを飛ばす</a></p>
<h1>「ファンクションの再実行」とは</h1>
<p>今回追加されたファンクション再実行機能は <strong>特定のエラーでファンクションが終了した場合に、そのファンクションを再度起動して初めから処理を実行する</strong> というものです。これまでエラーのリカバリーが必要な場合は自前でリトライ用のコードを書いてましたが、この機能を使うことでもリカバリーができるようになりました。</p>
<p><a href="https://craft.developers.karte.io/craft-functions/modules/retryable-error">RetryableError (ファンクションを再実行する)</a></p>
<h2>「ファンクションの再実行」の使い方</h2>
<p>ファンクションの再実行を行う場合は <code>RetryableError</code> でエラーをthrowします。</p>
<pre><code class="language-javascript">export default async function( data, { MODULES } ) {
  // MODULESからRetryableErrorを取り出す
  const { RetryableError } = MODULES;
  
  try {
    // ... なんらかの処理
  } catch (err) {
    throw new RetryableError('An error occurred. The function will retry shortly.')
  }
}
</code></pre>
<ul>
<li><code>RetryableError</code> は <code>MODULES</code> から取り出せます。</li>
<li>このコードでは <code>try ... catch</code> 構文でエラーをcatchした際に <code>RetryableError</code> をthrowしています。したがって、try節で例外が発生した場合にファンクションを再実行します。</li>
</ul>
<p>ここでは説明のためにtry節で発生したエラーをすべて <code>RetryableError</code> としていますが、実際には <strong>リトライ対象のエラーのみを <code>RetryableError</code> の対象にしましょう</strong> 。なぜかというと、ユーザー起因のエラーはファンクションの再実行では解決せず、期限いっぱいまで無駄に再実行されてしまうためです。</p>
<h2>リトライ実装との使い分け</h2>
<p>ファンクションの再実行機能はリトライ実装をしなくて良い分便利ではありますが、注意点があります。</p>
<ul>
<li>リカバリーのための時間が長くなる（数秒程度。再実行を繰り返すと数分かかることもある）</li>
<li>コードのはじめから再実行するため、同じ条件で実行した処理に対して同じ結果を返すような実装（べき等な実装）をする必要がある</li>
<li>再実行はファンクションの実行回数にカウントされる</li>
</ul>
<p>多くのユースケースはファンクションの再実行機能でカバーできるかと思いますが、例えばエラー時にすぐリトライしたい場合は自前でリトライを実装するというように、必要に応じて使い分けることをお勧めします。</p>
<h1>Webhook接客の再実装</h1>
<p>ここからはファンクション再実行の実用例を紹介します。以前、KARTEの接客とKARTE Craftを組み合わせてユーザー行動に応じてWebhookリクエストを飛ばす方法を紹介しました。</p>
<p><a href="https://solution.plaid.co.jp/202306-craft-webhook">(再掲) Web上のユーザー行動をトリガーにして外部にWebhookリクエストを飛ばす</a></p>
<p>この記事で紹介したコードを「ファンクションの再実行」を使って再実装しました。</p>
<ul>
<li><a href="https://github.com/plaidev/craft-codes/tree/main/craft-functions/webhook-action">craft-codes/craft-functions/webhook-action at main · plaidev/craft-codes</a></li>
</ul>
<h2>再実装版のWebhookのコードを使う</h2>
<p>コードの利用手順は次のとおりです。</p>
<ul>
<li>ブログ記事下部の「このSolutionをKARTE Craftで利用してみる」からテンプレートを展開する。
<ul>
<li>直前に開いていたプロジェクトでCraft Functionsの作成画面に移動するので、事前にKARTE Craftが有効なプロジェクトを開いておいてください。</li>
<li>再実装版のコードでは先日紹介した変数機能 (<a href="https://solution.plaid.co.jp/202310-craft-function-renewal">Craft Function新機能＆画面リニューアルのお知らせ</a>) を使っております。変数にはデフォルト値が入っていますが、必要に応じて変更してください。</li>
</ul>
</li>
<li>ファンクション名を指定して保存する。</li>
<li>以降の手順は以前の記事と同様です。
<ul>
<li><a href="https://solution.plaid.co.jp/202306-craft-webhook">(再掲) Web上のユーザー行動をトリガーにして外部にWebhookリクエストを飛ばす</a></li>
</ul>
</li>
</ul>
<h2>Webhookコード利用時の注意点</h2>
<ul>
<li>複数接客で異なるURLにリクエストをしたい場合でも <strong>ファンクションは1つで問題ありません。</strong></li>
<li>このコードでは1回のWebhookが複数回実行される場合があります。リクエストを重複なく実行させたい場合は以下の記事を参考にリクエストの重複排除を実装してください。
<ul>
<li><a href="https://solution.plaid.co.jp/implementing-exactly-once-semantics-in-karte-craft">KARTE Craftでファンクションの重複実行を防ぐ</a></li>
<li>上記記事で紹介しているCraft KVSを利用する場合はKARTE Craft Growthプランのご契約が必要です。</li>
</ul>
</li>
</ul>
<h2>（おまけ）再実装の詳細</h2>
<p>ここではコードの詳細を説明します。Craft Functionsのコードについて興味をお持ちの方はお読みください。</p>
<p>以前の記事で紹介したサンプルコードでは、Webhook先URLへのリクエストがエラーになった場合のリトライ処理を自前で実装していました。</p>
<ul>
<li><a href="https://github.com/plaidev/craft-codes/tree/a41714108c30953be53f66d6565343e8a9d9babf/craft-functions/webhook-action">craft-codes/craft-functions/webhook-action at a41714108c30953be53f66d6565343e8a9d9babf · plaidev/craft-codes</a></li>
</ul>
<p>次のコードはサンプルコードの一部です。async-retryを使ってリトライを行っています。このコードでは <code>BailError</code> をハンドリングして、それ以外のエラーが発生した場合にリトライを行います。</p>
<pre><code class="language-javascript">  // async-retry を使ったリトライ実装
  return await retry(async (bail, attempt) =&gt; {
    try {
      const resStatus = await requestData({ method, url, data: hookData, headers, campaignId, id });
      logger.log(`[${campaignId}][${id}] Webhook execution completed. status: ${resStatus}`);
      return;
    } catch (err) {
      if (err instanceof BailError) {
        bail(err);
        return;
      }
      if (isTimeoutPerExec({retryOptions, attempt, startMs})) {
        bail(new Error(`[${campaignId}][${id}] Timeout per exec.`));
        return;
      }
      throw err;
    }
  }, retryOptions);
</code></pre>
<p>次のコードは <code>requestData()</code> の一部です。ここでは500系以外のエラーでファンクションを終了するために <code>BailError</code> をthrowしています。</p>
<pre><code class="language-javascript">  const response = await fetch(url, requestOptions);

  if (!response.ok) {
    if (response.status &gt;= 500 &amp;&amp; response.status &lt; 600 || [408, 429].includes(response.status)) {
      // 500系や一時的に発生するエラーはリトライ想定で通常のErrorを発生させる
      throw new Error(`[${campaignId}][${id}] Request failed with status ${response.status}`);
    }
    // ユーザー起因のエラーの場合はリトライを行わないためBailErrorをthrowする
    throw new BailError(`[${campaignId}][${id}] Request failed with status ${response.status}. Bail Error.`);
  }
</code></pre>
<p>再実装版では、上記のコードをファンクションの再実行機能で書き換えています。</p>
<ul>
<li>async-retryのコードは省略できるため、次のように単に <code>requestData()</code> を呼び出すだけになります。<pre><code class="language-javascript">    const resStatus = await requestData({ method, url, data: hookData, headers, campaignId, id, RetryableError });
    logger.debug(
      `[${campaignId}][${id}] Webhook execution completed. status: ${resStatus}`
    );
</code></pre>
</li>
<li>実際にWebhook先にリクエストを行う <code>requestData()</code> では、500系エラーのようなリトライが必要な場合に <code>RetryableError</code> をthrowします。<pre><code class="language-javascript">  const response = await fetch(url, requestOptions);

  if (!response.ok) {
    if (response.status &gt;= 500 &amp;&amp; response.status &lt; 600 || [408, 429].includes(response.status)) {
      throw new RetryableError(
        `[${campaignId}][${id}] Request failed with status ${response.status}`,
        PER_DATA_TIMEOUT_MS // ファンクションが再実行できる期限
      );
    }
    throw new Error(`[${campaignId}][${id}] Request failed with status ${response.status}. Bail Error.`);
  }
</code></pre>
</li>
</ul>
<h1>まとめ</h1>
<p>この記事ではファンクションの再実行機能について説明し、Webhookソリューションの再実装版を紹介しました。エラーハンドリングで再実行の有無が設定できるので、簡単に柔軟なリトライ制御ができるようになりました。</p>
<p>また、ここで紹介したWebhookのロジックはさまざまな応用ができます。ブログ記事下部のボタンでファンクションを作成して、どんどんご活用ください！</p>
<hr>
<p>プレイドでは、世の中にインパクトを与える新しいソリューションを一緒につくる仲間を募集しています！<br>
ぜひ気軽にお問い合わせください。</p>
<p>↓ パートナー企業になりたい</p>
<ul>
<li><a href="https://ecosystem.plaid.co.jp/">CustomerData-Driven Solution を一緒に創りませんか？ | PLAID Ecosystem</a></li>
</ul>
<p>↓ PLAIDで働きたい</p>
<ul>
<li><a href="https://recruit.plaid.co.jp/requisitions/general-customer-engineer">Customer Engineer | 募集ポジション | 株式会社プレイド</a></li>
<li><a href="https://recruit.plaid.co.jp/requisitions/product-engineer">Product Engineer | 募集ポジション | 株式会社プレイド</a></li>
</ul>


「Web上のユーザー行動をトリガーに外部にWebhookリクエストを飛ばす」機能をKARTE Craftのファンクション再実行機能で再実装しました。ファンクションの再実行機能の説明と、再実装したWebhookコードの使い方を紹介します。

Webhook接客をファンクションの再実行機能で再実装しました！

<p>エンジニアのdaikichiです。みなさん<a href="https://johnwick.jp/">ジョン・ウィック：コンセクエンス</a>は <strong>何回観ましたか？</strong> 私は来週に3回目を予定しています。</p>
<p>さて、本日KARTE Craft Functionsの新機能及び刷新した管理画面をリリースしました！</p>
<h1>管理画面リニューアル</h1>
<p><img src="https://ik.imagekit.io/plaid/b2073118-a104-4c06-ac23-b1840eba0139/%E3%82%B9%E3%82%AF%E3%83%AA%E3%83%BC%E3%83%B3%E3%82%B7%E3%83%A7%E3%83%83%E3%83%882023-09-2914.35.05.png" alt="スクリーンショット2023-09-2914.35.05.png"></p>
<p>コードエディタ部分が新たに見やすくなるなど、画面を全体的に刷新しました。</p>
<h1>テンプレート検索パネル</h1>
<p><img src="https://ik.imagekit.io/plaid/9a812031-c1a3-4bb2-bde2-4cc84abd106a/スクリーンショット2023-09-2914.36.38.png" width="300px"> <img src="https://ik.imagekit.io/plaid/f0b2fafb-5ca3-4cb5-8f4d-c63910b587bd/スクリーンショット2023-09-2914.37.57.png" width="300px"></p>
<p>このBlogで紹介しているSolutionのサンプルコードの一部を管理画面内で検索することができます。<br>
検索したコードは即座に編集中のエディタに反映することが可能です。</p>
<h1>変数機能</h1>
<p><img src="https://ik.imagekit.io/plaid/4ddf663a-8ee7-402e-b858-f61f4f53a88c/%E3%82%B9%E3%82%AF%E3%83%AA%E3%83%BC%E3%83%B3%E3%82%B7%E3%83%A7%E3%83%83%E3%83%882023-09-2914.51.12.png" alt="スクリーンショット2023-09-2914.51.12.png"><br>
ファンクション編集画面に新たに「変数」タブができました。<br>
ここで変数の内容を設定し、コード内 に<code>&lt;% var_name %&gt;</code>の形で記述すると、ファンクションのデプロイ時に変数がコード内に展開されます。</p>
<p>Solutionテンプレート内にはこの変数機能が設定されたものが多くあります。それらを利用することで、お客様固有の値を変数タブで編集するだけで、JavaScriptを一切編集することなくSolutionの利用が可能になります！</p>
<p><a href="https://developers.karte.io/docs/%E5%A4%89%E6%95%B0%E3%81%AE%E5%88%A9%E7%94%A8">変数機能のドキュメントはこちら</a></p>
<h1>Solution Blog記事からファンクション編集画面へ直接遷移</h1>
<p><img src="https://ik.imagekit.io/plaid/ee7ff966-5023-4b68-af2c-a8a51b859138/image(2).png" alt="image(2).png"><br>
KARTE CraftのSolution記事からファンクションへ遷移するボタンを作りました！こちらのボタンをクリックするとその記事のSolutionのサンプルコードがすでに記入された状態の管理画面が表示されます。<br>
お気に入りのSolution記事があるけど利用の一歩を踏み出せなかった方はぜひこのボタンをポチっとしてみてください。</p>
<h1>おわりに</h1>
<p>KARTE Craftは今後も様々な新機能が実装される予定です。ぜひご期待ください！</p>


便利になったCraft Functionの画面と新機能をご紹介します！

Craft Function新機能＆画面リニューアルのお知らせ

<p>こんにちは、Customer EngineerのKohaです！<br>
今回が初投稿となります。お手柔らかにお願い申し上げます。</p>
<p>本記事では、先んじて投稿のあった「<a href="https://solution.plaid.co.jp/202309-ms-teams-change-campaign-status">Microsoft TeamsからKARTEの接客サービスの公開／非公開状態を切り替える</a>」の、Slackバージョンを紹介いたします。</p>
<p>こんな感じでSlackに接客情報とボタンを表示して、ボタン操作で接客ステータスを変更できるようになります。<br>
<img src="https://ik.imagekit.io/plaid/1867f35c-03fe-409c-b303-783dbdc71d1d/%E3%82%B9%E3%82%AF%E3%83%AA%E3%83%BC%E3%83%B3%E3%82%B7%E3%83%A7%E3%83%83%E3%83%882023-09-1216.11.13.png" alt="スクリーンショット2023-09-1216.11.13.png"></p>
<h1>用意する部品</h1>
<p>Slack Apps（Slackアプリ）×1<br>
Craft Functions × 2</p>
<h1>処理の流れ</h1>
<p>ざっくりイメージは冒頭の通りですが、詳しい仕組みはこのようになってます。<br>
<img src="https://ik.imagekit.io/plaid/fe2680bb-f982-43d8-a389-2f21847836cd/%E3%82%B9%E3%82%AF%E3%83%AA%E3%83%BC%E3%83%B3%E3%82%B7%E3%83%A7%E3%83%83%E3%83%882023-09-1210.06.50.png" alt="スクリーンショット2023-09-1210.06.50.png"></p>
<p>端的に書くと、<br>
・Slack上でSlash commandを実行して接客とボタンを表示<br>
・公開か停止かのボタンを押して接客のステータスを変更<br>
という流れです！</p>
<h1>実装手順</h1>
<p>実装の手順は次の通りです。</p>
<ol>
<li>Slack アプリの作成</li>
<li>Slack アプリをチャンネルに追加する</li>
<li>API v2 アプリを作成する</li>
<li>Slack アプリの OAuth トークンをCraft Secret Managerに登録する</li>
<li>API v2アプリのアクセストークンをCraft Secret Managerに登録する</li>
<li>Craft Functions を2つ作成する</li>
<li>Craft Functionsのエンドポイントを作成する</li>
<li>SlackアプリのSlach Commandを作成する</li>
<li>SlackアプリのInteractivityを有効にする</li>
</ol>
<p>順番に説明します。</p>
<p>まず、手順1〜4は以前に投稿した記事、<br>
「<a href="https://solution.plaid.co.jp/202307-hookv2-slack-integration">KARTE CraftでKARTEの接客ステータス変更時にSlack通知をする</a>」<br>
と全く同じです。こちらを実施した前提で手順5から説明します。</p>
<h2>5. API v2アプリのアクセストークンをCraft Secret Managerに登録する</h2>
<p>Slack側のアクション駆動でCraft Functionを起動する場合、API v2アプリへのアクセスも実装するので本手順も必要となります。手順4と同様に登録してください。</p>
<h2>6. Craft Functions を2つ作成する</h2>
<p>今回は、<br>
①接客サービス情報をSlackへ送る<br>
　<a href="https://github.com/plaidev/craft-codes/blob/main/craft-functions/slack-change-campaign-status-send/index.js">サンプルコード①</a></p>
<p>②接客ステータスを切り替える<br>
　<a href="https://github.com/plaidev/craft-codes/blob/main/craft-functions/slack-change-campaign-status-receive/index.js">サンプルコード②</a></p>
<p>サンプルコードを利用する場合は以下3つの定数を手動でご自身のものを代入してください。</p>
<pre><code>/* KARTE API V2 Setting - ACCESS TOKEN */
const SECRET_KEY_API = &quot;&quot;;

/* Slack App - Bot User OAuth Token */
const SECRET_KEY_SLACK = &quot;&quot;;

/* KARTE Project ID */
const PROJECT_ID = &quot;&quot;;
</code></pre>
<p>またそれぞれのFunctionのロジックは以下のようになっております。</p>
<h5>接客サービス情報をSlackへ送るFunction</h5>
<p>Slackから渡された接客IDでKARTE API v2（<a href="https://developers.karte.io/reference/post_v2beta-action-campaign-findbyid">接客取得API</a>）を利用し接客を検索する<br>
↓<br>
Slackに送るボタンと接客名・URLを含めたメッセージを作りSlackに送る</p>
<h5>接客ステータスを切り替えるFunction</h5>
<p>Slackのボタン操作結果からKARTE APIv2(<a href="https://developers.karte.io/reference/post_v2beta-action-campaign-findbyid">接客ステータス変更API</a>)を利用し接客ステータスを変更する<br>
↓<br>
変更結果をSlackに返し初めに送ったメッセージを更新する</p>
<h5>※補足：Slackへ送るボタンデザインの方法</h5>
<p>サンプルコードでは以下のように変数messageにJSON形式の値を詰めています。<br>
Slack APIを利用してSlackにメッセージをPostする際はJSONを渡す必要がありますが、描画する内容は<code>blocks</code>に表現します。この中身を簡単に作れるツールをSlackが公式に提供しており、テンプレートもいくつか用意されているようなので、もっとおしゃれでリッチにしたい！という方がいればお試しください。<br>
<a href="https://app.slack.com/block-kit-builder/">Slack | Block Kit Builder</a></p>
<pre><code>const message = {
        &quot;channel&quot;: channelId,
        &quot;attachments&quot;: [
            {
                &quot;fallback&quot;: campaign.campaignName,
                &quot;callback_id&quot;: campaign.campaignId
            }
        ],
        &quot;blocks&quot;: [
        / * 〜ここがUIを表現する箇所〜 */
　　　]
 }
</code></pre>
<h2>7. Craft Functionsのエンドポイントを作成する</h2>
<p>作成した2つのFunctionに対して、<br>
「<a href="https://solution.plaid.co.jp/202309-ms-teams-change-campaign-status">Microsoft TeamsからKARTEの接客サービスの公開／非公開状態を切り替える</a>」<br>
の手順3「Craft Functions の エンドポイントURLを作成する」を実施してください。</p>
<h2>8. SlackアプリのSlach Commandを作成する</h2>
<p>手順1で作成したSlackアプリにSlash Commandを設定します。</p>
<ul>
<li>作成したアプリを選択し、[Features &gt; Slash Commands]をクリック</li>
<li><code>Create New Command</code>をクリック。</li>
</ul>
<p><img src="https://ik.imagekit.io/plaid/6fa7232e-5cfb-4838-a097-86d0a957320b/%E3%82%B9%E3%82%AF%E3%83%AA%E3%83%BC%E3%83%B3%E3%82%B7%E3%83%A7%E3%83%83%E3%83%882023-09-1215.36.07.png" alt="スクリーンショット2023-09-1215.36.07.png"></p>
<ul>
<li>Commandに任意のコマンドを入力する。<br>
※Slackワークスペース内では同名称のCommandが許容されますが、最新のもののみが有効となるようなのでご注意ください。</li>
<li>Request URLに手順7で作成した<strong>接客サービス情報をSlackへ送るFunction</strong>のCraft EndpointのURLを入力する。</li>
<li>Short Discriptionに任意の説明文を入力する。</li>
<li><code>Save</code>をクリックする<br>
<img src="https://ik.imagekit.io/plaid/1db1fc65-9044-4dc6-8420-7249d02414b0/%E3%82%B9%E3%82%AF%E3%83%AA%E3%83%BC%E3%83%B3%E3%82%B7%E3%83%A7%E3%83%83%E3%83%882023-09-1215.39.19.png" alt="スクリーンショット2023-09-1215.39.19.png"></li>
</ul>
<h2>9. SlackアプリのInteractivityを有効にする</h2>
<p>今度はSlackに表示させたボタンをクリックした際にアクセスするURLを指定します。</p>
<ul>
<li>[Features &gt; Interactivity &amp; Shortcuts]をクリック。</li>
<li>Offとなっている箇所をOnに切り替える。</li>
<li>Request URLに手順7で作成した<strong>接客ステータスを切り替えるFuntion</strong>のCraft EndpointのURLを入力する。</li>
<li><code>Save Changes</code>をクリックして保存する。<br>
<img src="https://ik.imagekit.io/plaid/243f1e10-2f2d-42b0-9a1c-b2579f791e0d/%E3%82%B9%E3%82%AF%E3%83%AA%E3%83%BC%E3%83%B3%E3%82%B7%E3%83%A7%E3%83%83%E3%83%882023-09-1215.41.32.png" alt="スクリーンショット2023-09-1215.41.32.png"><br>
　※上キャプチャに含まれる「Shortcuts」は今回利用しないので設定不要です。</li>
</ul>
<h1>実際に動かしてみる</h1>
<p>実際に動作を確認してみましょう。</p>
<ul>
<li>
<p>今回作成したアプリを追加したチャンネルでSlash Commandを投稿する<br>
<img src="https://ik.imagekit.io/plaid/7ea87771-f17c-4720-a718-f7776a322fea/%E3%82%B9%E3%82%AF%E3%83%AA%E3%83%BC%E3%83%B3%E3%82%B7%E3%83%A7%E3%83%83%E3%83%882023-09-1216.07.21.png" alt="スクリーンショット2023-09-1216.07.21.png"></p>
</li>
<li>
<p>接客情報を取得中であるメッセージが表示された後、接客名、URL、ボタンが表示されることを確認します。<br>
※非公開メッセージで返ってくる{id:xxxx}はCraft Functionの実行IDです。2023年9月現在はこの文字列が固定で表示される仕様となっております。<br>
<img src="https://ik.imagekit.io/plaid/1867f35c-03fe-409c-b303-783dbdc71d1d/%E3%82%B9%E3%82%AF%E3%83%AA%E3%83%BC%E3%83%B3%E3%82%B7%E3%83%A7%E3%83%83%E3%83%882023-09-1216.11.13.png" alt="スクリーンショット2023-09-1216.11.13.png"></p>
</li>
<li>
<p>現在は停止中だったので<code>公開する</code>ボタンをクリックし、変更されたことを確認します。<br>
<img src="https://ik.imagekit.io/plaid/563a7e3c-04a2-4eec-af50-88287cbffb36/%E3%82%B9%E3%82%AF%E3%83%AA%E3%83%BC%E3%83%B3%E3%82%B7%E3%83%A7%E3%83%83%E3%83%882023-09-1216.14.22.png" alt="スクリーンショット2023-09-1216.14.22.png"></p>
</li>
<li>
<p>KARTE上でも確認する。<br>
<img src="https://ik.imagekit.io/plaid/3b24bae8-67c9-425d-bb70-7e01d4c3e355/%E3%82%B9%E3%82%AF%E3%83%AA%E3%83%BC%E3%83%B3%E3%82%B7%E3%83%A7%E3%83%83%E3%83%882023-09-1216.37.57.png" alt="スクリーンショット2023-09-1216.37.57.png"></p>
</li>
</ul>
<h1>おわりに</h1>
<p>Teamsから接客ステータスを変更するソリューションに続き、Slackからも接客のステータスを変更できるようになりました！ぜひ活用してみてください。</p>
<p>今回は接客IDを指定し、1つずつ接客を編集する仕様にてご紹介しましたが例えばKARTE Datahubをご利用であればジョブフロー機能を利用して接客の一覧を取得してSlackに投稿するというような応用も考えられます！</p>
<p>Slackをご利用の方はたくさんいらっしゃると思いますので、こういう使い方ができないだろうか？といったご意見お待ちしております！</p>
<hr>
<p>プレイドでは、世の中にインパクトを与える新しいソリューションを一緒につくる仲間を募集しています！<br>
ぜひ気軽にお問い合わせください。</p>
<p>↓ パートナー企業になりたい</p>
<ul>
<li><a href="https://ecosystem.plaid.co.jp/">CustomerData-Driven Solution を一緒に創りませんか？ | PLAID Ecosystem</a></li>
</ul>
<p>↓ PLAIDで働きたい</p>
<ul>
<li><a href="https://recruit.plaid.co.jp/requisitions/general-customer-engineer">Customer Engineer | 募集ポジション | 株式会社プレイド</a></li>
<li><a href="https://recruit.plaid.co.jp/requisitions/product-engineer">Product Engineer | 募集ポジション | 株式会社プレイド</a></li>
</ul>


KARTE CraftとSlack APIを利用するしKARTEの接客サービスへアクセスします。スマホなどから簡単に接客の公開非公開を操作することが可能になります。

SlackからKARTEの接客サービスの公開／非公開状態を切り替える

<p>こんにちは、Customer Engineerの島本です！<br>
こないだ錦糸町にある黄金湯に行ってきたのですが、<br>
女湯はコンパクトな作りのためセルフロウリュウでアツアツにできてとても良かったです！<br>
<img src="https://ik.imagekit.io/plaid/bb207543-cf14-430d-bf7a-79ec1941f2de/IMG_1383.jpg" alt="IMG_1383.jpg"></p>
<p>さて、KARTE をサイトの障害やメンテナンス情報といった急を要するような情報をユーザーに届けるために活用頂いている方も多いかと思いますが、その場合常にKARTE の管理画面にアクセスできる状態でないといけないという制約が発生します。</p>
<p>そんな時に、「<strong>KARTE の管理画面以外から接客サービスの公開非公開を変えたいな。社内のコミュニケーションツール使って変えられたら楽なのに</strong>」と思ったことはありませんか？</p>
<p>なんと、KARTE Craft を使うことで外部サービスからKARTE の接客サービスの公開非公開を変えることを実現できます！</p>
<p>今回は「Microsoft TeamsからKARTEの接客サービスの公開／非公開状態を切り替える」方法について紹介します。イメージとしてはこんな感じです。<br>
<img src="https://ik.imagekit.io/plaid/e57b8788-01af-42cb-86e5-bb7142fc1377/%E3%82%B9%E3%82%AF%E3%83%AA%E3%83%BC%E3%83%B3%E3%82%B7%E3%83%A7%E3%83%83%E3%83%882023-09-0422.51.59.png" alt="スクリーンショット2023-09-0422.51.59.png"></p>
<h1>処理の流れ</h1>
<p>全体の処理の流れは、次の通りです。<br>
<img src="https://ik.imagekit.io/plaid/cff24487-efb7-4ba0-bf26-7ef96349dd72/ms-teams-change-campaign-status.png" alt="ms-teams-change-campaign-status.png"></p>
<p>実現する上で必要なプロダクトやオプションは以下になります。</p>
<ul>
<li><a href="https://karte.io/">KARTE</a></li>
<li><a href="https://ecosystem.plaid.co.jp/product/karte-craft">KARTE Craft</a></li>
</ul>
<p>また、Craft Functions とMicrosoft Teams との連携では次の3つの機能を利用します。</p>
<ul>
<li><a href="https://learn.microsoft.com/ja-jp/microsoftteams/platform/webhooks-and-connectors/how-to/add-outgoing-webhook?tabs=urljsonpayload%2Cdotnet">Teams 送信 Webhook</a>
<ul>
<li>@メンションを使用してチャネル内のメッセージを外部サービスに送信し応答する</li>
</ul>
</li>
<li><a href="https://craft.developers.karte.io/craft-functions/triggers/endpoint">Craft Endpoint トリガー</a>
<ul>
<li>Craft Functionを実行するためのHTTPエンドポイント</li>
</ul>
</li>
<li><a href="https://developers.karte.io/reference/post_v2beta-action-campaign-toggleenabled">Toggle campaign's enabled status API</a>
<ul>
<li>接客サービスの公開・非公開を制御するAPI</li>
</ul>
</li>
</ul>
<h1>実装手順</h1>
<p>実装の手順は次の通りです。<br>
大きく分けてTeams 側と KARTE 側のそれぞれの設定があります。</p>
<ol>
<li>API v2 アプリを作成する</li>
<li>API v2 アプリの アクセストークンを Craft Secret Manager に登録する</li>
<li>Craft Functions の エンドポイントURLを作成する</li>
<li>Teams でチームを作成する</li>
<li>Teams で作成したチームに送信 Webhookを作成する</li>
<li>Teams 送信 Webhookの HMAC トークンを Craft Secret Manager に登録する</li>
<li>Craft Functions を作成する</li>
</ol>
<p>順番に見てみましょう。</p>
<h2>1. API v2 アプリを作成する</h2>
<p>まず、Toggle campaign's enabled status API を利用するためのAPI v2アプリを作成します。<br>
<img src="https://ik.imagekit.io/plaid/bfe2f6a8-b78c-4c95-ad91-db59ecc03a9b/image(5).png" alt="image(5).png"></p>
<ul>
<li>[ストア &gt; API v2設定] からアプリを新規作成</li>
<li>[アプリタイプ] を <code>token</code> に設定</li>
<li>必要なscopeを追加
<ul>
<li><code>beta.action.campaign.toggleEnabled</code>: API に必要</li>
</ul>
</li>
<li>アプリを保存し、一度だけ表示されるアクセストークンを控えておく</li>
</ul>
<p>「アプリタイプ」は後から変更できないため、誤って作成した場合は、アプリを再度作成し直してください。</p>
<h2>2. API v2 アプリの アクセストークンを Craft Secret Manager に登録する</h2>
<p>API v2 アプリのアクセストークンを Craft Secret Manager のシークレットとして登録します。それにより、秘匿すべきアクセストークンをファンクション上に直接記述する必要が無くなります。<br>
<img src="https://ik.imagekit.io/plaid/116765b1-4d21-4d74-8d3e-e5a4e4431e5b/image(6).png" alt="image(6).png"></p>
<ul>
<li>[Craft &gt; シークレット] からシークレットを新規作成</li>
<li>控えておいたアクセストークンを貼り付けて、適当な名前を付けて保存</li>
</ul>
<p>作成したシークレットの名前は、最後に作成するCraft Functions のファンクション中に記載します。</p>
<h2>3. Craft Functions の エンドポイントURLを作成する</h2>
<p>Craft Functionsを作成して一度保存した後に、エンドポイント設定からURLを作成します。<br>
<img src="https://ik.imagekit.io/plaid/a1c8021e-4690-40ad-8e91-2efb5cad5176/image(7).png" alt="image(7).png"></p>
<p>作成したエンドポイントURLはTeams で作成する送信 WebhookのコールバックURLに記載します。</p>
<h2>4. Teams でチームを作成する</h2>
<p>チームを作成してKARTE の接客サービスのステータスを変更するメンバーを追加します。</p>
<h2>5. Teams で作成したチームに送信 Webhookを作成する</h2>
<p>KARTE Craftにメッセージを送信するための送信 Webhookを作成します。<br>
コールバック URLには先程控えておいたCraft Functions の エンドポイントURLを記載します。</p>
<ul>
<li>
<p>送信 Webhook を作成するチームを選択し、[チームを管理 &gt; アプリ] から<code>送信 Webhook を作成</code>をクリック</p>
</li>
<li>
<p>次の画面で アプリの詳細を設定<br>
<img src="https://ik.imagekit.io/plaid/11d09e63-5f7f-4e09-8f06-995e14d4acf3/%E3%82%B9%E3%82%AF%E3%83%AA%E3%83%BC%E3%83%B3%E3%82%B7%E3%83%A7%E3%83%83%E3%83%882023-09-0413.15.32.png" alt="スクリーンショット2023-09-0413.15.32.png"></p>
<ul>
<li><strong>名前</strong>
<ul>
<li>Webhook タイトルと @メンション タブ</li>
</ul>
</li>
<li><strong>コールバック URL</strong>
<ul>
<li>Craft Functions の エンドポイントURL</li>
</ul>
</li>
<li><strong>説明</strong>
<ul>
<li>プロファイル カードとチーム レベルのアプリ ダッシュボードに表示される詳細な説明文</li>
</ul>
</li>
<li><strong>プロフィール画像</strong>
<ul>
<li>Webhook のアプリ アイコン (省略可能)</li>
</ul>
</li>
</ul>
</li>
<li>
<p>作成をクリックするとハッシュ ベースのメッセージ認証コード (HMAC) ダイアログが表示されるため、セキュリティトークンを控えておく<br>
<img src="https://ik.imagekit.io/plaid/da0179b4-9498-49b4-bb12-dbc41336dec9/%E3%82%B9%E3%82%AF%E3%83%AA%E3%83%BC%E3%83%B3%E3%82%B7%E3%83%A7%E3%83%83%E3%83%882023-09-0413.44.42.png" alt="スクリーンショット2023-09-0413.44.42.png"></p>
</li>
</ul>
<h2>6. Teams 送信Webhookの HMAC を Craft Secret Manager に登録する</h2>
<p>先程と同様に、Teams 送信 WebhookのHMAC トークンを Craft Secret Manager のシークレットとして登録します。</p>
<ul>
<li>[Craft &gt; シークレット] からシークレットを新規作成</li>
<li>控えておいたHMAC トークンを貼り付けて、適当な名前を付けて保存</li>
</ul>
<p>作成したシークレットの名前は、最後に作成するCraft Functions のファンクション中に記載します。</p>
<h2>7. Craft Functions を作成する</h2>
<p>Teams から受け取った情報を元に接客サービスの公開非公開を切り替えるためのCraft Functions のファンクションを作成します。<br>
サンプルとなるソースコードは、GitHubで公開しています。<br>
<a href="https://github.com/plaidev/craft-codes/tree/main/craft-functions/ms-teams-change-campaign-status">craft-codes/craft-functions/ms-teams-change-campaign-status at main · plaidev/craft-codes · GitHub</a></p>
<p>実装内容は、次のとおりです。</p>
<ol>
<li>リクエストに含まれるHMAC証明書の認証を行う</li>
<li>Teams からステータスを変更する接客サービスの内容を受け取る</li>
<li>KARTE の接客サービスの公開／非公開を切り替える</li>
<li>Teams にステータスを変更した接客の情報を送信する</li>
</ol>
<p>Craft Functions作成画面のcode に サンプルコードのindex.js の内容を貼り付け、modules に modules.json の内容を貼り付けます。冒頭に以下の2つを定数に指定します。</p>
<ul>
<li>シークレット名
<ul>
<li>KARTE_APP_SECRET_NAME
<ul>
<li>Craft Secret Manager に登録したAPI v2のSecret名を貼り付ける</li>
</ul>
</li>
<li>TEAMS_OUTGOING_WEBHOOK_SECRET_NAME
<ul>
<li>Craft Secret Manager に登録した HMACトークンのSecret名を貼り付ける</li>
</ul>
</li>
</ul>
</li>
</ul>
<pre><code>const KARTE_APP_SECRET_NAME = '';
const TEAMS_OUTGOING_WEBHOOK_SECRET_NAME = '';
</code></pre>
<p>以下の場合にはエラーメッセージがTeams に返ってくるようにしていますが、必要に応じて変更してください。</p>
<ul>
<li>HMAC トークンが間違っている場合
<ul>
<li><code>提供された認証情報が無効です。正しい認証情報を提供して再度試してください。</code></li>
</ul>
</li>
<li>接客IDが間違っている／入力されていない場合
<ul>
<li><code>入力データ内に接客サービスIDが見つかりませんでした。</code></li>
</ul>
</li>
<li>ステータスが間違っている／入力されていない場合
<ul>
<li><code>入力データ内にtrue/falseが見つかりませんでした。</code></li>
</ul>
</li>
</ul>
<p>これで、Teams から投稿した際にファンクションが実行され、KARTE の接客のステータスを変更する設定が完了しました。</p>
<h1>注意点</h1>
<p>サンプルコードを使用する場合、いくつか注意点がありますのでご留意ください。</p>
<ul>
<li>KARTE の接客サービスの公開／非公開を切り替えるためには、接客サービス毎のIDとステータス情報が必要になります。サンプルコードでは、Teams から接客サービスIDとステータス情報（true/false）を受け取った場合にステータスを切り替える実装になっているため、事前に対象の接客サービスIDを控えておいてください。</li>
<li>サンプルコードでは1投稿につきステータス変更できる接客はひとつになります。投稿する際に複数の接客サービスIDとステータスを入力しても、最初に入力した方しか変更されないため分けて投稿してください。</li>
<li>Teams 送信 Webhookでは、5秒以内にテキストが返ってこない場合は、<code>Sorry, there was a problem encountered with your request</code>というエラーが返ってきます。Craft Functionsの実行に時間がかかっている場合があるため、上記エラーが返ってきたときには、再度投稿を試してください。</li>
</ul>
<p>以上となります。</p>
<h1>実際に動かしてみる</h1>
<p>では、実際に動かしてみましょう！！</p>
<p>まず、対象の接客サービスIDを控えておきます。<br>
<img src="https://ik.imagekit.io/plaid/995116f2-13a3-41e2-8407-2c0c6a3d2838/%E3%82%B9%E3%82%AF%E3%83%AA%E3%83%BC%E3%83%B3%E3%82%B7%E3%83%A7%E3%83%83%E3%83%882023-09-0515.05.25.png" alt="スクリーンショット2023-09-0515.05.25.png"></p>
<p>現在は停止中なので、Teams から投稿して公開状態に切り替えてみようと思います。</p>
<p><img src="https://ik.imagekit.io/plaid/e57b8788-01af-42cb-86e5-bb7142fc1377/%E3%82%B9%E3%82%AF%E3%83%AA%E3%83%BC%E3%83%B3%E3%82%B7%E3%83%A7%E3%83%83%E3%83%882023-09-0422.51.59.png" alt="スクリーンショット2023-09-0422.51.59.png"><br>
作成した送信 Webhookをメンションして、接客サービスIDとステータス情報を入力して投稿したところ、接客のステータスが変わったと返信がきました！</p>
<p>実際に管理画面で公開状態に切り替わっているか確認してみましょう。<br>
<img src="https://ik.imagekit.io/plaid/de0f489e-1367-4e9f-8e76-d3adf0ad5dc4/%E3%82%B9%E3%82%AF%E3%83%AA%E3%83%BC%E3%83%B3%E3%82%B7%E3%83%A7%E3%83%83%E3%83%882023-09-0422.53.53.png" alt="スクリーンショット2023-09-0422.53.53.png"><br>
接客のステータスが公開中に切り替わっていますね！！</p>
<h1>おわりに</h1>
<p>今回はCraft Functionを実行するためにCraft Endpoint トリガーを使いましたが、一般的にエンドポイント（URL）が流出すると誰でも叩ける状態になってしまうというセキュリティリスクがあります。</p>
<p>Teams の送信 Webhook にはTeams と指定された外部サービス間の呼び出しを認証するために使用されるHMAC セキュリティトークンが用意されているため、不正な操作を防止することができ、安心して利用できますね。</p>
<p>「<strong>うちはTeams じゃなくてSlack 使ってるんだけどなあ</strong>」と思ったそこのあなた！<br>
安心してください。Slack からでもKARTE 接客サービスの公開／非公開状態を切り替えることできます。</p>
<p>その内容については8月に入社したkoha が執筆してくれますので乞うご期待！！！！！！</p>
<p>※2023/9/12追記<br>
早速執筆してくれたみたいなのでこちらもぜひご一読ください！<br>
<a href="https://solution.plaid.co.jp/202309-slack-change-campaign-status">SlackからKARTEの接客サービスの公開／非公開状態を切り替える</a></p>
<hr>
<p>プレイドでは、世の中にインパクトを与える新しいソリューションを一緒につくる仲間を募集しています！<br>
ぜひ気軽にお問い合わせください。</p>
<p>↓ パートナー企業になりたい</p>
<ul>
<li><a href="https://ecosystem.plaid.co.jp/">CustomerData-Driven Solution を一緒に創りませんか？ | PLAID Ecosystem</a></li>
</ul>
<p>↓ PLAIDで働きたい</p>
<ul>
<li><a href="https://recruit.plaid.co.jp/requisitions/general-customer-engineer">Customer Engineer | 募集ポジション | 株式会社プレイド</a></li>
<li><a href="https://recruit.plaid.co.jp/requisitions/product-engineer">Product Engineer | 募集ポジション | 株式会社プレイド</a></li>
</ul>


KARTE Craftを使って「Microsoft TeamsからKARTEの接客サービスの公開／非公開状態を切り替える」方法について紹介します。

Solution Blog

Recent Article

「Craft FunctionsのIPアドレスを固定する」機能をリリースしました！

「配信数やクリック数に応じた接客サービスの自動停止」をCraft Counterで実装する

クーポン在庫を順次払い出すAPIをKARTE Craftで実装してみた

Datahubクエリの結果をCraft KVSに格納してみた

「回答後に集計結果がリアルタイム表示されるアンケート」をCraft Counterで実装する

高パフォーマンスなカウンター用データベース「Craft Counter」がリリースされました🎉

Webhook接客をファンクションの再実行機能で再実装しました！

Craft Function新機能＆画面リニューアルのお知らせ

SlackからKARTEの接客サービスの公開／非公開状態を切り替える

Microsoft TeamsからKARTEの接客サービスの公開／非公開状態を切り替える

Archives

Writers

Recent Article

「Craft FunctionsのIPアドレスを固定する」機能をリリースしました！

「配信数やクリック数に応じた接客サービスの自動停止」をCraft Counterで実装する

クーポン在庫を順次払い出すAPIをKARTE Craftで実装してみた

Datahubクエリの結果をCraft KVSに格納してみた

「回答後に集計結果がリアルタイム表示されるアンケート」をCraft Counterで実装する

高パフォーマンスなカウンター用データベース 「Craft Counter」 がリリースされました🎉

Webhook接客をファンクションの再実行機能で再実装しました！

Craft Function新機能＆画面リニューアルのお知らせ

SlackからKARTEの接客サービスの公開／非公開状態を切り替える

Microsoft TeamsからKARTEの接客サービスの公開／非公開状態を切り替える

Archives

Writers

高パフォーマンスなカウンター用データベース「Craft Counter」がリリースされました🎉