card-creation

Domo Card CRUD リファレンス

CLI と raw API の比較：カード操作にはすべて community-domo-cli を使用します。raw curl/fetch は不要です。CLI は Domo Product API エンドポイントをラップし、認証を自動的に処理します。

KPI カードをプログラムで管理するための完全なリファレンスです。207 種類のチャートタイプについて、オーバーライドデータとともに記載しています。206/207 種類で動作を確認済みです（badge_line のみ失敗します）。

---

1. CRUD 操作

カードを作成する

community-domo-cli --output json -y cards create \
  --body-file card.json --page-id $PAGE_ID > card_response.json

CARD_ID=$(python3 -c "import json; print(json.load(open('card_response.json'))['id'])")

作成時は --page-id が必須です。

カード定義を読み取る

community-domo-cli --output json cards definition $CARD_ID > card_def.json

definition、dataSourceWrite、drillpath、columns を返します。読み取り／書き込み形式の不一致については、「注意点」を参照してください。

カードを更新する

community-domo-cli --output json -y cards update $CARD_ID \
  --body-file card_updated.json

本文全体が置き換えられます。変更したフィールドだけでなく、すべてのフィールドを含めてください。必ず最初に読み取り、変更してから書き戻します。

カードをコピーする（raw API — CLI コマンドなし）

curl -X POST "https://$INSTANCE/api/content/v1/cards/$CARD_ID/copy" \
  -H "x-domo-developer-token: $TOKEN" -H "Content-Type: application/json" -d '{}'

カードを削除する（raw API — CLI コマンドなし）

curl -X DELETE "https://$INSTANCE/api/content/v1/cards/$CARD_ID" \
  -H "x-domo-developer-token: $TOKEN"

完全に削除され、元に戻すことはできません。

補助操作

# Discover dataset columns before creating cards
community-domo-cli --output json datasets schema $DATASET_ID > schema.json

# List cards on a page
community-domo-cli --output json pages list-cards $PAGE_ID

# Add an existing card to another page (goes to appendix)
community-domo-cli -y pages add-card $PAGE_ID $CARD_ID

# Create a beast mode / variable
community-domo-cli --output json -y beast-modes create --body-file beastmode.json

---

2. 完全な本文スキーマ

CREATE および UPDATE 操作で必要となる正確な構造です。

{
  "definition": {
    "subscriptions": {
      "big_number": {
        "name": "big_number",
        "columns": [
          {
            "column": "Revenue",
            "aggregation": "SUM",
            "alias": "Revenue",
            "format": {"type": "abbreviated", "format": "#A"}
          }
        ],
        "filters": []
      },
      "main": {
        "name": "main",
        "columns": [
          {"column": "Team", "mapping": "ITEM"},
          {"column": "Revenue", "mapping": "VALUE", "aggregation": "SUM"}
        ],
        "filters": [],
        "orderBy": [],
        "groupBy": [{"column": "Team"}],
        "fiscal": false,
        "projection": false,
        "distinct": false
      }
    },
    "formulas": {
      "dsUpdated": [],
      "dsDeleted": [],
      "card": []
    },
    "annotations": {
      "new": [],
      "modified": [],
      "deleted": []
    },
    "conditionalFormats": {
      "card": [],
      "datasource": []
    },
    "controls": [],
    "segments": {
      "active": [],
      "create": [],
      "update": [],
      "delete": []
    },
    "charts": {
      "main": {
        "component": "main",
        "chartType": "badge_vert_bar",
        "overrides": {},
        "goal": null
      }
    },
    "dynamicTitle": {
      "text": [{"text": "My Card Title", "type": "TEXT"}]
    },
    "dynamicDescription": {
      "text": [{"text": "Card description here", "type": "TEXT"}],
      "displayOnCardDetails": true
    },
    "chartVersion": "12",
    "inputTable": false,
    "noDateRange": false,
    "title": "My Card Title",
    "description": "Card description here"
  },
  "dataProvider": {
    "dataSourceId": "DATASET_UUID_HERE"
  },
  "variables": true,
  "columns": false
}

