alibabacloud-dataworks-datastudio-develop

DataWorks データ開発

❗ 5 秒でわかる概要 — まずはこちらをお読みください

認証情報：最初に aliyun configure list を実行してください。CLI はほとんどの場合、事前に設定されています（STS トークン）。認証情報ファイルは検索しないでください。CLI の設定を確認するだけで十分です。

最初にプラグインをインストール：aliyun plugin install --names dataworks-public を実行してください。すべてのコマンドでプラグインモード（ケバブケース）を使用します：aliyun dataworks-public create-node ...

API：create-workflow-definition → create-node（ノードごと）→ create-pipeline-run（デプロイ）。更新の場合：update-node → create-pipeline-run。deploy-file、submit-file、create-file、create-business は絶対に使用しないでください。

FlowSpec：以下の「クイックスタート」セクションにある JSON をそのままコピーしてください。形式を推測しないでください。version は "2.0.0"、kind は "CycleWorkflow" または "Node" です。よくある誤った値：apiVersion、type、Workflow、metadata — いずれも誤りです。

更新後に公開：update-node → create-pipeline-run(type=Online) → get-pipeline-run をポーリング → exec-pipeline-run-stage。deploy-file は機能しません。

⚡ 必須：API 呼び出しの前にお読みください

これらの絶対的なルールは任意ではありません。いずれかに違反すると、タスクは必ず失敗します。

事前確認：Aliyun CLI 3.3.3 以上が必要です

aliyun version を実行して、3.3.3 以上であることを確認してください。インストールされていない場合、またはバージョンが古い場合は、 curl -fsSL --connect-timeout 10 --max-time 120 https://aliyuncli.alicdn.com/setup.sh | bash を実行して更新するか、 インストール手順について references/cli-installation-guide.md を参照してください。

Aliyun CLI のセットアップ（初回使用前に実行）：

# Plugin install (required)
aliyun plugin install --names dataworks-public
# Plugin update (run periodically)
aliyun plugin update --names dataworks-public
# AI-Mode: available commands are enable/disable/set-user-agent
# This skill DISABLES AI-Mode (exact parameter control required)
aliyun configure ai-mode disable
# Do NOT run: aliyun configure ai-mode enable
# Set user-agent for tracking
aliyun configure ai-mode set-user-agent AlibabaCloud-Agent-Skills/alibabacloud-dataworks-datastudio-develop

コマンドごとの UA フラグ（ビジネスコマンドのみ）：すべての aliyun dataworks-public の呼び出しに --user-agent AlibabaCloud-Agent-Skills/alibabacloud-dataworks-datastudio-develop を追加する必要があります。

0. 最初に行うこと：CLI の認証情報を確認します。 aliyun コマンドを実行する前に、必ず aliyun configure list を実行してください。CLI には通常、有効な STS トークン認証情報が事前設定されています。確認する前に認証情報ファイル（例：testconfig.json）を検索しないでください。aliyun configure list に有効なプロファイルが表示された場合は、そのまま使用してください。複数のプロファイルがある場合は、aliyun configure switch --profile <name> を実行して適切なものを選択してください。優先順位：名前に dataworks を含むプロファイル（大文字小文字を区別しない）を優先し、それ以外の場合は default を使用します。この手順を省略しないでください。切り替え前に aliyun dataworks-public コマンドを実行しないでください。AK/SK の値を読み取ったり、エコーしたり、表示したりすることは絶対にしないでください。
1. 初回使用前にプラグインをインストールします。 aliyun plugin install --names dataworks-public を実行してください。すでにインストールされている場合は、最新バージョンを確実に使用するため、aliyun plugin update --names dataworks-public を実行してください。このプラグインは、必要な呼び出し形式であるケバブケースのコマンド（create-node、create-workflow-definition など）を提供します。
2. プラグインモード（ケバブケース）のみを使用します。 DataWorks API の呼び出しはすべて、aliyun dataworks-public create-node --project-id ... --spec '...' のような形式にしてください。PascalCase の RPC（CreateNode、CreateWorkflowDefinition）は使用せず、必ずプラグインモードを使用してください。
3. 作成には、以下のコマンドのみを使用します： create-workflow-definition → create-node（--container-id を指定してノードごとに実行）→ create-pipeline-run（デプロイ用）。
4. 更新には、以下のコマンドのみを使用します： update-node（増分更新、kind:Node）→ create-pipeline-run（デプロイ用）。更新や公開に import-workflow-definition、deploy-file、submit-file は使用しないでください。 4a. デプロイ／公開には、以下のコマンドのみを使用します： create-pipeline-run --type Online --object-ids <ID> → get-pipeline-run --id <PipelineRunId>（ポーリング）→ exec-pipeline-run-stage --id <PipelineRunId> --code <StageCode>（次へ進む）。deploy-file、submit-file、list-deployment-packages、get-deployment-package は絶対に使用しないでください。これらはすべて旧式 API であり、失敗します。⚠️ --object-ids はスペース区切りの ID のみです（例：--object-ids 7567482277219412494）。JSON 配列文字列ではありません。'["ID"]' のように囲むと、CLI が角括弧を含む文字列をそのまま ID として渡すため、未找到发布对象: [["ID"]] が返されます。
5. create-workflow-definition または create-node がエラーを返した場合は、仕様を修正してください。従来の API にフォールバックしてはいけません。 エラー 58014884415 / 0x5083000000000005（「Spec JSON parse failed」）は、FlowSpec JSON の形式が間違っていることを意味します（例："kind":"CycleWorkflow" ではなく "kind":"Workflow" を使用した、"version" ではなく "apiVersion" を使用した、または {"version":"2.0.0","kind":"Node","spec":{"nodes":[...]}} 形式ではなく、フラットな {"type":"SHELL","content":"..."} 形式を使用した）。推測をやめて、以下のクイックスタートから正確な仕様をコピーし、必要な値だけを変更してください。
6. CLI コマンドは直接実行してください。ラッパースクリプトを作成してはいけません。 API 呼び出しをまとめるための .sh スクリプトは決して作成しないでください。各 aliyun コマンドをシェルで直接実行してください。ラッパースクリプトは複雑さを増し、エラーを分かりにくくします。
7. ファイルをローカルに保存しただけでは完了ではありません。 API が成功応答（例：create-workflow-definition／create-node からの {"Id": "..."}）を返した場合にのみ、タスクは完了です。API を呼び出さずに JSON ファイルをディスクに書き込んでも、ワークフロー／ノードは作成されていません。実際の API 応答なしに、成功したと主張してはいけません。
8. API 応答をシミュレート、モック、または捏造してはいけません。 認証情報が不足している、CLI の設定に誤りがある、または API 呼び出しがエラーを返した場合は、エラーメッセージを正確にユーザーに伝え、停止してください。偽の JSON 応答を生成したり、シミュレーション文書を作成したり、ハードコードされた出力を表示したり、何らかの形で成功したと主張したりしてはいけません。成功をシミュレートするより、明確に失敗を伝えるほうが重要です。
9. 認証情報のエラーが発生したら、直ちに停止してください。 aliyun configure list に認証情報が表示されない、または無効な認証情報が表示される場合、あるいは CLI 呼び出しで InvalidAccessKeyId、access_key_id must be assigned などの認証エラーが返された場合は、直ちに停止してください。このセッションの外で有効な認証情報を設定するよう、ユーザーに伝えてください。回避策（config.json を手動で書き込む、プレースホルダーの認証情報を使う、認証なしで続行するなど）を試してはいけません。認証情報が有効に機能することを確認するまで、その後の API 呼び出しを行ってはいけません。
10. このドキュメントに記載された API だけを使用してください。 呼び出す API はすべて、以下の API クイックリファレンステーブルに記載されている必要があります。必要な操作が記載されていない場合は、テーブルを再確認してください。別の名前で記載されている可能性があります。API 名を決して捏造してはいけません（例：CreateDeployment、ApproveDeployment、DeployNode は存在しません）。適切な API が見つからない場合は、ユーザーに尋ねてください。

