外部 API と連携する

このユースケースでできること

HTTPタイプのCraft Functionsをエンドポイントとして公開し、リクエストをきっかけに外部REST APIを呼び出して取得データをレスポンスとして返せます。APIキーは Craft Secret Manager で管理し、クライアント側に露出しません。

利用シーン

Craft Sites や Web アプリのバックエンド
- ブラウザから直接外部APIを呼べない（APIキーを隠したい）とき、Functionを経由してデータを取得する
オンデマンドなデータ取得
- ユーザーの操作や画面表示のタイミングで、CRM・在庫・天気など外部サービスの最新情報を取りにいく
外部APIのレスポンスを加工して返す
- 取得結果をフィルタ・整形してから、フロントや別システムに渡す

定期実行でデータを同期する場合はスケジュール実行するを、KARTEの接客をきっかけに外部へ送る場合は KARTE の接客から処理を実行するを参照してください。

サンプルコード

HTTPタイプのファンクションとしてデプロイします。

export default async function (data, { MODULES }) {
  const { res, secret } = MODULES;
  const logger = MODULES.initLogger({ logLevel: "INFO" });

  const apiKey = await secret.get("EXTERNAL_API_KEY_NAME");
  const response = await fetch("https://api.example.com/data", {
    headers: { Authorization: `Bearer ${apiKey}` },
  });

  if (!response.ok) {
    logger.error("API request failed", { status: response.status });
    return res.status(502).json({ error: "External API error" });
  }

  const body = await response.json();
  return res.status(200).json(body);
}

前提と手順の詳細

ファンクションの作成・デプロイ
- ファンクションを作成、編集、削除する（HTTPタイプを選択）
HTTPタイプの入力・レスポンス
- HTTPタイプのファンクション
APIキーの登録
- Craft Secret Manager

このユースケースのポイント

secret モジュールでキーを取得し、fetch の Authorization ヘッダーに付与する
外部APIのエラーはログに残し、クライアントには 502 で返す

動作確認

デプロイ後に表示されるエンドポイントURLへリクエストします。

curl https://<your-endpoint-url>

外部APIから取得したJSONが返れば成功です。