commerce-app-business-config

Commerce App のビジネス設定を構成する

既存の app.commerce.config.ts にある businessConfig.schema 配列を追加または変更します。 スキーマ内の各エントリは、Commerce Admin が UI フィールドとして表示する、マーチャントが設定可能な項目を定義します。 その他の拡張性ドメイン（webhooks、events）は、それぞれのスキルを使って別途追加します。

前提条件

• 設定ファイルが存在するだけでなく、アプリがスキャフォールディングされ、初期化済みであることを確認してください。次の両方が必要です。
  • プロジェクトルートに app.commerce.config.ts が存在すること、および
  • プロジェクトが初期化済みであること — 生成された src/commerce-extensibility-1/ ディレクトリと、インストール済みの node_modules（依存関係の @adobe/aio-commerce-lib-app）で確認できます。
• app.commerce.config.ts が存在しない場合は、停止してまず commerce-app-init を呼び出してください（設定を書き込み、その後 init を実行します）。
• 設定ファイルは存在するが、プロジェクトが初期化されていない（src/commerce-extensibility-1/ または node_modules がない）場合は、続行する前に npx @adobe/aio-commerce-lib-app init を実行してください。init は冪等です。既存の設定を検出して対話形式のプロンプトをスキップし、依存関係をインストールしてプロジェクトファイルを生成します。

Step 1 — 意図を把握する

ユーザーが公開したい各設定について、次の情報を収集します。

• 名前 — フィールドの機械処理用識別子（実行時にアプリが読み取る設定キーとして使用）
• 型 — 次のいずれか：list、text、password、email、url、tel、boolean
• ラベル（任意）— Admin に表示される、人が読みやすいラベル
• 説明（任意）— Admin でフィールドの横に表示されるヘルプテキスト
• デフォルト値（任意、型に依存 — 制約については Step 2 を参照）
• list フィールドの場合はさらに、selectionMode（"single" または "multiple"）と options（それぞれに label と value の文字列を含む）

ステップ 2 — 設定値を導き出す

書き込む前に、以下の型ごとの検証ルールを適用してください。先に進む前に、問題があればユーザーに伝えてください。

フィールド	制約
name	必須。空でない文字列
type	必須。list、text、password、email、url、tel、boolean のいずれか
label	省略可能な文字列
description	省略可能な文字列
list.selectionMode	list フィールドで必須："single" または "multiple"
list.options	list フィールドで必須。各オプションには label と value の両方の文字列が必要です
list/single のデフォルト	必須。オプションの value 文字列のいずれかと一致する必要があります（空でないこと）
list/multiple のデフォルト	省略可能な文字列配列（デフォルトは []）。各要素はオプションの値と一致する必要があります
text のデフォルト	省略可能な文字列（デフォルトは ""）
password のデフォルト	"" である必要があります。設定内のシークレットを防ぐため、空でないデフォルト値は拒否されます
email のデフォルト	省略可能。"" または完全に有効なメールアドレス
url のデフォルト	省略可能。"" または完全に有効な絶対 URL
tel のデフォルト	省略可能。/^\+?[0-9\s\-()]+$/ に一致（数字、空白、ハイフン、括弧、任意の +）
boolean のデフォルト	省略可能なブール値（デフォルトは false）

businessConfig.schema には少なくとも 1 つのフィールドが必要です。空の配列はビルド時に拒否されます。

ステップ 3 — app.commerce.config.ts を更新する

トップレベルの businessConfig.schema 配列に追加（または統合）し、他のすべてのドメインを保持してください。設定に businessConfig キーがすでにある場合は、置き換えずに businessConfig.schema に追加してください。

最小限の例：

businessConfig: {
  schema: [
    // Password (masked input — API keys, secrets)
    { name: "api_key", type: "password", label: "API Key", default: "" },

    // Single-select list
    {
      name: "region", type: "list", selectionMode: "single",
      label: "Region",
      options: [{ label: "EU", value: "eu" }, { label: "US", value: "us" }],
      default: "eu",   // required; must match an option value
    },

    // Boolean toggle
    { name: "debug_mode", type: "boolean", label: "Enable Debug Mode", default: false },

    // Dynamic list — options resolved at runtime via a factory that receives the action's params.
    // Required `default` factory for single-select; optional for multiple (falls back to []).
    {
      name: "paymentMethod", type: "dynamicList", selectionMode: "single",
      label: "Default Payment Method",
      options: async (params) => {
        const methods = await fetchPaymentMethods(params.SOME_API_KEY);
        return methods.map((m) => ({ label: m.title, value: m.code }));
      },
      default: (resolvedOptions) => resolvedOptions[0].value,
    },
  ],
}