以下の従来のコマンドをひとつでも入力しそうになったら、直ちに停止し、以下のクイックスタートを読み直してください： create-file、create-business、create-folder、--file-type、/bizroot、/workflowroot、deploy-file、submit-file、list-files、get-file、list-deployment-packages、get-deployment-package、create-deployment、approve-deployment、deploy-node、create-flow、create-file-depends、create-schedule

⚠️ FlowSpec のアンチパターン

エージェントは、間違った FlowSpec フィールドをよく作り出します。正しい形式は以下のクイックスタートに示されています。

❌ 間違い	✅ 正しい	備考
"apiVersion": "v1" または "apiVersion": "dataworks.aliyun.com/v1"	"version": "2.0.0"	FlowSpec では apiVersion ではなく version を使用します
"kind": "Flow" または "kind": "Workflow"	"kind": "CycleWorkflow"（ワークフローの場合）または "kind": "Node"（ノードの場合）	有効なのは Node、CycleWorkflow、ManualWorkflow のみです。"Workflow" 単独は無効です
"metadata": {"name": "..."}	"spec": {"workflows": [{"name": "..."}]}	FlowSpec に metadata フィールドはありません。名前は spec.workflows[0] または spec.nodes[0] の中に指定します
"type": "SHELL"（ノードレベル）	"script": {"runtime": {"command": "DIDE_SHELL"}}	ノードタイプは script.runtime.command に指定します
"schedule": {"cron": "..."}	"trigger": {"cron": "...", "type": "Scheduler"}	スケジュールには schedule ではなく trigger を使用します
path のない "script": {"content": "..."}	"script": {"path": "node_name", ...}	script.path は常に必須です

🚀 クイックスタート：エンドツーエンドのワークフロー作成

動作する完全な例 — 依存関係のある2つのノードを含むスケジュール済みワークフローを作成します。

# Step 1: Create the workflow container
aliyun dataworks-public create-workflow-definition \
  --project-id 585549 \
  --spec '{"version":"2.0.0","kind":"CycleWorkflow","spec":{"workflows":[{"name":"my_etl_workflow","script":{"path":"my_etl_workflow","runtime":{"command":"WORKFLOW"}}}]}}' \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-dataworks-datastudio-develop
# → Returns {"Id": "WORKFLOW_ID", ...}

# Step 2: Create upstream node (Shell) inside the workflow
# IMPORTANT: Before creating, verify output name "my_project.check_data" is not already used by another node (list-nodes)
aliyun dataworks-public create-node \
  --project-id 585549 \
  --scene DATAWORKS_PROJECT \
  --container-id WORKFLOW_ID \
  --spec '{"version":"2.0.0","kind":"Node","spec":{"nodes":[{"name":"check_data","id":"check_data","script":{"path":"check_data","runtime":{"command":"DIDE_SHELL"},"content":"#!/bin/bash\necho done"},"outputs":{"nodeOutputs":[{"data":"my_project.check_data","artifactType":"NodeOutput"}]}}]}}' \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-dataworks-datastudio-develop
# → Returns {"Id": "NODE_A_ID", ...}

# Step 3: Create downstream node (SQL) with dependency on upstream
# NOTE on dependencies: "nodeId" is the CURRENT node's name (self-reference), "output" is the UPSTREAM node's output
aliyun dataworks-public create-node \
  --project-id 585549 \
  --scene DATAWORKS_PROJECT \
  --container-id WORKFLOW_ID \
  --spec '{"version":"2.0.0","kind":"Node","spec":{"nodes":[{"name":"transform_data","id":"transform_data","script":{"path":"transform_data","runtime":{"command":"ODPS_SQL"},"content":"SELECT 1;"},"outputs":{"nodeOutputs":[{"data":"my_project.transform_data","artifactType":"NodeOutput"}]}}],"dependencies":[{"nodeId":"transform_data","depends":[{"type":"Normal","output":"my_project.check_data"}]}]}}' \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-dataworks-datastudio-develop

