hosting
POST /v1/bulk-jobs
Run one operation across many sites.
Xác thực
Gửi khóa API dưới dạng mã thông báo bearer. Khóa này phải có quyền sites.view; khóa không có quyền này sẽ bị từ chối với mã lỗi 403, không phải 404.
Endpoint này không nhận ID tổ chức. Khóa của bạn đã xác định tổ chức mà nó thuộc về và phản hồi được giới hạn trong phạm vi đó.
Dùng thử
Thay thế bất kỳ nội dung nào trong ngoعل (angle brackets) bằng giá trị của riêng bạn và trình giữ chỗ key bằng một key từ trang tổng quan của bạn.
curl -X POST https://api.zinndigital.com/v1/bulk-jobs \
-H "Authorization: Bearer zdk_live_…" \
-H "Content-Type: application/json" \
-d '{ "operation": <BulkOperation>, "selector": <BulkSelector> }'Đã đăng nhập? Bảng điều khiển API trong trang quản lý của bạn sẽ tự điền ID tổ chức thực tế và khóa của riêng bạn, sau đó chạy yêu cầu đối với API trực tiếp để bạn có thể xem phản hồi thực tế. Mở điểm cuối này trong bảng điều khiển API
Chi tiết
Freezes the selection into a per-site work-list and starts a durable, idempotent workflow. The submit is instant and the work is not — this returns 202 as soon as the rows are written, and nothing a person is watching waits on the job itself. Only eligible sites are enrolled; ineligible ones are not written as pre-failed rows, because a report padded with rows that never had a chance makes the failures that matter harder to find. previewBulkJob is where you see them. A selection that enrolls nothing is a 422, not a job that completes instantly: "completed, 0 of 0" is indistinguishable from success on every screen that renders it. ⛔ A typed confirm phrase is required when the selector is wider than an explicit list (product_line, org) or the operation is weighty (plugin_remove, plugin_deactivate, blueprint_apply) at any size. previewBulkJob returns the exact phrase in confirmation_phrase. ⛔ All the selected sites must belong to one organization. A mixed selection is a 422 naming the problem rather than a job whose owner is a guess. Requires sites.view plus the operation's own key (see the tag description).
Tham số
| Tên | Loại | Bắt buộc | Nội dung này là gì |
|---|---|---|---|
Idempotency-Key (header) | string | Không | Client-generated key that makes an unsafe request replay-safe: the server stores the first response and returns it verbatim for repeats. |
Nội dung yêu cầu
| Tên | Loại | Bắt buộc | Nội dung này là gì |
|---|---|---|---|
operation | BulkOperation | Có | What a bulk job does to each of its sites. ⛔ One job model with an operation discriminator, not eight job models. A selection, a frozen work-list, a durable pass and a per-site… |
selector | BulkSelector | Có | Which sites a job targets. ⛔ There is no all. A job belongs to exactly one organization and all would span every tenant on the platform; the fleet-wide act is a staff… |
selector_value | string | Không | The selector's argument — a product-line code for product_line, an organization id for org, a site-group id for group. Ignored for sites, whose members are site_ids. |
site_ids | Uuid[] | Không | The explicit selection, for selector: sites. Every id is fenced to the organizations you can reach, so one belonging to somebody else resolves to nothing rather than to a… |
params | BulkJobParams | Không | The operation's arguments. Which keys are read depends on operation: plugin_install takes slugs + activate; plugin_activate, plugin_deactivate and plugin_remove take… |
confirm | string | Không | The typed confirmation phrase, required when previewBulkJob answers confirmation_required: true. Send exactly the value it returned in confirmation_phrase. ⛔ Whether it is… |
note | string | Không | Free text kept with the job, for whoever reads the report later. |
Phản hồi
| Tên | Loại | Bắt buộc | Nội dung này là gì |
|---|---|---|---|
id | Uuid | Có | UUIDv7 identifier — sortable by creation time (docs/02 §8). |
org_id | Uuid | Có | UUIDv7 identifier — sortable by creation time (docs/02 §8). |
operation | BulkOperation | Có | What a bulk job does to each of its sites. ⛔ One job model with an operation discriminator, not eight job models. A selection, a frozen work-list, a durable pass and a per-site… |
params | BulkJobParams | Có | The operation's arguments. Which keys are read depends on operation: plugin_install takes slugs + activate; plugin_activate, plugin_deactivate and plugin_remove take… |
selector | BulkSelector | Có | Which sites a job targets. ⛔ There is no all. A job belongs to exactly one organization and all would span every tenant on the platform; the fleet-wide act is a staff… |
selector_value | string | Có | — |
status | BulkJobStatus | Có | ⛔ partial is a real outcome, not a rounding of the other two. A job where 4 of 900 sites failed is neither a success nor a failure, and reporting it as either is how a bulk… |
requested_by | string | Có | Who asked for it. |
note | string | Có | — |
created_at | string | Có | — |
updated_at | string | Có | — |
settled_at | object | Có | When the job finished; null while it is still running. |
counts | BulkJobCounts | Có | — |
progress | BulkJobProgress | Có | How far along a job is, how fast it is going and how much longer it has. ⛔⛔ Every estimate here is nullable, and a null must never be rendered as 0. rate_per_minute: 0… |
Các lỗi điểm cuối này có thể trả về
401 · 403 · 409 · 422 · 429