建立環境並建置
需要 company manager。受限 API key 對 environments 一律 404。
步驟
- 建環境 —
POST /environments（SandboxEnvironmentCreateRequest：name1–256、description≤2048）。回state: "active"。 - 建版本 —
POST /environments/{id}/versions（SandboxEnvironmentVersionCreateRequest）：source_digest（必填，^sha256:[0-9a-f]{64}$）——建置內容的內容雜湊。source_ref（≤1024，選填）、resource_profile（standard/performance/large/xlarge）。- 版本不可變，建立後
state: "draft"。
- 觸發建置 —
POST /environments/{id}/versions/{vid}/builds（build_region預設asia-east1、build_profile預設standard）。draft →build_queued，並建立一個 build attempt。 - 輪詢（無 streaming）：
- 建置嘗試：
GET /.../builds/{attempt_id}，看status走validation_queued → validating → build_queued → building → verifying → completed，直到terminal_class有值。 - 版本：
GET /.../versions/{vid}，看state走到ready（draft → build_queued → building → verifying → verified → regional_provisioning → ready）。
- 建置嘗試：
失敗與重試分支
| 情況 | 版本 state | 動作 |
|---|---|---|
| 可重試失敗 | retryable_failed | POST /.../retry-build |
| provisioning 卡住 | provisioning_blocked / provisioning 失敗 | POST /.../retry-provisioning |
| 客戶端建置失敗 | build terminal_class: customer_failed | 看 error_code / stage_code 修正內容，開新版本 |
| 平台失敗 | build terminal_class: platform_failed | 重試；持續失敗回報後端 |
| 取消 | POST /.../builds/{attempt_id}/cancel（kill switch 下仍可用） | → cancel_requested → cancelling → cancelled |
其他分支狀態：quarantined、rejected、blocked、abandoned、superseded、archived。
常見錯誤
- 409
build_not_eligible：版本目前 state 無法開始建置。 - 409：取消一個不可取消狀態的 attempt。
- 422：
source_digest格式不符、或帶了未知欄位（extra=forbid）。 - 404：未授權 / 別家公司的 id / 受限 key。
UI 建議
- 「環境列表 → 版本列表 → 每版本建置狀態」三層。
- 版本
state未到ready前，禁止把它拿去建立任務版本。 - 建置報告：
report_total_bytes > 0表示有報告（報告本體在控制面，前端只見此旗標）。
下一步：任務、發布與綁定。
Last updated on