# Step 4: Set workflow schedule (daily at 00:30)
aliyun dataworks-public update-workflow-definition \
  --project-id 585549 \
  --id WORKFLOW_ID \
  --spec '{"version":"2.0.0","kind":"CycleWorkflow","spec":{"workflows":[{"name":"my_etl_workflow","script":{"path":"my_etl_workflow","runtime":{"command":"WORKFLOW"}},"trigger":{"cron":"00 30 00 * * ?","timezone":"Asia/Shanghai","type":"Scheduler"}}]}}' \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-dataworks-datastudio-develop

# Step 5: Deploy the workflow online (REQUIRED — workflow is not active until deployed)
aliyun dataworks-public create-pipeline-run \
  --project-id 585549 \
  --type Online --object-ids WORKFLOW_ID \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-dataworks-datastudio-develop
# → Returns {"Id": "PIPELINE_RUN_ID", ...}
# Then poll get-pipeline-run and advance stages with exec-pipeline-run-stage
# (see "Publishing and Deploying" section below for full polling flow)

重要なパターン：create-workflow-definition → create-node（--container-id と outputs.nodeOutputs を指定）→ update-workflow-definition（トリガーを追加）→ create-pipeline-run（デプロイ）。ワークフロー内の各ノードには outputs.nodeOutputs が MUST です。ワークフローは create-pipeline-run でデプロイするまでアクティブになりません。

依存関係の接続の概要：spec.dependencies では、nodeId は現在のノード自身の名前（自己参照であり、上流ノードではありません）で、depends[].output は上流ノードの出力（projectIdentifier.upstream_node_name）です。上流ノードの outputs.nodeOutputs[].data の値と、下流ノードの depends[].output の値は、文字単位で完全に一致している必要があります。一致しない場合、依存関係は通知されずに失敗します。

コアワークフロー

環境の確認（作成前に必須）

ステップ 0 — CLI の認証情報を確認する（必ず最初に実行すること）： aliyun configure list を実行します。CLI はほとんどの場合、STS トークン認証情報で事前設定されています。このコマンドを実行する前に、「認証情報がありません」と主張したり、認証情報ファイルを探したりしないでください。 出力に Valid プロファイルが表示されていれば、有効な認証情報があるため、すぐに続行します。複数のプロファイルがある場合は、aliyun configure switch --profile <name> を実行します（dataworks という名前のプロファイルを優先し、それ以外は default を使用します）。この手順の前に aliyun dataworks-public コマンドを実行してはいけません。

認証情報が空または無効な場合は、ここで停止してください。 API 呼び出しを続行しないでください。エラーをユーザーに報告し、このセッションの外で有効な認証情報を設定するよう指示してください（aliyun configure または環境変数を使用）。設定ファイルを手動で書き込んだり、プレースホルダー値を使用したりするなどの回避策を試みないでください。

ノードやワークフローを作成する前に、プロジェクトの既存環境を把握してください。クエリの実行にはサブエージェントの使用を推奨します。生データによってコンテキストを使いすぎないよう、メインエージェントには要約のみを返してください。

サブエージェントのタスク：

1. list-workflow-definitions を呼び出して、ワークフロー一覧を取得する
2. list-nodes を呼び出して、既存のノード一覧を取得する
3. list-data-sources および list-compute-resources を呼び出して、利用可能なすべてのデータソースとコンピューティングエンジンのバインディング（EMR、Hologres、StarRocks など）を取得する。list-compute-resources は、コンピューティングエンジン型のリソースが返されない場合がある list-data-sources を補完します
4. 要約を返す（生データは返さない）：
   • ワークフロー一覧：名前 + 含まれるノード数 + 種類（スケジュール実行／手動）
   • 現在のタスクに関連する既存ノード：名前 + 種類 + 親ワークフロー
   • 利用可能なデータソース + コンピューティングリソース（名前、種類）：両方の一覧を統合する
   • 推奨する対象ワークフロー（タスクの説明から推測できる場合）

要約に基づき、メインエージェントが対象ワークフロー（既存または新規、ユーザーが決定）、ノードの命名（既存の規則に従う）、依存関係（SQL 参照と既存ノードから推測）を決定します。

作成前の競合チェック（すべてのオブジェクト種別で必須）：

1. 名前の重複チェック：オブジェクトを作成する前に、対応する一覧コマンドを使って、同じ名前のオブジェクトがすでに存在するか確認します。
   • ワークフロー → list-workflow-definitions
   • ノード → list-nodes（ノード名はプロジェクト内で一意です）
   • リソース → list-resources
   • 関数 → list-functions
   • コンポーネント → list-components
2. 既存オブジェクトへの対応：ユーザーに状況を伝え、どのように進めるかを確認します（既存のものを使用／名前を変更／既存のものを更新）。既存オブジェクトを直接削除することは禁止されています。
3. 出力名の競合チェック（重要）：ノードの outputs.nodeOutputs[].data（形式：${projectIdentifier}.NodeName）は、異なるワークフロー間でも、プロジェクト内で一意でなければなりません。list-nodes --name NodeName を使用し、応答の Outputs.NodeOutputs[].Data を確認して検証してください。既存ノードと出力名が競合する場合は、作成前に必ず解決してください。解決しないと、デプロイ時に "can not exported multiple nodes into the same output" というエラーが発生します（troubleshooting.md #11b を参照）。

確実性のレベルに応じた対応方法：

