Workiva 支援中心

Workiva Scripting 及 Python 3.9 支援終止

為了確保您的自動化流程與時俱進， Workiva 推出了對 Python 3.13的支援，以及讓您選擇每個指令碼的執行階段版本的指令碼層級設定。本指南說明如何安全地從 3.9 移至 3.13、測試什麼，以及如何以最小的干擾推出變更。

在 2025 年 10 月之前，Workiva Scripting 依賴於 Python Software Foundation的官方 Python 3.9 版本；此解決方案已於 2025 年 10 月結束，因此不再接收安全更新或錯誤修復。

為回應此問題，Workiva Scripting 已轉換為使用 Amazon Linux 2023 (AL2023) 映像，該映像提供自己的編譯版本，並支援 Python 3.9 和 Python 3.13。此變更可確保 Python 3.9 收到持續的安全修補程式 並在 Amazon 的更新周期中進行維護，即使開源社區已不再修補上游 Python 版本。

進行此轉換後，在 2027 年 10 月之前，Workiva Scripting 將繼續支援在 Python 3.9 上安全地執行腳本。 

誰應該考慮此遷移？目前在Python 3.9上執行 Workiva Scripting 自動化的任何人 - 無論是手動觸發程序、從 Chains（自動化鏈結）或透過「整合自動化」。

如果我什麼都不做呢？在 2027 年 10 月之前，您的指令碼將透過 AL2023 修補程式保持安全，但我們建議您移轉至 Python 3.13，因為受支援的執行階段為更新版本。

關於生命週期結束時間線和支援版本的更多背景資料，請審閱／審核官方Python 發行狀態網頁 。

Workiva 如何支持這項變革

Workiva 推出更新，讓開發人員能夠控制自己的指令碼使用哪個 Python 執行階段。此更新帶來以下變更：

• Python 3.13 支援： 所有新指令碼現在預設為最新穩定版本 Python 3.13。
• 每個腳本的執行階段移轉數： 現有的 Python 3.9 指令碼可以移轉至 Python 3.13。腳本移轉至 Python 3.13 後，無法再將其變更回 Python 3.9。
• 向後相容性： 所有現有指令碼繼續使用 Python 3.9，直到您更新它們。
• 編輯器和 API 支援： 您可以直接在 Workiva Script Editor 中或透過 Scripting API 設定或更新 Runtime。

這可確保您能依據自己的時間表進行遷移、安全測試，並只會在您確定生產指令碼已準備就緒時才切換。

此轉換的時間表

為了幫助您規劃，以下是推出時間表：

• Workiva 中提供了 Python 3.13（2025 年 9 月）： 可以使用 Scripting API 或 Scripting Editor 將現有的 Python 3.9 指令碼移轉至 Python 3.13。新指令碼使用 Python 3.13。
• Python 3.9 生命週期結束（2025 年 10 月）： 官方 Python 社區支持結束。Workiva 將透過 AL2023 繼續支援至 2027 年 10 月，但強烈建議移轉。
• 2027 年 10 月： Workiva 計劃在 2027 年 10 月終止對 Python 3.9 的支援，之後所有指令碼都將在 Python 3.13 上執行。

進行轉換

您應該盡快開始在 Python 3.13 上測試腳本，同時僅在 3.9 上保持生產，直到您驗證它們可以在 3.13 上正確運行。一旦您可以自如地使用 Python 3.13，請立即將您的生產指令碼轉換到 Python 3.13 運行時。

將腳本切換到 Python 3.13

我們建議的推出模式：建立副本、更新版本、測試，然後推廣。這可將生產風險降至最低，並在需要時讓您保留運行記錄。

步驟 1 - 複製一份

1. 在 Workiva 中，複製您的製作腳本。
   該副本將設定為 Python 3.13。

步驟 2 - 測試並修改文案

1. 在安全 / 測試上下文中執行副本。
2. 修正任何破壞性變更 (請參閱 「常見問題與修正」)。
3. 驗證輸出、副作用和效能。

步驟 3 - 變更為 3.13 (兩個選項)

