diff --git a/content/enterprise_influxdb/v1.10/tools/influxd-ctl.md b/content/enterprise_influxdb/v1.10/tools/influxd-ctl.md index 8a1512fe9..00007925f 100644 --- a/content/enterprise_influxdb/v1.10/tools/influxd-ctl.md +++ b/content/enterprise_influxdb/v1.10/tools/influxd-ctl.md @@ -1073,8 +1073,7 @@ Restored from my-full-backup in 58.58301ms, transferred 569344 bytes ### `show` -Shows all [meta nodes](/enterprise_influxdb/v1.10/concepts/glossary/#meta-node) and [data nodes](/enterprise_influxdb/v1.10/concepts/glossary/#data-node) that are part of the cluster. -The output includes the InfluxDB Enterprise version number and any [labels](#node-labels). +Shows all [meta nodes](/enterprise_influxdb/v1.10/concepts/glossary/#meta-node) and [data nodes](/enterprise_influxdb/v1.10/concepts/glossary/#data-node) that are part of the cluster. The output includes the `RAFT status` of all meta nodes, the InfluxDB Enterprise version number and any [labels](#node-labels). #### Syntax @@ -1086,24 +1085,29 @@ influxd-ctl show ##### Show all meta and data nodes in a cluster -In this example, the `show` command output displays that the cluster includes three meta nodes and two data nodes. -Every node is using InfluxDB Enterprise `1.10.x-c1.10.x`. +In this example, the `show` command output displays the cluster includes three meta nodes and two data nodes. Every node is InfluxDB Enterprise version `1.10.0`. The RAFT status shows `metatest_meta_0_1:8089` as the leader node, and the other two meta nodes as peers. ```bash $ influxd-ctl show Data Nodes ========== -ID TCP Address Version Labels -2 cluster-node-01:8088 1.10.x-c1.10.x {} -4 cluster-node-02:8088 1.10.x-c1.10.x {} - +ID TCP Address HTTP Address Version Labels +4 test_data_0_1:8088 test_data_0_1:8086 1.10.0 {} +5 test_data_0_2:8088 test_data_0_2:8086 1.10.0 {} + Meta Nodes ========== -TCP Address Version Labels -cluster-node-01:8091 1.10.x-c1.10.x {} -cluster-node-02:8091 1.10.x-c1.10.x {} -cluster-node-03:8091 1.10.x-c1.10.x {} +ID Raft Address HTTP Address Version Labels +1 test_meta_0_1:8089 test_meta_0_1:8091 1.10.0 {} +2 test_meta_1_1:8089 test_meta_1_1:8091 1.10.0 {} +3 test_meta_1_2:8089 test_meta_1_2:8091 1.10.0 {} + +Raft Status +========== +Leader test_meta_0_1:8089 +Peers ["test_meta_1_1:8089", "test_meta_1_2:8089"] + ``` ##### Show active and passive data nodes in a cluster @@ -1113,9 +1117,9 @@ In this example, the `show` command output displays that the cluster includes a Data Nodes ========== ID TCP Address Version Labels Passive -4 cluster-node_0_1:8088 1.10.6-c1.10.6 {} false -5 cluster-node_1_1:8088 1.10.6-c1.10.6 {} true -6 cluster-node_2_1:8088 1.10.6-c1.10.6 {} false +4 cluster-node_0_1:8088 1.10.0 {} false +5 cluster-node_1_1:8088 1.10.0 {} true +6 cluster-node_2_1:8088 1.10.0 {} false ``` ### `show-shards` diff --git a/content/enterprise_influxdb/v1.9/tools/influxd-ctl.md b/content/enterprise_influxdb/v1.9/tools/influxd-ctl.md index c5424450d..c37ab5b4b 100644 --- a/content/enterprise_influxdb/v1.9/tools/influxd-ctl.md +++ b/content/enterprise_influxdb/v1.9/tools/influxd-ctl.md @@ -1079,24 +1079,25 @@ influxd-ctl show ##### Show all meta and data nodes in a cluster In this example, the `show` command output displays that the cluster includes three meta nodes and two data nodes. -Every node is using InfluxDB Enterprise `1.9.x-c1.9.x`. +Every node is using InfluxDB Enterprise `1.9.8`. ```bash $ influxd-ctl show Data Nodes ========== -ID TCP Address Version Labels -2 cluster-node-01:8088 1.9.x-c1.9.x {} -4 cluster-node-02:8088 1.9.x-c1.9.x {} +ID TCP Address Version Labels +4 meta-node-01:8088 1.9.8 {} +5 meta-node-02:8088 1.9.8 {} Meta Nodes ========== -TCP Address Version Labels -cluster-node-01:8091 1.9.x-c1.9.x {} -cluster-node-02:8091 1.9.x-c1.9.x {} -cluster-node-03:8091 1.9.x-c1.9.x {} +ID TCP Address Version Labels +1 data-node-01:8091 1.9.8 {} +2 data-node-02:8091 1.9.8 {} +3 data-node-03:8091 1.9.8 {} ``` + ##### Show active and passive data nodes in a cluster In this example, the `show` command output displays that the cluster includes a passive data node. @@ -1105,12 +1106,11 @@ In this example, the `show` command output displays that the cluster includes a Data Nodes ========== ID TCP Address Version Labels Passive -4 cluster-node_0_1:8088 1.9.6-c1.9.6 {} false -5 cluster-node_1_1:8088 1.9.6-c1.9.6 {} true -6 cluster-node_2_1:8088 1.9.6-c1.9.6 {} false +4 cluster-node_0_1:8088 1.9.6 {} false +5 cluster-node_1_1:8088 1.9.6 {} true +6 cluster-node_2_1:8088 1.9.6 {} false ``` - ### `show-shards` Outputs details about existing [shards](/enterprise_influxdb/v1.9/concepts/glossary/#shard) of the cluster, including shard ID, database, [retention policy](/enterprise_influxdb/v1.9/concepts/glossary/#retention-policy-rp), desired replicas, [shard group](/enterprise_influxdb/v1.9/concepts/glossary/#shard-group), starting timestamp, ending timestamp, expiration timestamp, and [data node](/enterprise_influxdb/v1.9/concepts/glossary/#data-node) owners. diff --git a/content/influxdb/v2.3/process-data/_index.md b/content/influxdb/v2.3/process-data/_index.md index 02bcedcc8..87da9376f 100644 --- a/content/influxdb/v2.3/process-data/_index.md +++ b/content/influxdb/v2.3/process-data/_index.md @@ -13,13 +13,13 @@ related: - /resources/videos/influxdb-tasks/ --- -Process and analyze your data with tasks in the InfluxDB **task engine**. Use tasks (scheduled Flux queries) +Process and analyze your data with tasks in the InfluxDB **task engine**. +Use tasks (scheduled Flux queries) to input a data stream and then analyze, modify, and act on the data accordingly. Discover how to create and manage tasks using the InfluxDB user interface (UI) -and the `influx` command line interface (CLI). -Find examples of data downsampling, anomaly detection _(Coming)_, alerting -_(Coming)_, and other common tasks. +the `influx` command line interface (CLI), and the InfluxDB `/api/v2` API. +Find examples of data downsampling and other common tasks. {{% note %}} Tasks replace InfluxDB v1.x continuous queries. diff --git a/content/influxdb/v2.3/process-data/common-tasks/calculate_weekly_mean.md b/content/influxdb/v2.3/process-data/common-tasks/calculate_weekly_mean.md index e0b97153d..261adedcc 100644 --- a/content/influxdb/v2.3/process-data/common-tasks/calculate_weekly_mean.md +++ b/content/influxdb/v2.3/process-data/common-tasks/calculate_weekly_mean.md @@ -16,11 +16,12 @@ This example uses [NOAA water sample data](/influxdb/v2.3/reference/sample-data/ This example calculates a temperature weekly mean and stores it in a separate bucket. -The following query: - - Uses [`filter()`](/{{< latest "flux" >}}/stdlib/universe/filter/) to filter the `average_temperature` measurement. - - Uses [`range()`](/{{< latest "flux" >}}/stdlib/universe/range/) to define a time range. - - Uses [`aggregateWindow()`](/{{< latest "flux" >}}/stdlib/universe/aggregatewindow/) to group average temperature by week and compute the mean. - - Sends the weekly mean to a new bucket (`weekly_means`) +The sample query performs the following operations: + +- Uses [`filter()`](/{{< latest "flux" >}}/stdlib/universe/filter/) to select records with the `average_temperature` measurement. +- Uses [`range()`](/{{< latest "flux" >}}/stdlib/universe/range/) to define the start time. +- Uses [`aggregateWindow()`](/{{< latest "flux" >}}/stdlib/universe/aggregatewindow/) to group records by week and compute the mean. +- Sends the weekly mean to a new bucket (`weekly_means`). ```js option task = { @@ -34,6 +35,7 @@ from(bucket: "noaa") |> aggregateWindow(every: 1w, fn: mean) |> to(bucket: "weekly_means") ``` + ### Example results | _start | _stop | _field | _measurement | location | _value | _time | diff --git a/content/influxdb/v2.3/process-data/get-started.md b/content/influxdb/v2.3/process-data/get-started.md index 9712a9863..9bc63ea31 100644 --- a/content/influxdb/v2.3/process-data/get-started.md +++ b/content/influxdb/v2.3/process-data/get-started.md @@ -76,7 +76,7 @@ To learn more about using tasks with invokable scripts, see the [API reference d ## Retrieve and filter data -A basic Flux script uses the following functions to retrieve a specified amount +A minimal Flux script uses the following functions to retrieve a specified amount of data from a data source and then filter the data based on time or column values: @@ -139,6 +139,14 @@ from(bucket: "example-bucket") |> aggregateWindow(every: 5m, fn: mean) ``` +{{% note %}} +#### Use offset to account for latent data + +Use the `offset` task option to account for potentially latent data (like data from edge devices). +A task that runs at one hour intervals (`every: 1h`) with an offset of five minutes (`offset: 5m`) +executes 5 minutes after the hour, but queries data from the original one-hour interval. +{{% /note %}} + _See [Common tasks](/influxdb/v2.3/process-data/common-tasks) for examples of tasks commonly used with InfluxDB._ {{% cloud-only %}} diff --git a/content/influxdb/v2.3/process-data/manage-tasks/delete-task.md b/content/influxdb/v2.3/process-data/manage-tasks/delete-task.md index 3adf3cca9..d3ccc5aa2 100644 --- a/content/influxdb/v2.3/process-data/manage-tasks/delete-task.md +++ b/content/influxdb/v2.3/process-data/manage-tasks/delete-task.md @@ -24,8 +24,6 @@ related: ## Delete a task with the influx CLI Use the `influx task delete` command to delete a task. -_This command requires a task ID, which is available in the output of `influx task list`._ - ```sh # Syntax influx task delete -i @@ -33,3 +31,18 @@ influx task delete -i # Example influx task delete -i 0343698431c35000 ``` + +_To find the task ID, see [how to view tasks](/influxdb/v2.3/process-data/manage-tasks/view-tasks/)._ + +## Delete a task using the InfluxDB API + +Use the [`/tasks/TASK_ID` InfluxDB API endpoint](/influxdb/v2.3/api/#operation/DeleteTasksID) to delete a task and all associated records (task runs, logs, and labels). + +{{< api-endpoint method="DELETE" endpoint="http://localhost:8086/api/v2/tasks/TASK_ID" >}} + +_To find the task ID, see [how to view tasks](/influxdb/v2.3/process-data/manage-tasks/view-tasks/)._ + +Once the task is deleted, InfluxDB cancels all scheduled runs of the task. + +If you want to disable a task instead of delete it, see how to +[update the task status](/influxdb/v2.3/process-data/manage-tasks/update-task/) to `inactive`. diff --git a/content/influxdb/v2.3/process-data/manage-tasks/run-task.md b/content/influxdb/v2.3/process-data/manage-tasks/run-task.md index 2089dbbf0..54a647dea 100644 --- a/content/influxdb/v2.3/process-data/manage-tasks/run-task.md +++ b/content/influxdb/v2.3/process-data/manage-tasks/run-task.md @@ -12,11 +12,14 @@ related: - /influxdb/v2.3/reference/cli/influx/task/run - /influxdb/v2.3/reference/cli/influx/task/run/retry - /influxdb/v2.3/reference/cli/influx/task/retry-failed + - /influxdb/v2.3/api/#operation/PostTasksIDRuns + - /influxdb/v2.3/api/#operation/PostTasksIDRunsIDRetry --- InfluxDB data processing tasks generally run in defined intervals or at a specific time, -however, you can manually run a task from the InfluxDB user interface (UI) or the -`influx` command line interface (CLI). +however, you can manually run a task from the InfluxDB user interface (UI), +the `influx` command line interface (CLI), +or the InfluxDB `/api/v2` API. ## Run a task from the InfluxDB UI 1. In the navigation menu on the left, select **Tasks**. @@ -64,3 +67,13 @@ influx task retry-failed \ --after 2021-01-01T00:00:00Z \ --before 2021-01-01T23:59:59Z ``` + +## Run a task with the InfluxDB API +Use the [`/tasks/TASK_ID/runs` InfluxDB API endpoint](/influxdb/v2.3/api/#operation/PostTasksIDRuns) to manually run a task. + +{{< api-endpoint method="POST" endpoint="http://localhost:8086/api/v2/tasks/TASK_ID/runs" >}} + +### Retry failed task runs +Use the [`/tasks/TASK_ID/runs/RUN_ID/retry` InfluxDB API endpoint](/influxdb/v2.3/api/#operation/PostTasksIDRunsIDRetry) to retry a task run. + +{{< api-endpoint method="POST" endpoint="http://localhost:8086/api/v2/tasks/TASK_ID/runs/RUN_ID/retry" >}} diff --git a/content/influxdb/v2.3/process-data/manage-tasks/task-run-history.md b/content/influxdb/v2.3/process-data/manage-tasks/task-run-history.md index 4bffd2881..a02a6e420 100644 --- a/content/influxdb/v2.3/process-data/manage-tasks/task-run-history.md +++ b/content/influxdb/v2.3/process-data/manage-tasks/task-run-history.md @@ -13,12 +13,12 @@ related: - /influxdb/v2.3/reference/cli/influx/task/retry-failed --- -When an InfluxDB task runs, a "run" record is created in the task's history. +When an InfluxDB task runs, a _run_ record is created in the task's history. Logs associated with each run provide relevant log messages, timestamps, and the exit status of the run attempt. -Use the InfluxDB user interface (UI) or the `influx` command line interface (CLI) -to view task run histories and associated logs. +Use the InfluxDB user interface (UI), the `influx` command line interface (CLI), +or the InfluxDB `/api/v2` API to view task run histories and associated logs. ## View a task's run history in the InfluxDB UI @@ -47,21 +47,26 @@ influx task run list --task-id=0000000000000000 Detailed run logs are not currently available in the `influx` CLI. {{% /note %}} -## Retry failed task runs -Use the [`influx task retry-failed` command](/influxdb/v2.3/reference/cli/influx/task/retry-failed/) -to retry failed task runs. +To retry failed task runs, see how to [run tasks](/influxdb/v2.3/process-data/manage-tasks/run-task/). -```sh -# Retry failed tasks for a specific task -influx task retry-failed \ - --id 0000000000000000 +## View all logs for a task with the InfluxDB API -# Print information about runs that will be retried -influx task retry-failed \ - --dry-run +Use the [`/api/v2/tasks/TASK_ID/logs` InfluxDB API endpoint](/influxdb/v2.3/api/#operation/GetTasksIDLogs) to view the +log events for a task and exclude additional task metadata. -# Retry failed task runs that occurred in a specific time range -influx task retry-failed \ - --after 2021-01-01T00:00:00Z \ - --before 2021-01-01T23:59:59Z -``` +{{< api-endpoint method="GET" endpoint="http://localhost:8086/api/v2/tasks/TASK_ID/logs" >}} + +## View a task's run history with the InfluxDB API + +Use the [`/tasks/TASK_ID/runs` InfluxDB API endpoint](/influxdb/v2.3/api/#operation/GetTasksIDRuns) to view a task's run history. + +{{< api-endpoint method="GET" endpoint="http://localhost:8086/api/v2/tasks/TASK_ID/runs" >}} + +### View task run logs with the InfluxDB API + +To view logs associated with a run, use the [`/api/v2/tasks/TASK_ID/runs/RUN_ID/logs` InfluxDB API +endpoint](/influxdb/v2.3/api/#operation/GetTasksIDRunsIDLogs). + +{{< api-endpoint method="GET" endpoint="http://localhost:8086/api/v2/tasks/TASK_ID/runs/RUN_ID/logs" >}} + +To retry failed task runs, see how to [run tasks](/influxdb/v2.3/process-data/manage-tasks/run-task/). diff --git a/content/influxdb/v2.3/process-data/task-options.md b/content/influxdb/v2.3/process-data/task-options.md index 15b8a307a..7c361cf13 100644 --- a/content/influxdb/v2.3/process-data/task-options.md +++ b/content/influxdb/v2.3/process-data/task-options.md @@ -40,6 +40,7 @@ option task = { } ``` +{{% cloud-only %}} In a `/api/v2/tasks` request body with `scriptID`: ```json @@ -51,6 +52,7 @@ In a `/api/v2/tasks` request body with `scriptID`: ``` Replace `SCRIPT_ID` with the ID of your InfluxDB invokable script. +{{% /cloud-only %}} ## every @@ -58,6 +60,12 @@ The interval at which the task runs. This option also determines when the task f _**Data type:** Duration_ +For example, if you save or schedule a task at 2:30 and run the task every hour (`1h`): + +`option task = {name: "aggregation", every: 1h}` + +The task first executes at 3:00pm, and subsequently every hour after that. + In Flux: ```js @@ -67,6 +75,7 @@ option task = { } ``` +{{% cloud-only %}} In a `/api/v2/tasks` request body with `scriptID`: ```json @@ -77,14 +86,10 @@ In a `/api/v2/tasks` request body with `scriptID`: } ``` -For example, if you save or schedule a task at 2:30 and run the task every hour (`1h`): - -`option task = {name: "aggregation", every: 1h}` - -The task first executes at 3:00pm, and subsequently every hour after that. +{{% /cloud-only %}} {{% note %}} -In the InfluxDB UI, the **Interval** field sets this option. +In the InfluxDB UI, use the **Interval** field to set this option. {{% /note %}} ## cron @@ -104,6 +109,7 @@ option task = { } ``` +{{% cloud-only %}} In a `/api/v2/tasks` request body with `scriptID`: ```json @@ -114,6 +120,8 @@ In a `/api/v2/tasks` request body with `scriptID`: } ``` +{{% /cloud-only %}} + ## offset Delays the execution of the task but preserves the original time range. @@ -133,6 +141,8 @@ option task = { } ``` +{{% cloud-only %}} + In a `/api/v2/tasks` request body with `scriptID`: ```json @@ -142,3 +152,5 @@ In a `/api/v2/tasks` request body with `scriptID`: ... } ``` + +{{% /cloud-only %}} \ No newline at end of file diff --git a/content/influxdb/v2.3/write-data/developer-tools/api.md b/content/influxdb/v2.3/write-data/developer-tools/api.md index 5c79638a2..f99cac80e 100644 --- a/content/influxdb/v2.3/write-data/developer-tools/api.md +++ b/content/influxdb/v2.3/write-data/developer-tools/api.md @@ -2,7 +2,7 @@ title: Write data with the InfluxDB API weight: 206 description: > - Use the `/api/v2/write` endpoint of the InfluxDB API to write data to InfluxDB. + Use the `/api/v2/write` InfluxDB API endpoint to write data to InfluxDB. menu: influxdb_2_3: name: InfluxDB API diff --git a/content/influxdb/v2.4/process-data/_index.md b/content/influxdb/v2.4/process-data/_index.md index 641fe81f2..c68f6da65 100644 --- a/content/influxdb/v2.4/process-data/_index.md +++ b/content/influxdb/v2.4/process-data/_index.md @@ -13,13 +13,13 @@ related: - /resources/videos/influxdb-tasks/ --- -Process and analyze your data with tasks in the InfluxDB **task engine**. Use tasks (scheduled Flux queries) +Process and analyze your data with tasks in the InfluxDB **task engine**. +Use tasks (scheduled Flux queries) to input a data stream and then analyze, modify, and act on the data accordingly. Discover how to create and manage tasks using the InfluxDB user interface (UI) -and the `influx` command line interface (CLI). -Find examples of data downsampling, anomaly detection _(Coming)_, alerting -_(Coming)_, and other common tasks. +the `influx` command line interface (CLI), and the InfluxDB `/api/v2` API. +Find examples of data downsampling and other common tasks. {{% note %}} Tasks replace InfluxDB v1.x continuous queries. diff --git a/content/influxdb/v2.4/process-data/common-tasks/calculate_weekly_mean.md b/content/influxdb/v2.4/process-data/common-tasks/calculate_weekly_mean.md index 9ea5f67c2..2f6d99be8 100644 --- a/content/influxdb/v2.4/process-data/common-tasks/calculate_weekly_mean.md +++ b/content/influxdb/v2.4/process-data/common-tasks/calculate_weekly_mean.md @@ -16,11 +16,12 @@ This example uses [NOAA water sample data](/influxdb/v2.4/reference/sample-data/ This example calculates a temperature weekly mean and stores it in a separate bucket. -The following query: - - Uses [`filter()`](/{{< latest "flux" >}}/stdlib/universe/filter/) to filter the `average_temperature` measurement. - - Uses [`range()`](/{{< latest "flux" >}}/stdlib/universe/range/) to define a time range. - - Uses [`aggregateWindow()`](/{{< latest "flux" >}}/stdlib/universe/aggregatewindow/) to group average temperature by week and compute the mean. - - Sends the weekly mean to a new bucket (`weekly_means`) +The sample query performs the following operations: + +- Uses [`filter()`](/{{< latest "flux" >}}/stdlib/universe/filter/) to select records with the `average_temperature` measurement. +- Uses [`range()`](/{{< latest "flux" >}}/stdlib/universe/range/) to define the start time. +- Uses [`aggregateWindow()`](/{{< latest "flux" >}}/stdlib/universe/aggregatewindow/) to group records by week and compute the mean. +- Sends the weekly mean to a new bucket (`weekly_means`). ```js option task = { @@ -34,6 +35,7 @@ from(bucket: "noaa") |> aggregateWindow(every: 1w, fn: mean) |> to(bucket: "weekly_means") ``` + ### Example results | _start | _stop | _field | _measurement | location | _value | _time | diff --git a/content/influxdb/v2.4/process-data/get-started.md b/content/influxdb/v2.4/process-data/get-started.md index d01002c83..e3d8af1f7 100644 --- a/content/influxdb/v2.4/process-data/get-started.md +++ b/content/influxdb/v2.4/process-data/get-started.md @@ -35,12 +35,12 @@ Their form and order can vary, but they are all essential parts of a task. - [Data processing or transformation](#process-or-transform-your-data) - [A destination](#define-a-destination) -_[Skip to the full example task script](#full-example-task-script)_ +_[Skip to the full example task script](#full-example-flux-task-script)_ ## Define task options -Task options define specific information about the task. -The example below illustrates how task options are defined in your Flux script: +Task options define the schedule, name, and other information about the task. +The following example shows how to set task options in a Flux script: ```js option task = {name: "downsample_5m_precision", every: 1h, offset: 0m} @@ -53,17 +53,42 @@ about each option._ The InfluxDB UI provides a form for defining task options. {{% /note %}} -## Define a data source +{{% cloud-only %}} -1. Use [`from()`](/{{< latest "flux" >}}/stdlib/influxdata/influxdb/from/) - to query data from InfluxDB {{% cloud-only %}}Cloud{{% /cloud-only %}}. - Use - other [Flux input functions](/{{< latest "flux" >}}/function-types/#inputs) - to retrieve data from other sources. -2. Use [`range()`](/{{< latest "flux" >}}/stdlib/universe/range/) to define the time - range to return data from. -3. Use [`filter()`](/{{< latest "flux" >}}/stdlib/universe/filter/) to filter - data based on column values. +### Task options for invokable scripts + +Use the InfluxDB Cloud API to create tasks that reference and run [invokable scripts](influxdb/cloud/api-guide/api-invokable-scripts/). +When you create or update the task, pass task options as properties in the request body--for example: + +```json + { + "name": "30-day-avg-temp", + "description": "IoT Center 30d environment average.", + "every": "1d", + "offset": "0m" + ... + } +``` + +To learn more about creating tasks that run invokable scripts, see how to [create a task that references a script](/influxdb/cloud/process-data/manage-tasks/create-task/#create-a-task-that-references-a-script). + +{{% /cloud-only %}} + +## Retrieve and filter data + +A minimal Flux script uses the following functions to retrieve a specified amount +of data from a data source +and then filter the data based on time or column values: + +1. [`from()`](/{{< latest "flux" >}}/stdlib/influxdata/influxdb/from/): + queries data from InfluxDB {{% cloud-only %}}Cloud{{% /cloud-only %}}. +2. [`range()`](/{{< latest "flux" >}}/stdlib/universe/range/): defines the time + range to return data from. +3. [`filter()`](/{{< latest "flux" >}}/stdlib/universe/filter/): filters + data based on column values. + +The following sample Flux retrieves data from an InfluxDB bucket and then filters by +the `_measurement` and `host` columns: ```js from(bucket: "example-bucket") @@ -71,11 +96,20 @@ from(bucket: "example-bucket") |> filter(fn: (r) => r._measurement == "mem" and r.host == "myHost") ``` +_To retrieve data from other sources, see [Flux input functions](/{{< latest "flux" >}}/function-types/#inputs)._ + {{% note %}} + #### Use task options in your Flux script -Task options are defined in a `task` option record and can be referenced in your Flux script. -In the example above, the time range is defined as `-task.every`. +InfluxDB stores options in a `task` option record that you can reference in your Flux script. +The following sample Flux uses the time range `-task.every`: + +```js +from(bucket: "example-bucket") + |> range(start: -task.every) + |> filter(fn: (r) => r._measurement == "mem" and r.host == "myHost") +``` `task.every` is dot notation that references the `every` property of the `task` option record. `every` is defined as `1h`, therefore `-task.every` equates to `-1h`. @@ -85,23 +119,17 @@ Using task options to define values in your Flux script can make reusing your ta ## Process or transform your data -Tasks automatically process or transform data in some way at regular intervals. -Data processing can include operations such as downsampling data, detecting -anomalies, sending notifications, and more. +Tasks run scripts automatically at regular intervals. +Scripts process or transform data in some way--for example: downsampling, detecting +anomalies, or sending notifications. -{{% note %}} -#### Use offset to account for latent data - -Use the `offset` task option to account for potentially latent data (like data from edge devices). -A task that runs at one hour intervals (`every: 1h`) with an offset of five minutes (`offset: 5m`) -executes 5 minutes after the hour, but queries data from the original one hour interval. -{{% /note %}} - -The task example below downsamples data by calculating the average of set intervals. +Consider a task that runs hourly and downsamples data by calculating the average of set intervals. It uses [`aggregateWindow()`](/{{< latest "flux" >}}/stdlib/universe/aggregatewindow/) -to group points into 5 minute windows and calculate the average of each +to group points into 5-minute (`5m`) windows and calculate the average of each window with [`mean()`](/{{< latest "flux" >}}/stdlib/universe/mean/). +The following sample code shows the Flux script with task options: + ```js option task = {name: "downsample_5m_precision", every: 1h, offset: 0m} @@ -111,8 +139,56 @@ from(bucket: "example-bucket") |> aggregateWindow(every: 5m, fn: mean) ``` +{{% note %}} +#### Use offset to account for latent data + +Use the `offset` task option to account for potentially latent data (like data from edge devices). +A task that runs at one hour intervals (`every: 1h`) with an offset of five minutes (`offset: 5m`) +executes 5 minutes after the hour, but queries data from the original one-hour interval. +{{% /note %}} + _See [Common tasks](/influxdb/v2.4/process-data/common-tasks) for examples of tasks commonly used with InfluxDB._ +{{% cloud-only %}} + +### Process data with invokable scripts + +In InfluxDB Cloud, you can create tasks that run invokable scripts. +You can use invokable scripts to manage and reuse scripts for your organization. +You can use tasks to schedule script runs with options and parameters. + +The following sample `POST /api/v2/scripts` request body defines a new invokable script with the Flux from the previous example: + +```json +{ + "name": "aggregate-intervals", + "description": "Group points into 5 minute windows and calculate the average of each + window.", + "script": "from(bucket: "example-bucket")\ + |> range(start: -task.every)\ + |> filter(fn: (r) => r._measurement == "mem" and r.host == "myHost")\ + |> aggregateWindow(every: 5m, fn: mean)", + "language": "flux" +} +``` + +Note that the script doesn't contain task options. +Once you create the invokable script, you can use `POST /api/v2/tasks` to create a task that runs the script. +The following sample request body defines a task with the script ID and options: + +```json +{ + "every": "1h", + "description": "Downsample host with 5 min precision.", + "name": "downsample_5m_precision", + "scriptID": "09b2136232083000" +} +``` + +To create a script and a task that use parameters, see how to [create a task to run an invokable script](/influxdb/cloud/process-data/manage-tasks/create-task/). + +{{% /cloud-only %}} + ## Define a destination In most cases, you'll want to send and store data after the task has transformed it. @@ -133,12 +209,12 @@ To write data into InfluxDB, `to()` requires the following columns: - `_field` - `_value` -You can also write data to other destinations using -[Flux output functions](/{{< latest "flux" >}}/function-types/#outputs). +_To write data to other destinations, see +[Flux output functions](/{{< latest "flux" >}}/function-types/#outputs)._ -## Full example task script +## Full example Flux task script -Below is a task script that combines all of the components described above: +The following sample Flux combines all the components described in this guide: ```js // Task options @@ -154,6 +230,43 @@ from(bucket: "example-bucket") |> to(bucket: "example-downsampled") ``` +{{% cloud-only %}} + +## Full example task with invokable script + +The following sample code shows a `POST /api/v2/scripts` request body that +combines the components described in this guide: + +```json +{ + "name": "aggregate-intervals-and-export", + "description": "Group points into 5 minute windows and calculate the average of each + window.", + "script": "from(bucket: "example-bucket")\ + |> range(start: -task.every)\ + |> filter(fn: (r) => r._measurement == "mem" and r.host == "myHost")\ + // Data processing\ + |> aggregateWindow(every: 5m, fn: mean)\ + // Data destination\ + |> to(bucket: "example-downsampled")", + "language": "flux" +} +``` + +The following sample code shows a `POST /api/v2/tasks` request body to +schedule the script: + +```json +{ + "every": "1h", + "description": "Downsample host with 5 min precision.", + "name": "downsample_5m_precision", + "scriptID": "SCRIPT_ID" +} +``` + +{{% /cloud-only %}} + To learn more about InfluxDB tasks and how they work, watch the following video: {{< youtube zgCmdtZaH9M >}} diff --git a/content/influxdb/v2.4/process-data/manage-tasks/_index.md b/content/influxdb/v2.4/process-data/manage-tasks/_index.md index d079a83a8..a4a89b621 100644 --- a/content/influxdb/v2.4/process-data/manage-tasks/_index.md +++ b/content/influxdb/v2.4/process-data/manage-tasks/_index.md @@ -4,7 +4,7 @@ seotitle: Manage data processing tasks in InfluxDB list_title: Manage tasks description: > InfluxDB provides options for creating, reading, updating, and deleting tasks - using both the `influx` CLI and the InfluxDB UI. + using the `influx` CLI, the InfluxDB UI, and the InfluxDB API. influxdb/v2.4/tags: [tasks] menu: influxdb_2_4: @@ -13,8 +13,8 @@ menu: weight: 102 --- -InfluxDB provides two options for managing the creation, reading, updating, and deletion (CRUD) of tasks - -through the InfluxDB user interface (UI) or using the `influx` command line interface (CLI). -Both tools can perform all task CRUD operations. +InfluxDB provides multiple options for creating, reading, updating, and deleting (CRUD) tasks. +The following articles walk through managing tasks with the +InfluxDB user interface (UI), the `influx` command line interface (CLI), and the InfluxDB API. {{< children >}} diff --git a/content/influxdb/v2.4/process-data/manage-tasks/create-task.md b/content/influxdb/v2.4/process-data/manage-tasks/create-task.md index 1413021c8..204093112 100644 --- a/content/influxdb/v2.4/process-data/manage-tasks/create-task.md +++ b/content/influxdb/v2.4/process-data/manage-tasks/create-task.md @@ -12,16 +12,16 @@ related: - /influxdb/v2.4/reference/cli/influx/task/create --- -InfluxDB provides multiple ways to create tasks both in the InfluxDB user interface (UI) -and the `influx` command line interface (CLI). +Create tasks with the InfluxDB user interface (UI), `influx` command line interface (CLI), or `/api/v2` API. -_Before creating a task, review the [basics criteria for writing a task](/influxdb/v2.4/process-data/get-started)._ +_Before creating a task, review the [basics for writing a task](/influxdb/v2.4/process-data/get-started)._ - [InfluxDB UI](#create-a-task-in-the-influxdb-ui) - [`influx` CLI](#create-a-task-using-the-influx-cli) - [InfluxDB API](#create-a-task-using-the-influxdb-api) ## Create a task in the InfluxDB UI + The InfluxDB UI provides multiple ways to create a task: - [Create a task from the Data Explorer](#create-a-task-from-the-data-explorer) @@ -31,6 +31,7 @@ The InfluxDB UI provides multiple ways to create a task: - [Clone a task](#clone-a-task) ### Create a task from the Data Explorer + 1. In the navigation menu on the left, select **Data Explorer**. {{< nav-icon "data-explorer" >}} @@ -41,8 +42,8 @@ The InfluxDB UI provides multiple ways to create a task: for detailed information about each option. 5. Click **{{< caps >}}Save as Task{{< /caps >}}**. - ### Create a task in the Task UI + 1. In the navigation menu on the left, select **Tasks**. {{< nav-icon "tasks" >}} @@ -53,7 +54,9 @@ The InfluxDB UI provides multiple ways to create a task: 4. In the right panel, enter your task script. {{% note %}} + ##### Leave out the option tasks assignment + When creating a _new_ task in the InfluxDB Task UI, leave the code editor empty. When you save the task, the Task UI uses the [task options](/influxdb/v2.4/process-data/task-options/) you specify in the **Task options** form to populate `option task = {task_options}` for you. @@ -63,6 +66,7 @@ When you edit the saved task, you'll see the injected `option task = {task_optio 7. Click **Save** in the upper right. ### Import a task + 1. In the navigation menu on the left, select **Tasks**. {{< nav-icon "tasks" >}} @@ -74,6 +78,7 @@ When you edit the saved task, you'll see the injected `option task = {task_optio 5. Click **{{< caps >}}Save{{< /caps >}}** in the upper right. ### Create a task from a template + 1. In the navigation menu on the left, select **Settings** > **Templates**. {{< nav-icon "Settings" >}} @@ -81,20 +86,22 @@ When you edit the saved task, you'll see the injected `option task = {task_optio 2. Find the template you want to use and click its **Resources** list to expand the list of resources. 3. In the **Resources** list, click the task you want to use. - ### Clone a task + 1. In the navigation menu on the left, select **Tasks**. {{< nav-icon "tasks" >}} 2. Find the task you would like to clone and click the **{{< icon "settings" >}}** icon located far right of the task name. -4. Click **Clone**. +3. Click **Clone**. ## Create a task using the influx CLI + Use the `influx task create` command to create a new task. It accepts either a file path or raw Flux. -###### Create a task using a file +### Create a task using a file + ```sh # Syntax influx task create --org -f @@ -103,7 +110,8 @@ influx task create --org -f influx task create --org my-org -f /tasks/cq-mean-1h.flux ``` -###### Create a task using raw Flux +### Create a task using raw Flux + ```sh influx task create --org my-org - # to open stdin pipe @@ -119,29 +127,177 @@ option task = { ## Create a task using the InfluxDB API -Send a request using the **POST** method to the `/api/v2/tasks` InfluxDB API endpoint. -Provide the following in your API request: +{{% oss-only %}} +Use the [`/api/v2/tasks` InfluxDB API endpoint](/influxdb/v2.4/api/#operation/PostTasks) to create a task. +{{< api-endpoint method="POST" endpoint="http://localhost:8086/api/v2/tasks/" >}} + +Provide the following in your API request: ##### Request headers + - **Content-Type**: application/json - **Authorization**: Token *`INFLUX_API_TOKEN`* ##### Request body + JSON object with the following fields: -- **flux** : raw Flux task string +- **flux**: raw Flux task string that contains a [`task` option](/flux/v0.x/spec/options/) and a query. - **orgID**: your [InfluxDB organization ID](/influxdb/v2.4/organizations/view-orgs/#view-your-organization-id) - **status**: task status ("active" or "inactive") - **description**: task description ```sh -curl --request POST 'https://us-west-2-1.aws.cloud2.influxdata.com/api/v2/tasks' \ +curl --request POST 'http://localhost:8086/api/v2/tasks' \ --header 'Content-Type: application/json' \ --header 'Authorization: Token INFLUX_API_TOKEN' \ --data-raw '{ - "flux": "option task = {name: \"CPU Total 1 Hour New\", every: 1h}\n\nfrom(bucket: \"telegraf\")\n\t|> range(start: -1h)\n\t|> filter(fn: (r) =>\n\t\t(r._measurement == \"cpu\"))\n\t|> filter(fn: (r) =>\n\t\t(r._field == \"usage_system\"))\n\t|> filter(fn: (r) =>\n\t\t(r.cpu == \"cpu-total\"))\n\t|> aggregateWindow(every: 1h, fn: max)\n\t|> to(bucket: \"cpu_usage_user_total_1h\", org: \"\")", + "flux": "option task = {name: \"CPU Total 1 Hour New\", every: 1h}\n\nfrom(bucket: \"telegraf\")\n\t|> range(start: -1h)\n\t|> filter(fn: (r) =>\n\t\t(r._measurement == \"cpu\"))\n\t|> filter(fn: (r) =>\n\t\t(r._field == \"usage_system\"))\n\t|> filter(fn: (r) =>\n\t\t(r.cpu == \"cpu-total\"))\n\t|> aggregateWindow(every: 1h, fn: max)\n\t|> to(bucket: \"cpu_usage_user_total_1h\", org: \"INFLUX_ORG\")", "orgID": "INFLUX_ORG_ID", "status": "active", "description": "This task downsamples CPU data every hour" }' ``` + +{{% /oss-only %}} + +{{% cloud-only %}} + +An InfluxDB Cloud task can run either an [invokable script](/influxdb/cloud/api-guide/api-invokable-scripts/) or raw Flux stored in the task. + +- [Create a task that references a script](#create-a-task-that-references-a-script) +- [Create a task that contains a Flux script](#create-a-task-that-contains-a-flux-script) + +### Create a task that references a script + +With InfluxDB Cloud invokable scripts, you can manage, reuse, and invoke scripts as API endpoints. +You can use tasks to pass script parameters and schedule runs. + +Use the [`/api/v2/tasks` InfluxDB API endpoint](/influxdb/cloud/api/#operation/PostTasks) to create a task +that references a script ID. + +{{< api-endpoint method="POST" endpoint="http://localhost:8086/api/v2/tasks/" >}} + +Provide the following in your API request: + +#### Request headers + +- **Content-Type**: application/json +- **Authorization**: Token *`INFLUX_API_TOKEN`* + +#### Request body + +JSON object with the following fields: + +- **cron** or **every**: task schedule +- **name**: task name +- **scriptID**: [invokable script](/influxdb/cloud/api-guide/api-invokable-scripts/) ID + +```sh +curl --request POST 'https://cloud2.influxdata.com/api/v2/tasks' \ + --header 'Content-Type: application/json' \ + --header 'Authorization: Token INFLUX_API_TOKEN' \ + "cron": "0 * * * *", + "name": "downsample cpu", + "scriptID": "085a2960eaa20000", + "description": "This task downsamples CPU data every hour" +}' +``` + +To create a task that passes parameters when invoking the script, pass the _`scriptParameters`_ +property in the request body. +The following sample code creates a script with parameters, and then creates a +task to run the new script daily: + +```sh +SCRIPT_ID=$( +curl https://cloud2.influxdata.com/api/v2/scripts \ + --header "Authorization: Token INFLUX_API_TOKEN" \ + --header 'Accept: application/json' \ + --header 'Content-Type: application/json' \ + --data-binary @- << EOF | jq -r '.id' + { + "name": "filter-and-group19", + "description": "Returns filtered and grouped points from a bucket.", + "script": "from(bucket: params.bucket)\ + |> range(start: duration(v: params.rangeStart))\ + |> filter(fn: (r) => r._field == params.filterField)\ + |> group(columns: [params.groupColumn])", + "language": "flux" + } +EOF +) + +echo $SCRIPT_ID + +curl https://cloud2.influxdata.com/api/v2/tasks \ +--header "Content-type: application/json" \ +--header "Authorization: Token INFLUX_API_TOKEN" \ +--data @- << EOF + { + "name": "30-day-avg-temp", + "description": "IoT Center 30d temperature average.", + "every": "1d", + "scriptID": "${SCRIPT_ID}", + "scriptParameters": + { + "rangeStart": "-30d", + "bucket": "air_sensor", + "filterField": "temperature", + "groupColumn": "_time" + } + } +EOF +``` + +Replace **`INFLUX_API_TOKEN`** with your InfluxDB API token. + +### Create a task that contains a Flux script + +Use the [`/api/v2/tasks` InfluxDB API endpoint](/influxdb/cloud/api/#operation/PostTasks) to create a task that contains a Flux script with task options. + +{{< api-endpoint method="POST" endpoint="https://cloud2.influxdata.com/api/v2/tasks/" >}} + +Provide the following in your API request: + +#### Request headers + +- **Content-Type**: application/json +- **Authorization**: Token **`INFLUX_API_TOKEN`** + +#### Request body + +JSON object with the following fields: + +- **flux**: raw Flux task string that contains [`options`](/flux/v0.x/spec/options/) and the query. +- **status**: task status ("active" or "inactive") +- **description**: task description + +```sh +curl --request POST 'https://cloud2.influxdata.com/api/v2/tasks' \ + --header 'Content-Type: application/json' \ + --header 'Authorization: Token INFLUX_API_TOKEN' \ + --data-binary @- << EOF + { + "flux": "option task = {name: \"CPU Total 1 Hour New\", every: 1h}\ + from(bucket: \"telegraf\") + |> range(start: -1h) + |> filter(fn: (r) => (r._measurement == \"cpu\")) + |> filter(fn: (r) =>\n\t\t(r._field == \"usage_system\")) + |> filter(fn: (r) => (r.cpu == \"cpu-total\")) + |> aggregateWindow(every: 1h, fn: max) + |> to(bucket: \"cpu_usage_user_total_1h\", org: \"INFLUX_ORG\")", + "orgID": "INFLUX_ORG_ID", + "status": "active", + "description": "This task downsamples CPU data every hour" + } +EOF +``` + +Replace the following: + +- **`INFLUX_API_TOKEN`**: your InfluxDB [API token](/influxdb/cloud/security/tokens/view-tokens/) +- **`INFLUX_ORG`**: your InfluxDB organization name +- **`INFLUX_ORG_ID`**: your InfluxDB organization ID + +{{% /cloud-only %}} diff --git a/content/influxdb/v2.4/process-data/manage-tasks/delete-task.md b/content/influxdb/v2.4/process-data/manage-tasks/delete-task.md index 86aa12b8c..44f674525 100644 --- a/content/influxdb/v2.4/process-data/manage-tasks/delete-task.md +++ b/content/influxdb/v2.4/process-data/manage-tasks/delete-task.md @@ -24,8 +24,6 @@ related: ## Delete a task with the influx CLI Use the `influx task delete` command to delete a task. -_This command requires a task ID, which is available in the output of `influx task list`._ - ```sh # Syntax influx task delete -i @@ -33,3 +31,18 @@ influx task delete -i # Example influx task delete -i 0343698431c35000 ``` + +_To find the task ID, see [how to view tasks](/influxdb/v2.4/process-data/manage-tasks/view-tasks/)_ + +## Delete a task using the InfluxDB API + +Use the [`/tasks/TASK_ID` InfluxDB API endpoint](/influxdb/v2.4/api/#operation/DeleteTasksID) to delete a task and all associated records (task runs, logs, and labels). + +{{< api-endpoint method="DELETE" endpoint="http://localhost:8086/api/v2/tasks/TASK_ID" >}} + +_To find the task ID, see [how to view tasks](/influxdb/v2.4/process-data/manage-tasks/view-tasks/)_ + +Once the task is deleted, InfluxDB cancels all scheduled runs of the task. + +If you want to disable a task instead of delete it, see how to +[update the task status](/influxdb/v2.4/process-data/manage-tasks/update-task/) to `inactive`. diff --git a/content/influxdb/v2.4/process-data/manage-tasks/run-task.md b/content/influxdb/v2.4/process-data/manage-tasks/run-task.md index 8c99225ba..5136d74b9 100644 --- a/content/influxdb/v2.4/process-data/manage-tasks/run-task.md +++ b/content/influxdb/v2.4/process-data/manage-tasks/run-task.md @@ -12,11 +12,14 @@ related: - /influxdb/v2.4/reference/cli/influx/task/run - /influxdb/v2.4/reference/cli/influx/task/run/retry - /influxdb/v2.4/reference/cli/influx/task/retry-failed + - /influxdb/v2.4/api/#operation/PostTasksIDRuns + - /influxdb/v2.4/api/#operation/PostTasksIDRunsIDRetry --- InfluxDB data processing tasks generally run in defined intervals or at a specific time, -however, you can manually run a task from the InfluxDB user interface (UI) or the -`influx` command line interface (CLI). +however, you can manually run a task from the InfluxDB user interface (UI), +the `influx` command line interface (CLI), +or the InfluxDB `/api/v2` API. ## Run a task from the InfluxDB UI 1. In the navigation menu on the left, select **Tasks**. @@ -64,3 +67,15 @@ influx task retry-failed \ --after 2021-01-01T00:00:00Z \ --before 2021-01-01T23:59:59Z ``` + +## Run a task with the InfluxDB API +Use the [`/tasks/TASK_ID/runs` +InfluxDB API endpoint](/influxdb/v2.4/api/#operation/PostTasksIDRuns) to manually start a task run. + +{{< api-endpoint method="POST" endpoint="http://localhost:8086/api/v2/tasks/TASK_ID/runs" >}} + +### Retry failed task runs +Use the [`/tasks/TASK_ID/runs/RUN_ID/retry` +InfluxDB API endpoint](/influxdb/v2.4/api/#operation/PostTasksIDRunsIDRetry) to retry a task run. + +{{< api-endpoint method="POST" endpoint="http://localhost:8086/api/v2/tasks/TASK_ID/runs/RUN_ID/retry" >}} diff --git a/content/influxdb/v2.4/process-data/manage-tasks/task-run-history.md b/content/influxdb/v2.4/process-data/manage-tasks/task-run-history.md index b7b92e0bd..796249785 100644 --- a/content/influxdb/v2.4/process-data/manage-tasks/task-run-history.md +++ b/content/influxdb/v2.4/process-data/manage-tasks/task-run-history.md @@ -13,12 +13,12 @@ related: - /influxdb/v2.4/reference/cli/influx/task/retry-failed --- -When an InfluxDB task runs, a "run" record is created in the task's history. +When an InfluxDB task runs, a _run_ record is created in the task's history. Logs associated with each run provide relevant log messages, timestamps, and the exit status of the run attempt. -Use the InfluxDB user interface (UI) or the `influx` command line interface (CLI) -to view task run histories and associated logs. +Use the InfluxDB user interface (UI), the `influx` command line interface (CLI), +or the InfluxDB `/api/v2` API to view task run histories and associated logs. ## View a task's run history in the InfluxDB UI @@ -30,9 +30,11 @@ to view task run histories and associated logs. 3. Select **View Task Runs**. ### View task run logs + To view logs associated with a run, click **View Logs** next to the run in the task's run history. ## View a task's run history with the influx CLI + Use the `influx task run list` command to view a task's run history. ```sh @@ -47,21 +49,28 @@ influx task run list --task-id=0000000000000000 Detailed run logs are not currently available in the `influx` CLI. {{% /note %}} -## Retry failed task runs -Use the [`influx task retry-failed` command](/influxdb/v2.4/reference/cli/influx/task/retry-failed/) -to retry failed task runs. +To retry failed task runs, see how to [run tasks](/influxdb/v2.4/process-data/manage-tasks/run-task/). -```sh -# Retry failed tasks for a specific task -influx task retry-failed \ - --id 0000000000000000 +## View logs for a task with the InfluxDB API -# Print information about runs that will be retried -influx task retry-failed \ - --dry-run +Use the [`/api/v2/tasks/TASK_ID/logs` +InfluxDB API endpoint](/influxdb/v2.4/api/#operation/GetTasksIDLogs) to view the log events for a task and exclude additional task metadata. -# Retry failed task runs that occurred in a specific time range -influx task retry-failed \ - --after 2021-01-01T00:00:00Z \ - --before 2021-01-01T23:59:59Z -``` +{{< api-endpoint method="GET" endpoint="http://localhost:8086/api/v2/tasks/TASK_ID/logs" >}} + +## View a task's run history with the InfluxDB API + +Use the [`/tasks/TASK_ID/runs` +InfluxDB API endpoint](/influxdb/v2.4/api/#operation/GetTasksIDRuns) to view a task's run history. + +{{< api-endpoint method="GET" endpoint="http://localhost:8086/api/v2/tasks/{taskID}/runs" >}} + +### View task run logs with the InfluxDB API + +To view logs associated with a run, use the +[`/api/v2/tasks/TASK_ID/runs/RUN_ID/logs` InfluxDB API +endpoint](/influxdb/v2.4/api/#operation/GetTasksIDRunsIDLogs). + +{{< api-endpoint method="GET" endpoint="http://localhost:8086/api/v2/tasks/TASK_ID/runs/RUN_ID/logs" >}} + +To retry failed task runs, see how to [run tasks](/influxdb/v2.4/process-data/manage-tasks/run-task/). diff --git a/content/influxdb/v2.4/process-data/manage-tasks/update-task.md b/content/influxdb/v2.4/process-data/manage-tasks/update-task.md index b97244b04..9ac38baa6 100644 --- a/content/influxdb/v2.4/process-data/manage-tasks/update-task.md +++ b/content/influxdb/v2.4/process-data/manage-tasks/update-task.md @@ -72,3 +72,16 @@ influx task update -i --status < active | inactive > # Example influx task update -i 0343698431c35000 --status inactive ``` + +## Update a task with the InfluxDB API +Use the [`/tasks/TASK_ID` +InfluxDB API endpoint](/influxdb/v2.4/api/#operation/PatchTasksID) to update properties of a task. + +{{< api-endpoint method="PATCH" endpoint="http://localhost:8086/api/v2/tasks/TASK_ID" >}} + +In your request, pass the task ID and an object that contains the updated key-value pairs. +To activate or inactivate a task, set the `status` property. +`"status": "inactive"` cancels scheduled runs and prevents manual runs of the task. +_To find the task ID, see [how to view tasks](/influxdb/v2.4/process-data/manage-tasks/view-tasks/)._ + +Once InfluxDB applies the update, it cancels all previously scheduled runs of the task. diff --git a/content/influxdb/v2.4/process-data/manage-tasks/view-tasks.md b/content/influxdb/v2.4/process-data/manage-tasks/view-tasks.md index d3fdaad4c..357cae58c 100644 --- a/content/influxdb/v2.4/process-data/manage-tasks/view-tasks.md +++ b/content/influxdb/v2.4/process-data/manage-tasks/view-tasks.md @@ -25,7 +25,7 @@ Click the **Tasks** icon in the left navigation to view the lists of tasks. 3. Click the heading of any column to sort by that field. ## View tasks with the influx CLI -Use the `influx task list` command to return a list of created tasks. +Use the `influx task list` command to return a list of tasks. ```sh influx task list @@ -36,3 +36,9 @@ Other filtering options such as filtering by organization or user, or limiting the number of tasks returned, are available. See the [`influx task list` documentation](/influxdb/v2.4/reference/cli/influx/task/list) for information about other available flags. + +## View tasks with the InfluxDB API +Use the [`/tasks` InfluxDB API endpoint](/influxdb/v2.4/api/#operation/GetTasks) +to return a list of tasks. + +{{< api-endpoint method="GET" endpoint="http://localhost:8086/api/v2/tasks" >}} \ No newline at end of file diff --git a/content/influxdb/v2.4/process-data/task-options.md b/content/influxdb/v2.4/process-data/task-options.md index 235556a6d..45612d063 100644 --- a/content/influxdb/v2.4/process-data/task-options.md +++ b/content/influxdb/v2.4/process-data/task-options.md @@ -13,7 +13,7 @@ influxdb/v2.4/tags: [tasks, flux] --- Task options define specific information about a task. -They are set in a Flux script or in the InfluxDB user interface (UI). +They are set in a Flux script {{% cloud-only %}}, in the InfluxDB API, {{% /cloud-only %}} or in the InfluxDB user interface (UI). The following task options are available: - [name](#name) @@ -26,10 +26,13 @@ The following task options are available: {{% /note %}} ## name + The name of the task. _**Required**_. _**Data type:** String_ +In Flux: + ```js option task = { name: "taskName", @@ -37,12 +40,34 @@ option task = { } ``` +{{% cloud-only %}} +In a `/api/v2/tasks` request body with `scriptID`: + +```json +{ + "scriptID": "SCRIPT_ID", + "name": "TASK_NAME" + ... +} +``` + +Replace `SCRIPT_ID` with the ID of your InfluxDB invokable script. +{{% /cloud-only %}} + ## every The interval at which the task runs. This option also determines when the task first starts to run, depending on the specified time (in [duration literal](/{{< latest "flux" >}}/spec/lexical-elements/#duration-literals)). _**Data type:** Duration_ +For example, if you save or schedule a task at 2:30 and run the task every hour (`1h`): + +`option task = {name: "aggregation", every: 1h}` + +The task first executes at 3:00pm, and subsequently every hour after that. + +In Flux: + ```js option task = { // ... @@ -50,23 +75,33 @@ option task = { } ``` -For example, if you save or schedule a task at 2:30 and run the task every hour (`1h`): +{{% cloud-only %}} +In a `/api/v2/tasks` request body with `scriptID`: -`option task = {name: "aggregation", every: 1h}` +```json +{ + "scriptID": "SCRIPT_ID", + "every": "1h" + ... +} +``` -The task first executes at 3:00pm, and subsequently every hour after that. +{{% /cloud-only %}} {{% note %}} -In the InfluxDB UI, the **Interval** field sets this option. +In the InfluxDB UI, use the **Interval** field to set this option. {{% /note %}} ## cron + The [cron expression](https://en.wikipedia.org/wiki/Cron#Overview) that defines the schedule on which the task runs. Cron scheduling is based on system time. _**Data type:** String_ +In Flux: + ```js option task = { // ... @@ -74,6 +109,19 @@ option task = { } ``` +{{% cloud-only %}} +In a `/api/v2/tasks` request body with `scriptID`: + +```json +{ + "scriptID": "SCRIPT_ID", + "cron": "0 * * * *", + ... +} +``` + +{{% /cloud-only %}} + ## offset Delays the execution of the task but preserves the original time range. @@ -84,9 +132,25 @@ A common use case is offsetting execution to account for data that may arrive la _**Data type:** Duration_ +In Flux: + ```js option task = { // ... offset: 10m, } ``` + +{{% cloud-only %}} + +In a `/api/v2/tasks` request body with `scriptID`: + +```json +{ + "scriptID": "SCRIPT_ID", + "offset": "10m", + ... +} +``` + +{{% /cloud-only %}} \ No newline at end of file diff --git a/content/influxdb/v2.4/write-data/developer-tools/api.md b/content/influxdb/v2.4/write-data/developer-tools/api.md index 4c21f38ba..41aeca3b9 100644 --- a/content/influxdb/v2.4/write-data/developer-tools/api.md +++ b/content/influxdb/v2.4/write-data/developer-tools/api.md @@ -2,7 +2,7 @@ title: Write data with the InfluxDB API weight: 206 description: > - Use the `/api/v2/write` endpoint of the InfluxDB API to write data to InfluxDB. + Use the `/api/v2/write` InfluxDB API endpoint to write data to InfluxDB. menu: influxdb_2_4: name: InfluxDB API