• 確かな情報 → そのまま使用し、ユーザーに確認しない
• 確度の高い推論 → そのまま進め、出力で推論の根拠を説明する
• 不確かな情報 → 必ずユーザーに確認する

ノードの作成

統一されたワークフロー：OpenAPI Mode と Git Mode のどちらでも、同じローカルファイル構成を生成します。

⚠️ API を呼び出す前に、必ずローカルファイルを作成してください OpenAPI Mode と Git Mode のどちらを使用する場合でも、まず完全なノードフォルダー（spec.json + コードファイル + dataworks.properties）をローカルに作成し、build.py による統合と validate.py による検証を済ませてから、create-node／create-workflow-definition コマンドを呼び出す必要があります。ローカルファイルの作成を省略して、API を直接呼び出して Spec を構築することは禁止されています。

ステップ 1：Node ディレクトリと 3 つのファイルを作成する

1 つのフォルダーが 1 つのノードに対応し、次の 3 つのファイルを含みます。

my_node/
├── my_node.spec.json          # FlowSpec node definition
├── my_node.sql                # Code file (extension based on contentFormat)
└── dataworks.properties       # Runtime configuration (actual values)

spec.json — references/nodetypes/{category}/{TYPE}.md から最小限の Spec をコピーし、name と path を変更します。properties の値を参照するには ${spec.xxx} プレースホルダーを使用します。ユーザーが trigger、dependencies、rerunTimes などを指定した場合は、それらも spec に追加します。

コードファイル — ノードタイプのドキュメントにある contentFormat に基づいて形式（sql/shell/python/json/empty）を判断し、extension フィールドに基づいて拡張子を判断します。

dataworks.properties — 実際の値を入力します。

projectIdentifier=<actual project identifier>
spec.datasource.name=<actual datasource name>
spec.runtimeResource.resourceGroup=<actual resource group identifier>

不確かな値は入力しないでください。省略した場合、サーバーはプロジェクトのデフォルト値を自動的に使用します。

参照例：assets/templates/

ステップ 2：送信する

デフォルトは OpenAPI です（ユーザーが明示的に「Git にコミット」と指定した場合を除きます）。

1. build.py を使用して 3 つのファイルを API 入力にマージします。

   python $SKILL/scripts/build.py ./my_node > /tmp/spec.json
   

   build.py は次の 3 つの処理を行います（サードパーティ依存関係はありません。エラーが発生した場合は、ソースコードを参照して手動で実行してください）。

   • dataworks.properties を読み込み、spec.json 内の ${spec.xxx} および ${projectIdentifier} プレースホルダーを置換します
   • コードファイル（DI の .json コードファイルを含む）を読み込み、プレースホルダーを置換して script.content に埋め込みます
   • マージ済みの完全な JSON を出力します

2. 送信前に spec を検証します。

   python $SKILL/scripts/validate.py ./my_node
   

3. 送信前の検証（必須） — create-node を呼び出す前に、必ず API を使って、以下の情報が存在し、正しいことを検証してください。

   環境の検証（初回送信前に 1 回実行）：

   • runtimeResource.resourceGroup — list-resource-groups を呼び出してリソースグループの存在を確認し、返されたリソースグループ ID（Serverless_res_group_... など）を使用してください。人が読める名前（cx_res_4 など）は使用しないでください。不確かな場合は省略し、サーバーにプロジェクトのデフォルト値を使用させてください
   • datasource — 計算エンジンノード（ODPS_SQL、HOLOGRES_SQL など）にはデータソースが必要です。list-data-sources または list-compute-resources を呼び出して、データソース名とタイプが一致することを確認してください。不確かな場合は省略し、サーバーにプロジェクトのデフォルト値を使用させてください

   Spec の内容確認（ノードごとの送信前）：

   • script.runtime.command が目的のノードタイプに一致していること（references/nodetypes/{category}/{TYPE}.md を確認してください）
   • script.content — コードノードでは、マージ後の spec に空でないコードが含まれていることを確認してください。特に DI ノードでは、script.content が有効な DIJob JSON 文字列であり、フラットなトップレベルキー type、version、steps、order、setting、extend を持つことを確認してください。これは従来の DataX 形式 {"job":{"content":[{"reader":{"plugin":...}}]}} ではありません。生成された内容にトップレベルの "job" ラッパーまたは content[].reader.plugin が含まれている場合は、学習時の記憶にある誤った形式を使用しています。CreateNode を呼び出す前に、references/nodetypes/data_integration/DI.md および DATAX.md に合わせて書き直してください
   • trigger — ワークフローノードの場合、ワークフローのスケジュールを継承するため省略してください。ユーザーがノードごとのスケジュールを明示的に指定した場合に限り設定します。単独ノードの場合は、ユーザーがスケジュールを指定した場合に設定します
   • outputs.nodeOutputs — ワークフローノードでは必須です。形式：{"data":"${projectIdentifier}.NodeName","artifactType":"NodeOutput"}。出力名がプロジェクト内で一意であることを確認してください（list-nodes --name）
   • dependencies — nodeId は現在のノード自身の名前（自己参照）でなければなりません。depends[].output は上流ノードの outputs.nodeOutputs[].data と完全に一致していなければなりません。すべてのワークフローノードには依存関係が必要です。ルートノード（上流ノードなし）は ${projectIdentifier}_root（ドットではなくアンダースコア）に依存しなければなりません。下流ノードは上流ノードの出力に依存します。dependencies エントリーのないワークフローノードは孤立ノードになります
   • 文書化されていないフィールドを追加していないこと — 上記の FlowSpec のアンチパターン表と照らし合わせ、references/flowspec-guide.md に記載されていないフィールドは削除してください

