Influxdata
/
docs-v2
mirror of https://github.com/influxdata/docs-v2.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Fix/4449 missing task content (#4453) 

* fix: Clarify the example (Part of #4450).

* fix: update process-data with API. Don't forecast _coming_ examples.

* fix: v2.4 tasks get-started (#4449).

* fix: v2.4 tasks task-options (#4449).

* fix(tasks): port v2.3 and cloud-only task content to v2.4.

- Fixes and Closes #4449.
- Add new content for tasks API.

* Update content/influxdb/v2.3/process-data/manage-tasks/run-task.md

Co-authored-by: kelseiv <47797004+kelseiv@users.noreply.github.com>

* Update content/influxdb/v2.3/process-data/manage-tasks/task-run-history.md

* Update content/influxdb/v2.4/process-data/get-started.md

Co-authored-by: kelseiv <47797004+kelseiv@users.noreply.github.com>

* Update content/influxdb/v2.4/process-data/manage-tasks/create-task.md

Co-authored-by: kelseiv <47797004+kelseiv@users.noreply.github.com>

* Update content/influxdb/v2.3/process-data/manage-tasks/task-run-history.md

Co-authored-by: kelseiv <47797004+kelseiv@users.noreply.github.com>

* Update content/influxdb/v2.4/process-data/manage-tasks/create-task.md

Co-authored-by: kelseiv <47797004+kelseiv@users.noreply.github.com>

* Update content/influxdb/v2.4/process-data/manage-tasks/create-task.md

Co-authored-by: kelseiv <47797004+kelseiv@users.noreply.github.com>

* Update content/influxdb/v2.4/process-data/manage-tasks/create-task.md

Co-authored-by: kelseiv <47797004+kelseiv@users.noreply.github.com>

* Update content/influxdb/v2.4/process-data/manage-tasks/create-task.md

Co-authored-by: kelseiv <47797004+kelseiv@users.noreply.github.com>

Co-authored-by: kelseiv <47797004+kelseiv@users.noreply.github.com>
pull/3902/head^2
Jason Stirnaman 2022-09-13 09:19:52 -05:00 committed by GitHub
parent 64a618739b
commit f8197e1180
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
20 changed files with 570 additions and 126 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

8
content/influxdb/v2.3/process-data/_index.md
View File

@ -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.

12
content/influxdb/v2.3/process-data/common-tasks/calculate_weekly_mean.md
View File

@ -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 |

10
content/influxdb/v2.3/process-data/get-started.md
View File

@ -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 %}}

17
content/influxdb/v2.3/process-data/manage-tasks/delete-task.md
View File

@ -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 <task-id>
@ -33,3 +31,18 @@ influx task delete -i <task-id>
# 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`.

17
content/influxdb/v2.3/process-data/manage-tasks/run-task.md
View File

@ -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" >}}

41
content/influxdb/v2.3/process-data/manage-tasks/task-run-history.md
View File

@ -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/).

24
content/influxdb/v2.3/process-data/task-options.md
View File

@ -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 %}}

2
content/influxdb/v2.3/write-data/developer-tools/api.md
View File

@ -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

8
content/influxdb/v2.4/process-data/_index.md
View File

@ -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.

12
content/influxdb/v2.4/process-data/common-tasks/calculate_weekly_mean.md
View File

@ -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 |

177
content/influxdb/v2.4/process-data/get-started.md
View File

@ -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 >}}

8
content/influxdb/v2.4/process-data/manage-tasks/_index.md
View File

@ -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 >}}

182
content/influxdb/v2.4/process-data/manage-tasks/create-task.md
View File

@ -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 <org-name> -f </path/to/task-script>
@ -103,7 +110,8 @@ influx task create --org <org-name> -f </path/to/task-script>
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 - # <return> 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: \"<MYORG>\")",
"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 %}}

17
content/influxdb/v2.4/process-data/manage-tasks/delete-task.md
View File

@ -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 <task-id>
@ -33,3 +31,18 @@ influx task delete -i <task-id>
# 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`.

19
content/influxdb/v2.4/process-data/manage-tasks/run-task.md
View File

@ -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" >}}

45
content/influxdb/v2.4/process-data/manage-tasks/task-run-history.md
View File

@ -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/).

13
content/influxdb/v2.4/process-data/manage-tasks/update-task.md
View File

@ -72,3 +72,16 @@ influx task update -i <task-id> --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.

8
content/influxdb/v2.4/process-data/manage-tasks/view-tasks.md
View File

@ -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" >}}

74
content/influxdb/v2.4/process-data/task-options.md
View File

@ -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 %}}

2
content/influxdb/v2.4/write-data/developer-tools/api.md
View File

@ -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