Schemat gniazda importera Aggrega Wasm
Dokumentacja wygenerowana automatycznie. Nie należy jej edytować ręcznie — należy ją wygenerować ponownie z opublikowanego JSON Schema.
Identyfikator schematu: https://aggrega.ai/schemas/wasm-import-v1beta1.schema.json
Kształty komunikatów, które gniazdo pluginu importera przyjmuje (ImportInput) i emituje (ImportOutput). Importer przekształca obcy opis infrastruktury w encje Aggrega: odczytuje bajty źródłowe dla wskazanego formatu, mapuje każdy węzeł źródłowy na encję z katalogu i zwraca wyemitowane encje, podjęte decyzje mapowania, zgłoszone diagnostyki oraz wygenerowane pliki szkieletowe. Importer deklaruje obsługiwane formaty w swoim deskryptorze jako możliwości import:
Jeden z następujących kształtów
ImportInputImportOutput
Definicje
ImportInput
Ładunek, który otrzymuje gość importera: format źródłowy określający sposób odczytu bajtów, główne bajty źródłowe i nazwa pliku, z którego je odczytano, ewentualne nazwane źródła w przypadku importu wieloplikowego, opcjonalny nieprzezroczysty dokument opcji dostarczany przez konsumenta na potrzeby zachowania specyficznego dla importera, widok encji Components przechowywanych w katalogu obszaru roboczego oraz cel, dla którego import sporządza szkice.
| Właściwość | Typ | Wymagana | Opis |
|---|---|---|---|
format | string | tak | Nazwa importowanego formatu źródłowego, odpowiadająca jednej z ogłaszanych przez importer możliwości import: |
bytes | string | tak | Główne bajty źródłowe do zaimportowania, które importer odczytuje w nazwanym formacie: cały plik, gdy źródłem importu jest jeden plik, oraz pusta wartość, gdy jest nim katalog, którego pliki trafiają zamiast tego jako nazwane źródła. Każdy zestaw przenosi je we własnym typie pola — w postaci surowej, gdy ten typ jest typem bajtowym, oraz zakodowane w base64, gdy jest to ciąg znaków, który importer dekoduje, aby je odzyskać — a wygenerowany koder dokonuje konwersji między polem a postacią, w jakiej bajty są przesyłane. |
name | string | nie | Nazwa źródła importu, bez poprzedzającego ją katalogu, aby importer mógł wskazać źródło w tym, co zgłasza, i w tym, co tworzy jako szkic. Gdy źródłem jest jeden plik, jest to nazwa bazowa pliku: główne bajty nie docierają jako nazwane źródło, więc jest to jedyna nazwa, jaką mają. Gdy źródłem jest katalog, jest to nazwa bazowa katalogu, a pliki katalogu nadal docierają jako nazwane źródła, każdy pod własną nazwą, przy pustych głównych bajtach. Nieobecne, gdy źródło nie ma nazwy do przekazania. |
sources | ImportSource[] | nie | Nazwane źródła, każde z własnymi bajtami, na jednej liście posortowanej według nazwy. Gdy źródłem importu jest katalog, występuje jedno źródło na każdy jego plik wybrany przez zadeklarowane wzorce plików importera, nazwane ścieżką rozdzielaną ukośnikami wewnątrz katalogu. Przenoszone są tu także pliki deklarowane pod with.sources przez dołączenie konfigurujące importer, każdy pod swoją nazwą bazową, a host odrzuca import, w którym plik odczytany z katalogu i jeden z tych plików mają tę samą nazwę. Nieobecne, gdy żadne z nich nie dostarcza plików. |
settings | any | nie | Nieprzezroczysty dokument opcji importu dostarczany przez konsumenta na potrzeby zachowania specyficznego dla importera. Host przekazuje go bez interpretacji; importer odczytuje dowolny kształt, który dokumentuje. Nieobecny, gdy konsument nie dostarcza opcji. |
catalog | CatalogProjection | nie | Widok encji Components przechowywanych we własnym katalogu obszaru roboczego — katalogu, z którego wybrano sam importer — dzięki któremu importer może rozważać je jako kandydatów przy mapowaniu węzła źródłowego na encję katalogu. Host buduje go wyłącznie z tego lokalnego katalogu i zawiera on tylko nazwy, wersje, etykiety i zadeklarowaną strukturę: nigdy wartości, wartości domyślnej ani sekretu. Jego kolejność jest stała, więc jeden katalog daje jedną sekwencję bajtów. Nieobecny, gdy katalog nie zawiera żadnej encji Component. |
target | string | nie | Możliwość dostawcy, dla której import sporządza szkice, na przykład compose lub helm: cel przekazany do importu albo, w przypadku importu, który odświeża wcześniejszy i sam nie wskazuje żadnego celu, cel zapisany przez ten wcześniejszy import. Importer zapisuje w szkicach jako deklaracje to, czego potrzebuje wyłącznie ten cel, i pomija to, czego potrzebuje wyłącznie inny cel. Host przekazuje go bez zmian, po sprawdzeniu, że encja Recipe z katalogu obszaru roboczego się z nim wiąże. Nieobecne, gdy import nie wskazuje żadnego celu. |
Dodatkowe właściwości są niedozwolone.
CatalogProjection
Katalog obszaru roboczego widziany przez importer: jeden wpis na każdą encję Component w katalogu, każdy z metadanymi, które importer rozważa przy ocenie kandydata.
| Właściwość | Typ | Wymagana | Opis |
|---|---|---|---|
components | CatalogComponent[] | tak | Jeden wpis na każdą nazwę encji Component w katalogu, posortowane według nazwy. Gdy katalog zawiera kilka wersji jednej encji Component, jej wpis opisuje wersję, na którą rozwiązywane jest odwołanie wskazujące encję Component bez wersji. |
Dodatkowe właściwości są niedozwolone.
CatalogComponent
Jedna encja Component z katalogu obszaru roboczego: jej nazwa i wersja, etykiety, nazwy kluczy deklarowane przez jej values i provides oraz gniazda deklarowane dla jej zależności. Encja Component rozszerzająca inną zawiera zarówno to, co dziedziczy, jak i to, co deklaruje sama.
| Właściwość | Typ | Wymagana | Opis |
|---|---|---|---|
name | string | tak | Nazwa encji Component zadeklarowana w jej metadata.name — nazwa, pod którą odwołuje się do niej encja Aggregate. |
version | string | tak | Wersja encji Component zadeklarowana w jej metadata.version. |
labels | mapa string | nie | Etykiety encji Component jako mapa string-string. Nieobecne, gdy nie ma żadnych. |
values | string[] | nie | Posortowane nazwy kluczy najwyższego poziomu deklarowane przez values encji Component. Wyłącznie lista nazw: nigdy nie zawiera wartości ani wartości domyślnej. Nieobecne, gdy jej values nie deklaruje żadnego klucza. |
provides | string[] | nie | Posortowane nazwy kluczy najwyższego poziomu deklarowane przez provides encji Component. Wyłącznie lista nazw: nigdy nie zawiera wartości. Nieobecne, gdy jej provides nie deklaruje żadnego klucza. |
sockets | CatalogSocket[] | nie | Gniazda deklarowane przez encję Component dla jej zależności, w kolejności deklaracji: w przypadku encji Component rozszerzającej inną najpierw występują gniazda dziedziczone, w kolejności, w jakiej deklaruje je rozszerzana encja Component, a po nich gniazda dodane. Nieobecne, gdy nie deklaruje żadnych. |
Dodatkowe właściwości są niedozwolone.
CatalogSocket
Jedno gniazdo deklarowane przez encję Component z katalogu dla jej zależności: nazwa gniazda i selektor etykiet, który musi spełniać zależność podłączona przez to gniazdo.
| Właściwość | Typ | Wymagana | Opis |
|---|---|---|---|
name | string | tak | Nazwa gniazda zadeklarowana w usesSchema encji Component. |
selector | string | tak | Selektor etykiet gniazda, dosłownie, w gramatyce w stylu Kubernetes, w której zapisuje go encja Component: etykiety, które musi mieć zależność podłączona przez to gniazdo. |
Dodatkowe właściwości są niedozwolone.
ImportSource
Jedno nazwane źródło w imporcie wieloplikowym lub katalogowym: nazwa lokalizująca źródło oraz jego własne bajty.
| Właściwość | Typ | Wymagana | Opis |
|---|---|---|---|
name | string | tak | Nazwa tego źródła w obrębie importu, na przykład względna ścieżka pliku. |
bytes | string | tak | Bajty tego źródła. Każdy zestaw przenosi je we własnym typie pola — w postaci surowej, gdy ten typ jest typem bajtowym, oraz zakodowane w base64, gdy jest to ciąg znaków, który importer dekoduje, aby je odzyskać — a wygenerowany koder dokonuje konwersji między polem a postacią, w jakiej bajty są przesyłane. |
Dodatkowe właściwości są niedozwolone.
ImportOutput
Ładunek zwracany przez gościa importera: encje wytworzone przez import, stojące za nimi decyzje mapowania, diagnostyka zgłoszona przez import oraz wytworzone pliki szkieletowe. Każde pole jest opcjonalne, więc import, który niczego nie rozwiązał, może zwrócić samą diagnostykę.
| Właściwość | Typ | Wymagana | Opis |
|---|---|---|---|
entities | EmittedEntity[] | nie | Encje wytworzone przez import, każda będąca odwołaniem do istniejącej encji katalogu albo szkicem treści encji. Nieobecne, gdy import nie wyemitował żadnych encji. |
decisions | ImportDecision[] | nie | Decyzje mapowania podjęte przez import, po jednej na każdy rozwiązany węzeł źródłowy, rejestrujące rozważanych kandydatów i dokonany wybór. Nieobecne, gdy import nie zarejestrował żadnych decyzji. |
diagnostics | Diagnostic[] | nie | Diagnostyka zgłoszona przez import — na przykład nierozwiązany węzeł źródłowy lub niejednoznaczne mapowanie. Nieobecna, gdy import nie zgłosił żadnej. |
files | ScaffoldFile[] | nie | Pliki szkieletowe wytworzone przez import obok encji, na przykład startowy agregat lub plik readme. Nieobecne, gdy import nie wytworzył żadnych plików. |
error | string | nie | Komunikat o niepowodzeniu ustawiany, gdy gość został uruchomiony, ale nie mógł ukończyć operacji; nieobecny w razie powodzenia. Różni się od diagnostyki przenoszonej przez wynik: diagnostyka zgłasza problemy wykryte podczas przebiegu, który mimo to dał wynik, natomiast błąd zgłasza, że sama operacja nie została ukończona. Host traktuje obecny błąd jako nieudane wywołanie pluginu. |
Dodatkowe właściwości są niedozwolone.
EmittedEntity
Jedna encja wytworzona przez import: jej rodzaj, nazwa i sposób emisji — odwołanie do istniejącej encji katalogu albo nowo naszkicowana treść encji.
| Właściwość | Typ | Wymagana | Opis |
|---|---|---|---|
kind | string | tak | Rodzaj wyemitowanej encji. Podstawowe importery emitują Component, Aggregate i Release; czytelnik toleruje każdy inny rodzaj. |
name | string | tak | Nazwa wyemitowanej encji. |
mode | string (enum) | tak | Sposób emisji encji: reference wskazuje istniejącą encję katalogu po nazwie, a draft zawiera nowo naszkicowaną treść encji. Dozwolone wartości: "reference", "draft" |
body | string | nie | Surowa treść YAML naszkicowanej encji. Pusta dla czystego odwołania, które wskazuje istniejącą encję zamiast szkicować nową. |
labels | mapa string | nie | Etykiety dołączane do wyemitowanej encji jako mapa string-string. Podstawowe importery pozostawiają ją pustą. |
annotations | mapa string | nie | Adnotacje dołączane do wyemitowanej encji jako mapa string-string. Podstawowe importery pozostawiają ją pustą. |
sourceRef | string | nie | Odwołanie do węzła źródłowego, z którego wyemitowano tę encję, dzięki czemu czytelnik może prześledzić jej pochodzenie w importowanym źródle. |
decisionRef | string | nie | Odwołanie do decyzji mapowania, która wytworzyła tę encję, łączące ją z rozważanymi kandydatami i dokonanym wyborem. |
Dodatkowe właściwości są niedozwolone.
ImportDecision
Jedna decyzja mapowania: węzeł źródłowy rozpoznany przez importer, rozważane kandydackie encje katalogu, wybrany kandydat oraz uzasadnienie wyboru.
| Właściwość | Typ | Wymagana | Opis |
|---|---|---|---|
sourceNode | DecisionSourceNode | tak | Węzeł źródłowy rozpoznany przez tę decyzję: węzeł, który importer odczytał ze źródła i zmapował na encję katalogu. |
candidates | ImportCandidate[] | nie | Kandydackie encje katalogu, które importer rozważył dla tego węzła źródłowego, każda z jej wynikiem i rozbiciem na sygnały, na którym ten wynik się opiera. Nieobecne, gdy importer nie rozważył żadnych kandydatów. |
chosen | DecisionChoice | nie | Kandydat wybrany przez importer dla tego węzła źródłowego oraz sposób, w jaki go wyemitował. Nieobecne, gdy importer nie dokonał wyboru. |
rationale | string | nie | Czytelne dla człowieka wyjaśnienie, dlaczego importer dokonał tego wyboru. |
swapHint | string | nie | Wskazówka opisująca, jak zamienić wybrane mapowanie na alternatywne, aby czytelnik mógł zmienić decyzję. |
Dodatkowe właściwości są niedozwolone.
DecisionSourceNode
Węzeł źródłowy rozpoznany przez decyzję mapowania: identyfikator, typ, jaki nadaje mu źródło, oraz czytelne dla człowieka podsumowanie jego parametrów.
| Właściwość | Typ | Wymagana | Opis |
|---|---|---|---|
id | string | tak | Identyfikator węzła źródłowego w importowanym źródle. |
type | string | tak | Typ węzła źródłowego w postaci, w jakiej nazywa go źródło. |
paramsSummary | string | tak | Czytelne dla człowieka podsumowanie parametrów węzła źródłowego, wyświetlane obok decyzji. |
Dodatkowe właściwości są niedozwolone.
ImportCandidate
Jedna kandydacka encja katalogu rozważona przez importer dla węzła źródłowego: kandydacki komponent, jego łączny wynik, poziom dopasowania, do którego należy wynik, oraz rozbicie na sygnały, na którym wynik się opiera.
| Właściwość | Typ | Wymagana | Opis |
|---|---|---|---|
componentName | string | tak | Nazwa kandydackiego komponentu katalogu. |
score | liczba | tak | Łączny wynik dopasowania kandydata, zagregowany z rozbicia na sygnały. |
tier | string | tak | Poziom dopasowania, do którego należy kandydat — zgrubny przedział wyniku. |
signals | CandidateSignals | tak | Rozbicie na sygnały, na którym opiera się wynik kandydata. |
Dodatkowe właściwości są niedozwolone.
CandidateSignals
Rozbicie na sygnały, na którym opiera się wynik kandydata: jeden wkład na każdy pasujący sygnał. Obiekt o stałych polach, dzięki czemu zbiór sygnałów jest stabilny, a format przesyłu deterministyczny.
| Właściwość | Typ | Wymagana | Opis |
|---|---|---|---|
table | liczba | tak | Wkład do wyniku z sygnału tabeli mapowań. |
category | liczba | tak | Wkład do wyniku z sygnału kategorii. |
domainLabels | liczba | tak | Wkład do wyniku z sygnału etykiet domenowych. |
shape | liczba | tak | Wkład do wyniku z sygnału kształtu. |
name | liczba | tak | Wkład do wyniku z sygnału nazwy. |
Dodatkowe właściwości są niedozwolone.
DecisionChoice
Kandydat wybrany przez decyzję mapowania: docelowa encja katalogu, sposób jej emisji oraz poziom dopasowania wyboru.
| Właściwość | Typ | Wymagana | Opis |
|---|---|---|---|
target | string | tak | Nazwa wybranej docelowej encji katalogu. |
mode | string | tak | Sposób emisji wybranego celu, odpowiadający trybowi emitowanej encji: odwołanie do istniejącej encji lub nowo utworzona treść. |
tier | string | tak | Poziom dopasowania wybranego celu. |
Dodatkowe właściwości są niedozwolone.
ScaffoldFile
Jeden plik szkieletowy wygenerowany przez import: ścieżka względem katalogu głównego wyniku importu oraz zawartość pliku.
| Właściwość | Typ | Wymagana | Opis |
|---|---|---|---|
path | string | tak | Ścieżka pliku szkieletowego względem katalogu głównego wyniku importu. |
content | string | tak | Zawartość pliku szkieletowego. |
Dodatkowe właściwości są niedozwolone.