variable-creation

変数の作成

Domo のカード変数（インタラクティブコントロール）を作成し、実行するための curl コマンドまたは CLI コマンドを出力します。

変数は、Beast Mode の数式に値を渡すユーザーが調整可能な値で、動的な what-if 分析を可能にします。カードやダッシュボード上に、ドロップダウン、ピル、スライダー、テキストボックス、日付ピッカーの各コントロールとして表示されます。

このスキルを使用する場面

• ユーザーがカード上のドロップダウン、スライダー、またはインタラクティブコントロールを求めている
• ユーザーが「変数」や「パラメーター」に言及している、または動的／調整可能な値を求めている
• カードに what-if 分析や、ユーザーが選択可能な入力が必要である
• カードを作成していて、Beast Mode にユーザーが制御できる入力が必要だと気づいた

基本ワークフロー — 3 ステップでの作成

変数の作成には、順番に実行する 3 つの API 呼び出しが必要です。すべて必須です。途中のステップを省略すると、カードの保存時に 400 エラーが発生します。

1. Check name uniqueness (GET /query/v1/functions/variables/uniqueName)
2. Create the function template WITH embedded control (POST /query/v1/functions/template)
3. Register the variable control (PUT /content/v1/variable/controls)
4. Read the current card definition (PUT /content/v3/cards/kpi/definition)
5. Save the card with the new control (PUT /content/v3/cards/kpi/{cardId})

---

前提条件

パラメーター	ソース	必須
instanceUrl	Domo インスタンス（例：domo-gordon-pont.domo.com）	常に
devToken	CLI 認証／開発者トークン	常に
cardId	カード ID	常に
dataSourceId	データセット UUID（カード定義または列から取得）	検証とカードの保存に必要

---

変数のデータ型

データ型	式の例	対応するコントロール
string	'TEST'、'Option A'	DROPDOWN、PILL、TEXTBOX
numeric	100、0.5	DROPDOWN、PILL、SLIDER、TEXTBOX
date	CURRENT_DATE()、'2024-01-01'	DROPDOWN、DATE_PICKER

---

変数コントロールの種類

種類	説明	最適な用途
DROPDOWN	定義済みの値のリストから選択	カテゴリ選択、文字列／数値／日付
PILL	インラインの切り替えチップ	選択肢が少ない場合（2～5 個）
SLIDER	数値範囲スライダー	最小値と最大値がある数値範囲
TEXTBOX	自由入力	自由形式の文字列／数値入力
DATE_PICKER	カレンダーの日付選択	日付変数

データ型別の式の種類

データ型	exprType
string	STRING_VALUE
numeric	NUMERIC_VALUE
date	DATE_VALUE

値の配列

DROPDOWN および PILL コントロールでは、values 配列で選択可能なオプションを定義します。

{"expression": {"value": "Option Text", "exprType": "STRING_VALUE"}}

SLIDER コントロールでは、値で最小値と最大値の範囲を定義します。

[
  {"expression": {"value": "0", "exprType": "NUMERIC_VALUE"}},
  {"expression": {"value": "100", "exprType": "NUMERIC_VALUE"}}
]

---

ステップ 1：名前の一意性を確認する

エンドポイント： GET /api/query/v1/functions/variables/uniqueName?name={name}

curl -X GET "https://{instanceUrl}/api/query/v1/functions/variables/uniqueName?name={variableName}" \
  -H "X-DOMO-Developer-Token: {devToken}"

名前を使用できる場合は [] を返します。名前がすでに使用されている場合は、関数テンプレート ID の配列を返します。変数名は、Domo インスタンス全体で一意である必要があります。

---

ステップ 2：関数テンプレートを作成する

エンドポイント： POST /api/query/v1/functions/template

これにより、変数の関数テンプレートが作成されます。リクエストボディには埋め込みの control オブジェクトを含める必要があります。これは重要で、通常の Beast Mode 作成とは異なります。

curl -X POST "https://{instanceUrl}/api/query/v1/functions/template" \
  -H "X-DOMO-Developer-Token: {devToken}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "{variableName}",
    "formula": "{defaultExpression}",
    "status": "VALID",
    "dataType": "{dataType}",
    "persistedOnDataSource": false,
    "isAggregatable": true,
    "bignumber": false,
    "owner": null,
    "nonAggregatedColumns": [],
    "legacyId": "calculation_{uuid}",
    "variable": true,
    "isCalculation": true,
    "initialPersistedOnDataSource": false,
    "saved": true,
    "query": "{defaultExpression}",
    "control": {
      "format": {"type": "default"},
      "controlType": "VARIABLE",
      "function": {
        "name": "{variableName}",
        "dataType": "{dataType}",
        "expression": "{defaultExpression}",
        "id": -201
      },
      "saveOverride": true,
      "description": "",
      "values": [
        {"expression": {"value": "{value1}", "exprType": "{exprType}"}},
        {"expression": {"value": "{value2}", "exprType": "{exprType}"}}
      ],
      "type": "{controlType}",
      "unsaved": true,
      "name": "{variableName}",
      "id": -101
    },
    "description": "",
    "locked": false,
    "cacheWindow": "non_dynamic",
    "containsAggregation": false,
    "containsAnalytic": false,
    "invalidColumns": [],
    "nonAggregatedExpressions": [],
    "formulaTemplateDependencies": [],
    "columnPositions": [],
    "formulaId": "calculation_{another_uuid}",
    "formulaDependencies": [],
    "isControlled": false,
    "global": true,
    "unsaved": true,
    "expression": "{defaultExpression}"
  }'

