Przejdź do głównej zawartości
AggregaAggrega
Wybierz język: Polski
Ta strona została przetłumaczona maszynowo. Przeczytaj oryginał w języku angielskim.

aggrega search

Przeszukuje lokalny indeks skonfigurowanych rejestrów

Składnia

aggrega search [query] [flags]

Opis

Search the local index of the configured registries for entities matching a
free-text query and optional facet filters.
The index is the offline snapshot written by 'aggrega registry update'; search
reads it and contacts no network. Run 'aggrega registry update' first, and again
whenever you want to pick up newly published entities. A freshness line naming
each searched registry and when its index was last updated is written to standard
error, so standard output carries only the result data.
The optional positional query is a case-insensitive substring matched against
each entity's name and description. The facet filters narrow the result further,
combining as AND across facets and OR within a repeatable facet:
--kind entity kind (component, feature, recipe, featurerecipe,
workload, plugin); repeatable, case-insensitive
--capability a plugin capability; repeatable
--plugin-type a plugin socket type (for example provider, governance)
-l, --selector a label selector over the entity's catalog labels
Category is matched through the label selector, not a dedicated flag: a catalog
category is the label component.aggrega.ai/category, so
'-l component.aggrega.ai/category=compute' scopes the result to that category.
With no --registry, every configured registry's index is searched and the
results are merged. With --registry (a host or a friendly alias), only that
registry's index is searched.
A search needs at least one configured registry. With none configured there is
nowhere to look, so the command refuses: the reason goes to standard error,
standard output carries nothing, and the exit status is non-zero. That is what
lets a caller tell a search that ran and matched nothing from a search that
could not be performed. Run 'aggrega config init' to register a registry with
its signature trust policy, then 'aggrega registry update' to build the index.
The version reported for an entity is the one a resolution would take: a
version a publisher has retracted, where the retraction carries a signature
this workspace's trust policy verifies, is not reported. Such an entity is
still listed, and the versions left out are named in a NOTES column, so an
entity whose every published version is retracted is reported as existing with
no version to take rather than disappearing from the result. Pass
--include-retracted to report the highest published version whatever its
retraction status; the NOTES column names the retracted versions either way.
The same holds for 'aggrega search -o json', where the 'version' field carries
the version a resolution would take and a 'retracted' array names the versions
left out.

Flagi

FlagaDomyślnieOpis
--capability[]Zdolność (capability) Plugin do dopasowania. Można podać wielokrotnie; zachowywany jest rekord deklarujący dowolną z nich.
--include-retractedfalseZgłasza najwyższą opublikowaną wersję, nawet jeśli zweryfikowany znacznik ją wycofuje. Domyślnie zgłaszana jest wersja, którą wybrałoby rozwiązywanie zależności.
--kind[]Dopasowywany rodzaj encji (component|feature|recipe|featurerecipe|workload|plugin). Można powtarzać; zachowywany jest rekord pasujący do dowolnego z nich. Wielkość liter nie ma znaczenia.
--limit0Ogranicza liczbę wyników (0 oznacza brak limitu).
--output, -otableFormat wyjścia: table|json|names.
--plugin-type—Typ gniazda Plugin do dopasowania (na przykład provider, governance, linter).
--registry—Przeszukuje tylko ten rejestr, wskazany przez hosta lub przyjazny alias. Domyślnie przeszukiwane są wszystkie skonfigurowane rejestry.
--selector, -l—Selektor etykiet działający na etykietach katalogowych encji, w tym na jej kategorii (-l component.aggrega.ai/category=compute).

Gdy nie skonfigurowano żadnego rejestru

Wyszukiwanie odczytuje lokalny indeks rejestrów, do których ta maszyna jest skonfigurowana, więc wymaga co najmniej jednego z nich. Gdy żaden nie jest skonfigurowany, nie ma gdzie szukać, a aggrega search odmawia zamiast odpowiadać: zapisuje powód na standardowe wyjście błędów, kończy się kodem niezerowym i pozostawia standardowe wyjście puste — w każdym formacie wyjścia, łącznie z --output json.

Odmowa pozwala odróżnić dwie różne odpowiedzi. Wyszukiwanie, które się wykonało i niczego nie znalazło, kończy się kodem zero i zgłasza (no matches) na standardowym wyjściu; wyszukiwanie, którego w ogóle nie dało się wykonać, kończy się kodem niezerowym i niczego tam nie zgłasza. Skrypt rozgałęziający się według kodu wyjścia może więc odróżnić „ta encja nie jest opublikowana” od „ta maszyna nie ma rejestru, który mogłaby zapytać”, czego komunikat na standardowym wyjściu i kod zero nie są w stanie wyrazić.

Należy uruchomić aggrega config init, aby zarejestrować rejestr wraz z jego polityką zaufania podpisów, a następnie aggrega registry update, aby zbudować lokalny indeks odczytywany przez wyszukiwanie.

