Nguồn dữ liệu và khóa truy cập
Cách lấy danh mục hoặc ghi đơn hàng vào dịch vụ khác: lưu địa chỉ API, thêm khóa truy cập và cấu hình yêu cầu trong phản ứng.
Trên trang này
Nếu hàng hóa được lưu trên website của bạn, bot có thể lấy danh mục từ đó rồi gửi đơn hàng trở lại. Dịch vụ bên ngoài cần có API, tức giao diện trao đổi dữ liệu giữa các chương trình.
Trong Nguồn dữ liệu, hãy lưu một kết nối gồm địa chỉ API và cách gửi yêu cầu. Trong Khóa truy cập, thêm thông tin xác thực. Sau đó chọn kết nối trong hành động Truy vấn nguồn dữ liệu hoặc Ghi vào nguồn dữ liệu của phản ứng. Với dịch vụ đã có cấu hình sẵn, hãy xem Tích hợp trước.
Kết nối (Nguồn dữ liệu)
Vào Nguồn dữ liệu → Kết nối. Mỗi kết nối có Tên, Loại, URL gốc, thông tin xác thực liên kết và các HTTP header.
| Loại | Dùng để làm gì | Lưu ý |
|---|---|---|
| REST | Kết nối API HTTP/JSON bất kỳ | Cần địa chỉ và thông tin xác thực của dịch vụ |
| OzmaDB | Kết nối cơ sở dữ liệu OzmaDB/FunDB của bạn | URL gốc phải là gốc REST API; có cách đơn giản hơn để đọc view ẩn danh |
| IMAP | Không còn dùng để tạo kết nối mới | Kết nối cũ vẫn xuất hiện với nhãn «không được hỗ trợ» và có thể xóa |
Nút Kiểm tra gửi một yêu cầu thử, hiển thị trạng thái, độ trễ hoặc lỗi để bạn xác nhận URL và khóa.
Thông tin xác thực (Khóa truy cập)
Vào Khóa truy cập → Thông tin xác thực. Chọn cách xác thực theo tài liệu của dịch vụ. Bí mật được lưu dưới dạng mã hóa.
| Cách xác thực | Dữ liệu cần nhập |
|---|---|
| API key | Khóa và tên header, mặc định Authorization |
| Bearer token | Token cho header Authorization: Bearer |
| OAuth2 (password) | Token URL, Client ID/Secret, tên đăng nhập, mật khẩu và scope |
| OAuth2 (refresh) | Token URL, Client ID/Secret, refresh token và scope |
Với OAuth2, GetMyBot tự lấy token truy cập tạm thời rồi làm mới khi token hết hạn hoặc dịch vụ trả 401. Nếu dịch vụ cấp refresh token mới, hệ thống lưu lại. Khi sửa cấu hình, để trống trường bí mật nghĩa là giữ giá trị cũ.
Đọc và ghi dữ liệu trong phản ứng
- Truy vấn nguồn dữ liệu (
ds_query) đọc dữ liệu và lưu vào bộ nhớ tạm của phản ứng (ctx). Nhập đường dẫn yêu cầu, đường dẫn đến danh sách trong câu trả lời (JSONPath) và tên kết quả. Ví dụ, danh sách sản phẩm dưới tênproductscó thể dùng cho nút động hoặc vòng lặp qua danh sách. - Ghi vào nguồn dữ liệu (
ds_write) gửi dữ liệu bằng POST/PUT/DELETE với phần thân JSON.
Phần thân yêu cầu, gửi lại và kiểm tra câu trả lời
Với Yêu cầu web và Ghi vào nguồn dữ liệu, bạn có thể tạo phần thân POST/PUT bằng cây JSON. Mỗi giá trị có loại riêng: chuỗi, số, boolean, JSON hoặc null. Biến thay thế không biến số thành chuỗi, và bạn không cần tự thoát ký tự cho đối tượng lồng nhau. Ví dụ đơn hàng:
{
"customer": { "name": "{{param.name}}", "phone": "{{user.phone}}" },
"amount": 4900,
"paid": false
}
Phần thân dạng văn bản trước đây vẫn dùng được; chuyển chế độ không xóa nội dung đã nhập.
Gửi lại (retry_count) chỉ áp dụng cho lỗi mạng, 429 và 5xx, không áp dụng cho 4xx khác. GET, HEAD, OPTIONS, PUT và DELETE có thể gửi lại. POST và PATCH chỉ được gửi lại khi bạn tự đặt header Idempotency-Key, xác nhận rằng API nhận sẽ loại bỏ yêu cầu trùng khóa. Hệ thống vẫn gửi khóa riêng cho bước thực thi, nhưng khóa đó không tự bật gửi lại POST/PATCH, tránh tạo hai đơn hàng khi kết quả lần đầu không rõ. Các thao tác ghi qua tích hợp và CRM không tự gửi lại trong trường hợp này; ngoại lệ duy nhất là yêu cầu web có Idempotency-Key do bạn đặt.
Kiểm tra câu trả lời của kết nối trong trình chỉnh sửa REST gửi đúng một GET theo kết nối đã lưu, với đường dẫn và tham số bạn nhập (không dùng biến thay thế). Kết quả hiển thị trạng thái, loại và tối đa 64 KB nội dung; không ghi dữ liệu. Có thể lấy JSON trả về làm mẫu cho Phân tích câu trả lời.
Phân tích câu trả lời có trong các hành động dùng dữ liệu bên ngoài: yêu cầu web, truy vấn/ghi nguồn, AI, Google Trang tính, Google Drive, GetCourse và CRM. Nguồn Kết quả hành động là dữ liệu đã được chuẩn hóa; Toàn bộ câu trả lời là phần thân gốc trước khi xử lý. Mọi quy tắc được áp dụng cùng lúc: nếu một quy tắc lỗi, không biến nào được lưu.
Với yêu cầu đơn lẻ không cần lưu kết nối, dùng Yêu cầu web; để tải văn bản trang, dùng Tải URL. Xem Hành động.
View và bảng có tên trong OzmaDB
Lưu kết nối loại OzmaDB, chọn nó trong hành động truy vấn hoặc ghi nguồn, rồi bật chế độ OzmaDB. Các hành động HTTP cũ vẫn giữ chế độ và tham số cũ. Khi chủ động chuyển chế độ, các trường HTTP vẫn được giữ trong hành động; cấu hình Ozma được khôi phục trong lúc trình chỉnh sửa còn mở.
Để đọc, nhập tên tĩnh của Schema và View, hoặc bấm Tải danh mục. Tải thêm lấy các trang kế tiếp mà không làm mất mục đã chọn. Tải đối số và trường gợi ý theo metadata. Với mỗi đối số, nhập tên, loại và giá trị. Nếu không có quyền đọc danh mục hay metadata, bạn vẫn có thể nhập thủ công.
View là truy vấn được lưu, có thể kết hợp bảng và tính giá trị; dùng để đọc. Để tạo hoặc cập nhật bản ghi, hãy chọn riêng bảng Entity. Ví dụ đọc usr.people_by_team với đối số số team_id:
{
"connection": "ozma",
"ozma": {
"schema": "usr",
"view": "people_by_team",
"args": { "team_id": { "type": "number", "value": "42" } },
"limit": 100,
"offset": 0
},
"save_to_ctx": "people"
}
ctx.people chứa mảng đối tượng theo tên cột, chẳng hạn [{"id":7,"name":"Alex"}]. Bạn có thể dùng nó trong vòng lặp và các hành động sau. Kích thước trang mặc định 100, tối đa 500; offset từ 0 đến 100000. Khi đọc nhiều trang, hãy đặt thứ tự ổn định trong view.
Xem trước dữ liệu đọc chỉ đọc tối đa 20 hàng. Đối số phải là giá trị cố định, không có biến của sự kiện; để thử hành động có biến, hãy tạm thay bằng giá trị mẫu. Không có chế độ xem trước cho thao tác ghi.
Để ghi, nhập Schema, Entity, chọn Tạo hoặc Cập nhật, rồi thêm các trường có loại. Cập nhật cần ID bản ghi là số dương, có thể lấy từ hành động trước:
{
"connection": "ozma",
"ozma": {
"schema": "usr",
"entity": "person",
"operation": "update",
"id": "{{ctx.person_id}}",
"fields": {
"name": { "type": "string", "value": "{{text}}" },
"active": { "type": "boolean", "value": "true" },
"details": { "type": "json", "value": "{\"tags\":[\"member\"]}" },
"note": { "type": "null", "value": "" }
}
},
"save_to_ctx": "saved_person"
}
Khóa kết quả là tùy chọn và lưu câu trả lời của giao dịch. ID bản ghi đầu tiên là ctx.saved_person.results[0].id. Để tạo mới, dùng insert mà không có id. Khi tạo, fields rỗng dùng giá trị mặc định của entity; khi cập nhật, cần ít nhất một trường. Metadata loại bỏ các trường tính toán hoặc không được phép cho thao tác đã chọn. OzmaDB kiểm tra quyền và ràng buộc cuối cùng.
Các loại được hỗ trợ: string, number, boolean, json, null. Trong JSON của hành động, value luôn là chuỗi; loại được áp dụng sau khi thay biến lúc chạy. Số giữ nguyên độ chính xác, còn string không tự được hiểu là cú pháp JSON. Loại json chấp nhận JSON hợp lệ hoặc một biến có giá trị JSON; JSON sai sẽ gây lỗi. Tên schema, đối tượng và trường phải cố định, không có biến thay thế.
Nếu đã gửi thao tác ghi mà bị mất câu trả lời, kết quả có thể chưa rõ. Hãy kiểm tra dữ liệu trong OzmaDB trước khi gửi lại. Tự động gửi lại khi không xác nhận được khả năng loại trùng có thể tạo bản ghi lặp. Giao dịch theo lô tường minh vẫn dùng chế độ Yêu cầu HTTP.
Trích xuất dữ liệu bất kỳ từ JSON
Trong một trong hai hành động nguồn, kể cả chế độ HTTP, mở Phân tích câu trả lời. Bật trích xuất và chọn Kết quả hành động sau result_path hoặc chuẩn hóa Ozma, hay Toàn bộ câu trả lời trước khi biến đổi. Khóa kết quả chính vẫn hoạt động; các quy tắc còn lưu thêm vào những khóa ctx bạn đặt.
Sau Xem trước dữ liệu đọc, các hàng tự xuất hiện trong cây Phân tích câu trả lời. Xem trước không tự bật phân tích hay đổi hành động. Bấm một trường để tạo biến có tên, hoặc Lấy từ mọi bản ghi để thu thập giá trị ở tất cả hàng, ví dụ id thành danh sách ids. Quy tắc mới được thêm vào quy tắc cũ; tên trùng được thêm hậu tố. Bạn có thể đổi tên và sao chép biến thay thế.
Các nút Toàn bộ câu trả lời, Bản ghi đầu tiên, Mọi ID tạo cấu hình thường dùng; hai nút sau cần mảng phù hợp trong mẫu. Với thao tác ghi, ID bản ghi đã tạo thêm biến bắt buộc created_id mà không cần tạo bản ghi thử. Phân tích mới dùng toàn bộ câu trả lời; cấu hình cũ giữ nguồn cũ trừ khi bạn tự đổi. Có thể dán JSON mẫu, đổi đường dẫn, chế độ và cách đọc JSON lồng trong chuỗi ở phần nâng cao. Cây lớn chỉ hiện một phần. Mẫu không được lưu vào tham số hành động hoặc phân tích kịch bản. Kiểm tra phân tích chạy bộ phân tích trên mẫu, không gọi nguồn dữ liệu.
Ví dụ câu trả lời lồng nhau:
{
"results": [{ "id": 9007199254740993 }],
"groups": [
{ "members": [{ "name": "Alex", "active": false }] },
{ "members": [{ "name": "Sam", "active": true }] }
],
"extra": "{\"status\":{\"ready\":false}}"
}
Thêm vào tham số hành động:
{
"response_parser": {
"source": "raw",
"decode_json_strings": true,
"rules": [
{ "path": "$.results[0].id", "save_to_ctx": "created_id", "mode": "value", "required": true },
{ "path": "$.groups[*].members[*].name", "save_to_ctx": "member_names", "mode": "list" },
{ "path": "/extra/status/ready", "save_to_ctx": "ready", "mode": "value" }
]
}
}
Các quy tắc giữ nguyên ID lớn, lưu danh sách ["Alex","Sam"] và boolean false. Sau khi tạo thành công, có thể đưa {{ctx.created_id}} vào ID bản ghi của lần cập nhật sau. Có thể chọn chuỗi, số, boolean, đối tượng, mảng, null và toàn bộ gốc $. Đọc JSON trong chuỗi mở cả JSON lồng nhau hợp lệ trong cây mẫu.
Đường dẫn hỗ trợ .name, ["a.b"] (thoát ký tự JSON), chỉ số dương/âm ([0], [-1]), mọi phần tử ([*], .*), lát cắt ([1:3]) và JSON Pointer theo RFC 6901. Khóa chữ a/b dùng /a~1b, ký tự ~ thành ~0, còn / chọn khóa rỗng. Không hỗ trợ bộ lọc, biểu thức hoặc script.
Chế độ Một giá trị báo lỗi nếu có nhiều kết quả; đường dẫn wildcard nên dùng Danh sách giá trị. Quy tắc bắt buộc báo lỗi nếu không tìm thấy. Giá trị đơn không bắt buộc và không tìm thấy trở thành null; danh sách không tìm thấy trở thành []. Trong màn hình xem trước, null tìm thấy được phân biệt với không tìm thấy. Mọi quy tắc được tính trước khi đổi ctx. Giới hạn: 32 quy tắc, 1024 byte mỗi đường dẫn, 1 MiB dữ liệu vào/ra, 1000 kết quả mỗi quy tắc và giới hạn độ sâu/khối lượng duyệt.
ID hàng và nhãn quan hệ Ozma
Hai tùy chọn đọc Thêm ID bản ghi chính (mainId) và Thêm nhãn giá trị liên kết (pun) bật riêng. include_main_id: true thêm mainId của hàng; parse_pun: true biểu diễn ô có nhãn thành { "id": 42, "data": "Label" }. Nếu cột đã tên mainId, hệ thống báo lỗi xung đột. Hai tùy chọn không đổi toàn bộ câu trả lời gốc.
Sau khi đọc, bạn có thể chuyển nguồn giữa các hàng đã chuẩn hóa và toàn bộ câu trả lời trong Cài đặt phân tích nâng cao. Cấu hình cũ dùng toàn bộ câu trả lời sẽ tự hiện mẫu tương ứng. Đổi đối tượng, đối số hoặc cờ đọc sẽ xóa mẫu tự động cũ. Cây dữ liệu hiện ngay; JSON mẫu và Câu trả lời JSON mở khi bấm. Mẫu vượt giới hạn sẽ tự mở thông báo và trình sửa.
Trong hành động kế tiếp, mở Biến thay thế, tìm created_id trong Từ hành động trước rồi bấm Chèn cạnh {{ctx.created_id}} vào ID bản ghi hoặc đối số. Biến được chèn tại vị trí con trỏ. Danh sách chỉ chứa kết quả từ hành động trước trong cùng khối; đổi tên, xóa hoặc chuyển thứ tự sẽ cập nhật ngay.
Tìm trong danh mục và metadata đối tượng
Với hành động đọc Ozma mới, Khóa kết quả trong ngữ cảnh nằm trước phần chọn đối tượng. Khi chọn Ozma, hệ thống gợi ý ozma_rows và thêm hậu tố nếu tên này đã được quy tắc phân tích dùng. Tên cũ hoặc trường đã được bạn xóa trắng được giữ nguyên. Khóa kết quả bắt buộc khi đọc, tùy chọn khi ghi; thiếu khóa đọc sẽ báo lỗi ngay cạnh trường.
Tải danh mục lấy 50 view để đọc hoặc 50 entity để ghi. Trong Đối tượng từ danh mục, tìm theo schema.name trên toàn danh mục từ xa. Tìm chuỗi con theo nghĩa đen, không phân biệt chữ hoa/thường; _ và % là ký tự bình thường. Tải thêm tiếp tục từ offset máy chủ trả. Đối tượng đã chọn vẫn hiện khi đổi tìm kiếm; bạn vẫn nhập tên thủ công khi không có quyền xem danh mục. Có thể thử lại một trang lỗi mà không cần nhập lại.
Tải đối số và trường cho biết đối số bắt buộc, đích tham chiếu, loại cột và bảng chính. Metadata bổ sung mở các trường chưa biết và đối tượng/mảng được mã hóa thành chuỗi JSON. Số giữ nguyên cách viết chính xác. Dữ liệu quá lớn hoặc quá sâu sẽ có thông báo giới hạn. Xem metadata không đổi hành động hay quy tắc phân tích.
Toàn bộ quy trình cấu hình Ozma
Trong biểu mẫu kết nối Ozma, tên và loại nằm riêng với địa chỉ máy chủ và khóa đã lưu. HTTP header bổ sung thu gọn khi trống và mở khi đã có giá trị. Kết quả kiểm tra nằm cạnh nút kiểm tra; khóa được chọn bằng liên kết. Sau khi đổi cấu hình Ozma, trạng thái kiểm tra cũ được ẩn; kết quả đến muộn của cấu hình cũ không xác nhận cấu hình mới.
Trong hành động, kết nối và chế độ nằm cạnh nhau, khóa kết quả ở đầu biểu mẫu, schema.view hoặc schema.entity đã chọn hiện phía trên phần đối tượng. Schema và tên thủ công thu gọn khi đối tượng hợp lệ, mở nếu tên rỗng/sai hoặc không có quyền. Đối số và trường ghi được chỉnh theo hàng: tên, loại, giá trị, xóa. Gợi ý bắt buộc từ metadata luôn hiện; Loại và biến thay thế mở phần giải thích.
Tham số đọc gộp phân trang với tùy chọn ID và nhãn liên kết. Giá trị mặc định được thu gọn; giá trị khác mặc định hoặc lỗi phân trang mở các trường tương ứng. Kiểm tra đọc hiện hàng đã chuẩn hóa dưới dạng bảng trước, rồi có thể mở Câu trả lời JSON. Khi không có hàng, giao diện chỉ rõ điều cần kiểm tra và vẫn giữ số chính xác. JSON chuẩn hóa và Toàn bộ câu trả lời OzmaDB là hai phần có thể mở riêng.
Phần phân tích câu trả lời Ozma nhóm lựa chọn nhanh, biến kết quả, cài đặt đường dẫn nâng cao, mẫu/cây dữ liệu cục bộ và kết quả kiểm tra. Hành động HTTP cũ giữ giao diện và hành vi phân tích trước đây. Metadata bổ sung mở trực tiếp đến các trường, không cần thêm một tầng thư mục.
Bước tiếp theo
- Hành động: cách dùng
Truy vấn nguồn dữ liệuvàGhi vào nguồn dữ liệu. - Biến thay thế và công thức: dùng kết quả trong
ctx. - Tích hợp: kết nối được cấu hình sẵn cho các dịch vụ phổ biến.