選項 A - 這將保留生產運行記錄

1. 透過複製貼上的方式，將副本 的更新程式碼推回原始的 腳本。
2. 將原始 腳本的執行時間變更為Python 3.13 。
3. 重新執行您的測試，然後恢復原始的正常排程/觸發器。
4. (可選）歸檔或退役副本。

選項 B - 這將不會保留生產運行記錄

1. 變更生產觸發器 (也就是 Chains 觸發器) 從原始 腳本指向複製 腳本。
2. 副本 成為新的生產指令碼 (執行於Python 3.13)。
3. (選項) 將原始檔案歸檔或退還。

行動呼籲： 無論您選擇哪個選項，請在 2027 年 10 月之前將所有使用中的腳本移至 Python 3.13 。

更新 Python 執行時版本

使用腳本 API

開始之前，請確保您的 API 授與包含script:read和script:write範圍。有關建立或更新 API 授與的說明，請參閱 Workiva API 設定。

1. 確定腳本的執行時間。 

   GET /scripts/{scriptId} 授權：持有者 {token} X 版本：2026-01-01

   檢查回應中runtime 的值。

2. 更新腳本至 Python 3.13。

   PATCH /scripts/{scriptId} Authorization：Bearer {token} X-Version：2026-01-01 Content-Type：application/json [{ "op": "replace", "path": "/runtime", "value ": "python3.13" }]

變更執行階段不會自動重新產生指令碼的相依性套件。如果腳本包含 需求.txt來源，請在更新 Runtime 後開始產生相依性，並等待操作完成後再執行腳本。沒有 需求的腳本 不需要產生相依性。

有關更多詳細資訊，請參閱以下 Workiva 開發人員頁面：

• Scripting API 移轉指南
• 部分更新指令碼
  

範例：變更與讀取 Python 執行時版本

以下範例程式碼擷取指令碼的目前執行階段，將其移轉至 Python 3.13，並使用 Scripting API 重新產生其相依性套件。

import os import time import requests CLIENT_ID = os.environ["CLIENT_ID"] CLIENT_SECRET = os.environ["CLIENT_SECRET"] SCRIPT_ID = os.environ["SCRIPT_ID"] API_VERSION = "2026-01-01" API_BASE_URL = "https: //api.app.wdesk.com" SCRIPTS_API_URL = f"{API_BASE_URL}/scripts" AUTH_URL = f"{API_BASE_URL}/oauth2/token" Def get_auth_headers(client_id, client_secret):response =requests.post(AUTH_URL, headers= { "Content-Type": "application/x-www-form-urlencode;charset=UTF-8", "X-Version": API_VERSION, }, data={ "client_id": client_id, "client_secret": client_secret, "grant_type": "client_credentials", }, timeout=30, ) response.raise_for_status() return { "Authorization": f"Bearer {response.json()['access_token']}", "X-Version": API_VERSION , } Def read_version(script_id, headers):response =requests.get(f"{SCRIPTS_API_URL}/{script_id}", headers=headers, timeout=30, )response.raise_for_status() script = response.json()print( f"'{script['name']}' 指令碼的Python 版本: " f"{script['runtime'個": "application/json", }, json=[{ "op": "replace", "path": "/runtime", "value": "python3.13", }], timeout=30, ) 回應。 ')}" ) Defhas_requirements(script_id, headers):response =requests.get(f"{SCRIPTS_API_URL}/{script_id}/sources", headers=headers, timeout=30, )response.raise_for_status() return any(source ["path"] == "requirements.txt" for source in response.json()["data"] ) Def regenerate_Dependencies(script_id, headers):response =requests.post( f"{SCRIPTS_API_URL}/{script_id}/相依性/世代」, 標頭=標頭, 逾時=30, ) response.raise_for_status() Operation_url = response.json()["operationLocation"] while True: Operation_response =requests.get(op eration_url, headers=headers, timeout=30, ) Operation_response.raise_for_status() Operation = Operation_response.json() if {"完成"、"失敗"、"已取消"}中的操作["狀態"]：中斷時間.sleep( int(operation_response.headers.get("Retry-After", "5")) ) if Operation["status"] != "completed": raise RuntimeError( f"Dependency generation ended with status " f"{operation[' status']}: {Operation}") headers = get_auth_headers(CLIENT_ID, CLIENT_SECRET) read_version(SCRIPT_ID, headers) change_to_python_313(SCRIPT_ID, headers) if has_Requirements(SCRIPT_ID, headers): regenerate_Dependencies(SCRIPT_ID, headers) print("相關性重新產生成功.")else:print("找不到需求.txt 來源;已略過產生相依性。」)

