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にファイル保存する

KARTE Craftを使って自社Instagramアカウントの投稿を定期取得し、KARTEがWebに配信するアクションに自由なフォーマットで埋め込む方法について紹介します。

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

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

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

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

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

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

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

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

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

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

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


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

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

KARTEの接客サービス配信機能とKARTE Datahubが使える環境であれば、KARTEでレコメンド用のデータ管理からWebサイトへのクリエイティブの配信までを一気通貫で実現できます。今回は、KARTEが言う所の「レコメンド」を実現する最低限の手順を簡単に紹介します。

KARTEでレコメンドを実装してみた

<p>こんにちは。プレイドの矢澤です。</p>
<p>この記事は前後編の後編です。前編はこちらです。</p>
<p><a href="https://solution.plaid.co.jp/karte-craft-improve-customer-data-utilization-1">KARTEとKARTE Craftでユーザー情報の活用の幅が広がる話 (前編)</a></p>
<p>前回の記事では、KARTEとKARTE Craftについてエンジニアの方向けに紹介いたしました。KARTEのユーザーを「知る」機能の仕組みと、ユーザー状態の変化をKARTE Craftで外部に連携することで、KARTEをユーザー情報解析のバックエンドにできるのではないか、という話をしました。</p>
<p>とはいえ実際にKARTEとKARTE Craftを触ってみないとその感覚はわからないかと思います。そこで、後編ではユーザーの状態変化をリアルタイムに外部連携するサンプル実装を作ってみようと思います。</p>
<h1>作るもの</h1>
<p>今回は、KARTE内で発生するイベントをキッカケにユーザー情報をGoogle BigQueryに連携するサンプルを作成してみようと思います。動作を簡単に図で表現すると以下の通りです。</p>
<p><img src="https://ik.imagekit.io/plaid/dddec887-dfaa-469b-a109-76848506357a/craft_bigquery_sample.png" alt="craft_bigquery_sample.png"></p>
<ul>
<li>KARTEを利用しているページで、URLアンカーに特定の文字列が含まれていたらCraft Functionを発火する</li>
<li>受け取ったユーザー情報と閲覧しているWebサイトのURLをBigQueryのテーブルに記録する</li>
</ul>
<p>ユースケース的には微妙ではありますが、KARTEのデータがリアルタイムに外部サービスで利用できる感覚は持っていただけるかと思います。</p>
<h1>準備</h1>
<p>2023年4月現在、KARTE Craftはβ版として提供しています。利用にあたっては以下のページからの申し込みが必要です。</p>
<p><a href="https://docs.google.com/forms/d/e/1FAIpQLSfxNJl-HttTQPVZiqM3hyBzceSyzLNJ9BlLxwOWC1USoZmt_A/viewform">KARTE Craft 利用申請</a></p>
<p>このサンプルではBigQueryを利用するので、Google Cloudが利用できる環境をご準備ください。データの書き込み・読み取りにあたってはGoogle Cloudの利用料金が発生するので注意してください。</p>
<h1>手順</h1>
<p>では実装していきましょう。作業は大まかに分けて2つあります。</p>
<ul>
<li>BigQueryのテーブルにデータを書き込むファンクションの作成</li>
<li>サイト来訪ユーザーの閲覧 (View) をトリガーにCraft Functionsを起動するアクションの作成</li>
</ul>
<p>順番に説明します。</p>
<h2>BigQueryのテーブルにデータを書き込むファンクションを作成する</h2>
<p>まずはBigQueryのテーブルにデータを書き込む処理を実装します。</p>
<h3>BigQuery のテーブルを作成する</h3>
<p>事前にBigQueryのテーブルを作成しておきます。ドキュメントを参考にスキーマ定義つきのテーブルを作成します。<br>
<a href="https://cloud.google.com/bigquery/docs/tables?hl=ja#create_an_empty_table_with_a_schema_definition">テーブルの作成と使用  |  BigQuery  |  Google Cloud</a></p>
<p>今回はイベント発生時刻、ビジターID、閲覧先URLのみを連携するので、スキーマには以下を設定します。</p>
<table>
<thead>
<tr>
<th>フィールド</th>
<th>型</th>
<th>モード</th>
</tr>
</thead>
<tbody>
<tr>
<td>datetime</td>
<td>DATETIME</td>
<td>REQUIRED</td>
</tr>
<tr>
<td>visitor_id</td>
<td>STRING</td>
<td>REQUIRED</td>
</tr>
<tr>
<td>url</td>
<td>STRING</td>
<td>REQUIRED</td>
</tr>
</tbody>
</table>
<h3>Google Cloudの認証情報をSecret Managerに登録する</h3>
<p>ファンクションを作成する前に、Google Cloudの認証情報をCraft Secret Managerに登録します。Craft Secret ManagerはKARTE Craft用のシークレット管理機能です。APIキーやトークンなど、コードに直接記入することが非推奨とされる情報をシークレットとして保存して、コードから安全に呼び出せるようにします。</p>
<p>BigQueryテーブルへの書き込み権限を持つサービスアカウントを作成し、JSON形式でキーを発行します。詳しい手順はGoogle Cloudのドキュメントを参照してください。</p>
<p><a href="https://cloud.google.com/iam/docs/creating-managing-service-account-keys?hl=ja">サービス アカウント キーの作成と管理  |  IAM のドキュメント  |  Google Cloud</a></p>
<p>KARTE Craftのシークレット管理画面を開き、シークレットを作成します。</p>
<ul>
<li>シークレット名: <code>GOOGLE_CLOUD_SA_KEY</code></li>
<li>データ: サービスアカウントキーの本文をそのまま貼り付けます</li>
</ul>
<p><img src="https://ik.imagekit.io/plaid/a531ab5a-7ec3-407d-acf8-72ea43a27f9f/craft_secret.png" alt="craft_secret.png"></p>
<h3>Craft Functionsを作成する</h3>
<p>ドキュメントの <a href="https://craft.developers.karte.io/craft-functions/edit-craft-funcitons">Craft Functionsを作成する</a> を参考に、管理画面からファンクションを作成します。</p>
<ul>
<li>ファンクション名と説明には任意の名前と説明文を記載してください。</li>
<li>ファンクションのコードは以下のGitHubリポジトリに配置したものを使います。
<ul>
<li><a href="https://github.com/plaidev/craft-codes/tree/main/craft-functions/write-event-to-bq">plaidev/craft-codes/craft/write-event-to-bq</a></li>
<li>write-event-to-bq.js を codes に、 modules.json を packages に貼り付けます。</li>
</ul>
</li>
<li>ここで、<code>BIG_QUERY_DATASET</code> と <code>BIG_QUERY_TABLE</code> に書き込み先のデータセット、テーブルを指定します。</li>
</ul>
<p><img src="https://ik.imagekit.io/plaid/4149fe5f-435e-4929-861d-6e833f6f7baa/craft_function_settings.png" alt="craft_function_settings.png"></p>
<h2>アクションを作成する</h2>
<p>Craft Functionsの作成が完了したので、次はアクションを設定します。詳細な手順はドキュメントをご確認いただくとして、ここでは各要素の設定値を書いていきます。ここに書いていない必須項目については任意で設定してください。</p>
<p>注意として、今回は検証用のKARTEプロジェクトでの設定を想定してます。本番利用しているプロジェクトで設定する場合はエンドユーザーへの影響を避ける設定（ターゲットの絞り込み、トリガー設定で管理者以外では発生させられないイベントを設定する）を行うようにしてください。</p>
<p>アクションの作成手順は以下をご確認ください。</p>
<p><a href="https://craft.developers.karte.io/craft-functions/triggers/server-side-action">サーバーサイドアクション</a></p>
<p>接客サービス作成の全体の流れと対象ユーザー、トリガーの設定については以下をご確認ください。</p>
<p><a href="https://support.karte.io/post/4yOwCoZkdoPZwpFRvSrkwP">接客サービス作成の流れ | ドキュメント / アクション / 作成・ 配信設定 | KARTEサポートサイト</a><br>
<a href="https://support.karte.io/post/5YTahJyFdwojIWZtYlL65A">4. 対象ユーザーの設定/仕様 | ドキュメント / アクション / 作成・ 配信設定 | KARTEサポートサイト</a><br>
<a href="https://support.karte.io/post/4Ea4RlGZsZmAxRYp4dqCDv">5. Setting and Specifications of Target Event | ドキュメント / アクション / 作成・ 配信設定 | KARTEサポートサイト</a></p>
<p>Craftアクションの設定値は以下の通りです。</p>
<ul>
<li>ファンクション名：先ほど作成したファンクションの名前</li>
<li>ユーザー情報変数
<ul>
<li>変数名 <code>visitor_id</code>
<ul>
<li>「すべての期間」「閲覧」「visitor_id」の「最新の値」</li>
</ul>
</li>
<li>変数名 <code>url</code>
<ul>
<li>「すべての期間」「閲覧」「閲覧ページのURL」の「最新の値」</li>
</ul>
</li>
<li>変数名 <code>datetime</code>
<ul>
<li>「すべての期間」「閲覧」「送信日時」の「最新の値」</li>
</ul>
</li>
</ul>
</li>
<li>data： <code>{ &quot;visitor_id&quot;: &quot;#{visitor_id}&quot;, &quot;url&quot;: &quot;#{url}&quot;, &quot;datetime&quot;: &quot;#{datetime}&quot; }</code></li>
</ul>
<p><img src="https://ik.imagekit.io/plaid/933df0ed-6125-4f1a-905e-ae7d07f514ce/craft_action_settings.png" alt="craft_action_settings.png"></p>
<p>接客サービスの対象ユーザーには「全員」を指定します。</p>
<p><img src="https://ik.imagekit.io/plaid/e5c81621-f57b-4b0f-baed-5f10e2a82653/craft_action_target_user.png" alt="craft_action_target_user.png"></p>
<p>接客サービスの対象イベントには以下を設定します。</p>
<ul>
<li>閲覧イベント
<ul>
<li>閲覧ページのURLアンカーが次に等しい</li>
<li><code>craft_sample</code></li>
</ul>
</li>
<li>配信頻度: アクセス毎</li>
</ul>
<p><img src="https://ik.imagekit.io/plaid/87191c03-0d17-4cf3-b3ba-6faddd98a277/craft_action_target_event.png" alt="craft_action_target_event.png"></p>
<p>設定後、接客の保存と公開を行えば作業完了です。</p>
<h2>動作確認</h2>
<p>以上で設定が完了しました。KARTEを設定したWebページに移動して、URLの末尾に <code>#craft_sample</code> とアンカーをつけて開いてみます。</p>
<p><img src="https://ik.imagekit.io/plaid/11b48a9c-dda1-4f1a-901f-7935b0c359bc/craft_bq_trigger_check.png" alt="craft_bq_trigger_check.png"></p>
<p>10〜30秒ほど待ってBigQueryのテーブルにデータが書き込まれていれば成功です。</p>
<p><img src="https://ik.imagekit.io/plaid/fcac7fce-8c11-4326-b328-fe97729b8145/craft_bq_result.png" alt="craft_bq_result.png"></p>
<p>以上で作業は完了です。お疲れさまでした。</p>
<h1>まとめ</h1>
<p>今回は前後編にわたってKARTEとKARTE Craftを紹介いたしました。後編のこの記事では、実際にKARTEとKARTE Craftを使って、ユーザーの状態変化を外部のストレージに保存する実装を行いました。今回はBigQueryのテーブルにユーザーデータを書き込みましたが、KARTE Craftでは汎用のプログラムが実行できます。様々なストレージサービスにデータを連携したり、外部サービスの情報と組み合わせた処理も実現できるため、さまざまな応用例が考えられます。</p>
<p>今回はエンジニアの方向けにKARTEの仕組みやKARTE Craftのサービスとしての立ち位置にフォーカスして書きましたが、当ブログではKARTEとKARTE Craftを応用したソリューションもどんどん紹介する予定です。この記事をお読みになって具体的な利用方法に興味を持っていただけたら、当ブログの他の記事も見ていただければと思います！</p>
<hr>
<p>プレイドでは、ソリューションを一緒に作っていく仲間を募集しております！プレイドのテクノロジーを駆使し、お客様に新しい価値を提供できるソリューションを一緒に作っていきましょう！</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>
<li><a href="https://blog.plaid.co.jp/n/nd8a70f686885">2協業案件のリードに、PdMとしての役割も。経験が複利で増えるカスタマーエンジニアの多面性｜PLAID</a></li>
<li><a href="https://blog.plaid.co.jp/n/n6d87538d003f">幅広く活用できるプロダクトの価値を顧客に届ける「カスタマーエンジニア」の道を選択した3人のキャリアを聞きました｜PLAID</a></li>
</ul>


KARTE CraftはKARTE内で発生する種々のイベントをきっかけに汎用のプログラムを実行します。

KARTE Craftの概要

KARTE Craftの使用例として、KARTEのイベントをトリガーに外部サービスにデータを送るサンプルを紹介します。

KARTEとKARTE Craftでユーザー情報の活用の幅が広がる話 (後編)

<p>初めまして。プレイドでエンジニアをしている矢澤と申します。私はEcosystem Depertmentという部署で弊社が提供するKARTEというサービスを拡張するための機能開発をしております。これまでサーバーサイドAPIやWebhookといった外部連携機能を開発してきましたが、このたび新たに KARTE Craft という機能をベータ版として提供開始しました。</p>
<p><a href="https://ecosystem.plaid.co.jp/product/karte-craft">KARTE Craft</a></p>
<p>KARTE Craft は KARTE に FaaS 的な機能を統合した <strong>Craft Functions</strong> を中心に構成されるもので、KARTE内で発生する様々な事象をきっかけに汎用のプログラムを実行することができます。</p>
<p><img src="https://ik.imagekit.io/plaid/08a1c2d0-2adf-41b3-89ee-d8fdb27056bb/craft-overview.png" alt="craft-overview.png"></p>
<p>この機能はKARTEの拡張性を高める一方でプログラムを自前で作成する必要があるため、普段KARTEをご利用いただいているマーケティング・カスタマーサクセス領域の方にはハードルが高いかもしれません。そうなるとエンジニアの力を借りることになるかと思いますが、エンジニアの方からすれば「KARTEとは何者？何が美味しいの？」という状態かもしれません。</p>
<p>そこで、今回は主にサービスを開発されているエンジニアの方向けに、</p>
<ul>
<li>KARTEとは何者？</li>
<li>KARTEの技術的な特徴</li>
<li>KARTE Craftはどのような立ち位置のサービスなのか</li>
</ul>
<p>というテーマでKARTEとKARTE Craftをご紹介しようと思います。エンジニア的な視点でKARTEってなんだか面白そうだぞ、という感覚を持っていただければ幸いです。</p>
<p>この記事は前後編の前編です。後編では実際にKARTE Craftを使ってKARTEで収集したユーザー情報をBigQueryに書き込む仕組みを作ります。</p>
<h1>KARTEとは？</h1>
<p>そもそも「KARTE」とは何者でしょうか。KARTEは「CX（顧客体験）プラットフォーム」を名乗っています。</p>
<p><a href="https://karte.io/">CX（顧客体験）プラットフォーム KARTE（カルテ）</a></p>
<p>これを少し噛み砕くと、</p>
<ul>
<li>Webサイト・サービスを訪問する顧客を深く知るための機能 = <strong>顧客を「知る」機能</strong></li>
<li>顧客に合わせたコミュニケーションを行う機能 = <strong>顧客に「合わせる」機能</strong></li>
</ul>
<p>の両面を持つ、顧客体験の向上に役立つサービス群という意味になります。</p>
<p>「知る」機能では、Webサービスを訪れるユーザーの行動の一つひとつをイベントとして収集し、ユーザーの行動を時系列や統計データとして分析できるようにします。この機能によって、サービス内の一人ひとりのユーザーの行動をリアルタイムに分析することができます。</p>
<p>「合わせる」機能はWebポップアップ接客（バナー、アンケートなど）、チャット、メール配信およびプッシュ通知など、様々な種類があります。「知る」機能で取得したユーザーの行動変化をトリガーに、顧客にとって最適なコミュニケーションが取れるようになっています。</p>
<p><img src="https://ik.imagekit.io/plaid/7dcf3909-6511-43ae-b22f-02a00d58a782/popup_example.png" alt="popup_example.png"></p>
<h1>KARTEがユーザーを「知る」仕組み</h1>
<p>「知る」機能は「合わせる」機能の支えになる機能であることから、KARTEにおける重要な機能と考えることができます。「知る」機能の中でも特にコアになるのがユーザー情報の解析エンジンです。ここでは、KARTEがどのようにユーザーの情報を取得して解析しているのかを見ていきましょう。</p>
<p>KARTEがユーザーの情報を取得、解析するまでの流れを図にしてみました。図を見ながら流れを追ってみます。</p>
<p><img src="https://ik.imagekit.io/plaid/a7ab86d6-af19-4beb-86c3-9005933cbe3d/karte_customer_data_process.png" alt="karte_customer_data_process.png"></p>
<ul>
<li>（準備）KARTEを利用するWebサイトに script タグを挿入します。</li>
<li>scriptタグに含まれるプログラムによって、Webサイトに訪問したユーザーの情報がKARTEに送信されます。
<ul>
<li>ここで送信する情報の一つひとつを「イベント」と呼びます。</li>
<li>送信するイベントのスキーマは自由に設定できます。</li>
</ul>
</li>
<li>KARTEはイベントを受け取り、そのイベントを解析してユーザー単位の統計値を更新します。これを「ユーザー情報」と呼びます。</li>
<li>ユーザー情報の変化や特定のイベントをトリガーにWebポップアップやプッシュ通知などのコミュニケーション機能（「アクション」と呼びます）が作動します。</li>
</ul>
<p><img src="https://ik.imagekit.io/plaid/3c12b929-7d77-49fb-8f2a-343bb443fb81/karte_event_customer_data.png" alt="karte_event_customer_data.png"></p>
<p>つまり、KARTEはWebサイトに埋め込んだタグ経由でユーザーの「イベント」を取得し、解析エンジンでリアルタイムに解析し、「ユーザー情報」として使えるようにします。そして、こうして得られた「ユーザー情報」や「イベント」をトリガーに「アクション」を発火します。</p>
<p>KARTEの強みはこのリアルタイム解析エンジンです。スクラッチで開発しており、スキーマレスなイベントを高速に処理できます。強力な解析エンジンがあることで、Webサービスに訪れるユーザーの統計情報をリアルタイムに解析してコミュニケーションに繋げることができるのです。</p>
<h1>KARTE Craft</h1>
<p>KARTE Craft は KARTEにFaaS機能を統合した <strong>Craft Functions</strong> を中心に構成されます。Node.jsのコードをデプロイすることで、KARTEで発生する様々な事象をトリガーにプログラムを動かせます。</p>
<p>KARTE Craftは以下の特徴があります。</p>
<ul>
<li>ユーザーが作成した任意のNode.js 18プログラムを実行することができる。</li>
<li>KARTEの解析エンジンによって、リアルタイムに変化するユーザー情報をトリガーにできる。また、イベントもスキーマレスなので、自由度の高いトリガー設計が可能。</li>
<li>イベント以外にもチャットメッセージの送受信やデータ連携機能のジョブ開始終了など、KARTEのコミュニケーション機能にまつわる様々な事象もトリガーに使える。</li>
</ul>
<p>KARTE Craftを使えば、例えば次のようなことが実現できます。</p>
<ul>
<li>KARTEで解析したユーザー情報を自身のアプリケーションのダッシュボードに適用する</li>
<li>ユーザー情報の変化に基づいて外部サービスから情報を取得し、自身のサービスに適用する</li>
</ul>
<p>これらの例から分かる通り、KARTE CraftはKARTEのリアルタイムなイベント解析結果を外部に連携したり、外部のデータを使ったより発展したコミュニケーションを実現します。</p>
<h2>デベロッパーから見た KARTE Craft の立ち位置</h2>
<p>エンジニアの方からすると、AWS LambdaやGoogle CloudのCloud Functions、Azure Functionsなど主要なクラウドプロバイダーがFaaSを提供している中で、プレイドがFaaSを機能に組み込む理由は無いように見えるかと思います。それでもKARTE Craftを開発したのは、KARTE Craftがあることで、KARTEに閉じたユーザー情報解析エンジンをユーザーアプリケーションのバックエンドとして提供できると考えたためです。</p>
<p>KARTEはユーザー情報の解析からフロントエンドへのコンテンツ配信まで一貫して提供しているので、ある種完結したプラットフォームになっています。このプラットフォーム内で起きる事象をそのまま外部に露出することでもアプリケーションでの利用は可能です。しかし、KARTEとシームレスにつながるプログラム実行基盤を備えることで、KARTEの解析エンジンのパワーがより簡単に扱えるようになります。</p>
<p>例えば、WebhookではKARTEのイベントをトリガーに特定のURLにメッセージを送信できますが、送信したメッセージを処理する仕組み (AWS LambdaやZapier Appなど) は自前で準備する必要があります。ここをKARTE Craftとして吸収することで、自前でのリソース作成の煩雑さを減らします。</p>
<p>この考え方はFirebaseとCloud Functionの関係に似ています。Firebaseはモバイル/Webアプリケーションの提供に必要なバックエンド機能を提供するサービスです。Firebaseはプログラム実行環境としてCloud Functionsを統合しており、Firebaseの様々なトリガーとCloud Functionsがシームレスにつながっています。KARTEとKARTE Craftも同じ関係で、KARTE内で発生するトリガーとプログラム実行基盤をシームレスにつなぐことで、ユーザー情報解析エンジンを別のアプリケーションから簡単に利用できるようにします。</p>
<h2>マーケター・カスタマーサクセスから見たKARTE Craftの立ち位置</h2>
<p>KARTE Craftはイベント解析エンジンをバックエンドとして提供することを目的としていますが、副次的な効果として、KARTEユーザーが抱える「ちょっとしたことをやるためのコンピューティングリソース確保のハードルが高い」という問題も解決できます。</p>
<p>これまではシンプルな連携機能のみを提供していたため、カスタマイズされた処理を実装するためにはクラウドサービスを使ってコンピューティングリソースを立ち上げる必要がありました。そのため、社内IT部門やエンジニア部門といった社内の関係者との同意を得る必要性が生じ、スピード感のある施策実現の課題となっていました。</p>
<p>プログラミングの知識が必要となるため関係者や弊社カスタマーエンジニアの力を借りる必要はありますが、KARTEにプログラム実行環境を備えることでサーバーインフラを準備するための手間は無くなります。結果、込み入った処理を比較的簡単に実装できるようになります。</p>
<h1>まとめ</h1>
<p>今回はエンジニアの方向けにKARTEのコア技術である解析エンジンとKARTE Craftについて紹介しました。スキーマレスかつリアルタイムなユーザー情報解析機能にFaaS的な機能が統合されることで、KARTEをユーザーの状態変化を捉えるバックエンドとして利用できるようになることを期待します。</p>
<p>この記事は前後編の前編です。後編では、実際にKARTEのイベントをトリガーにFunctionを動作する手順を紹介いたします。<br>
<a href="https://solution.plaid.co.jp/karte-craft-improve-customer-data-utilization-2">KARTEとKARTE Craftでユーザー情報の活用の幅が広がる話 (後編)</a></p>
<hr>
<p>プレイドでは、ソリューションを一緒に作っていく仲間を募集しております！プレイドのテクノロジーを駆使し、お客様に新しい価値を提供できるソリューションを一緒に作っていきましょう！</p>
<ul>
<li><a href="https://recruit.plaid.co.jp/requisitions/ecosystem-engineer">Ecosystem Engineer | 募集ポジション | 株式会社プレイド</a></li>
<li><a href="https://recruit.plaid.co.jp/requisitions/general-customer-engineer">General Customer Engineer | 募集ポジション | 株式会社プレイド</a></li>
<li><a href="https://blog.plaid.co.jp/n/nd8a70f686885">2協業案件のリードに、PdMとしての役割も。経験が複利で増えるカスタマーエンジニアの多面性｜PLAID</a></li>
<li><a href="https://blog.plaid.co.jp/n/n6d87538d003f">幅広く活用できるプロダクトの価値を顧客に届ける「カスタマーエンジニア」の道を選択した3人のキャリアを聞きました｜PLAID</a></li>
</ul>


KARTEのユーザーデータ解析の仕組みとKARTE Craftの概要を紹介します。

KARTEとKARTE Craftでユーザー情報の活用の幅が広がる話 (前編)

<h2>はじめに</h2>
<p>前回の記事に続けての投稿になります！プレイドでCustomer Engineerをしております渡辺（<a href="https://twitter.com/ikmwtnb">@ikmwtnb</a>）と申します！</p>
<p>突然ですが、プッシュ通知やメールなどのパーソナライズ、どのように実施されていますか？</p>
<p>他社が提供する/自社で管理するAPIのレスポンスの内容を含めてパーソナライズしたメッセージを送信したいと思ったことはないでしょうか？実はこういった要望はプレイドの社内でもお客様とのコミュニケーションに使いたいという声や、お客様からもよく聞かれる声だったりします。</p>
<p>今回は、<a href="https://ecosystem.plaid.co.jp/product/karte-craft">KARTE Craft</a>と呼ばれる新機能を用いて天気情報APIとの連携を実装し、ユーザーがいる場所の天気予報の情報を用いて、プッシュ通知をパーソナライズする方法についてご紹介します。</p>
<h2>KARTE Craftとは？</h2>
<p>最初に、KARTE Craft と呼ばれるKARTEの機能についてご紹介します。KARTE Craft とは、KARTE内で発生する状態の変化をトリガーとして、汎用のプログラムを実行できる機能です。端的に表現すると、KARTE内で提供するFaaS（Function as a Service）です。</p>
<p><img src="https://ik.imagekit.io/plaid/1fa14615-5569-4d5d-adaa-06dae7b965f8/craft-overview.png" alt="craft-overview.png"></p>
<p>KARTE Craftでは現在、上記の図に記載したKARTE内外で発生するさまざまな出来事をトリガーに、Craft Functions に記載したNode.jsの任意のコードを実行することが可能になっています。</p>
<p>今回のようなAPIを利用したキャンペーンを実装したい、など高度な施策の要件が上がった際に、エンジニアが自由にコードを書いてKARTEで実行できるKARTE Craft は、今回のケースにまさにぴったりな機能となっています。</p>
<h2>実装イメージ</h2>
<p>KARTE Craft を用いての天気情報APIと連携したプッシュ通知のパーソナライズは下記のような構成で実装します。<br>
（こちらの実装についてはあくまで一例となりますので、お客様ごとに実装されたい施策によって実装方針は異なります。実装に迷ったら、お気軽にお問い合わせください。）</p>
<p><img src="https://ik.imagekit.io/plaid/56ce1060-abe7-49c3-b47d-4c1db4115647/%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-04-0413.41.47.png" alt="スクリーンショット2023-04-0413.41.47.png"></p>
<p>処理の流れを説明するとは下記のようになります。</p>
<ol>
<li>位置情報を含んだイベントがユーザーからKARTEに送信される</li>
<li>1のイベントをトリガーにCraft接客がトリガーされる</li>
<li>Craft Functions が起動する</li>
<li>天気情報APIに位置情報を送信する</li>
<li>天気情報APIから返却される天気予報を受け取る</li>
<li>Craft Functions がサーバーサイドAPI経由で、イベントとして天気予報の情報をユーザーデータに書き込む</li>
<li>プッシュ通知の接客（イベント応答接客）がトリガーされる</li>
<li>プッシュ通知が配信される（接客が表示される）</li>
</ol>
<p>上記の処理の流れについて、実装の中でも特徴的な部分を中心に説明します。</p>
<h2>Craftの設定</h2>
<p>本実装で大きな役割を果たすCraftですが、今回は下記のような緯度・経度を含む位置情報を含んだイベントをトリガーに起動されます。例えば、ユーザーの位置情報をアプリで取得し、KARTE for AppのSDK経由でKARTEに下記のようなイベント（<code>get_location</code>イベント）で送信することを想定しています。</p>
<pre><code class="language-json">&quot;values&quot;: {
    &quot;get_location&quot;: {
      &quot;latitude&quot;: 35.6696559,
      &quot;longtitude&quot;: 139.7639876,
    }
  }
</code></pre>
<p>上記のような情報を受け取って、Craft Functions は処理を開始します。受け取るためには、Craft接客が必要になりますので、Craft接客の配信トリガーには上記の<code>get_location</code>イベントを設定します。</p>
<p>Craft Functions として設定するNode.jsのサンプルコードを公開しています。</p>
<p><a href="https://github.com/plaidev/craft-codes/tree/main/craft-functions/fetch-open-weather">craft-codes/craft-functions/fetch-open-weather at main · plaidev/craft-codes</a></p>
<p>ここでは<a href="https://openweathermap.org/">OpenWeatherMap</a>が提供している<a href="https://openweathermap.org/forecast5">5 day weather forecast</a>（<code>api.openweathermap.org/data/2.5/forecast?</code>）を利用して、72時間後の天気を取得してその内容をKARTEに<code>weather_information</code>イベントのデータとして書き込みます。</p>
<p>このCraft内では、<br>
4. 天気情報APIに位置情報を送信する<br>
5. 天気情報APIから返却される天気予報を受け取る<br>
6. Craft Functions がサーバーサイドAPI経由で、イベントとして天気予報の情報をユーザーデータに書き込む<br>
という処理が実行されています。<br>
※KARTEの<a href="https://developers.karte.io/docs/create-api-v2-apps">サーバーサイドAPIのTokenの発行方法</a>やOpenWeatherのAPI  Keyの発行方法は当記事では省略致します。</p>
<pre><code class="language-json">&quot;values&quot;: {
    &quot;weather_information&quot;: {
      &quot;latitude&quot;: &quot;rainy&quot;,
    }
  }
</code></pre>
<p>APIから取得してきた天気情報を上記のようなイベントデータ（<code>weather_information</code>）として書き込むことで、このあと設定するプッシュ通知のトリガーとコンテンツのパーソナライズに利用します。</p>
<h2>プッシュ通知の配信</h2>
<p>最後にプッシュ通知の設定をします。プッシュ通知の接客の設定は下記のように設定します。</p>
<ul>
<li>ターゲット配信機能を利用
<ul>
<li>イベント応答を選択し、<code>weather_information</code>を配信トリガーに設定</li>
<li>アクションの中身で、ユーザー情報変数で<code>weather_information.weather</code>をプッシュ通知のbodyに埋め込む。</li>
</ul>
</li>
</ul>
<p>配信されるプッシュ通知のイメージとしては下記のようなものとなります。<br>
<img src="https://ik.imagekit.io/plaid/cafd57d2-7cf3-4869-b398-1a9b87a6e8cb/%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-04-0418.43.04.png" alt="image"><br>
赤枠の部分が、API経由で取得した天気予報状況になり、ユーザーがいる地点の3日後の天気の情報がプッシュ通知のBodyに表示されています。</p>
<h2>最後に</h2>
<p>この実装を応用して、例えば下記のような施策を実装することが可能となります。</p>
<ul>
<li>夕方の天気が雨のユーザーにだけ、傘などの防雨グッズをリコメンド</li>
<li>週末の天気予報と関連した商品のリコメンド（晴れならピクニック用品など）</li>
<li>季節の移り変わりで急な天気の変化があるユーザーにだけ、季節性の強い商品をリコメンド（防寒具、日焼け止めなど）</li>
</ul>
<p>天気情報のAPIに限らず、APIを用いた施策を実施したい際にはぜひKARTE Craft の利用を検討してみてください！</p>
<p>また、プレイドでは、ソリューションを一緒に作っていく仲間を募集しております！プレイドのテクノロジーを駆使し、お客様に新しい価値を提供できるソリューションを一緒に作っていきましょう！</p>
<ul>
<li><a href="https://recruit.plaid.co.jp/requisitions/general-customer-engineer">Customer Engineerの募集要項</a></li>
<li><a href="https://blog.plaid.co.jp/n/n6d87538d003f">幅広く活用できるプロダクトの価値を顧客に届ける「カスタマーエンジニア」の道を選択した3人のキャリアを聞きました</a></li>
<li><a href="https://blog.plaid.co.jp/n/nd8a70f686885">2協業案件のリードに、PdMとしての役割も。経験が複利で増えるカスタマーエンジニアの多面性</a></li>
</ul>


KARTE Craftと呼ばれる新機能を用いて天気情報APIとの連携を実装し、ユーザーがいる場所の天気予報の情報を用いて、プッシュ通知をパーソナライズする方法についてご紹介します。

天気情報を提供するAPIを用いてプッシュ通知の内容をパーソナライズする

<h2>はじめに</h2>
<p>はじめまして！プレイドでCustomer Engineerをしております渡辺（<a href="https://twitter.com/ikmwtnb">@ikmwtnb</a>）と申します！</p>
<p>2023年に入ってLLM（大規模言語モデル）が本当に盛り上がっていますよね。その中でも、OpenAIが開発したChatGPTは、その高い応答性と自然な文章生成能力により、多くの人々の注目を集めています。（この記事の作成自体も、ChatGPT（GPT4）に助けてもらいながら書いております。）</p>
<p>今回は、ウェブチャットのサービスである<a href="https://talk.karte.io/">KARTE Talk</a>とChatGPTとのAPI連携を実装し、KARTE Talk上（Web）でChatGPTと会話できるようにする方法についてご紹介します。ここでは、<a href="https://ecosystem.plaid.co.jp/product/karte-craft">KARTE Craft</a> と呼ばれるKARTEの新しい機能を用いて、連携を実装します！</p>
<h1>注意事項</h1>
<p><strong>ChatGPT等最新の技術はビジネスでの活用におけるリスク等がまだ十分に議論・認識されていないため、下記のようなことに注意しながら</strong>読み進めてください。</p>
<ul>
<li>記事中では、エンドユーザーの入力した情報をChatGPTに送信していますが、プレイドではお客様からお預かりしたデータをChatGPT等の外部サービスに送信は実施していません。記事で紹介されているスクリーンショット等は開発環境のものであり、入力するデータを限定して実施しています。</li>
<li>本記事は、KARTEの機能を用いて実現できることを検証する目的で公開しており、読者に対してChatGPTの利用を推奨するものではありません。読者がChatGPT等をビジネスで用いることによって被った損害等に対して責任を負うことはできないため、ご留意ください。</li>
<li>当記事を参考にビジネスでChatGPT等を利用される際は、情報の取り扱いにご注意ください。</li>
</ul>
<h1>実現できること</h1>
<p><img src="https://ik.imagekit.io/plaid/9dd94443-f207-472b-a17e-49ad9cec0532/%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-03-3114.21.45.png" alt="image"><br>
KARTE Talk上でChatGPTと会話をすることが可能になります。上記の画像では、「株式会社プレイドという会社が提供しているKARTEというサービスについて教えてください。」という質問に対して、ChatGPTが回答をしてくれています。（ChatGPTの回答の内容は正確ではないですが。。）<br>
今回は非常にシンプルな実装にしているため、OpenAIが提供しているWEBベースのGUIの画面で実施できるような文脈を読み取って回答するような機能は実現されていません。（もちろん、実装を工夫することで、そうした実装も可能となります。）</p>
<h1>ChatGPTとKARTE Talkの連携方法</h1>
<p>ChatGPTとKARTE Talkの連携は下記のような構成で実現しています。<br>
<img src="https://ik.imagekit.io/plaid/b8a60364-67a1-4825-9762-f1bff36ee7a5/%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-04-0715.44.12.png" alt="image"></p>
<p>システムの各登場人物を整理すると下記のようになります。</p>
<ul>
<li><strong>ウィジェット</strong>：エンドユーザーがメッセージを送信する画面</li>
<li><strong>KARTE Talk</strong>：KARTE Talkのサーバー</li>
<li><strong>Talk Hook</strong>：KARTE Talk上のメッセージを検知し、他のシステムの処理をトリガーできるhook</li>
<li><strong>KARTE Craft</strong>：KARTE上で任意のコードを実行できるいわゆるFaaS機能</li>
<li><strong>ChatGPT</strong>：チャットボットサービス</li>
</ul>
<h2>API連携処理の実装に必要な情報を取得する</h2>
<p>ChatGPTとのAPI連携の処理の実装には、いくつかのトークンなどの認証情報を含む情報が必要になります。下記を参考に、必要な情報を取得してください。</p>
<ul>
<li>ChatGPTのAPIキー（<code>CHAT_GPT_API_KEY</code>）
<ul>
<li>OpenAIの公式ウェブサイトにアクセスし、アカウントを作成（もしくはログイン）してAPIキーを取得してください。</li>
</ul>
</li>
<li>KARTEのAPIのアクセストークン
<ul>
<li><a href="https://developers.karte.io/docs/create-api-v2-apps">こちら</a>を参考に、アプリを作成し、アクセストークンを取得してください。</li>
</ul>
</li>
<li>KARTE Talkのチャットの送信者として指定するオペレータ（<code>SENDER_ID</code>）
<ul>
<li>KARTE Talkの[Talk設定] &gt; [オペレーター設定]から任意のオペレーターを選択し、アサインID(<code>オペレーターID</code>)の値を取得してください。</li>
</ul>
</li>
</ul>
<h2>ChatGPTとの連携の設定</h2>
<p>本連携の実装には、下記のような設定が必要になります。</p>
<ul>
<li>KARTE Craftの設定</li>
<li>Talk Hookの設定</li>
<li>接客の公開</li>
</ul>
<p>馴染みもない機能も多いと思いますので、それぞれの設定についてステップごとに説明致します。</p>
<h2>KARTE Craftの設定</h2>
<p>KARTE Craft は、KARTE内のイベント/Hook等をトリガーに任意のコードを実行できるFaaS（Function as a Service）のような機能です。<br>
ここでは、この後に設定するTalk Hookから情報を受け取り、その情報を元にChatGPTのAPIにリクエストをし、KARTE TalkにAPI経由でChatGPTの回答を返す処理を実装しています。</p>
<p>[Craft]&gt;[ファンクション]&gt;[作成]から新規のCraft Functions の作成画面に遷移します。次のGithub上のコードを元に、前項「API連携処理の実装に必要な情報を取得する」で取得した情報を元に定数の値を設定しながら、craftのコードエディタ上でコードを設定してください。</p>
<p><a href="https://github.com/plaidev/craft-codes/tree/main/craft-functions/reply-chat-by-gpt">craft-codes/craft-functions/reply-chat-by-gpt at main · plaidev/craft-codes</a></p>
<p>コードを設定した後、任意の名前を設定し、[有効化] の<code>Functionを有効にする</code>にチェックを入れて、Funcitonを有効化します。</p>
<h2>Talk Hookの設定</h2>
<ul>
<li>[ストア] &gt; [API v2設定] &gt; [作成]ボタンから新規のアプリを作成します。アプリタイプは<code>token</code>、Scopeとして<code>talk.message.get</code>を設定し、任意の名前をつけ保存します。</li>
<li>作成されたアプリの詳細画面に遷移し、[hook設定]から[編集]ボタンを押下します。トリガー設定に<code>KARTE Talk: ユーザーからのメッセージ送信時</code>を選択します。[チャネル設定]&gt;[Craft]でhook statusを'有効にする'とし、[ファンクション名]を作成したCraftに設定します。</li>
</ul>
<h2>チャットウィジェットの接客を公開する</h2>
<p>KARTEのチャットウィジェットの接客を公開することで、ChatGPTと会話できるようになりました。<br>
<img src="https://ik.imagekit.io/plaid/9dd94443-f207-472b-a17e-49ad9cec0532/%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-03-3114.21.45.png" alt="image"></p>
<h1>まとめと今後の展望</h1>
<p>今回は、KARTE Talk上でChatGPTと会話できるようにするという機能を、非常にシンプルなコードで実装しました。<br>
KARTEでは、今回用いた新機能であるKARTE Craft を用いることで、カスタマーデータを起点とした様々な処理を実装することができるようになっています。</p>
<p>ChatGPTを用いたより発展的なユースケースや、KARTE Craft を用いた高度な処理についても当ソリューションブログでどんどん公開していきますので、お見逃しなく！</p>
<p>また、プレイドでは、ソリューションを一緒に作っていく仲間を募集しております！プレイドのテクノロジーを駆使し、お客様に新しい価値を提供できるソリューションを一緒に作っていきましょう！</p>
<ul>
<li><a href="https://recruit.plaid.co.jp/requisitions/general-customer-engineer">Customer Engineerの募集要項</a></li>
<li><a href="https://blog.plaid.co.jp/n/n6d87538d003f">幅広く活用できるプロダクトの価値を顧客に届ける「カスタマーエンジニア」の道を選択した3人のキャリアを聞きました</a></li>
<li><a href="https://blog.plaid.co.jp/n/nd8a70f686885">2協業案件のリードに、PdMとしての役割も。経験が複利で増えるカスタマーエンジニアの多面性</a></li>
</ul>


[やってみた]KARTE TalkとKARTE Craftを使ってChatGPTとチャットウィジェット上で会話をする

<h1>はじめに</h1>
<p>プレイドでCustomer Engineerをしております渡辺（<a href="https://twitter.com/ikmwtnb">@ikmwtnb</a>）と申します！</p>
<p>前回の「<a href="https://solution.plaid.co.jp/talk-chat-gpt-api">[やってみた]KARTE TalkとKARTE Craftを使ってChatGPTとチャットウィジェット上で会話をする</a>」に続きまして、ChatGPTとKARTE Talkを組み合わせたユースケースについて紹介致します。前回の記事では、エンドユーザーがチャットウィジェット上でChatGPTと会話するというKARTE TalkとChatGPTを本当にシンプルに組み合わせたものでしたが、今回はより実践に近いユースケースとなります。</p>
<h1>注意事項</h1>
<p><strong>ChatGPT等最新の技術はビジネスでの活用におけるリスク等がまだ十分に議論・認識されていないため、下記のようなことに注意しながら</strong>読み進めてください。</p>
<ul>
<li>記事中では、エンドユーザーの入力した情報をChatGPTに送信していますが、プレイドではお客様からお預かりしたデータをChatGPT等の外部サービスに送信は実施していません。記事で紹介されているスクリーンショット等は開発環境のものであり、入力するデータを限定して実施しています。</li>
<li>本記事は、KARTEの機能を用いて実現できることを検証する目的で公開しており、読者に対してChatGPTの利用を推奨するものではありません。読者がChatGPT等をビジネスで用いることによって被った損害等に対して責任を負うことはできないため、ご留意ください。</li>
<li>当記事を参考にビジネスでChatGPT等を利用される際は、情報の取り扱いにご注意ください。</li>
</ul>
<h1>実現できることと利用シーン</h1>
<p>今回は、「KARTE Talkの画面上でChatGPTに質問をして参考回答をもらう」ということを実現します。実現する内容としては下記のような画面のイメージとなります。</p>
<p><img src="https://ik.imagekit.io/plaid/a0e0c420-6165-4d17-94c2-ed90531ce026/%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-04-0715.20.54.png" alt="スクリーンショット2023-04-0715.20.54.png"></p>
<p>想定している利用シーンは次のようなものです。</p>
<p>エンドユーザーは「株式会社プレイドのKARTEというプロダクトについて教えてほしいです。」という問い合わせをチャット経由で実施します。オペレーターは回答に悩んだので、「教えてGPT：株式会社プレイドのKARTEについて教えてください」とノートに記述します。ノートに記述されたことをトリガーに、ChatGPTへの問い合わせが行われ、ChatGPTの回答がノートに追記されます。</p>
<h1>実現方針</h1>
<p>この機能は下記のような仕組みで実現されています。<br>
<img src="https://ik.imagekit.io/plaid/9c90eacd-cf1e-4c81-9dfa-e26a14c7811b/craft-chatgpt-talk-note.png" alt="craft-chatgpt-talk-note.png"></p>
<p>仕組み・設定方法は<a href="https://solution.plaid.co.jp/talk-chat-gpt-api">前回の記事で紹介したもの</a>とほとんど同様ですので、詳細の説明は省きます。前回の仕組みとの主要な差分としては下記のようなものになります。</p>
<ul>
<li>Craft Functions の中で利用しているKARTEのAPIについて、<code>v2/talk/message/sendFromOperator </code>の替わりに<code>2beta/talk/note/send</code>を利用</li>
<li>Craft Functions のトリガーに<code>KARTE Talk: ノート送信時</code>を利用</li>
</ul>
<p>そして、Craft Functions のコードは次のURLで公開されています。</p>
<p><a href="https://github.com/plaidev/craft-codes/tree/main/craft-functions/ask-chatgpt-through-note">craft-codes/craft-functions/ask-chatgpt-through-note at main · plaidev/craft-codes</a></p>
<p>特徴的な点としては、すべてのノートへの書き込みがChatGPTに問い合わせされてしまうとノイズになってしまうため、「教えてGPT：」と記載されたノートのみに反応して、ChatGPTに問い合わせるようになっております。</p>
<h1>まとめと今後の展望</h1>
<p>この仕組みをベースとして、例えば自社で開発した独自のモデル等を用いて、学習させた社内データをチャットの参考回答としてノートに表示させると言ったことも可能になります。今回はChatGPTのAPIを用いて実現しておりますが、それが他のシステムのAPIであっても問題ありません。</p>
<p>このような高度なAIを組み込んだチャットのオペレーションを組むことにより、<strong>オペレーターの回答の品質向上や気軽に参考回答を聞くことができる心理的安全性の高まり</strong>が期待されます。実際にプレイド社内でも、利用いただいているお客様への問い合わせに対してより高品質かつ早く回答できるように、新しい技術をどのように活用していけるのか、ディスカッションが熱くなされています。</p>
<p>プレイドでは、子会社であるライトタッチ社が<a href="https://rightsupport.karte.io/"><strong>KARTE RightSupport</strong></a>というカスタマーサポート領域に特化したプロダクトも提供しております。カスタマーサポート領域におけるAIの活用についてご相談がありましたら、ぜひお気軽にご相談ください！</p>
<p>また、プレイドでは、ソリューションを一緒に作っていく仲間を募集しております！プレイドのテクノロジーを駆使し、お客様に新しい価値を提供できるソリューションを一緒に作っていきましょう！</p>
<ul>
<li><a href="https://recruit.plaid.co.jp/requisitions/general-customer-engineer">Customer Engineerの募集要項</a></li>
<li><a href="https://blog.plaid.co.jp/n/n6d87538d003f">幅広く活用できるプロダクトの価値を顧客に届ける「カスタマーエンジニア」の道を選択した3人のキャリアを聞きました</a></li>
<li><a href="https://blog.plaid.co.jp/n/nd8a70f686885">2協業案件のリードに、PdMとしての役割も。経験が複利で増えるカスタマーエンジニアの多面性</a></li>
</ul>


[やってみた]KARTE Talkの画面上でChatGPTに質問をして参考回答をもらう

<h2>はじめに</h2>
<p>こんにちは！今日は、DatahubとAmazonS3（以下、S3）の連携について、ステップ・バイ・ステップで説明していきたいと思います。S3連携はKARTE Datahubの機能の一部です。比較的簡単に設定できますが、手順自体は少し多いため、この記事を参考にしていただくと、スムーズに設定ができるようになります。ぜひ皆様の環境でも実施して見てください。</p>
<h2>準備</h2>
<ul>
<li>KARTE Datahubの契約があること</li>
<li>S3の準備
<ul>
<li>今回は、KARTEで払い出したS3を想定します</li>
</ul>
</li>
</ul>
<h3>KARTEで払い出したAmazon S3について</h3>
<p>KARTEでは、お客様のご要望に応じてS3バケットを払い出すことが可能です。払い出しをご希望の方は、当社の担当者にご連絡ください。</p>
<p>KARTEで払い出したS3には制限がありますので、ご要望に沿わない場合があります。その点、ご了承ください。</p>
<p>例えば、以下のような場合には、ご要望に沿えないことがあります。その場合は、自前で作成することをおすすめします。</p>
<ul>
<li>リージョンを変更したい場合
<ul>
<li>払い出したS3のリージョンは、<code>ap-northeast-1</code>に固定されます。</li>
<li>変更することはできません。</li>
</ul>
</li>
<li>ファイルの世代管理を行いたい場合
<ul>
<li>ファイルの世代管理は設定できません。</li>
</ul>
</li>
<li>Amazon EventBridgeを使ってS3と連携させたい場合
<ul>
<li>払い出したS3で利用することはできません。</li>
</ul>
</li>
<li>S3のバケットポリシーをカスタマイズしたい場合
<ul>
<li>カスタマイズすることはできません。</li>
</ul>
</li>
</ul>
<p>などなど</p>
<p>自前で準備したS3でも、「KARTEでは払い出したS3の設定確認」以外はだいたい同じですので、参考にしてみてください。</p>
<h2>KARTEで払い出したS3の設定確認</h2>
<p>KARTEで払い出したS3の設定を確認します。上記の通り、プラグインを開放する必要があるため、当社の担当者にご連絡ください。</p>
<h3>設定確認方法</h3>
<p>「すべてのプロダクト」→「ストア」→「アプリ設定」より、「Amazon S3」をクリックして、設定を確認します。</p>
<p><img src="https://ik.imagekit.io/plaid/3ceeffb0-8519-48ad-b0b6-9a0d0584041c/%E3%83%95%E3%82%9A%E3%83%A9%E3%82%AF%E3%82%99%E3%82%A4%E3%83%B3%E4%B8%80%E8%A6%A7_-_%E7%A4%BE%E5%86%85%E6%A4%9C%E8%A8%BC%E7%94%A8_yusuke_yajima_-_KARTE.png" alt="プラグイン一覧_-社内検証用_yusuke_yajima-_KARTE.png"></p>
<p>以下の画面は、後で利用するために別のタブで開いておくと便利です。</p>
<p><img src="https://ik.imagekit.io/plaid/2dbc5212-e0f0-4cf7-acb0-7cdd56fc45df/%E3%83%95%E3%82%9A%E3%83%A9%E3%82%AF%E3%82%99%E3%82%A4%E3%83%B3%E8%A9%B3%E7%B4%B0_-_%E7%A4%BE%E5%86%85%E6%A4%9C%E8%A8%BC%E7%94%A8_yusuke_yajima_-_KARTE.png" alt="プラグイン詳細_-社内検証用_yusuke_yajima-_KARTE.png"></p>
<h3>ファイルをアップロード</h3>
<p>aws cliを利用してアップロードします。インストールや設定等は<a href="https://docs.aws.amazon.com/ja_jp/cli/latest/userguide/getting-started-install.html">こちら</a>をご確認ください。</p>
<p>今回利用したコマンドは以下です。<code>s3_sample_data.csv</code>を使用します。</p>
<pre><code class="language-bash">aws s3 mv ./s3_sample_data.csv s3://karte-data-bucket/[アクセス可能なs3フォルダの値]/s3-dir/s3_sample_data.csv
</code></pre>
<p>今回は<code>アクセス可能なs3フォルダ</code>  配下に<code>s3-dir</code> の中にcsvファイルを格納します。</p>
<p>今回はaws cliを利用しましたが、CyberduckやWinSCPなどを利用しても問題がありません。</p>
<h2>データセット作成</h2>
<p>今回利用するデータセット作成します。</p>
<p><img src="https://ik.imagekit.io/plaid/2ca78008-4ecf-41b1-bb6b-a12317900ae5/%E3%83%86%E3%82%99%E3%83%BC%E3%82%BF%E3%82%BB%E3%83%83%E3%83%88_-_%E7%A4%BE%E5%86%85%E6%A4%9C%E8%A8%BC%E7%94%A8_yusuke_yajima_-_KARTE(1).png" alt="データセット_-社内検証用_yusuke_yajima-_KARTE(1).png"></p>
<p><img src="https://ik.imagekit.io/plaid/f57a8fbc-5b0d-423a-8c95-81e6e14812cd/%E3%83%86%E3%82%99%E3%83%BC%E3%82%BF%E3%82%BB%E3%83%83%E3%83%88_-_%E7%A4%BE%E5%86%85%E6%A4%9C%E8%A8%BC%E7%94%A8_yusuke_yajima_-_KARTE(2).png" alt="データセット_-社内検証用_yusuke_yajima-_KARTE(2).png"></p>
<h2>テーブル作成</h2>
<p>作成したテーブルに、S3からのデータをジョブフローを使ってインポートします。</p>
<p>「テーブルを作成」をクリックし、テーブルを作成します。</p>
<p><img src="https://ik.imagekit.io/plaid/77bb745b-aa8a-41fb-96f7-ef5ecbca283d/%E3%83%86%E3%82%99%E3%83%BC%E3%82%BF%E3%82%BB%E3%83%83%E3%83%88_-_%E7%A4%BE%E5%86%85%E6%A4%9C%E8%A8%BC%E7%94%A8_yusuke_yajima_-_KARTE(3).png" alt="データセット_-社内検証用_yusuke_yajima-_KARTE(3).png"></p>
<p>必要な情報を入力し、テーブル名などを指定してください。必要に応じて「スキーマ」なども指定してください。一般的には指定することをおすすめします。入力が完了したら、「作成する」をクリックしてください。</p>
<p><img src="https://ik.imagekit.io/plaid/087fbbac-7f59-4c5b-81fa-bc1ce5ee2511/%E3%83%86%E3%82%99%E3%83%BC%E3%82%BF%E3%82%BB%E3%83%83%E3%83%88_-_%E7%A4%BE%E5%86%85%E6%A4%9C%E8%A8%BC%E7%94%A8_yusuke_yajima_-_KARTE(5).png" alt="データセット_-社内検証用_yusuke_yajima-_KARTE(5).png"></p>
<p>作成されると以下のようになります。今回はジョブフローを作成するので、「ジョブ作成」をクリックして次に進みます。</p>
<p><img src="https://ik.imagekit.io/plaid/9927ba9f-c952-4a78-ae48-fd73e05f7764/%E3%83%86%E3%82%99%E3%83%BC%E3%82%BF%E3%82%BB%E3%83%83%E3%83%88_-_%E7%A4%BE%E5%86%85%E6%A4%9C%E8%A8%BC%E7%94%A8_yusuke_yajima_-_KARTE_%E3%81%A8_%E6%A0%AA%E5%BC%8F%E4%BC%9A%E7%A4%BE%E3%83%95%E3%82%9A%E3%83%AC%E3%82%A4%E3%83%88%E3%82%99_-_%E3%82%AB%E3%83%AC%E3%83%B3%E3%82%BF%E3%82%99%E3%83%BC_-_2023%E5%B9%B4_4%E6%9C%88_3%E6%97%A5__%E6%9C%88%E6%9B%9C%E6%97%A5_%E3%80%81%E4%BB%8A%E6%97%A5.png" alt="データセット_-社内検証用_yusuke_yajima-KARTE_と_株式会社プレイド-カレンダー-2023年_4月_3日__月曜日、今日.png"></p>
<h2>ジョブフローの設定</h2>
<p>ジョブフローを作成し、データをインポートします。</p>
<p>今回は、上記の手順で遷移してきましたが、「グローバルメニュー」→「Datahub」→「ジョブフロー」から作成することもできます。</p>
<h3>ジョブの設定</h3>
<p>「外部サービス」を選択後、「接続先の作成・管理」をクッリクします。</p>
<p><img src="https://ik.imagekit.io/plaid/3e5fe768-1242-4470-b576-f97df3277fb0/%E3%83%86%E3%82%99%E3%83%BC%E3%82%BF%E3%82%BB%E3%83%83%E3%83%88_-_%E7%A4%BE%E5%86%85%E6%A4%9C%E8%A8%BC%E7%94%A8_yusuke_yajima_-_KARTE(6).png" alt="データセット_-社内検証用_yusuke_yajima-_KARTE(6).png"></p>
<p>「作成」から「Amazon S3」を選択します</p>
<p><img src="https://ik.imagekit.io/plaid/7760c567-2517-4e2e-90b0-d1f7c6607665/%E3%83%86%E3%82%99%E3%83%BC%E3%82%BF%E3%82%BB%E3%83%83%E3%83%88_-_%E7%A4%BE%E5%86%85%E6%A4%9C%E8%A8%BC%E7%94%A8_yusuke_yajima_-_KARTE(7).png" alt="データセット_-社内検証用_yusuke_yajima-_KARTE(7).png"></p>
<p>接続先名などを入力して上部の「保存」を押します。</p>
<ul>
<li>接続先名
<ul>
<li>任意</li>
</ul>
</li>
<li>アクセスキーID/シークレットアクセスキー
<ul>
<li>今回は、「S3の設定確認」で確認した値を入力します</li>
</ul>
</li>
<li>リージョン
<ul>
<li>払い出しS3を利用する場合は、<code>ap-northeast-1</code>  を指定してください</li>
</ul>
</li>
</ul>
<p><img src="https://ik.imagekit.io/plaid/df081b69-0a6a-43b5-b5d7-1fb37073982e/%E3%83%86%E3%82%99%E3%83%BC%E3%82%BF%E3%82%BB%E3%83%83%E3%83%88_-_%E7%A4%BE%E5%86%85%E6%A4%9C%E8%A8%BC%E7%94%A8_yusuke_yajima_-_KARTE(8).png" alt="データセット_-社内検証用_yusuke_yajima-_KARTE(8).png"></p>
<p>「保存」後に「接続先に設定」をクリック、または「接続先」より作成した設定を指定します。</p>
<p>指定後、以下を「S3の設定確認」で確認した情報を元に設定します。最後に、「接続を確認する」をクリックして確認します。「成功」していることを確認します</p>
<p><img src="https://ik.imagekit.io/plaid/bbb4ea65-b256-4f19-acf3-8aa36751cde7/%E3%83%86%E3%82%99%E3%83%BC%E3%82%BF%E3%82%BB%E3%83%83%E3%83%88_-_%E7%A4%BE%E5%86%85%E6%A4%9C%E8%A8%BC%E7%94%A8_yusuke_yajima_-_KARTE(9).png" alt="データセット_-社内検証用_yusuke_yajima-_KARTE(9).png"></p>
<p>ジョブ名などを必要に応じて設定し、「完了」をクリックします</p>
<h3>ジョブフロー設定</h3>
<p>必要に応じて以下を設定します。今回は使用しないので、「ジョブフロー名」を設定して、右上の「保存」よりジョブフローを保存します。</p>
<p><img src="https://ik.imagekit.io/plaid/840bad23-91e6-49b4-ae09-f76b7153b210/QualtData(2).png" alt="QualtData(2).png"></p>
<p>右上にある「保存」をクリックし、「個別に実行」でジョブを実行します。</p>
<p><img src="https://ik.imagekit.io/plaid/b0b7e96e-7c3c-4359-aad3-dcbcb4f7837b/QualtData(3).png" alt="QualtData(3).png"><br>
<img src="https://ik.imagekit.io/plaid/4a2a7688-97a3-4af3-8ec1-82a8548f5944/QualtData(4).png" alt="QualtData(4).png"></p>
<h2>確認</h2>
<p>実行ログが「実行済」になっていることを確認し、対象のデータセットに値が入っていることを確認してください。データテーブルにデータが入っていれば成功です！</p>
<p>お疲れさまでした！</p>
<h2>最後に</h2>
<p>今回は、KARTEで払い出したS3を利用しての連携を紹介しましたが、お客様環境で作成したS3でもほぼ同じ手順で利用が可能です。手軽にKARTEに情報が連携できるのは魅力的ですね！インポートしたデータを分析したり、紐付けテーブルで活用したりと幅が広がりますので、ぜひ活用してみてください。</p>


KARTE DatahubとAmazon S3連携をステップ・バイ・ステップで手順を確認する

<h1>このブログについて</h1>
<p>本ブログ最初の記事ということで、簡単にブログ開設の背景を記載させていただきます。<br>
本題を読みたい方は、そっと下にスクロールして次項に進んでください。</p>
<p>私はカスタマーエンジニアとして、<a href="https://karte.io/">KARTE</a>活用の技術的なサポートを行っています。<br>
（カスタマーエンジニアがどんな職種か気になった方は、ぜひ<a href="https://blog.plaid.co.jp/n/n6d87538d003f">こちら</a>をご一読ください。）</p>
<p>日々の業務の中で、</p>
<ul>
<li>KARTEを深く利用することで、何ができるのか知ってほしい</li>
<li>サポートサイトの幅には収まらない、もっと踏み込んだ活用方法（ソリューション）を広く伝えたい</li>
</ul>
<p>という思いを持つようになりました。<br>
そして、それは他のカスタマーエンジニアも同様でした。</p>
<p>KARTEは汎用性が高いプロダクトである反面、使いこなすことが難しいプロダクトでもあります。</p>
<p>このブログを通して、KARTEユーザーの創造性を刺激し、ソリューション実現の手助けとなるようなコンテンツを発信していきたいと考えております。</p>
<h1>この記事について</h1>
<p>さて、本記事ではDatahubクエリについてのTipsをご紹介します。<br>
KARTEの汎用性を高める機能であるDatahubの活用により、KARTE内外のデータを利用することで施策の幅を広げたり、柔軟なデータ分析を実施したりすることが可能となります。<br>
Datahubクエリは、基本的にはBigQueryの標準SQLを踏襲しており、自由度が高い機能となっています。</p>
<p>今回は、その中でも難易度の高い要素の一つとなる、タイムゾーンを考慮したDatahubクエリの記述方法についてのご紹介です。<br>
具体的には、標準ではUTCでの絞り込みとなる<strong>Period型のパラメータを使って、JST（日本標準時）でデータを絞り込む方法</strong>について記載します。</p>
<h1>仕様の整理</h1>
<p>まずは、DatahubでPeriod型のパラメータを指定した際の仕様について整理します。</p>
<p>今回は、クエリコレクションの「UU、PV、セッション数の算出」を例にみていきます。<br>
クエリは下記のようになっています。</p>
<pre><code class="language-SQL">SELECT
  DATE(sync_date) AS date
  , COUNT(DISTINCT user_id) AS uu
  , COUNT(DISTINCT session_id) AS session
  , COUNT(*) AS pv
FROM
  {% karte_event period[0], period[1] %}
WHERE
  event_name = 'view'
GROUP BY date
ORDER BY date DESC
</code></pre>
<p>パラメータを下記のように設定し、クエリを実行します。<br>
その後、「変換後クエリ」から実際に実行されたクエリについて確認してみます。</p>
<p><img src="https://ik.imagekit.io/plaid/c870cd60-addb-47e2-a104-e74c7bc989c6/%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-02-2719.57.40.png" alt="スクリーンショット2023-02-2719.57.40.png"></p>
<p>変換後のクエリは下記のようになっています。</p>
<pre><code class="language-SQL">SELECT
  DATE(sync_date) AS date
  , COUNT(DISTINCT user_id) AS uu
  , COUNT(DISTINCT session_id) AS session
  , COUNT(*) AS pv
FROM
  (SELECT sync_date as sync_date, user_id as user_id, visitor_id as visitor_id, session_id as session_id, event_name as event_name, values as values, shorten_segments as shorten_segments, scores as scores, keys.is_visitor as is_visitor, source as source, event_hash as event_hash, user_fields as user_fields, dimensions as dimensions, processor as processor, keys.live_session_id as live_session_id FROM `karte-data.karte_stream_{{API_KEY}}.krt_pockyevent_v1_*` WHERE _TABLE_SUFFIX BETWEEN '20230220' AND '20230222')
WHERE
  event_name = 'view'
GROUP BY date
ORDER BY date DESC
</code></pre>
<p>少し見づらいですが、ポイントは下記2点です。</p>
<ul>
<li><code>karte_event</code> の実態は <code>karte-data.karte_stream_{{API_KEY}}.krt_pockyevent_v1_*</code> の特定カラムを抜き出したviewである</li>
<li><code>karte-data.karte_stream_{{API_KEY}}.krt_pockyevent_v1_*</code> はUTCベースの日付でパーティションされており、Period型のパラメータでパーティションされたテーブルを絞り込むことで期間指定を実現している</li>
</ul>
<h1>JSTへの換算</h1>
<p>DatahubではUTCでデータが格納されているので、上述の例で抽出対象の期間をJSTからUTCに変換してみます。</p>
<table>
<thead>
<tr>
<th></th>
<th>JST</th>
<th>UTC</th>
</tr>
</thead>
<tbody>
<tr>
<td>起点となる時間</td>
<td>2023-02-20 00:00:00</td>
<td>2023-02-19 15:00:00</td>
</tr>
<tr>
<td>終点となる時間</td>
<td>2023-02-23 00:00:00</td>
<td>2023-02-22 15:00:00</td>
</tr>
</tbody>
</table>
<p>前項より、JSTによる絞り込みには下記2つの工程が必要となります。</p>
<ol>
<li>パーティションされたテーブル全体が抽出対象ではなくなるため、イベント送信日時（ <code>sync_date</code> ）ベースでの絞り込みを行う</li>
<li>UTCベースで2023-02-19からデータが必要になるため、一日分多くパーティションされたテーブルを取得する</li>
</ol>
<h2>Step1 抽出対象のイベント送信日時を算出する</h2>
<p>今回の要件を整理すると、イベント送信日時の絞り込みのゴールは下記のようになります。<br>
<code>2023-02-20 00:00:00 JST &lt;= sync_date &lt; 2023-02-24 00:00:00 JST</code></p>
<p>Period型のパラメータは、YYYYMMDD型の文字列の配列が実態となっています。<br>
つまり今回の例の場合、period[0]は20230220という文字列であり、period[1]は20230223という文字列になります。</p>
<p>ここからSQLを利用して、抽出対象となる時間を算出する方法を考えます。</p>
<ol>
<li>period[0]をJSTのtimestampとして解釈、UTCに変換し、これを絞り込み期間の起点とする</li>
<li>period[1]のJSTのtimestampとして解釈、UTCに変換し、そこに一日加算したものを絞り込み期間の終点とする</li>
</ol>
<pre><code class="language-SQL">WITH jst_timestamp AS (
  SELECT
    PARSE_TIMESTAMP('%Y%m%d', {{period[0]}}, 'Asia/Tokyo') AS start_timestamp
    , TIMESTAMP_ADD( PARSE_TIMESTAMP('%Y%m%d', {{period[1]}}, 'Asia/Tokyo'), INTERVAL 1 DAY) AS end_timestamp
)

SELECT * FROM jst_timestamp
</code></pre>
<p>実行結果を見ると、意図した値が算出できていることがわかります。</p>
<p><img src="https://ik.imagekit.io/plaid/650f45ca-4298-4ee5-b304-71f15cea3a2f/%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-02-2720.53.54.png" alt="スクリーンショット2023-02-2720.53.54.png"></p>
<h2>Step2 抽出対象の日付を算出する</h2>
<p>このステップのゴールは、パーティションテーブルの絞り込みに利用する日付文字列を算出することです。<br>
例の場合、「20230219」「20230222」の2つの文字列が必要になります。</p>
<p>こちらは、Step1の結果をYYYYMMDD型の文字列にCASTすることで取得できます。</p>
<pre><code class="language-SQL">WITH jst_timestamp AS (
  SELECT
    PARSE_TIMESTAMP('%Y%m%d', {{period[0]}}, 'Asia/Tokyo') AS start_timestamp
    , TIMESTAMP_ADD( PARSE_TIMESTAMP('%Y%m%d', {{period[1]}}, 'Asia/Tokyo'), INTERVAL 1 DAY) AS end_timestamp
)
, jst_period AS (
  SELECT
    CAST(start_timestamp AS STRING FORMAT 'YYYYMMDD') AS start_period
    , CAST(end_timestamp AS STRING FORMAT 'YYYYMMDD') AS end_period
  FROM
    jst_timestamp
)

SELECT * FROM jst_period
</code></pre>
<p>実行結果を確認すると、こちらも意図通りの結果が得られていることがわかります。</p>
<p><img src="https://ik.imagekit.io/plaid/f2c7cde4-1f9c-4249-bdfd-ab7d0c9fbab6/%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-02-2721.33.48.png" alt="スクリーンショット2023-02-2721.33.48.png"></p>
<h1>最終的なクエリ</h1>
<p>最終的には、下記のようなクエリでJST換算でデータを絞り込むことができました。</p>
<pre><code class="language-SQL">WITH jst_timestamp AS (
  SELECT
    PARSE_TIMESTAMP('%Y%m%d', {{period[0]}}, 'Asia/Tokyo') AS start_timestamp
    , TIMESTAMP_ADD( PARSE_TIMESTAMP('%Y%m%d', {{period[1]}}, 'Asia/Tokyo'), INTERVAL 1 DAY) AS end_timestamp
)
, jst_period AS (
  SELECT
    CAST(start_timestamp AS STRING FORMAT 'YYYYMMDD') AS start_period
    , CAST(end_timestamp AS STRING FORMAT 'YYYYMMDD') AS end_period
  FROM
    jst_timestamp
)
SELECT
  DATE(sync_date) AS date
  , COUNT(DISTINCT user_id) AS uu
  , COUNT(DISTINCT session_id) AS session
  , COUNT(*) AS pv
FROM
  jst_timestamp
  , jst_period
  , {% karte_event_all %} AS t
WHERE
  event_name = 'view'
  AND t.TABLE_SUFFIX BETWEEN start_period AND end_period
  AND sync_date &gt;= start_timestamp
  AND sync_date &lt; end_timestamp
GROUP BY date
ORDER BY date DESC
</code></pre>
<p>いかがでしたでしょうか。<br>
今回ご紹介した内容が少しでもお役に立てば幸いです。</p>
<p>本ブログではこのような小ネタから、もっと本格的に作り込まれたソリューションまで、さまざまなコンテンツを発信していく予定ですので、定期的にチェックしてみてください！</p>
