Workiva スクリプトと API を活用することで、オペレーションとワークフローを大幅に効率化できます。すべてのスクリプトプロジェクトと同様に、コード開発とバージョンコントロールのベストプラクティスに従うことが、効果的なプロジェクト管理、継続性、そして成功につながります。
プロジェクト開発とワークフローにおけるWorkivaスクリプトのヒントとコツをご紹介します。
Workivaスクリプト編集者
Workiva スクリプトエディタを使用すると、Workiva 内のコードの管理、スクリプトの実行、本番環境での実行状況の監視、および問題のトラブルシューティングを行うことができます。高度な開発、テスト、リンティング、デバッグ、およびバージョン管理を行う場合は、専用の開発環境を使用してください。
開発環境
すでにエンタープライズ開発環境とバージョンコントロールシステムを持っている場合は、スクリプトの開発とテスト中すべてにそれを使用することをお勧めします。
開発環境のキーコンポーネントには、コード編集者 （一般的な例として、VSCode 、PyCharm 、Jupyter などがあります）、バージョンコントロールシステム （一般的な例として、GitHub 、GitLab などがあります）が含まれます。非エンジニアやコマンドラインインターフェイスでの作業を好まない人には、GitHub Desktop やSourceTree など、バージョンコントロールシステムでの作業を効率化できる軽量ツールがあります。
開発環境がない場合は、設定を検討してください。その間、スクリプトのコピーを（変更前、変更中、変更後にかかわらず）保存し、スクリプトの開発/作業バージョンを本番バージョンから切り離して保管するようにしてください。
スクリプト開発
スクリプトプロジェクトの開発とテスト中、Pythonとバージョンコントロールの主要なプラクティスに従うことを検討してください：
Python
PEP 8 - Style Guide for Python Code にできるだけ従いましょう。コードの一貫性は、可読性、保守性、継続性のために非常に有益です。
堅牢で信頼性が高く、スケーラブルなプロダクションレベルの Python スクリプトを構築するには、次のようなキーにフォーカスしてください：
- 認証: APIグラントを使用して、Workiva API用の短期間有効なアクセストークンをリクエストします。統合に必要なスコープのみを付与し、クライアントIDとシークレットを保護し、認証情報をログに保存しないようにしてください。手順については、および「Workiva API の設定」 を参照してください。
- モジュール性： 大きなスクリプトを、より小さく、独立した、再利用可能な単位（関数、クラス、モジュール/ファイル）に分割します。これにより、スクリプトを読みやすくし、テストしやすくし、デバッグしやすくし、時間の経過とともに保守しやすくします。
- ロギング： 重要なイベント、ステータスの変化、警告、エラーを記録するために、有用で構造化されたロギングを実装してください。認証情報、アクセストークン、実行時の入力データ、その他の機密情報は、決して記録しないでください。
-
エラー処理： エラー処理用のロジックを含むことで、スクリプトをクラッシュさせることなく、予期せぬ状況を適切に管理し、より堅牢で信頼性が高く、ユーザーフレンドリーなものにします。
メモ: 不測の事態に対処するためにエラー処理を使用する 。スクリプトの設計が最適でないことによるパフォーマンス上の問題を、これを頼りに補ったり隠したりしてはいけません（たとえば、スクリプトが大量の「
429: Too Many Requests といったレスポンスを大量に生成する場合、スクリプトの設計とワークフローを見直し、API呼び出しを最適化すべきであり、スクリプトの成功を、大量の429レスポンスを適切に処理できることに依存してはなりません）。 - 説明書： コードが何をするのか、どのように使うのかを説明します (内部的にはコメントや docstrings を、外部的にはユーザーガイド (README) を使って)。
- バージョン追跡： セマンティック・バージョニング をスクリプト・プロジェクトに組み込み、バージョン追跡を支援します。
- 命名規則： スクリプトにはクリアな名称規則を使用してください (例:
customername_function_v1_3.py)。 - コードのコンプライアンスをテストして検証してください。
ruffやflake8などの Python パッケージを使って、lint や書式設定を行いましょう。また、一般的なコード編集者が利用できるアドオンツールや拡張機能を活用して、ガイドを作成したり、コードの書式設定やリンティングを支援したりすることもできます。 -
AIコードアシスト： デバッグや最適化のヘルプとして活用できる無料および有料のAIコードツールが多数あります。
メモ： AIコードアシスタントはヘルプではありますが、高度なスクリプトや自動化を開発するために必要な知識や専門性に取って代わるものではありません。
バージョンコントロール
- 信頼できる唯一の情報源： バージョン管理システムを、スクリプトプロジェクトの中央リポジトリおよび信頼できる唯一の情報源として使用します。頻繁に変更をコミットして、最新の開発作業とテスト中がすべて把握され、一元的に保存されるようにしましょう。
- 変更を完全にドキュメント化します： すべての変更をドキュメント化するために、バージョンコントロールシステムのすべてのコミットやプルリクエストに、可能な限り詳細で裏付けとなる情報を追加します（誰が変更したのか、何が変更されたのか、なぜ変更されたのか、など）。
ワークフローのベストプラクティス
スクリプトの開発、テスト、デプロイを行う場合、ワークフローのベストプラクティスに従うことで、スクリプトのパフォーマンスを最大化し、潜在的なエラーや問題を最小限に抑えることができます。開発ワークフローの主な柱には、次のものが含まれます：
- 開発環境にて、初期開発および単体テストを実施してください。
- スクリプトを、Workivaでの統合テストを行うために、ステージングワークスペースまたはその他の管理された領域に移してください。本番環境以外のデータを使用してください。
- テストが完了してから、本番用ワークスペースにスクリプトをデプロイしてください。
Workivaへのコード転送
開発とテストが完了したら、コードをWorkivaに移行してください。スクリプトエディタでソースを手動で更新することも可能ですが、バージョン管理システムから Workiva Scripting API を使用してデプロイを自動化する ことを強くお勧めします。自動デプロイにより、時間を節約し、手作業によるミスを減らし、Workivaとバージョン管理されたソースとの同期を維持することができます。
ソースの自動デプロイには、スクリプトの「script:write」スコープを持つAPIアクセス権が必要です。デプロイ時にソースの取得や検証も行う場合は、スクリプトが必要です：read 。すべてのAPIリクエストに、X-Version: 2026-01-01を指定して送信してください。助成金の申請手順については、および「Workiva API の設定」 を参照してください。サポートされている操作については、『スクリプト API ガイド』（ ）を参照してください。
スクリプトの実行と監視
スクリプトは、スクリプトエディタ、チェーン、スクリプトAPI、または統合オートメーションから直接トリガーできます。スクリプトのトリガー方法にかかわらず、スクリプト エディタを使用して実行を監視し、問題のトラブルシューティングを行うことをお勧めします。
ログ
スクリプトエディタには、「」の「Logs」セクションが含まれています。スクリプトでは、重要な操作、ステータスの変化、警告、およびエラーを記録するために、詳細かつ構造化されたロギングを使用することを強くお勧めします。適切なログ記録は、パフォーマンスの監視、問題のトラブルシューティング、およびスクリプトの動作を理解するために不可欠です。
Pythonの標準ライブラリであるやといったロギングパッケージには、タイムスタンプ、ログレベル、メッセージなどの有用な情報が含まれています。 （DEBUG）、 、 （、 、および （INFO）、 、 （WARNING）ERROR）といった適切なレベルを使用して、出力される情報の量を制御してください。認証情報、アクセストークン、実行時の入力データ、その他の機密情報は記録しないでください。
多くの上級ユーザーは、ログを同じワークスペース内の指定の Workiva スプレッドシートにプッシュする関数も含みます。これにより、使用しやすく、分析が速くなり、ログのクエリが効率的になります。Workiva スプレッドシートへのログ出力例です（スプレッドシートとシート ID は難読化されています）：
デバッグと新規機能の追加
スクリプトの運用中に問題が発生した場合は、本番環境ではなく、開発環境でデバッグと更新を行うことをお勧めします。これらの修正/更新が完了し、テスト中で、バージョンコントロールシステムにコミットしたら、更新したスクリプトを安全にWorkivaにプッシュバックすることができます。
既存のスクリプトに新規機能を追加する場合も、これと同じワークフローを使用します。すべてのスクリプトの更新が完了し、正常にテストされ、バージョン管理システムにコミットされると、更新されたスクリプトを Workiva にプッシュできます。