フィールドごとのリファレンス

ルートレベル

フィールド	型	必須	説明
definition	object	はい	すべてのカード設定を含みます
dataProvider.dataSourceId	string	はい	データセット UUID。dsId ではなく、dataSourceId を使用してください！
variables	boolean	はい	true にする必要があります。
columns	boolean	はい	false にする必要があります。

definition.subscriptions.big_number

カード上部のサマリー数値を制御します。常に必須ですが、カード自体に数値が表示される badge_singlevalue では、columns は空にしてください。

フィールド	型	説明
name	string	常に "big_number"
columns	array	badge_singlevalue では空の []。それ以外のすべてのタイプでは、最初の VALUE 列です。
columns[].column	string	列名（データセット列の場合）
columns[].formulaId	string	Beast mode ID（計算フィールドの場合）
columns[].aggregation	string	SUM、AVG、COUNT、MIN、MAX
columns[].alias	string	表示名
columns[].format	object	{"type": "abbreviated", "format": "#A"}
filters	array	big_number では常に []

definition.subscriptions.main

フィールド	型	説明
name	string	常に "main"
columns	array	マッピングを含むすべての列定義（セクション 3 を参照）
filters	array	フィルターオブジェクト
orderBy	array	並べ替え定義
groupBy	array	ITEM 列と SERIES 列から自動生成されます：[{"column": "Name"}]
fiscal	boolean	デフォルトは false
projection	boolean	デフォルトは false
distinct	boolean	デフォルトは false

フィルターオブジェクトの構造：

{
  "column": "Type",
  "values": ["New Business"],
  "filterType": "LEGACY",
  "operand": "IN"
}

definition.formulas

フィールド	型	説明
dsUpdated	array	更新されたデータセットレベルの数式
dsDeleted	array	削除されたデータセットレベルの数式
card	array	カードレベルの Beast mode（セクション 4 を参照）

definition.charts.main

フィールド	型	説明
component	string	常に "main"
chartType	string	207 種類のいずれか（セクション 5 を参照）
overrides	object	チャートのスタイル設定のオーバーライド（値はすべて文字列）
goal	null/object	目標線の設定

definition.conditionalFormats — オブジェクト必須

{"card": [], "datasource": []}

definition.segments — オブジェクト必須

{"active": [], "create": [], "update": [], "delete": []}

definition.dynamicTitle / dynamicDescription

{
  "text": [{"text": "Title goes here", "type": "TEXT"}]
}

dynamicDescription には "displayOnCardDetails": true も設定します。

その他の定義フィールド

フィールド	型	デフォルト	説明
chartVersion	string	"12"	チャートのレンダリングバージョン
inputTable	boolean	false	カードが入力テーブルかどうか
noDateRange	boolean	false	日付範囲によるフィルタリングを無効にします
title	string	--	プレーンテキストのタイトル（dynamicTitle も設定します）
description	string	--	プレーンテキストの説明

---

3. 列のマッピング

マッピングの種類

マッピング	視覚的な役割	必須	説明
ITEM	X 軸／カテゴリ	はい（ほとんどのチャート）	ディメンション／カテゴリ軸
VALUE	Y 軸／メジャー	はい	測定対象の数値
SERIES	色／凡例	いいえ	データを色付きの系列にグループ化します

列オブジェクトの構造

データセット列の場合：

{
  "column": "Team",
  "mapping": "ITEM",
  "aggregation": "SUM",
  "alias": "Team Name",
  "format": {"type": "number", "format": "###,##0"}
}

ビーストモード列の場合：

{
  "formulaId": "calculation_123456",
  "mapping": "VALUE",
  "aggregation": "SUM",
  "alias": "Win Rate %"
}

フィールドリファレンス

