利用 Workiva 脚本和 API 可以显著简化操作和工作流程。与所有脚本项目一样，遵循代码开发和版本控制的最佳实践可以带来有效的项目管理、连续性和成功。
以下是一些关于 Workiva 脚本编写的技巧和窍门，可用于项目开发和工作流程。
Workiva脚本编辑器
Workiva 脚本编辑器可帮助您管理 Workiva 中的代码、运行脚本、监控生产运行以及解决问题。对于高级开发、测试、代码检查、调试和版本控制，请使用专用开发环境。
开发环境
如果您已经拥有企业开发环境和版本控制系统，我们建议您将其用于所有脚本开发和测试。
开发环境的关键组件包括 代码编辑 器（流行的例子包括 VSCode、 PyCharm、 Jupyter等）和 版本控制系统 （流行的例子包括 GitHub 和 GitLab） 。对于非工程师或不喜欢使用命令行界面的人来说，有一些轻量级工具，例如 GitHub Desktop 和 SourceTree ，可以简化版本控制系统中的工作。
如果您还没有开发环境，请考虑搭建一个。同时，请务必保存脚本副本（在任何更改/更新之前、期间和之后），并确保将脚本的开发/工作版本与生产版本分开，以减少意外覆盖。
脚本开发
在脚本项目的开发和测试过程中，请考虑遵循主流的 Python 和版本控制实践：
Python
尽可能遵循 PEP 8 - Python 代码风格指南 。代码一致性对可读性、可维护性和连续性都大有裨益。
要构建健壮、可靠且可扩展的生产级 Python 脚本，请务必关注以下关键领域：
- 身份验证:使用 API 授权请求 Workiva API 的短期访问令牌。仅授予集成所需的权限范围，保护客户端 ID 和密钥，并且绝不将凭据存储在日志中。有关说明，请参阅 Workiva API 设置。
- 模块化： 将大型脚本拆分成更小、独立和可重用的单元（函数、类、模块/文件）。这样一来，脚本就更容易阅读、测试、调试和长期维护。
- 日志记录： 包含有用的、结构化的日志记录，以捕获重要事件、状态更改、警告和错误。绝不记录凭据、访问令牌、运行时输入或其他敏感信息。
-
错误处理： 添加错误处理逻辑，使脚本更加健壮、可靠和用户友好，能够优雅地处理意外情况，而不是崩溃。
注： 使用错误处理来解决 意外情况。不要依赖它来弥补或掩盖脚本设计欠佳导致的性能问题（例如，如果您的脚本生成大量
429: Too Many Requests响应，则应重构脚本设计和工作流程以优化 API 调用，不应依赖有效处理大量 429 响应来保证脚本成功运行） 。 - 文档： 解释代码的功能以及如何使用它（内部通过注释和文档字符串，外部通过用户指南（README）），使其他开发人员和未来的您能够有效且高效地理解和修改脚本。
- 版本跟踪： 将 语义化版本控制 融入到您的脚本项目中，以帮助进行版本跟踪。
- 命名约定：为您的脚本使用清晰的命名约定（例如：
customername_function_v1_3.py）。 - 测试并验证代码合规性。使用 Python 包，例如
ruff和flake8来执行 lint 和格式检查。您还可以利用流行的代码编辑器提供的丰富插件工具和扩展程序，获取代码格式化和代码检查方面的指南和帮助。 -
AI 代码辅助： 有许多免费和付费的 AI 代码工具可供您使用，以帮助进行调试和优化。
注： 虽然人工智能代码助手很有帮助，但它们并不能取代开发高级脚本和自动化程序所需的知识和专业技能。
版本控制
- 拥有单一数据源： 使用版本控制系统作为脚本项目的中央存储库和单一数据源。经常提交更改，以确保所有最新的开发工作和测试都被捕获并集中存储。
- 完整记录更改： 在版本控制系统中的所有提交和拉取请求中尽可能添加详细信息和支持信息，以记录所有更改（谁进行了更改、更改了什么、为什么进行了更改等）。
工作流程最佳实践
在开发、测试和部署脚本时，遵循工作流程最佳实践将有助于最大限度地提高脚本性能，并最大限度地减少潜在的错误和问题。开发工作流程的一些主要支柱包括：
- 在开发环境中进行初始开发和单元测试。
- 将脚本传输到暂存工作区或其他受控区域，以便在 Workiva 中进行集成测试。使用非生产数据。
- 只有在测试完成后才能将脚本部署到生产工作区。
将代码转移至 Workiva
开发和测试完成后，将代码移交给 Workiva。您可以在脚本编辑器中手动更新源代码，但 我们强烈建议您使用 Workiva 脚本 API 从版本控制系统 自动部署。自动化部署可以节省时间、减少人为错误，并有助于使 Workiva 与版本控制源保持同步。
自动源代码部署需要具有script:write作用域的 API 授权。如果部署还检索或验证源，则需要script:read。每次 API 请求都发送X-Version: 2026-01-01。有关授权说明，请参阅 Workiva API 设置。有关支持的操作，请参阅 脚本 API 指南。
运行和监控脚本
脚本可以直接从脚本编辑器、链、脚本 API 或集成自动化中触发。无论脚本是如何触发的，我们都建议您使用脚本编辑器来监控运行情况并解决问题。
日志记录
脚本编辑器包含一个日志部分。我们强烈建议您的脚本使用详细、结构化的日志记录来记录重要操作、状态变化、警告和错误。良好的日志记录对于监控性能、排除故障和了解脚本行为至关重要。
标准的 Pythonlogging包可以包含时间戳、日志级别和消息等有用信息。使用适当的级别，例如DEBUG、INFO、WARNING和ERROR，来控制生成的信息量。请勿记录凭据、访问令牌、运行时输入或其他敏感信息。
许多高级用户还添加了将日志推送到同一工作区中指定的 Workiva 电子表格的功能。这样可以更方便地访问日志，更快地进行分析，并高效地查询日志。以下是 Workiva 电子表格的日志输出示例（电子表格和工作表 ID 已进行模糊处理）：
调试和添加新功能
如果在脚本运行过程中出现任何问题，我们建议您在开发环境中进行调试和更新，而不是在生产环境中进行调试和更新。一旦这些修复/更新完成、测试并提交到您的版本控制系统，您就可以安全地将更新后的脚本推送回 Workiva。
向现有脚本添加新功能时，也应采用相同的工作流程：在开发环境中执行所有更新和测试。所有脚本更新完成后，经过成功测试并提交到版本控制系统后，即可将更新后的脚本推送到 Workiva。