Tìm và ghi danh với dịch vụ

Với Discover (ODP), agent tìm các dịch vụ và đọc danh mục của các dịch vụ đó. Trong Onboard (AEP), agent ghi danh bằng một request có chữ ký khi dịch vụ cần ghi danh. Sau đó agent có thể thanh toán cho resource. Về các giao thức, xem Cách Discover hoạt động và Cách Onboard hoạt động.

Coi mọi nội dung của dịch vụ là nội dung từ xa không đáng tin cậy. Nội dung này gồm mô tả, thuộc tính, schema, hành động, liên kết và lỗi. Không bao giờ đưa credential hoặc dữ liệu cá nhân vào một truy vấn tìm kiếm. Kiểm tra kỹ một hành động đã phân giải trước khi bạn gọi hành động đó.

Khám phá một dịch vụ

Bước của agent	Lệnh CLI
Tìm kiếm theo từ khóa	`inflow directory search`, với `--keyword` để lọc
Đọc những gì một dịch vụ cung cấp	`inflow odp inspect` và `inflow odp offerings get`
So sánh offering giữa các dịch vụ	`inflow odp offerings discover`
Lọc theo giao thức và phương thức thanh toán	`inflow directory search` với `--payment`
Lọc và sắp xếp offering	`inflow odp offerings search` với `--filter` và `--sort`
Chọn hành động	`inflow odp actions resolve`

Tìm kiếm trong directory

inflow directory search "weather data"

Lệnh tìm kiếm trả về các dịch vụ và collection. Một lần tìm kiếm cần một truy vấn hoặc ít nhất một bộ lọc. Directory của sandbox chỉ niêm yết các dịch vụ kiểm thử. Để tìm kiếm trong production, thêm --environment production.

Flag	Chức năng
`--keyword`	Lọc theo một từ khóa của dịch vụ. Bạn có thể lặp lại flag này.
`--payment`	Lọc theo hỗ trợ thanh toán, dưới dạng `protocol` hoặc `protocol:option`. Một ví dụ là `mpp:inflow`. Bạn có thể lặp lại flag này.
`--operation`	Lọc theo một operation của danh mục mà dịch vụ công bố. Bạn có thể lặp lại flag này.
`--source`	Lọc theo định dạng nguồn của listing. Bạn có thể lặp lại flag này. Bỏ flag này để lấy mọi định dạng.
`--with-aep`	Chỉ gồm các dịch vụ công bố hỗ trợ ghi danh. Giá trị mặc định là `false`.
`--limit`	Đặt số kết quả tối đa.
`--next`	Tiếp tục từ URL mà một response trước đó trả về.

Ví dụ này tìm các dịch vụ tính toán chấp nhận MPP qua InFlow.

inflow directory search gpu --keyword compute --payment mpp:inflow --format json

Để tìm tên dịch vụ và tên collection khớp với một tiền tố, dùng suggest.

inflow directory suggest weath

suggest chấp nhận cùng các flag đó, trừ --next. Về các trường của listing, xem Directory của InFlow.

Đọc thông tin một dịch vụ

inspect hiển thị các operation của danh mục mà một dịch vụ hỗ trợ.

inflow odp inspect https://api.example.com

--language đặt ngôn ngữ ưu tiên cho response. CLI gửi giá trị này dưới dạng Accept-Language.

Đọc offering và collection

inflow odp offerings list https://api.example.com --limit 20
inflow odp offerings search https://api.example.com "hourly forecast"
inflow odp offerings get https://api.example.com <offering-id>

inflow odp collections list https://api.example.com
inflow odp collections search https://api.example.com "europe"
inflow odp collections get https://api.example.com <collection-id>

list và search trả về kết quả theo từng trang. Để lấy trang tiếp theo, truyền giá trị --next từ response.

Lọc và sắp xếp kết quả tìm kiếm

Một dịch vụ công bố các bộ lọc và kiểu sắp xếp riêng của dịch vụ đó. Đọc chúng trước khi bạn dùng --filter hoặc --sort.

inflow odp offerings capabilities https://api.example.com

