Google 會運用 AI 技術將內容翻譯成你偏好的語言，但可能會出錯。

排解問題

本頁面說明如何解決使用 Workflows 時可能遇到的問題。

詳情請參閱監控和偵錯 Workflows。

部署錯誤

部署工作流程時，Workflows 會檢查原始碼是否沒有錯誤，且符合語言語法。如果發現錯誤，Workflows 會傳回錯誤。最常見的部署錯誤類型包括：

參照未定義的變數、步驟或子工作流程
語法錯誤
- 縮排不正確
- 缺少或多餘的 {、}、"、- 或 :

舉例來說，下列原始碼會擲回部署錯誤，因為回傳敘述參照了未定義的變數 varC：

- step1:
    assign:
    - varA: "Hello"
    - varB: "World"
- step2:
    return: ${varC + varB}

下列 Google Cloud 控制台和 gcloud CLI 範例會使用這段錯誤的原始碼。

控制台

發生部署錯誤時，Workflows 會在「Edit workflow」(編輯工作流程) 頁面的橫幅中顯示錯誤訊息：錯誤訊息會標記原始碼中的問題，並盡可能指定錯誤來源：

Could not deploy workflow: failed to build: error in step step2: error
evaluating return value: symbol 'varC' is neither a variable nor a
sub-workflow name (Code: 3)

gcloud

執行 gcloud workflows deploy 指令時，如果部署失敗，Workflows 會將錯誤訊息傳回指令列。錯誤訊息會標示原始碼中的問題，並盡可能指出錯誤來源：

ERROR: (gcloud.workflows.deploy) [INVALID_ARGUMENT] failed to build:
error in step step2: error evaluating return value: symbol 'varC' is neither
a variable nor a sub-workflow name

如要解決問題，請編輯工作流程的原始碼。在這種情況下，請參照 varA，而非 varC。

HTTP `403` 服務帳戶權限錯誤

執行、部署或更新工作流程時，可能會遇到 HTTP 403 (PERMISSION_DENIED) 錯誤。

執行工作流程時權限遭拒

如果 HTTP 伺服器回應 403 錯誤代碼，表示工作流程的服務帳戶沒有存取目標資源的權限，因此工作流程執行失敗。例如：

SERVICE_ACCOUNT does not have storage.objects.create access to the Google Cloud
Storage object. Permission 'storage.objects.create' denied on resource (or it may not exist).

建立工作流程時，每個工作流程都會與一個 Identity and Access Management (IAM) 服務帳戶建立關聯。如要解決這個問題，請為工作流程的服務帳戶授予一或多個 IAM 角色，其中包含存取工作流程所用資源所需的最低權限。舉例來說，如要讓工作流程將記錄傳送至 Cloud Logging，請務必將包含 logging.logEntries.create 權限的角色授予執行工作流程的服務帳戶。詳情請參閱「授予工作流程權限，以便存取 Google Cloud 資源」。

部署或更新工作流程時權限遭拒

部署或更新工作流程時，如果您無權以工作流程服務帳戶的身分執行操作，要求可能會失敗，並顯示 HTTP 403 (PERMISSION_DENIED) 錯誤。例如：

Permission 'iam.serviceaccounts.actAs' denied on service
account PROJECT_NUMBER-compute@ (or it may not exist).

或

permission iam.serviceAccounts.ActAs is required on the workflow's new/current
service account to set it or the workflow source contents

如要解決這個問題，請將包含 iam.serviceAccounts.actAs 權限的角色 (例如服務帳戶使用者 (roles/iam.serviceAccountUser)) 授予部署或更新工作流程的主體。視作業而定，請在下列服務帳戶授予這個角色：

僅更新工作流程原始碼 (不更新服務帳戶)：在與工作流程相關聯的現有服務帳戶上授予角色。
建立工作流程、更新服務帳戶，或同時更新原始碼和服務帳戶：將角色授予與工作流程建立關聯的新服務帳戶。