フィールド	必須	説明
column	はい*	データセットの列名
formulaId	はい*	ビーストモードのレガシー ID（計算フィールドでは column の代わりに使用）
mapping	はい	ITEM、VALUE、または SERIES
aggregation	いいえ	SUM、AVG、COUNT、MIN、MAX、UNIQUE
alias	いいえ	表示名の上書き
format	いいえ	数値／日付の書式設定オブジェクト

*column または formulaId のいずれかが必要です。

チャートの種類別の例

棒グラフ（カテゴリ＋メジャー）：

[
  {"column": "Region", "mapping": "ITEM"},
  {"column": "Revenue", "mapping": "VALUE", "aggregation": "SUM"}
]

積み上げ棒グラフ（カテゴリ＋メジャー＋系列）：

[
  {"column": "Region", "mapping": "ITEM"},
  {"column": "Revenue", "mapping": "VALUE", "aggregation": "SUM"},
  {"column": "Product Line", "mapping": "SERIES"}
]

単一値（メジャーのみ）：

[
  {"column": "Revenue", "mapping": "VALUE", "aggregation": "SUM", "alias": "Total Revenue"}
]

テーブル（複数の項目）：

[
  {"column": "Name", "mapping": "ITEM"},
  {"column": "Department", "mapping": "ITEM"},
  {"column": "Revenue", "mapping": "VALUE", "aggregation": "SUM"},
  {"column": "Deals", "mapping": "VALUE", "aggregation": "COUNT"}
]

groupBy の自動生成

すべての ITEM 列と SERIES 列から groupBy を作成します：

group_by = []
for c in columns:
    if c.get("mapping") in ("ITEM", "SERIES") and "column" in c:
        group_by.append({"column": c["column"]})

---

4. ビーストモード

カードレベルとデータセットレベル

スコープ	保存先	可視性	参照方法
カードレベル	definition.formulas.card[]	このカードのみ	カードの本文にインラインで含めます
データセットレベル	API 経由で作成	そのデータセットを使用するすべてのカード	formulaId で参照します

ビーストモードの作成（データセットレベル）

community-domo-cli --output json -y beast-modes create \
  --body-file beastmode.json > bm_response.json

本文：

{
  "name": "Revenue per Deal",
  "owner": 705231757,
  "locked": false,
  "global": false,
  "expression": "SUM(`Distinct Closed Won ACV`) / COUNT(`Opportunity ID`)",
  "links": [
    {
      "resource": {"type": "DATA_SOURCE", "id": "DATASET_UUID"},
      "visible": true,
      "active": false,
      "valid": "VALID"
    }
  ],
  "aggregated": true,
  "analytic": false,
  "nonAggregatedColumns": [],
  "dataType": "DECIMAL",
  "status": "VALID",
  "cacheWindow": "non_dynamic",
  "columnPositions": [],
  "functions": [],
  "functionTemplateDependencies": [],
  "archived": false,
  "hidden": false,
  "variable": false
}

レスポンスには id（UUID）と legacyId が含まれます。カード列では legacyId を formulaId として使用してください。

dataType のオプション

値	用途
DECIMAL	通貨、パーセンテージ、比率（デフォルト）
LONG	整数、カウント
DOUBLE	高精度の小数
STRING	テキスト／カテゴリの結果
DATE	日付計算

---

5. チャートタイプ一覧

22 グループにわたる 207 種類のチャートタイプがあります。以下の一覧から badge_* 形式のタイプ文字列を選び、対応するリファレンスファイルで上書きの詳細を確認してください。