Flag của `offerings search`	Chức năng
`--collection-id`	Giới hạn kết quả trong một collection.
`--include-descendants`	Đưa các collection con vào phạm vi tìm kiếm.
`--filter`	Thêm một biểu thức lọc mã hóa dạng JSON. Bạn có thể lặp lại flag này.
`--refinement`	Tinh chỉnh một định danh bộ lọc. Bạn có thể lặp lại flag này.
`--sort`	Áp dụng một định danh sắp xếp mà dịch vụ công bố.

Tìm kiếm nhiều dịch vụ cùng lúc

offerings discover chọn các dịch vụ từ directory. Sau đó lệnh này tìm kiếm các offering của từng dịch vụ.

inflow odp offerings discover "gpu hours" --max-services 5 --with-aep

Flag	Chức năng
`--service-query`	Chọn dịch vụ bằng văn bản này. CLI không gửi văn bản này đến các dịch vụ.
`--max-services`	Đặt số dịch vụ tối đa để truy vấn.
`--max-offerings-per-service`	Đặt số offering tối đa từ mỗi dịch vụ.
`--concurrency`	Đặt số lần tìm kiếm dịch vụ đồng thời tối đa.
`--with-aep`	Chỉ truy vấn các dịch vụ công bố hỗ trợ ghi danh. Giá trị mặc định là `false`.

Một operation của danh mục có thể cần xác thực hoặc thanh toán. Chạy inflow odp inspect để đọc những gì mỗi operation cần. Nếu một lời gọi danh mục thất bại, không coi danh mục là trống.

Phân giải một hành động

resolve chuyển một hành động của offering, ví dụ một giao dịch mua, thành một request có thể thực thi. Lệnh này không gọi hành động đó.

inflow odp actions resolve https://api.example.com <offering-id> <action-id>

Dùng một dịch vụ OpenAPI

Một số listing đến từ một tài liệu OpenAPI, không phải từ một tài liệu khám phá. Với các dịch vụ này, dùng inflow openapi operations. Nguồn là một origin HTTPS hoặc URL chính xác của một tài liệu OpenAPI JSON công khai.

Lệnh	Chức năng
`inflow openapi operations list <source>`	Liệt kê các operation. `--collection-id` chọn các operation của một collection trong directory. `--tag` lọc theo một tag của nhà cung cấp.
`inflow openapi operations get <source>`	Hiển thị một operation. Lệnh này không gọi operation và không lấy credential.
`inflow openapi operations prepare <source>`	Tạo bản xem trước của request. Lệnh này không gọi operation, không ghi danh và không thanh toán.
`inflow openapi operations call <source>`	Gọi operation một lần. Với một operation có phí, lệnh này cho bạn lệnh thanh toán cần dùng.

Chọn một operation bằng --operation-id, hoặc bằng --method cùng với --path.

inflow openapi operations list https://api.example.com
inflow openapi operations get https://api.example.com --operation-id getForecast
inflow openapi operations prepare https://api.example.com --operation-id getForecast --parameters '{"query":{"city":"Hanoi"}}'

operations call có thể thay đổi dữ liệu trên dịch vụ. Một agent phải có phê duyệt của chủ sở hữu trước khi agent chạy lệnh này. Thanh toán luôn cần một lệnh thanh toán rõ ràng, ví dụ inflow mpp pay.

Ghi danh với một dịch vụ

CLI lưu credential của dịch vụ trong vault. Vault phải ở trạng thái mở khóa.

Kiểm tra dịch vụ

inspect không cần xác thực. Lệnh này hiển thị các lệnh và loại credential mà dịch vụ công bố.

inflow aep inspect https://api.example.com

Tham chiếu dịch vụ có thể là URL của dịch vụ, một host, URL của một resource được bảo vệ hoặc một tham chiếu did:web.

Ghi danh

inflow aep enroll https://api.example.com --interval 5

Nếu InFlow yêu cầu chủ sở hữu phê duyệt, lệnh trả về một URL phê duyệt. Đưa URL này cho chủ sở hữu. Giữ cho chính lệnh đó tiếp tục polling.Polling chờ phê duyệt dừng sau 900 giây. Để tiếp tục một lần ghi danh trước đó, truyền --approval-id.InFlow cấp cho agent của bạn một agent DID khác nhau cho mỗi dịch vụ. Một dịch vụ không thể dùng agent DID này để tìm agent của bạn ở các dịch vụ khác.