詳情請參閱「服務帳戶權限」。

HTTP `404 No such object` 或 `Not found` 錯誤

使用 Cloud Storage 連接器時，如果 HTTP 伺服器回應 404 錯誤代碼，工作流程執行作業就會失敗。例如：

HTTP server responded with error code 404
in step "read_input_file", routine "main", line: 13
{
  "body": "Not Found",
  "code": 404,
  ...
}

請對物件名稱進行網址編碼，確保路徑安全。您可以使用 url_encode 和 url_encode_plus 函式，對要求網址的物件名稱或查詢字串中出現的適用字元進行編碼。例如：

- init:
    assign:
        - source_bucket: "my-bucket"
        - file_name: "my-folder/my-file.json"
- list_objects:
    call: googleapis.storage.v1.objects.get
    args:
        bucket: ${source_bucket}
        object: ${text.url_encode(file_name)}
        alt: media
    result: r
- returnStep:
    return: ${r}

如果未對物件名稱進行網址編碼，且儲存空間值區含有資料夾，要求就會失敗。詳情請參閱「編碼網址路徑部分」和「Cloud Storage 命名注意事項」。

HTTP `429 Too many requests` 錯誤

可同時執行的工作流程執行作業數量有上限。如果這項配額用盡，且執行作業待處理功能已停用，或待處理執行作業的配額已達上限，則任何新的執行作業都會失敗，並傳回 HTTP 429 Too many requests 狀態碼。

達到並行執行配額後，執行作業待處理功能可讓您將工作流程執行作業排入佇列。根據預設，所有要求 (包括由 Cloud Tasks 觸發的要求) 都會啟用執行作業待處理功能，但下列情況除外：

在工作流程中使用 executions.run 或 executions.create 連接器建立執行作業時，系統預設會停用執行作業待處理功能。如要設定，請明確將執行的 disableConcurrencyQuotaOverflowBuffering 欄位設為 false。
如果是 Pub/Sub 觸發的執行作業，系統會停用執行作業待處理功能，且無法設定。

詳情請參閱「管理執行作業待處理項目」。

您也可以啟用 Cloud Tasks 工作佇列，以您定義的速率執行子工作流程，並提高執行速率。在這種情況下，建議您明確停用執行作業待處理功能。

跨專案服務帳戶權限錯誤

如果嘗試使用跨專案服務帳戶部署工作流程時收到 PERMISSION_DENIED 錯誤，請確認專案未強制執行 iam.disableCrossProjectServiceAccountUsage 布林限制，且服務帳戶設定正確。詳情請參閱「使用跨專案服務帳戶部署工作流程」。

資源名稱必須符合 RFC 1123 規定

當 HTTP 伺服器回應 400 錯誤代碼時，工作流程執行作業會失敗。例如：

"description": "must conform to RFC 1123: only lowercase, digits, hyphens,
and periods are allowed, must begin and end with letter or digit, and less
than 64 characters."

如要解決這個問題，請確認資源名稱符合 RFC 1123 定義的 DNS 標籤標準，且指派變數時，您正確串連字串和運算式。

舉例來說，您無法像這樣指派變數：- string: hello-${world}。請改為執行下列操作：

YAML

  - assign_vars:
      assign:
          - string: "hello"
          - string: ${string+" "+"world"}

JSON

  [
    {
      "assign_vars": {
        "assign": [
          {
            "string": "hello"
          },
          {
            "string": "${string+" "+"world"}"
          },
        ]
      }
    }
  ]

含有冒號的運算式

在 YAML 中，如果冒號被解讀為定義對應，含有冒號的運算式可能會導致非預期的行為。雖然可以部署及執行工作流程，但輸出內容不會符合預期。

如果使用 Google Cloud 控制台建立工作流程， Google Cloud 控制台無法以視覺化方式呈現工作流程，您可能會收到類似下列的警告：

工作流程建立警告

如要解決這個問題，請用單引號括住 YAML 運算式：