使用腳本編輯器

使用指令碼編輯器，您可以直接在 UI 中設定執行階段。對於使用 Python 3.9 的現有腳本，請使用 屬性 → 執行階段版本 將其移轉至 Python 3.13。儲存後，無法將指令碼變更回 Python 3.9。

若要更新編輯器中的指令碼，請

1. 在Scripting Editor 中開啟指令碼。
2. 移至右側屬性面板。
3. 在Runtime Version 下，從下拉式選單中選擇Python 3.13 。
4. 儲存您的變更。
5. 在安全/測試環境中執行腳本，然後再推廣到生產環境。

提示

• 確保您腳本中的任何第三方套件與 Python 3.13 相容。
• 更新requirements.txt 檔案中任何固定的套件版本 (例如，與 Python 3.9 不同，requests==2.28 在 3.13 中不需要)。
• 請閱讀官方 Python 文件，以瞭解有關 Python 版本的主要變更的詳細資訊3.10,3.11,3.12, 以及3.13, 包括：
  • 結構模式匹配、f 字串更新、改進錯誤訊息
  • 效能大幅提升（函式呼叫、字串操作、記憶體管理、JSON 序列化/解序列化）
  • 套件與特定套件參數的棄用與移除 (例如 cgi、cgitb、distutils 等已被棄用；asyncio的「loop」參數已被移除)

從 3.9 移至 3.13 的常見遷移問題與修正

以下是當您將腳本從 Python 3.9 移動到 3.13 時可能會遇到的一些常見問題，以及建議的修正方法：

• 第三方程式庫： 某些套件可能尚不支援 Python 3.13。
  • 修復： 升級至最新的相容版本，或以其他版本取代。仔細測試任何釘住的需求。您可以在pyreadiness.org/3.13 檢查您的函式庫是否支援，並檢閱 「支援的指令碼函式庫與相依性 」 說明文章，以取得更多資訊。
• 要求庫版本： 要求 庫是 Workiva Scripting 中最常見的第三方庫。在 Python 3.9 的早期版本中，指令碼會在要求者 版本 2.30.0 或更新版本時分解/中斷。一旦您移植到 Python 3.13，您就可以使用最新版本的requests 而不會有問題。
• Python 3.13 在字串和位元組的處理方式上有所差異： 更嚴格的類型檢查可能會浮現出隱藏的問題。
  • 修正： 檢查混合str 和bytes 的程式碼，並確保明確的編碼/解碼。
• 日期時間和時區行為： Python 3.13 在 zoneinfo 程式庫和更嚴格的解析方面存在差異。
  • 修正： 測試所有日期/時間邏輯，特別是格式化和時區轉換。
• JSON 序列化： 由於更嚴格的規則，某些物件可能無法序列化。
  • 修正： 確保自訂物件在json.dumps 之前轉換，或使用預設的編碼器。
• 已過時的 API： 在 Python 3.9 中已過時的某些 Python stdlib 函數（例如 asyncio.get_event_loop、 distutils和某些語言環境 API）已被移除。
  • 修正： 更新程式碼，以使用受支援的替代方案。
• 效能變更: 循環和異步任務的行為可能不同。
  • 修復： 在關鍵路徑上執行負載測試；必要時更新並發邏輯。

提示： 請務必先測試生產指令碼的副本。在受控測試環境中應用的修補程式可降低生產問題的風險。

Python 3.13 的新增功能

以下是 Python 3.13 的一些變更重點：

