Workiva 的 API 版本控制
應用程式介面 (API) 版本化是指派獨特的識別元給 API 設計的不同迭代器，以有效管理和傳達變更的重要實務。它的主要目的是維持向後相容性，以確保依賴舊版本的指令碼和應用程式不會在新的 API 版本發行時分解/中斷。這種穩定性可讓 API 提供者在不影響現有使用者的情況下，推出重大更新、錯誤修補和新的功能，並授與消費者所需的時間與控制項/控制措施，以便在他們準備好時轉移他們的系統。正確的 API 版本升階最終會促進一個可靠、可擴充且專業的開發生態系統。
2026-01-01 API 版本發佈
2026 年 1 月，Workiva 將發佈新的 API 版本，2026-01-01 。新的版本在多個領域都有顯著的改進，包括一致性改進、新的功能以及過時的舊功能。升級至 2026-01-01 版本的優點包括與最新 Workiva 平台功能的持續相容性增強了安全性、提高了性能，並能充分利用新的功能。
有關新的 API 版本的其他資訊，請參閱Workiva API 2026-01-01 升級指南 。
2022-01-01 API 版本過時
隨著 2026-01-01 版本的發行，較舊的 2022-01-01 版本將進入其過時輸入階段。對這個舊版本的支援將持續到 2029 年 1 月日落為止，而對 2022-01-01 原型端點的支援將於 2027 年 1 月結束。
附註： 2022-01-01 版本中的大部分原型端點已於 2026-01-01 版本升階為一般可用性 (GA)。
| 版本 | 狀態 | 端點鍵入型別式 | 日落日期 |
|---|---|---|---|
| 2026-01-01 | 一般可用性 (GA) | 全部 | 不適用 (目前) |
| 2022-01-01 | 已過時 | 原型 | 2027 年 1 月 |
| 2022-01-01 | 已過時 | GA | 2029 年 1 月 |
比較 API 版本
當發布新的版本時，Workiva 開發人員中心 (Workiva Developers Hub) 上該版本的 API 文件包括 Changelog 區段 (UI)/章節，其中包含該版本中 API 變更的詳細說明文件。2026-01-01 版本將有2026-01-01 升級指南 區段 (UI)/章節，內含該版本變更的完整攻略。
此外，有許多開放原始碼工具可用於在兩個不同的 API 版本上執行比較。這些型別式的工具可讓您快速且詳細地比較版本變更。開放原始碼工具oasdiff 有一個基於網頁的 Diff Calculator ，可讓您上傳兩個 API 版本設定檔案 (oas.yaml)，並針對分解/中斷變更、變更記錄或原始差異執行比較。它能以文字、yaml、json、html 及 markdown 輸出結果。
參考特定 API 版本 (資料)
Workiva API 利用X-Version 標頭指定要使用的 API 版本。如果未傳送 X-Version 標頭，則版本預設為過時的 2022-01-01 版本。
附註： 在 2029 年 1 月之後，X-Version 標頭將是必需的，沒有 X-Version 標頭的所有 API 呼叫都會失敗。
若要透過 Python 在 API 請求中指定版本，請在每個 API 請求的頁首/標頭中包括資料鍵/值對。例如：headers = {'X-Version': '2026-01-01'} 。
目前您可以指定2026-01-01 或2022-01-01 。
由於 2026-01-01 版本中有許多分解/中斷變更，因此必須確保為適用版本設定 X-Version 標頭，並確保 API 端點 URL 路徑和參數符合該版本的必要結構。此外，瞭解 API 呼叫的回應格式以及該格式在不同版本之間的任何潛在差異也很重要。
範例
GET 要求者範例
以下是在 Retrieve a List of Spreadsheets 終點中使用 GET 要求者的範例，適用於 2026-01-01 和 2022-01-01 版本 (這些範例包括不記名代用幣作為本文中混淆目的的代用幣變數)。
2026-01-01 版本
# 2026-01-01 版本 # 附註 X-Version 標頭和要求的 URL headers = { 'Accept': 'application/json', 'Authorization': token, 'X-Version': '2026-01-01', } resp = requests.get( 'https://api.app.wdesk.com/spreadsheets', headers = headers, )2022-01-01 版本
# 2022-01-01 版本 # 附註 X-Version 標頭和要求的 URL headers = { 'Accept': 'application/json', 'Authorization': token, 'X-Version': '2022-01-01', } resp = requests.get( 'https://api.app.wdesk.com/platform/v1/spreadsheets', headers = headers, )PATCH 要求者範例
以下是針對 2026-01-01 和 2022-01-01 版本，在 Partially Update a Single Section endpoint 中使用 PATCH 要求者的範例 (為了混淆的目的，這些範例包括在本文中作為令牌變數的 bearer 令牌)。
2026-01-01 版本
# 2026-01-01 版本 # 附註 X-Version 標頭和 requests URL headers = { 'Content-Type': 'application/json', 'Accept': 'application/json', 'Authorization':token, 'X-Version': '2026-01-01', } patch_op = [ "op": "replace", "path": "/name", "value": "My New Section Name" } ] resp = requests.patch ( https://api.app.wdesk.com/documents/{documentId}/sections/{sectionId}', json = patch_op, headers = headers, )2022-01-01 版本
# 2022-01-01 版本 # 附註 X-Version 標頭和要求者的 URL headers = { 'Content-Type': 'application/json', 'Accept': 'application/json', 'Authorization': token, 'X-Version': '2022-01-01', } patch_op = [ { "op": "replace", "path": "/name", "value": "My New Section Name" } ] resp = requests.patch( f'https://api.app.wdesk.com/platform/v1/documents/{documentId}/sections/{sectionId}', json = patch_op, headers = headers, )提示： 除了確保 URL 路徑和參數結構符合適用的 API 版本之外，請務必查看說明文件，以瞭解可用參數選項的詳細資訊。
例如，在上述部分更新單一區段的範例中，2022-01-01 版本有三個可用路徑選項 ( /name , /index , /parent )，但在 2026-01-01 版本則有超過三十個可用路徑選項。
指令碼與 API 版本的最佳做法
雖然您所需的特定 API 版本可能取決於從屬 (參照) 的啟用腳本和應用程式的狀態、升級到新的 API 版本的時間表或其他因素，以下是一些與指令碼和 API 版本相關的最佳做法。
務必指定 API 版本
切勿依賴 API 提供者的預設版本。在每次 API 呼叫中明確指定版本。透過明確指定版本，您可以控制腳本或應用程式執行的版本。
集中化版本常數
將 API 版本定義為單一、易於定位的常數或組態變數，放在指令碼頂端或單獨的組態檔案中。這可靠地簡化了疑難排解並提高了可維護性。範例：
# config.py 或在主腳本的頂端 API_VERSION = '2026-01-01「 # 在 requests 呼叫中 headers = { 」Accept': 'application/json', 'Authorization': token, 'X-Version'：API_VERSION, } resp = requests.get( 'https://api.app.wdesk.com/spreadsheets', headers = headers, )避免混合 API 版本
請勿嘗試在單一指令碼或應用程式中混合 API 版本。單一指令碼或應用程式中的所有 API 呼叫應參考相同的 Workiva API 版本 (例如，所有 API 呼叫應使用「2026-01-01」版本)。混合版本會使除錯、請求結構描述和回應格式變得複雜，使指令碼的行為難以預測，維護也變得更複雜。
隔離 API 互動邏輯
建立一個專用的模組或函數設定（通常稱為「wrapper」或「client」），以處理所有與外部 API 的通訊。此圖案將腳本的 「商業邏輯 」與 「API 通訊邏輯 」分開。如果 API 變更（例如，端點 URL 或請求/回應結構在新的 API 版本中變更），則只需更新封裝函數，而無需更新整個指令碼。
從容處理過時的端點和參數
從舊的 API 版本移除到新的 API 版本時，請預期端點和參數可能會被重新命名或移除。確保您的指令碼包括強大的錯誤處理與記錄，因為這可支援指令碼開發的最佳做法，並增加版本相關錯誤被擷取與記錄的機率。
有關指令碼最佳做法的其他資訊，請參閱Workiva Scripting：開發最佳做法文章。
過時監控與規劃
Workiva 將改為每年為新的主要版本提供兩個發佈視窗；春季和秋季。若在發佈日期臨近時沒有發生分解/中斷變更事件，且該期間的候選發佈版本為空，則 Workiva 將不會在該期間發佈新的 API 版本。
我們建議您積極追蹤Workiva API 開發人員中心 網站，訂閱Workiva 發行版本注意事項 ，並遵循已發佈的發佈和廢棄時間表。使用過時 API 版本的指令碼最終會被分解/中斷。瞭解 API 版本的日落（使用期限結束）日期，可讓您在日落日期 之前安排必要的升級工作。
指令碼遷移與驗證
為了確保 API 版本的無縫遷移，請建立並行測試策略：複製現有的生產腳本，僅修改該複製本以針對新的 API 版本（包括對頁首、URL 路徑和/或請求/回應結構的任何必要變更），然後同時測試新舊腳本，以比較並驗證功能和輸出。
透過在可控制的環境中並排執行它們，您可以使用穩定的舊指令碼作為標準，在完全切換到新版本並廢棄舊版本之前，監控並驗證新的指令碼所產生的功能和結果是否完全相同。