zkk 2f184c317d 合并最新内容,适配开门检测机型
# Conflicts:
#	moonraker/components/file_manager/metadata.py   resolved by ada08d4574e13099a392bba4b3ebe34485807c0a version
2025-03-31 11:37:27 +08:00

453 lines
18 KiB
Markdown

# Job History
Moonraker's `history` component tracks print job completion data.
The following endpoints are available to manage Moonraker's job
history data.
## Get job list
```{.http .apirequest title="HTTP Request"}
GET /server/history/list?limit=50&start=50&since=1&before=5&order=asc
```
```{.json .apirequest title="JSON-RPC Request"}
{
"jsonrpc": "2.0",
"method": "server.history.list",
"params":{
"limit": 50,
"start": 10,
"since": 464.54,
"before": 1322.54,
"order": "asc"
},
"id": 5656
}
```
/// api-parameters
open: True
| Name | Type | Default | Description |
| -------- | :----: | --------- | ----------------------------------------------- |
| `limit` | int | 50 | Maximum number of job entries to return. |
| `start` | int | 0 | The record number indicating the first entry |
| | | | of the returned list. |^
| `before` | float | undefined | A timestamp in unix time. When specified, the |
| | | | returned list will only contain entries created |^
| | | | before this date. |^
| `since` | float | undefined | A timestamp in unix time. When specified, the |
| | | | returned list will only contain entries created |^
| | | | after this date. |^
| `order` | string | "desc" | The order of the list returned. May be `asc` |
| | | | (ascending) or `desc` (descending). |^
///
/// collapse-code
```{.json .apiresponse title="Example Response"}
{
"count": 1,
"jobs": [
{
"job_id": "000001",
"exists": true,
"end_time": 1615764265.6493807,
"filament_used": 7.83,
"filename": "test/history_test.gcode",
"metadata": {
// Object containing metadata at time of job
},
"print_duration": 18.37201827496756,
"status": "completed",
"start_time": 1615764496.622146,
"total_duration": 18.37201827496756,
"user": "testuser",
"auxiliary_data": [
{
"provider": "sensor hist_test",
"name": "power_consumption",
"value": 4.119977,
"description": "Printer Power Consumption",
"units": "kWh"
},
{
"provider": "sensor hist_test",
"name": "max_current",
"value": 2.768851,
"description": "Maximum current draw",
"units": "A"
},
{
"provider": "sensor hist_test",
"name": "min_current",
"value": 0.426725,
"description": "Minimum current draw",
"units": "A"
},
{
"provider": "sensor hist_test",
"name": "avg_current",
"value": 1.706872,
"description": "Average current draw",
"units": "A"
},
{
"provider": "sensor hist_test",
"name": "status",
"value": 2,
"description": "Power Switch Status",
"units": null
},
{
"provider": "sensor hist_test",
"name": "filament",
"value": 19.08058495194607,
"description": "filament usage tracker",
"units": "mm"
},
{
"provider": "spoolman",
"name": "spool_ids",
"value": [
1
],
"description": "Spool IDs used",
"units": null
}
]
}
]
}
```
///
/// api-response-spec
open: True
| Field | Type | Description |
| ------- | :------: | -------------------------------------------------- |
| `count` | int | The number of entries returned by the query. |
| `jobs` | [object] | An array of [Job History](#job-history-entry-spec) |
| | | objects. |^
| Field | Type | Description |
| ---------------- | :------------: | ----------------------------------------------------------- |
| `job_id` | string | A unique ID for the entry. |
| `user` | string \| null | The user that started the job. Will be `null` |
| | | if Moonraker cannot identify a user (ie: job) |^
| | | was started via Klipper's display. |^
| `filename` | string | The path, relative to `gcodes` root, of the file |
| | | associated with the job. |^
| `exists` | bool | A value of `true` indicates that the file |
| | | associated with the job exists on disk and has |^
| | | not been modified. |^
| `status` | string | The [job status](#job-history-status-desc) |
| | | at the time of query. |^
| `start_time` | float | A timestamp, in unix time, indicating when |
| | | the job started. |^
| `end_time` | float \| null | A timestamp, in unix time, indicating when |
| | | the job finished. Will be `null` if the |^
| | | job is in progress or if Moonraker is |^
| | | interrupted prior to the job completion. |^
| `print_duration` | float | The amount of time, in seconds, the job |
| | | spent printing (ie: printer not idle). |^
| `total_duration` | float | The total amount of time, in seconds, the |
| | | job took to print. This includes time paused. |^
| `filament_used` | float | The amount of filament (in mm) used during the job. |
| `metadata` | object | The [gcode metadata](./file_manager.md#gcode-metadata-spec) |
| | | object associated with the job. The `job_id` and |^
| | | `print_start_time` fields are removed from the metadata as |^
| | | they are redundant. |^
| `auxiliary_data` | [object] | An array of [auxiliary field](#job-history-aux-field-spec) |
| | | objects containing supplemental history data related to |^
| | | the job. |^
{ #job-history-entry-spec } Job History
| Field | Type | Description |
| ------------- | :------------: | ------------------------------------------------- |
| `provider` | string | The component or extension that generated the |
| | | auxiliary field. |^
| `name` | string | A name identifying the field. |
| `description` | string | A brief description of the data in this entry. |
| `value` | any | The value associated with the field. Can be any |
| | | valid JSON type. |^
| `units` | string \| null | The unit type associated with the value. For |
| | | example this would be `mm` for millimeters. Can |^
| | | be `null` if no unit abbreviation is appropriate. |^
{ #job-history-aux-field-spec } Auxiliary Field
| Status | Description |
| ------------------- | ----------------------------------------------------- |
| `in_progress` | The job is currently active. |
| `completed` | The job successfully completed. |
| `cancelled` | The job was cancelled by the user. |
| `error` | The job was aborted due to an error during execution. |
| `klippy_shutdown` | The job was aborted due to Klippy Shutdown. |
| `klippy_disconnect` | Moonraker's connection to Klippy was lost while the |
| | job was in progress. |^
| `interrupted` | Moonraker was abruptly terminated while the job was |
| | in progress. |^
{ #job-history-status-desc } Job Status
///
## Get job totals
```{.http .apirequest title="HTTP Request"}
GET /server/history/totals
```
```{.json .apirequest title="JSON-RPC Request"}
{
"jsonrpc": "2.0",
"method": "server.history.totals",
"id": 5656
}
```
/// collapse-code
```{.json .apiresponse title="Example Response"}
{
"job_totals": {
"total_jobs": 3,
"total_time": 11748.077333278954,
"total_print_time": 11348.794790096988,
"total_filament_used": 11615.718840001999,
"longest_job": 11665.191012736992,
"longest_print": 11348.794790096988
},
"auxiliary_totals": [
{
"provider": "sensor hist_test",
"field": "power_consumption",
"maximum": 4.119977,
"total": 4.119977
},
{
"provider": "sensor hist_test",
"field": "avg_current",
"maximum": 1.706872,
"total": null
},
{
"provider": "sensor hist_test",
"field": "filament",
"maximum": 19.08058495194607,
"total": 19.08058495194607
}
]
}
```
///
/// api-response-spec
open: True
| Field | Type | Description |
| ------------------ | :------: | ----------------------------------------------- |
| `job_totals` | object | A [Job Totals](#job-history-totals-spec) object |
| | | reporting all current totals. |^
| `auxiliary_totals` | [object] | An array of |
| | | [Auxiliary Total](#job-auxiliary-totals-spec) |^
| | | objects. |^
| Field | Type | Description |
| --------------------- | :------: | ------------------------------------------------------ |
| `total_jobs` | int | The total number of jobs tracked. |
| `total_time` | float | The total amount of job work time (in seconds) |
| | | across all jobs, including time paused. |^
| `total_print_time` | float | The total amount of time printing (in seconds) |
| | | across all jobs. |^
| `total_filament_used` | float | The total amount of filament used (in mm) across |
| | | all jobs. |^
| `longest_job` | float | The maximum time spent working on a single job, |
| | | including time paused. |^
| `longest_print` | float | The maximum time spent printing a single job. |
| `auxiliary_totals` | [object] | An array of |
| | | [Auxiliary Total](#job-auxiliary-totals-spec) objects. |^
{ #job-history-totals-spec } Job Totals
| Field | Type | Description |
| ---------- | :-----------: | ----------------------------------------------- |
| `provider` | string | The component or extension that generated the |
| | | auxiliary totals. |^
| `field` | string | The corresponding `name` of the auxiliary field |
| | | used to generate totals. |^
| `maximum` | float \| null | The maximum value observed across all prints. |
| | | Will be `null` if the maximum is not available. |^
| `total` | float \| null | The accumulated total value across all prints. |
| | | Will be `null` if the total is not available. |^
{ #job-auxiliary-totals-spec } Auxiliary Total
///
## Reset totals
Resets the persistent "job totals" to zero.
```{.http .apirequest title="HTTP Request"}
POST /server/history/reset_totals
```
```{.json .apirequest title="JSON-RPC Request"}
{
"jsonrpc": "2.0",
"method": "server.history.reset_totals",
"id": 5534
}
```
/// collapse-code
```{.json .apiresponse title="Example Response"}
{
"last_totals": {
"total_jobs": 3,
"total_time": 11748.077333278954,
"total_print_time": 11348.794790096988,
"total_filament_used": 11615.718840001999,
"longest_job": 11665.191012736992,
"longest_print": 11348.794790096988
},
"last_auxiliary_totals": [
{
"provider": "sensor hist_test",
"field": "power_consumption",
"maximum": 4.119977,
"total": 4.119977
},
{
"provider": "sensor hist_test",
"field": "avg_current",
"maximum": 1.706872,
"total": null
},
{
"provider": "sensor hist_test",
"field": "filament",
"maximum": 19.08058495194607,
"total": 19.08058495194607
}
]
}
```
///
/// api-response-spec
open: True
| Field | Type | Description |
| ----------------------- | :------: | ----------------------------------------------- |
| `last_totals` | object | A [Job Totals](#job-history-totals-spec) object |
| | | reporting all totals prior to the reset. |^
| `last_auxiliary_totals` | [object] | An array of |
| | | [Auxiliary Total](#job-auxiliary-totals-spec) |^
| | | objects reporting totals prior to the reset. |^
///
## Get a single job
```{.http .apirequest title="HTTP Request"}
GET /server/history/job?uid=<id>
```
```{.json .apirequest title="JSON-RPC Request"}
{
"jsonrpc": "2.0",
"method": "server.history.get_job",
"params":{"uid": "{uid}"},
"id": 4564
}
```
/// api-parameters
open: True
| Name | Type | Default | Description |
| ----- | :----: | ------------ | --------------------------------------- |
| `uid` | string | **REQUIRED** | The unique identifier for the requested |
| | | | job history. |^
///
/// collapse-code
```{.json .apiresponse title="Example Response"}
{
"job": {
"job_id": "000001",
"exists": true,
"end_time": 1615764265.6493807,
"filament_used": 7.83,
"filename": "test/history_test.gcode",
"metadata": {
// Object containing metadata at time of job
},
"print_duration": 18.37201827496756,
"status": "completed",
"start_time": 1615764496.622146,
"total_duration": 18.37201827496756
}
}
```
///
/// api-response-spec
open: True
| Field | Type | Description |
| ----- | :----: | ------------------------------------------------------------- |
| `job` | object | The requested [Job History](#job-history-entry-spec ) object. |
///
## Delete a job
```{.http .apirequest title="HTTP Request"}
DELETE /server/history/job?uid=<id>
```
```{.json .apirequest title="JSON-RPC Request"}
{
"jsonrpc": "2.0",
"method": "server.history.delete_job",
"params":{
"uid": "{uid}"
},
"id": 5534
}
```
/// api-parameters
open: True
| Name | Type | Default | Description |
| ----- | :----: | --------------- | ------------------------------------------ |
| `uid` | string | **REQUIRED** | The unique identifier for the job entry |
| | | if `all==false` | to delete. |^
| `all` | bool | false | When set to `true` all job history entries |
| | | | will be removed. |^
//// tip
If `all = true` is specified the `uid` parameter should be omitted.
////
///
```{.json .apiresponse title="Example Response"}
{
"deleted_jobs": [
"000000",
"000001"
]
}
```
/// api-response-spec
open: True
| Field | Type | Description |
| -------------- | :------: | ------------------------------------- |
| `deleted_jobs` | [string] | An array of unique IDs indicating the |
| | | job entries that were deleted. |^
///