Bỏ qua để đến nội dung
AggregaAggrega
Chọn ngôn ngữ: Tiếng Việt
Trang này được dịch bằng máy. Đọc bản gốc tiếng Anh.

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 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.

Cờ

CờMặc địnhMô 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-retractedfalseBá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.
--limit0Giới hạn số lượng kết quả (0 nghĩa là không giới hạn).
--output, -otableĐị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:

  • version là 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ách retracted nêu tên tất cả các phiên bản đó.
  • retracted liệ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.