4. API を呼び出して送信します（references/api/CreateNode.md を参照してください）。

   aliyun dataworks-public create-node \
     --project-id $PROJECT_ID \
     --scene DATAWORKS_PROJECT \
     --spec "$(cat /tmp/spec.json)" \
     --user-agent AlibabaCloud-Agent-Skills/alibabacloud-dataworks-datastudio-develop
   

   注：dataworks-public プラグインが必要です（上記の Aliyun CLI のセットアップを参照してください）。コマンドが見つからない場合は、先にプラグインをインストールしてください。従来のコマンド（create-file/create-folder）は絶対に使用しないでください。 サンドボックスのフォールバック：$(cat ...) がブロックされる場合は、Python の subprocess.run(['aliyun', 'dataworks-public', 'create-node', '--project-id', str(PID), '--scene', 'DATAWORKS_PROJECT', '--spec', spec_str, '--user-agent', 'AlibabaCloud-Agent-Skills/alibabacloud-dataworks-datastudio-develop']) を使用してください。

5. ワークフロー内に配置するには、--container-id $WorkflowId を追加します

Git モード（ユーザーが明示的に要求した場合）：git add ./my_node && git commit を実行すると、DataWorks が自動的に同期してプレースホルダーを置き換えます

必須フィールド（実際に検証済み、130 種類以上すべてに共通）：

• name — ノード名
• id — name と同じ値に設定する必要があります。これにより、spec.dependencies[*].nodeId が一致します。id を明示的に指定しないと、API が依存関係を黙って破棄する場合があります
• script.path — スクリプトのパス。ノード名で終わる必要があります。サーバーがワークフローのプレフィックスを自動的に付加します
• script.runtime.command — ノードタイプ（例：ODPS_SQL、DIDE_SHELL）

コピーして使える最小限のノード Spec（Shell ノードの例）：

{"version":"2.0.0","kind":"Node","spec":{"nodes":[{
  "name":"my_shell_node","id":"my_shell_node",
  "script":{"path":"my_shell_node","runtime":{"command":"DIDE_SHELL"},"content":"#!/bin/bash\necho hello"}
}]}}

その他のフィールドは必須ではありません。サーバーがプロジェクトのデフォルト値を自動的に設定します：

• datasource, runtimeResource — 不明な場合は渡さないでください。サーバーがプロジェクトのデフォルト値を自動的にバインドします
• trigger — 渡さない場合は、ワークフローのスケジュールを引き継ぎます。ユーザーが指定した場合にのみ渡してください
• dependencies, rerunTimes など — ユーザーが指定した場合にのみ渡してください
• outputs.nodeOutputs — 単独ノードでは任意ですが、ワークフロー内のノードでは必須です（{"data":"${projectIdentifier}.NodeName","artifactType":"NodeOutput"}）。指定しないと、後続の依存関係が黙って失敗します。⚠️ 出力名（${projectIdentifier}.NodeName）はプロジェクト内で一意である必要があります。別のワークフローにあるノードも含め、別のノードが同じ出力名をすでに使用している場合、デプロイは「can not exported multiple nodes into the same output」というエラーで失敗します。作成前に必ず list-nodes で確認してください

ワークフローの作成

⚠️ ワークフローの作成でも、まずローカルファイルを作成する必要があります。 先にワークフロー内の各ノードのローカルフォルダー（spec.json + コードファイル + dataworks.properties）を作成し、検証に合格した後で API を順番に呼び出してください。初回のコミット前に、list-resource-groups、list-data-sources などのコマンドを使って、リソースグループやデータソースなどの環境情報が存在し、正しいことを確認する必要があります。ディレクトリ構成の詳細については、workflow-guide.md を参照してください。

1. ワークフロー定義を作成する（最小限の spec）：

   {"version":"2.0.0","kind":"CycleWorkflow","spec":{"workflows":[{
     "name":"workflow_name","script":{"path":"workflow_name","runtime":{"command":"WORKFLOW"}}
   }]}}
   

   create-workflow-definition を呼び出す → WorkflowId が返されます
2. 依存関係の順序に従ってノードを作成する（各ノードで --container-id WorkflowId を渡します）
   • 各ノードの作成前：${projectIdentifier}.NodeName がプロジェクト内の既存ノードの出力として使用されていないことを確認します（--name を指定して list-nodes を使用し、Outputs.NodeOutputs[].Data を確認してください）。出力名が重複すると、デプロイは失敗します
   • 各ノードの spec には outputs.nodeOutputs を必ず含めてください：{"data":"${projectIdentifier}.NodeName","artifactType":"NodeOutput"}
   • 後続ノードでは、spec.dependencies に依存関係を宣言します。nodeId = 現在のノード自身の名前（自己参照）、depends[].output = 上流ノードの出力（workflow-guide.md を参照）
3. 依存関係を確認する（全ノード作成後に必須） — 各後続ノードについて、list-node-dependencies --id <NodeID> を呼び出します。上流の依存関係があるはずなのに TotalCount が 0 の場合、create-node が依存関係を黙って破棄しています。spec.dependencies を使って、直ちに update-node で修正してください（下記の「依存関係の更新」を参照）。すべての依存関係が確認されるまで、デプロイに進まないでください
4. スケジュールを設定する — ユーザーがスケジュールを指定した場合は、trigger を指定して update-workflow-definition を実行します
5. オンラインでデプロイする（必須） — create-pipeline-run --type Online --object-ids <WorkflowId> を実行 → get-pipeline-run --id <PipelineRunId> をポーリング → exec-pipeline-run-stage --id <PipelineRunId> --code <StageCode> でステージを進めます。デプロイが完了するまで、ワークフローは有効になりません。 この手順を省略したり、ユーザーに手動で実行するよう伝えたりしないでください。

詳細なガイドと、コピーして使えるノード Spec の完全な例（出力と依存関係を含む）：references/workflow-guide.md

既存ノードの更新

増分更新を必ず使用してください — ノード ID と変更するフィールドのみを渡します：

