Web上のユーザー行動をトリガーにして外部にWebhookリクエストを飛ばす

<html><head></head><body>こんにちは。エンジニアの矢澤です。
KARTEで接客サービスを作る際、配信スケジュールを設定することはよくあるかと思います。KARTEの接客サービスでは、開始日時・終了日時の指定、曜日指定、時間帯指定による配信スケジュールが組めますが、施策によってはより複雑な配信スケジュールを設定したいかと思います。例えば「毎月第1、第3月曜日はキャンペーン用に通知をしたい」「平日働いている方向けの施策のため、土日だけではなく祝日も接客を配信を止めたい」などです。
残念ながら、2023年6月時点で例に挙げた配信スケジュール設定は標準の機能として提供していません。しかし、KARTE CraftとKARTEの接客サービス公開APIを組み合わせることでこれらの配信スケジュール設定が実現できます。
簡単な実装例は以下のKARTE Craftのドキュメントに記載しております（<a href="https://craft.developers.karte.io/handson/craft-campaign-scheduler" target="_blank" rel="noreferrer">接客スケジュールを複数設定する</a>）が、今回は発展形としてGoogle Calendarを使って接客配信のスケジュールを行う方法を紹介します。
<h1 id="「接客スケジューラー」を考える">「接客スケジューラー」を考える</h1>
今回作る機能を「接客スケジューラー」と呼ぶことにします。接客スケジューラーでやりたいことは次の通りです。
<ul>
<li>複雑な配信スケジュールが設定できる
<ul>
<li>開始日時・終了日時を事前に複数設定できる</li>
<li>定期配信のバリエーションが増やせる</li>
<li>「祝日だけ配信しない」ができる</li>
</ul>
</li>
</ul>
これを実現するために、次のような機能を考えます。
<ul>
<li>Google Calendarに接客サービスの配信スケジュールを予定として登録すると、予定の開始時間以降に配信が開始し、予定の終了時間以降に配信が終了する。
<ul>
<li>複雑な配信スケジュールの設定をGoogle Calendarに任せる。</li>
</ul>
</li>
<li>祝日情報を外部から取得し、祝日時の配信停止を行う。
<ul>
<li>内閣府が公開している祝日一覧のCSVファイルが利用できる。(<a href="https://www8.cao.go.jp/chosei/shukujitsu/gaiyou.html" target="_blank" rel="noreferrer">国民の祝日について - 内閣府</a>)</li>
</ul>
</li>
</ul>
上記を踏まえて接客スケジューラーの構成を考えた結果、次の図のようになりました。Craft Functionを定期実行して、カレンダーのチェックと接客サービスの公開・停止を行います。
<img src="https://ik.imagekit.io/plaid/a4c805ce-4a2e-4dc9-9cba-d5c6063f763f/campaign-scheduler.png" alt="campaign-scheduler.png">
構成要素は次の通りです。
<div class="TableScroll"><table>
<thead>
<tr>
<th>項目</th>
<th>説明</th>
</tr>
</thead>
<tbody>
<tr>
<td>Craft Functions</td>
<td>KARTE Craftのファンクション実行機能です。Google Calendarと祝日情報を取得し、接客サービスの公開・停止を切り替えます。</td>
</tr>
<tr>
<td>Craft Scheduler</td>
<td>Craft Functionsのスケジュール実行トリガーです。接客サービス公開・停止の切り替えをこのトリガーで指定した時間間隔で行います。</td>
</tr>
<tr>
<td>Google Calendar</td>
<td>接客サービスのスケジュールをカレンダーの予定として設定します。</td>
</tr>
<tr>
<td>内閣府Webサイト</td>
<td>国民の祝日一覧をこのサイトから取得します。</td>
</tr>
<tr>
<td>接客サービス</td>
<td>公開・停止切り替えの対象となる接客サービス</td>
</tr>
</tbody>
</table></div>
<h1 id="接客スケジューラーを構築してみる">接客スケジューラーを構築してみる</h1>
構成を考えたので、実際に接客スケジューラーを作ってみます。作業内容はおおまかに次の通りです。
<ul>
<li>Google Cloudのサービスアカウントを作成する</li>
<li>Google Calendarにサービスアカウントを追加する</li>
<li>API v2 Appを作成する</li>
<li>Craft Functionsを作成する</li>
</ul>
<h2 id="準備">準備</h2>
構築にあたって、事前に以下の準備を行います。
<ul>
<li>Google Cloud プロジェクトの作成
<ul>
<li>Google Calendar APIをあらかじめ有効化しておきます。</li>
<li>Google Calendarの設定で組織外のユーザーが追加できない場合はCalendarと同じ組織配下にプロジェクトを作成します。</li>
</ul>
</li>
<li>Google Calendarの作成
<ul>
<li>接客スケジューラー用に新しくカレンダーを作成します。</li>
</ul>
</li>
<li>KARTEのAPI v2 (β API)とKARTE Craftの有効化
<ul>
<li>有効化されていない場合は弊社の担当営業・サクセスにご連絡ください。</li>
</ul>
</li>
</ul>
Google Cloud プロジェクトは、プログラムからGoogle Calendar APIの認証を通すために用意します。具体的には、Google Calendar プロジェクトのサービスアカウントをGoogle Calendarに追加し、サービスアカウントの鍵をクレデンシャルとしてプログラムで使います。
<img src="https://ik.imagekit.io/plaid/bb07f984-77ca-42f8-966d-9e7bb3f17dda/google-cloud-sa-key.png" alt="google-cloud-sa-key.png">
<h2 id="Google Cloudのサービスアカウントを作成する">Google Cloudのサービスアカウントを作成する</h2>
Google Cloudのサービスアカウントを作成します。
<ul>
<li>サービスアカウントを作成する
<ul>
<li>以下のドキュメントを参考に、Google Cloudのサービスアカウントを作成します。
<ul>
<li><a href="https://cloud.google.com/iam/docs/service-accounts-create?hl=ja" target="_blank" rel="noreferrer">サービス アカウントを作成する &nbsp;|&nbsp; IAM のドキュメント &nbsp;|&nbsp; Google Cloud</a></li>
</ul>
</li>
<li>サービスアカウントのメールアドレスを管理画面で確認して控えておきます。</li>
</ul>
</li>
<li>サービスアカウントキーを作成する
<ul>
<li>以下のドキュメントを参考に、サービスアカウントのキーを作成します。ここで、鍵の形式はJSON形式を指定します。
<ul>
<li><a href="https://cloud.google.com/iam/docs/creating-managing-service-account-keys?hl=ja" target="_blank" rel="noreferrer">サービス アカウント キーの作成と管理 &nbsp;|&nbsp; IAM のドキュメント &nbsp;|&nbsp; Google Cloud</a></li>
</ul>
</li>
</ul>
</li>
</ul>
<h2 id="サービスアカウントをGoogle Calendarに追加する">サービスアカウントをGoogle Calendarに追加する</h2>
事前に準備したGoogle Calendarの [設定と共有] 画面を開きます。
[特定のユーザーまたはグループと共有する] で先ほど控えていおいたサービスアカウントのメールアドレスを追加します。
以上でGoogle Calendar側の設定は完了です。
<h2 id="API v2 App を作成する">API v2 App を作成する</h2>
今回はKARTEのAPI v2を使って接客サービスの公開・停止を切り替えるため、API v2のアプリケーションが必要になります。
<a href="https://developers.karte.io/reference/post_v2beta-action-campaign-toggleenabled" target="_blank" rel="noreferrer">Toggle campaign's enabled status.</a>
以下のページを参考にアプリケーションを作成します。
<a href="https://developers.karte.io/docs/create-api-v2-apps" target="_blank" rel="noreferrer">アプリを利用する</a>
アプリを作成する際に、 <code>beta.action.campaign.toggleEnabled</code> のスコープを設定しておきます。また、アプリ作成後に1度だけ表示されるアクセストークンを控えておきます。
<h2 id="Craft Functionsを作成する">Craft Functionsを作成する</h2>
接客スケジューラーの本丸である、Craft Functionsを作っていきます。
<h3 id="シークレットを登録する">シークレットを登録する</h3>
ここまでの手順でGoogle CloudのサービスアカウントキーとKARTEのAPI v2のアクセストークンを控えました。これらのシークレット情報（サービスを利用するための鍵）を安全に利用するため、Craft Secret Managerに登録します。
登録する名前は次の通りです。
<ul>
<li><code>GOOGLE_CALENDAR_CREDENTIALS</code> : サービスアカウントキーとして取得したJSON形式のテキストを丸ごと登録します。</li>
<li><code>KARTE_API_TOKEN</code> : API v2 App のアクセストークンを登録します。</li>
</ul>
シークレットの登録方法は次のドキュメントを参考にしてください。 
<a href="https://craft.developers.karte.io/craft-secret-manager/gets-started" target="_blank" rel="noreferrer">Craft Secret Manager</a>
<h3 id="Craft Functionsを作成する">Craft Functionsを作成する</h3>
Craft FunctionsのコードはGitHubリポジトリに置いています。
<a href="https://github.com/plaidev/craft-codes/tree/main/craft-functions/campaign-scheduler" target="_blank" rel="noreferrer">craft-codes/-functions/campaign-scheduler at main · plaidev/craft-codes · GitHub</a>
Craft Functions作成画面のcode に campaign-scheduler.js の内容を貼り付け、modules に modules.json の内容を貼り付けます。codeの <code>管理者向け設定</code> を書き換えます。
<pre><code class="language-js hljs">/**********************************************
 * 管理者向け設定
 **********************************************/

