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