为了演示 Workiva 脚本在 Workiva 中的工作原理，我们构建了一个简单的脚本来更新电子表格中的单元格。您可以按照以下步骤在您自己的工作空间中复制该脚本。
注：目前仅可通过自定义 Workiva 实现脚本编写。了解更多。
要求
- 您的工作区必须启用 Workiva 脚本功能。了解更多关于Workiva脚本的信息。
- 要创建或编辑脚本，需要 脚本编辑器 角色。
- 本示例使用的 API 授权必须具有
file:write范围和对目标电子表格的访问权限。有关操作说明，请参阅 Workiva API 设置。 - 您必须生成 依赖 项才能直接从电子表格运行此脚本。这将包括与 Workiva 公共 API交互所需的“requests”库。
编写脚本
要在您的工作区中构建脚本，请按照以下步骤操作：
- 从主页，点击 + 创建 => 脚 本。
- 在右侧，输入剧本名称和简短描述。
-
转到屏幕中间的脚本编辑器，删除所有现有代码。复制并粘贴以下内容：
import os import time import requests AUTH_URL = "https://api.app.wdesk.com/oauth2/token" SS_API_URL = "https://api.app.wdesk.com/spreadsheets/" API_VERSION = "2026-01-01" REQUEST_TIMEOUT = 30 OPERATION_TIMEOUT = 120 CLIENT_ID = os.getenv("CLIENT_ID") CLIENT_SECRET = os.getenv("CLIENT_SECRET") SPREADSHEET_ID = os.getenv("SPREADSHEET_ID") SHEET_ID = os.getenv("SHEET_ID") HELLO_WORLD = os.getenv("HELLO_WORLD") class ApiAuth: def __init__(self): self._headers = { "Content-Type": "application/x-www-form-urlencoded;charset=UTF-8", "X-Version": API_VERSION, } def getAuthToken(self): tokenRes = requests.post( AUTH_URL, data={ "client_id": CLIENT_ID, "client_secret": CLIENT_SECRET, "grant_type": "client_credentials", }, headers=self._headers, timeout=REQUEST_TIMEOUT, ) tokenRes.raise_for_status() return tokenRes.json()["access_token"] class SSApi: def __init__(self, accessToken): self._accessToken = "Bearer " + accessToken self._ssApiUrl = ( SS_API_URL + SPREADSHEET_ID + "/sheets/" + SHEET_ID + "/values/A2:H" ) self._headers = { "Authorization": self._accessToken, "X-Version": API_VERSION, } def getRawData(self): dataRes = requests.get( self._ssApiUrl, headers=self._headers, timeout=REQUEST_TIMEOUT, ) dataRes.raise_for_status() rawData = dataRes.json() return rawData["data"][0]["values"] def waitForOperation(self, operationUrl): deadline = time.monotonic() + OPERATION_TIMEOUT while time.monotonic() < deadline: operationRes = requests.get( operationUrl, headers=self._headers, timeout=REQUEST_TIMEOUT, ) operationRes.raise_for_status() operation = operationRes.json() if operation["status"] == "completed": return if operation["status"] == "failed": raise RuntimeError( operation.get("failureReason", "Spreadsheet update failed") ) time.sleep(float(operationRes.headers.get("Retry-After", "2"))) raise TimeoutError("电子表格更新在超时前未完成") def updateRange(self, sheetId, range, values): url = ( SS_API_URL + SPREADSHEET_ID + "/sheets/" + sheetId + "/values/" + range ) print("更新范围：", url) print("值：", values) dataRes = requests.put( url, headers=self._headers, json=values, timeout=REQUEST_TIMEOUT, ) dataRes.raise_for_status() operationUrl = dataRes.headers.get("Location") if not operationUrl: operationUrl = dataRes.json().get("operationLocation") if not operationUrl: raise RuntimeError("电子表格更新未返回操作 URL") self.waitForOperation(operationUrl) def write_tier_data(ssApi): ssApi.updateRange(SHEET_ID, "A1", {"values": [[HELLO_WORLD]]}) def main(): authToken = ApiAuth().getAuthToken() ssApi = SSApi(authToken) write_tier_data(ssApi) print("调用 main") main() - 按一下“保存”(Save)。
此时，您应该确保 已为此脚本生成必要的依赖 项。
运行脚本
运行此脚本前，必须先生成依赖项。依赖包包括用于调用 Workiva 公共 API 的requests库。
- 打开脚本后，点击屏幕顶部菜单栏中的 运行脚本 。
- 输入访问电子表格 API 所需的参数、电子表格和工作表 ID 以及单元格的文本内容。点击 运行脚本。
注：ID 可在电子表格的 URL 中找到： /spreadsheet/{spreadsheetId}/sheet/{sheetId}.
要验证脚本是否执行完毕，请检查电子表格中更新后的单元格。
直接从电子表格运行脚本
Workiva 自动化通过环境变量提供电子表格和工作表 ID，但不传递自定义运行时输入。要将此脚本与自动化一起使用，请替换原始脚本中的运行时输入声明。限制脚本的访问权限，只允许授权用户访问，因为拥有源代码权限的用户可以查看脚本代码中定义的值。
代替：
CLIENT_ID = os.getenv("CLIENT_ID") CLIENT_SECRET = os.getenv("CLIENT_SECRET") SPREADSHEET_ID = os.getenv("SPREADSHEET_ID") SHEET_ID = os.getenv("SHEET_ID") HELLO_WORLD = os.getenv("HELLO_WORLD")和：
CLIENT_ID = "您的客户端 ID" CLIENT_SECRET = "您的客户端密钥" SPREADSHEET_ID = os.getenv("输入电子表格 ID") SHEET_ID = os.getenv("输入电子表格 SHEET_ID") HELLO_WORLD = "Hello World"- 请将凭证占位符和单元格值替换为您的实际值。
- 保存脚本。
- 在电子表格的“自动化”面板中，创建一个带有 手动执行 触发器的自动化。
- 添加一个 执行脚本 操作并选择此脚本。
- 保存并运行自动化流程。
要了解更多信息，请参阅 使用自动化执行脚本 。