// スケジューラーで管理する対象の接客サービスID
const TARGET_CAMPAIGNS = [
 'aaaaaaaaaaaaaaaaaaaaaaaa',
 'bbbbbbbbbbbbbbbbbbbbbbbb',
];

// カレンダーID
const CALENDAR_ID = 'x_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx@group.calendar.google.com'
</code></pre>
<ul>
<li><code>TARGET_CAMPAIGNS</code> に対象の接客サービスIDを配列形式で指定します。
<ul>
<li>管理画面の接客サービス設定画面のURLを見ると <code>https://admin.karte.io/p/xxxxxxxxxxxxxxxxxxxxxxxx/service/yyyyyyyyyyyyyyyyyyyyyyyy</code> という形式になっています。このURLの <code>/service/</code> 以降、つまり <code>yyyyyyyyyyyyyyyyyyyyyyyy</code> が接客サービスIDです。</li>
</ul>
</li>
<li><code>CALENDAR_ID</code> にGoogle CalendarのIDを指定します。
<ul>
<li>Google CalendarのIDは [設定と共有] 画面で確認できます。</li>
</ul>
</li>
</ul>
上記の書き換えができたら、[保存] を選択してCraft Functionsを作成します。
Craft Functionsの作成方法は次のドキュメントを参考にしてください。 
<a href="https://craft.developers.karte.io/craft-functions/edit-craft-funcitons" target="_blank" rel="noreferrer">Craft Functionsを作成する</a>
<h3 id="Craft Schedulerを設定する">Craft Schedulerを設定する</h3>
作成したCraft Functionsの詳細画面で起動スケジュールを設定します。以下のドキュメントを参考に起動スケジュールを設定します。 
<a href="https://craft.developers.karte.io/craft-functions/triggers/scheduler" target="_blank" rel="noreferrer">Craft Scheduler</a>
起動スケジュール設定によって、公開・停止の切り替えタイミングが変わります。以下は設定例です。
<ul>
<li><code>* * * * *</code> : 毎分起動してGoogle Calendar設定を確認する。</li>
<li><code>0/5 * * * *</code> : 毎時0分から5分毎に起動する。</li>
<li><code>0 * * * *</code> : 1時間毎に起動する。この場合、Google Calendarで分単位の予定を設定しても無視される。</li>
<li><code>15 3 * * *</code> : 毎日3:15に起動する。</li>
</ul>
通常は毎分起動か5分ごとに起動にしておけば良いかと思います。以上で準備は完了です。
<h1 id="実際に動かしてみる">実際に動かしてみる</h1>
接客スケジューラーが完成したところで、実際に動作を確認しましょう。
Google Calendarで接客スケジューラー用のカレンダーに予定を登録します。
<ul>
<li>タイトルに任意の名前を指定します。接客サービスを表す簡単な名前が良いでしょう。</li>
<li>メモ欄に設定を入力します（後述）。</li>
</ul>
設定は以下のJSONフォーマットで記載します。
<pre><code class="language-json hljs">{ 
 "campaign_id": "yyyyyyyyyyyyyyyyyyyyyyyy",
 "on_holiday": "(enable|disable)"
}
</code></pre>
各要素の説明は次の通りです。
<ul>
<li><code>campaign_id</code> : 接客サービスIDです。</li>
<li><code>on_holiday</code> : 祝日の場合の接客サービス公開設定です。<code>enable</code> もしくは <code>disable</code> を指定します。 <code>enable</code> の場合は祝日の場合も接客を公開し、 <code>disable</code> の場合は祝日の際に接客サービスを停止します。このプロパティは省略可能で、省略時は <code>enable</code> と扱われます。</li>
</ul>
設定例を2つ示します。
例1 : 祝日に停止する
<pre><code class="language-json hljs">{
 "campaign_id": "yyyyyyyyyyyyyyyyyyyyyyyy",
 "on_holiday": "disable"
}
</code></pre>
例2 : 祝日の場合も公開する
<pre><code class="language-json hljs">{ "campaign_id": "yyyyyyyyyyyyyyyyyyyyyyyy" }
</code></pre>
実際にカレンダーに登録した様子はこんな感じです。
<img src="https://ik.imagekit.io/plaid/75606a75-fc6e-494c-b6b2-3e6826b6bb08/google-calendar-event.png" alt="google-calendar-event.png">
動作確認のため、現在時刻に予定を作成して1分ほど待つと、ポップアップ接客が公開されました。
<img src="https://ik.imagekit.io/plaid/afb45527-1403-4b53-b8c5-fa4c796e6bca/campaign-scheduler-campaign-enabled.png" alt="campaign-scheduler-campaign-enabled.png">
その後、予定を現在時刻のちょっと前に設定して1分待つと、ポップアップ接客が停止されました。
<img src="https://ik.imagekit.io/plaid/8f2983bc-737a-4338-a802-59ce8042f1e2/campaign-scheduler-campaign-disabled.png" alt="campaign-scheduler-campaign-disabled.png">
このように、カレンダーの予定に連動して接客サービスの公開・停止が行われることがわかります。これで複雑な配信スケジュール設定もGoogle Calendarに登録すればOKですね。
<h1 id="注意点">注意点</h1>
今回作った接客スケジューラーの注意点は次の通りです。
<ul>
<li>接客サービスを手動で公開・停止するときは、Craft Functionsのコードから対象の接客サービスIDを削除してください。コードに接客サービスIDが残ったままだと、Craft Functionsの定期起動によってGoogle Calendar通りの公開設定に戻ってしまいます。</li>
<li>接客サービスの公開・停止は、カレンダーに設定した時刻から数秒〜数十秒程度遅れます。秒単位のタイムラグが許容できる環境で利用してください。</li>
<li>接客サービスの公開・停止をするAPI <code>/v2beta/action/campaign/toggleEnabled</code> には分間のリクエスト数制限があります。直近1分で制限を超えたリクエストはエラーとなるため、リクエスト制限を超える数の接客を対象にする場合は上限の解放をご検討ください。
<ul>
<li><a href="https://developers.karte.io/reference/api-v2-limitation" target="_blank" rel="noreferrer">API のリクエスト回数制限</a></li>
</ul>
</li>
</ul>
<h1 id="まとめ">まとめ</h1>
今回はGoogle CalendarとKARTE Craftを活用して、KARTEの接客スケジューラーを作ってみました。KARTEの標準の配信スケジュール機能にはない複雑なスケジュール設定が実現できました。このように、KARTE Craftを使って外部サービスと連携することで、KARTE標準の機能を拡張することができます。今後もKARTE Craftの活用例を発信していきますので、お楽しみに！
<hr>
プレイドでは、世の中にインパクトを与える新しいソリューションを一緒につくる仲間を募集しています！ 
ぜひ気軽にお問い合わせください。
↓ パートナー企業になりたい
<ul>
<li><a href="https://ecosystem.plaid.co.jp/" target="_blank" rel="noreferrer">CustomerData-Driven Solution を一緒に創りませんか？ | PLAID Ecosystem</a></li>
</ul>
↓ プレイドで働きたい
<ul>
<li><a href="https://recruit.plaid.co.jp/requisitions/general-customer-engineer" target="_blank" rel="noreferrer">Customer Engineer | 募集ポジション | 株式会社プレイド</a></li>
<li><a href="https://recruit.plaid.co.jp/requisitions/product-engineer" target="_blank" rel="noreferrer">Product Engineer | 募集ポジション | 株式会社プレイド</a></li>
</ul>
</body></html>

KARTEの接客は時間帯、曜日によるスケジュール配信が可能ですが、「第2水曜日の日中だけ配信」のような複雑なスケジュールは設定できません。この記事ではGoogle CalendarとKARTE Craftを使って複雑な接客スケジュールを設定する方法を説明します。

KARTE CraftとGoogle Calendarを使ってKARTEの接客配信スケジュールを拡張しよう