作成時に HTTP 400 を返すのは badge_line のみです。代わりに badge_two_trendline または badge_spark_line を使用してください。 | Group | Count | Types | Reference | |-------|-------|-------|-----------| | Bar | 24 | badge_vert_bar, badge_horiz_bar, badge_vert_stackedbar, badge_horiz_stackedbar, badge_vert_multibar, badge_horiz_multibar, badge_vert_nestedbar, badge_horiz_nestedbar, badge_vert_percentbar, badge_horiz_percentbar, badge_vert_100pct, badge_horiz_100pct, badge_vert_dual_stackedbar, badge_horiz_dual_stackedbar, badge_vert_rtbar, badge_horiz_rtbar, badge_vert_rtmultibar, badge_horiz_rtmultibar, badge_vert_rtstackedbar, badge_horiz_rtstackedbar, badge_vert_bar_overlay, badge_horiz_bar_overlay, badge_vert_symbol, badge_spark_bar | references/bar.md | | Line | 16 | badge_trendline, badge_two_trendline, badge_curvedline, badge_stepline, badge_symbolline, badge_rttrendline, badge_stackedtrend, badge_variance_line, badge_spark_line, badge_curved_symbolline, badge_horiz_trendline, badge_horiz_curvedline, badge_horiz_stepline, badge_horiz_symbolline, badge_horiz_curved_symbolline, badge_horiz_stackedtrend | references/line.md | | Combo | 18 | badge_line_bar, badge_line_stackedbar, badge_line_clusterbar, badge_vert_bar_line, badge_horiz_bar_line, badge_curved_line_bar, badge_curved_line_stackedbar, badge_horiz_line_bar, badge_horiz_line_clusterbar, badge_horiz_line_stackedbar, badge_vert_100pct_linebar, badge_horiz_100pct_linebar, badge_vert_nested_linebar, badge_horiz_nested_linebar, badge_symbol_bar, badge_symbol_stackedbar, badge_horiz_symbol_bar, badge_horiz_symbol_stackedbar | references/barline.md | | Area + Dot Plot | 26 | badge_vert_area_overlay, badge_horiz_area_overlay, badge_vert_100pct_area, badge_horiz_100pct_area, badge_vert_curved_area_overlay, badge_horiz_curved_area_overlay, badge_vert_curved_stacked_area, badge_horiz_curved_stacked_area, badge_vert_curved_100pct_area, badge_horiz_curved_100pct_area, badge_vert_step_area_overlay, badge_horiz_step_area_overlay, badge_vert_step_stacked_area, badge_horiz_step_stacked_area, badge_vert_step_100pct_area, badge_horiz_step_100pct_area, badge_vert_dotplot_overlay, badge_horiz_dotplot_overlay, badge_vert_multi_dotplot, badge_horiz_multi_dotplot, badge_vert_stacked_dotplot, badge_horiz_stacked_dotplot, badge_vert_line_multi_dotplot, badge_horiz_line_multi_dotplot, badge_vert_line_stacked_dotplot, badge_horiz_line_stacked_dotplot | references/area.md | | Pie / Donut / Rose | 5 | badge_pie, badge_donut, badge_nautilus, badge_nautilus_donut, badge_nightingale_rose | references/pie.md | | Tables | 5 | badge_basic_table, badge_pivot_table, badge_flex_table, badge_table, badge_heatmap_table | references/table.md | | Gauges + Multi-Value | 16 | badge_singlevalue, badge_filledgauge, badge_gauge, badge_facegauge, badge_shapegauge, badge_compgauge, badge_compfillgauge_basic, badge_compfillgauge_adv, badge_progressbar, badge_radial_progress, badge_multi_radial_progress, badge_in_range_gauge, badge_imagegauge, badge_bullet, badge_multi_value, badge_multi_value_cols | references/gauge.md | | Maps | 42 | badge_world_map, badge_map, badge_map_us_state, badge_map_us_county, badge_map_latlong, badge_map_latlong_route, + 36 country maps | references/map.md | | Specialty | 16 | badge_treemap, badge_funnel, badge_funnel_bars, badge_funnel_swing, badge_waffle, badge_word_cloud, badge_stream, badge_stream_funnel, badge_slope, badge_bump, badge_pareto, badge_heatmap, badge_gantt, badge_gantt_dep, badge_gantt_percent, badge_calendar | references/specialty.md | | Data Science | 6 | badge_ds_forecasting, badge_ds_outliers, badge_ds_pred_modeling, badge_ds_spc, badge_correlation_matrix, badge_confusion_matrix | references/data-science.md | | Period over Period | 13 | badge_pop_trendline, badge_pop_trendline_var, badge_pop_rttrendline, badge_pop_bar_line, badge_pop_bar_line_var, badge_pop_line_bar, badge_pop_line_bar_var, badge_pop_vert_multibar, badge_pop_filledgauge, badge_pop_shapegauge, badge_pop_multi_value, badge_pop_progressbar, badge_pop_flex_table | references/period-over-period.md | | Statistical | 8 | badge_vert_histogram, badge_horiz_histogram, badge_vert_boxplot, badge_horiz_boxplot, badge_vert_waterfall, badge_horiz_waterfall, badge_xy_line, badge_xybubble | references/statistical.md | | Selectors | 6 | badge_checkbox_selector, badge_date_selector, badge_dropdown_selector, badge_radio_selector, badge_range_selector, badge_slicer | references/selector.md | | Text + Small Charts | 6 | badge_textbox, badge_dynamic_textbox, badge_vert_marimekko, badge_horiz_marimekko, badge_vert_facetedbar, badge_horiz_facetedbar | references/small-charts.md |