主なフィールド：

• variable: true — 通常の Beast Mode ではなく、変数関数であることを示します
• control — プレースホルダー ID（-201、-101）を含む埋め込みのコントロール定義
• legacyId と formulaId — calculation_{uuid} 形式の一意な UUID を生成します
• global: true — 変数はインスタンス全体に適用されます
• owner: null — オーナーはサーバーによって割り当てられます

レスポンス — id（数値の関数テンプレート ID）を保存します。

{
  "id": 1172,
  "name": "{variableName}",
  "legacyId": "calculation_{uuid}",
  "variable": true,
  ...
}

---

ステップ 3：変数コントロールを登録する

エンドポイント： PUT /api/content/v1/variable/controls

このステップでは、コントロールを Domo コントロールシステムに登録します。このステップを行わないと、カードの保存時に 400 が返されます。

curl -X PUT "https://{instanceUrl}/api/content/v1/variable/controls" \
  -H "X-DOMO-Developer-Token: {devToken}" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "format": {"type": "default"},
      "controlType": "VARIABLE",
      "function": {
        "name": "{variableName}",
        "dataType": "{dataType}",
        "expression": "{defaultExpression}",
        "id": {functionTemplateId from Step 2}
      },
      "saveOverride": true,
      "description": "",
      "values": [
        {"expression": {"value": "{value1}", "exprType": "{exprType}"}},
        {"expression": {"value": "{value2}", "exprType": "{exprType}"}}
      ],
      "type": "{controlType}",
      "unsaved": false,
      "name": "{variableName}"
    }
  ]'

ステップ 2 のコントロールとの主な違い：

• function.id はステップ 2 で取得した実際のテンプレート ID です（-201 ではありません）
• unsaved: false（true ではありません）
• コントロールレベルに id: -101 はありません
• ボディはコントロールオブジェクトの配列です

レスポンス — 登録済みのコントロールを含む配列が返されます。コントロールにはサーバーによって割り当てられた id が含まれます。

[
  {
    "id": 145,
    "function": {"id": 1172, ...},
    "type": "DROPDOWN",
    "values": [...],
    "controlType": "VARIABLE",
    ...
  }
]

---

ステップ 4：現在のカード定義を読み取る

curl -X PUT "https://{instanceUrl}/api/content/v3/cards/kpi/definition" \
  -H "X-DOMO-Developer-Token: {devToken}" \
  -H "Content-Type: application/json" \
  -d '{
    "dynamicText": true,
    "variables": true,
    "urn": "{cardId}"
  }'

レスポンス全体を保存します。definition.subscriptions、definition.controls、definition.charts、definition.modified などが必要です。

レスポンスの columns[].sourceId から dataSourceId を取得します。

---

ステップ 5：新しいコントロールを追加してカードを保存する

エンドポイント： PUT /api/content/v3/cards/kpi/{cardId}

カード定義に新しいコントロールをマージして、更新ペイロードを作成します。

curl -X PUT "https://{instanceUrl}/api/content/v3/cards/kpi/{cardId}" \
  -H "X-DOMO-Developer-Token: {devToken}" \
  -H "Content-Type: application/json" \
  -d '{
    "definition": {
      "subscriptions": {existing subscriptions from card def — do NOT add dataSourceId here},
      "formulas": {"dsUpdated": [], "dsDeleted": [], "card": []},
      "annotations": {"new": [], "modified": [], "deleted": []},
      "conditionalFormats": {"card": [], "datasource": []},
      "controls": [{existing controls with saveOverride: true}, {new control}],
      "segments": {"active": [], "create": [], "update": [], "delete": []},
      "charts": {existing charts},
      "dynamicTitle": {existing dynamicTitle},
      "dynamicDescription": {"text": []},
      "chartVersion": "{existing chartVersion}",
      "allowTableDrill": true,
      "inputTable": false,
      "modified": {existing modified timestamp},
      "title": "{card title}",
      "description": ""
    },
    "dataProvider": {"dataSourceId": "{dataSourceId}"},
    "variables": true,
    "columns": false
  }'

ペイロードに関する重要な注意事項：

• トップレベルでは variables: true と columns: false を指定します
• dataSourceId は dataProvider のみに指定し、subscriptions.main には指定しません
• formulas には {dsUpdated, dsDeleted, card} 構造を使用します（読み取りレスポンスの配列形式ではありません）
• 既存のコントロールは、saveOverride: true を追加した完全なサーバー形式で渡す必要があります
• 新しいコントロールには、ステップ 2 で取得したテンプレート ID を function.id に指定する簡略形式を使用します
• modified タイムスタンプは、カード定義の値と一致させる必要があります