{"version":"2.0.0","kind":"Node","spec":{"nodes":[{
  "id":"NodeID",
  "script":{"content":"new code"}
}]}}

⚠️ 重要：update-node では、ノードがワークフローに属している場合でも、必ず"kind":"Node"を使用します。"kind":"CycleWorkflow"は使用しないでください。これはワークフローレベルの操作（update-workflow-definition）専用です。

変更していないフィールド（datasource や runtimeResource など）は渡さないでください（サーバーが値を修正している場合があり、それらを渡し直すとエラーになることがあります）。

⚠️ 依存関係の更新：update-nodeでノードの依存関係を修正または変更するには、spec.dependenciesを使用します。例：

{"version":"2.0.0","kind":"Node","spec":{"nodes":[{"id":"NodeID"}],"dependencies":[{"nodeId":"current_node_name","depends":[{"type":"Normal","output":"project.upstream_node"}]}]}}

ワークフローの更新と再公開

既存ノードを変更し、その変更をデプロイする一連の流れです：

1. ノードを検索する — list-nodes(--name xxx) → Node ID を取得
2. ノードを更新する — 増分 spec（kind:Node、idと変更したフィールドのみ）を指定してupdate-nodeを実行
3. 公開する — create-pipeline-run --type Online --object-ids <PublishObjectId>を実行 → get-pipeline-run --id <PipelineRunId>をポーリング → exec-pipeline-run-stage --id <PipelineRunId> --code <StageCode>でステージを進めます。⚠️ <PublishObjectId>の選択ルール：ノードがワークフロー内にある場合（get-nodeのpathに/が含まれる場合。例：wf_name/node_name）、<PublishObjectId>にはノード ID ではなく、必ずワークフロー IDを指定します。API はワークフロー内のノード ID を拒否し、未找到发布对象を返します。単独ノード（ルートパスで/がない場合）に限り、そのノード自身の ID を指定します。

# Step 1: Find the node
aliyun dataworks-public list-nodes --project-id $PID --name "my_node" --user-agent AlibabaCloud-Agent-Skills/alibabacloud-dataworks-datastudio-develop
# → Note the node Id from the response

# Step 2: Update (incremental — only id + changed fields)
aliyun dataworks-public update-node --project-id $PID --id $NODE_ID \
  --spec '{"version":"2.0.0","kind":"Node","spec":{"nodes":[{"id":"'$NODE_ID'","script":{"content":"SELECT 1;"}}]}}' \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-dataworks-datastudio-develop

# Step 3: Publish (see "Publishing and Deploying" below)
# IMPORTANT: if $NODE_ID's `path` from get-node contains a "/", it is in a workflow —
# replace $NODE_ID below with the workflow ID. Standalone nodes (root path) take their own ID.
aliyun dataworks-public create-pipeline-run --project-id $PID \
  --type Online --object-ids $NODE_ID \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-dataworks-datastudio-develop

update-nodeの後によくある誤った手順（すべて禁止）：

• ❌ deploy-file / submit-file — レガシー API のため、失敗するか予期しない動作をします
• ❌ import-workflow-definition — 初回の一括インポート専用であり、更新や公開には使用しません
• ❌ list-files / get-file — レガシーなファイルモデルです。代わりにlist-nodes / get-nodeを使用してください
• ✅ create-pipeline-run → get-pipeline-run → exec-pipeline-run-stage

公開とデプロイ

⚠️ デプロイにはdeploy-file、submit-file、list-deployment-packages、get-deployment-package、list-files、get-fileを絶対に使用しないでください。 これらはすべてレガシー API です。次のものだけを使用してください：create-pipeline-run → get-pipeline-run → exec-pipeline-run-stage。

公開は非同期のマルチステージパイプラインとして実行されます：

1. create-pipeline-run --type Online --object-ids <ID>を実行し、IdフィールドからPipelineRunIdを取得します。⚠️ **--object-idsはスペース区切りの ID（引用符や括弧のない形式）**であり、JSON 配列文字列ではありません。ID はそのまま渡してください：--object-ids 7567482277219412494。'["..."]'のように囲むと、CLI が括弧付きテキストを ID としてそのまま送信するため、未找到发布对象: [["..."]]が発生します。API が公開するのは最初の ID とその子エンティティだけです。独立したオブジェクトについては、create-pipeline-runを個別に実行してください。ワークフロー内のノードの場合：ノード ID ではなく、ワークフロー ID を渡してください（ワークフロー内のノード ID は同じ未找到发布对象エラーで拒否されます）
2. get-pipeline-run --id <PipelineRunId>をポーリングし、Pipeline.StatusとPipeline.Stagesを確認します
3. ステージのステータスがInitで、前のすべてのステージがSuccessの場合、exec-pipeline-run-stage --id <PipelineRunId> --code <Stage.Code>を呼び出してステージを進めます（パラメーターは--idであり、--pipeline-run-idではありません）
4. パイプライン全体のステータスがSuccess（デプロイ成功）になるまで続けます。他の終端ステータス（Fail、Termination、Cancel）は、デプロイが成功していないことを意味します。上記のルール #15 を参照してください

重要なポイント：Build ステージは自動で実行されますが、Check ステージと Deploy ステージは手動で進める必要があります。CLI の詳細な例、Status Decision Matrix 全体、ポーリングスクリプトについては、references/deploy-guide.mdを参照してください。

CLI に関する注意：aliyun CLI が返す JSON のトップレベルキーはPipelineです（SDK のresp.body.pipelineではありません）。Stages はPipeline.Stagesにあります。

一般的なノードタイプ

