# 快速开始 (/docs/cloud/services/automation/quickstart)



本教程使用 develop、Bash、curl 和 jq。所有命令在同一个 Bash 会话中按顺序执行；不需要安装 SDK。脚本只做加法，不调用计费能力。

<a id="environment" />

## 1. 创建 API Key [#1-创建-api-key]

打开 [Develop Console → API Keys](https://console-develop.deepraxis.ai/keys)，创建 Key，并将其保存到环境变量 `PRAXIS_API_KEY`。Key 的管理说明见[平台管理](/docs/cloud/account)。

```bash
export PRAXIS_API_URL="https://api-develop.deepraxis.ai"
: "${PRAXIS_API_KEY:?Set PRAXIS_API_KEY to your develop API Key}"
command -v curl
command -v jq
curl --fail-with-body -sS "$PRAXIS_API_URL/automation/v1/runs?limit=1" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" | jq -e '.data | type == "array"'
```

期望：两个命令都能找到，最后输出 `true`，退出码为 0；这同时验证 Key 能访问自动化运行列表。

<a id="run-source" />

## 2. 临时运行脚本 [#2-临时运行脚本]

[创建运行](/docs/api/native/automation/createRun)接受源码和输入。`wait` 表示本次 HTTP 请求等待运行终态的最长秒数，范围 0–60，默认 0。`wait: 60` 最多等待 60 秒，运行提前结束就提前返回；等待结束不会取消运行。HTTP 200 表示已到终态（也可能失败），202 表示仍在排队或执行，两者都要检查 `status`。

```bash
SOURCE='export default async (input: { n: number }) => ({ answer: input.n + 1 });'
RUN=$(curl --fail-with-body -sS "$PRAXIS_API_URL/automation/v1/runs" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  -H 'Content-Type: application/json' \
  --data "$(jq -n --arg source "$SOURCE" \
    '{source:$source,language:"ts",input:{n:41},wait:60}')")
RUN_ID=$(jq -er '.id' <<< "$RUN")
jq -e '.id | startswith("run_")' <<< "$RUN"
```

期望：输出 `true`，`RUN_ID` 是新运行的 ID。源码接收 `n: 41`，返回 `answer: 42`。

HTTP 202 的响应仍是 Run 对象。下面是字段节选（`id` 以实际响应为准）：

```json
{
  "id": "run_...",
  "status": "running",
  "output": null,
  "error": null
}
```

保留 `RUN_ID`，按下一节 GET `/automation/v1/runs/$RUN_ID`，直到 `completed`、`faulted` 或 `cancelled`。不要因为等待结束就重复创建运行。

<a id="read-result" />

## 3. 读结果 [#3-读结果]

用[读取运行](/docs/api/native/automation/getRun)检查终态。下面的函数在约 3 分钟内轮询；脚本失败时打印真实错误并返回非零退出码。

```bash
read_result() {
  local result
  for attempt in $(seq 1 90); do
    result=$(curl --fail-with-body -sS \
      "$PRAXIS_API_URL/automation/v1/runs/$1" \
      -H "Authorization: Bearer $PRAXIS_API_KEY") || return 1
    case "$(jq -r '.status' <<< "$result")" in
      completed) jq -e '.output.answer == 42' <<< "$result"; return $? ;;
      faulted|cancelled) jq '{status,error}' <<< "$result"; return 1 ;;
    esac
    sleep 2
  done
  echo 'Still pending: retrieve the run again using its ID' >&2
  return 1
}
read_result "$RUN_ID"
```

期望：输出 `true` 且退出码为 0，证明运行已 `completed`，输出确实为 42。若仍未完成，保留 `RUN_ID`，再次读取；不要因为客户端等待结束就重复创建运行。

<a id="publish-script" />

## 4. 保存为脚本并发布 [#4-保存为脚本并发布]

把同一份源码保存为[脚本草稿](/docs/api/native/automation/createScript)，读取当前 `draft.revision` 后[发布版本](/docs/api/native/automation/publishScriptVersion)。每次教程使用不同的名称。

命名空间由你自行取名，例如自己的项目名。下面的 `docs-samples` 只是示例；修改 `NAMESPACE` 后，后续请求会使用同一个命名空间。

```bash
NAMESPACE="docs-samples"
SCRIPT_NAME="hello-$(date +%s)-$RANDOM"
SCRIPT=$(curl --fail-with-body -sS "$PRAXIS_API_URL/automation/v1/scripts" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  -H 'Content-Type: application/json' \
  --data "$(jq -n --arg namespace "$NAMESPACE" --arg name "$SCRIPT_NAME" --arg source "$SOURCE" \
    '{namespace:$namespace,name:$name,draft:$source}')")
jq -e '.id | startswith("scr_")' <<< "$SCRIPT"
DRAFT=$(curl --fail-with-body -sS \
  "$PRAXIS_API_URL/automation/v1/scripts/$NAMESPACE/$SCRIPT_NAME" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" | jq -er '.draft.revision')
curl --fail-with-body -sS \
  "$PRAXIS_API_URL/automation/v1/scripts/$NAMESPACE/$SCRIPT_NAME/versions" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  -H 'Content-Type: application/json' \
  --data "$(jq -n --arg revision "$DRAFT" \
    '{version:"1.0.0",expected_draft_revision:$revision}')" \
  | jq -e '.version == "1.0.0"'
```

期望：两次检查均输出 `true`；版本 `1.0.0` 已发布。若返回 `PRECONDITION_FAILED`，报错原文「草稿已修改」，重新读取草稿，确认内容后用最新 revision 发布。

<a id="run-version" />

## 5. 按版本运行 [#5-按版本运行]

```bash
TARGET="$NAMESPACE/$SCRIPT_NAME@1.0.0"
RUN=$(curl --fail-with-body -sS "$PRAXIS_API_URL/automation/v1/runs" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  -H 'Content-Type: application/json' \
  --data "$(jq -n --arg target "$TARGET" \
    '{target:$target,input:{n:41},wait:60}')")
RUN_ID=$(jq -er '.id' <<< "$RUN")
read_result "$RUN_ID"
```

期望：再次输出 `true`，结果仍为 42。保留 `TARGET`，下一步可以给它[添加触发器](/docs/cloud/services/automation/guides/triggers)。用完后可[归档脚本](/docs/api/native/automation/archiveScript)；归档会保留名称和历史。

[API 参考 →](/docs/api/native/automation) · [Cookbook →](/docs/cookbook)