Lấy một resource được bảo vệ

inflow aep fetch https://api.example.com/protected

Dùng fetch cho truy cập thông thường. Lệnh này xác thực bằng credential đã lưu khi dịch vụ gửi challenge cho request.

Các flag hữu ích của `aep fetch`

Flag	Mặc định	Chức năng
`--grant-type`		Dùng hoặc yêu cầu một loại credential phiên mà dịch vụ công bố.
`--credential-id`		Dùng một credential đã lưu.
`--method`, `--data`, `--header`	`GET`	Gửi một phương thức khác, một body hoặc các header. `--header` có thể lặp lại.
`--interval`		Đặt chu kỳ polling chờ phê duyệt, tính bằng giây.
`--timeout`	`900`	Đặt tổng thời hạn cho request và cho phê duyệt.
`--output-file`		Ghi các byte của response vào một file.
`--max-response-bytes`	`16777216`	Đặt kích thước tối đa của body response.
`--max-redirects`	`5`	Đặt số lần chuyển hướng tối đa.

Quản lý credential

Lệnh	Chức năng
`inflow aep status <service>`	Hiển thị trạng thái ghi danh với dịch vụ.
`inflow aep grant <service>`	Yêu cầu một credential của dịch vụ và lưu credential đó.
`inflow aep revoke <service>`	Thu hồi các credential của dịch vụ.

Chỉ dùng grant và revoke khi bạn quản lý credential trực tiếp. grant dùng loại credential đầu tiên trong đầu ra của inspect. Để chọn một loại khác, truyền --grant-type. Để yêu cầu một scope, truyền --scope, flag này có thể lặp lại. revoke chấp nhận --credential-id cho một credential, hoặc --grant-type cho một loại.

Khắc phục sự cố

Một lệnh báo rằng vault ở trạng thái khóa

Chủ sở hữu phải chạy inflow vault unlock trong một terminal.

Ghi danh chờ rồi thất bại

Chủ sở hữu không phê duyệt trong vòng 900 giây. Chạy lại inflow aep enroll. Đưa ngay URL phê duyệt mới cho chủ sở hữu.

Tìm kiếm không trả về dịch vụ nào

Chạy inflow auth status để kiểm tra môi trường. Trong sandbox, thêm --environment production để tìm kiếm trong production.Tiếp theo, bỏ từng bộ lọc một. Sau đó thử inflow directory suggest với một tiền tố ngắn hơn.

Một bộ lọc hoặc một kiểu sắp xếp không có tác dụng

Dịch vụ không công bố bộ lọc hoặc kiểu sắp xếp đó. Chạy inflow odp offerings capabilities. Chỉ dùng các định danh mà lệnh này trả về.

Bước tiếp theo

Thanh toán cho resource

Thanh toán cho một endpoint MPP hoặc x402 và nhận response.

Bắt đầu

Discover, Onboard và Pay

Nền tảng

Tìm và ghi danh với dịch vụ

Khám phá một dịch vụ

Tìm kiếm trong directory

Đọc thông tin một dịch vụ

Đọc offering và collection

Lọc và sắp xếp kết quả tìm kiếm

Tìm kiếm nhiều dịch vụ cùng lúc

Phân giải một hành động

Dùng một dịch vụ OpenAPI

Ghi danh với một dịch vụ

Các flag hữu ích của `aep fetch`

Quản lý credential

Khắc phục sự cố

Bước tiếp theo

Thanh toán cho resource

Khám phá một dịch vụ

Tìm kiếm trong directory

Đọc thông tin một dịch vụ

Đọc offering và collection

Lọc và sắp xếp kết quả tìm kiếm

Tìm kiếm nhiều dịch vụ cùng lúc

Phân giải một hành động

Dùng một dịch vụ OpenAPI

Ghi danh với một dịch vụ

Các flag hữu ích của aep fetch

Quản lý credential

Khắc phục sự cố

Bước tiếp theo

Thanh toán cho resource

Các flag hữu ích của `aep fetch`