refactor: common task properties:

src/cloud.yml

@@ -41,7 +41,7 @@ paths:
     $ref: './cloud/paths/dashboards.yml'
   /tasks:
     $ref: './cloud/paths/tasks.yml'
-  "/tasks/{taskID}":
+  /tasks/{taskID}:
     $ref: "./cloud/paths/tasks_taskID.yml"
 components:
   parameters:
@@ -82,6 +82,10 @@ components:
       $ref: "./cloud/schemas/Task.yml"
     TaskCreateRequest:
       $ref: "./cloud/schemas/TaskCreateRequest.yml"
+    TaskScriptID:
+      $ref: "./cloud/schemas/TaskProperties.yml#/scriptID"
+    TaskScriptParameters:
+      $ref: "./cloud/schemas/TaskProperties.yml#/scriptParameters"
     TaskUpdateRequest:
       $ref: "./cloud/schemas/TaskUpdateRequest.yml"
   responses:
@@ -96,7 +100,7 @@ components:
     TaskWithFluxRequest:
       $ref: "./common/requestBody/examples/TaskRequestExamples.yml#/TaskWithFluxRequest"
     TaskWithScriptRequest:
-      $ref: "./common/requestBody/examples/TaskRequestExamples.yml#/TaskWithScriptRequest"
+      $ref: "./cloud/requestBody/examples/TaskRequestExamples.yml#/TaskWithScriptRequest"
   securitySchemes:
     TokenAuthentication:
       type: apiKey

src/cloud/paths/tasks.yml

@@ -3,19 +3,23 @@ get:
   tags:
     - Data I/O endpoints
     - Tasks
-  summary: List all tasks
+  summary: List tasks
   description: |
-    Retrieves a list of [tasks]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task).
+    Lists [tasks]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task).
 
     To limit which tasks are returned, pass query parameters in your request.
     If no query parameters are passed, InfluxDB returns all tasks up to the default `limit`.
+
+    #### Related guide
+
+    - [Process data with InfluxDB tasks]({{% INFLUXDB_DOCS_URL %}}/process-data/)
   parameters:
     - $ref: "../../common/parameters/TraceSpan.yml"
     - in: query
       name: name
       description: |
-        A [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) name.
-        Only returns tasks with the specified name.
+        A task name.
+        Only returns [tasks]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) with the specified name.
         Different tasks may have the same name.
       schema:
         type: string
@@ -24,29 +28,29 @@ get:
       schema:
         type: string
       description: |
-        A [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) ID.
-        Only returns tasks created after the specified task.
+        A task ID.
+        Only returns [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) created after the specified task.
     - in: query
       name: user
       schema:
         type: string
       description: |
-        A [user]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#user) ID.
-        Only returns tasks owned by the specified user.
+        A user ID.
+        Only returns [tasks]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) owned by the specified [user]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#user).
     - in: query
       name: org
       schema:
         type: string
       description: |
-        An [organization]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#organization) name.
-        Only returns tasks owned by the specified organization.
+        An organization name.
+        Only returns [tasks]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) owned by the specified [organization]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#organization).
     - in: query
       name: orgID
       schema:
         type: string
       description: |
-        An [organization]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#organization) ID.
-        Only returns tasks owned by the specified organization.
+        An organization ID.
+        Only returns tasks owned by the specified [organization]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#organization).
     - in: query
       name: status
       schema:
@@ -55,8 +59,8 @@ get:
           - active
           - inactive
       description: |
-        A [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) status.
-        Only returns tasks that have the specified status (`active` or `inactive`).
+        A task status.
+        Only returns [tasks]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) that have the specified status.
     - in: query
       name: limit
       schema:
@@ -89,8 +93,11 @@ get:
     - in: query
       name: sortBy
       description: |
-        The sort field. Only `name` is supported.
-        Specifies the field used to sort records in the list.
+        The sort field.
+        Specifies the task property used to sort records in the list.
+        Default is `name`.
+
+        The parameter has one supported value: `name`.
       required: false
       schema:
         type: string
@@ -99,11 +106,13 @@ get:
     - in: query
       name: type
       description: |
-        A [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) type (`basic` or `system`).
+        A task type.
+        Specifies the level of detail for [tasks]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) in the response.
         Default is `system`.
-        Specifies the level of detail for tasks in the response.
+
         The default (`system`) response contains all the metadata properties for tasks.
-        To reduce the response size, pass `basic` to omit some task properties (`flux`, `createdAt`, `updatedAt`).
+        To reduce the response size, set the `type` parameter to `basic` (`type=basic`)
+        to omit some task properties (`flux`, `createdAt`, `updatedAt`).
       required: false
       schema:
         default: ""
@@ -114,8 +123,8 @@ get:
     - in: query
       name: scriptID
       description: |