用途	command	contentFormat	Extension	datasource
シェルスクリプト	DIDE_SHELL	shell	.sh	—
MaxCompute SQL	ODPS_SQL	sql	.sql	odps
Python スクリプト	PYTHON	python	.py	—
オフラインデータ同期	DI	json	.json	—
Hologres SQL	HOLOGRES_SQL	sql	.sql	hologres
Flink ストリーミング SQL	FLINK_SQL_STREAM	sql	.json	flink
Flink バッチ SQL	FLINK_SQL_BATCH	sql	.json	flink
EMR Hive	EMR_HIVE	sql	.sql	emr
EMR Spark SQL	EMR_SPARK_SQL	sql	.sql	emr
Serverless Spark SQL	SERVERLESS_SPARK_SQL	sql	.sql	emr
StarRocks SQL	StarRocks	sql	.sql	starrocks
ClickHouse SQL	CLICK_SQL	sql	.sql	clickhouse
仮想ノード	VIRTUAL	empty	.vi	—

全タイプ（130 種以上）の一覧：references/nodetypes/index.md（コマンド名、説明、カテゴリで検索でき、各タイプの詳細ドキュメントへのリンクがあります）

ノードタイプが見つからない場合：

1. references/nodetypes/index.md を確認し、キーワードで照合します
2. Glob("**/{keyword}*.md", path="references/nodetypes") を使ってドキュメントを直接探します
3. get-node コマンドを使って、ライブ環境から類似ノードの仕様を取得し、参考にします
4. いずれも解決しない場合 → DIDE_SHELL に切り替え、Shell 内でコマンドラインツールを使って作業します

主な制約

1. script.path は必須です：スクリプトのパスはノード名で終わる必要があります。作成時はノード名だけを渡すこともできます。その場合、サーバーがワークフローのプレフィックスを自動的に付加します。
2. 依存関係は spec.dependencies で設定します：spec.dependencies の nodeId は自己参照です。上流ノードではなく、現在のノード自身の name（作成対象のノード）を指定する必要があります。depends[].output は上流ノードの出力（${projectIdentifier}.UpstreamNodeName）です。上流ノードの outputs.nodeOutputs[].data と下流ノードの depends[].output は、文字単位で完全に一致している必要があります。上流ノードでは outputs.nodeOutputs を宣言する必要があります。⚠️ 出力名（${projectIdentifier}.NodeName）は、プロジェクト内でグローバルに一意である必要があります。重複するとデプロイに失敗します。
3. 変更不可のプロパティ：ノードの command（ノードタイプ）は作成後に変更できません。誤っている場合は、その旨をユーザーに伝え、正しいタイプで新しいノードを作成するよう提案してください。
4. 更新は差分のみ指定してください：変更する id とフィールドのみを渡してください。datasource/runtimeResource などの変更しないフィールドは渡さないでください。
5. datasource.type はサーバーによって補正される場合があります：例：flink → flink_serverless。作成時には汎用タイプを使用してください。
6. ノードは単独で存在できます：ノードはルートレベル（--container-id を渡さない）で作成することも、ワークフローに所属させる（--container-id WorkflowId を渡す）こともできます。ワークフローに配置するかどうかはユーザーが決定します。
7. ワークフローの command は常に WORKFLOW です：script.runtime.command は "WORKFLOW" である必要があります。
8. このスキルでは削除をサポートしていません：このスキルには削除操作はありません。作成または公開に失敗した場合、既存のオブジェクトを削除して問題を「修正」しようとしてはいけません。正しい手順は、失敗の原因を診断し、具体的な競合内容をユーザーに伝え、対処方法（名前変更／既存オブジェクトの更新）をユーザーに判断してもらうことです。
9. 作成前に名前の競合を確認する必要があります：Create API を呼び出す前に、対応する List API を使用して名前が重複していないことを確認してください（「Environment Discovery」を参照）。名前が競合すると作成に失敗します。ノードの出力名（outputs.nodeOutputs[].data）が重複すると、依存関係のエラーまたは公開の失敗につながります。
10. 変更操作にはユーザーの確認が必要です：Create と読み取り専用クエリ（Get/List）を除き、既存のオブジェクトを変更するすべての OpenAPI 操作（Update、Move、Rename など）は、実行前に内容をユーザーに提示し、明示的な確認を得る必要があります。確認時には、操作の種類、対象オブジェクトの名前／ID、主な変更内容を含めてください。ユーザーの確認前にこれらの API を呼び出してはいけません。Delete と Abolish の操作はこのスキルではサポートしていません。
11. 2024-05-18 バージョンの API のみを使用してください：このスキルのすべての API は DataWorks 2024-05-18 バージョンです。旧 API（create-file、create-folder、create-flow-project など）は禁止されています。API 呼び出しでエラーが返された場合は、まず troubleshooting.md を確認してください。旧 API に切り替えてはいけません。
12. エラー時は力任せに再試行せず、停止してください：同じエラーコードが 2 回を超えて連続して返された場合、方法が誤っています。同じ誤った API をパラメーターだけ変えて繰り返し再試行するのではなく、停止してエラーの原因を分析してください（troubleshooting.md を確認してください）。新しい API が失敗しても、旧 API（create-file、create-business など）に切り替えてはいけません。代わりに、このドキュメントの先頭にある FlowSpec Anti-Patterns テーブルを確認してください。最大の失敗要因 #1：0x5083000000000005（「Spec JSON parse failed」）が返された場合、FlowSpec の構造を手当たり次第に試してはいけません。「Quick Start」セクションに移動し、動作する JSON をそのままコピーしてください。最大の失敗要因 #2：コマンドが見つからない場合は、プラグインがインストールされていることを確認してください（aliyun plugin install --names dataworks-public）。
13. CLI パラメーター名はドキュメントで確認し、推測してはいけません：API を呼び出す前に、必ず references/api/{APIName}.md を確認してパラメーター名を確かめてください。よくある間違い：get-project の ID パラメーターは --project-id ではなく --id です。update-node には --id が必要です。不明な場合は aliyun dataworks-public {command} --help で確認してください。
14. 書き込み操作では冪等性を確保してください：作成前に、作成前の競合チェック（List API）を実行してください。Create の実行後にネットワークエラーまたはタイムアウトが発生した場合は、再試行する前に List/Get API でリソースがすでに作成されていないか確認してください。すべてのレスポンスから RequestId を記録してください。
15. Pipeline.Status == 'Success' でない限り、デプロイ成功を宣言してはいけません：create-pipeline-run の後、「デプロイ済み」と見なせるのは、get-pipeline-run が返す最終的な Pipeline.Status が Success の場合だけです。Termination、Fail、Cancel のステータス、またはいずれかのステージが Init／Fail のままである場合は、一部のステージが成功している場合、バージョン番号が変更されている場合、または先行するステージで exec-pipeline-run-stage が Success: true を返した場合でも、デプロイは成功していません。その場合、成功を宣言するローカルの結果ファイル（例：publishing_result.json）を書き込んではいけません。ユーザーに「デプロイ済み」と伝えてはいけません。また、400 流水线不是正在运行 エラーを黙って無視してはいけません。ユーザー向けの概要を作成する前に、get-pipeline-run をもう一度実行してください。パイプラインが終了した実際のステージを報告してください。判定表：references/deploy-guide.md の「Status Decision Matrix」セクションを参照してください。