---

共通のオーバーライドカテゴリ

ほとんどのチャートタイプでは、次の標準オーバーライドカテゴリを共有します。

カテゴリ	目的	主なオーバーライド
general	フォント、並べ替え、制限	default_font_family、font_size（Smaller/Larger/Largest）、total_sort、display_limit、hide_interactivity、disable_animation
legend	凡例の位置とスタイル	lrg_legend_position（Top/Bottom/Hide）、details_legend_position、legend_font_family
bar_settings	棒の幅／高さ	width_percentage、fixed_bar_width、allow_wide_bars
grid_lines	グリッド、ゼロ線、計算線	hide_value_gridlines、grid_line_color、zero_line_color、calculated_line（Median/Average）
data_label_settings	チャート上の値ラベル	show_data_label（Always/Always - Rotated）、datalabel_position、datalabel_fnt_clr、decimal_places_dl
value_scale_y	Y軸の書式設定	title_y、label_format_y（Number/Currency/Percentage）、divide_value_scale_by_y、value_scale_min、value_scale_max、log_scale_y
category_scale_x	X軸の書式設定	title_x、cat_scale_show_labels、cat_scale_manual_rotate、max_label_length、never_use_time_scale
hover_text_settings	ツールチップの書式設定	hover_text、hover_format、decimal_places_hvr
number_format	通貨／小数の設定	currency_symbol、currency_sym_position、decimal_separator、thousands_separator
gradient_colors	グラデーションカラー	use_gradient_colors、gradient_start_fill_color、gradient_end_fill_color、gradient_by_value
scale_marker	参照線／範囲	sm_type（Line/Range/Quantiles）、sm_val_type、sm_value、sm_line_color
colors	系列の色	series_1_color（16進数文字列）

オーバーライド値の型

型	形式	例
boolean	"true"または"false"（文字列として）	"use_gradient_colors": "true"
string	自由形式のテキストまたは16進数の色	"gradient_start_fill_color": "#99CCEEFF"
float	文字列としての数値	"display_limit": "10"
select_list	定義済みの値のいずれか	"font_size": "Largest"

すべてのオーバーライド値は文字列です。ブール値や数値も同様です。

---

6. 条件付き書式

構造は配列ではなく、オブジェクトでなければなりません。

"conditionalFormats": {
  "card": [
    {
      "type": "COLOR",
      "column": "Revenue",
      "rules": [
        {"min": 0, "max": 50000, "color": "#FF0000", "label": "Below Target"},
        {"min": 50000, "max": 100000, "color": "#FFAA00", "label": "Near Target"},
        {"min": 100000, "color": "#00AA00", "label": "Above Target"}
      ]
    }
  ],
  "datasource": []
}