aggrega registry list i aggrega registry update reagują na tę samą sytuację inaczej, i to celowo. Wylistowanie rejestrów, gdy nie ma żadnego, jest pełnym wylistowaniem zbioru pustego, a budowa indeksu, gdy nie ma czego przeglądać, nie ma już nic do zrobienia: obie operacje są zakończone, więc obie zgłaszają wynik na standardowym wyjściu i kończą się kodem zero. Tylko wyszukiwanie zgłasza, że nie mogło wykonać tego, o co zostało poproszone.

Wersja zgłaszana przez wyszukiwanie

Kolumna VERSION zawiera wersję, którą wybrałoby rozwiązywanie zależności. Wersja wycofana przez wydawcę nie jest zgłaszana, pod warunkiem że wycofanie ma podpis weryfikowany przez politykę zaufania tego obszaru roboczego — to te same dwa warunki, które decydują, czy wycofanie wpływa na pobranie, więc wyszukiwanie i pobranie zgadzają się co do tego, która wersja jest odpowiedzią.

Wycofanie niespełniające któregokolwiek z warunków nie zmienia niczego w zgłaszanym wyniku. Znacznik o poziomie doradczym pozostawia swoją wersję możliwą do wybrania, a znacznik, którego podpis nie przechodzi weryfikacji, nie jest deklaracją, na podstawie której działa ten obszar roboczy. W obu przypadkach najwyższa opublikowana wersja jest zgłaszana dokładnie tak, jak byłaby bez żadnego znacznika.

Encja z wycofaną wersją nadal jest wyświetlana. Kolumna NOTES wymienia pominięte wersje i pojawia się tylko w wyniku, w którym jest coś do zgłoszenia. Encja, której każda opublikowana wersja jest wycofana, jest zgłaszana z wartością (none) jako wersją i notatką, że nie pozostała żadna wersja, zamiast zostać usunięta z wyniku — pominiętej encji nie dałoby się odróżnić od takiej, która nie istnieje.

Przekazanie --include-retracted powoduje zgłoszenie najwyższej opublikowanej wersji bez względu na status wycofania, co odpowiada na pytanie „co jest opublikowane?”, a nie „czego należy użyć?”. Zmienia to tylko zgłaszaną wersję; kolumna NOTES wymienia wycofane wersje w obu przypadkach.

Wyszukiwanie odczytuje lokalny indeks zapisywany przez aggrega registry update, więc zgłasza to, co każdy rejestr deklarował w chwili ostatniej budowy indeksu. Wersja wycofana od tego czasu nie jest jeszcze odnotowana, a wiersz aktualności zapisywany na standardowe wyjście błędów podaje moment zbudowania każdego indeksu.

Wynik do odczytu maszynowego

--output json przenosi ten sam kontrakt w dwóch polach:

  • version to wersja, którą wybrałoby rozwiązywanie zależności. Jest pustym ciągiem, gdy każda opublikowana wersja jest wycofana, czemu towarzyszy lista retracted wymieniająca je wszystkie.
  • retracted wymienia wersje pominięte w tym wyborze, w rosnącej kolejności wersji. Pole jest nieobecne, gdy niczego nie pominięto.

Konsument pytający, którą wersję otrzyma, odczytuje version. Wyprowadzanie tego z tablicy deprecations oznacza ponowną implementację warunków poziomu i podpisu, a druga implementacja tych warunków może się nie zgadzać z tą, którą stosuje kompilator; retracted zgłasza wynik, który te warunki już dały.

Każdy rekord zawiera też published: każdą wersję odnotowaną w indeksie, w rosnącej kolejności wersji, każdą z manifestDigest, na który wskazywał jej tag w chwili budowy indeksu, oraz — jeśli polityka zaufania tego obszaru roboczego zweryfikowała własny podpis tej wersji — jej signer: spośród kilku weryfikowanych ten, który dziennik przejrzystości odnotował najwcześniej. Wersja bez signer nie ma podpisu zweryfikowanego przez tę politykę i nic więcej się o niej nie mówi. Konsument odczytujący zawartość jednej wersji adresuje ją tym skrótem — na przykład aggrega inspect oci://<host>/<repository>@<digest> — więc odczytuje bajty odnotowane przez indeks, bez względu na to, co później stanie się z tagiem.

Jeśli cokolwiek odnotowuje datę publikacji wersji, jej wpis zawiera też publishedAt, znacznik czasu RFC 3339 w UTC z dokładnością do sekundy, oraz publishedAtSource, który wskazuje jego źródło. transparency-log to czas, w którym dziennik przejrzystości odnotował bezkluczowy podpis wersji, zweryfikowany przez politykę zaufania tego obszaru roboczego wraz z podpisaną przez dziennik obietnicą tego czasu — podpis signer, najwcześniejszy z weryfikowanych, więc ponowne podpisanie wersji nie zmienia żadnego z nich. publisher to czas podany przez publikację obok tego, co opublikowała, według własnego zegara publikującej maszyny, którego nic nie poświadcza. Oba są trzymane osobno, aby konsument sortujący według daty nadal mógł odróżnić czas poświadczony od deklarowanego. Wersja bez żadnego z nich nie ma daty i nic więcej się o niej nie mówi; informacje o tym, kiedy każdy z nich jest odnotowywany, zawiera aggrega registry update.