すべてのフィールド型を示す完全なリファレンスは、assets/business-config.ts を参照してください。

ステップ 4 — 拡張ポイントを登録する

init を実行し、commerce/configuration/1 を app.config.yaml と install.yaml に追加して、必須の @adobe/aio-commerce-lib-config 依存関係をインストールします。この処理は冪等性があり、拡張ポイントがすでに登録されていても安全に実行できます。

npx @adobe/aio-commerce-lib-app init

ステップ 5 — 検証する

プロジェクトをビルドして、更新した設定が有効であることを確認します。

aio app build

検証エラーによるビルド失敗では、問題のあるフィールドが直接示されます。

ランタイムアクションで設定を読み取る

@adobe/aio-commerce-lib-config を使用して、マーチャントが Commerce Admin で設定した値を読み取ります。 設定に関する呼び出しを行う前に、アクションを呼び出すたびに、生成されたスキーマを使ってライブラリを初期化する必要があります。

基本パターン

import {
  initialize,
  getConfigurationByKey,
  getConfiguration,
  byCodeAndLevel,
} from "@adobe/aio-commerce-lib-config";
// Schema is generated by `aio app build` into .generated/configuration-schema.json
// under the commerce-configuration-1 extension; adjust the relative path for your action.
import schema from "../../.generated/configuration-schema.json" with { type: "json" };

export async function main(params) {
  await initialize({ schema });

  // Read a single field — config is null if the key has never been set
  const { config } = await getConfigurationByKey(
    "api_key", // the `name` from your schema
    byCodeAndLevel("global", "global"), // scope
  );
  const apiKey = config?.value ?? "";

  // Read all fields for a scope
  const { config: allConfig } = await getConfiguration(
    byCodeAndLevel("global", "global"),
  );
  // allConfig is an array of { name, value, origin } entries

  return { statusCode: 200, body: { success: true } };
}

スコープセレクター

セレクター	使用する場面
byCodeAndLevel("global", "global")	アプリ全体の設定 — すべてのストアに適用されます
byCodeAndLevel(storeCode, "store_view")	ストアビューごとの設定（最も具体的）
byCode(storeCode)	スコープのデフォルトレベルを使用して解決する場合
byScopeId(scopeId)	Commerce のスコープの数値 ID がある場合

値は親スコープから継承されます。store_view に設定されていないフィールドは、store、website、次に global の値にフォールバックします。

パスワードフィールド

aio app build は、パスワードフィールドを初めて検出したときに AIO_COMMERCE_CONFIG_ENCRYPTION_KEY を自動生成して .env に書き込みます（以降のビルドでは値を検証します）。手動での設定は不要です。

実行時に値を復号化するには、このキーをアクションで使用できるようにする必要があります。アクションの ext.config.yaml で入力として設定します。

inputs:
  AIO_COMMERCE_CONFIG_ENCRYPTION_KEY: $AIO_COMMERCE_CONFIG_ENCRYPTION_KEY

キーを設定すると、getConfigurationByKey は平文の値を返します。追加の復号化コードは不要です。

よくある問題

• list/single のデフォルト値がない：単一選択リストフィールドには default が必須で、省略できません。いずれかのオプションの value 文字列と完全に一致する必要があります。
• defineConfig が見つからない：@adobe/aio-commerce-lib-app がインストールされていること、および defineConfig を @adobe/aio-commerce-lib-app/config からインポートしていることを確認してください。

品質基準

• aio app build がエラーなく完了する

次のステップ

aio app build が成功したら：

• Webhook インターセプターを追加する — commerce-app-webhooks を呼び出して、Commerce の操作の実行前または実行後にインターセプトします
• イベントサブスクリプションを追加する — commerce-app-eventing を呼び出して、Commerce または外部のイベントをサブスクライブします
• Admin UI を拡張する — commerce-app-admin-ui を呼び出して、Commerce Admin にカスタム列、一括アクション、注文表示ボタン、またはメニュー項目を追加します

参考資料

• assets/business-config.ts — すべてのフィールドタイプをインラインの制約コメント付きで示した設定例