API クイックリファレンス

API バージョン：以下に記載されているすべての API は、DataWorks 2024-05-18 バージョンです。以下の表に記載されている API のみを使用してください。ほかの DataWorks API を検索したり、使用したりしないでください。

ビジネス呼び出し形式（プラグインモードでは、すべての呼び出しで UA フラグが必要です）：aliyun dataworks-public {kebab-case-command} --parameter --user-agent AlibabaCloud-Agent-Skills/alibabacloud-dataworks-datastudio-develop — プラグインのインストールと UA のグローバル設定については、上記の「Aliyun CLI Setup」セクションを参照してください。

各 API の詳細なパラメーターとコードテンプレートは、references/api/{APIName}.md に記載されています。呼び出しでエラーが返された場合は、https://api.aliyun.com/meta/v1/products/dataworks-public/versions/2024-05-18/apis/{APIName}/api.json から最新の定義を取得できます。

コンポーネント

コマンド	説明
create-component	コンポーネントを作成します
get-component	コンポーネントの詳細を取得します
update-component	コンポーネントを更新します
list-components	コンポーネントの一覧を取得します

ノード

コマンド	説明
create-node	データ開発ノードを作成します。project-id + scene + spec が必要で、container-id は任意です
update-node	ノード情報を更新します。差分更新のため、id と変更するフィールドのみを渡します
move-node	ノードを指定したパスに移動します
rename-node	ノードの名前を変更します
get-node	ノードの詳細を取得します。完全な spec を返します
list-nodes	ノードの一覧を取得します。ワークフローによる絞り込みに対応しています
list-node-dependencies	ノードの依存ノードの一覧を取得します

ワークフロー定義

コマンド	説明
create-workflow-definition	ワークフローを作成します。project-id + spec が必要です
import-workflow-definition	ワークフローをインポートします（初回の一括インポート専用です。更新や公開には使用しないでください。代わりに update-node + create-pipeline-run を使用してください）
update-workflow-definition	ワークフロー情報を差分更新します
move-workflow-definition	ワークフローを指定したパスに移動します
rename-workflow-definition	ワークフローの名前を変更します
get-workflow-definition	ワークフローの詳細を取得します
list-workflow-definitions	ワークフローの一覧を取得します。タイプで絞り込めます

リソース

コマンド	説明
create-resource	ファイルリソースを作成します
update-resource	ファイルリソース情報を差分更新します
move-resource	ファイルリソースを指定したディレクトリに移動します
rename-resource	ファイルリソースの名前を変更します
get-resource	ファイルリソースの詳細を取得します
list-resources	ファイルリソースの一覧を取得します

関数

コマンド	説明
create-function	UDF 関数を作成します
update-function	UDF 関数情報を差分更新します
move-function	関数を指定したパスに移動します
rename-function	関数の名前を変更します
get-function	関数の詳細を取得します
list-functions	関数の一覧を取得します

公開パイプライン

コマンド	説明
create-pipeline-run	公開パイプラインを作成します。type=Online/Offline
exec-pipeline-run-stage	公開パイプラインの指定したステージを実行します。非同期の場合はポーリングが必要です
get-pipeline-run	公開パイプラインの詳細を取得し、ステージのステータスを返します
list-pipeline-runs	公開パイプラインの一覧を取得します
list-pipeline-run-items	公開コンテンツを取得します

補助クエリ

コマンド	説明
get-project	id から projectIdentifier を取得します
list-data-sources	データソースの一覧を取得します
list-compute-resources	コンピューティングエンジンのバインディング（EMR、Hologres、StarRocks など）の一覧を取得します — list-data-sources を補完します
list-resource-groups	リソースグループの一覧を取得します

リファレンスドキュメント

シナリオ	ドキュメント
API と CLI コマンドの全一覧	references/related-apis.md
RAM 権限ポリシーの設定	references/ram-policies.md
操作の検証方法	references/verification-method.md
受け入れ基準とテストケース	references/acceptance-criteria.md
CLI のインストールと設定ガイド	references/cli-installation-guide.md
ノードタイプの一覧（130 種類以上）	references/nodetypes/index.md
FlowSpec フィールドリファレンス	references/flowspec-guide.md
ワークフロー開発	references/workflow-guide.md
スケジューリング設定	references/scheduling-guide.md
公開と公開解除	references/deploy-guide.md
DI データ統合	references/di-guide.md
トラブルシューティング	references/troubleshooting.md
完全な例	assets/templates/README.md