建議：'${"a: " +string(a)}'

不建議使用：${"a: " +string(a)}

使用非英數字元的地圖鍵

存取含有非英數字元的對應鍵 (例如 "special!key": value 中的驚嘆號) 時，必須用引號括住鍵名。如果鍵名稱未以引號括住，就無法部署工作流程。舉例來說，如果您嘗試部署下列原始碼，系統會擲回 token recognition error：

- init:
    assign:
    - var:
        key:
            "special!key": bar
- returnOutput:
    return: '${"foo" + var.key[special!key]}'

如要解決這個問題，請改用下列程式碼傳回輸出內容：

'${"foo" + var.key["special!key"]}'

清單中的多個運算式

在清單中使用多個運算式 (例如下列疊代範圍範例) 不是有效的 YAML：

[${rangeStart}, ${rangeEnd}])

解決這個問題的方法如下：

將清單放入運算式中：

${[rangeStart, rangeEnd]}
請用單引號括住每個運算式：

['${rangeStart}', '${rangeEnd}']

結果會如預期，顯示兩個值的清單。

客戶自行管理的加密金鑰 (CMEK)

搭配使用 Cloud KMS 和 Workflows 時，可能會發生錯誤。下表說明各種問題及解決方法。

問題	說明
權限 `cloudkms.cryptoKeyVersions.useToEncrypt` 遭拒	提供的 Cloud KMS 金鑰不存在，或權限設定不正確。解決方法：確認 Cloud KMS 金鑰是否存在。列出指定金鑰環的金鑰，並驗證其用途。確認 Workflows 服務代理有權存取金鑰，且已獲派 `cloudkms.cryptoKeyEncrypterDecrypter` 角色。
未啟用金鑰版本	提供的 Cloud KMS 金鑰版本已停用。解決方案：重新啟用 Cloud KMS 金鑰版本。
金鑰環區域與要保護的資源不符	提供的 KMS 金鑰環區域與工作流程的區域不同。解決方案：使用相同區域的 Cloud KMS 金鑰環和受保護的工作流程。(請注意，這些資源可以位於不同專案)。詳情請參閱「Cloud KMS 位置」和「Workflows 位置」。
超過 Cloud KMS 配額限制	Cloud KMS 要求配額已達上限。解決方案：限制 Cloud KMS 呼叫次數，或提高配額上限。詳情請參閱「Cloud KMS 配額」。

使用 Cloud Run 連接器時找不到要求的實體

嘗試使用連接器方法 googleapis.run.v1.namespaces.jobs.create 時，如果 HTTP 伺服器回應錯誤代碼 404，工作流程執行作業就會失敗。

這個方法需要您指定 HTTP 端點的位置。例如 us-central1 或 asia-southeast1。如未指定位置，系統會使用全域端點 https://run.googleapis.com，但這個位置僅支援清單方法。

如要解決這個問題，請務必在呼叫連接器時指定 location 引數。如要瞭解 Cloud Run Admin API 位置選項，請參閱「服務端點」。

資源限制

如果遇到資源限制或 ResourceLimitError、MemoryLimitExceededError 或 ResultSizeLimitExceededError 等錯誤，可以清除變數來釋出記憶體。例如，您可能需要釋出後續步驟所需的記憶體。或者，您可能會有不關心結果的呼叫，您可以完全省略這些結果。

YAML 縮排

YAML 縮排有其意義，每個縮排層級至少應有兩個空格。縮排不足可能會導致錯誤，新的層級應至少從上一行文字開頭縮排兩個空格。

舉例來說，下列範例未正確指定包含 stepName 和 call 項目的地圖清單項目：

- stepName:
  call: sys.log

請改為將後續行縮排兩個空格，將 call 巢狀結構置於 stepName 內：

- stepName:
    call: sys.log

請務必使用空格 (而非定位字元) 縮排。

後續步驟

Workflows 的已知問題

排解問題 透過集合功能整理內容 你可以依據偏好儲存及分類內容。