-        A [script](#tag/Invokable-Scripts) ID.
-        Only returns tasks that use the specified invokable script.
+        A script ID.
+        Only returns tasks that use the specified [invokable script](#tag/Invokable-Scripts).
       schema:
         type: string
   responses:
@@ -151,52 +160,7 @@ post:
   description: |
     Creates a [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) and returns the task.
 
-    Use this endpoint to create a scheduled task that runs a Flux script.
-
-    #### InfluxDB Cloud
-
-    - You can use either `flux` or `scriptID` to provide the task script.
-
-      - `flux`: a string of "raw" Flux that contains task options and the script--for example:
-
-        ```json
-        {
-          "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\")",
-          "status": "active",
-          "description": "This task downsamples CPU data every hour"
-        }
-        ```
-
-      - `scriptID`: the ID of an [invokable script](#tag/Invokable-Scripts)
-        for the task to run.
-        To pass task options when using `scriptID`, pass the options as
-        properties in the request body--for example:
-
-        ```json
-        {
-          "name": "CPU Total 1 Hour New",
-          "description": "This task downsamples CPU data every hour",
-          "every": "1h",
-          "scriptID": "SCRIPT_ID",
-          "scriptParameters":
-            {
-              "rangeStart": "-1h",
-              "bucket": "telegraf",
-              "filterField": "cpu-total"
-            }
-          }
-        ```
-
-    #### Limitations:
-
-    - You can't use `flux` and `scriptID` for the same task.
+    Use this endpoint to create a scheduled task that runs a script.
 
     #### Related guides
 
@@ -207,15 +171,41 @@ post:
   parameters:
     - $ref: "../../common/parameters/TraceSpan.yml"
   requestBody:
-    description: The task to create
+    description: |
+      In the request body, provide the task.
+
+      Set one of the following properties to provide the script that the task runs:
+        - `flux`
+        - `scriptID`
+
+      If you set the `scriptID` property, you can set the following properties to configure the task:
+        - `cron`
+        - `every`
+        - `offset`
+        - `scriptParameters`
+
+      If you set the `flux` property, you must provide the `task` configuration option
+      in the Flux script.
+
+      See [task configuration options]({{% INFLUXDB_DOCS_URL %}}/process-data/task-options/)
+      for detail and examples.
+
+      #### Limitations:
+
+      - You can't use `flux` and `scriptID` in the same task.
     required: true
     content:
       application/json:
         schema:
           $ref: "../schemas/TaskCreateRequest.yml"
+        examples:
+          TaskWithFlux:
+            $ref: "../../common/requestBody/examples/TaskRequestExamples.yml#/TaskWithFluxRequest"
+          TaskWithScriptID:
+            $ref: "../requestBody/examples/TaskRequestExamples.yml#/TaskWithScriptRequest"
   responses:
     "201":
-      description: Success. The response body contains a `tasks` list with the new task.
+      description: Success. The response body contains a `tasks` list with the task.
       content:
         application/json:
           schema:
@@ -227,8 +217,10 @@ post:
 
         #### InfluxDB Cloud
 
-        - Returns this error if the task doesn't contain one of _`flux`_ or _`scriptID`_.
-        - Returns this error if the task contains _`flux`_ _and_ _`scriptID`_.
+        - Returns this error if the task doesn't contain the `flux` property
+          or the `scriptID` property.
+        - Returns this error if the task contains `flux` _and_ `scriptID`
+          properties.
       content:
         application/json:
           schema:
@@ -258,41 +250,3 @@ post:
         application/json:
           schema:
             $ref: "../../common/schemas/Error.yml"
-  x-codeSamples:
-    - lang: Shell
-      label: "cURL: create a Flux script task"
-      source: |
-        curl INFLUX_URL/api/v2/tasks \
-        --header "Content-type: application/json" \
-        --header "Authorization: Token INFLUX_API_TOKEN" \
-        --data-binary @- << EOF
-          {
-            "orgID": "INFLUX_ORG_ID",
-            "description": "IoT Center 30d environment average.",
-            "flux": "option task = {name: \"iot-center-task-1\", every: 30m}\
-                    from(bucket: \"iot_center\")\
-                      |> range(start: -30d)\
-                      |> filter(fn: (r) => r._measurement == \"environment\")\
-                      |> aggregateWindow(every: 1h, fn: mean)"
-          }
-        EOF
-    - lang: Shell
-      label: "cURL: create a Flux script reference task"
-      source: |
-        curl INFLUX_URL/api/v2/tasks \
-        --header "Content-type: application/json" \
-        --header "Authorization: Token INFLUX_API_TOKEN" \
-        --data-binary @- << EOF
-          {
-            "orgID": "INFLUX_ORG_ID",
-            "description": "IoT Center 30d environment average.",
-            "scriptID": "085138a111448000",
-            "scriptParameters":
-              {
-                "rangeStart": "-30d",
-                "bucket": "air_sensor",
-                "filterField": "temperature",
-                "groupColumn": "_time"
-              }
-          }
-        EOF