Перейти до вмісту
AggregaAggrega
Обрати мову: Українська
Цю сторінку перекладено машинним способом. Читати оригінал англійською.

aggrega search

Шукати в локальному індексі налаштованих реєстрів

Синтаксис

aggrega search [query] [flags]

Опис

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.

Прапорці

ПрапорецьЗа замовчуваннямОпис
--capability[]Можливість сутності Plugin, з якою слід шукати збіг. Можна повторювати; запис, що оголошує будь-яку з них, залишається.
--include-retractedfalseПовідомляти найвищу опубліковану версію, навіть якщо перевірений маркер її відкликає. За замовчуванням повідомляється версія, яку обрало б розв’язання.
--kind[]Тип сутності, за яким шукати (component|feature|recipe|featurerecipe|workload|plugin). Можна повторювати; запис, що відповідає будь-якому з них, зберігається. Без урахування регістру.
--limit0Обмежити кількість результатів (0 означає без обмеження).
--output, -otableФормат виводу: table|json|names.
--plugin-type—Тип сокета сутності Plugin, з яким слід шукати збіг (наприклад, provider, governance, linter).
--registry—Шукати лише в цьому реєстрі, указаному за хостом або зручним псевдонімом. За замовчуванням пошук виконується в усіх налаштованих реєстрах.
--selector, -l—Селектор міток за мітками каталогу сутності, серед яких є її категорія (-l component.aggrega.ai/category=compute).

Коли жоден реєстр не налаштовано

Пошук читає локальний індекс реєстрів, до яких налаштовано доступ на цій машині, тож потрібен принаймні один із них. Якщо жоден не налаштовано, шукати ніде, і aggrega search відмовляє замість відповіді: записує причину до стандартного потоку помилок, завершується з ненульовим кодом і залишає стандартний вивід порожнім — у кожному форматі виводу, зокрема --output json.

Саме відмова розрізняє дві різні відповіді. Пошук, який виконався й нічого не знайшов, завершується з кодом нуль і повідомляє (no matches) у стандартний вивід; пошук, який узагалі не зміг виконатися, завершується з ненульовим кодом і нічого туди не повідомляє. Тому скрипт, що розгалужується за кодом завершення, може відрізнити «цю сутність не опубліковано» від «на цій машині немає реєстру, до якого звернутися», чого повідомлення у стандартному виводі з нульовим кодом виразити не може.

Виконайте aggrega config init, щоб зареєструвати реєстр разом із його політикою довіри до підписів, а потім aggrega registry update, щоб побудувати локальний індекс, який читає пошук.

aggrega registry list і aggrega registry update реагують на ту саму ситуацію інакше, і це навмисно. Перелік реєстрів, коли їх немає, — це повний перелік порожньої множини, а побудові індексу, якій нічого обходити, нічого й не лишається робити: обидві операції завершені, тож обидві звітують у стандартний вивід і завершуються з кодом нуль. Лише пошук повідомляє, що не зміг виконати те, про що його просили.

Версія, яку повідомляє пошук

Стовпець VERSION містить версію, яку обрало б розв’язання. Версія, яку її видавець відкликав, не повідомляється за умови, що відкликання має підпис, який перевіряє політика довіри цього робочого простору, — ті самі дві умови, що визначають, чи впливає відкликання на завантаження, тож пошук і завантаження погоджуються щодо того, яка версія є відповіддю.

Відкликання, що не задовольняє будь-яку з умов, нічого не змінює в повідомленому. Маркер рекомендаційного рівня серйозності залишає свою версію доступною для вибору, а маркер, підпис якого не перевіряється, не є твердженням, на яке зважає цей робочий простір. В обох випадках найвища опублікована версія повідомляється точно так, як і без жодного маркера.

Сутність із відкликаною версією все одно показується. Стовпець NOTES називає пропущені версії й з’являється лише в результаті, де є що повідомити. Сутність, у якої кожну опубліковану версію відкликано, показується з (none) як версією та приміткою, що жодної версії не лишилося, замість вилучення з результату — пропущену сутність було б неможливо відрізнити від тієї, якої не існує.

Передайте --include-retracted, щоб повідомляти найвищу опубліковану версію незалежно від статусу відкликання, — це відповідь на «що опубліковано?», а не на «що мені використовувати?». Це змінює лише повідомлену версію; стовпець NOTES називає відкликані версії в обох випадках.

Пошук читає локальний індекс, який записує aggrega registry update, тож повідомляє те, що заявляв кожен реєстр на момент останньої побудови цього індексу. Версію, відкликану відтоді, ще не записано, а рядок актуальності, що записується до стандартного потоку помилок, називає момент побудови кожного індексу.

Машиночитаний результат

--output json передає той самий контракт у двох полях:

  • version — версія, яку обрало б розв’язання. Це порожній рядок, коли кожну опубліковану версію відкликано, і тоді поруч є список retracted, що називає їх усі.
  • retracted перелічує версії, пропущені під час цього вибору, у порядку зростання версій. Він відсутній, коли нічого не пропущено.

Споживач, який хоче знати, яку версію отримає, читає version. Виводити її натомість із масиву deprecations означає заново реалізувати умови щодо серйозності та підпису, а друга реалізація цих умов цілком може розійтися з тією, яку застосовує компілятор; retracted повідомляє результат, який ці умови вже дали.

Кожен запис також містить published: кожну версію, яку записав індекс, у порядку зростання версій, кожну з manifestDigest, на який розв’язувався її тег під час побудови індексу, і, якщо політика довіри цього робочого простору перевірила власний підпис цієї версії, її signer — з кількох перевірених той, який журнал прозорості записав найраніше. Версія без signer не має підпису, перевіреного цією політикою, і більше про неї нічого не повідомляється. Споживач, що читає вміст однієї версії, адресує його за цим дайджестом — наприклад, aggrega inspect oci://<host>/<repository>@<digest> — тож читає саме ті байти, які записав індекс, хоч би що потім сталося з тегом.

Якщо щось записує час публікації версії, її запис також містить publishedAt — позначку часу RFC 3339 в UTC з точністю до секунди, і publishedAtSource, що вказує, звідки вона походить. transparency-log — час, коли журнал прозорості записав безключовий підпис версії, який політика довіри цього робочого простору перевірила разом із підписаною журналом обіцянкою щодо цього часу, — підпис signer, найраніший із перевірених, тож повторне підписання версії не змінює жодного з них. publisher — час, який публікація вказала поряд із опублікованим, за власним годинником машини-видавця, що ніщо не засвідчує. Їх тримають окремо, щоб споживач, який сортує за датою, усе одно міг відрізнити засвідчений час від заявленого. Версія без жодного з них не має дати, і більше про неї нічого не повідомляється; див. aggrega registry update, щоб дізнатися, коли записується кожен із них.