---

オプション：変数の数式を検証する

エンドポイント： POST /api/query/v1/functions/validateFormulas

検証は任意ですが、作成前に実行することをおすすめします。数式エントリーには "variable": true を指定する必要があります。

curl -X POST "https://{instanceUrl}/api/query/v1/functions/validateFormulas" \
  -H "X-DOMO-Developer-Token: {devToken}" \
  -H "Content-Type: application/json" \
  -d '{
    "dataSourceId": "{dataSourceId}",
    "columns": [{column schema array}],
    "formulas": {
      "{formulaId}": {
        "id": "{formulaId}",
        "name": "{variableName}",
        "formula": "{defaultExpression}",
        "status": "valid",
        "dataType": "{dataType}",
        "variable": true,
        "templateId": null,
        "legacyId": "{formulaId}",
        "formulaDependencies": []
      }
    }
  }'

---

Beast Mode で変数を使用する

Beast Mode の数式で参照しない限り、変数はカードに影響しません。

CASE
  WHEN `My Variable` = 'Option A' THEN `column_a`
  WHEN `My Variable` = 'Option B' THEN `column_b`
  ELSE `column_a`
END

変数はデータセットの列と同様に、バッククォートで囲んだ名前で参照します。

---

3 層のコントロール階層

変数には、次の 3 段階のオーバーライド設定があります。

1. デフォルトコントロール — Beast Mode Editor（または API）で設定します。基準となる値です。
2. カード変数コントロール — 特定のカードに対して Analyzer でオーバーライドします。ダッシュボードには引き継がれません。
3. ダッシュボード変数コントロール — 特定のダッシュボードでオーバーライドします。ページを更新するとリセットされます。

---

CLI の使用

community-domo-cli は、3 ステップの一連の処理を自動的に実行します。

# Check if a variable name is available
community-domo-cli variables check-name "My Variable"

# List variables on a card
community-domo-cli variables list {cardId}

# Create a variable (handles all 3 steps internally)
community-domo-cli variables create {cardId} --body-file variable.json

# Validate a variable formula
community-domo-cli variables validate --body-file validate-payload.json

# Read full card definition (includes controls)
community-domo-cli cards definition {cardId}

例：CLI で文字列のドロップダウン変数を作成する

variable.json：

{
  "name": "Region Selector",
  "type": "DROPDOWN",
  "function": {
    "name": "Region Selector",
    "dataType": "string",
    "expression": "'North'"
  },
  "description": "Select a region to filter by",
  "values": [
    {"expression": {"value": "North", "exprType": "STRING_VALUE"}},
    {"expression": {"value": "South", "exprType": "STRING_VALUE"}},
    {"expression": {"value": "East", "exprType": "STRING_VALUE"}},
    {"expression": {"value": "West", "exprType": "STRING_VALUE"}}
  ]
}

community-domo-cli variables create 1810280719 --body-file variable.json --yes

CLI は次の処理を自動的に実行します。

1. 名前が一意であることを確認します
2. 埋め込みのコントロールを含む関数テンプレートを作成します
3. PUT /content/v1/variable/controls を使用してコントロールを登録します
4. カード定義を読み取ります
5. マージしてカードを保存します

---

トラブルシューティング

問題	原因	対処法
カードに変数が表示されない	いずれのビーストモードでも参照されていない	変数を使用するビーストモードを作成します
カードの保存で 400 が返される	PUT /content/v1/variable/controls の手順がない	カードを保存する前にコントロールを登録する必要があります
カードの保存で 400 が返される	subscriptions.main の dataSourceId	削除してください。dataSourceId は dataProvider にのみ指定します
カードの保存で 400 が返される	既存のコントロールがサーバーの完全な形式になっていない	カード定義に含まれる既存のコントロールを変更せずに saveOverride: true として渡します
500 内部データベースエラー	変数名が重複している	まず GET /query/v1/functions/variables/uniqueName で名前を確認します
検証結果が INVALID	式の構文が正しくない	文字列の引用符と、日付の関数構文を確認します
ダッシュボードに変数コントロールが表示されない	カードレベルのオーバーライドが反映されない	ダッシュボードレベルでコントロールを設定します
ダッシュボードの更新時に変数がリセットされる	想定どおりの動作	ページの読み込み時にダッシュボードコントロールは既定値にリセットされます

---

出力形式

ユーザー向けのコマンドを生成する場合は、次の内容を提示します。

1. 機能 — 変数について説明する1文
2. 変数の定義 — 名前、型、既定値、コントロールの種類、選択肢
3. 番号付きコマンド — 実行順に並べます（全3手順）。そのままコピーして貼り付けられます
4. 各レスポンスへの対応 — 特に、手順2で関数テンプレート ID を保存する方法
5. ビーストモードとの連携 — 変数を参照する数式を示します
6. 確認 — 実行後に Domo でカードを確認するよう伝えます