ファンクションの書き方

このページではCraft Functionsのコードの書き方について、全てのタイプで共通のルールを説明します。タイプ特有のルールについては、それぞれ次のページを参照してください。

HTTPタイプ: HTTPタイプのファンクションを作成する
イベント駆動タイプ: イベント駆動タイプのファンクションを作成する

また、実行環境の使い回しやコールドスタートなどの性質、実行時間や処理力の上限などの制約についてはファンクションの性質と制約を参照してください。

Craft Functions の記法

Craft Functionsのコードの記法を説明します。

Craft Functions のランタイム

Craft FunctionsはNode.jsの実行環境上で動作します。サポート状況はファンクションのランタイムとサポート期限をご確認ください。

Craft Functions のエントリポイント

Craft Functionsでは、次のように定義した関数がエントリポイントとなります。

export default async function (data, { MODULES }) {
  // この関数内に処理を記述する
  // Async Functionとして定義しているので、awaitで呼び出す処理が必要
}

この関数は次の要件を満たします。

関数名は指定しません。 export default として定義します。
引数は data と MODULES 要素を持つオブジェクト ( { MODULES } ) の2つです。
基本的にはasync functionとして定義します。

入力 (data)

Craft Functionsは外部からの入力として、引数 data の値を受け取ります。dataの型はファンクションの種類によって異なります。

HTTPタイプでは、オブジェクト req, res を値に持つobject型です。
イベント駆動タイプでは、object型もしくはstring型です。

それぞれの詳細は HTTPタイプのファンクションを作成するおよびイベント駆動タイプのファンクションを作成するを参照してください。

モジュールの利用

Craft Functionsでは次の方法でモジュールが利用できます。

MODULES 引数の要素として取り出して利用する
npm modulesをコード内でimportする
Node.jsの標準モジュールを利用する

これらのモジュールの使用方法を説明します。

`MODULES` の利用

Craft Functionsの独自モジュールは MODULES 引数の要素として取り出せます。

const { initLogger, secret } = MODULES
const logger = initLogger({ logLevel: 'DEBUG' });

logger.log('informational log');
const { KARTE_SECRET_KEY: secretValue } = await secret.get({ keys: [ 'KARTE_SECRET_KEY' ] });

MODULES で利用できるモジュールは Craft Functions で利用できるモジュールで説明します。

npm modules を import する

npm modulesを利用する際にはファンクション編集画面の modules で利用したいモジュールとバージョンをJSON形式で指定します。

例えば、Google Cloud Pub/SubのNode.jsライブラリを利用する場合は modules で次のように指定します。

{
  "@google-cloud/pubsub": "3.4.1"
}

複数のnpm modulesを利用する場合は、 modules で利用するmoduleをJSON形式で列挙します。

{
  "@google-cloud/pubsub": "3.4.1",
  "@google-cloud/bigquery": "6.1.0"
}

npm modulesをCraft Functions内で利用する際は、Craft Functionsのコード内で import 文を使い呼び出します。

import { PubSub } from "@google-cloud/pubsub";

export default async function (data, { MODULES }) {
  // clientConfigの詳細な設定方法は省略
  const clientConfig = {
    projectId: "hogehoge",
    credentials: {
      client_email: "fugafuga",
      private_key: "foobar",
    },
  };
  const topic = new PubSub(clientConfig).topic("topic-name");

  // 略
}

npm modules の制限

現在Craftで利用できるnpm modulesについては、利用できる npm modules をご参照ください。
各moduleの任意のバージョンが指定できます。ただし、チルダ ~ キャレット ^ によるバージョン指定はできないのでご注意ください。
- 存在しないバージョンを指定するとファンクションの作成に失敗します。

Node.js の標準モジュールを利用する

Node.jsの標準モジュールとして crypto が利用できます。利用する場合は、Craft Functionsのコードでimportします。

import { randomUUID } from "crypto";

export default async function (data, { MODULES }) {
  const { initLogger } = MODULES;
  const logger = initLogger({ logLevel: "DEBUG" });
  logger.log(randomUUID());
}

関数の同期/非同期

Craft Functionsの大半のユースケースでは、外部システムへのアクセスが発生します。JavaScriptでは特に理由がない限り外部へのリクエストは非同期処理で実現するため、多くの場合、Craft FunctionsはAsync Functionとして定義します。

入力を単純にログとして出力するだけの場合、非同期処理は必要ありません。このような場合、Craft Functionsは同期関数として定義できます。

export default function (data, { MODULES }) {
  const { initLogger } = MODULES;
  const logger = initLogger({ logLevel: "DEBUG" });
  // for debbuging.
  logger.log(data);
}

Fetch API の利用

Craft Functions上で外部のリソースにアクセスする場合は、Node.jsの fetch() を利用します。

Global objects | Node.js v20.12.2 Documentation

例: JSON データを取得する

OpenWeatherMap APIを呼び出して緯度経度から天気情報データをjson形式で取り出します。

// 緯度(lat)　経度(lon) をもとに OpenWeatherMap から天気情報を取得する
const api_key = "API_KEY"; // OpenWeatherMapのAPIキーを指定する。
const lat = 35.6696559; // 北緯 35.6696559 度
const lon = 139.7639876; // 統計 139.7639876 度
const ret = await fetch(
  `https://api.openweathermap.org/data/2.5/forecast?lat=${lat}&lon=${lon}&appid=${api_key}`
);
const weather_forecast = await ret.json();

例: CSV ファイルを取得する

内閣府が公開している祝日一覧を取得する例です。

// 内閣府のWebサイトにある国民の祝日一覧CSVを取得する
const HOLIDAYS_LIST_URL =
  "https://www8.cao.go.jp/chosei/shukujitsu/syukujitsu.csv";
const res = await fetch(HOLIDAYS_LIST_URL, {
  method: "GET",
  headers: {
    Accept: "text/csv",
  },
});

// 必要に応じてエラー処理を行う
if (res.status !== 200) {
  logger.error(res);
  throw new Error("cannot get holidays data.");
}

// 祝日一覧のCSVから日時情報のみ取得する
const ret = (await res.text())
  .split("\\n")
  .slice(1)
  .map((line) => line.split(",")[0]);

KARTE のサーバーサイド API (API v2) の利用

Craft FunctionsではKARTEのサーバーサイドAPI (API v2) が利用できます。利用の際にはmodulesで api を指定し、API リファレンスのNodeの実行例に従ってコードを記述します。

例: Send event to KARTE API (/v2/track/event/write) を実行する

modulesでapiを指定します。

{
  "api": "5.0.8"
}

コードでAPIを呼び出します。以下はイベント駆動タイプのファンクションとしての実行例です。

api() の引数にはAPIリファレンスのNodeのリクエスト例（下図）に基づいて設定します。
参考：Send event to KARTE

import api from "api";

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

  // 実際の引数は APIリファレンスNode Example を参照
  const insight = api("@dev-karte/vx.y#zzzzzzzzzzzzz");
  insight.auth("token_value"); // 実運用の際は、Secret Managerに設定したアクセストークンを利用します。

  const res_data = await insight.postV2TrackEventWrite({
    keys: { user_id: "test01" },
    event: {
      values: { key1: "value1", key2: "value2" },
      event_name: "test_event",
    },
  });

  logger.log(res_data);
}