Wykorzystanie skryptów i interfejsów API firmy Workiva może znacząco usprawnić operacje i przepływy pracy. Podobnie jak w przypadku wszystkich projektów skryptowych, stosowanie się do najlepszych praktyk w zakresie tworzenia kodu i kontroli wersji zapewnia efektywne zarządzanie projektem, ciągłość i sukces.
Poniżej znajdziesz kilka wskazówek i trików dotyczących skryptów Workiva, przydatnych przy tworzeniu projektów i przepływów pracy.
Edytor skryptów Workiva
Edytor skryptów Workiva pomaga zarządzać kodem w Workiva, uruchamiać skrypty, monitorować przebiegi produkcyjne i rozwiązywać problemy. Do zaawansowanych zadań związanych z rozwojem, testowaniem, analizą błędów, debugowaniem i kontrolą wersji należy używać dedykowanego środowiska programistycznego.
Środowisko programistyczne
Jeśli dysponujesz już środowiskiem programistycznym dla przedsiębiorstw i systemem kontroli wersji, zalecamy korzystanie z nich przy tworzeniu i testowaniu skryptów.
Kluczowe elementy środowiska programistycznego obejmują Edytor kodu (popularne przykłady to VSCode , PyCharm , Jupyter itp.) i System kontroli wersji (popularne przykłady to GitHub i GitLab ). Dla osób niebędących inżynierami lub tych, które wolą nie pracować w interfejsie wiersza poleceń, dostępne są lekkie narzędzia, takie jak GitHub Desktop i SourceTree , które mogą usprawnić pracę w systemach kontroli wersji.
Jeżeli nie posiadasz środowiska programistycznego, rozważ jego utworzenie. W międzyczasie pamiętaj o zapisywaniu kopii swoich skryptów (przed, w trakcie i po wszelkich zmianach/aktualizacjach) i pamiętaj o trzymaniu wersji roboczej/rozwojowej skryptów oddzielnie od wersji produkcyjnych, aby ograniczyć ryzyko przypadkowego nadpisania.
Rozwój skryptów
Podczas opracowywania i testowania projektów skryptowych należy wziąć pod uwagę następujące główne praktyki dotyczące języka Python i kontroli wersji:
Pyton
W miarę możliwości stosuj się do wytycznych PEP 8 - Style Guide for Python Code . Spójność kodu jest niezwykle korzystna dla czytelności, łatwości utrzymania i ciągłości kodu.
Aby tworzyć solidne, niezawodne i skalowalne skrypty Pythona na poziomie produkcyjnym, należy skupić się na kluczowych obszarach, takich jak:
- Uwierzytelnianie : Użyj przyznania API, aby zażądać krótkotrwałych tokenów dostępu do interfejsów API Workiva. Przyznawaj tylko zakresy wymagane przez integrację, chroń identyfikator klienta i tajny klucz oraz nigdy nie przechowuj danych uwierzytelniających w logach. Instrukcje znajdziesz w Konfiguracja interfejsu API Workiva .
- Modułowość: Podziel duże skrypty na mniejsze, niezależne i wielokrotnego użytku jednostki (funkcje, klasy, moduły/pliki). Dzięki temu skrypt jest łatwiejszy do czytania, testowania, debugowania i konserwacji w dłuższej perspektywie.
- Rejestrowanie: Dołącz przydatne, ustrukturyzowane rejestrowanie w celu przechwytywania ważnych zdarzeń, zmian statusu, ostrzeżeń i błędów. Nigdy nie rejestruj danych uwierzytelniających, tokenów dostępu, danych wejściowych środowiska wykonawczego ani innych poufnych informacji.
-
Obsługa błędów: Dodaj logikę obsługi błędów, aby skrypty były bardziej odporne, niezawodne i przyjazne dla użytkownika dzięki płynnemu zarządzaniu nieoczekiwanymi sytuacjami zamiast powodowania awarii.
Uwaga: Użyj obsługi błędów, aby poradzić sobie z nieoczekiwanymi sytuacjami . Nie należy na nim polegać w celu kompensacji lub maskowania konsekwencji wydajnościowych nieoptymalnego projektu skryptu (na przykład, jeśli skrypt generuje dużą liczbę odpowiedzi
429: Zbyt wiele żądań , projekt skryptu i przepływ pracy należy przebudować w celu zoptymalizowania wywołań API; nie należy polegać na efektywnym obsłudze dużej liczby odpowiedzi 429 dla powodzenia skryptu). - Dokumentacja: Wyjaśnia, co robi kod i jak go używać (zarówno wewnętrznie za pomocą komentarzy i docstringów, jak i zewnętrznie za pomocą podręczników użytkownika (README), umożliwiając innym programistom i przyszłym użytkownikom zrozumienie i skuteczną i wydajną modyfikację skryptu.
- Śledzenie wersji: Włącz wersjonowanie semantyczne do swoich projektów skryptowych, aby ułatwić śledzenie wersji.
- Konwencje nazewnictwa: Używaj jasnych konwencji nazewnictwa dla swoich skryptów (na przykład:
customername_function_v1_3.py). - Testowanie i weryfikacja zgodności kodu. Użyj pakietów Pythona, takich jak
ruffiflake8 ,aby wykonać kontrolę lint i formatowania. Można również wykorzystać rozbudowaną gamę dodatkowych narzędzi i rozszerzeń dostępnych dla popularnych edytorów kodu, które stanowią przewodniki i pomoc w formatowaniu i analizowaniu kodu. -
Pomoc w kodzie AI: dostępnych jest wiele darmowych i płatnych narzędzi do kodowania AI, z których możesz skorzystać, aby uzyskać pomoc w debugowaniu i optymalizacji.
Uwaga: Choć pomocni są asystenci kodu AI, nie zastępują oni wiedzy i doświadczenia niezbędnych do tworzenia zaawansowanych skryptów i automatyzacji.
Kontrola wersji
- Korzystaj z jednego źródła prawdy: Używaj swojego systemu kontroli wersji jako centralnego repozytorium i jednego źródła prawdy dla swoich projektów skryptowych. Często zatwierdzaj zmiany, aby mieć pewność, że wszystkie najnowsze prace rozwojowe i testowe zostaną przechwycone i centralnie zapisane.
- Dokładnie udokumentuj zmiany: Dodaj jak najwięcej szczegółów i informacji pomocniczych do wszystkich zatwierdzeń i żądań ściągnięcia w systemie kontroli wersji, aby udokumentować wszystkie zmiany (kto wprowadził zmianę, na czym ona polega, dlaczego została wprowadzona itp.).
Najlepsze praktyki dotyczące przepływu pracy
Podczas opracowywania, testowania i wdrażania skryptów przestrzeganie najlepszych praktyk przepływu pracy pomoże zmaksymalizować wydajność skryptów i zminimalizować potencjalne błędy i problemy. Oto niektóre z głównych filarów procesu prac rozwojowych:
- Przeprowadź wstępne prace rozwojowe i testy jednostkowe w swoim środowisku programistycznym.
- Przenieś skrypt do tymczasowego obszaru roboczego lub innego kontrolowanego obszaru w celu przeprowadzenia testów integracyjnych w Workiva. Użyj danych niepochodzących z produkcji.
- Wdróż skrypt w środowisku produkcyjnym dopiero po zakończeniu testów.
Przenoszenie kodu do Workiva
Po zakończeniu prac nad rozwojem i testowaniem prześlij kod do Workiva. Źródła można aktualizować ręcznie w Edytorze skryptów, ale zdecydowanie zalecamy automatyzację wdrażania z poziomu systemu kontroli wersji za pomocą interfejsu API skryptów Workiva. Automatyczne wdrażanie oszczędza czas, zmniejsza liczbę błędów ręcznych i pomaga zachować synchronizację Workiva ze źródłem objętym kontrolą wersji.
Do automatycznego wdrażania źródła wymagane jest przyznanie interfejsu API z zakresem script:write . Jeśli wdrożenie obejmuje również pobieranie lub weryfikowanie źródeł, wymagane jest script:read . Wysyłaj X-Version: 2026-01-01 z każdym żądaniem API. Instrukcje dotyczące przyznawania grantów można znaleźć w Konfiguracja interfejsu API Workiva . Obsługiwane operacje można znaleźć w przewodniku po interfejsie API skryptów .
Uruchamianie i monitorowanie skryptów
Skrypty można uruchamiać bezpośrednio z Edytora skryptów, z Łańcuchów, z Interfejsów API skryptów lub ze Zintegrowanych automatyzacji. Niezależnie od sposobu uruchamiania skryptów, zalecamy korzystanie z Edytora skryptów do monitorowania uruchomień i rozwiązywania problemów.
Rejestrowanie
Edytor skryptów zawiera sekcję Dzienniki . Zdecydowanie zalecamy, aby Twoje skrypty korzystały ze szczegółowego, strukturalnego rejestrowania w celu rejestrowania ważnych operacji, zmian statusu, ostrzeżeń i błędów. Dobre rejestrowanie jest niezbędne do monitorowania wydajności, rozwiązywania problemów i zrozumienia zachowania skryptu.
Standardowy pakiet Python logging może zawierać przydatne informacje, takie jak znaczniki czasu, poziomy rejestrowania i komunikaty. Użyj odpowiednich poziomów, takich jak , DEBUG INFO , WARNING i ERROR , aby kontrolować ilość generowanych informacji. Nie rejestruj danych uwierzytelniających, tokenów dostępu, danych wejściowych środowiska wykonawczego ani innych poufnych informacji.
Wielu zaawansowanych użytkowników uwzględnia również funkcjonalność umożliwiającą przesyłanie dzienników do wyznaczonego arkusza kalkulacyjnego Workiva w tym samym obszarze roboczym. Umożliwia to łatwiejszy dostęp, szybszą analizę i efektywne przeszukiwanie dzienników. Poniżej znajduje się przykład danych wyjściowych dziennika do arkusza kalkulacyjnego Workiva (identyfikatory arkusza kalkulacyjnego i arkusza zostały zaciemnione):
Debugowanie i dodawanie nowych funkcji
Jeżeli w trakcie działania skryptu wystąpią jakiekolwiek problemy, zalecamy przeprowadzenie debugowania i aktualizacji w środowisku programistycznym, a nie produkcyjnym. Gdy poprawki/aktualizacje zostaną ukończone, przetestowane i zatwierdzone w systemie kontroli wersji, możesz bezpiecznie przesłać zaktualizowany skrypt z powrotem do Workiva.
Ten sam przepływ pracy należy zastosować podczas dodawania nowych funkcji do istniejących skryptów: wszystkie aktualizacje i testy należy wykonywać w środowisku programistycznym. Gdy wszystkie aktualizacje skryptu zostaną ukończone, pomyślnie przetestowane i zatwierdzone w systemie kontroli wersji, możesz przesłać zaktualizowany skrypt do Workiva.