本頁面由 Cloud Translation API 翻譯而成。

疑難排解

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

詳情請參閱「監控」和「偵錯」工作流程。

部署錯誤

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

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

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

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

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

控制台

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

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 'iam.serviceaccounts.actAs' denied on service
account PROJECT_NUMBER-compute@developer.gserviceaccount.com (or it may not exist).

或

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).

每個工作流程都會在建立時與 IAM 服務帳戶建立關聯。如要解決這個問題，請授予服務帳戶一或多個 IAM 角色，這些角色須包含管理工作流程所需的最低權限。舉例來說，如要允許工作流程將記錄傳送至 Cloud Logging，請確認執行工作流程的服務帳戶具備含有 logging.logEntries.create 權限的角色。詳情請參閱「授予工作流程權限，以便存取 Google Cloud 資源」。

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}

如果未對物件名稱進行網址編碼，且儲存空間 bucket 含有資料夾，要求就會失敗。詳情請參閱「對網址路徑部分進行編碼」和「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

請改為將後續行縮排兩個空格，在 stepName 中巢狀內嵌 call：

- stepName:
    call: sys.log

請務必使用空格，而非定位字元，來縮排程式碼行。

後續步驟

工作流程的已知問題

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