Tło
Chains współdziała z różnymi systemami innych firm, a także z platformą Workiva, wykorzystując REST API systemu, z którym się integruje. Wiele odpowiedzi REST API jest w formacie JSON, w tym różne interfejsy API Workiva. Chociaż odpowiedź JSON może być dobrze udokumentowana i spójnie ustrukturyzowana, trudno jest pracować z danymi w tym formacie. Polecenie Array to CSV w konektorze JSON to przydatny sposób na konwersję ładunku JSON do formatu tabelarycznego (wiersze i kolumny) do użytku na platformie Workiva.
W tym artykule zbadamy, jak korzystać z możliwości filtrowania tego polecenia, aby zwracać tylko te wyniki z ładunku JSON, które są potrzebne. Może to być konieczne, ponieważ odpowiedź REST API często zawiera więcej informacji niż jest to potrzebne, ponieważ ładunek jest generalnie określany przez programistów, a użytkownicy końcowi punktu końcowego często nie mają możliwości ograniczenia zakresu zwracanych danych.
Przykładowo, polecenie List Files Command konektora Workiva wykorzystuje punkt końcowy Retrieve a List of Files z interfejsu API Workiva Wdata, aby zwrócić listę wszystkich plików powiązanych z tabelą Wdata. Odpowiedź JSON dla tego punktu końcowego zawiera następujące informacje:
[
{
"created": "2024-01-24T12:01:53.000Z",
"id": "89b34ac927fe499abf944571ded77983",
"metadata": {
"column1": {},
"column2": {}
},
"name": "executions_2024-01.csv",
"numRecords": 108808,
"originalFileSize": 26226080,
"status": "IMPORTED",
"tableId": "bafe350ebff74a2dbc11262245483dee",
"updated": "2024-01-24T12:02:03.000Z",
"userId": "HzU1OTQwMTMxODMzMTE4NzI",
"version": 1
},
{
"created": "2023-12-18T15:06:56.000Z",
"id": "62f3d0b79b724776a4fae8bf25f711f1",
"metadata": {
"column1": {},
"column2": {}
},
"name": "executions_2023-12.csv",
"numRecords": 101789,
"originalFileSize": 24226080,
"status": "IMPORTED",
"tableId": "bafe350ebff74a2dbc11262245483dee",
"updated": "2023-12-18T15:06:56.000Z",
"userId": "HzU1OTQwMTMxODMzMTE4NzI",
"version": 1
}
]
Polecenie Array to CSV pozwala nam wybrać tylko te pola, które możemy pobrać z odpowiedzi JSON. Na przykład, możemy wybrać pola id, name i status, określając je w sekcji wprowadzania kolumn polecenia. Polecenie wyodrębni każdy identyfikator pliku, nazwę i status z odpowiedzi JSON i utworzy wiersz dla każdego pliku w odpowiedzi JSON.
Kontynuując powyższy przykład z plikami list, częstym przypadkiem użycia na platformie Workiva jest potrzeba aktualizacji danych (pliku) w tabeli Wdata. Aby zaimportować zaktualizowany zestaw danych (plik), istniejący zestaw danych musi zostać usunięty z tabeli, ponieważ Wdata nie zezwala na wiele plików o tej samej nazwie. Aby usunąć istniejący plik, należy pobrać jego identyfikator i status (Staged lub Imported).
Jednym z podejść do pobierania tych informacji jest konwersja ładunku List Files JSON do formatu tabelarycznego przy użyciu polecenia Array to CSV. Następnie użyj polecenia Tabular Transformation Smart Filter Rows, aby wyodrębnić pojedynczy wiersz z informacjami o pliku. Następnie użyj polecenia Tabular Transformation Extract Value, aby pobrać ID pliku i status. Na potrzeby tego artykułu nazwiemy to podejściem Legacy.
Korzystanie z filtrów
Wejście Filter umożliwia filtrowanie odpowiedzi JSON nie tylko pod względem pól (kolumn) do wyboru, ale także elementów (wierszy), które zostaną pobrane z ładunku JSON. Jest to potężny mechanizm umożliwiający wybór konkretnych potrzebnych danych, co poprawia wydajność procesu integracji. Filtr pozwala na użycie jednego lub więcej elementów w ładunku JSON w celu ograniczenia liczby pobieranych elementów (wierszy).
Kryterium filtra składa się z 3 komponentów - ścieżki elementu, wartości porównania i operatora. Kryteria muszą mieć wartość true lub false. Gdy kryteria filtrowania zwrócą wartość true, rekord zostanie wyodrębniony z ładunku JSON zgodnie z definicją Command Columns i utworzony jako wiersz w wynikowym pliku CSV. Na przykład:
- Czy status pliku jest równy Staged?
W tym przykładzie status pliku to ścieżka elementu, equal to operator, a Staged to wartość porównania. Każdy rekord w ładunku JSON, w którym status pliku to Staged, tworzy wiersz w CSV zawierający definicję kolumn w konfiguracji poleceń. W tym przykładzie są to ID, nazwa i status.
Ścieżka elementu
Aby określić filtr, ścieżka do elementu musi być znana. Na przykład w odpowiedzi List Files ścieżka do elementu Status to:
@.status
Wartość powiązana z elementem jest pobierana podczas wykonywania polecenia. W powyższym przykładzie ładunku byłaby to wartość IMPORTED dla elementu status .
Uwaga: Ścieżka elementu musi rozpoczynać się od symbolu (@).
Wartość porównawcza
Wartość porównania to wartość, z którą porównywana jest wartość ścieżki elementu. Wartość porównania może być wartością statyczną zdefiniowaną w konfiguracji polecenia lub może wykorzystywać zmienną lub wartość wyjściową, która jest określana podczas wykonywania.
Operator
Operator określa typ oceny, która zostanie przeprowadzona w celu filtrowania danych.
Uwaga: Wymagana jest spacja między ścieżką elementu a operatorem , a także między operatorem a wartością porównania.
Obsługiwani operatorzy
| Typ operatora | Operator | Użyj |
| Liczbowy | <</td> | Sprawdź, czy wartość elementu jest mniejsza niż wartość porównania |
| Liczbowy | <= | Sprawdź, czy wartość elementu jest mniejsza lub równa wartości porównania |
| Liczbowy | > | Sprawdź, czy wartość elementu jest większa niż wartość porównania |
| Liczbowy | >= | Sprawdź, czy wartość elementu jest większa lub równa wartości porównania |
| Logiczny / Tekstowy | == |
Sprawdź, czy wartość elementu jest równa (identyczna) z wartością porównania. Wartość oceny musi być ujęta w podwójne cudzysłowy ("") i jest CASE-SENSITIVE. Symbole wieloznaczne są NIE obsługiwane. |
| Logiczny / Tekstowy | != |
Sprawdź, czy wartość elementu jest nie równa wartości porównania. Wartość oceny musi być ujęta w podwójne cudzysłowy ("") i jest CASE-SENSITIVE. Symbole wieloznaczne są NIE obsługiwane. |
| Logiczny / Tekstowy | && | Operator AND, który umożliwia ocenę wielu ścieżek filtrowania i/lub kryteriów. Użycie tego operatora zwraca tylko te rekordy, dla których wszystkie warunki mają wartość true. |
| Logiczny / Tekstowy | || | Operator OR , który umożliwia ocenę wielu ścieżek filtrowania i/lub kryteriów. Użycie tego operatora zwraca wszystkie rekordy, dla których co najmniej jeden z warunków ma wartość true. |
Ważne jest, aby wziąć pod uwagę typ wartości, które istnieją dla ścieżki elementu podczas określania operatora. Na przykład użycie operatora greater than (>) potencjalnie spowodowałoby wyświetlenie pustego wyniku podczas oceny elementu zawierającego wartości tekstowe, ponieważ ocena liczbowa wartości tekstowej jest nielogiczna.
Składnia filtrów i przykładowe filtry
Wszystkie filtry muszą zaczynać się od znaku zapytania (?) i być zawarte w nawiasach.
Pojedyncze kryteria
Pojedyncze kryterium filtrowania wykorzystuje następującą składnię:
?(Element_Path Operator Comparison_Value)
?(@.name == "executions_2023-12.csv")
Ten filtr zwraca wszystkie rekordy, w których element name jest równy executions_2023-12.csv.
Wiele kryteriów
Filtr wielu kryteriów wykorzystuje następującą składnię:
?(Element_Path Operator Comparison_Value Logical_Operator Element_Path Operator Comparison_Value)
?(@.name == "executions_2023-12.csv" && @.status == "IMPORTED")
Ten filtr zwraca wszystkie rekordy, w których element name jest równy executions_2023-12.csv, a element status jest równy IMPORTED.
Przykładowa konfiguracja poleceń
W tym przykładzie wejście Filter jest skonfigurowane do oceny elementu name w ładunku JSON. Filtr używa zmiennych dla roku i miesiąca, które w tym przykładzie są wartościami wejściowymi środowiska wykonawczego. Umożliwia to filtrowi dynamiczne uwzględnianie roku i miesiąca określonego podczas wykonywania łańcucha.
Wartość filtrów
Filtry umożliwiają pobieranie tylko wymaganych wierszy z odpowiedzi JSON. Może to zmniejszyć rozmiar pliku wyjściowego generowanego przez polecenie, co może poprawić wydajność łańcucha.
Dodatkowo, podczas próby wyodrębnienia pojedynczego wiersza z odpowiedzi JSON, Dynamic Outputs może być użyty do wyodrębnienia tych konkretnych wartości z przefiltrowanego ładunku i udostępnienia ich do wykorzystania w kolejnych węzłach łańcucha.
Poniżej przedstawiono przykładowe definicje wyjścia dynamicznego.
Wynikowy łańcuch jest bardziej usprawniony dzięki pojedynczemu węzłowi (Array to CSV) wykonującemu operacje czterech węzłów wymagane w starszym podejściu. Ten usprawniony łańcuch działa również bardziej wydajnie, ponieważ wykonywana jest mniejsza liczba poleceń, a wynikowe dane wyjściowe są mniejsze.