aggrega search
Tìm kiếm trong chỉ mục cục bộ của các registry đã cấu hình
Cú pháp
aggrega search [query] [flags]Mô tả
Search the local index of the configured registries for entities matching afree-text query and optional facet filters.
The index is the offline snapshot written by 'aggrega registry update'; searchreads it and contacts no network. Run 'aggrega registry update' first, and againwhenever you want to pick up newly published entities. A freshness line namingeach searched registry and when its index was last updated is written to standarderror, so standard output carries only the result data.
The optional positional query is a case-insensitive substring matched againsteach 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 catalogcategory 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 theresults are merged. With --registry (a host or a friendly alias), only thatregistry's index is searched.
A search needs at least one configured registry. With none configured there isnowhere 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 whatlets a caller tell a search that ran and matched nothing from a search thatcould not be performed. Run 'aggrega config init' to register a registry withits signature trust policy, then 'aggrega registry update' to build the index.
The version reported for an entity is the one a resolution would take: aversion a publisher has retracted, where the retraction carries a signaturethis workspace's trust policy verifies, is not reported. Such an entity isstill listed, and the versions left out are named in a NOTES column, so anentity whose every published version is retracted is reported as existing withno version to take rather than disappearing from the result. Pass--include-retracted to report the highest published version whatever itsretraction status; the NOTES column names the retracted versions either way.The same holds for 'aggrega search -o json', where the 'version' field carriesthe version a resolution would take and a 'retracted' array names the versionsleft out.Cờ
| Cờ | Mặc định | Mô tả |
|---|---|---|
--capability | [] | Khả năng của Plugin cần khớp. Có thể lặp lại; một bản ghi khai báo bất kỳ khả năng nào trong số đó sẽ được giữ lại. |
--include-retracted | false | Báo cáo phiên bản đã xuất bản cao nhất ngay cả khi một dấu đánh đã được xác minh thu hồi nó. Theo mặc định, phiên bản được báo cáo là phiên bản mà một lần phân giải sẽ chọn. |
--kind | [] | Loại thực thể cần khớp (component|feature|recipe|featurerecipe|workload|plugin). Có thể lặp lại; một bản ghi khớp bất kỳ loại nào sẽ được giữ lại. Không phân biệt chữ hoa chữ thường. |
--limit | 0 | Giới hạn số lượng kết quả (0 nghĩa là không giới hạn). |
--output, -o | table | Định dạng đầu ra: table|json|names. |
--plugin-type | — | Loại socket của Plugin cần khớp (ví dụ provider, governance, linter). |
--registry | — | Chỉ tìm kiếm trong registry này, được chỉ định bằng host hoặc bí danh thân thiện. Mặc định tìm kiếm mọi registry đã cấu hình. |
--selector, -l | — | Bộ chọn nhãn trên các nhãn danh mục của thực thể, bao gồm danh mục của nó (-l component.aggrega.ai/category=compute). |
Khi không có registry nào được cấu hình
Một lần tìm kiếm đọc chỉ mục cục bộ của các registry mà máy này được cấu hình để truy cập, vì vậy nó
cần ít nhất một registry. Khi không có registry nào được cấu hình thì không có nơi nào để tìm, và aggrega search
từ chối thay vì trả lời: nó ghi lý do vào standard error, thoát với mã khác không, và
để trống standard output — ở mọi định dạng đầu ra, kể cả --output json.
Việc từ chối là điều giúp phân biệt hai câu trả lời khác nhau. Một lần tìm kiếm đã chạy nhưng không khớp gì
sẽ thoát với mã không và báo (no matches) trên standard output; một lần tìm kiếm hoàn toàn không thể chạy
sẽ thoát với mã khác không và không báo gì ở đó. Do đó, một script rẽ nhánh theo mã thoát có thể
phân biệt “thực thể này chưa được xuất bản” với “máy này không có registry nào để hỏi”, điều mà một thông báo
trên standard output cùng mã thoát không không thể diễn đạt được.
Chạy aggrega config init để đăng ký một registry cùng với chính sách tin cậy chữ ký của nó, sau đó
chạy aggrega registry update để xây dựng chỉ mục cục bộ mà lần tìm kiếm đọc.
aggrega registry list và aggrega registry update phản hồi cùng tình huống đó theo cách khác, và
điều này là có chủ ý. Liệt kê các registry khi không có registry nào là một danh sách đầy đủ của một tập rỗng,
và một lần xây dựng chỉ mục không có gì để duyệt thì không còn việc gì để làm: cả hai đều là thao tác đã hoàn tất, nên
cả hai đều báo trên standard output và thoát với mã không. Chỉ có lần tìm kiếm là đang báo rằng nó không thể làm
điều được yêu cầu.
Phiên bản mà một lần tìm kiếm báo cáo
Cột VERSION chứa phiên bản mà một lần phân giải sẽ chọn. Một phiên bản mà nhà xuất bản đã
thu hồi sẽ không được báo cáo, với điều kiện việc thu hồi mang một chữ ký mà chính sách tin cậy của workspace này xác minh được — cũng chính là hai điều kiện quyết định việc thu hồi có ảnh hưởng đến một lần pull hay không, nên
một lần tìm kiếm và một lần pull thống nhất về phiên bản nào là câu trả lời.
Một lần thu hồi không đáp ứng một trong hai điều kiện sẽ không thay đổi gì trong những gì được báo cáo. Một dấu đánh ở mức độ khuyến cáo vẫn để phiên bản của nó có thể được chọn, và một dấu đánh có chữ ký không xác minh được không phải là một tuyên bố mà workspace này hành động theo. Trong cả hai trường hợp, phiên bản đã xuất bản cao nhất được báo cáo đúng như khi không có dấu đánh nào.
Một thực thể có phiên bản bị thu hồi vẫn được liệt kê. Một cột NOTES nêu tên các phiên bản bị loại
ra, và chỉ xuất hiện trong kết quả có điều gì đó để báo cáo. Một thực thể mà mọi phiên bản
đã xuất bản đều bị thu hồi sẽ được báo cáo với (none) làm phiên bản và một ghi chú cho biết không còn
phiên bản nào, thay vì bị loại khỏi kết quả — một thực thể bị bỏ qua sẽ
không thể phân biệt với một thực thể không tồn tại.
Truyền --include-retracted để báo cáo phiên bản đã xuất bản cao nhất bất kể trạng thái thu hồi
của nó, đây là câu trả lời cho “cái gì đã được xuất bản?” thay vì “tôi nên dùng cái gì?”. Nó
chỉ thay đổi phiên bản được báo cáo; cột NOTES vẫn nêu tên các phiên bản bị thu hồi trong
cả hai trường hợp.
Những gì một lần tìm kiếm đọc là chỉ mục cục bộ mà aggrega registry update ghi ra, nên nó báo cáo
những gì mỗi registry đã nêu khi chỉ mục đó được xây dựng lần cuối. Một phiên bản bị thu hồi kể từ đó
chưa được ghi nhận, và dòng độ mới được ghi vào standard error nêu thời điểm mỗi
chỉ mục được xây dựng.
Kết quả máy đọc được
--output json mang cùng hợp đồng đó trong hai trường:
versionlà phiên bản mà một lần phân giải sẽ chọn. Nó là chuỗi rỗng khi mọi phiên bản đã xuất bản đều bị thu hồi, đi kèm với một danh sáchretractednêu tên tất cả các phiên bản đó.retractedliệt kê các phiên bản bị loại khỏi lựa chọn đó, theo thứ tự phiên bản tăng dần. Nó không có mặt khi không có gì bị loại ra.
Một bên tiêu thụ muốn biết mình sẽ nhận phiên bản nào thì đọc version. Suy ra điều đó từ
mảng deprecations thay vào đó đồng nghĩa với việc cài đặt lại các điều kiện về mức độ và chữ ký, và
một cài đặt thứ hai của các điều kiện đó hoàn toàn có thể không khớp với cài đặt mà trình biên dịch
áp dụng; retracted báo cáo kết quả mà các điều kiện đó đã tạo ra.
Mỗi bản ghi cũng mang published: mọi phiên bản mà chỉ mục đã ghi nhận, theo thứ tự phiên bản
tăng dần, mỗi phiên bản kèm manifestDigest mà tag của nó phân giải thành khi chỉ mục được xây dựng và, nơi
chính sách tin cậy của workspace này đã xác minh chữ ký riêng của phiên bản đó, kèm signer của nó — trong số nhiều
chữ ký xác minh được, là chữ ký mà transparency log ghi nhận sớm nhất. Một phiên bản không có signer thì không mang
chữ ký nào mà chính sách đó đã xác minh, và không có thêm điều gì được nói về nó.
Một bên tiêu thụ đọc nội dung của một phiên bản sẽ chỉ định nó bằng digest đó — ví dụ
aggrega inspect oci://<host>/<repository>@<digest> — nên những gì nó đọc là các byte mà chỉ mục
đã ghi nhận, bất kể điều gì xảy ra với tag sau đó.
Khi có nơi nào ghi nhận thời điểm một phiên bản được xuất bản, mục của nó cũng mang publishedAt, một
dấu thời gian RFC 3339 theo UTC chính xác đến giây, và publishedAtSource, cho biết nó đến từ đâu.
transparency-log là thời điểm một transparency log ghi nhận chữ ký keyless của phiên bản,
mà chính sách tin cậy của workspace này đã xác minh cùng với lời cam kết đã ký của log về thời điểm
đó — chữ ký của signer, chữ ký sớm nhất trong số những chữ ký xác minh được, nên việc ký lại một phiên bản
không làm thay đổi cả hai. publisher là thời điểm mà bản xuất bản nêu kèm theo những gì nó xuất bản, lấy từ
đồng hồ riêng của máy xuất bản, điều mà không có gì chứng thực. Hai giá trị được giữ tách biệt để một bên tiêu thụ
sắp xếp theo ngày vẫn có thể phân biệt thời điểm được chứng thực với thời điểm được tự nêu. Một phiên bản không có cả hai
thì không mang ngày nào, và không có thêm điều gì được nói về nó; xem
aggrega registry update để biết
khi nào mỗi giá trị được ghi nhận.