conditionalFormatsに{card:[], datasource:[]}ではなく配列[]を渡すと、HTTP 400が発生します。読み取り時にはDomo UIから配列として返されるため、書き込む前にオブジェクトに変換してください。

---

7. 注意点

重大 — 失敗の原因になります

注意点	詳細
dataProvider.dataSourceIdであり、dsIdではありません	フィールド名はdataSourceIdです。dsIdを使うと、エラーなしで失敗します。
ルートにvariables: trueが必要です	ルートレベルに含める必要があります。
ルートにcolumns: falseが必要です	ルートレベルに含める必要があります。
両方のサブスクリプションが必要です	big_numberとmainの両方を含める必要があります。どちらかが欠けるとHTTP 400が発生します。
conditionalFormatsはオブジェクトでなければなりません	{"card":[], "datasource":[]}。[]を渡すとHTTP 400が発生します。
segmentsはオブジェクトでなければなりません	{"active":[], "create":[], "update":[], "delete":[]}。[]を渡すとHTTP 400が発生します。
badge_lineは失敗します	常にHTTP 400が返されます。badge_two_trendlineまたはbadge_spark_lineを使用してください。
CREATEには--page-idが必要です	cards create --page-id $PAGE_ID — 必須です。
UPDATEではpage-idを使用しません	cards update $CARD_ID — カードIDのみです。

重要 — 動作に影響します

注意点	詳細
上書き値は文字列です	ブール値（"true"）や数値（"10"）も文字列にする必要があります。
UPDATE は定義全体を置き換えます	全体が置き換えられます。最初に読み取り、変更してから書き戻してください。
READ→WRITE の形式の不一致	更新前に修正してください：formulas（読み取り=[]、書き込み={"dsUpdated":[],"dsDeleted":[],"card":[]}）、conditionalFormats（読み取り=[]、書き込み={"card":[],"datasource":[]}）、annotations（読み取り=[]、書き込み={"new":[],"modified":[],"deleted":[]}）、segments（読み取り={"active":[],"definitions":[]}、書き込み={"active":[],"create":[],"update":[],"delete":[]}）。また、存在しない場合は title、description、noDateRange を追加し、modified、allowTableDrill を削除してください。
groupBy の自動生成	すべての ITEM 列と SERIES 列から構築してください。これを省略すると、グループ化されず、すべての値が 1 つに集計されます。
singlevalue には big_number	badge_singlevalue では、big_number に columns: [] が必要です。その他のタイプでは、最初の VALUE 列を指定します。
PoP カードには dateRangeFilter が必要です	次の条件を満たさない場合、badge_pop_* カードの比較値は「0」になります：メインに mapping:"ITEM"、aggregation:"MAX" を指定した日付列があること、dateTimeRange と periods を含む dateRangeFilter があること、time_period のサブスクリプションがあること。periods を追加する前に dateGrain を削除してください（互いに競合します）。
セレクターカードには big_number の列が必要です	big_number.columns が空の場合、400 {"message":"big_number subscription missing select columns"} が発生します。ドロップダウンではフィルター列に COUNT を、日付セレクターでは MAX を使用してください。

---

クイックリファレンス

CREATE:  cards create --body-file card.json --page-id PAGE_ID
READ:    cards definition CARD_ID
UPDATE:  cards update CARD_ID --body-file card.json
COPY:    POST /content/v1/cards/CARD_ID/copy  (raw API)
DELETE:  DELETE /content/v1/cards/CARD_ID      (raw API)

Required root: variables=true, columns=false
Required data: dataProvider.dataSourceId (NOT dsId)
Required subs: big_number AND main
conditionalFormats: {card:[], datasource:[]}  (OBJECT)
segments:           {active:[], create:[], update:[], delete:[]}  (OBJECT)

Line charts: badge_two_trendline (NOT badge_line)
Total types: 207 (206 work, badge_line fails)