• 改進的互動式解釋器: 多行編輯、顏色和彩色追溯。
• 實驗性自由執行緒建置模式： 在某些平台上允許使用真正的平行執行緒 (無 GIL)。
• 實驗性 JIT： 效能提升的早期基礎。
• 更優異的偵錯工具： locals() 變更現在可與明確定義的語意搭配使用。
• 新的記憶體配置器: 已修改的 mimalloc 包含並在支援時預設啟用。
• 較小的檔案： 文件字串會移除前置空格，進而減少記憶體使用量和 .pyc 檔案大小。
• New dbm backend: 預設上使用 dbm.sqlite3 。
• 平台更新： macOS 最低 10.13、iOS/Android 第 3 層、WASI 第 2 層。
• 鍵入改善： 鍵入預設值、範圍縮小、唯讀項目和棄用註解。
• 移除: 已移除過時模組 (例如cgi、 telnetlib、 imghdr、 lib2to3等)。

如需完整的發行說明，請參閱 Python.org 的 「Python 3.13 的新功能 」。

如果您想檢視 3.9 和 3.13 之間引入的具體變更，請參閱：

• Python 3.10 新增功能
• Python 3.11 新增功能
• Python 3.12 新增功能

常見問答

問：我需要馬上遷移所有的腳本嗎？
不。您現在可以開始在 Python 3.13 上測試腳本，同時在 3.9 上繼續生產。所有腳本都必須在 2027 年 10 月之前遷移到 Python 3.13。

問：我現有的腳本是否在 Python 3.9 達到生命週期結束時自動中斷？
不。Workiva Scripting 依賴於 Amazon Linux 2023 (AL2023) 下的 Amazon Python 3.9 版本，該版本會在 2027 年 10 月之前繼續接收安全修補程式。您的指令碼不受官方 Python 3.9 生命週期結束的影響。

問：我可以在 3.13 上測試腳本，而將生產保留在 3.9 上嗎？
是。建立腳本的副本以進行測試，該副本將自動設定為在 Python 3.13 上執行。在升階至生產階段之前，請先修正複製本中的任何問題。為了避免失去相容性，請保留不同的版本，一個適用於 3.9，一個適用於 3.13，這樣您就可以在需要時輕鬆切換。

問：Scripting Editor 是否支援變更 Runtime？
是。您可以直接在「指令碼編輯器」(Scripting Editor) 中設定指令碼的 Python 執行階段：開啟指令碼，前往「屬性」(Properties) 面板，然後在「執行階段版本」(Runtime Version) 下選取版本。

問：我可以在哪裡了解更多關於圖書館支援的資訊？
請檢查pyreadiness.org/3.13 和 「支援的腳本函式庫和相依性 」 Workiva 幫助文章。

問：如果切換腳本，我的歷史運行資料會發生什麼變化？
視情況而定。如果覆寫原始腳本，則會保留執行記錄。如果您將觸發器指向副本，原始碼的執行歷程會保留在舊腳本中。

問：如果我不在 2027 年 10 月之前移轉，會怎麼樣？
在 2027 年 10 月之後，當 Workiva 根據 AL2023 停止支援在 Python 3.9 上執行腳本時，您的腳本將自動轉換到 Python 3.13。為避免中斷，您應該在 2027 年 10 月之前測試腳本並將其遷移到 Python 3.13。

問：在遷移時，我需要變更我的 Chains（自動化工作流程）或整合自動化嗎？
不。只要將基礎指令碼更新到 Python 3.13，您的鏈結和整合自動化就將繼續按預期執行。主要的級距是確保指令碼本身已被移植。

問：如果發生問題，我可以將指令碼從 Python 3.13 回滾到 3.9 嗎？
不。一旦腳本設定為 Python 3.13，就無法將其執行階段切換回 Python 3.9。如果需要回退，請在 Python 3.9 上保留腳本的單獨副本 — 在 3.9 上維護一個版本，在 3.13 上維護另一個版本 — 以便在測試期間出現問題時還原到 3.9 副本。