From 91cee1457f3ef69ff4d402ac5adcdc8fad35ea66 Mon Sep 17 00:00:00 2001 From: Jason Stirnaman Date: Mon, 31 Oct 2022 12:21:53 -0500 Subject: [PATCH 1/3] refactor: common task properties: - add TaskProperties.yml that defines schemas for properties. - in _schemas.yml, define NamedSchemas for the properties so they can be referenced elsewhere. - replace duplicated properties with to the schemas in TaskProperties.yml - cleanup descriptions. --- contracts/cloud-diff.yml | 311 +++++++++++------------ contracts/cloud.json | 171 +++++++------ contracts/cloud.yml | 217 ++++++++-------- contracts/common.yml | 38 +++ contracts/oss-diff.yml | 191 +++++++------- contracts/oss.json | 115 +++++---- contracts/oss.yml | 119 +++++---- contracts/ref/cloud.yml | 223 ++++++++-------- contracts/ref/oss.yml | 125 +++++---- src/cloud.yml | 6 +- src/cloud/paths/tasks.yml | 2 +- src/cloud/schemas/Task.yml | 141 ++-------- src/cloud/schemas/TaskCreateRequest.yml | 81 ++---- src/cloud/schemas/TaskProperties.yml | 26 ++ src/cloud/schemas/TaskUpdateRequest.yml | 30 +-- src/common/_schemas.yml | 16 ++ src/common/paths/tasks.yml | 2 +- src/common/schemas/Task.yml | 112 ++------ src/common/schemas/TaskCreateRequest.yml | 24 +- src/common/schemas/TaskProperties.yml | 118 +++++++++ src/common/schemas/TaskUpdateRequest.yml | 20 +- src/oss.yml | 2 +- 22 files changed, 1044 insertions(+), 1046 deletions(-) create mode 100644 src/cloud/schemas/TaskProperties.yml create mode 100644 src/common/schemas/TaskProperties.yml diff --git a/contracts/cloud-diff.yml b/contracts/cloud-diff.yml index 419b3022e..30abb5ff7 100644 --- a/contracts/cloud-diff.yml +++ b/contracts/cloud-diff.yml @@ -1447,17 +1447,20 @@ paths: org: /api/v2/labels/1 properties: self: - $ref: '#/components/schemas/Task/properties/links/properties/self' + $ref: '#/paths/~1dashboards/post/responses/201/content/application~1json/schema/oneOf/0/allOf/1/properties/links/properties/org' cells: - $ref: '#/components/schemas/Task/properties/links/properties/self' + $ref: '#/paths/~1dashboards/post/responses/201/content/application~1json/schema/oneOf/0/allOf/1/properties/links/properties/org' members: - $ref: '#/components/schemas/Task/properties/links/properties/self' + $ref: '#/paths/~1dashboards/post/responses/201/content/application~1json/schema/oneOf/0/allOf/1/properties/links/properties/org' owners: - $ref: '#/components/schemas/Task/properties/links/properties/self' + $ref: '#/paths/~1dashboards/post/responses/201/content/application~1json/schema/oneOf/0/allOf/1/properties/links/properties/org' labels: - $ref: '#/components/schemas/Task/properties/links/properties/self' + $ref: '#/paths/~1dashboards/post/responses/201/content/application~1json/schema/oneOf/0/allOf/1/properties/links/properties/org' org: - $ref: '#/components/schemas/Task/properties/links/properties/self' + type: string + format: uri + readOnly: true + description: URI of resource. id: readOnly: true type: string @@ -1500,7 +1503,7 @@ paths: type: string description: The reference to a view from the views API. labels: - $ref: '#/components/schemas/Task/properties/labels' + $ref: '#/components/schemas/Variable/properties/labels' - type: object allOf: - $ref: '#/paths/~1dashboards/post/requestBody/content/application~1json/schema' @@ -1517,17 +1520,17 @@ paths: org: /api/v2/labels/1 properties: self: - $ref: '#/components/schemas/Task/properties/links/properties/self' + $ref: '#/paths/~1dashboards/post/responses/201/content/application~1json/schema/oneOf/0/allOf/1/properties/links/properties/org' cells: - $ref: '#/components/schemas/Task/properties/links/properties/self' + $ref: '#/paths/~1dashboards/post/responses/201/content/application~1json/schema/oneOf/0/allOf/1/properties/links/properties/org' members: - $ref: '#/components/schemas/Task/properties/links/properties/self' + $ref: '#/paths/~1dashboards/post/responses/201/content/application~1json/schema/oneOf/0/allOf/1/properties/links/properties/org' owners: - $ref: '#/components/schemas/Task/properties/links/properties/self' + $ref: '#/paths/~1dashboards/post/responses/201/content/application~1json/schema/oneOf/0/allOf/1/properties/links/properties/org' labels: - $ref: '#/components/schemas/Task/properties/links/properties/self' + $ref: '#/paths/~1dashboards/post/responses/201/content/application~1json/schema/oneOf/0/allOf/1/properties/links/properties/org' org: - $ref: '#/components/schemas/Task/properties/links/properties/self' + $ref: '#/paths/~1dashboards/post/responses/201/content/application~1json/schema/oneOf/0/allOf/1/properties/links/properties/org' id: readOnly: true type: string @@ -2265,7 +2268,7 @@ paths: readOnly: true type: string labels: - $ref: '#/components/schemas/Task/properties/labels' + $ref: '#/components/schemas/Variable/properties/labels' links: type: object readOnly: true @@ -2278,19 +2281,19 @@ paths: properties: self: description: The URL for this check. - $ref: '#/components/schemas/Task/properties/links/properties/self' + $ref: '#/paths/~1dashboards/post/responses/201/content/application~1json/schema/oneOf/0/allOf/1/properties/links/properties/org' labels: description: The URL to retrieve labels for this check. - $ref: '#/components/schemas/Task/properties/links/properties/self' + $ref: '#/paths/~1dashboards/post/responses/201/content/application~1json/schema/oneOf/0/allOf/1/properties/links/properties/org' members: description: The URL to retrieve members for this check. - $ref: '#/components/schemas/Task/properties/links/properties/self' + $ref: '#/paths/~1dashboards/post/responses/201/content/application~1json/schema/oneOf/0/allOf/1/properties/links/properties/org' owners: description: The URL to retrieve owners for this check. - $ref: '#/components/schemas/Task/properties/links/properties/self' + $ref: '#/paths/~1dashboards/post/responses/201/content/application~1json/schema/oneOf/0/allOf/1/properties/links/properties/org' query: description: The URL to retrieve the Flux script for this check. - $ref: '#/components/schemas/Task/properties/links/properties/self' + $ref: '#/paths/~1dashboards/post/responses/201/content/application~1json/schema/oneOf/0/allOf/1/properties/links/properties/org' required: - name - orgID @@ -3109,7 +3112,7 @@ paths: items: $ref: '#/paths/~1dashboards/post/responses/201/content/application~1json/schema/oneOf/1/allOf/1/properties/cells/items/allOf/1/properties/properties/oneOf/0/properties/colors/items' labels: - $ref: '#/components/schemas/Task/properties/labels' + $ref: '#/components/schemas/Variable/properties/labels' default: description: Unexpected error content: @@ -3211,11 +3214,11 @@ paths: URI pointers for additional paged results. properties: next: - $ref: '#/components/schemas/Task/properties/links/properties/self' + $ref: '#/paths/~1dashboards/post/responses/201/content/application~1json/schema/oneOf/0/allOf/1/properties/links/properties/org' self: - $ref: '#/components/schemas/Task/properties/links/properties/self' + $ref: '#/paths/~1dashboards/post/responses/201/content/application~1json/schema/oneOf/0/allOf/1/properties/links/properties/org' prev: - $ref: '#/components/schemas/Task/properties/links/properties/self' + $ref: '#/paths/~1dashboards/post/responses/201/content/application~1json/schema/oneOf/0/allOf/1/properties/links/properties/org' required: - self dashboards: @@ -3531,7 +3534,7 @@ paths: parameters: - $ref: '#/paths/~1users/get/parameters/0' requestBody: - description: The task to create + description: Provide a task object in the request body. required: true content: application/json: @@ -3934,21 +3937,21 @@ components: dashboards: /api/v2/dashboards?org=myorg properties: self: - $ref: '#/components/schemas/Task/properties/links/properties/self' + $ref: '#/paths/~1dashboards/post/responses/201/content/application~1json/schema/oneOf/0/allOf/1/properties/links/properties/org' members: - $ref: '#/components/schemas/Task/properties/links/properties/self' + $ref: '#/paths/~1dashboards/post/responses/201/content/application~1json/schema/oneOf/0/allOf/1/properties/links/properties/org' owners: - $ref: '#/components/schemas/Task/properties/links/properties/self' + $ref: '#/paths/~1dashboards/post/responses/201/content/application~1json/schema/oneOf/0/allOf/1/properties/links/properties/org' labels: - $ref: '#/components/schemas/Task/properties/links/properties/self' + $ref: '#/paths/~1dashboards/post/responses/201/content/application~1json/schema/oneOf/0/allOf/1/properties/links/properties/org' secrets: - $ref: '#/components/schemas/Task/properties/links/properties/self' + $ref: '#/paths/~1dashboards/post/responses/201/content/application~1json/schema/oneOf/0/allOf/1/properties/links/properties/org' buckets: - $ref: '#/components/schemas/Task/properties/links/properties/self' + $ref: '#/paths/~1dashboards/post/responses/201/content/application~1json/schema/oneOf/0/allOf/1/properties/links/properties/org' tasks: - $ref: '#/components/schemas/Task/properties/links/properties/self' + $ref: '#/paths/~1dashboards/post/responses/201/content/application~1json/schema/oneOf/0/allOf/1/properties/links/properties/org' dashboards: - $ref: '#/components/schemas/Task/properties/links/properties/self' + $ref: '#/paths/~1dashboards/post/responses/201/content/application~1json/schema/oneOf/0/allOf/1/properties/links/properties/org' id: readOnly: true type: string @@ -3988,22 +3991,22 @@ components: properties: labels: description: The URL to retrieve labels for this bucket. - $ref: '#/components/schemas/Task/properties/links/properties/self' + $ref: '#/paths/~1dashboards/post/responses/201/content/application~1json/schema/oneOf/0/allOf/1/properties/links/properties/org' members: description: The URL to retrieve members that can read this bucket. - $ref: '#/components/schemas/Task/properties/links/properties/self' + $ref: '#/paths/~1dashboards/post/responses/201/content/application~1json/schema/oneOf/0/allOf/1/properties/links/properties/org' org: description: The URL to retrieve parent organization for this bucket. - $ref: '#/components/schemas/Task/properties/links/properties/self' + $ref: '#/paths/~1dashboards/post/responses/201/content/application~1json/schema/oneOf/0/allOf/1/properties/links/properties/org' owners: description: The URL to retrieve owners that can read and write to this bucket. - $ref: '#/components/schemas/Task/properties/links/properties/self' + $ref: '#/paths/~1dashboards/post/responses/201/content/application~1json/schema/oneOf/0/allOf/1/properties/links/properties/org' self: description: The URL for this bucket. - $ref: '#/components/schemas/Task/properties/links/properties/self' + $ref: '#/paths/~1dashboards/post/responses/201/content/application~1json/schema/oneOf/0/allOf/1/properties/links/properties/org' write: description: The URL to write line protocol to this bucket. - $ref: '#/components/schemas/Task/properties/links/properties/self' + $ref: '#/paths/~1dashboards/post/responses/201/content/application~1json/schema/oneOf/0/allOf/1/properties/links/properties/org' id: readOnly: true type: string @@ -4085,7 +4088,7 @@ components: required: - everySeconds labels: - $ref: '#/components/schemas/Task/properties/labels' + $ref: '#/components/schemas/Variable/properties/labels' required: - name - retentionRules @@ -4160,10 +4163,10 @@ components: properties: self: readOnly: true - $ref: '#/components/schemas/Task/properties/links/properties/self' + $ref: '#/paths/~1dashboards/post/responses/201/content/application~1json/schema/oneOf/0/allOf/1/properties/links/properties/org' user: readOnly: true - $ref: '#/components/schemas/Task/properties/links/properties/self' + $ref: '#/paths/~1dashboards/post/responses/201/content/application~1json/schema/oneOf/0/allOf/1/properties/links/properties/org' Limit: type: object description: These are org limits similar to those configured in/by quartz. @@ -4307,7 +4310,28 @@ components: sort_order: type: integer labels: - $ref: '#/components/schemas/Task/properties/labels' + type: array + items: + type: object + properties: + id: + readOnly: true + type: string + orgID: + readOnly: true + type: string + name: + type: string + properties: + type: object + additionalProperties: + type: string + description: | + Key-value pairs associated with this label. + To remove a property, send an update with an empty value (`""`) for the key. + example: + color: ffb3b3 + description: this is a description arguments: type: object oneOf: @@ -4579,31 +4603,33 @@ components: id: readOnly: true type: string + description: | + The resource ID that InfluxDB uses to uniquely identify the task. orgID: description: | - An [organization]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#organization) ID. - Specifies the organization that owns the task. + An organization ID. + Identifies the [organization]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#organization) that owns the task. type: string org: description: | - An [organization]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#organization) name. - Specifies the organization that owns the task. + An organization name. + Identifies the [organization]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#organization) that owns the task. type: string name: description: The name of the task. type: string + description: + description: A description of the task. + type: string ownerID: description: | - A [user]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#user) ID. - Specifies the owner of the task. + A user ID. + Identifies the [user]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#user) that owns the task. - To find a user ID, you can use the + To find a user ID, use the [`GET /api/v2/users` endpoint](#operation/GetUsers) to list users. type: string - description: - description: A description of the task. - type: string status: type: string enum: @@ -4612,32 +4638,11 @@ components: description: | `inactive` cancels scheduled runs and prevents manual runs of the task. labels: - type: array - items: - type: object - properties: - id: - readOnly: true - type: string - orgID: - readOnly: true - type: string - name: - type: string - properties: - type: object - additionalProperties: - type: string - description: | - Key-value pairs associated with this label. - To remove a property, send an update with an empty value (`""`) for the key. - example: - color: ffb3b3 - description: this is a description + $ref: '#/components/schemas/Variable/properties/labels' authorizationID: description: | An authorization ID. - Specifies the authorization used when the task communicates with the query engine. + Identifies the authorization used when the task communicates with the query engine. To find an authorization ID, use the [`GET /api/v2/authorizations` endpoint](#operation/GetAuthorizations) to @@ -4645,12 +4650,14 @@ components: type: string flux: description: | - The Flux script that the task executes. + Flux with [task configuration options]({{% INFLUXDB_DOCS_URL %}}/process-data/task-options/) + and the script for the task to run. - #### Limitations - - If you use the `flux` property, you can't use the `scriptID` and `scriptParameters` properties. + #### Related guides + + - [Task configuration options]({{% INFLUXDB_DOCS_URL %}}/process-data/task-options/) type: string - format: flux + format: Flux every: description: 'The interval ([duration literal]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#rfc3339-timestamp)) at which the task runs. `every` also determines when the task first runs, depending on the specified time.' type: string @@ -4658,6 +4665,7 @@ components: cron: description: 'A [Cron expression](https://en.wikipedia.org/wiki/Cron#Overview) that defines the schedule on which the task runs. InfluxDB uses the system time when evaluating Cron expressions.' type: string + format: cron offset: description: 'A [duration](https://docs.influxdata.com/flux/v0.x/spec/lexical-elements/#duration-literals) to delay execution of the task after the scheduled time has elapsed. `0` removes the offset.' type: string @@ -4697,45 +4705,21 @@ components: logs: /api/v2/tasks/1/logs properties: self: - type: string - format: uri - readOnly: true - description: URI of resource. + $ref: '#/paths/~1dashboards/post/responses/201/content/application~1json/schema/oneOf/0/allOf/1/properties/links/properties/org' owners: - $ref: '#/components/schemas/Task/properties/links/properties/self' + $ref: '#/paths/~1dashboards/post/responses/201/content/application~1json/schema/oneOf/0/allOf/1/properties/links/properties/org' members: - $ref: '#/components/schemas/Task/properties/links/properties/self' + $ref: '#/paths/~1dashboards/post/responses/201/content/application~1json/schema/oneOf/0/allOf/1/properties/links/properties/org' runs: - $ref: '#/components/schemas/Task/properties/links/properties/self' + $ref: '#/paths/~1dashboards/post/responses/201/content/application~1json/schema/oneOf/0/allOf/1/properties/links/properties/org' logs: - $ref: '#/components/schemas/Task/properties/links/properties/self' + $ref: '#/paths/~1dashboards/post/responses/201/content/application~1json/schema/oneOf/0/allOf/1/properties/links/properties/org' labels: - $ref: '#/components/schemas/Task/properties/links/properties/self' + $ref: '#/paths/~1dashboards/post/responses/201/content/application~1json/schema/oneOf/0/allOf/1/properties/links/properties/org' scriptID: - description: | - A script ID. - Specifies the [invokable script](#tag/Invokable-Scripts) that the task executes. - - #### Limitations - - - If you use the `scriptID` property, you can't use the `flux` property. - - #### Related guides - - - [Create a task that references a script]({{% INFLUXDB_DOCS_URL %}}/process-data/manage-tasks/create-task/#create-a-task-that-references-a-script) - type: string + $ref: '#/components/schemas/TaskScriptID' scriptParameters: - description: | - Key-value pairs for `params` in the script. - Defines the invocation parameter values passed to the script specified by `scriptID`. - When running the task, InfluxDB executes the script with the parameters - you provide. - - #### Limitations - - - To use `scriptParameters`, you must provide a `scriptID`. - - If you use the `scriptID` and `scriptParameters` properties, you can't use the `flux` property. - type: object + $ref: '#/components/schemas/TaskScriptParameters' required: - id - name @@ -4744,85 +4728,74 @@ components: type: object properties: orgID: - description: The ID of the organization that owns the task. - type: string + $ref: '#/components/schemas/Task/properties/orgID' org: - description: The name of the organization that owns the task. - type: string + $ref: '#/components/schemas/Task/properties/org' + name: + $ref: '#/components/schemas/Task/properties/name' + description: + $ref: '#/components/schemas/Task/properties/description' + every: + $ref: '#/components/schemas/Task/properties/every' + cron: + $ref: '#/components/schemas/Task/properties/cron' + offset: + $ref: '#/components/schemas/Task/properties/offset' status: $ref: '#/components/schemas/Task/properties/status' flux: - description: | - The Flux script that the task runs. + $ref: '#/components/schemas/Task/properties/flux' + scriptID: + $ref: '#/components/schemas/TaskScriptID' + scriptParameters: + $ref: '#/components/schemas/TaskScriptParameters' + TaskScriptID: + description: | + A script ID. + Identifies the [invokable script](#tag/Invokable-Scripts) that the task runs. - #### Limitations + #### Related guides - - If you use the `flux` property, you can't use the `scriptID` and `scriptParameters` properties. - type: string - description: - description: The description of the task. - type: string - scriptID: - description: | - The ID of the script that the task runs. + - [Create a task that references a script]({{% INFLUXDB_DOCS_URL %}}/process-data/manage-tasks/create-task/#create-a-task-that-references-a-script). + type: string + TaskScriptParameters: + description: | + Key-value pairs for `params` in the script. + Defines the invocation parameter values passed to the [invokable script](#tag/Invokable-Scripts) specified + by the `scriptID` property. + When running the task, InfluxDB executes the script with the parameters + you provide. - #### Limitations + #### Limitations - - If you use the `scriptID` property, you can't use the `flux` property. - type: string - scriptParameters: - description: | - The parameter key-value pairs passed to the script (referenced by `scriptID`) during the task run. + - To use the `scriptParameters` property, you must also set the `scriptID` property + for the task. - #### Limitations + #### Related guides - - `scriptParameters` requires `scriptID`. - - If you use the `scriptID` and `scriptParameters` properties, you can't use the `flux` property. - type: object - name: - description: The name of the task - type: string - every: - description: | - The interval ([duration literal](https://docs.influxdata.com/flux/v0.x/spec/lexical-elements/#duration-literals))) at which the task runs. - `every` also determines when the task first runs, depending on the specified time. - type: string - cron: - description: 'A [Cron expression](https://en.wikipedia.org/wiki/Cron#Overview) that defines the schedule on which the task runs. InfluxDB bases cron runs on the system time.' - type: string - offset: - description: 'A [duration](https://docs.influxdata.com/flux/v0.x/spec/lexical-elements/#duration-literals) to delay execution of the task after the scheduled time has elapsed. `0` removes the offset.' - type: string - format: duration + - [Create a task that references a script]({{% INFLUXDB_DOCS_URL %}}/process-data/manage-tasks/create-task/#create-a-task-that-references-a-script). + type: object TaskUpdateRequest: type: object properties: status: $ref: '#/components/schemas/Task/properties/status' - flux: - description: Update the Flux script that the task runs. - type: string name: - description: Update the 'name' option in the flux script. - type: string + $ref: '#/components/schemas/Task/properties/name' + description: + $ref: '#/components/schemas/Task/properties/description' every: - description: Update the 'every' option in the flux script. - type: string + $ref: '#/components/schemas/Task/properties/every' cron: - description: Update the 'cron' option in the flux script. - type: string + $ref: '#/components/schemas/Task/properties/cron' offset: - description: Update the 'offset' option in the flux script. - type: string - description: - description: Update the description of the task. - type: string + $ref: '#/components/schemas/Task/properties/offset' + flux: + $ref: '#/components/schemas/Task/properties/flux' scriptID: - description: Update the 'scriptID' of the task. - type: string + $ref: '#/components/schemas/TaskScriptID' scriptParameters: - description: Update the 'scriptParameters' of the task. - type: object + $ref: '#/components/schemas/TaskScriptParameters' responses: null examples: AuthorizationPostRequest: diff --git a/contracts/cloud.json b/contracts/cloud.json index 76f1dc925..80f62d557 100644 --- a/contracts/cloud.json +++ b/contracts/cloud.json @@ -13012,7 +13012,7 @@ } ], "requestBody": { - "description": "The task to create", + "description": "Provide a task object in the request body.", "required": true, "content": { "application/json": { @@ -16278,6 +16278,42 @@ } } }, + "TaskCron": { + "description": "A [Cron expression](https://en.wikipedia.org/wiki/Cron#Overview) that defines the schedule on which the task runs. InfluxDB uses the system time when evaluating Cron expressions.", + "type": "string", + "format": "cron" + }, + "TaskDescription": { + "description": "A description of the task.", + "type": "string" + }, + "TaskEvery": { + "description": "The interval ([duration literal]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#rfc3339-timestamp)) at which the task runs. `every` also determines when the task first runs, depending on the specified time.", + "type": "string", + "format": "duration" + }, + "TaskFlux": { + "description": "Flux with [task configuration options]({{% INFLUXDB_DOCS_URL %}}/process-data/task-options/)\nand the script for the task to run.\n\n#### Related guides\n\n- [Task configuration options]({{% INFLUXDB_DOCS_URL %}}/process-data/task-options/)\n", + "type": "string", + "format": "Flux" + }, + "TaskName": { + "description": "The name of the task.", + "type": "string" + }, + "TaskOffset": { + "description": "A [duration](https://docs.influxdata.com/flux/v0.x/spec/lexical-elements/#duration-literals) to delay execution of the task after the scheduled time has elapsed. `0` removes the offset.", + "type": "string", + "format": "duration" + }, + "TaskOrg": { + "description": "An organization name.\nIdentifies the [organization]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#organization) that owns the task.\n", + "type": "string" + }, + "TaskOrgID": { + "description": "An organization ID.\nIdentifies the [organization]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#organization) that owns the task.\n", + "type": "string" + }, "TaskStatusType": { "type": "string", "enum": [ @@ -21533,26 +21569,23 @@ "properties": { "id": { "readOnly": true, - "type": "string" + "type": "string", + "description": "The resource ID that InfluxDB uses to uniquely identify the task.\n" }, "orgID": { - "description": "An [organization]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#organization) ID.\nSpecifies the organization that owns the task.\n", - "type": "string" + "$ref": "#/components/schemas/TaskOrgID" }, "org": { - "description": "An [organization]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#organization) name.\nSpecifies the organization that owns the task.\n", - "type": "string" + "$ref": "#/components/schemas/TaskOrg" }, "name": { - "description": "The name of the task.", - "type": "string" - }, - "ownerID": { - "description": "A [user]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#user) ID.\nSpecifies the owner of the task.\n\nTo find a user ID, you can use the\n[`GET /api/v2/users` endpoint](#operation/GetUsers) to\nlist users.\n", - "type": "string" + "$ref": "#/components/schemas/TaskName" }, "description": { - "description": "A description of the task.", + "$ref": "#/components/schemas/TaskDescription" + }, + "ownerID": { + "description": "A user ID.\nIdentifies the [user]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#user) that owns the task.\n\nTo find a user ID, use the\n[`GET /api/v2/users` endpoint](#operation/GetUsers) to\nlist users.\n", "type": "string" }, "status": { @@ -21562,27 +21595,20 @@ "$ref": "#/components/schemas/Labels" }, "authorizationID": { - "description": "An authorization ID.\nSpecifies the authorization used when the task communicates with the query engine.\n\nTo find an authorization ID, use the\n[`GET /api/v2/authorizations` endpoint](#operation/GetAuthorizations) to\nlist authorizations.\n", + "description": "An authorization ID.\nIdentifies the authorization used when the task communicates with the query engine.\n\nTo find an authorization ID, use the\n[`GET /api/v2/authorizations` endpoint](#operation/GetAuthorizations) to\nlist authorizations.\n", "type": "string" }, "flux": { - "description": "The Flux script that the task executes.\n\n#### Limitations\n - If you use the `flux` property, you can't use the `scriptID` and `scriptParameters` properties.\n", - "type": "string", - "format": "flux" + "$ref": "#/components/schemas/TaskFlux" }, "every": { - "description": "The interval ([duration literal]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#rfc3339-timestamp)) at which the task runs. `every` also determines when the task first runs, depending on the specified time.", - "type": "string", - "format": "duration" + "$ref": "#/components/schemas/TaskEvery" }, "cron": { - "description": "A [Cron expression](https://en.wikipedia.org/wiki/Cron#Overview) that defines the schedule on which the task runs. InfluxDB uses the system time when evaluating Cron expressions.", - "type": "string" + "$ref": "#/components/schemas/TaskCron" }, "offset": { - "description": "A [duration](https://docs.influxdata.com/flux/v0.x/spec/lexical-elements/#duration-literals) to delay execution of the task after the scheduled time has elapsed. `0` removes the offset.", - "type": "string", - "format": "duration" + "$ref": "#/components/schemas/TaskOffset" }, "latestCompleted": { "description": "A timestamp ([RFC3339 date/time format]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#rfc3339-timestamp)) of the latest scheduled and completed run.", @@ -21646,12 +21672,10 @@ } }, "scriptID": { - "description": "A script ID.\nSpecifies the [invokable script](#tag/Invokable-Scripts) that the task executes.\n\n#### Limitations\n\n- If you use the `scriptID` property, you can't use the `flux` property.\n\n#### Related guides\n\n- [Create a task that references a script]({{% INFLUXDB_DOCS_URL %}}/process-data/manage-tasks/create-task/#create-a-task-that-references-a-script)\n", - "type": "string" + "$ref": "#/components/schemas/TaskScriptID" }, "scriptParameters": { - "description": "Key-value pairs for `params` in the script.\nDefines the invocation parameter values passed to the script specified by `scriptID`.\nWhen running the task, InfluxDB executes the script with the parameters\nyou provide.\n\n#### Limitations\n\n- To use `scriptParameters`, you must provide a `scriptID`.\n- If you use the `scriptID` and `scriptParameters` properties, you can't use the `flux` property.\n", - "type": "object" + "$ref": "#/components/schemas/TaskScriptParameters" } }, "required": [ @@ -21664,88 +21688,77 @@ "type": "object", "properties": { "orgID": { - "description": "The ID of the organization that owns the task.", - "type": "string" + "$ref": "#/components/schemas/TaskOrgID" }, "org": { - "description": "The name of the organization that owns the task.", - "type": "string" + "$ref": "#/components/schemas/TaskOrg" }, - "status": { - "$ref": "#/components/schemas/TaskStatusType" - }, - "flux": { - "description": "The Flux script that the task runs.\n\n#### Limitations\n\n- If you use the `flux` property, you can't use the `scriptID` and `scriptParameters` properties.\n", - "type": "string" + "name": { + "$ref": "#/components/schemas/TaskName" }, "description": { - "description": "The description of the task.", - "type": "string" - }, - "scriptID": { - "description": "The ID of the script that the task runs.\n\n#### Limitations\n\n- If you use the `scriptID` property, you can't use the `flux` property.\n", - "type": "string" - }, - "scriptParameters": { - "description": "The parameter key-value pairs passed to the script (referenced by `scriptID`) during the task run.\n\n#### Limitations\n\n- `scriptParameters` requires `scriptID`.\n- If you use the `scriptID` and `scriptParameters` properties, you can't use the `flux` property.\n", - "type": "object" - }, - "name": { - "description": "The name of the task", - "type": "string" + "$ref": "#/components/schemas/TaskDescription" }, "every": { - "description": "The interval ([duration literal](https://docs.influxdata.com/flux/v0.x/spec/lexical-elements/#duration-literals))) at which the task runs.\n`every` also determines when the task first runs, depending on the specified time.\n", - "type": "string" + "$ref": "#/components/schemas/TaskEvery" }, "cron": { - "description": "A [Cron expression](https://en.wikipedia.org/wiki/Cron#Overview) that defines the schedule on which the task runs. InfluxDB bases cron runs on the system time.", - "type": "string" + "$ref": "#/components/schemas/TaskCron" }, "offset": { - "description": "A [duration](https://docs.influxdata.com/flux/v0.x/spec/lexical-elements/#duration-literals) to delay execution of the task after the scheduled time has elapsed. `0` removes the offset.", - "type": "string", - "format": "duration" + "$ref": "#/components/schemas/TaskOffset" + }, + "status": { + "$ref": "#/components/schemas/TaskStatusType" + }, + "flux": { + "$ref": "#/components/schemas/TaskFlux" + }, + "scriptID": { + "$ref": "#/components/schemas/TaskScriptID" + }, + "scriptParameters": { + "$ref": "#/components/schemas/TaskScriptParameters" } } }, + "TaskScriptID": { + "description": "A script ID.\nIdentifies the [invokable script](#tag/Invokable-Scripts) that the task runs.\n\n#### Related guides\n\n- [Create a task that references a script]({{% INFLUXDB_DOCS_URL %}}/process-data/manage-tasks/create-task/#create-a-task-that-references-a-script).\n", + "type": "string" + }, + "TaskScriptParameters": { + "description": "Key-value pairs for `params` in the script.\nDefines the invocation parameter values passed to the [invokable script](#tag/Invokable-Scripts) specified\nby the `scriptID` property.\nWhen running the task, InfluxDB executes the script with the parameters\nyou provide.\n\n#### Limitations\n\n- To use the `scriptParameters` property, you must also set the `scriptID` property\n for the task.\n\n#### Related guides\n\n- [Create a task that references a script]({{% INFLUXDB_DOCS_URL %}}/process-data/manage-tasks/create-task/#create-a-task-that-references-a-script).\n", + "type": "object" + }, "TaskUpdateRequest": { "type": "object", "properties": { "status": { "$ref": "#/components/schemas/TaskStatusType" }, - "flux": { - "description": "Update the Flux script that the task runs.", - "type": "string" - }, "name": { - "description": "Update the 'name' option in the flux script.", - "type": "string" + "$ref": "#/components/schemas/TaskName" + }, + "description": { + "$ref": "#/components/schemas/TaskDescription" }, "every": { - "description": "Update the 'every' option in the flux script.", - "type": "string" + "$ref": "#/components/schemas/TaskEvery" }, "cron": { - "description": "Update the 'cron' option in the flux script.", - "type": "string" + "$ref": "#/components/schemas/TaskCron" }, "offset": { - "description": "Update the 'offset' option in the flux script.", - "type": "string" + "$ref": "#/components/schemas/TaskOffset" }, - "description": { - "description": "Update the description of the task.", - "type": "string" + "flux": { + "$ref": "#/components/schemas/TaskFlux" }, "scriptID": { - "description": "Update the 'scriptID' of the task.", - "type": "string" + "$ref": "#/components/schemas/TaskScriptID" }, "scriptParameters": { - "description": "Update the 'scriptParameters' of the task.", - "type": "object" + "$ref": "#/components/schemas/TaskScriptParameters" } } } diff --git a/contracts/cloud.yml b/contracts/cloud.yml index eee61e0af..f738fc86d 100644 --- a/contracts/cloud.yml +++ b/contracts/cloud.yml @@ -10584,7 +10584,7 @@ paths: parameters: - $ref: '#/components/parameters/TraceSpan' requestBody: - description: The task to create + description: Provide a task object in the request body. required: true content: application/json: @@ -13155,6 +13155,44 @@ components: Default is the server _now_ time. type: string format: date-time + TaskCron: + description: 'A [Cron expression](https://en.wikipedia.org/wiki/Cron#Overview) that defines the schedule on which the task runs. InfluxDB uses the system time when evaluating Cron expressions.' + type: string + format: cron + TaskDescription: + description: A description of the task. + type: string + TaskEvery: + description: 'The interval ([duration literal](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#rfc3339-timestamp)) at which the task runs. `every` also determines when the task first runs, depending on the specified time.' + type: string + format: duration + TaskFlux: + description: | + Flux with [task configuration options](https://docs.influxdata.com/influxdb/cloud/process-data/task-options/) + and the script for the task to run. + + #### Related guides + + - [Task configuration options](https://docs.influxdata.com/influxdb/cloud/process-data/task-options/) + type: string + format: Flux + TaskName: + description: The name of the task. + type: string + TaskOffset: + description: 'A [duration](https://docs.influxdata.com/flux/v0.x/spec/lexical-elements/#duration-literals) to delay execution of the task after the scheduled time has elapsed. `0` removes the offset.' + type: string + format: duration + TaskOrg: + description: | + An organization name. + Identifies the [organization](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#organization) that owns the task. + type: string + TaskOrgID: + description: | + An organization ID. + Identifies the [organization](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#organization) that owns the task. + type: string TaskStatusType: type: string enum: @@ -16770,31 +16808,25 @@ components: id: readOnly: true type: string - orgID: description: | - An [organization](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#organization) ID. - Specifies the organization that owns the task. - type: string + The resource ID that InfluxDB uses to uniquely identify the task. + orgID: + $ref: '#/components/schemas/TaskOrgID' org: - description: | - An [organization](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#organization) name. - Specifies the organization that owns the task. - type: string + $ref: '#/components/schemas/TaskOrg' name: - description: The name of the task. - type: string + $ref: '#/components/schemas/TaskName' + description: + $ref: '#/components/schemas/TaskDescription' ownerID: description: | - A [user](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#user) ID. - Specifies the owner of the task. + A user ID. + Identifies the [user](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#user) that owns the task. - To find a user ID, you can use the + To find a user ID, use the [`GET /api/v2/users` endpoint](#operation/GetUsers) to list users. type: string - description: - description: A description of the task. - type: string status: $ref: '#/components/schemas/TaskStatusType' labels: @@ -16802,31 +16834,20 @@ components: authorizationID: description: | An authorization ID. - Specifies the authorization used when the task communicates with the query engine. + Identifies the authorization used when the task communicates with the query engine. To find an authorization ID, use the [`GET /api/v2/authorizations` endpoint](#operation/GetAuthorizations) to list authorizations. type: string flux: - description: | - The Flux script that the task executes. - - #### Limitations - - If you use the `flux` property, you can't use the `scriptID` and `scriptParameters` properties. - type: string - format: flux + $ref: '#/components/schemas/TaskFlux' every: - description: 'The interval ([duration literal](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#rfc3339-timestamp)) at which the task runs. `every` also determines when the task first runs, depending on the specified time.' - type: string - format: duration + $ref: '#/components/schemas/TaskEvery' cron: - description: 'A [Cron expression](https://en.wikipedia.org/wiki/Cron#Overview) that defines the schedule on which the task runs. InfluxDB uses the system time when evaluating Cron expressions.' - type: string + $ref: '#/components/schemas/TaskCron' offset: - description: 'A [duration](https://docs.influxdata.com/flux/v0.x/spec/lexical-elements/#duration-literals) to delay execution of the task after the scheduled time has elapsed. `0` removes the offset.' - type: string - format: duration + $ref: '#/components/schemas/TaskOffset' latestCompleted: description: 'A timestamp ([RFC3339 date/time format](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#rfc3339-timestamp)) of the latest scheduled and completed run.' type: string @@ -16874,30 +16895,9 @@ components: labels: $ref: '#/components/schemas/Link' scriptID: - description: | - A script ID. - Specifies the [invokable script](#tag/Invokable-Scripts) that the task executes. - - #### Limitations - - - If you use the `scriptID` property, you can't use the `flux` property. - - #### Related guides - - - [Create a task that references a script](https://docs.influxdata.com/influxdb/cloud/process-data/manage-tasks/create-task/#create-a-task-that-references-a-script) - type: string + $ref: '#/components/schemas/TaskScriptID' scriptParameters: - description: | - Key-value pairs for `params` in the script. - Defines the invocation parameter values passed to the script specified by `scriptID`. - When running the task, InfluxDB executes the script with the parameters - you provide. - - #### Limitations - - - To use `scriptParameters`, you must provide a `scriptID`. - - If you use the `scriptID` and `scriptParameters` properties, you can't use the `flux` property. - type: object + $ref: '#/components/schemas/TaskScriptParameters' required: - id - name @@ -16906,85 +16906,74 @@ components: type: object properties: orgID: - description: The ID of the organization that owns the task. - type: string + $ref: '#/components/schemas/TaskOrgID' org: - description: The name of the organization that owns the task. - type: string + $ref: '#/components/schemas/TaskOrg' + name: + $ref: '#/components/schemas/TaskName' + description: + $ref: '#/components/schemas/TaskDescription' + every: + $ref: '#/components/schemas/TaskEvery' + cron: + $ref: '#/components/schemas/TaskCron' + offset: + $ref: '#/components/schemas/TaskOffset' status: $ref: '#/components/schemas/TaskStatusType' flux: - description: | - The Flux script that the task runs. + $ref: '#/components/schemas/TaskFlux' + scriptID: + $ref: '#/components/schemas/TaskScriptID' + scriptParameters: + $ref: '#/components/schemas/TaskScriptParameters' + TaskScriptID: + description: | + A script ID. + Identifies the [invokable script](#tag/Invokable-Scripts) that the task runs. - #### Limitations + #### Related guides - - If you use the `flux` property, you can't use the `scriptID` and `scriptParameters` properties. - type: string - description: - description: The description of the task. - type: string - scriptID: - description: | - The ID of the script that the task runs. + - [Create a task that references a script](https://docs.influxdata.com/influxdb/cloud/process-data/manage-tasks/create-task/#create-a-task-that-references-a-script). + type: string + TaskScriptParameters: + description: | + Key-value pairs for `params` in the script. + Defines the invocation parameter values passed to the [invokable script](#tag/Invokable-Scripts) specified + by the `scriptID` property. + When running the task, InfluxDB executes the script with the parameters + you provide. - #### Limitations + #### Limitations - - If you use the `scriptID` property, you can't use the `flux` property. - type: string - scriptParameters: - description: | - The parameter key-value pairs passed to the script (referenced by `scriptID`) during the task run. + - To use the `scriptParameters` property, you must also set the `scriptID` property + for the task. - #### Limitations + #### Related guides - - `scriptParameters` requires `scriptID`. - - If you use the `scriptID` and `scriptParameters` properties, you can't use the `flux` property. - type: object - name: - description: The name of the task - type: string - every: - description: | - The interval ([duration literal](https://docs.influxdata.com/flux/v0.x/spec/lexical-elements/#duration-literals))) at which the task runs. - `every` also determines when the task first runs, depending on the specified time. - type: string - cron: - description: 'A [Cron expression](https://en.wikipedia.org/wiki/Cron#Overview) that defines the schedule on which the task runs. InfluxDB bases cron runs on the system time.' - type: string - offset: - description: 'A [duration](https://docs.influxdata.com/flux/v0.x/spec/lexical-elements/#duration-literals) to delay execution of the task after the scheduled time has elapsed. `0` removes the offset.' - type: string - format: duration + - [Create a task that references a script](https://docs.influxdata.com/influxdb/cloud/process-data/manage-tasks/create-task/#create-a-task-that-references-a-script). + type: object TaskUpdateRequest: type: object properties: status: $ref: '#/components/schemas/TaskStatusType' - flux: - description: Update the Flux script that the task runs. - type: string name: - description: Update the 'name' option in the flux script. - type: string + $ref: '#/components/schemas/TaskName' + description: + $ref: '#/components/schemas/TaskDescription' every: - description: Update the 'every' option in the flux script. - type: string + $ref: '#/components/schemas/TaskEvery' cron: - description: Update the 'cron' option in the flux script. - type: string + $ref: '#/components/schemas/TaskCron' offset: - description: Update the 'offset' option in the flux script. - type: string - description: - description: Update the description of the task. - type: string + $ref: '#/components/schemas/TaskOffset' + flux: + $ref: '#/components/schemas/TaskFlux' scriptID: - description: Update the 'scriptID' of the task. - type: string + $ref: '#/components/schemas/TaskScriptID' scriptParameters: - description: Update the 'scriptParameters' of the task. - type: object + $ref: '#/components/schemas/TaskScriptParameters' responses: AuthorizationError: description: | diff --git a/contracts/common.yml b/contracts/common.yml index 3f24118c4..56fdd50a1 100644 --- a/contracts/common.yml +++ b/contracts/common.yml @@ -11019,6 +11019,44 @@ components: Default is the server _now_ time. type: string format: date-time + TaskCron: + description: 'A [Cron expression](https://en.wikipedia.org/wiki/Cron#Overview) that defines the schedule on which the task runs. InfluxDB uses the system time when evaluating Cron expressions.' + type: string + format: cron + TaskDescription: + description: A description of the task. + type: string + TaskEvery: + description: 'The interval ([duration literal](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#rfc3339-timestamp)) at which the task runs. `every` also determines when the task first runs, depending on the specified time.' + type: string + format: duration + TaskFlux: + description: | + Flux with [task configuration options](https://docs.influxdata.com/influxdb/v2.3/process-data/task-options/) + and the script for the task to run. + + #### Related guides + + - [Task configuration options](https://docs.influxdata.com/influxdb/v2.3/process-data/task-options/) + type: string + format: Flux + TaskName: + description: The name of the task. + type: string + TaskOffset: + description: 'A [duration](https://docs.influxdata.com/flux/v0.x/spec/lexical-elements/#duration-literals) to delay execution of the task after the scheduled time has elapsed. `0` removes the offset.' + type: string + format: duration + TaskOrg: + description: | + An organization name. + Identifies the [organization](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#organization) that owns the task. + type: string + TaskOrgID: + description: | + An organization ID. + Identifies the [organization](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#organization) that owns the task. + type: string TaskStatusType: type: string enum: diff --git a/contracts/oss-diff.yml b/contracts/oss-diff.yml index f97ebf37c..c46a1e4f2 100644 --- a/contracts/oss-diff.yml +++ b/contracts/oss-diff.yml @@ -2230,7 +2230,7 @@ paths: type: object properties: labels: - $ref: '#/components/schemas/Task/properties/labels' + $ref: '#/components/schemas/Variable/properties/labels' links: $ref: '#/paths/~1dashboards/get/responses/200/content/application~1json/schema/properties/links' default: @@ -3285,17 +3285,17 @@ paths: org: /api/v2/labels/1 properties: self: - $ref: '#/components/schemas/Task/properties/links/properties/self' + $ref: '#/components/schemas/ScraperTargetResponse/allOf/1/properties/links/properties/self' cells: - $ref: '#/components/schemas/Task/properties/links/properties/self' + $ref: '#/components/schemas/ScraperTargetResponse/allOf/1/properties/links/properties/self' members: - $ref: '#/components/schemas/Task/properties/links/properties/self' + $ref: '#/components/schemas/ScraperTargetResponse/allOf/1/properties/links/properties/self' owners: - $ref: '#/components/schemas/Task/properties/links/properties/self' + $ref: '#/components/schemas/ScraperTargetResponse/allOf/1/properties/links/properties/self' labels: - $ref: '#/components/schemas/Task/properties/links/properties/self' + $ref: '#/components/schemas/ScraperTargetResponse/allOf/1/properties/links/properties/self' org: - $ref: '#/components/schemas/Task/properties/links/properties/self' + $ref: '#/components/schemas/ScraperTargetResponse/allOf/1/properties/links/properties/self' id: readOnly: true type: string @@ -3338,7 +3338,7 @@ paths: type: string description: The reference to a view from the views API. labels: - $ref: '#/components/schemas/Task/properties/labels' + $ref: '#/components/schemas/Variable/properties/labels' - type: object allOf: - $ref: '#/paths/~1dashboards/post/requestBody/content/application~1json/schema' @@ -3355,17 +3355,17 @@ paths: org: /api/v2/labels/1 properties: self: - $ref: '#/components/schemas/Task/properties/links/properties/self' + $ref: '#/components/schemas/ScraperTargetResponse/allOf/1/properties/links/properties/self' cells: - $ref: '#/components/schemas/Task/properties/links/properties/self' + $ref: '#/components/schemas/ScraperTargetResponse/allOf/1/properties/links/properties/self' members: - $ref: '#/components/schemas/Task/properties/links/properties/self' + $ref: '#/components/schemas/ScraperTargetResponse/allOf/1/properties/links/properties/self' owners: - $ref: '#/components/schemas/Task/properties/links/properties/self' + $ref: '#/components/schemas/ScraperTargetResponse/allOf/1/properties/links/properties/self' labels: - $ref: '#/components/schemas/Task/properties/links/properties/self' + $ref: '#/components/schemas/ScraperTargetResponse/allOf/1/properties/links/properties/self' org: - $ref: '#/components/schemas/Task/properties/links/properties/self' + $ref: '#/components/schemas/ScraperTargetResponse/allOf/1/properties/links/properties/self' id: readOnly: true type: string @@ -4103,7 +4103,7 @@ paths: readOnly: true type: string labels: - $ref: '#/components/schemas/Task/properties/labels' + $ref: '#/components/schemas/Variable/properties/labels' links: type: object readOnly: true @@ -4116,19 +4116,19 @@ paths: properties: self: description: The URL for this check. - $ref: '#/components/schemas/Task/properties/links/properties/self' + $ref: '#/components/schemas/ScraperTargetResponse/allOf/1/properties/links/properties/self' labels: description: The URL to retrieve labels for this check. - $ref: '#/components/schemas/Task/properties/links/properties/self' + $ref: '#/components/schemas/ScraperTargetResponse/allOf/1/properties/links/properties/self' members: description: The URL to retrieve members for this check. - $ref: '#/components/schemas/Task/properties/links/properties/self' + $ref: '#/components/schemas/ScraperTargetResponse/allOf/1/properties/links/properties/self' owners: description: The URL to retrieve owners for this check. - $ref: '#/components/schemas/Task/properties/links/properties/self' + $ref: '#/components/schemas/ScraperTargetResponse/allOf/1/properties/links/properties/self' query: description: The URL to retrieve the Flux script for this check. - $ref: '#/components/schemas/Task/properties/links/properties/self' + $ref: '#/components/schemas/ScraperTargetResponse/allOf/1/properties/links/properties/self' required: - name - orgID @@ -4947,7 +4947,7 @@ paths: items: $ref: '#/paths/~1dashboards/post/responses/201/content/application~1json/schema/oneOf/1/allOf/1/properties/cells/items/allOf/1/properties/properties/oneOf/0/properties/colors/items' labels: - $ref: '#/components/schemas/Task/properties/labels' + $ref: '#/components/schemas/Variable/properties/labels' default: description: Unexpected error content: @@ -5029,11 +5029,11 @@ paths: URI pointers for additional paged results. properties: next: - $ref: '#/components/schemas/Task/properties/links/properties/self' + $ref: '#/components/schemas/ScraperTargetResponse/allOf/1/properties/links/properties/self' self: - $ref: '#/components/schemas/Task/properties/links/properties/self' + $ref: '#/components/schemas/ScraperTargetResponse/allOf/1/properties/links/properties/self' prev: - $ref: '#/components/schemas/Task/properties/links/properties/self' + $ref: '#/components/schemas/ScraperTargetResponse/allOf/1/properties/links/properties/self' required: - self dashboards: @@ -5270,7 +5270,7 @@ paths: parameters: - $ref: '#/paths/~1ready/get/parameters/0' requestBody: - description: The task to create. + description: Provide a task object in the request body. required: true content: application/json: @@ -5604,21 +5604,21 @@ components: dashboards: /api/v2/dashboards?org=myorg properties: self: - $ref: '#/components/schemas/Task/properties/links/properties/self' + $ref: '#/components/schemas/ScraperTargetResponse/allOf/1/properties/links/properties/self' members: - $ref: '#/components/schemas/Task/properties/links/properties/self' + $ref: '#/components/schemas/ScraperTargetResponse/allOf/1/properties/links/properties/self' owners: - $ref: '#/components/schemas/Task/properties/links/properties/self' + $ref: '#/components/schemas/ScraperTargetResponse/allOf/1/properties/links/properties/self' labels: - $ref: '#/components/schemas/Task/properties/links/properties/self' + $ref: '#/components/schemas/ScraperTargetResponse/allOf/1/properties/links/properties/self' secrets: - $ref: '#/components/schemas/Task/properties/links/properties/self' + $ref: '#/components/schemas/ScraperTargetResponse/allOf/1/properties/links/properties/self' buckets: - $ref: '#/components/schemas/Task/properties/links/properties/self' + $ref: '#/components/schemas/ScraperTargetResponse/allOf/1/properties/links/properties/self' tasks: - $ref: '#/components/schemas/Task/properties/links/properties/self' + $ref: '#/components/schemas/ScraperTargetResponse/allOf/1/properties/links/properties/self' dashboards: - $ref: '#/components/schemas/Task/properties/links/properties/self' + $ref: '#/components/schemas/ScraperTargetResponse/allOf/1/properties/links/properties/self' id: readOnly: true type: string @@ -5658,22 +5658,22 @@ components: properties: labels: description: The URL to retrieve labels for this bucket. - $ref: '#/components/schemas/Task/properties/links/properties/self' + $ref: '#/components/schemas/ScraperTargetResponse/allOf/1/properties/links/properties/self' members: description: The URL to retrieve members that can read this bucket. - $ref: '#/components/schemas/Task/properties/links/properties/self' + $ref: '#/components/schemas/ScraperTargetResponse/allOf/1/properties/links/properties/self' org: description: The URL to retrieve parent organization for this bucket. - $ref: '#/components/schemas/Task/properties/links/properties/self' + $ref: '#/components/schemas/ScraperTargetResponse/allOf/1/properties/links/properties/self' owners: description: The URL to retrieve owners that can read and write to this bucket. - $ref: '#/components/schemas/Task/properties/links/properties/self' + $ref: '#/components/schemas/ScraperTargetResponse/allOf/1/properties/links/properties/self' self: description: The URL for this bucket. - $ref: '#/components/schemas/Task/properties/links/properties/self' + $ref: '#/components/schemas/ScraperTargetResponse/allOf/1/properties/links/properties/self' write: description: The URL to write line protocol to this bucket. - $ref: '#/components/schemas/Task/properties/links/properties/self' + $ref: '#/components/schemas/ScraperTargetResponse/allOf/1/properties/links/properties/self' id: readOnly: true type: string @@ -5755,7 +5755,7 @@ components: required: - everySeconds labels: - $ref: '#/components/schemas/Task/properties/labels' + $ref: '#/components/schemas/Variable/properties/labels' required: - name - retentionRules @@ -5830,10 +5830,10 @@ components: properties: self: readOnly: true - $ref: '#/components/schemas/Task/properties/links/properties/self' + $ref: '#/components/schemas/ScraperTargetResponse/allOf/1/properties/links/properties/self' user: readOnly: true - $ref: '#/components/schemas/Task/properties/links/properties/self' + $ref: '#/components/schemas/ScraperTargetResponse/allOf/1/properties/links/properties/self' Variable: type: object required: @@ -5868,7 +5868,9 @@ components: items: type: string labels: - $ref: '#/components/schemas/Task/properties/labels' + type: array + items: + $ref: '#/paths/~1scrapers~1%7BscraperTargetID%7D~1labels/post/responses/201/content/application~1json/schema/properties/label' arguments: type: object oneOf: @@ -6067,15 +6069,18 @@ components: organization: /api/v2/orgs/1 properties: self: - $ref: '#/components/schemas/Task/properties/links/properties/self' + type: string + format: uri + readOnly: true + description: URI of resource. members: - $ref: '#/components/schemas/Task/properties/links/properties/self' + $ref: '#/components/schemas/ScraperTargetResponse/allOf/1/properties/links/properties/self' owners: - $ref: '#/components/schemas/Task/properties/links/properties/self' + $ref: '#/components/schemas/ScraperTargetResponse/allOf/1/properties/links/properties/self' bucket: - $ref: '#/components/schemas/Task/properties/links/properties/self' + $ref: '#/components/schemas/ScraperTargetResponse/allOf/1/properties/links/properties/self' organization: - $ref: '#/components/schemas/Task/properties/links/properties/self' + $ref: '#/components/schemas/ScraperTargetResponse/allOf/1/properties/links/properties/self' ScraperTargetResponses: type: object properties: @@ -6461,31 +6466,33 @@ components: id: readOnly: true type: string + description: | + The resource ID that InfluxDB uses to uniquely identify the task. orgID: description: | - An [organization]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#organization) ID. - Specifies the organization that owns the task. + An organization ID. + Identifies the [organization]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#organization) that owns the task. type: string org: description: | - An [organization]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#organization) name. - Specifies the organization that owns the task. + An organization name. + Identifies the [organization]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#organization) that owns the task. type: string name: description: The name of the task. type: string + description: + description: A description of the task. + type: string ownerID: description: | - A [user]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#user) ID. - Specifies the owner of the task. + A user ID. + Identifies the [user]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#user) that owns the task. - To find a user ID, you can use the + To find a user ID, use the [`GET /api/v2/users` endpoint](#operation/GetUsers) to list users. type: string - description: - description: A description of the task. - type: string status: type: string enum: @@ -6494,22 +6501,26 @@ components: description: | `inactive` cancels scheduled runs and prevents manual runs of the task. labels: - type: array - items: - $ref: '#/paths/~1scrapers~1%7BscraperTargetID%7D~1labels/post/responses/201/content/application~1json/schema/properties/label' + $ref: '#/components/schemas/Variable/properties/labels' authorizationID: description: | An authorization ID. - Specifies the authorization used when the task communicates with the query engine. + Identifies the authorization used when the task communicates with the query engine. To find an authorization ID, use the [`GET /api/v2/authorizations` endpoint](#operation/GetAuthorizations) to list authorizations. type: string flux: - description: The Flux script that the task executes. + description: | + Flux with [task configuration options]({{% INFLUXDB_DOCS_URL %}}/process-data/task-options/) + and the script for the task to run. + + #### Related guides + + - [Task configuration options]({{% INFLUXDB_DOCS_URL %}}/process-data/task-options/) type: string - format: flux + format: Flux every: description: 'The interval ([duration literal]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#rfc3339-timestamp)) at which the task runs. `every` also determines when the task first runs, depending on the specified time.' type: string @@ -6517,6 +6528,7 @@ components: cron: description: 'A [Cron expression](https://en.wikipedia.org/wiki/Cron#Overview) that defines the schedule on which the task runs. InfluxDB uses the system time when evaluating Cron expressions.' type: string + format: cron offset: description: 'A [duration](https://docs.influxdata.com/flux/v0.x/spec/lexical-elements/#duration-literals) to delay execution of the task after the scheduled time has elapsed. `0` removes the offset.' type: string @@ -6556,20 +6568,17 @@ components: logs: /api/v2/tasks/1/logs properties: self: - type: string - format: uri - readOnly: true - description: URI of resource. + $ref: '#/components/schemas/ScraperTargetResponse/allOf/1/properties/links/properties/self' owners: - $ref: '#/components/schemas/Task/properties/links/properties/self' + $ref: '#/components/schemas/ScraperTargetResponse/allOf/1/properties/links/properties/self' members: - $ref: '#/components/schemas/Task/properties/links/properties/self' + $ref: '#/components/schemas/ScraperTargetResponse/allOf/1/properties/links/properties/self' runs: - $ref: '#/components/schemas/Task/properties/links/properties/self' + $ref: '#/components/schemas/ScraperTargetResponse/allOf/1/properties/links/properties/self' logs: - $ref: '#/components/schemas/Task/properties/links/properties/self' + $ref: '#/components/schemas/ScraperTargetResponse/allOf/1/properties/links/properties/self' labels: - $ref: '#/components/schemas/Task/properties/links/properties/self' + $ref: '#/components/schemas/ScraperTargetResponse/allOf/1/properties/links/properties/self' required: - id - name @@ -6579,19 +6588,17 @@ components: type: object properties: orgID: - description: The ID of the organization that owns this Task. - type: string + $ref: '#/components/schemas/Task/properties/orgID' org: - description: The name of the organization that owns this Task. - type: string + $ref: '#/components/schemas/Task/properties/org' + name: + $ref: '#/components/schemas/Task/properties/name' + description: + $ref: '#/components/schemas/Task/properties/description' + flux: + $ref: '#/components/schemas/Task/properties/flux' status: $ref: '#/components/schemas/Task/properties/status' - flux: - description: The Flux script to run for this task. - type: string - description: - description: An optional description of the task. - type: string required: - flux TaskUpdateRequest: @@ -6600,23 +6607,17 @@ components: status: $ref: '#/components/schemas/Task/properties/status' flux: - description: The Flux script that the task runs. - type: string + $ref: '#/components/schemas/Task/properties/flux' name: - description: Update the 'name' option in the flux script. - type: string + $ref: '#/components/schemas/Task/properties/name' every: - description: Update the 'every' option in the flux script. - type: string + $ref: '#/components/schemas/Task/properties/every' cron: - description: Update the 'cron' option in the flux script. - type: string + $ref: '#/components/schemas/Task/properties/cron' offset: - description: Update the 'offset' option in the flux script. - type: string + $ref: '#/components/schemas/Task/properties/offset' description: - description: Update the description of the task. - type: string + $ref: '#/components/schemas/Task/properties/description' responses: null examples: AuthorizationPostRequest: diff --git a/contracts/oss.json b/contracts/oss.json index f55d3efd6..891f3119b 100644 --- a/contracts/oss.json +++ b/contracts/oss.json @@ -15394,7 +15394,7 @@ } ], "requestBody": { - "description": "The task to create.", + "description": "Provide a task object in the request body.", "required": true, "content": { "application/json": { @@ -18655,6 +18655,42 @@ } } }, + "TaskCron": { + "description": "A [Cron expression](https://en.wikipedia.org/wiki/Cron#Overview) that defines the schedule on which the task runs. InfluxDB uses the system time when evaluating Cron expressions.", + "type": "string", + "format": "cron" + }, + "TaskDescription": { + "description": "A description of the task.", + "type": "string" + }, + "TaskEvery": { + "description": "The interval ([duration literal]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#rfc3339-timestamp)) at which the task runs. `every` also determines when the task first runs, depending on the specified time.", + "type": "string", + "format": "duration" + }, + "TaskFlux": { + "description": "Flux with [task configuration options]({{% INFLUXDB_DOCS_URL %}}/process-data/task-options/)\nand the script for the task to run.\n\n#### Related guides\n\n- [Task configuration options]({{% INFLUXDB_DOCS_URL %}}/process-data/task-options/)\n", + "type": "string", + "format": "Flux" + }, + "TaskName": { + "description": "The name of the task.", + "type": "string" + }, + "TaskOffset": { + "description": "A [duration](https://docs.influxdata.com/flux/v0.x/spec/lexical-elements/#duration-literals) to delay execution of the task after the scheduled time has elapsed. `0` removes the offset.", + "type": "string", + "format": "duration" + }, + "TaskOrg": { + "description": "An organization name.\nIdentifies the [organization]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#organization) that owns the task.\n", + "type": "string" + }, + "TaskOrgID": { + "description": "An organization ID.\nIdentifies the [organization]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#organization) that owns the task.\n", + "type": "string" + }, "TaskStatusType": { "type": "string", "enum": [ @@ -24209,26 +24245,23 @@ "properties": { "id": { "readOnly": true, - "type": "string" + "type": "string", + "description": "The resource ID that InfluxDB uses to uniquely identify the task.\n" }, "orgID": { - "description": "An [organization]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#organization) ID.\nSpecifies the organization that owns the task.\n", - "type": "string" + "$ref": "#/components/schemas/TaskOrgID" }, "org": { - "description": "An [organization]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#organization) name.\nSpecifies the organization that owns the task.\n", - "type": "string" + "$ref": "#/components/schemas/TaskOrg" }, "name": { - "description": "The name of the task.", - "type": "string" - }, - "ownerID": { - "description": "A [user]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#user) ID.\nSpecifies the owner of the task.\n\nTo find a user ID, you can use the\n[`GET /api/v2/users` endpoint](#operation/GetUsers) to\nlist users.\n", - "type": "string" + "$ref": "#/components/schemas/TaskName" }, "description": { - "description": "A description of the task.", + "$ref": "#/components/schemas/TaskDescription" + }, + "ownerID": { + "description": "A user ID.\nIdentifies the [user]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#user) that owns the task.\n\nTo find a user ID, use the\n[`GET /api/v2/users` endpoint](#operation/GetUsers) to\nlist users.\n", "type": "string" }, "status": { @@ -24238,27 +24271,20 @@ "$ref": "#/components/schemas/Labels" }, "authorizationID": { - "description": "An authorization ID.\nSpecifies the authorization used when the task communicates with the query engine.\n\nTo find an authorization ID, use the\n[`GET /api/v2/authorizations` endpoint](#operation/GetAuthorizations) to\nlist authorizations.\n", + "description": "An authorization ID.\nIdentifies the authorization used when the task communicates with the query engine.\n\nTo find an authorization ID, use the\n[`GET /api/v2/authorizations` endpoint](#operation/GetAuthorizations) to\nlist authorizations.\n", "type": "string" }, "flux": { - "description": "The Flux script that the task executes.", - "type": "string", - "format": "flux" + "$ref": "#/components/schemas/TaskFlux" }, "every": { - "description": "The interval ([duration literal]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#rfc3339-timestamp)) at which the task runs. `every` also determines when the task first runs, depending on the specified time.", - "type": "string", - "format": "duration" + "$ref": "#/components/schemas/TaskEvery" }, "cron": { - "description": "A [Cron expression](https://en.wikipedia.org/wiki/Cron#Overview) that defines the schedule on which the task runs. InfluxDB uses the system time when evaluating Cron expressions.", - "type": "string" + "$ref": "#/components/schemas/TaskCron" }, "offset": { - "description": "A [duration](https://docs.influxdata.com/flux/v0.x/spec/lexical-elements/#duration-literals) to delay execution of the task after the scheduled time has elapsed. `0` removes the offset.", - "type": "string", - "format": "duration" + "$ref": "#/components/schemas/TaskOffset" }, "latestCompleted": { "description": "A timestamp ([RFC3339 date/time format]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#rfc3339-timestamp)) of the latest scheduled and completed run.", @@ -24333,23 +24359,22 @@ "type": "object", "properties": { "orgID": { - "description": "The ID of the organization that owns this Task.", - "type": "string" + "$ref": "#/components/schemas/TaskOrgID" }, "org": { - "description": "The name of the organization that owns this Task.", - "type": "string" + "$ref": "#/components/schemas/TaskOrg" }, - "status": { - "$ref": "#/components/schemas/TaskStatusType" + "name": { + "$ref": "#/components/schemas/TaskName" + }, + "description": { + "$ref": "#/components/schemas/TaskDescription" }, "flux": { - "description": "The Flux script to run for this task.", - "type": "string" + "$ref": "#/components/schemas/TaskFlux" }, - "description": { - "description": "An optional description of the task.", - "type": "string" + "status": { + "$ref": "#/components/schemas/TaskStatusType" } }, "required": [ @@ -24363,28 +24388,22 @@ "$ref": "#/components/schemas/TaskStatusType" }, "flux": { - "description": "The Flux script that the task runs.", - "type": "string" + "$ref": "#/components/schemas/TaskFlux" }, "name": { - "description": "Update the 'name' option in the flux script.", - "type": "string" + "$ref": "#/components/schemas/TaskName" }, "every": { - "description": "Update the 'every' option in the flux script.", - "type": "string" + "$ref": "#/components/schemas/TaskEvery" }, "cron": { - "description": "Update the 'cron' option in the flux script.", - "type": "string" + "$ref": "#/components/schemas/TaskCron" }, "offset": { - "description": "Update the 'offset' option in the flux script.", - "type": "string" + "$ref": "#/components/schemas/TaskOffset" }, "description": { - "description": "Update the description of the task.", - "type": "string" + "$ref": "#/components/schemas/TaskDescription" } } } diff --git a/contracts/oss.yml b/contracts/oss.yml index 6b3333e77..1990fef59 100644 --- a/contracts/oss.yml +++ b/contracts/oss.yml @@ -12165,7 +12165,7 @@ paths: parameters: - $ref: '#/components/parameters/TraceSpan' requestBody: - description: The task to create. + description: Provide a task object in the request body. required: true content: application/json: @@ -14665,6 +14665,44 @@ components: Default is the server _now_ time. type: string format: date-time + TaskCron: + description: 'A [Cron expression](https://en.wikipedia.org/wiki/Cron#Overview) that defines the schedule on which the task runs. InfluxDB uses the system time when evaluating Cron expressions.' + type: string + format: cron + TaskDescription: + description: A description of the task. + type: string + TaskEvery: + description: 'The interval ([duration literal](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#rfc3339-timestamp)) at which the task runs. `every` also determines when the task first runs, depending on the specified time.' + type: string + format: duration + TaskFlux: + description: | + Flux with [task configuration options](https://docs.influxdata.com/influxdb/v2.3/process-data/task-options/) + and the script for the task to run. + + #### Related guides + + - [Task configuration options](https://docs.influxdata.com/influxdb/v2.3/process-data/task-options/) + type: string + format: Flux + TaskName: + description: The name of the task. + type: string + TaskOffset: + description: 'A [duration](https://docs.influxdata.com/flux/v0.x/spec/lexical-elements/#duration-literals) to delay execution of the task after the scheduled time has elapsed. `0` removes the offset.' + type: string + format: duration + TaskOrg: + description: | + An organization name. + Identifies the [organization](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#organization) that owns the task. + type: string + TaskOrgID: + description: | + An organization ID. + Identifies the [organization](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#organization) that owns the task. + type: string TaskStatusType: type: string enum: @@ -18494,31 +18532,25 @@ components: id: readOnly: true type: string - orgID: description: | - An [organization](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#organization) ID. - Specifies the organization that owns the task. - type: string + The resource ID that InfluxDB uses to uniquely identify the task. + orgID: + $ref: '#/components/schemas/TaskOrgID' org: - description: | - An [organization](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#organization) name. - Specifies the organization that owns the task. - type: string + $ref: '#/components/schemas/TaskOrg' name: - description: The name of the task. - type: string + $ref: '#/components/schemas/TaskName' + description: + $ref: '#/components/schemas/TaskDescription' ownerID: description: | - A [user](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#user) ID. - Specifies the owner of the task. + A user ID. + Identifies the [user](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#user) that owns the task. - To find a user ID, you can use the + To find a user ID, use the [`GET /api/v2/users` endpoint](#operation/GetUsers) to list users. type: string - description: - description: A description of the task. - type: string status: $ref: '#/components/schemas/TaskStatusType' labels: @@ -18526,27 +18558,20 @@ components: authorizationID: description: | An authorization ID. - Specifies the authorization used when the task communicates with the query engine. + Identifies the authorization used when the task communicates with the query engine. To find an authorization ID, use the [`GET /api/v2/authorizations` endpoint](#operation/GetAuthorizations) to list authorizations. type: string flux: - description: The Flux script that the task executes. - type: string - format: flux + $ref: '#/components/schemas/TaskFlux' every: - description: 'The interval ([duration literal](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#rfc3339-timestamp)) at which the task runs. `every` also determines when the task first runs, depending on the specified time.' - type: string - format: duration + $ref: '#/components/schemas/TaskEvery' cron: - description: 'A [Cron expression](https://en.wikipedia.org/wiki/Cron#Overview) that defines the schedule on which the task runs. InfluxDB uses the system time when evaluating Cron expressions.' - type: string + $ref: '#/components/schemas/TaskCron' offset: - description: 'A [duration](https://docs.influxdata.com/flux/v0.x/spec/lexical-elements/#duration-literals) to delay execution of the task after the scheduled time has elapsed. `0` removes the offset.' - type: string - format: duration + $ref: '#/components/schemas/TaskOffset' latestCompleted: description: 'A timestamp ([RFC3339 date/time format](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#rfc3339-timestamp)) of the latest scheduled and completed run.' type: string @@ -18602,19 +18627,17 @@ components: type: object properties: orgID: - description: The ID of the organization that owns this Task. - type: string + $ref: '#/components/schemas/TaskOrgID' org: - description: The name of the organization that owns this Task. - type: string + $ref: '#/components/schemas/TaskOrg' + name: + $ref: '#/components/schemas/TaskName' + description: + $ref: '#/components/schemas/TaskDescription' + flux: + $ref: '#/components/schemas/TaskFlux' status: $ref: '#/components/schemas/TaskStatusType' - flux: - description: The Flux script to run for this task. - type: string - description: - description: An optional description of the task. - type: string required: - flux TaskUpdateRequest: @@ -18623,23 +18646,17 @@ components: status: $ref: '#/components/schemas/TaskStatusType' flux: - description: The Flux script that the task runs. - type: string + $ref: '#/components/schemas/TaskFlux' name: - description: Update the 'name' option in the flux script. - type: string + $ref: '#/components/schemas/TaskName' every: - description: Update the 'every' option in the flux script. - type: string + $ref: '#/components/schemas/TaskEvery' cron: - description: Update the 'cron' option in the flux script. - type: string + $ref: '#/components/schemas/TaskCron' offset: - description: Update the 'offset' option in the flux script. - type: string + $ref: '#/components/schemas/TaskOffset' description: - description: Update the description of the task. - type: string + $ref: '#/components/schemas/TaskDescription' responses: AuthorizationError: description: | diff --git a/contracts/ref/cloud.yml b/contracts/ref/cloud.yml index edd4c582f..ec02bfbcc 100644 --- a/contracts/ref/cloud.yml +++ b/contracts/ref/cloud.yml @@ -4775,7 +4775,7 @@ components: authorizationID: description: | An authorization ID. - Specifies the authorization used when the task communicates with the query engine. + Identifies the authorization used when the task communicates with the query engine. To find an authorization ID, use the [`GET /api/v2/authorizations` endpoint](#operation/GetAuthorizations) to @@ -4786,28 +4786,16 @@ components: readOnly: true type: string cron: - description: A [Cron expression](https://en.wikipedia.org/wiki/Cron#Overview) - that defines the schedule on which the task runs. InfluxDB uses the system - time when evaluating Cron expressions. - type: string + $ref: '#/components/schemas/TaskCron' description: - description: A description of the task. - type: string + $ref: '#/components/schemas/TaskDescription' every: - description: The interval ([duration literal](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#rfc3339-timestamp)) - at which the task runs. `every` also determines when the task first runs, - depending on the specified time. - format: duration - type: string + $ref: '#/components/schemas/TaskEvery' flux: - description: | - The Flux script that the task executes. - - #### Limitations - - If you use the `flux` property, you can't use the `scriptID` and `scriptParameters` properties. - format: flux - type: string + $ref: '#/components/schemas/TaskFlux' id: + description: | + The resource ID that InfluxDB uses to uniquely identify the task. readOnly: true type: string labels: @@ -4852,58 +4840,26 @@ components: readOnly: true type: object name: - description: The name of the task. - type: string + $ref: '#/components/schemas/TaskName' offset: - description: A [duration](https://docs.influxdata.com/flux/v0.x/spec/lexical-elements/#duration-literals) - to delay execution of the task after the scheduled time has elapsed. `0` - removes the offset. - format: duration - type: string + $ref: '#/components/schemas/TaskOffset' org: - description: | - An [organization](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#organization) name. - Specifies the organization that owns the task. - type: string + $ref: '#/components/schemas/TaskOrg' orgID: - description: | - An [organization](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#organization) ID. - Specifies the organization that owns the task. - type: string + $ref: '#/components/schemas/TaskOrgID' ownerID: description: | - A [user](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#user) ID. - Specifies the owner of the task. + A user ID. + Identifies the [user](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#user) that owns the task. - To find a user ID, you can use the + To find a user ID, use the [`GET /api/v2/users` endpoint](#operation/GetUsers) to list users. type: string scriptID: - description: | - A script ID. - Specifies the [invokable script](#tag/Invokable-Scripts) that the task executes. - - #### Limitations - - - If you use the `scriptID` property, you can't use the `flux` property. - - #### Related guides - - - [Create a task that references a script](https://docs.influxdata.com/influxdb/cloud/process-data/manage-tasks/create-task/#create-a-task-that-references-a-script) - type: string + $ref: '#/components/schemas/TaskScriptID' scriptParameters: - description: | - Key-value pairs for `params` in the script. - Defines the invocation parameter values passed to the script specified by `scriptID`. - When running the task, InfluxDB executes the script with the parameters - you provide. - - #### Limitations - - - To use `scriptParameters`, you must provide a `scriptID`. - - If you use the `scriptID` and `scriptParameters` properties, you can't use the `flux` property. - type: object + $ref: '#/components/schemas/TaskScriptParameters' status: $ref: '#/components/schemas/TaskStatusType' updatedAt: @@ -4918,60 +4874,97 @@ components: TaskCreateRequest: properties: cron: - description: A [Cron expression](https://en.wikipedia.org/wiki/Cron#Overview) - that defines the schedule on which the task runs. InfluxDB bases cron - runs on the system time. - type: string + $ref: '#/components/schemas/TaskCron' description: - description: The description of the task. - type: string + $ref: '#/components/schemas/TaskDescription' every: - description: | - The interval ([duration literal](https://docs.influxdata.com/flux/v0.x/spec/lexical-elements/#duration-literals))) at which the task runs. - `every` also determines when the task first runs, depending on the specified time. - type: string + $ref: '#/components/schemas/TaskEvery' flux: - description: | - The Flux script that the task runs. - - #### Limitations - - - If you use the `flux` property, you can't use the `scriptID` and `scriptParameters` properties. - type: string + $ref: '#/components/schemas/TaskFlux' name: - description: The name of the task - type: string + $ref: '#/components/schemas/TaskName' offset: - description: A [duration](https://docs.influxdata.com/flux/v0.x/spec/lexical-elements/#duration-literals) - to delay execution of the task after the scheduled time has elapsed. `0` - removes the offset. - format: duration - type: string + $ref: '#/components/schemas/TaskOffset' org: - description: The name of the organization that owns the task. - type: string + $ref: '#/components/schemas/TaskOrg' orgID: - description: The ID of the organization that owns the task. - type: string + $ref: '#/components/schemas/TaskOrgID' scriptID: - description: | - The ID of the script that the task runs. + $ref: '#/components/schemas/TaskScriptID' + scriptParameters: + $ref: '#/components/schemas/TaskScriptParameters' + status: + $ref: '#/components/schemas/TaskStatusType' + type: object + TaskCron: + description: A [Cron expression](https://en.wikipedia.org/wiki/Cron#Overview) + that defines the schedule on which the task runs. InfluxDB uses the system + time when evaluating Cron expressions. + format: cron + type: string + TaskDescription: + description: A description of the task. + type: string + TaskEvery: + description: The interval ([duration literal](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#rfc3339-timestamp)) + at which the task runs. `every` also determines when the task first runs, + depending on the specified time. + format: duration + type: string + TaskFlux: + description: | + Flux with [task configuration options](https://docs.influxdata.com/influxdb/cloud/process-data/task-options/) + and the script for the task to run. - #### Limitations + #### Related guides - - If you use the `scriptID` property, you can't use the `flux` property. - type: string - scriptParameters: - description: | - The parameter key-value pairs passed to the script (referenced by `scriptID`) during the task run. + - [Task configuration options](https://docs.influxdata.com/influxdb/cloud/process-data/task-options/) + format: Flux + type: string + TaskName: + description: The name of the task. + type: string + TaskOffset: + description: A [duration](https://docs.influxdata.com/flux/v0.x/spec/lexical-elements/#duration-literals) + to delay execution of the task after the scheduled time has elapsed. `0` removes + the offset. + format: duration + type: string + TaskOrg: + description: | + An organization name. + Identifies the [organization](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#organization) that owns the task. + type: string + TaskOrgID: + description: | + An organization ID. + Identifies the [organization](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#organization) that owns the task. + type: string + TaskScriptID: + description: | + A script ID. + Identifies the [invokable script](#tag/Invokable-Scripts) that the task runs. - #### Limitations + #### Related guides - - `scriptParameters` requires `scriptID`. - - If you use the `scriptID` and `scriptParameters` properties, you can't use the `flux` property. - type: object - status: - $ref: '#/components/schemas/TaskStatusType' + - [Create a task that references a script](https://docs.influxdata.com/influxdb/cloud/process-data/manage-tasks/create-task/#create-a-task-that-references-a-script). + type: string + TaskScriptParameters: + description: | + Key-value pairs for `params` in the script. + Defines the invocation parameter values passed to the [invokable script](#tag/Invokable-Scripts) specified + by the `scriptID` property. + When running the task, InfluxDB executes the script with the parameters + you provide. + + #### Limitations + + - To use the `scriptParameters` property, you must also set the `scriptID` property + for the task. + + #### Related guides + + - [Create a task that references a script](https://docs.influxdata.com/influxdb/cloud/process-data/manage-tasks/create-task/#create-a-task-that-references-a-script). type: object TaskStatusType: description: | @@ -4983,29 +4976,21 @@ components: TaskUpdateRequest: properties: cron: - description: Update the 'cron' option in the flux script. - type: string + $ref: '#/components/schemas/TaskCron' description: - description: Update the description of the task. - type: string + $ref: '#/components/schemas/TaskDescription' every: - description: Update the 'every' option in the flux script. - type: string + $ref: '#/components/schemas/TaskEvery' flux: - description: Update the Flux script that the task runs. - type: string + $ref: '#/components/schemas/TaskFlux' name: - description: Update the 'name' option in the flux script. - type: string + $ref: '#/components/schemas/TaskName' offset: - description: Update the 'offset' option in the flux script. - type: string + $ref: '#/components/schemas/TaskOffset' scriptID: - description: Update the 'scriptID' of the task. - type: string + $ref: '#/components/schemas/TaskScriptID' scriptParameters: - description: Update the 'scriptParameters' of the task. - type: object + $ref: '#/components/schemas/TaskScriptParameters' status: $ref: '#/components/schemas/TaskStatusType' type: object @@ -14994,7 +14979,7 @@ paths: application/json: schema: $ref: '#/components/schemas/TaskCreateRequest' - description: The task to create + description: Provide a task object in the request body. required: true responses: "201": diff --git a/contracts/ref/oss.yml b/contracts/ref/oss.yml index 5ed3ab231..fdf8eeb7f 100644 --- a/contracts/ref/oss.yml +++ b/contracts/ref/oss.yml @@ -4883,7 +4883,7 @@ components: authorizationID: description: | An authorization ID. - Specifies the authorization used when the task communicates with the query engine. + Identifies the authorization used when the task communicates with the query engine. To find an authorization ID, use the [`GET /api/v2/authorizations` endpoint](#operation/GetAuthorizations) to @@ -4894,24 +4894,16 @@ components: readOnly: true type: string cron: - description: A [Cron expression](https://en.wikipedia.org/wiki/Cron#Overview) - that defines the schedule on which the task runs. InfluxDB uses the system - time when evaluating Cron expressions. - type: string + $ref: '#/components/schemas/TaskCron' description: - description: A description of the task. - type: string + $ref: '#/components/schemas/TaskDescription' every: - description: The interval ([duration literal](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#rfc3339-timestamp)) - at which the task runs. `every` also determines when the task first runs, - depending on the specified time. - format: duration - type: string + $ref: '#/components/schemas/TaskEvery' flux: - description: The Flux script that the task executes. - format: flux - type: string + $ref: '#/components/schemas/TaskFlux' id: + description: | + The resource ID that InfluxDB uses to uniquely identify the task. readOnly: true type: string labels: @@ -4956,30 +4948,19 @@ components: readOnly: true type: object name: - description: The name of the task. - type: string + $ref: '#/components/schemas/TaskName' offset: - description: A [duration](https://docs.influxdata.com/flux/v0.x/spec/lexical-elements/#duration-literals) - to delay execution of the task after the scheduled time has elapsed. `0` - removes the offset. - format: duration - type: string + $ref: '#/components/schemas/TaskOffset' org: - description: | - An [organization](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#organization) name. - Specifies the organization that owns the task. - type: string + $ref: '#/components/schemas/TaskOrg' orgID: - description: | - An [organization](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#organization) ID. - Specifies the organization that owns the task. - type: string + $ref: '#/components/schemas/TaskOrgID' ownerID: description: | - A [user](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#user) ID. - Specifies the owner of the task. + A user ID. + Identifies the [user](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#user) that owns the task. - To find a user ID, you can use the + To find a user ID, use the [`GET /api/v2/users` endpoint](#operation/GetUsers) to list users. type: string @@ -4998,22 +4979,64 @@ components: TaskCreateRequest: properties: description: - description: An optional description of the task. - type: string + $ref: '#/components/schemas/TaskDescription' flux: - description: The Flux script to run for this task. - type: string + $ref: '#/components/schemas/TaskFlux' + name: + $ref: '#/components/schemas/TaskName' org: - description: The name of the organization that owns this Task. - type: string + $ref: '#/components/schemas/TaskOrg' orgID: - description: The ID of the organization that owns this Task. - type: string + $ref: '#/components/schemas/TaskOrgID' status: $ref: '#/components/schemas/TaskStatusType' required: - flux type: object + TaskCron: + description: A [Cron expression](https://en.wikipedia.org/wiki/Cron#Overview) + that defines the schedule on which the task runs. InfluxDB uses the system + time when evaluating Cron expressions. + format: cron + type: string + TaskDescription: + description: A description of the task. + type: string + TaskEvery: + description: The interval ([duration literal](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#rfc3339-timestamp)) + at which the task runs. `every` also determines when the task first runs, + depending on the specified time. + format: duration + type: string + TaskFlux: + description: | + Flux with [task configuration options](https://docs.influxdata.com/influxdb/v2.3/process-data/task-options/) + and the script for the task to run. + + #### Related guides + + - [Task configuration options](https://docs.influxdata.com/influxdb/v2.3/process-data/task-options/) + format: Flux + type: string + TaskName: + description: The name of the task. + type: string + TaskOffset: + description: A [duration](https://docs.influxdata.com/flux/v0.x/spec/lexical-elements/#duration-literals) + to delay execution of the task after the scheduled time has elapsed. `0` removes + the offset. + format: duration + type: string + TaskOrg: + description: | + An organization name. + Identifies the [organization](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#organization) that owns the task. + type: string + TaskOrgID: + description: | + An organization ID. + Identifies the [organization](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#organization) that owns the task. + type: string TaskStatusType: description: | `inactive` cancels scheduled runs and prevents manual runs of the task. @@ -5024,23 +5047,17 @@ components: TaskUpdateRequest: properties: cron: - description: Update the 'cron' option in the flux script. - type: string + $ref: '#/components/schemas/TaskCron' description: - description: Update the description of the task. - type: string + $ref: '#/components/schemas/TaskDescription' every: - description: Update the 'every' option in the flux script. - type: string + $ref: '#/components/schemas/TaskEvery' flux: - description: The Flux script that the task runs. - type: string + $ref: '#/components/schemas/TaskFlux' name: - description: Update the 'name' option in the flux script. - type: string + $ref: '#/components/schemas/TaskName' offset: - description: Update the 'offset' option in the flux script. - type: string + $ref: '#/components/schemas/TaskOffset' status: $ref: '#/components/schemas/TaskStatusType' type: object @@ -16032,7 +16049,7 @@ paths: application/json: schema: $ref: '#/components/schemas/TaskCreateRequest' - description: The task to create. + description: Provide a task object in the request body. required: true responses: "201": diff --git a/src/cloud.yml b/src/cloud.yml index 2ff1cf7de..f88afcbb2 100644 --- a/src/cloud.yml +++ b/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: diff --git a/src/cloud/paths/tasks.yml b/src/cloud/paths/tasks.yml index 3d305c64f..a28b7b40c 100644 --- a/src/cloud/paths/tasks.yml +++ b/src/cloud/paths/tasks.yml @@ -207,7 +207,7 @@ post: parameters: - $ref: "../../common/parameters/TraceSpan.yml" requestBody: - description: The task to create + description: Provide a task object in the request body. required: true content: application/json: diff --git a/src/cloud/schemas/Task.yml b/src/cloud/schemas/Task.yml index 408544852..d8624ed17 100644 --- a/src/cloud/schemas/Task.yml +++ b/src/cloud/schemas/Task.yml @@ -1,142 +1,45 @@ type: object properties: id: - readOnly: true - type: string + $ref: ../../common/schemas/TaskProperties.yml#/id orgID: - description: | - An [organization]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#organization) ID. - Specifies the organization that owns the task. - type: string + $ref: ../../common/schemas/TaskProperties.yml#/orgID org: - description: | - An [organization]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#organization) name. - Specifies the organization that owns the task. - type: string + $ref: ../../common/schemas/TaskProperties.yml#/org name: - description: The name of the task. - type: string - ownerID: - description: | - A [user]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#user) ID. - Specifies the owner of the task. - - To find a user ID, you can use the - [`GET /api/v2/users` endpoint](#operation/GetUsers) to - list users. - type: string + $ref: ../../common/schemas/TaskProperties.yml#/name description: - description: A description of the task. - type: string + $ref: ../../common/schemas/TaskProperties.yml#/description + ownerID: + $ref: ../../common/schemas/TaskProperties.yml#/ownerID status: - $ref: "../../common/schemas/TaskStatusType.yml" + $ref: ../../common/schemas/TaskProperties.yml#/status labels: - $ref: "../../common/schemas/Labels.yml" + $ref: ../../common/schemas/TaskProperties.yml#/labels authorizationID: - description: | - An authorization ID. - Specifies the authorization used when the task communicates with the query engine. - - To find an authorization ID, use the - [`GET /api/v2/authorizations` endpoint](#operation/GetAuthorizations) to - list authorizations. - type: string + $ref: ../../common/schemas/TaskProperties.yml#/authorizationID flux: - description: | - The Flux script that the task executes. - - #### Limitations - - If you use the `flux` property, you can't use the `scriptID` and `scriptParameters` properties. - type: string - format: flux + $ref: ../../common/schemas/TaskProperties.yml#/flux every: - description: >- - The interval ([duration literal]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#rfc3339-timestamp)) at which the task runs. - `every` also determines when the task first runs, depending on the specified time. - type: string - format: duration + $ref: ../../common/schemas/TaskProperties.yml#/every cron: - description: >- - A [Cron expression](https://en.wikipedia.org/wiki/Cron#Overview) that defines the schedule on which the task runs. - InfluxDB uses the system time when evaluating Cron expressions. - type: string + $ref: ../../common/schemas/TaskProperties.yml#/cron offset: - description: >- - A [duration](https://docs.influxdata.com/flux/v0.x/spec/lexical-elements/#duration-literals) to delay execution of the task after the scheduled time has elapsed. - `0` removes the offset. - type: string - format: duration + $ref: ../../common/schemas/TaskProperties.yml#/offset latestCompleted: - description: >- - A timestamp ([RFC3339 date/time format]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#rfc3339-timestamp)) of the latest scheduled and completed run. - type: string - format: date-time - readOnly: true + $ref: ../../common/schemas/TaskProperties.yml#/latestCompleted lastRunStatus: - readOnly: true - type: string - enum: - - failed - - success - - canceled + $ref: ../../common/schemas/TaskProperties.yml#/lastRunStatus lastRunError: - readOnly: true - type: string + $ref: ../../common/schemas/TaskProperties.yml#/lastRunError createdAt: - type: string - format: date-time - readOnly: true + $ref: ../../common/schemas/TaskProperties.yml#/createdAt updatedAt: - type: string - format: date-time - readOnly: true + $ref: ../../common/schemas/TaskProperties.yml#/updatedAt links: - type: object - readOnly: true - example: - self: "/api/v2/tasks/1" - owners: "/api/v2/tasks/1/owners" - members: "/api/v2/tasks/1/members" - labels: "/api/v2/tasks/1/labels" - runs: "/api/v2/tasks/1/runs" - logs: "/api/v2/tasks/1/logs" - properties: - self: - $ref: "../../common/schemas/Link.yml" - owners: - $ref: "../../common/schemas/Link.yml" - members: - $ref: "../../common/schemas/Link.yml" - runs: - $ref: "../../common/schemas/Link.yml" - logs: - $ref: "../../common/schemas/Link.yml" - labels: - $ref: "../../common/schemas/Link.yml" + $ref: ../../common/schemas/TaskProperties.yml#/links scriptID: - description: | - A script ID. - Specifies the [invokable script](#tag/Invokable-Scripts) that the task executes. - - #### Limitations - - - If you use the `scriptID` property, you can't use the `flux` property. - - #### Related guides - - - [Create a task that references a script]({{% INFLUXDB_DOCS_URL %}}/process-data/manage-tasks/create-task/#create-a-task-that-references-a-script) - type: string + $ref: ./TaskProperties.yml#/scriptID scriptParameters: - description: | - Key-value pairs for `params` in the script. - Defines the invocation parameter values passed to the script specified by `scriptID`. - When running the task, InfluxDB executes the script with the parameters - you provide. - - #### Limitations - - - To use `scriptParameters`, you must provide a `scriptID`. - - If you use the `scriptID` and `scriptParameters` properties, you can't use the `flux` property. - type: object - + $ref: ./TaskProperties.yml#/scriptParameters required: [id, name, orgID] diff --git a/src/cloud/schemas/TaskCreateRequest.yml b/src/cloud/schemas/TaskCreateRequest.yml index 4fcaead8e..258ed396d 100644 --- a/src/cloud/schemas/TaskCreateRequest.yml +++ b/src/cloud/schemas/TaskCreateRequest.yml @@ -1,57 +1,24 @@ - type: object - properties: - orgID: - description: The ID of the organization that owns the task. - type: string - org: - description: The name of the organization that owns the task. - type: string - status: - $ref: "../../common/schemas/TaskStatusType.yml" - flux: - description: | - The Flux script that the task runs. - - #### Limitations - - - If you use the `flux` property, you can't use the `scriptID` and `scriptParameters` properties. - type: string - description: - description: The description of the task. - type: string - scriptID: - description: | - The ID of the script that the task runs. - - #### Limitations - - - If you use the `scriptID` property, you can't use the `flux` property. - type: string - scriptParameters: - description: | - The parameter key-value pairs passed to the script (referenced by `scriptID`) during the task run. - - #### Limitations - - - `scriptParameters` requires `scriptID`. - - If you use the `scriptID` and `scriptParameters` properties, you can't use the `flux` property. - type: object - name: - description: The name of the task - type: string - every: - description: | - The interval ([duration literal](https://docs.influxdata.com/flux/v0.x/spec/lexical-elements/#duration-literals))) at which the task runs. - `every` also determines when the task first runs, depending on the specified time. - type: string - cron: - description: >- - A [Cron expression](https://en.wikipedia.org/wiki/Cron#Overview) that defines the schedule on which the task runs. - InfluxDB bases cron runs on the system time. - type: string - offset: - description: >- - A [duration](https://docs.influxdata.com/flux/v0.x/spec/lexical-elements/#duration-literals) to delay execution of the task after the scheduled time has elapsed. - `0` removes the offset. - type: string - format: duration +type: object +properties: + orgID: + $ref: ../../common/schemas/TaskProperties.yml#/orgID + org: + $ref: ../../common/schemas/TaskProperties.yml#/org + name: + $ref: ../../common/schemas/TaskProperties.yml#/name + description: + $ref: ../../common/schemas/TaskProperties.yml#/description + every: + $ref: ../../common/schemas/TaskProperties.yml#/every + cron: + $ref: ../../common/schemas/TaskProperties.yml#/cron + offset: + $ref: ../../common/schemas/TaskProperties.yml#/offset + status: + $ref: ../../common/schemas/TaskProperties.yml#/status + flux: + $ref: ../../common/schemas/TaskProperties.yml#/flux + scriptID: + $ref: ./TaskProperties.yml#/scriptID + scriptParameters: + $ref: ./TaskProperties.yml#/scriptParameters \ No newline at end of file diff --git a/src/cloud/schemas/TaskProperties.yml b/src/cloud/schemas/TaskProperties.yml new file mode 100644 index 000000000..488cc2da3 --- /dev/null +++ b/src/cloud/schemas/TaskProperties.yml @@ -0,0 +1,26 @@ +scriptID: + description: | + A script ID. + Identifies the [invokable script](#tag/Invokable-Scripts) that the task runs. + + #### Related guides + + - [Create a task that references a script]({{% INFLUXDB_DOCS_URL %}}/process-data/manage-tasks/create-task/#create-a-task-that-references-a-script). + type: string +scriptParameters: + description: | + Key-value pairs for `params` in the script. + Defines the invocation parameter values passed to the [invokable script](#tag/Invokable-Scripts) specified + by the `scriptID` property. + When running the task, InfluxDB executes the script with the parameters + you provide. + + #### Limitations + + - To use the `scriptParameters` property, you must also set the `scriptID` property + for the task. + + #### Related guides + + - [Create a task that references a script]({{% INFLUXDB_DOCS_URL %}}/process-data/manage-tasks/create-task/#create-a-task-that-references-a-script). + type: object diff --git a/src/cloud/schemas/TaskUpdateRequest.yml b/src/cloud/schemas/TaskUpdateRequest.yml index 3b1b82ee9..adcd26cf7 100644 --- a/src/cloud/schemas/TaskUpdateRequest.yml +++ b/src/cloud/schemas/TaskUpdateRequest.yml @@ -1,28 +1,20 @@ type: object properties: status: - $ref: "../../common/schemas/TaskStatusType.yml" - flux: - description: Update the Flux script that the task runs. - type: string + $ref: ../../common/schemas/TaskProperties.yml#/status name: - description: Update the 'name' option in the flux script. - type: string + $ref: ../../common/schemas/TaskProperties.yml#/name + description: + $ref: ../../common/schemas/TaskProperties.yml#/description every: - description: Update the 'every' option in the flux script. - type: string + $ref: ../../common/schemas/TaskProperties.yml#/every cron: - description: Update the 'cron' option in the flux script. - type: string + $ref: ../../common/schemas/TaskProperties.yml#/cron offset: - description: Update the 'offset' option in the flux script. - type: string - description: - description: Update the description of the task. - type: string + $ref: ../../common/schemas/TaskProperties.yml#/offset + flux: + $ref: ../../common/schemas/TaskProperties.yml#/flux scriptID: - description: Update the 'scriptID' of the task. - type: string + $ref: ./TaskProperties.yml#/scriptID scriptParameters: - description: Update the 'scriptParameters' of the task. - type: object + $ref: ./TaskProperties.yml#/scriptParameters diff --git a/src/common/_schemas.yml b/src/common/_schemas.yml index a532d32f7..bbabecfe2 100644 --- a/src/common/_schemas.yml +++ b/src/common/_schemas.yml @@ -160,6 +160,22 @@ $ref: "./common/schemas/Run.yml" RunManually: $ref: "./common/schemas/RunManually.yml" + TaskCron: + $ref: "./common/schemas/TaskProperties.yml#/cron" + TaskDescription: + $ref: "./common/schemas/TaskProperties.yml#/description" + TaskEvery: + $ref: "./common/schemas/TaskProperties.yml#/every" + TaskFlux: + $ref: "./common/schemas/TaskProperties.yml#/flux" + TaskName: + $ref: "./common/schemas/TaskProperties.yml#/name" + TaskOffset: + $ref: "./common/schemas/TaskProperties.yml#/offset" + TaskOrg: + $ref: "./common/schemas/TaskProperties.yml#/org" + TaskOrgID: + $ref: "./common/schemas/TaskProperties.yml#/orgID" TaskStatusType: $ref: "./common/schemas/TaskStatusType.yml" UserResponse: diff --git a/src/common/paths/tasks.yml b/src/common/paths/tasks.yml index f70358235..e873be96f 100644 --- a/src/common/paths/tasks.yml +++ b/src/common/paths/tasks.yml @@ -132,7 +132,7 @@ post: parameters: - $ref: "../parameters/TraceSpan.yml" requestBody: - description: The task to create. + description: Provide a task object in the request body. required: true content: application/json: diff --git a/src/common/schemas/Task.yml b/src/common/schemas/Task.yml index e338d771d..019b28683 100644 --- a/src/common/schemas/Task.yml +++ b/src/common/schemas/Task.yml @@ -1,113 +1,41 @@ type: object properties: id: - readOnly: true - type: string + $ref: ./TaskProperties.yml#/id orgID: - description: | - An [organization]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#organization) ID. - Specifies the organization that owns the task. - type: string + $ref: ./TaskProperties.yml#/orgID org: - description: | - An [organization]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#organization) name. - Specifies the organization that owns the task. - type: string + $ref: ./TaskProperties.yml#/org name: - description: The name of the task. - type: string - ownerID: - description: | - A [user]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#user) ID. - Specifies the owner of the task. - - To find a user ID, you can use the - [`GET /api/v2/users` endpoint](#operation/GetUsers) to - list users. - type: string + $ref: ./TaskProperties.yml#/name description: - description: A description of the task. - type: string + $ref: ./TaskProperties.yml#/description + ownerID: + $ref: ./TaskProperties.yml#/ownerID status: - $ref: "./TaskStatusType.yml" + $ref: ./TaskProperties.yml#/status labels: - $ref: "./Labels.yml" + $ref: ./TaskProperties.yml#/labels authorizationID: - description: | - An authorization ID. - Specifies the authorization used when the task communicates with the query engine. - - To find an authorization ID, use the - [`GET /api/v2/authorizations` endpoint](#operation/GetAuthorizations) to - list authorizations. - type: string + $ref: ./TaskProperties.yml#/authorizationID flux: - description: The Flux script that the task executes. - type: string - format: flux + $ref: ./TaskProperties.yml#/flux every: - description: >- - The interval ([duration literal]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#rfc3339-timestamp)) at which the task runs. - `every` also determines when the task first runs, depending on the specified time. - type: string - format: duration + $ref: ./TaskProperties.yml#/every cron: - description: >- - A [Cron expression](https://en.wikipedia.org/wiki/Cron#Overview) that defines the schedule on which the task runs. - InfluxDB uses the system time when evaluating Cron expressions. - type: string + $ref: ./TaskProperties.yml#/cron offset: - description: >- - A [duration](https://docs.influxdata.com/flux/v0.x/spec/lexical-elements/#duration-literals) to delay execution of the task after the scheduled time has elapsed. - `0` removes the offset. - type: string - format: duration + $ref: ./TaskProperties.yml#/offset latestCompleted: - description: >- - A timestamp ([RFC3339 date/time format]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#rfc3339-timestamp)) of the latest scheduled and completed run. - type: string - format: date-time - readOnly: true + $ref: ./TaskProperties.yml#/latestCompleted lastRunStatus: - readOnly: true - type: string - enum: - - failed - - success - - canceled + $ref: ./TaskProperties.yml#/lastRunStatus lastRunError: - readOnly: true - type: string + $ref: ./TaskProperties.yml#/lastRunError createdAt: - type: string - format: date-time - readOnly: true + $ref: ./TaskProperties.yml#/createdAt updatedAt: - type: string - format: date-time - readOnly: true + $ref: ./TaskProperties.yml#/updatedAt links: - type: object - readOnly: true - example: - self: "/api/v2/tasks/1" - owners: "/api/v2/tasks/1/owners" - members: "/api/v2/tasks/1/members" - labels: "/api/v2/tasks/1/labels" - runs: "/api/v2/tasks/1/runs" - logs: "/api/v2/tasks/1/logs" - properties: - self: - $ref: "./Link.yml" - owners: - $ref: "./Link.yml" - members: - $ref: "./Link.yml" - runs: - $ref: "./Link.yml" - logs: - $ref: "./Link.yml" - labels: - $ref: "./Link.yml" - + $ref: ./TaskProperties.yml#/links required: [id, name, orgID, flux] diff --git a/src/common/schemas/TaskCreateRequest.yml b/src/common/schemas/TaskCreateRequest.yml index 9758cca91..8034983e4 100644 --- a/src/common/schemas/TaskCreateRequest.yml +++ b/src/common/schemas/TaskCreateRequest.yml @@ -1,18 +1,16 @@ type: object properties: orgID: - description: The ID of the organization that owns this Task. - type: string + $ref: ./TaskProperties.yml#/orgID org: - description: The name of the organization that owns this Task. - type: string - status: - $ref: "./TaskStatusType.yml" - flux: - description: The Flux script to run for this task. - type: string + $ref: ./TaskProperties.yml#/org + name: + $ref: ./TaskProperties.yml#/name description: - description: An optional description of the task. - type: string - - required: [flux] + $ref: ./TaskProperties.yml#/description + flux: + $ref: ./TaskProperties.yml#/flux + status: + $ref: ./TaskProperties.yml#/status + required: + - flux diff --git a/src/common/schemas/TaskProperties.yml b/src/common/schemas/TaskProperties.yml new file mode 100644 index 000000000..4f64c13fd --- /dev/null +++ b/src/common/schemas/TaskProperties.yml @@ -0,0 +1,118 @@ +id: + readOnly: true + type: string + description: | + The resource ID that InfluxDB uses to uniquely identify the task. +orgID: + description: | + An organization ID. + Identifies the [organization]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#organization) that owns the task. + type: string +org: + description: | + An organization name. + Identifies the [organization]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#organization) that owns the task. + type: string +name: + description: The name of the task. + type: string +description: + description: A description of the task. + type: string +ownerID: + description: | + A user ID. + Identifies the [user]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#user) that owns the task. + + To find a user ID, use the + [`GET /api/v2/users` endpoint](#operation/GetUsers) to + list users. + type: string +status: + $ref: "./TaskStatusType.yml" +labels: + $ref: "./Labels.yml" +authorizationID: + description: | + An authorization ID. + Identifies the authorization used when the task communicates with the query engine. + + To find an authorization ID, use the + [`GET /api/v2/authorizations` endpoint](#operation/GetAuthorizations) to + list authorizations. + type: string +flux: + description: | + Flux with [task configuration options]({{% INFLUXDB_DOCS_URL %}}/process-data/task-options/) + and the script for the task to run. + + #### Related guides + + - [Task configuration options]({{% INFLUXDB_DOCS_URL %}}/process-data/task-options/) + type: string + format: Flux +every: + description: >- + The interval ([duration literal]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#rfc3339-timestamp)) at which the task runs. + `every` also determines when the task first runs, depending on the specified time. + type: string + format: duration +cron: + description: >- + A [Cron expression](https://en.wikipedia.org/wiki/Cron#Overview) that defines the schedule on which the task runs. + InfluxDB uses the system time when evaluating Cron expressions. + type: string + format: cron +offset: + description: >- + A [duration](https://docs.influxdata.com/flux/v0.x/spec/lexical-elements/#duration-literals) to delay execution of the task after the scheduled time has elapsed. + `0` removes the offset. + type: string + format: duration +latestCompleted: + description: >- + A timestamp ([RFC3339 date/time format]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#rfc3339-timestamp)) of the latest scheduled and completed run. + type: string + format: date-time + readOnly: true +lastRunStatus: + readOnly: true + type: string + enum: + - failed + - success + - canceled +lastRunError: + readOnly: true + type: string +createdAt: + type: string + format: date-time + readOnly: true +updatedAt: + type: string + format: date-time + readOnly: true +links: + type: object + readOnly: true + example: + self: "/api/v2/tasks/1" + owners: "/api/v2/tasks/1/owners" + members: "/api/v2/tasks/1/members" + labels: "/api/v2/tasks/1/labels" + runs: "/api/v2/tasks/1/runs" + logs: "/api/v2/tasks/1/logs" + properties: + self: + $ref: "./Link.yml" + owners: + $ref: "./Link.yml" + members: + $ref: "./Link.yml" + runs: + $ref: "./Link.yml" + logs: + $ref: "./Link.yml" + labels: + $ref: "./Link.yml" diff --git a/src/common/schemas/TaskUpdateRequest.yml b/src/common/schemas/TaskUpdateRequest.yml index 4f0f1289c..3195eac1a 100644 --- a/src/common/schemas/TaskUpdateRequest.yml +++ b/src/common/schemas/TaskUpdateRequest.yml @@ -1,22 +1,16 @@ type: object properties: status: - $ref: "./TaskStatusType.yml" + $ref: ./TaskProperties.yml#/status flux: - description: The Flux script that the task runs. - type: string + $ref: ./TaskProperties.yml#/flux name: - description: Update the 'name' option in the flux script. - type: string + $ref: ./TaskProperties.yml#/name every: - description: Update the 'every' option in the flux script. - type: string + $ref: ./TaskProperties.yml#/every cron: - description: Update the 'cron' option in the flux script. - type: string + $ref: ./TaskProperties.yml#/cron offset: - description: Update the 'offset' option in the flux script. - type: string + $ref: ./TaskProperties.yml#/offset description: - description: Update the description of the task. - type: string + $ref: ./TaskProperties.yml#/description diff --git a/src/oss.yml b/src/oss.yml index 084547d61..f325a28a9 100644 --- a/src/oss.yml +++ b/src/oss.yml @@ -109,7 +109,7 @@ paths: $ref: "./common/paths/dashboards.yml" /tasks: $ref: "./common/paths/tasks.yml" - "/tasks/{taskID}": + /tasks/{taskID}: $ref: "./common/paths/tasks_taskID.yml" components: parameters: From 02a6f6b8523ba281c6892f1c8ca753b6b553eba9 Mon Sep 17 00:00:00 2001 From: Jason Stirnaman Date: Fri, 28 Oct 2022 13:50:19 -0500 Subject: [PATCH 2/3] docs(tasks): revise task descriptions, add error example: - apply style updates to task descriptions. - add error example for trying to run an inactive task. --- src/cloud/paths/tasks.yml | 171 +++++++----------- src/cloud/paths/tasks_taskID.yml | 94 +++++----- src/common/paths/tasks.yml | 72 ++++---- src/common/paths/tasks_taskID.yml | 41 +++-- src/common/paths/tasks_taskID_labels.yml | 27 ++- .../paths/tasks_taskID_labels_labelID.yml | 10 +- src/common/paths/tasks_taskID_logs.yml | 21 ++- src/common/paths/tasks_taskID_members.yml | 23 ++- .../paths/tasks_taskID_members_userID.yml | 8 +- src/common/paths/tasks_taskID_owners.yml | 14 +- .../paths/tasks_taskID_owners_userID.yml | 9 +- src/common/paths/tasks_taskID_runs.yml | 35 +++- src/common/paths/tasks_taskID_runs_runID.yml | 20 +- .../paths/tasks_taskID_runs_runID_logs.yml | 10 +- .../paths/tasks_taskID_runs_runID_retry.yml | 12 +- 15 files changed, 292 insertions(+), 275 deletions(-) diff --git a/src/cloud/paths/tasks.yml b/src/cloud/paths/tasks.yml index a28b7b40c..6e47dfe5f 100644 --- a/src/cloud/paths/tasks.yml +++ b/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,40 @@ post: parameters: - $ref: "../../common/parameters/TraceSpan.yml" requestBody: - description: Provide a task object in the request body. + 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" + TaskWithFlux: + $ref: "../../common/requestBody/examples/TaskRequestExamples.yml#/TaskWithFluxRequest" + TaskWithScriptID: + $ref: "../../common/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 +216,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 +249,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 diff --git a/src/cloud/paths/tasks_taskID.yml b/src/cloud/paths/tasks_taskID.yml index cf9786a3c..403e58bfe 100644 --- a/src/cloud/paths/tasks_taskID.yml +++ b/src/cloud/paths/tasks_taskID.yml @@ -5,7 +5,7 @@ get: - Tasks summary: Retrieve a task description: | - Retrieves a [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task). + Retrieves the specified [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task). parameters: - $ref: "../../common/parameters/TraceSpan.yml" - in: path @@ -14,8 +14,8 @@ get: type: string required: true description: | - A [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) ID. - Specifies the task to retrieve. + A task ID. + Specifies the [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) to retrieve. responses: "200": description: Success. The response body contains the task. @@ -39,67 +39,52 @@ patch: - Tasks summary: Update a task description: | - Updates a [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task), + Updates the specified [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task), and then cancels all scheduled runs of the task. Use this endpoint to set, modify, or clear task properties--for example: `cron`, `name`, `flux`, `status`. Once InfluxDB applies the update, it cancels all previously scheduled runs of the task. - To update a task, pass 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. + The `status` property set to `inactive` cancels scheduled runs and prevents manual runs of the task. - #### InfluxDB Cloud + #### Related guides - - 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: + - [Update a task]({{% INFLUXDB_DOCS_URL %}}/process-data/manage-tasks/update-task/) + - [Task configuration options]({{% INFLUXDB_DOCS_URL %}}/process-data/task-options/) + requestBody: + description: | + In the request body, provide the task properties to update. + To provide the script that the task runs, + set either the `flux` property or the `scriptID` property. - ```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" - } - ``` + If you set `scriptID`, you can set the following properties to configure the task: + - `cron` + - `every` + - `offset` + - `scriptParameters` - - `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: + If you set the `flux` property, provide the `task` configuration option + in the Flux script. - ```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" - } - } - ``` + See [task configuration options]({{% INFLUXDB_DOCS_URL %}}/process-data/task-options/) + for detail and examples. - #### Limitations: + #### Limitations: - - You can't use `flux` and `scriptID` for the same task. - requestBody: - description: An task update to apply. + - You can't set `flux` and `scriptID` properties for the same task--for + example, if you set the `scriptID` property, then InfluxDB sets the `flux` property + to an empty string (`""`). required: true content: application/json: schema: $ref: "../schemas/TaskUpdateRequest.yml" + examples: + TaskWithFlux: + $ref: "../../common/requestBody/examples/TaskRequestExamples.yml#/TaskWithFluxRequest" + TaskWithScriptID: + $ref: "../../common/requestBody/examples/TaskRequestExamples.yml#/TaskWithScriptRequest" parameters: - $ref: "../../common/parameters/TraceSpan.yml" - in: path @@ -108,8 +93,8 @@ patch: type: string required: true description: | - A [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) ID. - Specifies the task to update. + A task ID. + Specifies the [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) to update. responses: "200": description: Success. The response body contains the updated task. @@ -133,12 +118,13 @@ delete: - Tasks summary: Delete a task description: | - Deletes a [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) and associated records. - - Use this endpoint to delete a task and all associated records (task runs, logs, and labels). + Deletes the specified [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) + and all associated records (task runs, logs, and labels). Once the task is deleted, InfluxDB cancels all scheduled runs of the task. - If you want to disable a task instead of delete it, [update the task status to `inactive`](#operation/PatchTasksID). + To disable a task instead of delete it, use + [`PATCH /api/v2/tasks/TASK_ID`](#operation/PatchTasksID) to set the task's `status` + property to `inactive`. parameters: - $ref: "../../common/parameters/TraceSpan.yml" - in: path @@ -146,7 +132,9 @@ delete: schema: type: string required: true - description: A [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) ID. Specifies the task to delete. + description: | + A task ID. + Specifies the [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) to delete. responses: "204": description: Success. The task and task runs are deleted. Scheduled runs are canceled. diff --git a/src/common/paths/tasks.yml b/src/common/paths/tasks.yml index e873be96f..c19ea65c9 100644 --- a/src/common/paths/tasks.yml +++ b/src/common/paths/tasks.yml @@ -5,7 +5,7 @@ get: - 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`. @@ -18,8 +18,9 @@ get: - 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) + that have the specified name. Different tasks may have the same name. schema: type: string @@ -28,29 +29,31 @@ 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 [tasks]({{% 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 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]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) owned by the specified [organization]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#organization). + required: true - in: query name: status schema: @@ -59,8 +62,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: @@ -78,9 +81,9 @@ 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`). required: false @@ -121,7 +124,9 @@ post: - Tasks summary: Create a task description: | - Creates a [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) and returns the task. + Creates a [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) and returns the task. + + Use this endpoint to create a scheduled task that runs a script. #### Related guides @@ -132,12 +137,20 @@ post: parameters: - $ref: "../parameters/TraceSpan.yml" requestBody: - description: Provide a task object in the request body. + description: | + In the request body, provide the task. + + #### InfluxDB OSS + + - Requires either the `org` parameter or the `orgID` parameter. required: true content: application/json: schema: $ref: "../schemas/TaskCreateRequest.yml" + examples: + TaskWithFlux: + $ref: "../../common/requestBody/examples/TaskRequestExamples.yml#/TaskWithFluxRequest" responses: "201": description: Success. The response body contains a `tasks` list with the task. @@ -159,15 +172,16 @@ post: $ref: "../schemas/Error.yml" examples: orgProvidedNotFound: - summary: The org or orgID passed doesn't own the token passed in the header + summary: The organization specified by org or orgID doesn't own the token passed in the header value: { "code":"invalid", "message":"failed to decode request body: organization not found" } missingFluxError: - summary: Task in request body is missing Flux query - value: { + summary: The request body doesn't contain a Flux query + value: + { "code":"invalid", "message": "failed to decode request: missing flux" } @@ -181,21 +195,3 @@ post: application/json: schema: $ref: "../schemas/Error.yml" - x-codeSamples: - - lang: Shell - label: "cURL: create a task" - source: | - curl http://localhost:8086/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 diff --git a/src/common/paths/tasks_taskID.yml b/src/common/paths/tasks_taskID.yml index d69400030..b6f815969 100644 --- a/src/common/paths/tasks_taskID.yml +++ b/src/common/paths/tasks_taskID.yml @@ -5,7 +5,7 @@ get: - Tasks summary: Retrieve a task description: | - Retrieves a [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task). + Retrieves the specified [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task). parameters: - $ref: "../parameters/TraceSpan.yml" - in: path @@ -13,7 +13,9 @@ get: schema: type: string required: true - description: The ID of the task to retrieve. + description: | + A task ID. + Specifies the [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) to retrieve. responses: "200": description: Success. The response body contains the task. @@ -37,21 +39,27 @@ patch: - Tasks summary: Update a task description: | - Updates a task and then cancels all scheduled runs of the task. + Updates the specified [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task), + and then cancels all scheduled runs of the task. - Use this endpoint to set, modify, and clear task properties (for example: `cron`, `name`, `flux`, `status`). + Use this endpoint to set, modify, or clear task properties--for example: `cron`, `name`, `flux`, `status`. Once InfluxDB applies the update, it cancels all previously scheduled runs of the task. - To update a task, pass 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. + #### Related guides + + - [Update a task]({{% INFLUXDB_DOCS_URL %}}/process-data/manage-tasks/update-task/) + - [Task configuration options]({{% INFLUXDB_DOCS_URL %}}/process-data/task-options/) requestBody: - description: An object that contains updated task properties to apply. + description: | + In the request body, provide the task properties to update. required: true content: application/json: schema: $ref: "../schemas/TaskUpdateRequest.yml" + examples: + TaskWithFlux: + $ref: "../../common/requestBody/examples/TaskRequestExamples.yml#/TaskWithFluxRequest" parameters: - $ref: "../parameters/TraceSpan.yml" - in: path @@ -59,7 +67,9 @@ patch: schema: type: string required: true - description: The ID of the task to update. + description: | + A task ID. + Specifies the [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task)to update. responses: "200": description: Success. The response body contains the updated task. @@ -83,12 +93,13 @@ delete: - Tasks summary: Delete a task description: | - Deletes a task and associated records. - - Use this endpoint to delete a task and all associated records (task runs, logs, and labels). + Deletes the specified [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) + and all associated records (task runs, logs, and labels). Once the task is deleted, InfluxDB cancels all scheduled runs of the task. - If you want to disable a task instead of delete it, [update the task status to `inactive`](#operation/PatchTasksID). + To disable a task instead of delete it, use + [`PATCH /api/v2/tasks/TASK_ID`](#operation/PatchTasksID) to set the task status + to `inactive`. parameters: - $ref: "../parameters/TraceSpan.yml" - in: path @@ -96,7 +107,9 @@ delete: schema: type: string required: true - description: The ID of the task to delete. + description: | + A task ID. + Specifies the [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) to delete. responses: "204": description: Success. The task and runs are deleted. Scheduled runs are canceled. diff --git a/src/common/paths/tasks_taskID_labels.yml b/src/common/paths/tasks_taskID_labels.yml index 9e45af5ea..b1f252d34 100644 --- a/src/common/paths/tasks_taskID_labels.yml +++ b/src/common/paths/tasks_taskID_labels.yml @@ -4,9 +4,12 @@ get: - Tasks summary: List labels for a task description: | - Retrieves a list of all labels for a task. + Lists all labels for a task. - Labels may be used for grouping and filtering tasks. + Use this endpoint to list labels applied to a task. + Labels are a way to add metadata to InfluxDB resources. + You can use labels for grouping and filtering resources in the + InfluxDB UI, `influx` CLI, and InfluxDB API. parameters: - $ref: "../parameters/TraceSpan.yml" - in: path @@ -14,7 +17,9 @@ get: schema: type: string required: true - description: The ID of the task to retrieve labels for. + description: | + A task ID. + Specifies the task to retrieve labels for. responses: "200": description: Success. The response body contains a list of all labels for the task. @@ -38,9 +43,12 @@ post: - Tasks summary: Add a label to a task description: | - Adds a label to a task. + Adds a label to a [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task). - Use this endpoint to add a label that you can use to filter tasks in the InfluxDB UI. + Use this endpoint to add a label to a task. + Labels are a way to add metadata to InfluxDB resources. + You can use labels for grouping and filtering resources in the + InfluxDB UI, `influx` CLI, and InfluxDB API. parameters: - $ref: "../parameters/TraceSpan.yml" - in: path @@ -48,9 +56,12 @@ post: schema: type: string required: true - description: The ID of the task to label. + description: | + A task ID. + Specifies the [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) to label. requestBody: - description: An object that contains a _`labelID`_ to add to the task. + description: | + In the request body, provide an object that specifies the label. required: true content: application/json: @@ -58,7 +69,7 @@ post: $ref: "../schemas/LabelMapping.yml" responses: "201": - description: Success. The response body contains a list of all labels for the task. + description: Success. The response body contains the label. content: application/json: schema: diff --git a/src/common/paths/tasks_taskID_labels_labelID.yml b/src/common/paths/tasks_taskID_labels_labelID.yml index 4057d15e3..f94089011 100644 --- a/src/common/paths/tasks_taskID_labels_labelID.yml +++ b/src/common/paths/tasks_taskID_labels_labelID.yml @@ -4,7 +4,7 @@ delete: - Tasks summary: Delete a label from a task description: | - Deletes a label from a task. + Deletes a label from a [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task). parameters: - $ref: "../parameters/TraceSpan.yml" - in: path @@ -12,13 +12,17 @@ delete: schema: type: string required: true - description: The ID of the task to delete the label from. + description: | + A task ID. + Specifies the [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) to delete the label from. - in: path name: labelID schema: type: string required: true - description: The ID of the label to delete. + description: | + A label ID. + Specifies the label to delete. responses: "204": description: Success. The label is deleted. diff --git a/src/common/paths/tasks_taskID_logs.yml b/src/common/paths/tasks_taskID_logs.yml index 5e7f760b2..433137665 100644 --- a/src/common/paths/tasks_taskID_logs.yml +++ b/src/common/paths/tasks_taskID_logs.yml @@ -2,12 +2,12 @@ get: operationId: GetTasksIDLogs tags: - Tasks - summary: Retrieve all logs for a task + summary: List logs for a task description: | - Retrieves a list of all logs for a [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task). + Lists all log events for a [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task). - 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. + When a task runs, InfluxDB creates a `run` record in the task’s history. + Logs associated with each run provide relevant log messages, timestamps, and the exit status of the `run` attempt. Use this endpoint to retrieve only the log events for a task, without additional task metadata. @@ -18,20 +18,21 @@ get: schema: type: string required: true - description: The task ID. + description: A task ID. Specifies the [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) to retrieve logs for. responses: "200": description: | - Success. The response body contains an `events` list with logs for the task. - Each log event `message` contains detail about the event. - If a task run fails, InfluxDB logs an event with the reason for the failure. + Success. + The response body contains an `events` list with logs for the task. + Each log event `message` contains detail about the event. + If a task run fails, InfluxDB logs an event with the reason for the failure. content: application/json: schema: $ref: "../schemas/Logs.yml" examples: taskSuccess: - summary: Events for a successful task run. + summary: Events for a successful task run value: "events": [ { @@ -46,7 +47,7 @@ get: } ] taskFailure: - summary: Events for a failed task run. + summary: Events for a failed task run value: { "events": [ { diff --git a/src/common/paths/tasks_taskID_members.yml b/src/common/paths/tasks_taskID_members.yml index 0b72dd50b..66917b463 100644 --- a/src/common/paths/tasks_taskID_members.yml +++ b/src/common/paths/tasks_taskID_members.yml @@ -7,6 +7,8 @@ get: description: | **Deprecated**: Tasks don't use `owner` and `member` roles. Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. + + Lists all users that have the `member` role for the specified [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task). parameters: - $ref: "../parameters/TraceSpan.yml" - in: path @@ -14,12 +16,16 @@ get: schema: type: string required: true - description: The task ID. + description: | + A task ID. + Specifies the [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) to retrieve members for. responses: "200": description: | Success. The response body contains a list of `users` that have the `member` role for a task. + + If the task has no members, the response contains an empty `users` array. content: application/json: schema: @@ -40,7 +46,8 @@ post: **Deprecated**: Tasks don't use `owner` and `member` roles. Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. - Adds a user to members of a task and returns the member. + Adds a specified user to members of the specified [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) and then returns + the member. parameters: - $ref: "../parameters/TraceSpan.yml" - in: path @@ -48,9 +55,12 @@ post: schema: type: string required: true - description: The task ID. + description: | + A [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) ID. + Specifies the task for the member. requestBody: - description: A user to add as a member of the task. + description: | + In the request body, provide an object that specifies the user. required: true content: application/json: @@ -58,7 +68,10 @@ post: $ref: "../schemas/AddResourceMemberRequestBody.yml" responses: "201": - description: Created. The user is added to task members. + description: | + Created. The task `member` role is assigned to the user. + The response body contains the resource member with + role and user detail. content: application/json: schema: diff --git a/src/common/paths/tasks_taskID_members_userID.yml b/src/common/paths/tasks_taskID_members_userID.yml index dfb3ae26e..402ccd146 100644 --- a/src/common/paths/tasks_taskID_members_userID.yml +++ b/src/common/paths/tasks_taskID_members_userID.yml @@ -7,6 +7,8 @@ delete: description: | **Deprecated**: Tasks don't use `owner` and `member` roles. Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. + + Removes a member from a [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task). parameters: - $ref: "../parameters/TraceSpan.yml" - in: path @@ -14,16 +16,16 @@ delete: schema: type: string required: true - description: The ID of the member to remove. + description: A user ID. Specifies the member to remove. - in: path name: taskID schema: type: string required: true - description: The task ID. + description: A task ID. Specifies the [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) to remove the member from. responses: "204": - description: Member removed + description: Success. The member is removed. default: description: Unexpected error content: diff --git a/src/common/paths/tasks_taskID_owners.yml b/src/common/paths/tasks_taskID_owners.yml index 08e6a586f..10e092c6c 100644 --- a/src/common/paths/tasks_taskID_owners.yml +++ b/src/common/paths/tasks_taskID_owners.yml @@ -8,7 +8,7 @@ get: **Deprecated**: Tasks don't use `owner` and `member` roles. Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. - Retrieves all users that have owner permission for a task. + Lists all users that have the `owner` role for the specified task. parameters: - $ref: "../parameters/TraceSpan.yml" - in: path @@ -16,7 +16,7 @@ get: schema: type: string required: true - description: The ID of the task to retrieve owners for. + description: A task ID. Specifies the task to retrieve owners for. responses: "200": description: | @@ -60,7 +60,8 @@ post: **Deprecated**: Tasks don't use `owner` and `member` roles. Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. - Assigns a task `owner` role to a user. + Adds a specified user to owners of the specified task and then returns the + owner. Use this endpoint to create a _resource owner_ for the task. A _resource owner_ is a user with `role: owner` for a specific resource. @@ -71,9 +72,12 @@ post: schema: type: string required: true - description: The task ID. + description: | + A task ID. + Specifies the [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) for the owner. requestBody: - description: A user to add as an owner of the task. + description: | + In the request body, provide an object that specifies the user. required: true content: application/json: diff --git a/src/common/paths/tasks_taskID_owners_userID.yml b/src/common/paths/tasks_taskID_owners_userID.yml index 4df6d8773..d8db0f5bc 100644 --- a/src/common/paths/tasks_taskID_owners_userID.yml +++ b/src/common/paths/tasks_taskID_owners_userID.yml @@ -8,6 +8,7 @@ delete: **Deprecated**: Tasks don't use `owner` and `member` roles. Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. + Removes an owner from a [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task). parameters: - $ref: "../parameters/TraceSpan.yml" - in: path @@ -15,16 +16,18 @@ delete: schema: type: string required: true - description: The ID of the owner to remove. + description: A user ID. Specifies the owner to remove from the [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task). - in: path name: taskID schema: type: string required: true - description: The task ID. + description: | + A task ID. + Specifies the [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) to remove the owner from. responses: "204": - description: Owner removed + description: Success. The owner is removed. default: description: Unexpected error content: diff --git a/src/common/paths/tasks_taskID_runs.yml b/src/common/paths/tasks_taskID_runs.yml index 31c4728dc..6c357d53a 100644 --- a/src/common/paths/tasks_taskID_runs.yml +++ b/src/common/paths/tasks_taskID_runs.yml @@ -4,10 +4,11 @@ get: - Tasks summary: List runs for a task description: | - Retrieves a list of runs for a [task]({{% INFLUXDB_DOCS_URL %}}/process-data/). + Lists runs for the specified [task]({{% INFLUXDB_DOCS_URL %}}/process-data/). To limit which task runs are returned, pass query parameters in your request. - If no query parameters are passed, InfluxDB returns all task runs up to the default `limit`. + If you don't pass query parameters, InfluxDB returns all runs for the task + up to the default `limit`. parameters: - $ref: "../parameters/TraceSpan.yml" - in: path @@ -16,15 +17,16 @@ get: type: string required: true description: | - The ID of the task to get runs for. - Only returns runs for this task. + A task ID. + Specifies the [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) to + to list runs for. - in: query name: after schema: type: string description: A task run ID. - Only returns runs created after this run. + Only returns runs created after the specified run. - in: query name: limit schema: @@ -41,7 +43,7 @@ get: format: date-time description: | A timestamp ([RFC3339 date/time format]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#rfc3339-timestamp)). - Only returns runs scheduled after this time. + Only returns runs scheduled after the specified time. - in: query name: beforeTime schema: @@ -49,7 +51,7 @@ get: format: date-time description: | A timestamp ([RFC3339 date/time format]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#rfc3339-timestamp)). - Only returns runs scheduled before this time. + Only returns runs scheduled before the specified time. responses: "200": description: Success. The response body contains the list of task runs. @@ -78,6 +80,10 @@ post: To _retry_ a previous run (and avoid creating a new run), use the [`POST /api/v2/tasks/{taskID}/runs/{runID}/retry` endpoint](#operation/PostTasksIDRunsIDRetry). + + #### Limitations + + - Queuing a task run requires that the task's `status` property be set to `active`. parameters: - $ref: "../parameters/TraceSpan.yml" - in: path @@ -85,6 +91,10 @@ post: schema: type: string required: true + description: | + A task ID. + Specifies the [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) to + to run. requestBody: content: application/json: @@ -97,6 +107,17 @@ post: application/json: schema: $ref: "../schemas/Run.yml" + "400": + description: Bad request. + content: + application/json: + examples: + inactiveTask: + summary: Can't run an inactive task + value: { + "code": "invalid", + "message": "failed to force run: inactive task" + } "401": $ref: "../responses/AuthorizationError.yml" "500": diff --git a/src/common/paths/tasks_taskID_runs_runID.yml b/src/common/paths/tasks_taskID_runs_runID.yml index ecf6571f9..6dd5325c9 100644 --- a/src/common/paths/tasks_taskID_runs_runID.yml +++ b/src/common/paths/tasks_taskID_runs_runID.yml @@ -4,7 +4,7 @@ get: - Tasks summary: Retrieve a run for a task. description: | - Retrieves a specific run for a [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task). + Retrieves the specified run for the specified [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task). Use this endpoint to retrieve detail and logs for a specific task run. parameters: @@ -14,13 +14,16 @@ get: schema: type: string required: true - description: The ID of the task to retrieve runs for. + description: | + A task ID. + Specifies the [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) + that the task run belongs to. - in: path name: runID schema: type: string required: true - description: The ID of the run to retrieve. + description: A task run ID. Specifies the run to retrieve. responses: "200": description: Success. The response body contains the task run. @@ -77,7 +80,7 @@ delete: description: | Cancels a running [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task). - Use this endpoint with InfluxDB OSS to cancel a running task. + Use this endpoint to cancel a running task. #### InfluxDB Cloud @@ -89,13 +92,18 @@ delete: schema: type: string required: true - description: The ID of the task to cancel. + description: | + A task ID. + Specifies the [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) to + to cancel. - in: path name: runID schema: type: string required: true - description: The ID of the task run to cancel. + description: | + A task run ID. + Specifies the task run to cancel. responses: "204": description: | diff --git a/src/common/paths/tasks_taskID_runs_runID_logs.yml b/src/common/paths/tasks_taskID_runs_runID_logs.yml index 8a1fc79e3..fd8939231 100644 --- a/src/common/paths/tasks_taskID_runs_runID_logs.yml +++ b/src/common/paths/tasks_taskID_runs_runID_logs.yml @@ -2,12 +2,12 @@ get: operationId: GetTasksIDRunsIDLogs tags: - Tasks - summary: Retrieve all logs for a run + summary: List logs for a run description: | - Retrieves all logs for a task run. + Lists all logs for a task run. A log is a list of run events with `runID`, `time`, and `message` properties. - Use this endpoint to help analyze task performance and troubleshoot failed task runs. + Use this endpoint to help analyze [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) performance and troubleshoot failed task runs. parameters: - $ref: "../parameters/TraceSpan.yml" - in: path @@ -15,13 +15,13 @@ get: schema: type: string required: true - description: The ID of the task to get logs for. + description: A task ID. Specifies the [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) that the run belongs to. - in: path name: runID schema: type: string required: true - description: The ID of the run to get logs for. + description: A run ID. Specifies the task run to list logs for. responses: "200": description: | diff --git a/src/common/paths/tasks_taskID_runs_runID_retry.yml b/src/common/paths/tasks_taskID_runs_runID_retry.yml index 8406bcf31..5af3ab68d 100644 --- a/src/common/paths/tasks_taskID_runs_runID_retry.yml +++ b/src/common/paths/tasks_taskID_runs_runID_retry.yml @@ -4,15 +4,15 @@ post: - Tasks summary: Retry a task run description: | - Queues a [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) run to - retry and returns the scheduled run. + Queues a [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) run to + retry and then returns the scheduled run. To manually start a _new_ task run, use the [`POST /api/v2/tasks/{taskID}/runs` endpoint](#operation/PostTasksIDRuns). #### Limitations - - The task must be _active_ (`status: "active"`). + - Queuing a task run requires that the task's `status` property be set to `active`. requestBody: content: application/json; charset=utf-8: @@ -26,15 +26,15 @@ post: type: string required: true description: | - A [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) ID. - Specifies the task to retry. + A task ID. + Specifies the [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) that the task run belongs to. - in: path name: runID schema: type: string required: true description: | - A [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) run ID. + A task run ID. Specifies the task run to retry. To find a task run ID, use the From b5dafb5f7765114a72ffcf5c31efb2202e7e1e96 Mon Sep 17 00:00:00 2001 From: Jason Stirnaman Date: Fri, 28 Oct 2022 14:38:58 -0500 Subject: [PATCH 3/3] docs: fix shared examples. --- contracts/cloud-diff.yml | 276 ++++------ contracts/cloud.json | 206 ++++---- contracts/cloud.yml | 455 +++++++++-------- contracts/common.yml | 187 ++++--- contracts/oss-diff.yml | 112 ++-- contracts/oss.json | 190 ++++--- contracts/oss.yml | 299 +++++++---- contracts/ref/cloud.yml | 477 +++++++++--------- contracts/ref/oss.yml | 314 +++++++----- src/cloud.yml | 2 +- src/cloud/paths/tasks.yml | 3 +- src/cloud/paths/tasks_taskID.yml | 2 +- .../examples/TaskRequestExamples.yml | 17 + src/cloud/schemas/TaskCreateRequest.yml | 2 +- src/common/paths/tasks.yml | 2 +- src/common/paths/tasks_taskID.yml | 2 +- src/common/paths/tasks_taskID_runs.yml | 2 + .../examples/AuthorizationRequestExamples.yml | 84 +-- .../examples/TaskRequestExamples.yml | 34 +- 19 files changed, 1458 insertions(+), 1208 deletions(-) create mode 100644 src/cloud/requestBody/examples/TaskRequestExamples.yml diff --git a/contracts/cloud-diff.yml b/contracts/cloud-diff.yml index 30abb5ff7..f19781072 100644 --- a/contracts/cloud-diff.yml +++ b/contracts/cloud-diff.yml @@ -3237,19 +3237,23 @@ paths: 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: '#/paths/~1users/get/parameters/0' - 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 @@ -3258,29 +3262,29 @@ paths: 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: @@ -3289,8 +3293,8 @@ paths: - 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: @@ -3323,8 +3327,11 @@ paths: - 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 @@ -3333,11 +3340,13 @@ paths: - 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: '' @@ -3348,8 +3357,8 @@ paths: - 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: @@ -3478,52 +3487,7 @@ paths: 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 @@ -3534,15 +3498,41 @@ paths: parameters: - $ref: '#/paths/~1users/get/parameters/0' requestBody: - description: Provide a task object in the request body. + 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: '#/components/schemas/TaskCreateRequest' + examples: + TaskWithFlux: + $ref: '#/components/examples/TaskWithFluxRequest' + TaskWithScriptID: + $ref: '#/components/examples/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: @@ -3554,8 +3544,10 @@ paths: #### 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: @@ -3581,44 +3573,6 @@ paths: application/json: schema: $ref: '#/paths/~1users/get/responses/401/content/application~1json/schema' - 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 '/tasks/{taskID}': get: operationId: GetTasksID @@ -3627,7 +3581,7 @@ paths: - Tasks summary: Retrieve a task description: | - Retrieves a [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task). + Retrieves the specified [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task). parameters: - $ref: '#/paths/~1users/get/parameters/0' - in: path @@ -3636,8 +3590,8 @@ paths: type: string required: true description: | - A [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) ID. - Specifies the task to retrieve. + A task ID. + Specifies the [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) to retrieve. responses: '200': description: Success. The response body contains the task. @@ -3705,67 +3659,52 @@ paths: - Tasks summary: Update a task description: | - Updates a [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task), + Updates the specified [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task), and then cancels all scheduled runs of the task. Use this endpoint to set, modify, or clear task properties--for example: `cron`, `name`, `flux`, `status`. Once InfluxDB applies the update, it cancels all previously scheduled runs of the task. - To update a task, pass 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. + The `status` property set to `inactive` cancels scheduled runs and prevents manual runs of the task. - #### InfluxDB Cloud + #### Related guides - - 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. + - [Update a task]({{% INFLUXDB_DOCS_URL %}}/process-data/manage-tasks/update-task/) + - [Task configuration options]({{% INFLUXDB_DOCS_URL %}}/process-data/task-options/) requestBody: - description: An task update to apply. + description: | + In the request body, provide the task properties to update. + To provide the script that the task runs, + set either the `flux` property or the `scriptID` property. + + If you set `scriptID`, you can set the following properties to configure the task: + - `cron` + - `every` + - `offset` + - `scriptParameters` + + If you set the `flux` property, 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 set `flux` and `scriptID` properties for the same task--for + example, if you set the `scriptID` property, then InfluxDB sets the `flux` property + to an empty string (`""`). required: true content: application/json: schema: $ref: '#/components/schemas/TaskUpdateRequest' + examples: + TaskWithFlux: + $ref: '#/components/examples/TaskWithFluxRequest' + TaskWithScriptID: + $ref: '#/components/examples/TaskWithScriptRequest' parameters: - $ref: '#/paths/~1users/get/parameters/0' - in: path @@ -3774,8 +3713,8 @@ paths: type: string required: true description: | - A [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) ID. - Specifies the task to update. + A task ID. + Specifies the [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) to update. responses: '200': description: Success. The response body contains the updated task. @@ -3799,12 +3738,13 @@ paths: - Tasks summary: Delete a task description: | - Deletes a [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) and associated records. - - Use this endpoint to delete a task and all associated records (task runs, logs, and labels). + Deletes the specified [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) + and all associated records (task runs, logs, and labels). Once the task is deleted, InfluxDB cancels all scheduled runs of the task. - If you want to disable a task instead of delete it, [update the task status to `inactive`](#operation/PatchTasksID). + To disable a task instead of delete it, use + [`PATCH /api/v2/tasks/TASK_ID`](#operation/PatchTasksID) to set the task's `status` + property to `inactive`. parameters: - $ref: '#/paths/~1users/get/parameters/0' - in: path @@ -3812,7 +3752,9 @@ paths: schema: type: string required: true - description: 'A [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) ID. Specifies the task to delete.' + description: | + A task ID. + Specifies the [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) to delete. responses: '204': description: Success. The task and task runs are deleted. Scheduled runs are canceled. @@ -4835,7 +4777,7 @@ components: summary: A task with Flux description: Sets the `flux` property with Flux task options and a query. value: - 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\")" + 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 contains Flux that configures the task schedule and downsamples CPU data every hour. TaskWithScriptRequest: diff --git a/contracts/cloud.json b/contracts/cloud.json index 80f62d557..9640cc831 100644 --- a/contracts/cloud.json +++ b/contracts/cloud.json @@ -8265,7 +8265,7 @@ "Tasks" ], "summary": "List runs for a task", - "description": "Retrieves a list of runs for a [task]({{% INFLUXDB_DOCS_URL %}}/process-data/).\n\nTo limit which task runs are returned, pass query parameters in your request.\nIf no query parameters are passed, InfluxDB returns all task runs up to the default `limit`.\n", + "description": "Lists runs for the specified [task]({{% INFLUXDB_DOCS_URL %}}/process-data/).\n\nTo limit which task runs are returned, pass query parameters in your request.\nIf you don't pass query parameters, InfluxDB returns all runs for the task\nup to the default `limit`.\n", "parameters": [ { "$ref": "#/components/parameters/TraceSpan" @@ -8277,7 +8277,7 @@ "type": "string" }, "required": true, - "description": "The ID of the task to get runs for.\nOnly returns runs for this task.\n" + "description": "A task ID.\nSpecifies the [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) to\nto list runs for.\n" }, { "in": "query", @@ -8285,7 +8285,7 @@ "schema": { "type": "string" }, - "description": "A task run ID. Only returns runs created after this run." + "description": "A task run ID. Only returns runs created after the specified run." }, { "in": "query", @@ -8305,7 +8305,7 @@ "type": "string", "format": "date-time" }, - "description": "A timestamp ([RFC3339 date/time format]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#rfc3339-timestamp)).\nOnly returns runs scheduled after this time.\n" + "description": "A timestamp ([RFC3339 date/time format]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#rfc3339-timestamp)).\nOnly returns runs scheduled after the specified time.\n" }, { "in": "query", @@ -8314,7 +8314,7 @@ "type": "string", "format": "date-time" }, - "description": "A timestamp ([RFC3339 date/time format]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#rfc3339-timestamp)).\nOnly returns runs scheduled before this time.\n" + "description": "A timestamp ([RFC3339 date/time format]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#rfc3339-timestamp)).\nOnly returns runs scheduled before the specified time.\n" } ], "responses": { @@ -8346,7 +8346,7 @@ "Tasks" ], "summary": "Start a task run, overriding the schedule", - "description": "Schedules a task run to start immediately, ignoring scheduled runs.\n\nUse this endpoint to manually start a task run.\nScheduled runs will continue to run as scheduled.\nThis may result in concurrently running tasks.\n\nTo _retry_ a previous run (and avoid creating a new run),\nuse the [`POST /api/v2/tasks/{taskID}/runs/{runID}/retry` endpoint](#operation/PostTasksIDRunsIDRetry).\n", + "description": "Schedules a task run to start immediately, ignoring scheduled runs.\n\nUse this endpoint to manually start a task run.\nScheduled runs will continue to run as scheduled.\nThis may result in concurrently running tasks.\n\nTo _retry_ a previous run (and avoid creating a new run),\nuse the [`POST /api/v2/tasks/{taskID}/runs/{runID}/retry` endpoint](#operation/PostTasksIDRunsIDRetry).\n\n#### Limitations\n\n- Queuing a task run requires that the task's `status` property be set to `active`.\n", "parameters": [ { "$ref": "#/components/parameters/TraceSpan" @@ -8357,7 +8357,8 @@ "schema": { "type": "string" }, - "required": true + "required": true, + "description": "A task ID.\nSpecifies the [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) to\nto run.\n" } ], "requestBody": { @@ -8380,6 +8381,25 @@ } } }, + "400": { + "description": "Bad request.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + }, + "examples": { + "inactiveTask": { + "summary": "Can't run an inactive task", + "value": { + "code": "invalid", + "message": "failed to force run: inactive task" + } + } + } + } + } + }, "401": { "$ref": "#/components/responses/AuthorizationError" }, @@ -8399,7 +8419,7 @@ "Tasks" ], "summary": "Retrieve a run for a task.", - "description": "Retrieves a specific run for a [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task).\n\nUse this endpoint to retrieve detail and logs for a specific task run.\n", + "description": "Retrieves the specified run for the specified [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task).\n\nUse this endpoint to retrieve detail and logs for a specific task run.\n", "parameters": [ { "$ref": "#/components/parameters/TraceSpan" @@ -8411,7 +8431,7 @@ "type": "string" }, "required": true, - "description": "The ID of the task to retrieve runs for." + "description": "A task ID.\nSpecifies the [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task)\nthat the task run belongs to.\n" }, { "in": "path", @@ -8420,7 +8440,7 @@ "type": "string" }, "required": true, - "description": "The ID of the run to retrieve." + "description": "A task run ID. Specifies the run to retrieve." } ], "responses": { @@ -8489,7 +8509,7 @@ "Tasks" ], "summary": "Cancel a running task", - "description": "Cancels a running [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task).\n\nUse this endpoint with InfluxDB OSS to cancel a running task.\n\n#### InfluxDB Cloud\n\n- Doesn't support this operation.\n", + "description": "Cancels a running [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task).\n\nUse this endpoint to cancel a running task.\n\n#### InfluxDB Cloud\n\n- Doesn't support this operation.\n", "parameters": [ { "$ref": "#/components/parameters/TraceSpan" @@ -8501,7 +8521,7 @@ "type": "string" }, "required": true, - "description": "The ID of the task to cancel." + "description": "A task ID.\nSpecifies the [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) to\nto cancel.\n" }, { "in": "path", @@ -8510,7 +8530,7 @@ "type": "string" }, "required": true, - "description": "The ID of the task run to cancel." + "description": "A task run ID.\nSpecifies the task run to cancel.\n" } ], "responses": { @@ -8552,7 +8572,7 @@ "Tasks" ], "summary": "Retry a task run", - "description": "Queues a [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) run to\nretry and returns the scheduled run.\n\nTo manually start a _new_ task run, use the\n[`POST /api/v2/tasks/{taskID}/runs` endpoint](#operation/PostTasksIDRuns).\n\n#### Limitations\n\n- The task must be _active_ (`status: \"active\"`).\n", + "description": "Queues a [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) run to\nretry and then returns the scheduled run.\n\nTo manually start a _new_ task run, use the\n[`POST /api/v2/tasks/{taskID}/runs` endpoint](#operation/PostTasksIDRuns).\n\n#### Limitations\n\n- Queuing a task run requires that the task's `status` property be set to `active`.\n", "requestBody": { "content": { "application/json; charset=utf-8": { @@ -8573,7 +8593,7 @@ "type": "string" }, "required": true, - "description": "A [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) ID.\nSpecifies the task to retry.\n" + "description": "A task ID.\nSpecifies the [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) that the task run belongs to.\n" }, { "in": "path", @@ -8582,7 +8602,7 @@ "type": "string" }, "required": true, - "description": "A [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) run ID.\nSpecifies the task run to retry.\n\nTo find a task run ID, use the\n[`GET /api/v2/tasks/{taskID}/runs` endpoint](#operation/GetTasksIDRuns)\nto list task runs.\n" + "description": "A task run ID.\nSpecifies the task run to retry.\n\nTo find a task run ID, use the\n[`GET /api/v2/tasks/{taskID}/runs` endpoint](#operation/GetTasksIDRuns)\nto list task runs.\n" } ], "responses": { @@ -8654,8 +8674,8 @@ "tags": [ "Tasks" ], - "summary": "Retrieve all logs for a task", - "description": "Retrieves a list of all logs for a [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task).\n\nWhen an InfluxDB task runs, a “run” record is created in the task’s history.\nLogs associated with each run provide relevant log messages, timestamps, and the exit status of the run attempt.\n\nUse this endpoint to retrieve only the log events for a task,\nwithout additional task metadata.\n", + "summary": "List logs for a task", + "description": "Lists all log events for a [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task).\n\nWhen a task runs, InfluxDB creates a `run` record in the task’s history.\nLogs associated with each run provide relevant log messages, timestamps, and the exit status of the `run` attempt.\n\nUse this endpoint to retrieve only the log events for a task,\nwithout additional task metadata.\n", "parameters": [ { "$ref": "#/components/parameters/TraceSpan" @@ -8667,12 +8687,12 @@ "type": "string" }, "required": true, - "description": "The task ID." + "description": "A task ID. Specifies the [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) to retrieve logs for." } ], "responses": { "200": { - "description": "Success. The response body contains an `events` list with logs for the task.\nEach log event `message` contains detail about the event.\nIf a task run fails, InfluxDB logs an event with the reason for the failure.\n", + "description": "Success.\nThe response body contains an `events` list with logs for the task.\nEach log event `message` contains detail about the event.\nIf a task run fails, InfluxDB logs an event with the reason for the failure.\n", "content": { "application/json": { "schema": { @@ -8680,7 +8700,7 @@ }, "examples": { "taskSuccess": { - "summary": "Events for a successful task run.", + "summary": "Events for a successful task run", "value": { "events": [ { @@ -8697,7 +8717,7 @@ } }, "taskFailure": { - "summary": "Events for a failed task run.", + "summary": "Events for a failed task run", "value": { "events": [ { @@ -8746,8 +8766,8 @@ "tags": [ "Tasks" ], - "summary": "Retrieve all logs for a run", - "description": "Retrieves all logs for a task run.\nA log is a list of run events with `runID`, `time`, and `message` properties.\n\nUse this endpoint to help analyze task performance and troubleshoot failed task runs.\n", + "summary": "List logs for a run", + "description": "Lists all logs for a task run.\nA log is a list of run events with `runID`, `time`, and `message` properties.\n\nUse this endpoint to help analyze [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) performance and troubleshoot failed task runs.\n", "parameters": [ { "$ref": "#/components/parameters/TraceSpan" @@ -8759,7 +8779,7 @@ "type": "string" }, "required": true, - "description": "The ID of the task to get logs for." + "description": "A task ID. Specifies the [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) that the run belongs to." }, { "in": "path", @@ -8768,7 +8788,7 @@ "type": "string" }, "required": true, - "description": "The ID of the run to get logs for." + "description": "A run ID. Specifies the task run to list logs for." } ], "responses": { @@ -8848,7 +8868,7 @@ "Tasks" ], "summary": "List labels for a task", - "description": "Retrieves a list of all labels for a task.\n\nLabels may be used for grouping and filtering tasks.\n", + "description": "Lists all labels for a task.\n\nUse this endpoint to list labels applied to a task.\nLabels are a way to add metadata to InfluxDB resources.\nYou can use labels for grouping and filtering resources in the\nInfluxDB UI, `influx` CLI, and InfluxDB API.\n", "parameters": [ { "$ref": "#/components/parameters/TraceSpan" @@ -8860,7 +8880,7 @@ "type": "string" }, "required": true, - "description": "The ID of the task to retrieve labels for." + "description": "A task ID.\nSpecifies the task to retrieve labels for.\n" } ], "responses": { @@ -8897,7 +8917,7 @@ "Tasks" ], "summary": "Add a label to a task", - "description": "Adds a label to a task.\n\nUse this endpoint to add a label that you can use to filter tasks in the InfluxDB UI.\n", + "description": "Adds a label to a [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task).\n\nUse this endpoint to add a label to a task.\nLabels are a way to add metadata to InfluxDB resources.\nYou can use labels for grouping and filtering resources in the\nInfluxDB UI, `influx` CLI, and InfluxDB API.\n", "parameters": [ { "$ref": "#/components/parameters/TraceSpan" @@ -8909,11 +8929,11 @@ "type": "string" }, "required": true, - "description": "The ID of the task to label." + "description": "A task ID.\nSpecifies the [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) to label.\n" } ], "requestBody": { - "description": "An object that contains a _`labelID`_ to add to the task.", + "description": "In the request body, provide an object that specifies the label.\n", "required": true, "content": { "application/json": { @@ -8925,7 +8945,7 @@ }, "responses": { "201": { - "description": "Success. The response body contains a list of all labels for the task.", + "description": "Success. The response body contains the label.", "content": { "application/json": { "schema": { @@ -8959,7 +8979,7 @@ "Tasks" ], "summary": "Delete a label from a task", - "description": "Deletes a label from a task.\n", + "description": "Deletes a label from a [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task).\n", "parameters": [ { "$ref": "#/components/parameters/TraceSpan" @@ -8971,7 +8991,7 @@ "type": "string" }, "required": true, - "description": "The ID of the task to delete the label from." + "description": "A task ID.\nSpecifies the [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) to delete the label from.\n" }, { "in": "path", @@ -8980,7 +9000,7 @@ "type": "string" }, "required": true, - "description": "The ID of the label to delete." + "description": "A label ID.\nSpecifies the label to delete.\n" } ], "responses": { @@ -9153,7 +9173,7 @@ "Tasks" ], "summary": "List all task members", - "description": "**Deprecated**: Tasks don't use `owner` and `member` roles.\nUse [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions.\n", + "description": "**Deprecated**: Tasks don't use `owner` and `member` roles.\nUse [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions.\n\nLists all users that have the `member` role for the specified [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task).\n", "parameters": [ { "$ref": "#/components/parameters/TraceSpan" @@ -9165,12 +9185,12 @@ "type": "string" }, "required": true, - "description": "The task ID." + "description": "A task ID.\nSpecifies the [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) to retrieve members for.\n" } ], "responses": { "200": { - "description": "Success. The response body contains a list of `users` that have\nthe `member` role for a task.\n", + "description": "Success. The response body contains a list of `users` that have\nthe `member` role for a task.\n\nIf the task has no members, the response contains an empty `users` array.\n", "content": { "application/json": { "schema": { @@ -9198,7 +9218,7 @@ "Tasks" ], "summary": "Add a member to a task", - "description": "**Deprecated**: Tasks don't use `owner` and `member` roles.\nUse [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions.\n\nAdds a user to members of a task and returns the member.\n", + "description": "**Deprecated**: Tasks don't use `owner` and `member` roles.\nUse [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions.\n\nAdds a specified user to members of the specified [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) and then returns\nthe member.\n", "parameters": [ { "$ref": "#/components/parameters/TraceSpan" @@ -9210,11 +9230,11 @@ "type": "string" }, "required": true, - "description": "The task ID." + "description": "A [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) ID.\nSpecifies the task for the member.\n" } ], "requestBody": { - "description": "A user to add as a member of the task.", + "description": "In the request body, provide an object that specifies the user.\n", "required": true, "content": { "application/json": { @@ -9226,7 +9246,7 @@ }, "responses": { "201": { - "description": "Created. The user is added to task members.", + "description": "Created. The task `member` role is assigned to the user.\nThe response body contains the resource member with\nrole and user detail.\n", "content": { "application/json": { "schema": { @@ -9256,7 +9276,7 @@ "Tasks" ], "summary": "Remove a member from a task", - "description": "**Deprecated**: Tasks don't use `owner` and `member` roles.\nUse [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions.\n", + "description": "**Deprecated**: Tasks don't use `owner` and `member` roles.\nUse [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions.\n\nRemoves a member from a [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task).\n", "parameters": [ { "$ref": "#/components/parameters/TraceSpan" @@ -9268,7 +9288,7 @@ "type": "string" }, "required": true, - "description": "The ID of the member to remove." + "description": "A user ID. Specifies the member to remove." }, { "in": "path", @@ -9277,12 +9297,12 @@ "type": "string" }, "required": true, - "description": "The task ID." + "description": "A task ID. Specifies the [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) to remove the member from." } ], "responses": { "204": { - "description": "Member removed" + "description": "Success. The member is removed." }, "default": { "description": "Unexpected error", @@ -9305,7 +9325,7 @@ "Tasks" ], "summary": "List all owners of a task", - "description": "**Deprecated**: Tasks don't use `owner` and `member` roles.\nUse [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions.\n\nRetrieves all users that have owner permission for a task.\n", + "description": "**Deprecated**: Tasks don't use `owner` and `member` roles.\nUse [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions.\n\nLists all users that have the `owner` role for the specified task.\n", "parameters": [ { "$ref": "#/components/parameters/TraceSpan" @@ -9317,7 +9337,7 @@ "type": "string" }, "required": true, - "description": "The ID of the task to retrieve owners for." + "description": "A task ID. Specifies the task to retrieve owners for." } ], "responses": { @@ -9366,7 +9386,7 @@ "Tasks" ], "summary": "Add an owner for a task", - "description": "**Deprecated**: Tasks don't use `owner` and `member` roles.\nUse [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions.\n\nAssigns a task `owner` role to a user.\n\nUse this endpoint to create a _resource owner_ for the task.\nA _resource owner_ is a user with `role: owner` for a specific resource.\n", + "description": "**Deprecated**: Tasks don't use `owner` and `member` roles.\nUse [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions.\n\nAdds a specified user to owners of the specified task and then returns the\nowner.\n\nUse this endpoint to create a _resource owner_ for the task.\nA _resource owner_ is a user with `role: owner` for a specific resource.\n", "parameters": [ { "$ref": "#/components/parameters/TraceSpan" @@ -9378,11 +9398,11 @@ "type": "string" }, "required": true, - "description": "The task ID." + "description": "A task ID.\nSpecifies the [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) for the owner.\n" } ], "requestBody": { - "description": "A user to add as an owner of the task.", + "description": "In the request body, provide an object that specifies the user.\n", "required": true, "content": { "application/json": { @@ -9455,7 +9475,7 @@ "Tasks" ], "summary": "Remove an owner from a task", - "description": "**Deprecated**: Tasks don't use `owner` and `member` roles.\nUse [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions.\n", + "description": "**Deprecated**: Tasks don't use `owner` and `member` roles.\nUse [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions.\n\nRemoves an owner from a [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task).\n", "parameters": [ { "$ref": "#/components/parameters/TraceSpan" @@ -9467,7 +9487,7 @@ "type": "string" }, "required": true, - "description": "The ID of the owner to remove." + "description": "A user ID. Specifies the owner to remove from the [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task)." }, { "in": "path", @@ -9476,12 +9496,12 @@ "type": "string" }, "required": true, - "description": "The task ID." + "description": "A task ID.\nSpecifies the [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) to remove the owner from.\n" } ], "responses": { "204": { - "description": "Owner removed" + "description": "Success. The owner is removed." }, "default": { "description": "Unexpected error", @@ -12775,8 +12795,8 @@ "Data I/O endpoints", "Tasks" ], - "summary": "List all tasks", - "description": "Retrieves a list of [tasks]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task).\n\nTo limit which tasks are returned, pass query parameters in your request.\nIf no query parameters are passed, InfluxDB returns all tasks up to the default `limit`.\n", + "summary": "List tasks", + "description": "Lists [tasks]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task).\n\nTo limit which tasks are returned, pass query parameters in your request.\nIf no query parameters are passed, InfluxDB returns all tasks up to the default `limit`.\n\n#### Related guide\n\n- [Process data with InfluxDB tasks]({{% INFLUXDB_DOCS_URL %}}/process-data/)\n", "parameters": [ { "$ref": "#/components/parameters/TraceSpan" @@ -12784,7 +12804,7 @@ { "in": "query", "name": "name", - "description": "A [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) name.\nOnly returns tasks with the specified name.\nDifferent tasks may have the same name.\n", + "description": "A task name.\nOnly returns [tasks]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) with the specified name.\nDifferent tasks may have the same name.\n", "schema": { "type": "string" } @@ -12795,7 +12815,7 @@ "schema": { "type": "string" }, - "description": "A [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) ID.\nOnly returns tasks created after the specified task.\n" + "description": "A task ID.\nOnly returns [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) created after the specified task.\n" }, { "in": "query", @@ -12803,7 +12823,7 @@ "schema": { "type": "string" }, - "description": "A [user]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#user) ID.\nOnly returns tasks owned by the specified user.\n" + "description": "A user ID.\nOnly returns [tasks]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) owned by the specified [user]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#user).\n" }, { "in": "query", @@ -12811,7 +12831,7 @@ "schema": { "type": "string" }, - "description": "An [organization]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#organization) name.\nOnly returns tasks owned by the specified organization.\n" + "description": "An organization name.\nOnly returns [tasks]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) owned by the specified [organization]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#organization).\n" }, { "in": "query", @@ -12819,7 +12839,7 @@ "schema": { "type": "string" }, - "description": "An [organization]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#organization) ID.\nOnly returns tasks owned by the specified organization.\n" + "description": "An organization ID.\nOnly returns tasks owned by the specified [organization]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#organization).\n" }, { "in": "query", @@ -12831,7 +12851,7 @@ "inactive" ] }, - "description": "A [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) status.\nOnly returns tasks that have the specified status (`active` or `inactive`).\n" + "description": "A task status.\nOnly returns [tasks]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) that have the specified status.\n" }, { "in": "query", @@ -12868,7 +12888,7 @@ { "in": "query", "name": "sortBy", - "description": "The sort field. Only `name` is supported.\nSpecifies the field used to sort records in the list.\n", + "description": "The sort field.\nSpecifies the task property used to sort records in the list.\nDefault is `name`.\n\nThe parameter has one supported value: `name`.\n", "required": false, "schema": { "type": "string", @@ -12880,7 +12900,7 @@ { "in": "query", "name": "type", - "description": "A [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) type (`basic` or `system`).\nDefault is `system`.\nSpecifies the level of detail for tasks in the response.\nThe default (`system`) response contains all the metadata properties for tasks.\nTo reduce the response size, pass `basic` to omit some task properties (`flux`, `createdAt`, `updatedAt`).\n", + "description": "A task type.\nSpecifies the level of detail for [tasks]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) in the response.\nDefault is `system`.\n\nThe default (`system`) response contains all the metadata properties for tasks.\nTo reduce the response size, set the `type` parameter to `basic` (`type=basic`)\nto omit some task properties (`flux`, `createdAt`, `updatedAt`).\n", "required": false, "schema": { "default": "", @@ -12894,7 +12914,7 @@ { "in": "query", "name": "scriptID", - "description": "A [script](#tag/Invokable-Scripts) ID.\nOnly returns tasks that use the specified invokable script.\n", + "description": "A script ID.\nOnly returns tasks that use the specified [invokable script](#tag/Invokable-Scripts).\n", "schema": { "type": "string" } @@ -13005,26 +13025,34 @@ "Tasks" ], "summary": "Create a task", - "description": "Creates a [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) and returns the task.\n\nUse this endpoint to create a scheduled task that runs a Flux script.\n\n#### InfluxDB Cloud\n\n- You can use either `flux` or `scriptID` to provide the task script.\n\n - `flux`: a string of \"raw\" Flux that contains task options and the script--for example:\n\n ```json\n {\n \"flux\": \"option task = {name: \\\"CPU Total 1 Hour New\\\", every: 1h}\\\n from(bucket: \\\"telegraf\\\")\n |> range(start: -1h)\n |> filter(fn: (r) => (r._measurement == \\\"cpu\\\"))\n |> filter(fn: (r) =>\\n\\t\\t(r._field == \\\"usage_system\\\"))\n |> filter(fn: (r) => (r.cpu == \\\"cpu-total\\\"))\n |> aggregateWindow(every: 1h, fn: max)\n |> to(bucket: \\\"cpu_usage_user_total_1h\\\", org: \\\"INFLUX_ORG\\\")\",\n \"status\": \"active\",\n \"description\": \"This task downsamples CPU data every hour\"\n }\n ```\n\n - `scriptID`: the ID of an [invokable script](#tag/Invokable-Scripts)\n for the task to run.\n To pass task options when using `scriptID`, pass the options as\n properties in the request body--for example:\n\n ```json\n {\n \"name\": \"CPU Total 1 Hour New\",\n \"description\": \"This task downsamples CPU data every hour\",\n \"every\": \"1h\",\n \"scriptID\": \"SCRIPT_ID\",\n \"scriptParameters\":\n {\n \"rangeStart\": \"-1h\",\n \"bucket\": \"telegraf\",\n \"filterField\": \"cpu-total\"\n }\n }\n ```\n\n#### Limitations:\n\n- You can't use `flux` and `scriptID` for the same task.\n\n#### Related guides\n\n- [Get started with tasks]({{% INFLUXDB_DOCS_URL %}}/process-data/get-started/)\n- [Create a task]({{% INFLUXDB_DOCS_URL %}}/process-data/manage-tasks/create-task/)\n- [Common tasks]({{% INFLUXDB_DOCS_URL %}}/process-data/common-tasks/)\n- [Task configuration options]({{% INFLUXDB_DOCS_URL %}}/process-data/task-options/)\n", + "description": "Creates a [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) and returns the task.\n\nUse this endpoint to create a scheduled task that runs a script.\n\n#### Related guides\n\n- [Get started with tasks]({{% INFLUXDB_DOCS_URL %}}/process-data/get-started/)\n- [Create a task]({{% INFLUXDB_DOCS_URL %}}/process-data/manage-tasks/create-task/)\n- [Common tasks]({{% INFLUXDB_DOCS_URL %}}/process-data/common-tasks/)\n- [Task configuration options]({{% INFLUXDB_DOCS_URL %}}/process-data/task-options/)\n", "parameters": [ { "$ref": "#/components/parameters/TraceSpan" } ], "requestBody": { - "description": "Provide a task object in the request body.", + "description": "In the request body, provide the task.\n\nSet one of the following properties to provide the script that the task runs:\n - `flux`\n - `scriptID`\n\nIf you set the `scriptID` property, you can set the following properties to configure the task:\n - `cron`\n - `every`\n - `offset`\n - `scriptParameters`\n\nIf you set the `flux` property, you must provide the `task` configuration option\nin the Flux script.\n\nSee [task configuration options]({{% INFLUXDB_DOCS_URL %}}/process-data/task-options/)\nfor detail and examples.\n\n#### Limitations:\n\n- You can't use `flux` and `scriptID` in the same task.\n", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskCreateRequest" + }, + "examples": { + "TaskWithFlux": { + "$ref": "#/components/examples/TaskWithFluxRequest" + }, + "TaskWithScriptID": { + "$ref": "#/components/examples/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": { @@ -13034,7 +13062,7 @@ } }, "400": { - "description": "Bad request.\nThe response body contains detail about the error.\n\n#### InfluxDB Cloud\n\n- Returns this error if the task doesn't contain one of _`flux`_ or _`scriptID`_.\n- Returns this error if the task contains _`flux`_ _and_ _`scriptID`_.\n", + "description": "Bad request.\nThe response body contains detail about the error.\n\n#### InfluxDB Cloud\n\n- Returns this error if the task doesn't contain the `flux` property\n or the `scriptID` property.\n- Returns this error if the task contains `flux` _and_ `scriptID`\n properties.\n", "content": { "application/json": { "schema": { @@ -13075,19 +13103,7 @@ } } } - }, - "x-codeSamples": [ - { - "lang": "Shell", - "label": "cURL: create a Flux script task", - "source": "curl INFLUX_URL/api/v2/tasks \\\n--header \"Content-type: application/json\" \\\n--header \"Authorization: Token INFLUX_API_TOKEN\" \\\n--data-binary @- << EOF\n {\n \"orgID\": \"INFLUX_ORG_ID\",\n \"description\": \"IoT Center 30d environment average.\",\n \"flux\": \"option task = {name: \\\"iot-center-task-1\\\", every: 30m}\\\n from(bucket: \\\"iot_center\\\")\\\n |> range(start: -30d)\\\n |> filter(fn: (r) => r._measurement == \\\"environment\\\")\\\n |> aggregateWindow(every: 1h, fn: mean)\"\n }\nEOF\n" - }, - { - "lang": "Shell", - "label": "cURL: create a Flux script reference task", - "source": "curl INFLUX_URL/api/v2/tasks \\\n--header \"Content-type: application/json\" \\\n--header \"Authorization: Token INFLUX_API_TOKEN\" \\\n--data-binary @- << EOF\n {\n \"orgID\": \"INFLUX_ORG_ID\",\n \"description\": \"IoT Center 30d environment average.\",\n \"scriptID\": \"085138a111448000\",\n \"scriptParameters\":\n {\n \"rangeStart\": \"-30d\",\n \"bucket\": \"air_sensor\",\n \"filterField\": \"temperature\",\n \"groupColumn\": \"_time\"\n }\n }\nEOF\n" - } - ] + } } }, "/tasks/{taskID}": { @@ -13098,7 +13114,7 @@ "Tasks" ], "summary": "Retrieve a task", - "description": "Retrieves a [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task).\n", + "description": "Retrieves the specified [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task).\n", "parameters": [ { "$ref": "#/components/parameters/TraceSpan" @@ -13110,7 +13126,7 @@ "type": "string" }, "required": true, - "description": "A [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) ID.\nSpecifies the task to retrieve.\n" + "description": "A task ID.\nSpecifies the [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) to retrieve.\n" } ], "responses": { @@ -13147,14 +13163,22 @@ "Tasks" ], "summary": "Update a task", - "description": "Updates a [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task),\nand then cancels all scheduled runs of the task.\n\nUse this endpoint to set, modify, or clear task properties--for example: `cron`, `name`, `flux`, `status`.\nOnce InfluxDB applies the update, it cancels all previously scheduled runs of the task.\n\nTo update a task, pass an object that contains the updated key-value pairs.\nTo activate or inactivate a task, set the `status` property.\n_`\"status\": \"inactive\"`_ cancels scheduled runs and prevents manual runs of the task.\n\n#### InfluxDB Cloud\n\n- Use either `flux` or `scriptID` to provide the task script.\n\n - `flux`: a string of \"raw\" Flux that contains task options and the script--for example:\n\n ```json\n {\n \"flux\": \"option task = {name: \\\"CPU Total 1 Hour New\\\", every: 1h}\\\n from(bucket: \\\"telegraf\\\")\n |> range(start: -1h)\n |> filter(fn: (r) => (r._measurement == \\\"cpu\\\"))\n |> filter(fn: (r) =>\\n\\t\\t(r._field == \\\"usage_system\\\"))\n |> filter(fn: (r) => (r.cpu == \\\"cpu-total\\\"))\n |> aggregateWindow(every: 1h, fn: max)\n |> to(bucket: \\\"cpu_usage_user_total_1h\\\", org: \\\"INFLUX_ORG\\\")\",\n \"status\": \"active\",\n \"description\": \"This task downsamples CPU data every hour\"\n }\n ```\n\n - `scriptID`: the ID of an [invokable script](#tag/Invokable-Scripts)\n for the task to run.\n To pass task options when using `scriptID`, pass the options as\n properties in the request body--for example:\n\n ```json\n {\n \"name\": \"CPU Total 1 Hour New\",\n \"description\": \"This task downsamples CPU data every hour\",\n \"every\": \"1h\",\n \"scriptID\": \"SCRIPT_ID\",\n \"scriptParameters\":\n {\n \"rangeStart\": \"-1h\",\n \"bucket\": \"telegraf\",\n \"filterField\": \"cpu-total\"\n }\n }\n ```\n\n#### Limitations:\n\n- You can't use `flux` and `scriptID` for the same task.\n", + "description": "Updates the specified [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task),\nand then cancels all scheduled runs of the task.\n\nUse this endpoint to set, modify, or clear task properties--for example: `cron`, `name`, `flux`, `status`.\nOnce InfluxDB applies the update, it cancels all previously scheduled runs of the task.\n\nTo activate or inactivate a task, set the `status` property.\nThe `status` property set to `inactive` cancels scheduled runs and prevents manual runs of the task.\n\n#### Related guides\n\n- [Update a task]({{% INFLUXDB_DOCS_URL %}}/process-data/manage-tasks/update-task/)\n- [Task configuration options]({{% INFLUXDB_DOCS_URL %}}/process-data/task-options/)\n", "requestBody": { - "description": "An task update to apply.", + "description": "In the request body, provide the task properties to update.\nTo provide the script that the task runs,\nset either the `flux` property or the `scriptID` property.\n\nIf you set `scriptID`, you can set the following properties to configure the task:\n - `cron`\n - `every`\n - `offset`\n - `scriptParameters`\n\nIf you set the `flux` property, provide the `task` configuration option\nin the Flux script.\n\nSee [task configuration options]({{% INFLUXDB_DOCS_URL %}}/process-data/task-options/)\nfor detail and examples.\n\n#### Limitations:\n\n- You can't set `flux` and `scriptID` properties for the same task--for\n example, if you set the `scriptID` property, then InfluxDB sets the `flux` property\n to an empty string (`\"\"`).\n", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskUpdateRequest" + }, + "examples": { + "TaskWithFlux": { + "$ref": "#/components/examples/TaskWithFluxRequest" + }, + "TaskWithScriptID": { + "$ref": "#/components/examples/TaskWithScriptRequest" + } } } } @@ -13170,7 +13194,7 @@ "type": "string" }, "required": true, - "description": "A [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) ID.\nSpecifies the task to update.\n" + "description": "A task ID.\nSpecifies the [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) to update.\n" } ], "responses": { @@ -13207,7 +13231,7 @@ "Tasks" ], "summary": "Delete a task", - "description": "Deletes a [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) and associated records.\n\nUse this endpoint to delete a task and all associated records (task runs, logs, and labels).\nOnce the task is deleted, InfluxDB cancels all scheduled runs of the task.\n\nIf you want to disable a task instead of delete it, [update the task status to `inactive`](#operation/PatchTasksID).\n", + "description": "Deletes the specified [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task)\nand all associated records (task runs, logs, and labels).\nOnce the task is deleted, InfluxDB cancels all scheduled runs of the task.\n\nTo disable a task instead of delete it, use\n[`PATCH /api/v2/tasks/TASK_ID`](#operation/PatchTasksID) to set the task's `status`\nproperty to `inactive`.\n", "parameters": [ { "$ref": "#/components/parameters/TraceSpan" @@ -13219,7 +13243,7 @@ "type": "string" }, "required": true, - "description": "A [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) ID. Specifies the task to delete." + "description": "A task ID.\nSpecifies the [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) to delete.\n" } ], "responses": { @@ -21926,7 +21950,7 @@ "summary": "A task with Flux", "description": "Sets the `flux` property with Flux task options and a query.", "value": { - "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\")", + "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 contains Flux that configures the task schedule and downsamples CPU data every hour." } diff --git a/contracts/cloud.yml b/contracts/cloud.yml index f738fc86d..ea80266e5 100644 --- a/contracts/cloud.yml +++ b/contracts/cloud.yml @@ -6928,10 +6928,11 @@ paths: - Tasks summary: List runs for a task description: | - Retrieves a list of runs for a [task](https://docs.influxdata.com/influxdb/cloud/process-data/). + Lists runs for the specified [task](https://docs.influxdata.com/influxdb/cloud/process-data/). To limit which task runs are returned, pass query parameters in your request. - If no query parameters are passed, InfluxDB returns all task runs up to the default `limit`. + If you don't pass query parameters, InfluxDB returns all runs for the task + up to the default `limit`. parameters: - $ref: '#/components/parameters/TraceSpan' - in: path @@ -6940,13 +6941,14 @@ paths: type: string required: true description: | - The ID of the task to get runs for. - Only returns runs for this task. + A task ID. + Specifies the [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task) to + to list runs for. - in: query name: after schema: type: string - description: A task run ID. Only returns runs created after this run. + description: A task run ID. Only returns runs created after the specified run. - in: query name: limit schema: @@ -6963,7 +6965,7 @@ paths: format: date-time description: | A timestamp ([RFC3339 date/time format](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#rfc3339-timestamp)). - Only returns runs scheduled after this time. + Only returns runs scheduled after the specified time. - in: query name: beforeTime schema: @@ -6971,7 +6973,7 @@ paths: format: date-time description: | A timestamp ([RFC3339 date/time format](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#rfc3339-timestamp)). - Only returns runs scheduled before this time. + Only returns runs scheduled before the specified time. responses: '200': description: Success. The response body contains the list of task runs. @@ -7000,6 +7002,10 @@ paths: To _retry_ a previous run (and avoid creating a new run), use the [`POST /api/v2/tasks/{taskID}/runs/{runID}/retry` endpoint](#operation/PostTasksIDRunsIDRetry). + + #### Limitations + + - Queuing a task run requires that the task's `status` property be set to `active`. parameters: - $ref: '#/components/parameters/TraceSpan' - in: path @@ -7007,6 +7013,10 @@ paths: schema: type: string required: true + description: | + A task ID. + Specifies the [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task) to + to run. requestBody: content: application/json: @@ -7019,6 +7029,18 @@ paths: application/json: schema: $ref: '#/components/schemas/Run' + '400': + description: Bad request. + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + examples: + inactiveTask: + summary: Can't run an inactive task + value: + code: invalid + message: 'failed to force run: inactive task' '401': $ref: '#/components/responses/AuthorizationError' '500': @@ -7032,7 +7054,7 @@ paths: - Tasks summary: Retrieve a run for a task. description: | - Retrieves a specific run for a [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task). + Retrieves the specified run for the specified [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task). Use this endpoint to retrieve detail and logs for a specific task run. parameters: @@ -7042,13 +7064,16 @@ paths: schema: type: string required: true - description: The ID of the task to retrieve runs for. + description: | + A task ID. + Specifies the [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task) + that the task run belongs to. - in: path name: runID schema: type: string required: true - description: The ID of the run to retrieve. + description: A task run ID. Specifies the run to retrieve. responses: '200': description: Success. The response body contains the task run. @@ -7097,7 +7122,7 @@ paths: description: | Cancels a running [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task). - Use this endpoint with InfluxDB OSS to cancel a running task. + Use this endpoint to cancel a running task. #### InfluxDB Cloud @@ -7109,13 +7134,18 @@ paths: schema: type: string required: true - description: The ID of the task to cancel. + description: | + A task ID. + Specifies the [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task) to + to cancel. - in: path name: runID schema: type: string required: true - description: The ID of the task run to cancel. + description: | + A task run ID. + Specifies the task run to cancel. responses: '204': description: | @@ -7157,15 +7187,15 @@ paths: - Tasks summary: Retry a task run description: | - Queues a [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task) run to - retry and returns the scheduled run. + Queues a [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task) run to + retry and then returns the scheduled run. To manually start a _new_ task run, use the [`POST /api/v2/tasks/{taskID}/runs` endpoint](#operation/PostTasksIDRuns). #### Limitations - - The task must be _active_ (`status: "active"`). + - Queuing a task run requires that the task's `status` property be set to `active`. requestBody: content: application/json; charset=utf-8: @@ -7179,15 +7209,15 @@ paths: type: string required: true description: | - A [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task) ID. - Specifies the task to retry. + A task ID. + Specifies the [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task) that the task run belongs to. - in: path name: runID schema: type: string required: true description: | - A [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task) run ID. + A task run ID. Specifies the task run to retry. To find a task run ID, use the @@ -7245,12 +7275,12 @@ paths: operationId: GetTasksIDLogs tags: - Tasks - summary: Retrieve all logs for a task + summary: List logs for a task description: | - Retrieves a list of all logs for a [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task). + Lists all log events for a [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task). - 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. + When a task runs, InfluxDB creates a `run` record in the task’s history. + Logs associated with each run provide relevant log messages, timestamps, and the exit status of the `run` attempt. Use this endpoint to retrieve only the log events for a task, without additional task metadata. @@ -7261,11 +7291,12 @@ paths: schema: type: string required: true - description: The task ID. + description: 'A task ID. Specifies the [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task) to retrieve logs for.' responses: '200': description: | - Success. The response body contains an `events` list with logs for the task. + Success. + The response body contains an `events` list with logs for the task. Each log event `message` contains detail about the event. If a task run fails, InfluxDB logs an event with the reason for the failure. content: @@ -7274,7 +7305,7 @@ paths: $ref: '#/components/schemas/Logs' examples: taskSuccess: - summary: Events for a successful task run. + summary: Events for a successful task run value: events: - runID: 09b070dadaa7d000 @@ -7284,7 +7315,7 @@ paths: time: '2022-07-18T14:46:07.242859Z' message: Completed(success) taskFailure: - summary: Events for a failed task run. + summary: Events for a failed task run value: events: - runID: 09a946fc3167d000 @@ -7311,12 +7342,12 @@ paths: operationId: GetTasksIDRunsIDLogs tags: - Tasks - summary: Retrieve all logs for a run + summary: List logs for a run description: | - Retrieves all logs for a task run. + Lists all logs for a task run. A log is a list of run events with `runID`, `time`, and `message` properties. - Use this endpoint to help analyze task performance and troubleshoot failed task runs. + Use this endpoint to help analyze [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task) performance and troubleshoot failed task runs. parameters: - $ref: '#/components/parameters/TraceSpan' - in: path @@ -7324,13 +7355,13 @@ paths: schema: type: string required: true - description: The ID of the task to get logs for. + description: 'A task ID. Specifies the [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task) that the run belongs to.' - in: path name: runID schema: type: string required: true - description: The ID of the run to get logs for. + description: A run ID. Specifies the task run to list logs for. responses: '200': description: | @@ -7382,9 +7413,12 @@ paths: - Tasks summary: List labels for a task description: | - Retrieves a list of all labels for a task. + Lists all labels for a task. - Labels may be used for grouping and filtering tasks. + Use this endpoint to list labels applied to a task. + Labels are a way to add metadata to InfluxDB resources. + You can use labels for grouping and filtering resources in the + InfluxDB UI, `influx` CLI, and InfluxDB API. parameters: - $ref: '#/components/parameters/TraceSpan' - in: path @@ -7392,7 +7426,9 @@ paths: schema: type: string required: true - description: The ID of the task to retrieve labels for. + description: | + A task ID. + Specifies the task to retrieve labels for. responses: '200': description: Success. The response body contains a list of all labels for the task. @@ -7416,9 +7452,12 @@ paths: - Tasks summary: Add a label to a task description: | - Adds a label to a task. + Adds a label to a [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task). - Use this endpoint to add a label that you can use to filter tasks in the InfluxDB UI. + Use this endpoint to add a label to a task. + Labels are a way to add metadata to InfluxDB resources. + You can use labels for grouping and filtering resources in the + InfluxDB UI, `influx` CLI, and InfluxDB API. parameters: - $ref: '#/components/parameters/TraceSpan' - in: path @@ -7426,9 +7465,12 @@ paths: schema: type: string required: true - description: The ID of the task to label. + description: | + A task ID. + Specifies the [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task) to label. requestBody: - description: An object that contains a _`labelID`_ to add to the task. + description: | + In the request body, provide an object that specifies the label. required: true content: application/json: @@ -7436,7 +7478,7 @@ paths: $ref: '#/components/schemas/LabelMapping' responses: '201': - description: Success. The response body contains a list of all labels for the task. + description: Success. The response body contains the label. content: application/json: schema: @@ -7458,7 +7500,7 @@ paths: - Tasks summary: Delete a label from a task description: | - Deletes a label from a task. + Deletes a label from a [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task). parameters: - $ref: '#/components/parameters/TraceSpan' - in: path @@ -7466,13 +7508,17 @@ paths: schema: type: string required: true - description: The ID of the task to delete the label from. + description: | + A task ID. + Specifies the [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task) to delete the label from. - in: path name: labelID schema: type: string required: true - description: The ID of the label to delete. + description: | + A label ID. + Specifies the label to delete. responses: '204': description: Success. The label is deleted. @@ -7644,6 +7690,8 @@ paths: description: | **Deprecated**: Tasks don't use `owner` and `member` roles. Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. + + Lists all users that have the `member` role for the specified [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task). parameters: - $ref: '#/components/parameters/TraceSpan' - in: path @@ -7651,12 +7699,16 @@ paths: schema: type: string required: true - description: The task ID. + description: | + A task ID. + Specifies the [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task) to retrieve members for. responses: '200': description: | Success. The response body contains a list of `users` that have the `member` role for a task. + + If the task has no members, the response contains an empty `users` array. content: application/json: schema: @@ -7677,7 +7729,8 @@ paths: **Deprecated**: Tasks don't use `owner` and `member` roles. Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. - Adds a user to members of a task and returns the member. + Adds a specified user to members of the specified [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task) and then returns + the member. parameters: - $ref: '#/components/parameters/TraceSpan' - in: path @@ -7685,9 +7738,12 @@ paths: schema: type: string required: true - description: The task ID. + description: | + A [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task) ID. + Specifies the task for the member. requestBody: - description: A user to add as a member of the task. + description: | + In the request body, provide an object that specifies the user. required: true content: application/json: @@ -7695,7 +7751,10 @@ paths: $ref: '#/components/schemas/AddResourceMemberRequestBody' responses: '201': - description: Created. The user is added to task members. + description: | + Created. The task `member` role is assigned to the user. + The response body contains the resource member with + role and user detail. content: application/json: schema: @@ -7716,6 +7775,8 @@ paths: description: | **Deprecated**: Tasks don't use `owner` and `member` roles. Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. + + Removes a member from a [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task). parameters: - $ref: '#/components/parameters/TraceSpan' - in: path @@ -7723,16 +7784,16 @@ paths: schema: type: string required: true - description: The ID of the member to remove. + description: A user ID. Specifies the member to remove. - in: path name: taskID schema: type: string required: true - description: The task ID. + description: 'A task ID. Specifies the [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task) to remove the member from.' responses: '204': - description: Member removed + description: Success. The member is removed. default: description: Unexpected error content: @@ -7750,7 +7811,7 @@ paths: **Deprecated**: Tasks don't use `owner` and `member` roles. Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. - Retrieves all users that have owner permission for a task. + Lists all users that have the `owner` role for the specified task. parameters: - $ref: '#/components/parameters/TraceSpan' - in: path @@ -7758,7 +7819,7 @@ paths: schema: type: string required: true - description: The ID of the task to retrieve owners for. + description: A task ID. Specifies the task to retrieve owners for. responses: '200': description: | @@ -7802,7 +7863,8 @@ paths: **Deprecated**: Tasks don't use `owner` and `member` roles. Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. - Assigns a task `owner` role to a user. + Adds a specified user to owners of the specified task and then returns the + owner. Use this endpoint to create a _resource owner_ for the task. A _resource owner_ is a user with `role: owner` for a specific resource. @@ -7813,9 +7875,12 @@ paths: schema: type: string required: true - description: The task ID. + description: | + A task ID. + Specifies the [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task) for the owner. requestBody: - description: A user to add as an owner of the task. + description: | + In the request body, provide an object that specifies the user. required: true content: application/json: @@ -7874,6 +7939,8 @@ paths: description: | **Deprecated**: Tasks don't use `owner` and `member` roles. Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. + + Removes an owner from a [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task). parameters: - $ref: '#/components/parameters/TraceSpan' - in: path @@ -7881,16 +7948,18 @@ paths: schema: type: string required: true - description: The ID of the owner to remove. + description: 'A user ID. Specifies the owner to remove from the [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task).' - in: path name: taskID schema: type: string required: true - description: The task ID. + description: | + A task ID. + Specifies the [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task) to remove the owner from. responses: '204': - description: Owner removed + description: Success. The owner is removed. default: description: Unexpected error content: @@ -10317,19 +10386,23 @@ paths: tags: - Data I/O endpoints - Tasks - summary: List all tasks + summary: List tasks description: | - Retrieves a list of [tasks](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task). + Lists [tasks](https://docs.influxdata.com/influxdb/cloud/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](https://docs.influxdata.com/influxdb/cloud/process-data/) parameters: - $ref: '#/components/parameters/TraceSpan' - in: query name: name description: | - A [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task) name. - Only returns tasks with the specified name. + A task name. + Only returns [tasks](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task) with the specified name. Different tasks may have the same name. schema: type: string @@ -10338,29 +10411,29 @@ paths: schema: type: string description: | - A [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task) ID. - Only returns tasks created after the specified task. + A task ID. + Only returns [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task) created after the specified task. - in: query name: user schema: type: string description: | - A [user](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#user) ID. - Only returns tasks owned by the specified user. + A user ID. + Only returns [tasks](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task) owned by the specified [user](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#user). - in: query name: org schema: type: string description: | - An [organization](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#organization) name. - Only returns tasks owned by the specified organization. + An organization name. + Only returns [tasks](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task) owned by the specified [organization](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#organization). - in: query name: orgID schema: type: string description: | - An [organization](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#organization) ID. - Only returns tasks owned by the specified organization. + An organization ID. + Only returns tasks owned by the specified [organization](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#organization). - in: query name: status schema: @@ -10369,8 +10442,8 @@ paths: - active - inactive description: | - A [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task) status. - Only returns tasks that have the specified status (`active` or `inactive`). + A task status. + Only returns [tasks](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task) that have the specified status. - in: query name: limit schema: @@ -10403,8 +10476,11 @@ paths: - 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 @@ -10413,11 +10489,13 @@ paths: - in: query name: type description: | - A [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task) type (`basic` or `system`). + A task type. + Specifies the level of detail for [tasks](https://docs.influxdata.com/influxdb/cloud/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: '' @@ -10428,8 +10506,8 @@ paths: - 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: @@ -10528,52 +10606,7 @@ paths: description: | Creates a [task](https://docs.influxdata.com/influxdb/cloud/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 @@ -10584,15 +10617,41 @@ paths: parameters: - $ref: '#/components/parameters/TraceSpan' requestBody: - description: Provide a task object in the request body. + 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](https://docs.influxdata.com/influxdb/cloud/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: '#/components/schemas/TaskCreateRequest' + examples: + TaskWithFlux: + $ref: '#/components/examples/TaskWithFluxRequest' + TaskWithScriptID: + $ref: '#/components/examples/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: @@ -10604,8 +10663,10 @@ paths: #### 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: @@ -10631,44 +10692,6 @@ paths: application/json: schema: $ref: '#/components/schemas/Error' - 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 '/tasks/{taskID}': get: operationId: GetTasksID @@ -10677,7 +10700,7 @@ paths: - Tasks summary: Retrieve a task description: | - Retrieves a [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task). + Retrieves the specified [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task). parameters: - $ref: '#/components/parameters/TraceSpan' - in: path @@ -10686,8 +10709,8 @@ paths: type: string required: true description: | - A [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task) ID. - Specifies the task to retrieve. + A task ID. + Specifies the [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task) to retrieve. responses: '200': description: Success. The response body contains the task. @@ -10711,67 +10734,52 @@ paths: - Tasks summary: Update a task description: | - Updates a [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task), + Updates the specified [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task), and then cancels all scheduled runs of the task. Use this endpoint to set, modify, or clear task properties--for example: `cron`, `name`, `flux`, `status`. Once InfluxDB applies the update, it cancels all previously scheduled runs of the task. - To update a task, pass 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. + The `status` property set to `inactive` cancels scheduled runs and prevents manual runs of the task. - #### InfluxDB Cloud - - - Use either `flux` or `scriptID` to provide the task script. + #### Related guides - - `flux`: a string of "raw" Flux that contains task options and the script--for example: + - [Update a task](https://docs.influxdata.com/influxdb/cloud/process-data/manage-tasks/update-task/) + - [Task configuration options](https://docs.influxdata.com/influxdb/cloud/process-data/task-options/) + requestBody: + description: | + In the request body, provide the task properties to update. + To provide the script that the task runs, + set either the `flux` property or the `scriptID` property. - ```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" - } - ``` + If you set `scriptID`, you can set the following properties to configure the task: + - `cron` + - `every` + - `offset` + - `scriptParameters` - - `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: + If you set the `flux` property, provide the `task` configuration option + in the Flux script. - ```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" - } - } - ``` + See [task configuration options](https://docs.influxdata.com/influxdb/cloud/process-data/task-options/) + for detail and examples. - #### Limitations: + #### Limitations: - - You can't use `flux` and `scriptID` for the same task. - requestBody: - description: An task update to apply. + - You can't set `flux` and `scriptID` properties for the same task--for + example, if you set the `scriptID` property, then InfluxDB sets the `flux` property + to an empty string (`""`). required: true content: application/json: schema: $ref: '#/components/schemas/TaskUpdateRequest' + examples: + TaskWithFlux: + $ref: '#/components/examples/TaskWithFluxRequest' + TaskWithScriptID: + $ref: '#/components/examples/TaskWithScriptRequest' parameters: - $ref: '#/components/parameters/TraceSpan' - in: path @@ -10780,8 +10788,8 @@ paths: type: string required: true description: | - A [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task) ID. - Specifies the task to update. + A task ID. + Specifies the [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task) to update. responses: '200': description: Success. The response body contains the updated task. @@ -10805,12 +10813,13 @@ paths: - Tasks summary: Delete a task description: | - Deletes a [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task) and associated records. - - Use this endpoint to delete a task and all associated records (task runs, logs, and labels). + Deletes the specified [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task) + and all associated records (task runs, logs, and labels). Once the task is deleted, InfluxDB cancels all scheduled runs of the task. - If you want to disable a task instead of delete it, [update the task status to `inactive`](#operation/PatchTasksID). + To disable a task instead of delete it, use + [`PATCH /api/v2/tasks/TASK_ID`](#operation/PatchTasksID) to set the task's `status` + property to `inactive`. parameters: - $ref: '#/components/parameters/TraceSpan' - in: path @@ -10818,7 +10827,9 @@ paths: schema: type: string required: true - description: 'A [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task) ID. Specifies the task to delete.' + description: | + A task ID. + Specifies the [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task) to delete. responses: '204': description: Success. The task and task runs are deleted. Scheduled runs are canceled. @@ -17103,7 +17114,7 @@ components: summary: A task with Flux description: Sets the `flux` property with Flux task options and a query. value: - 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\")" + 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 contains Flux that configures the task schedule and downsamples CPU data every hour. TaskWithScriptRequest: diff --git a/contracts/common.yml b/contracts/common.yml index 56fdd50a1..dcf366600 100644 --- a/contracts/common.yml +++ b/contracts/common.yml @@ -6639,10 +6639,11 @@ paths: - Tasks summary: List runs for a task description: | - Retrieves a list of runs for a [task](https://docs.influxdata.com/influxdb/v2.3/process-data/). + Lists runs for the specified [task](https://docs.influxdata.com/influxdb/v2.3/process-data/). To limit which task runs are returned, pass query parameters in your request. - If no query parameters are passed, InfluxDB returns all task runs up to the default `limit`. + If you don't pass query parameters, InfluxDB returns all runs for the task + up to the default `limit`. parameters: - $ref: '#/components/parameters/TraceSpan' - in: path @@ -6651,13 +6652,14 @@ paths: type: string required: true description: | - The ID of the task to get runs for. - Only returns runs for this task. + A task ID. + Specifies the [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) to + to list runs for. - in: query name: after schema: type: string - description: A task run ID. Only returns runs created after this run. + description: A task run ID. Only returns runs created after the specified run. - in: query name: limit schema: @@ -6674,7 +6676,7 @@ paths: format: date-time description: | A timestamp ([RFC3339 date/time format](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#rfc3339-timestamp)). - Only returns runs scheduled after this time. + Only returns runs scheduled after the specified time. - in: query name: beforeTime schema: @@ -6682,7 +6684,7 @@ paths: format: date-time description: | A timestamp ([RFC3339 date/time format](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#rfc3339-timestamp)). - Only returns runs scheduled before this time. + Only returns runs scheduled before the specified time. responses: '200': description: Success. The response body contains the list of task runs. @@ -6711,6 +6713,10 @@ paths: To _retry_ a previous run (and avoid creating a new run), use the [`POST /api/v2/tasks/{taskID}/runs/{runID}/retry` endpoint](#operation/PostTasksIDRunsIDRetry). + + #### Limitations + + - Queuing a task run requires that the task's `status` property be set to `active`. parameters: - $ref: '#/components/parameters/TraceSpan' - in: path @@ -6718,6 +6724,10 @@ paths: schema: type: string required: true + description: | + A task ID. + Specifies the [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) to + to run. requestBody: content: application/json: @@ -6730,6 +6740,18 @@ paths: application/json: schema: $ref: '#/components/schemas/Run' + '400': + description: Bad request. + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + examples: + inactiveTask: + summary: Can't run an inactive task + value: + code: invalid + message: 'failed to force run: inactive task' '401': $ref: '#/components/responses/AuthorizationError' '500': @@ -6743,7 +6765,7 @@ paths: - Tasks summary: Retrieve a run for a task. description: | - Retrieves a specific run for a [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task). + Retrieves the specified run for the specified [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task). Use this endpoint to retrieve detail and logs for a specific task run. parameters: @@ -6753,13 +6775,16 @@ paths: schema: type: string required: true - description: The ID of the task to retrieve runs for. + description: | + A task ID. + Specifies the [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) + that the task run belongs to. - in: path name: runID schema: type: string required: true - description: The ID of the run to retrieve. + description: A task run ID. Specifies the run to retrieve. responses: '200': description: Success. The response body contains the task run. @@ -6808,7 +6833,7 @@ paths: description: | Cancels a running [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task). - Use this endpoint with InfluxDB OSS to cancel a running task. + Use this endpoint to cancel a running task. #### InfluxDB Cloud @@ -6820,13 +6845,18 @@ paths: schema: type: string required: true - description: The ID of the task to cancel. + description: | + A task ID. + Specifies the [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) to + to cancel. - in: path name: runID schema: type: string required: true - description: The ID of the task run to cancel. + description: | + A task run ID. + Specifies the task run to cancel. responses: '204': description: | @@ -6868,15 +6898,15 @@ paths: - Tasks summary: Retry a task run description: | - Queues a [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) run to - retry and returns the scheduled run. + Queues a [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) run to + retry and then returns the scheduled run. To manually start a _new_ task run, use the [`POST /api/v2/tasks/{taskID}/runs` endpoint](#operation/PostTasksIDRuns). #### Limitations - - The task must be _active_ (`status: "active"`). + - Queuing a task run requires that the task's `status` property be set to `active`. requestBody: content: application/json; charset=utf-8: @@ -6890,15 +6920,15 @@ paths: type: string required: true description: | - A [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) ID. - Specifies the task to retry. + A task ID. + Specifies the [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) that the task run belongs to. - in: path name: runID schema: type: string required: true description: | - A [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) run ID. + A task run ID. Specifies the task run to retry. To find a task run ID, use the @@ -6956,12 +6986,12 @@ paths: operationId: GetTasksIDLogs tags: - Tasks - summary: Retrieve all logs for a task + summary: List logs for a task description: | - Retrieves a list of all logs for a [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task). + Lists all log events for a [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task). - 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. + When a task runs, InfluxDB creates a `run` record in the task’s history. + Logs associated with each run provide relevant log messages, timestamps, and the exit status of the `run` attempt. Use this endpoint to retrieve only the log events for a task, without additional task metadata. @@ -6972,11 +7002,12 @@ paths: schema: type: string required: true - description: The task ID. + description: 'A task ID. Specifies the [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) to retrieve logs for.' responses: '200': description: | - Success. The response body contains an `events` list with logs for the task. + Success. + The response body contains an `events` list with logs for the task. Each log event `message` contains detail about the event. If a task run fails, InfluxDB logs an event with the reason for the failure. content: @@ -6985,7 +7016,7 @@ paths: $ref: '#/components/schemas/Logs' examples: taskSuccess: - summary: Events for a successful task run. + summary: Events for a successful task run value: events: - runID: 09b070dadaa7d000 @@ -6995,7 +7026,7 @@ paths: time: '2022-07-18T14:46:07.242859Z' message: Completed(success) taskFailure: - summary: Events for a failed task run. + summary: Events for a failed task run value: events: - runID: 09a946fc3167d000 @@ -7022,12 +7053,12 @@ paths: operationId: GetTasksIDRunsIDLogs tags: - Tasks - summary: Retrieve all logs for a run + summary: List logs for a run description: | - Retrieves all logs for a task run. + Lists all logs for a task run. A log is a list of run events with `runID`, `time`, and `message` properties. - Use this endpoint to help analyze task performance and troubleshoot failed task runs. + Use this endpoint to help analyze [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) performance and troubleshoot failed task runs. parameters: - $ref: '#/components/parameters/TraceSpan' - in: path @@ -7035,13 +7066,13 @@ paths: schema: type: string required: true - description: The ID of the task to get logs for. + description: 'A task ID. Specifies the [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) that the run belongs to.' - in: path name: runID schema: type: string required: true - description: The ID of the run to get logs for. + description: A run ID. Specifies the task run to list logs for. responses: '200': description: | @@ -7093,9 +7124,12 @@ paths: - Tasks summary: List labels for a task description: | - Retrieves a list of all labels for a task. + Lists all labels for a task. - Labels may be used for grouping and filtering tasks. + Use this endpoint to list labels applied to a task. + Labels are a way to add metadata to InfluxDB resources. + You can use labels for grouping and filtering resources in the + InfluxDB UI, `influx` CLI, and InfluxDB API. parameters: - $ref: '#/components/parameters/TraceSpan' - in: path @@ -7103,7 +7137,9 @@ paths: schema: type: string required: true - description: The ID of the task to retrieve labels for. + description: | + A task ID. + Specifies the task to retrieve labels for. responses: '200': description: Success. The response body contains a list of all labels for the task. @@ -7127,9 +7163,12 @@ paths: - Tasks summary: Add a label to a task description: | - Adds a label to a task. + Adds a label to a [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task). - Use this endpoint to add a label that you can use to filter tasks in the InfluxDB UI. + Use this endpoint to add a label to a task. + Labels are a way to add metadata to InfluxDB resources. + You can use labels for grouping and filtering resources in the + InfluxDB UI, `influx` CLI, and InfluxDB API. parameters: - $ref: '#/components/parameters/TraceSpan' - in: path @@ -7137,9 +7176,12 @@ paths: schema: type: string required: true - description: The ID of the task to label. + description: | + A task ID. + Specifies the [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) to label. requestBody: - description: An object that contains a _`labelID`_ to add to the task. + description: | + In the request body, provide an object that specifies the label. required: true content: application/json: @@ -7147,7 +7189,7 @@ paths: $ref: '#/components/schemas/LabelMapping' responses: '201': - description: Success. The response body contains a list of all labels for the task. + description: Success. The response body contains the label. content: application/json: schema: @@ -7169,7 +7211,7 @@ paths: - Tasks summary: Delete a label from a task description: | - Deletes a label from a task. + Deletes a label from a [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task). parameters: - $ref: '#/components/parameters/TraceSpan' - in: path @@ -7177,13 +7219,17 @@ paths: schema: type: string required: true - description: The ID of the task to delete the label from. + description: | + A task ID. + Specifies the [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) to delete the label from. - in: path name: labelID schema: type: string required: true - description: The ID of the label to delete. + description: | + A label ID. + Specifies the label to delete. responses: '204': description: Success. The label is deleted. @@ -7355,6 +7401,8 @@ paths: description: | **Deprecated**: Tasks don't use `owner` and `member` roles. Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. + + Lists all users that have the `member` role for the specified [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task). parameters: - $ref: '#/components/parameters/TraceSpan' - in: path @@ -7362,12 +7410,16 @@ paths: schema: type: string required: true - description: The task ID. + description: | + A task ID. + Specifies the [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) to retrieve members for. responses: '200': description: | Success. The response body contains a list of `users` that have the `member` role for a task. + + If the task has no members, the response contains an empty `users` array. content: application/json: schema: @@ -7388,7 +7440,8 @@ paths: **Deprecated**: Tasks don't use `owner` and `member` roles. Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. - Adds a user to members of a task and returns the member. + Adds a specified user to members of the specified [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) and then returns + the member. parameters: - $ref: '#/components/parameters/TraceSpan' - in: path @@ -7396,9 +7449,12 @@ paths: schema: type: string required: true - description: The task ID. + description: | + A [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) ID. + Specifies the task for the member. requestBody: - description: A user to add as a member of the task. + description: | + In the request body, provide an object that specifies the user. required: true content: application/json: @@ -7406,7 +7462,10 @@ paths: $ref: '#/components/schemas/AddResourceMemberRequestBody' responses: '201': - description: Created. The user is added to task members. + description: | + Created. The task `member` role is assigned to the user. + The response body contains the resource member with + role and user detail. content: application/json: schema: @@ -7427,6 +7486,8 @@ paths: description: | **Deprecated**: Tasks don't use `owner` and `member` roles. Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. + + Removes a member from a [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task). parameters: - $ref: '#/components/parameters/TraceSpan' - in: path @@ -7434,16 +7495,16 @@ paths: schema: type: string required: true - description: The ID of the member to remove. + description: A user ID. Specifies the member to remove. - in: path name: taskID schema: type: string required: true - description: The task ID. + description: 'A task ID. Specifies the [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) to remove the member from.' responses: '204': - description: Member removed + description: Success. The member is removed. default: description: Unexpected error content: @@ -7461,7 +7522,7 @@ paths: **Deprecated**: Tasks don't use `owner` and `member` roles. Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. - Retrieves all users that have owner permission for a task. + Lists all users that have the `owner` role for the specified task. parameters: - $ref: '#/components/parameters/TraceSpan' - in: path @@ -7469,7 +7530,7 @@ paths: schema: type: string required: true - description: The ID of the task to retrieve owners for. + description: A task ID. Specifies the task to retrieve owners for. responses: '200': description: | @@ -7513,7 +7574,8 @@ paths: **Deprecated**: Tasks don't use `owner` and `member` roles. Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. - Assigns a task `owner` role to a user. + Adds a specified user to owners of the specified task and then returns the + owner. Use this endpoint to create a _resource owner_ for the task. A _resource owner_ is a user with `role: owner` for a specific resource. @@ -7524,9 +7586,12 @@ paths: schema: type: string required: true - description: The task ID. + description: | + A task ID. + Specifies the [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) for the owner. requestBody: - description: A user to add as an owner of the task. + description: | + In the request body, provide an object that specifies the user. required: true content: application/json: @@ -7585,6 +7650,8 @@ paths: description: | **Deprecated**: Tasks don't use `owner` and `member` roles. Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. + + Removes an owner from a [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task). parameters: - $ref: '#/components/parameters/TraceSpan' - in: path @@ -7592,16 +7659,18 @@ paths: schema: type: string required: true - description: The ID of the owner to remove. + description: 'A user ID. Specifies the owner to remove from the [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task).' - in: path name: taskID schema: type: string required: true - description: The task ID. + description: | + A task ID. + Specifies the [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) to remove the owner from. responses: '204': - description: Owner removed + description: Success. The owner is removed. default: description: Unexpected error content: diff --git a/contracts/oss-diff.yml b/contracts/oss-diff.yml index c46a1e4f2..1f634a0b0 100644 --- a/contracts/oss-diff.yml +++ b/contracts/oss-diff.yml @@ -5054,7 +5054,7 @@ paths: - 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`. @@ -5067,8 +5067,9 @@ paths: - 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) + that have the specified name. Different tasks may have the same name. schema: type: string @@ -5077,29 +5078,31 @@ paths: 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 [tasks]({{% 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 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]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) owned by the specified [organization]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#organization). + required: true - in: query name: status schema: @@ -5108,8 +5111,8 @@ paths: - 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: @@ -5127,9 +5130,9 @@ paths: - 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`). required: false @@ -5259,7 +5262,9 @@ paths: - Tasks summary: Create a task description: | - Creates a [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) and returns the task. + Creates a [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) and returns the task. + + Use this endpoint to create a scheduled task that runs a script. #### Related guides @@ -5270,12 +5275,20 @@ paths: parameters: - $ref: '#/paths/~1ready/get/parameters/0' requestBody: - description: Provide a task object in the request body. + description: | + In the request body, provide the task. + + #### InfluxDB OSS + + - Requires either the `org` parameter or the `orgID` parameter. required: true content: application/json: schema: $ref: '#/components/schemas/TaskCreateRequest' + examples: + TaskWithFlux: + $ref: '#/components/examples/TaskWithFluxRequest' responses: '201': description: Success. The response body contains a `tasks` list with the task. @@ -5297,12 +5310,12 @@ paths: $ref: '#/paths/~1users/get/responses/401/content/application~1json/schema' examples: orgProvidedNotFound: - summary: The org or orgID passed doesn't own the token passed in the header + summary: The organization specified by org or orgID doesn't own the token passed in the header value: code: invalid message: 'failed to decode request body: organization not found' missingFluxError: - summary: Task in request body is missing Flux query + summary: The request body doesn't contain a Flux query value: code: invalid message: 'failed to decode request: missing flux' @@ -5316,24 +5329,6 @@ paths: application/json: schema: $ref: '#/paths/~1users/get/responses/401/content/application~1json/schema' - x-codeSamples: - - lang: Shell - label: 'cURL: create a task' - source: | - curl http://localhost:8086/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 '/tasks/{taskID}': get: operationId: GetTasksID @@ -5342,7 +5337,7 @@ paths: - Tasks summary: Retrieve a task description: | - Retrieves a [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task). + Retrieves the specified [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task). parameters: - $ref: '#/paths/~1ready/get/parameters/0' - in: path @@ -5350,7 +5345,9 @@ paths: schema: type: string required: true - description: The ID of the task to retrieve. + description: | + A task ID. + Specifies the [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) to retrieve. responses: '200': description: Success. The response body contains the task. @@ -5418,21 +5415,27 @@ paths: - Tasks summary: Update a task description: | - Updates a task and then cancels all scheduled runs of the task. + Updates the specified [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task), + and then cancels all scheduled runs of the task. - Use this endpoint to set, modify, and clear task properties (for example: `cron`, `name`, `flux`, `status`). + Use this endpoint to set, modify, or clear task properties--for example: `cron`, `name`, `flux`, `status`. Once InfluxDB applies the update, it cancels all previously scheduled runs of the task. - To update a task, pass 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. + #### Related guides + + - [Update a task]({{% INFLUXDB_DOCS_URL %}}/process-data/manage-tasks/update-task/) + - [Task configuration options]({{% INFLUXDB_DOCS_URL %}}/process-data/task-options/) requestBody: - description: An object that contains updated task properties to apply. + description: | + In the request body, provide the task properties to update. required: true content: application/json: schema: $ref: '#/components/schemas/TaskUpdateRequest' + examples: + TaskWithFlux: + $ref: '#/components/examples/TaskWithFluxRequest' parameters: - $ref: '#/paths/~1ready/get/parameters/0' - in: path @@ -5440,7 +5443,9 @@ paths: schema: type: string required: true - description: The ID of the task to update. + description: | + A task ID. + Specifies the [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task)to update. responses: '200': description: Success. The response body contains the updated task. @@ -5464,12 +5469,13 @@ paths: - Tasks summary: Delete a task description: | - Deletes a task and associated records. - - Use this endpoint to delete a task and all associated records (task runs, logs, and labels). + Deletes the specified [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) + and all associated records (task runs, logs, and labels). Once the task is deleted, InfluxDB cancels all scheduled runs of the task. - If you want to disable a task instead of delete it, [update the task status to `inactive`](#operation/PatchTasksID). + To disable a task instead of delete it, use + [`PATCH /api/v2/tasks/TASK_ID`](#operation/PatchTasksID) to set the task status + to `inactive`. parameters: - $ref: '#/paths/~1ready/get/parameters/0' - in: path @@ -5477,7 +5483,9 @@ paths: schema: type: string required: true - description: The ID of the task to delete. + description: | + A task ID. + Specifies the [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) to delete. responses: '204': description: Success. The task and runs are deleted. Scheduled runs are canceled. @@ -6657,7 +6665,7 @@ components: summary: A task with Flux description: Sets the `flux` property with Flux task options and a query. value: - 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\")" + 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 contains Flux that configures the task schedule and downsamples CPU data every hour. securitySchemes: diff --git a/contracts/oss.json b/contracts/oss.json index 891f3119b..7810f447b 100644 --- a/contracts/oss.json +++ b/contracts/oss.json @@ -8266,7 +8266,7 @@ "Tasks" ], "summary": "List runs for a task", - "description": "Retrieves a list of runs for a [task]({{% INFLUXDB_DOCS_URL %}}/process-data/).\n\nTo limit which task runs are returned, pass query parameters in your request.\nIf no query parameters are passed, InfluxDB returns all task runs up to the default `limit`.\n", + "description": "Lists runs for the specified [task]({{% INFLUXDB_DOCS_URL %}}/process-data/).\n\nTo limit which task runs are returned, pass query parameters in your request.\nIf you don't pass query parameters, InfluxDB returns all runs for the task\nup to the default `limit`.\n", "parameters": [ { "$ref": "#/components/parameters/TraceSpan" @@ -8278,7 +8278,7 @@ "type": "string" }, "required": true, - "description": "The ID of the task to get runs for.\nOnly returns runs for this task.\n" + "description": "A task ID.\nSpecifies the [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) to\nto list runs for.\n" }, { "in": "query", @@ -8286,7 +8286,7 @@ "schema": { "type": "string" }, - "description": "A task run ID. Only returns runs created after this run." + "description": "A task run ID. Only returns runs created after the specified run." }, { "in": "query", @@ -8306,7 +8306,7 @@ "type": "string", "format": "date-time" }, - "description": "A timestamp ([RFC3339 date/time format]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#rfc3339-timestamp)).\nOnly returns runs scheduled after this time.\n" + "description": "A timestamp ([RFC3339 date/time format]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#rfc3339-timestamp)).\nOnly returns runs scheduled after the specified time.\n" }, { "in": "query", @@ -8315,7 +8315,7 @@ "type": "string", "format": "date-time" }, - "description": "A timestamp ([RFC3339 date/time format]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#rfc3339-timestamp)).\nOnly returns runs scheduled before this time.\n" + "description": "A timestamp ([RFC3339 date/time format]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#rfc3339-timestamp)).\nOnly returns runs scheduled before the specified time.\n" } ], "responses": { @@ -8347,7 +8347,7 @@ "Tasks" ], "summary": "Start a task run, overriding the schedule", - "description": "Schedules a task run to start immediately, ignoring scheduled runs.\n\nUse this endpoint to manually start a task run.\nScheduled runs will continue to run as scheduled.\nThis may result in concurrently running tasks.\n\nTo _retry_ a previous run (and avoid creating a new run),\nuse the [`POST /api/v2/tasks/{taskID}/runs/{runID}/retry` endpoint](#operation/PostTasksIDRunsIDRetry).\n", + "description": "Schedules a task run to start immediately, ignoring scheduled runs.\n\nUse this endpoint to manually start a task run.\nScheduled runs will continue to run as scheduled.\nThis may result in concurrently running tasks.\n\nTo _retry_ a previous run (and avoid creating a new run),\nuse the [`POST /api/v2/tasks/{taskID}/runs/{runID}/retry` endpoint](#operation/PostTasksIDRunsIDRetry).\n\n#### Limitations\n\n- Queuing a task run requires that the task's `status` property be set to `active`.\n", "parameters": [ { "$ref": "#/components/parameters/TraceSpan" @@ -8358,7 +8358,8 @@ "schema": { "type": "string" }, - "required": true + "required": true, + "description": "A task ID.\nSpecifies the [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) to\nto run.\n" } ], "requestBody": { @@ -8381,6 +8382,25 @@ } } }, + "400": { + "description": "Bad request.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + }, + "examples": { + "inactiveTask": { + "summary": "Can't run an inactive task", + "value": { + "code": "invalid", + "message": "failed to force run: inactive task" + } + } + } + } + } + }, "401": { "$ref": "#/components/responses/AuthorizationError" }, @@ -8400,7 +8420,7 @@ "Tasks" ], "summary": "Retrieve a run for a task.", - "description": "Retrieves a specific run for a [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task).\n\nUse this endpoint to retrieve detail and logs for a specific task run.\n", + "description": "Retrieves the specified run for the specified [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task).\n\nUse this endpoint to retrieve detail and logs for a specific task run.\n", "parameters": [ { "$ref": "#/components/parameters/TraceSpan" @@ -8412,7 +8432,7 @@ "type": "string" }, "required": true, - "description": "The ID of the task to retrieve runs for." + "description": "A task ID.\nSpecifies the [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task)\nthat the task run belongs to.\n" }, { "in": "path", @@ -8421,7 +8441,7 @@ "type": "string" }, "required": true, - "description": "The ID of the run to retrieve." + "description": "A task run ID. Specifies the run to retrieve." } ], "responses": { @@ -8490,7 +8510,7 @@ "Tasks" ], "summary": "Cancel a running task", - "description": "Cancels a running [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task).\n\nUse this endpoint with InfluxDB OSS to cancel a running task.\n\n#### InfluxDB Cloud\n\n- Doesn't support this operation.\n", + "description": "Cancels a running [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task).\n\nUse this endpoint to cancel a running task.\n\n#### InfluxDB Cloud\n\n- Doesn't support this operation.\n", "parameters": [ { "$ref": "#/components/parameters/TraceSpan" @@ -8502,7 +8522,7 @@ "type": "string" }, "required": true, - "description": "The ID of the task to cancel." + "description": "A task ID.\nSpecifies the [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) to\nto cancel.\n" }, { "in": "path", @@ -8511,7 +8531,7 @@ "type": "string" }, "required": true, - "description": "The ID of the task run to cancel." + "description": "A task run ID.\nSpecifies the task run to cancel.\n" } ], "responses": { @@ -8553,7 +8573,7 @@ "Tasks" ], "summary": "Retry a task run", - "description": "Queues a [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) run to\nretry and returns the scheduled run.\n\nTo manually start a _new_ task run, use the\n[`POST /api/v2/tasks/{taskID}/runs` endpoint](#operation/PostTasksIDRuns).\n\n#### Limitations\n\n- The task must be _active_ (`status: \"active\"`).\n", + "description": "Queues a [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) run to\nretry and then returns the scheduled run.\n\nTo manually start a _new_ task run, use the\n[`POST /api/v2/tasks/{taskID}/runs` endpoint](#operation/PostTasksIDRuns).\n\n#### Limitations\n\n- Queuing a task run requires that the task's `status` property be set to `active`.\n", "requestBody": { "content": { "application/json; charset=utf-8": { @@ -8574,7 +8594,7 @@ "type": "string" }, "required": true, - "description": "A [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) ID.\nSpecifies the task to retry.\n" + "description": "A task ID.\nSpecifies the [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) that the task run belongs to.\n" }, { "in": "path", @@ -8583,7 +8603,7 @@ "type": "string" }, "required": true, - "description": "A [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) run ID.\nSpecifies the task run to retry.\n\nTo find a task run ID, use the\n[`GET /api/v2/tasks/{taskID}/runs` endpoint](#operation/GetTasksIDRuns)\nto list task runs.\n" + "description": "A task run ID.\nSpecifies the task run to retry.\n\nTo find a task run ID, use the\n[`GET /api/v2/tasks/{taskID}/runs` endpoint](#operation/GetTasksIDRuns)\nto list task runs.\n" } ], "responses": { @@ -8655,8 +8675,8 @@ "tags": [ "Tasks" ], - "summary": "Retrieve all logs for a task", - "description": "Retrieves a list of all logs for a [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task).\n\nWhen an InfluxDB task runs, a “run” record is created in the task’s history.\nLogs associated with each run provide relevant log messages, timestamps, and the exit status of the run attempt.\n\nUse this endpoint to retrieve only the log events for a task,\nwithout additional task metadata.\n", + "summary": "List logs for a task", + "description": "Lists all log events for a [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task).\n\nWhen a task runs, InfluxDB creates a `run` record in the task’s history.\nLogs associated with each run provide relevant log messages, timestamps, and the exit status of the `run` attempt.\n\nUse this endpoint to retrieve only the log events for a task,\nwithout additional task metadata.\n", "parameters": [ { "$ref": "#/components/parameters/TraceSpan" @@ -8668,12 +8688,12 @@ "type": "string" }, "required": true, - "description": "The task ID." + "description": "A task ID. Specifies the [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) to retrieve logs for." } ], "responses": { "200": { - "description": "Success. The response body contains an `events` list with logs for the task.\nEach log event `message` contains detail about the event.\nIf a task run fails, InfluxDB logs an event with the reason for the failure.\n", + "description": "Success.\nThe response body contains an `events` list with logs for the task.\nEach log event `message` contains detail about the event.\nIf a task run fails, InfluxDB logs an event with the reason for the failure.\n", "content": { "application/json": { "schema": { @@ -8681,7 +8701,7 @@ }, "examples": { "taskSuccess": { - "summary": "Events for a successful task run.", + "summary": "Events for a successful task run", "value": { "events": [ { @@ -8698,7 +8718,7 @@ } }, "taskFailure": { - "summary": "Events for a failed task run.", + "summary": "Events for a failed task run", "value": { "events": [ { @@ -8747,8 +8767,8 @@ "tags": [ "Tasks" ], - "summary": "Retrieve all logs for a run", - "description": "Retrieves all logs for a task run.\nA log is a list of run events with `runID`, `time`, and `message` properties.\n\nUse this endpoint to help analyze task performance and troubleshoot failed task runs.\n", + "summary": "List logs for a run", + "description": "Lists all logs for a task run.\nA log is a list of run events with `runID`, `time`, and `message` properties.\n\nUse this endpoint to help analyze [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) performance and troubleshoot failed task runs.\n", "parameters": [ { "$ref": "#/components/parameters/TraceSpan" @@ -8760,7 +8780,7 @@ "type": "string" }, "required": true, - "description": "The ID of the task to get logs for." + "description": "A task ID. Specifies the [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) that the run belongs to." }, { "in": "path", @@ -8769,7 +8789,7 @@ "type": "string" }, "required": true, - "description": "The ID of the run to get logs for." + "description": "A run ID. Specifies the task run to list logs for." } ], "responses": { @@ -8849,7 +8869,7 @@ "Tasks" ], "summary": "List labels for a task", - "description": "Retrieves a list of all labels for a task.\n\nLabels may be used for grouping and filtering tasks.\n", + "description": "Lists all labels for a task.\n\nUse this endpoint to list labels applied to a task.\nLabels are a way to add metadata to InfluxDB resources.\nYou can use labels for grouping and filtering resources in the\nInfluxDB UI, `influx` CLI, and InfluxDB API.\n", "parameters": [ { "$ref": "#/components/parameters/TraceSpan" @@ -8861,7 +8881,7 @@ "type": "string" }, "required": true, - "description": "The ID of the task to retrieve labels for." + "description": "A task ID.\nSpecifies the task to retrieve labels for.\n" } ], "responses": { @@ -8898,7 +8918,7 @@ "Tasks" ], "summary": "Add a label to a task", - "description": "Adds a label to a task.\n\nUse this endpoint to add a label that you can use to filter tasks in the InfluxDB UI.\n", + "description": "Adds a label to a [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task).\n\nUse this endpoint to add a label to a task.\nLabels are a way to add metadata to InfluxDB resources.\nYou can use labels for grouping and filtering resources in the\nInfluxDB UI, `influx` CLI, and InfluxDB API.\n", "parameters": [ { "$ref": "#/components/parameters/TraceSpan" @@ -8910,11 +8930,11 @@ "type": "string" }, "required": true, - "description": "The ID of the task to label." + "description": "A task ID.\nSpecifies the [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) to label.\n" } ], "requestBody": { - "description": "An object that contains a _`labelID`_ to add to the task.", + "description": "In the request body, provide an object that specifies the label.\n", "required": true, "content": { "application/json": { @@ -8926,7 +8946,7 @@ }, "responses": { "201": { - "description": "Success. The response body contains a list of all labels for the task.", + "description": "Success. The response body contains the label.", "content": { "application/json": { "schema": { @@ -8960,7 +8980,7 @@ "Tasks" ], "summary": "Delete a label from a task", - "description": "Deletes a label from a task.\n", + "description": "Deletes a label from a [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task).\n", "parameters": [ { "$ref": "#/components/parameters/TraceSpan" @@ -8972,7 +8992,7 @@ "type": "string" }, "required": true, - "description": "The ID of the task to delete the label from." + "description": "A task ID.\nSpecifies the [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) to delete the label from.\n" }, { "in": "path", @@ -8981,7 +9001,7 @@ "type": "string" }, "required": true, - "description": "The ID of the label to delete." + "description": "A label ID.\nSpecifies the label to delete.\n" } ], "responses": { @@ -9154,7 +9174,7 @@ "Tasks" ], "summary": "List all task members", - "description": "**Deprecated**: Tasks don't use `owner` and `member` roles.\nUse [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions.\n", + "description": "**Deprecated**: Tasks don't use `owner` and `member` roles.\nUse [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions.\n\nLists all users that have the `member` role for the specified [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task).\n", "parameters": [ { "$ref": "#/components/parameters/TraceSpan" @@ -9166,12 +9186,12 @@ "type": "string" }, "required": true, - "description": "The task ID." + "description": "A task ID.\nSpecifies the [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) to retrieve members for.\n" } ], "responses": { "200": { - "description": "Success. The response body contains a list of `users` that have\nthe `member` role for a task.\n", + "description": "Success. The response body contains a list of `users` that have\nthe `member` role for a task.\n\nIf the task has no members, the response contains an empty `users` array.\n", "content": { "application/json": { "schema": { @@ -9199,7 +9219,7 @@ "Tasks" ], "summary": "Add a member to a task", - "description": "**Deprecated**: Tasks don't use `owner` and `member` roles.\nUse [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions.\n\nAdds a user to members of a task and returns the member.\n", + "description": "**Deprecated**: Tasks don't use `owner` and `member` roles.\nUse [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions.\n\nAdds a specified user to members of the specified [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) and then returns\nthe member.\n", "parameters": [ { "$ref": "#/components/parameters/TraceSpan" @@ -9211,11 +9231,11 @@ "type": "string" }, "required": true, - "description": "The task ID." + "description": "A [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) ID.\nSpecifies the task for the member.\n" } ], "requestBody": { - "description": "A user to add as a member of the task.", + "description": "In the request body, provide an object that specifies the user.\n", "required": true, "content": { "application/json": { @@ -9227,7 +9247,7 @@ }, "responses": { "201": { - "description": "Created. The user is added to task members.", + "description": "Created. The task `member` role is assigned to the user.\nThe response body contains the resource member with\nrole and user detail.\n", "content": { "application/json": { "schema": { @@ -9257,7 +9277,7 @@ "Tasks" ], "summary": "Remove a member from a task", - "description": "**Deprecated**: Tasks don't use `owner` and `member` roles.\nUse [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions.\n", + "description": "**Deprecated**: Tasks don't use `owner` and `member` roles.\nUse [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions.\n\nRemoves a member from a [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task).\n", "parameters": [ { "$ref": "#/components/parameters/TraceSpan" @@ -9269,7 +9289,7 @@ "type": "string" }, "required": true, - "description": "The ID of the member to remove." + "description": "A user ID. Specifies the member to remove." }, { "in": "path", @@ -9278,12 +9298,12 @@ "type": "string" }, "required": true, - "description": "The task ID." + "description": "A task ID. Specifies the [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) to remove the member from." } ], "responses": { "204": { - "description": "Member removed" + "description": "Success. The member is removed." }, "default": { "description": "Unexpected error", @@ -9306,7 +9326,7 @@ "Tasks" ], "summary": "List all owners of a task", - "description": "**Deprecated**: Tasks don't use `owner` and `member` roles.\nUse [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions.\n\nRetrieves all users that have owner permission for a task.\n", + "description": "**Deprecated**: Tasks don't use `owner` and `member` roles.\nUse [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions.\n\nLists all users that have the `owner` role for the specified task.\n", "parameters": [ { "$ref": "#/components/parameters/TraceSpan" @@ -9318,7 +9338,7 @@ "type": "string" }, "required": true, - "description": "The ID of the task to retrieve owners for." + "description": "A task ID. Specifies the task to retrieve owners for." } ], "responses": { @@ -9367,7 +9387,7 @@ "Tasks" ], "summary": "Add an owner for a task", - "description": "**Deprecated**: Tasks don't use `owner` and `member` roles.\nUse [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions.\n\nAssigns a task `owner` role to a user.\n\nUse this endpoint to create a _resource owner_ for the task.\nA _resource owner_ is a user with `role: owner` for a specific resource.\n", + "description": "**Deprecated**: Tasks don't use `owner` and `member` roles.\nUse [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions.\n\nAdds a specified user to owners of the specified task and then returns the\nowner.\n\nUse this endpoint to create a _resource owner_ for the task.\nA _resource owner_ is a user with `role: owner` for a specific resource.\n", "parameters": [ { "$ref": "#/components/parameters/TraceSpan" @@ -9379,11 +9399,11 @@ "type": "string" }, "required": true, - "description": "The task ID." + "description": "A task ID.\nSpecifies the [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) for the owner.\n" } ], "requestBody": { - "description": "A user to add as an owner of the task.", + "description": "In the request body, provide an object that specifies the user.\n", "required": true, "content": { "application/json": { @@ -9456,7 +9476,7 @@ "Tasks" ], "summary": "Remove an owner from a task", - "description": "**Deprecated**: Tasks don't use `owner` and `member` roles.\nUse [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions.\n", + "description": "**Deprecated**: Tasks don't use `owner` and `member` roles.\nUse [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions.\n\nRemoves an owner from a [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task).\n", "parameters": [ { "$ref": "#/components/parameters/TraceSpan" @@ -9468,7 +9488,7 @@ "type": "string" }, "required": true, - "description": "The ID of the owner to remove." + "description": "A user ID. Specifies the owner to remove from the [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task)." }, { "in": "path", @@ -9477,12 +9497,12 @@ "type": "string" }, "required": true, - "description": "The task ID." + "description": "A task ID.\nSpecifies the [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) to remove the owner from.\n" } ], "responses": { "204": { - "description": "Owner removed" + "description": "Success. The owner is removed." }, "default": { "description": "Unexpected error", @@ -15199,7 +15219,7 @@ "Tasks" ], "summary": "List tasks", - "description": "Retrieves a list of [tasks]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task).\n\nTo limit which tasks are returned, pass query parameters in your request.\nIf no query parameters are passed, InfluxDB returns all tasks up to the default `limit`.\n\n#### Related guide\n\n- [Process data with InfluxDB tasks]({{% INFLUXDB_DOCS_URL %}}/process-data/)\n", + "description": "Lists [tasks]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task).\n\nTo limit which tasks are returned, pass query parameters in your request.\nIf no query parameters are passed, InfluxDB returns all tasks up to the default `limit`.\n\n#### Related guide\n\n- [Process data with InfluxDB tasks]({{% INFLUXDB_DOCS_URL %}}/process-data/)\n", "parameters": [ { "$ref": "#/components/parameters/TraceSpan" @@ -15207,7 +15227,7 @@ { "in": "query", "name": "name", - "description": "A [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) name.\nOnly returns tasks with the specified name.\nDifferent tasks may have the same name.\n", + "description": "A task name.\nOnly returns [tasks]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task)\nthat have the specified name.\nDifferent tasks may have the same name.\n", "schema": { "type": "string" } @@ -15218,7 +15238,7 @@ "schema": { "type": "string" }, - "description": "A [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) ID.\nOnly returns tasks created after the specified task.\n" + "description": "A task ID.\nOnly returns [tasks]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) created after the specified task.\n" }, { "in": "query", @@ -15226,7 +15246,7 @@ "schema": { "type": "string" }, - "description": "A [user]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#user) ID.\nOnly returns tasks owned by the specified user.\n" + "description": "A user ID.\nOnly returns [tasks]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task)\nowned by the specified [user]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#user).\n" }, { "in": "query", @@ -15234,7 +15254,7 @@ "schema": { "type": "string" }, - "description": "An [organization]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#organization) name.\nOnly returns tasks owned by the specified organization.\n" + "description": "An organization name.\nOnly returns tasks owned by the specified [organization]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#organization).\n" }, { "in": "query", @@ -15242,7 +15262,8 @@ "schema": { "type": "string" }, - "description": "An [organization]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#organization) ID.\nOnly returns tasks owned by the specified organization.\n" + "description": "An organization ID.\nOnly returns [tasks]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) owned by the specified [organization]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#organization).\n", + "required": true }, { "in": "query", @@ -15254,7 +15275,7 @@ "inactive" ] }, - "description": "A [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) status.\nOnly returns tasks that have the specified status (`active` or `inactive`).\n" + "description": "A task status.\nOnly returns [tasks]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) that have the specified status.\n" }, { "in": "query", @@ -15270,7 +15291,7 @@ { "in": "query", "name": "type", - "description": "A [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) type (`basic` or `system`).\nDefault is `system`.\nSpecifies the level of detail for tasks in the response.\nThe default (`system`) response contains all the metadata properties for tasks.\nTo reduce the response size, pass `basic` to omit some task properties (`flux`, `createdAt`, `updatedAt`).\n", + "description": "A task type.\nSpecifies the level of detail for [tasks]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) in the response.\nDefault is `system`.\nThe default (`system`) response contains all the metadata properties for tasks.\nTo reduce the response size, pass `basic` to omit some task properties (`flux`, `createdAt`, `updatedAt`).\n", "required": false, "schema": { "default": "", @@ -15387,19 +15408,24 @@ "Tasks" ], "summary": "Create a task", - "description": "Creates a [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) and returns the task.\n\n#### Related guides\n\n- [Get started with tasks]({{% INFLUXDB_DOCS_URL %}}/process-data/get-started/)\n- [Create a task]({{% INFLUXDB_DOCS_URL %}}/process-data/manage-tasks/create-task/)\n- [Common tasks]({{% INFLUXDB_DOCS_URL %}}/process-data/common-tasks/)\n- [Task configuration options]({{% INFLUXDB_DOCS_URL %}}/process-data/task-options/)\n", + "description": "Creates a [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) and returns the task.\n\nUse this endpoint to create a scheduled task that runs a script.\n\n#### Related guides\n\n- [Get started with tasks]({{% INFLUXDB_DOCS_URL %}}/process-data/get-started/)\n- [Create a task]({{% INFLUXDB_DOCS_URL %}}/process-data/manage-tasks/create-task/)\n- [Common tasks]({{% INFLUXDB_DOCS_URL %}}/process-data/common-tasks/)\n- [Task configuration options]({{% INFLUXDB_DOCS_URL %}}/process-data/task-options/)\n", "parameters": [ { "$ref": "#/components/parameters/TraceSpan" } ], "requestBody": { - "description": "Provide a task object in the request body.", + "description": "In the request body, provide the task.\n\n#### InfluxDB OSS\n\n- Requires either the `org` parameter or the `orgID` parameter.\n", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskCreateRequest" + }, + "examples": { + "TaskWithFlux": { + "$ref": "#/components/examples/TaskWithFluxRequest" + } } } } @@ -15424,14 +15450,14 @@ }, "examples": { "orgProvidedNotFound": { - "summary": "The org or orgID passed doesn't own the token passed in the header", + "summary": "The organization specified by org or orgID doesn't own the token passed in the header", "value": { "code": "invalid", "message": "failed to decode request body: organization not found" } }, "missingFluxError": { - "summary": "Task in request body is missing Flux query", + "summary": "The request body doesn't contain a Flux query", "value": { "code": "invalid", "message": "failed to decode request: missing flux" @@ -15457,14 +15483,7 @@ } } } - }, - "x-codeSamples": [ - { - "lang": "Shell", - "label": "cURL: create a task", - "source": "curl http://localhost:8086/api/v2/tasks \\\n --header \"Content-type: application/json\" \\\n --header \"Authorization: Token INFLUX_API_TOKEN\" \\\n --data-binary @- << EOF\n {\n \"orgID\": \"INFLUX_ORG_ID\",\n \"description\": \"IoT Center 30d environment average.\",\n \"flux\": \"option task = {name: \\\"iot-center-task-1\\\", every: 30m}\\\n from(bucket: \\\"iot_center\\\")\\\n |> range(start: -30d)\\\n |> filter(fn: (r) => r._measurement == \\\"environment\\\")\\\n |> aggregateWindow(every: 1h, fn: mean)\"\n }\nEOF\n" - } - ] + } } }, "/tasks/{taskID}": { @@ -15475,7 +15494,7 @@ "Tasks" ], "summary": "Retrieve a task", - "description": "Retrieves a [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task).\n", + "description": "Retrieves the specified [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task).\n", "parameters": [ { "$ref": "#/components/parameters/TraceSpan" @@ -15487,7 +15506,7 @@ "type": "string" }, "required": true, - "description": "The ID of the task to retrieve." + "description": "A task ID.\nSpecifies the [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) to retrieve.\n" } ], "responses": { @@ -15524,14 +15543,19 @@ "Tasks" ], "summary": "Update a task", - "description": "Updates a task and then cancels all scheduled runs of the task.\n\nUse this endpoint to set, modify, and clear task properties (for example: `cron`, `name`, `flux`, `status`).\nOnce InfluxDB applies the update, it cancels all previously scheduled runs of the task.\n\nTo update a task, pass an object that contains the updated key-value pairs.\nTo activate or inactivate a task, set the `status` property.\n_`\"status\": \"inactive\"`_ cancels scheduled runs and prevents manual runs of the task.\n", + "description": "Updates the specified [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task),\nand then cancels all scheduled runs of the task.\n\nUse this endpoint to set, modify, or clear task properties--for example: `cron`, `name`, `flux`, `status`.\nOnce InfluxDB applies the update, it cancels all previously scheduled runs of the task.\n\n#### Related guides\n\n- [Update a task]({{% INFLUXDB_DOCS_URL %}}/process-data/manage-tasks/update-task/)\n- [Task configuration options]({{% INFLUXDB_DOCS_URL %}}/process-data/task-options/)\n", "requestBody": { - "description": "An object that contains updated task properties to apply.", + "description": "In the request body, provide the task properties to update.\n", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskUpdateRequest" + }, + "examples": { + "TaskWithFlux": { + "$ref": "#/components/examples/TaskWithFluxRequest" + } } } } @@ -15547,7 +15571,7 @@ "type": "string" }, "required": true, - "description": "The ID of the task to update." + "description": "A task ID.\nSpecifies the [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task)to update.\n" } ], "responses": { @@ -15584,7 +15608,7 @@ "Tasks" ], "summary": "Delete a task", - "description": "Deletes a task and associated records.\n\nUse this endpoint to delete a task and all associated records (task runs, logs, and labels).\nOnce the task is deleted, InfluxDB cancels all scheduled runs of the task.\n\nIf you want to disable a task instead of delete it, [update the task status to `inactive`](#operation/PatchTasksID).\n", + "description": "Deletes the specified [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task)\nand all associated records (task runs, logs, and labels).\nOnce the task is deleted, InfluxDB cancels all scheduled runs of the task.\n\nTo disable a task instead of delete it, use\n[`PATCH /api/v2/tasks/TASK_ID`](#operation/PatchTasksID) to set the task status\n to `inactive`.\n", "parameters": [ { "$ref": "#/components/parameters/TraceSpan" @@ -15596,7 +15620,7 @@ "type": "string" }, "required": true, - "description": "The ID of the task to delete." + "description": "A task ID.\nSpecifies the [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) to delete.\n" } ], "responses": { @@ -24571,7 +24595,7 @@ "summary": "A task with Flux", "description": "Sets the `flux` property with Flux task options and a query.", "value": { - "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\")", + "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 contains Flux that configures the task schedule and downsamples CPU data every hour." } diff --git a/contracts/oss.yml b/contracts/oss.yml index 1990fef59..0b4d47e4a 100644 --- a/contracts/oss.yml +++ b/contracts/oss.yml @@ -6918,10 +6918,11 @@ paths: - Tasks summary: List runs for a task description: | - Retrieves a list of runs for a [task](https://docs.influxdata.com/influxdb/v2.3/process-data/). + Lists runs for the specified [task](https://docs.influxdata.com/influxdb/v2.3/process-data/). To limit which task runs are returned, pass query parameters in your request. - If no query parameters are passed, InfluxDB returns all task runs up to the default `limit`. + If you don't pass query parameters, InfluxDB returns all runs for the task + up to the default `limit`. parameters: - $ref: '#/components/parameters/TraceSpan' - in: path @@ -6930,13 +6931,14 @@ paths: type: string required: true description: | - The ID of the task to get runs for. - Only returns runs for this task. + A task ID. + Specifies the [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) to + to list runs for. - in: query name: after schema: type: string - description: A task run ID. Only returns runs created after this run. + description: A task run ID. Only returns runs created after the specified run. - in: query name: limit schema: @@ -6953,7 +6955,7 @@ paths: format: date-time description: | A timestamp ([RFC3339 date/time format](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#rfc3339-timestamp)). - Only returns runs scheduled after this time. + Only returns runs scheduled after the specified time. - in: query name: beforeTime schema: @@ -6961,7 +6963,7 @@ paths: format: date-time description: | A timestamp ([RFC3339 date/time format](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#rfc3339-timestamp)). - Only returns runs scheduled before this time. + Only returns runs scheduled before the specified time. responses: '200': description: Success. The response body contains the list of task runs. @@ -6990,6 +6992,10 @@ paths: To _retry_ a previous run (and avoid creating a new run), use the [`POST /api/v2/tasks/{taskID}/runs/{runID}/retry` endpoint](#operation/PostTasksIDRunsIDRetry). + + #### Limitations + + - Queuing a task run requires that the task's `status` property be set to `active`. parameters: - $ref: '#/components/parameters/TraceSpan' - in: path @@ -6997,6 +7003,10 @@ paths: schema: type: string required: true + description: | + A task ID. + Specifies the [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) to + to run. requestBody: content: application/json: @@ -7009,6 +7019,18 @@ paths: application/json: schema: $ref: '#/components/schemas/Run' + '400': + description: Bad request. + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + examples: + inactiveTask: + summary: Can't run an inactive task + value: + code: invalid + message: 'failed to force run: inactive task' '401': $ref: '#/components/responses/AuthorizationError' '500': @@ -7022,7 +7044,7 @@ paths: - Tasks summary: Retrieve a run for a task. description: | - Retrieves a specific run for a [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task). + Retrieves the specified run for the specified [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task). Use this endpoint to retrieve detail and logs for a specific task run. parameters: @@ -7032,13 +7054,16 @@ paths: schema: type: string required: true - description: The ID of the task to retrieve runs for. + description: | + A task ID. + Specifies the [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) + that the task run belongs to. - in: path name: runID schema: type: string required: true - description: The ID of the run to retrieve. + description: A task run ID. Specifies the run to retrieve. responses: '200': description: Success. The response body contains the task run. @@ -7087,7 +7112,7 @@ paths: description: | Cancels a running [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task). - Use this endpoint with InfluxDB OSS to cancel a running task. + Use this endpoint to cancel a running task. #### InfluxDB Cloud @@ -7099,13 +7124,18 @@ paths: schema: type: string required: true - description: The ID of the task to cancel. + description: | + A task ID. + Specifies the [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) to + to cancel. - in: path name: runID schema: type: string required: true - description: The ID of the task run to cancel. + description: | + A task run ID. + Specifies the task run to cancel. responses: '204': description: | @@ -7147,15 +7177,15 @@ paths: - Tasks summary: Retry a task run description: | - Queues a [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) run to - retry and returns the scheduled run. + Queues a [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) run to + retry and then returns the scheduled run. To manually start a _new_ task run, use the [`POST /api/v2/tasks/{taskID}/runs` endpoint](#operation/PostTasksIDRuns). #### Limitations - - The task must be _active_ (`status: "active"`). + - Queuing a task run requires that the task's `status` property be set to `active`. requestBody: content: application/json; charset=utf-8: @@ -7169,15 +7199,15 @@ paths: type: string required: true description: | - A [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) ID. - Specifies the task to retry. + A task ID. + Specifies the [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) that the task run belongs to. - in: path name: runID schema: type: string required: true description: | - A [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) run ID. + A task run ID. Specifies the task run to retry. To find a task run ID, use the @@ -7235,12 +7265,12 @@ paths: operationId: GetTasksIDLogs tags: - Tasks - summary: Retrieve all logs for a task + summary: List logs for a task description: | - Retrieves a list of all logs for a [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task). + Lists all log events for a [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task). - 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. + When a task runs, InfluxDB creates a `run` record in the task’s history. + Logs associated with each run provide relevant log messages, timestamps, and the exit status of the `run` attempt. Use this endpoint to retrieve only the log events for a task, without additional task metadata. @@ -7251,11 +7281,12 @@ paths: schema: type: string required: true - description: The task ID. + description: 'A task ID. Specifies the [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) to retrieve logs for.' responses: '200': description: | - Success. The response body contains an `events` list with logs for the task. + Success. + The response body contains an `events` list with logs for the task. Each log event `message` contains detail about the event. If a task run fails, InfluxDB logs an event with the reason for the failure. content: @@ -7264,7 +7295,7 @@ paths: $ref: '#/components/schemas/Logs' examples: taskSuccess: - summary: Events for a successful task run. + summary: Events for a successful task run value: events: - runID: 09b070dadaa7d000 @@ -7274,7 +7305,7 @@ paths: time: '2022-07-18T14:46:07.242859Z' message: Completed(success) taskFailure: - summary: Events for a failed task run. + summary: Events for a failed task run value: events: - runID: 09a946fc3167d000 @@ -7301,12 +7332,12 @@ paths: operationId: GetTasksIDRunsIDLogs tags: - Tasks - summary: Retrieve all logs for a run + summary: List logs for a run description: | - Retrieves all logs for a task run. + Lists all logs for a task run. A log is a list of run events with `runID`, `time`, and `message` properties. - Use this endpoint to help analyze task performance and troubleshoot failed task runs. + Use this endpoint to help analyze [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) performance and troubleshoot failed task runs. parameters: - $ref: '#/components/parameters/TraceSpan' - in: path @@ -7314,13 +7345,13 @@ paths: schema: type: string required: true - description: The ID of the task to get logs for. + description: 'A task ID. Specifies the [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) that the run belongs to.' - in: path name: runID schema: type: string required: true - description: The ID of the run to get logs for. + description: A run ID. Specifies the task run to list logs for. responses: '200': description: | @@ -7372,9 +7403,12 @@ paths: - Tasks summary: List labels for a task description: | - Retrieves a list of all labels for a task. + Lists all labels for a task. - Labels may be used for grouping and filtering tasks. + Use this endpoint to list labels applied to a task. + Labels are a way to add metadata to InfluxDB resources. + You can use labels for grouping and filtering resources in the + InfluxDB UI, `influx` CLI, and InfluxDB API. parameters: - $ref: '#/components/parameters/TraceSpan' - in: path @@ -7382,7 +7416,9 @@ paths: schema: type: string required: true - description: The ID of the task to retrieve labels for. + description: | + A task ID. + Specifies the task to retrieve labels for. responses: '200': description: Success. The response body contains a list of all labels for the task. @@ -7406,9 +7442,12 @@ paths: - Tasks summary: Add a label to a task description: | - Adds a label to a task. + Adds a label to a [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task). - Use this endpoint to add a label that you can use to filter tasks in the InfluxDB UI. + Use this endpoint to add a label to a task. + Labels are a way to add metadata to InfluxDB resources. + You can use labels for grouping and filtering resources in the + InfluxDB UI, `influx` CLI, and InfluxDB API. parameters: - $ref: '#/components/parameters/TraceSpan' - in: path @@ -7416,9 +7455,12 @@ paths: schema: type: string required: true - description: The ID of the task to label. + description: | + A task ID. + Specifies the [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) to label. requestBody: - description: An object that contains a _`labelID`_ to add to the task. + description: | + In the request body, provide an object that specifies the label. required: true content: application/json: @@ -7426,7 +7468,7 @@ paths: $ref: '#/components/schemas/LabelMapping' responses: '201': - description: Success. The response body contains a list of all labels for the task. + description: Success. The response body contains the label. content: application/json: schema: @@ -7448,7 +7490,7 @@ paths: - Tasks summary: Delete a label from a task description: | - Deletes a label from a task. + Deletes a label from a [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task). parameters: - $ref: '#/components/parameters/TraceSpan' - in: path @@ -7456,13 +7498,17 @@ paths: schema: type: string required: true - description: The ID of the task to delete the label from. + description: | + A task ID. + Specifies the [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) to delete the label from. - in: path name: labelID schema: type: string required: true - description: The ID of the label to delete. + description: | + A label ID. + Specifies the label to delete. responses: '204': description: Success. The label is deleted. @@ -7634,6 +7680,8 @@ paths: description: | **Deprecated**: Tasks don't use `owner` and `member` roles. Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. + + Lists all users that have the `member` role for the specified [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task). parameters: - $ref: '#/components/parameters/TraceSpan' - in: path @@ -7641,12 +7689,16 @@ paths: schema: type: string required: true - description: The task ID. + description: | + A task ID. + Specifies the [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) to retrieve members for. responses: '200': description: | Success. The response body contains a list of `users` that have the `member` role for a task. + + If the task has no members, the response contains an empty `users` array. content: application/json: schema: @@ -7667,7 +7719,8 @@ paths: **Deprecated**: Tasks don't use `owner` and `member` roles. Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. - Adds a user to members of a task and returns the member. + Adds a specified user to members of the specified [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) and then returns + the member. parameters: - $ref: '#/components/parameters/TraceSpan' - in: path @@ -7675,9 +7728,12 @@ paths: schema: type: string required: true - description: The task ID. + description: | + A [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) ID. + Specifies the task for the member. requestBody: - description: A user to add as a member of the task. + description: | + In the request body, provide an object that specifies the user. required: true content: application/json: @@ -7685,7 +7741,10 @@ paths: $ref: '#/components/schemas/AddResourceMemberRequestBody' responses: '201': - description: Created. The user is added to task members. + description: | + Created. The task `member` role is assigned to the user. + The response body contains the resource member with + role and user detail. content: application/json: schema: @@ -7706,6 +7765,8 @@ paths: description: | **Deprecated**: Tasks don't use `owner` and `member` roles. Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. + + Removes a member from a [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task). parameters: - $ref: '#/components/parameters/TraceSpan' - in: path @@ -7713,16 +7774,16 @@ paths: schema: type: string required: true - description: The ID of the member to remove. + description: A user ID. Specifies the member to remove. - in: path name: taskID schema: type: string required: true - description: The task ID. + description: 'A task ID. Specifies the [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) to remove the member from.' responses: '204': - description: Member removed + description: Success. The member is removed. default: description: Unexpected error content: @@ -7740,7 +7801,7 @@ paths: **Deprecated**: Tasks don't use `owner` and `member` roles. Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. - Retrieves all users that have owner permission for a task. + Lists all users that have the `owner` role for the specified task. parameters: - $ref: '#/components/parameters/TraceSpan' - in: path @@ -7748,7 +7809,7 @@ paths: schema: type: string required: true - description: The ID of the task to retrieve owners for. + description: A task ID. Specifies the task to retrieve owners for. responses: '200': description: | @@ -7792,7 +7853,8 @@ paths: **Deprecated**: Tasks don't use `owner` and `member` roles. Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. - Assigns a task `owner` role to a user. + Adds a specified user to owners of the specified task and then returns the + owner. Use this endpoint to create a _resource owner_ for the task. A _resource owner_ is a user with `role: owner` for a specific resource. @@ -7803,9 +7865,12 @@ paths: schema: type: string required: true - description: The task ID. + description: | + A task ID. + Specifies the [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) for the owner. requestBody: - description: A user to add as an owner of the task. + description: | + In the request body, provide an object that specifies the user. required: true content: application/json: @@ -7864,6 +7929,8 @@ paths: description: | **Deprecated**: Tasks don't use `owner` and `member` roles. Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. + + Removes an owner from a [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task). parameters: - $ref: '#/components/parameters/TraceSpan' - in: path @@ -7871,16 +7938,18 @@ paths: schema: type: string required: true - description: The ID of the owner to remove. + description: 'A user ID. Specifies the owner to remove from the [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task).' - in: path name: taskID schema: type: string required: true - description: The task ID. + description: | + A task ID. + Specifies the [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) to remove the owner from. responses: '204': - description: Owner removed + description: Success. The owner is removed. default: description: Unexpected error content: @@ -11975,7 +12044,7 @@ paths: - Tasks summary: List tasks description: | - Retrieves a list of [tasks](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task). + Lists [tasks](https://docs.influxdata.com/influxdb/v2.3/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`. @@ -11988,8 +12057,9 @@ paths: - in: query name: name description: | - A [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) name. - Only returns tasks with the specified name. + A task name. + Only returns [tasks](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) + that have the specified name. Different tasks may have the same name. schema: type: string @@ -11998,29 +12068,31 @@ paths: schema: type: string description: | - A [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) ID. - Only returns tasks created after the specified task. + A task ID. + Only returns [tasks](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) created after the specified task. - in: query name: user schema: type: string description: | - A [user](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#user) ID. - Only returns tasks owned by the specified user. + A user ID. + Only returns [tasks](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) + owned by the specified [user](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#user). - in: query name: org schema: type: string description: | - An [organization](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#organization) name. - Only returns tasks owned by the specified organization. + An organization name. + Only returns tasks owned by the specified [organization](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#organization). - in: query name: orgID schema: type: string description: | - An [organization](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#organization) ID. - Only returns tasks owned by the specified organization. + An organization ID. + Only returns [tasks](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) owned by the specified [organization](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#organization). + required: true - in: query name: status schema: @@ -12029,8 +12101,8 @@ paths: - active - inactive description: | - A [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) status. - Only returns tasks that have the specified status (`active` or `inactive`). + A task status. + Only returns [tasks](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) that have the specified status. - in: query name: limit schema: @@ -12048,9 +12120,9 @@ paths: - in: query name: type description: | - A [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) type (`basic` or `system`). + A task type. + Specifies the level of detail for [tasks](https://docs.influxdata.com/influxdb/v2.3/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`). required: false @@ -12154,7 +12226,9 @@ paths: - Tasks summary: Create a task description: | - Creates a [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) and returns the task. + Creates a [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) and returns the task. + + Use this endpoint to create a scheduled task that runs a script. #### Related guides @@ -12165,12 +12239,20 @@ paths: parameters: - $ref: '#/components/parameters/TraceSpan' requestBody: - description: Provide a task object in the request body. + description: | + In the request body, provide the task. + + #### InfluxDB OSS + + - Requires either the `org` parameter or the `orgID` parameter. required: true content: application/json: schema: $ref: '#/components/schemas/TaskCreateRequest' + examples: + TaskWithFlux: + $ref: '#/components/examples/TaskWithFluxRequest' responses: '201': description: Success. The response body contains a `tasks` list with the task. @@ -12192,12 +12274,12 @@ paths: $ref: '#/components/schemas/Error' examples: orgProvidedNotFound: - summary: The org or orgID passed doesn't own the token passed in the header + summary: The organization specified by org or orgID doesn't own the token passed in the header value: code: invalid message: 'failed to decode request body: organization not found' missingFluxError: - summary: Task in request body is missing Flux query + summary: The request body doesn't contain a Flux query value: code: invalid message: 'failed to decode request: missing flux' @@ -12211,24 +12293,6 @@ paths: application/json: schema: $ref: '#/components/schemas/Error' - x-codeSamples: - - lang: Shell - label: 'cURL: create a task' - source: | - curl http://localhost:8086/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 '/tasks/{taskID}': get: operationId: GetTasksID @@ -12237,7 +12301,7 @@ paths: - Tasks summary: Retrieve a task description: | - Retrieves a [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task). + Retrieves the specified [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task). parameters: - $ref: '#/components/parameters/TraceSpan' - in: path @@ -12245,7 +12309,9 @@ paths: schema: type: string required: true - description: The ID of the task to retrieve. + description: | + A task ID. + Specifies the [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) to retrieve. responses: '200': description: Success. The response body contains the task. @@ -12269,21 +12335,27 @@ paths: - Tasks summary: Update a task description: | - Updates a task and then cancels all scheduled runs of the task. + Updates the specified [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task), + and then cancels all scheduled runs of the task. - Use this endpoint to set, modify, and clear task properties (for example: `cron`, `name`, `flux`, `status`). + Use this endpoint to set, modify, or clear task properties--for example: `cron`, `name`, `flux`, `status`. Once InfluxDB applies the update, it cancels all previously scheduled runs of the task. - To update a task, pass 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. + #### Related guides + + - [Update a task](https://docs.influxdata.com/influxdb/v2.3/process-data/manage-tasks/update-task/) + - [Task configuration options](https://docs.influxdata.com/influxdb/v2.3/process-data/task-options/) requestBody: - description: An object that contains updated task properties to apply. + description: | + In the request body, provide the task properties to update. required: true content: application/json: schema: $ref: '#/components/schemas/TaskUpdateRequest' + examples: + TaskWithFlux: + $ref: '#/components/examples/TaskWithFluxRequest' parameters: - $ref: '#/components/parameters/TraceSpan' - in: path @@ -12291,7 +12363,9 @@ paths: schema: type: string required: true - description: The ID of the task to update. + description: | + A task ID. + Specifies the [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task)to update. responses: '200': description: Success. The response body contains the updated task. @@ -12315,12 +12389,13 @@ paths: - Tasks summary: Delete a task description: | - Deletes a task and associated records. - - Use this endpoint to delete a task and all associated records (task runs, logs, and labels). + Deletes the specified [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) + and all associated records (task runs, logs, and labels). Once the task is deleted, InfluxDB cancels all scheduled runs of the task. - If you want to disable a task instead of delete it, [update the task status to `inactive`](#operation/PatchTasksID). + To disable a task instead of delete it, use + [`PATCH /api/v2/tasks/TASK_ID`](#operation/PatchTasksID) to set the task status + to `inactive`. parameters: - $ref: '#/components/parameters/TraceSpan' - in: path @@ -12328,7 +12403,9 @@ paths: schema: type: string required: true - description: The ID of the task to delete. + description: | + A task ID. + Specifies the [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) to delete. responses: '204': description: Success. The task and runs are deleted. Scheduled runs are canceled. @@ -18786,7 +18863,7 @@ components: summary: A task with Flux description: Sets the `flux` property with Flux task options and a query. value: - 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\")" + 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 contains Flux that configures the task schedule and downsamples CPU data every hour. securitySchemes: diff --git a/contracts/ref/cloud.yml b/contracts/ref/cloud.yml index ec02bfbcc..b855849b4 100644 --- a/contracts/ref/cloud.yml +++ b/contracts/ref/cloud.yml @@ -40,10 +40,10 @@ components: description: This task contains Flux that configures the task schedule and downsamples CPU data every hour. 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\")" + \"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 TaskWithScriptRequest: description: | @@ -14709,52 +14709,56 @@ paths: /api/v2/tasks: get: description: | - Retrieves a list of [tasks](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task). + Lists [tasks](https://docs.influxdata.com/influxdb/cloud/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](https://docs.influxdata.com/influxdb/cloud/process-data/) operationId: GetTasks parameters: - $ref: '#/components/parameters/TraceSpan' - description: | - A [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task) name. - Only returns tasks with the specified name. + A task name. + Only returns [tasks](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task) with the specified name. Different tasks may have the same name. in: query name: name schema: type: string - description: | - A [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task) ID. - Only returns tasks created after the specified task. + A task ID. + Only returns [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task) created after the specified task. in: query name: after schema: type: string - description: | - A [user](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#user) ID. - Only returns tasks owned by the specified user. + A user ID. + Only returns [tasks](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task) owned by the specified [user](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#user). in: query name: user schema: type: string - description: | - An [organization](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#organization) name. - Only returns tasks owned by the specified organization. + An organization name. + Only returns [tasks](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task) owned by the specified [organization](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#organization). in: query name: org schema: type: string - description: | - An [organization](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#organization) ID. - Only returns tasks owned by the specified organization. + An organization ID. + Only returns tasks owned by the specified [organization](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#organization). in: query name: orgID schema: type: string - description: | - A [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task) status. - Only returns tasks that have the specified status (`active` or `inactive`). + A task status. + Only returns [tasks](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task) that have the specified status. in: query name: status schema: @@ -14792,8 +14796,11 @@ paths: minimum: 0 type: integer - 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`. in: query name: sortBy required: false @@ -14802,11 +14809,13 @@ paths: - name type: string - description: | - A [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task) type (`basic` or `system`). + A task type. + Specifies the level of detail for [tasks](https://docs.influxdata.com/influxdb/cloud/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`). in: query name: type required: false @@ -14817,8 +14826,8 @@ paths: - system type: string - 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). in: query name: scriptID schema: @@ -14903,7 +14912,7 @@ paths: $ref: '#/components/responses/InternalServerError' default: $ref: '#/components/responses/GeneralServerError' - summary: List all tasks + summary: List tasks tags: - Data I/O endpoints - Tasks @@ -14918,52 +14927,7 @@ paths: description: | Creates a [task](https://docs.influxdata.com/influxdb/cloud/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 @@ -14977,9 +14941,35 @@ paths: requestBody: content: application/json: + examples: + TaskWithFlux: + $ref: '#/components/examples/TaskWithFluxRequest' + TaskWithScriptID: + $ref: '#/components/examples/TaskWithScriptRequest' schema: $ref: '#/components/schemas/TaskCreateRequest' - description: Provide a task object in the request body. + 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](https://docs.influxdata.com/influxdb/cloud/process-data/task-options/) + for detail and examples. + + #### Limitations: + + - You can't use `flux` and `scriptID` in the same task. required: true responses: "201": @@ -14988,7 +14978,7 @@ paths: schema: $ref: '#/components/schemas/Task' description: Success. The response body contains a `tasks` list with the - new task. + task. "400": content: application/json: @@ -15013,8 +15003,10 @@ paths: #### 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. "401": $ref: '#/components/responses/AuthorizationError' "500": @@ -15029,58 +15021,22 @@ paths: tags: - Data I/O endpoints - Tasks - x-codeSamples: - - label: 'cURL: create a Flux script task' - lang: Shell - 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 - - label: 'cURL: create a Flux script reference task' - lang: Shell - 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 /api/v2/tasks/{taskID}: delete: description: | - Deletes a [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task) and associated records. - - Use this endpoint to delete a task and all associated records (task runs, logs, and labels). + Deletes the specified [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task) + and all associated records (task runs, logs, and labels). Once the task is deleted, InfluxDB cancels all scheduled runs of the task. - If you want to disable a task instead of delete it, [update the task status to `inactive`](#operation/PatchTasksID). + To disable a task instead of delete it, use + [`PATCH /api/v2/tasks/TASK_ID`](#operation/PatchTasksID) to set the task's `status` + property to `inactive`. operationId: DeleteTasksID parameters: - $ref: '#/components/parameters/TraceSpan' - - description: A [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task) - ID. Specifies the task to delete. + - description: | + A task ID. + Specifies the [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task) to delete. in: path name: taskID required: true @@ -15105,13 +15061,13 @@ paths: - Tasks get: description: | - Retrieves a [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task). + Retrieves the specified [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task). operationId: GetTasksID parameters: - $ref: '#/components/parameters/TraceSpan' - description: | - A [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task) ID. - Specifies the task to retrieve. + A task ID. + Specifies the [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task) to retrieve. in: path name: taskID required: true @@ -15140,66 +15096,25 @@ paths: - Tasks patch: description: | - Updates a [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task), + Updates the specified [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task), and then cancels all scheduled runs of the task. Use this endpoint to set, modify, or clear task properties--for example: `cron`, `name`, `flux`, `status`. Once InfluxDB applies the update, it cancels all previously scheduled runs of the task. - To update a task, pass 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. - - #### InfluxDB Cloud - - - 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: + The `status` property set to `inactive` cancels scheduled runs and prevents manual runs of the task. - ```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: + #### Related guides - - You can't use `flux` and `scriptID` for the same task. + - [Update a task](https://docs.influxdata.com/influxdb/cloud/process-data/manage-tasks/update-task/) + - [Task configuration options](https://docs.influxdata.com/influxdb/cloud/process-data/task-options/) operationId: PatchTasksID parameters: - $ref: '#/components/parameters/TraceSpan' - description: | - A [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task) ID. - Specifies the task to update. + A task ID. + Specifies the [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task) to update. in: path name: taskID required: true @@ -15208,9 +15123,35 @@ paths: requestBody: content: application/json: + examples: + TaskWithFlux: + $ref: '#/components/examples/TaskWithFluxRequest' + TaskWithScriptID: + $ref: '#/components/examples/TaskWithScriptRequest' schema: $ref: '#/components/schemas/TaskUpdateRequest' - description: An task update to apply. + description: | + In the request body, provide the task properties to update. + To provide the script that the task runs, + set either the `flux` property or the `scriptID` property. + + If you set `scriptID`, you can set the following properties to configure the task: + - `cron` + - `every` + - `offset` + - `scriptParameters` + + If you set the `flux` property, provide the `task` configuration option + in the Flux script. + + See [task configuration options](https://docs.influxdata.com/influxdb/cloud/process-data/task-options/) + for detail and examples. + + #### Limitations: + + - You can't set `flux` and `scriptID` properties for the same task--for + example, if you set the `scriptID` property, then InfluxDB sets the `flux` property + to an empty string (`""`). required: true responses: "200": @@ -15235,13 +15176,18 @@ paths: /api/v2/tasks/{taskID}/labels: get: description: | - Retrieves a list of all labels for a task. + Lists all labels for a task. - Labels may be used for grouping and filtering tasks. + Use this endpoint to list labels applied to a task. + Labels are a way to add metadata to InfluxDB resources. + You can use labels for grouping and filtering resources in the + InfluxDB UI, `influx` CLI, and InfluxDB API. operationId: GetTasksIDLabels parameters: - $ref: '#/components/parameters/TraceSpan' - - description: The ID of the task to retrieve labels for. + - description: | + A task ID. + Specifies the task to retrieve labels for. in: path name: taskID required: true @@ -15270,13 +15216,18 @@ paths: - Tasks post: description: | - Adds a label to a task. + Adds a label to a [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task). - Use this endpoint to add a label that you can use to filter tasks in the InfluxDB UI. + Use this endpoint to add a label to a task. + Labels are a way to add metadata to InfluxDB resources. + You can use labels for grouping and filtering resources in the + InfluxDB UI, `influx` CLI, and InfluxDB API. operationId: PostTasksIDLabels parameters: - $ref: '#/components/parameters/TraceSpan' - - description: The ID of the task to label. + - description: | + A task ID. + Specifies the [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task) to label. in: path name: taskID required: true @@ -15287,7 +15238,8 @@ paths: application/json: schema: $ref: '#/components/schemas/LabelMapping' - description: An object that contains a _`labelID`_ to add to the task. + description: | + In the request body, provide an object that specifies the label. required: true responses: "201": @@ -15295,8 +15247,7 @@ paths: application/json: schema: $ref: '#/components/schemas/LabelResponse' - description: Success. The response body contains a list of all labels for - the task. + description: Success. The response body contains the label. "400": $ref: '#/components/responses/BadRequestError' "401": @@ -15313,17 +15264,21 @@ paths: /api/v2/tasks/{taskID}/labels/{labelID}: delete: description: | - Deletes a label from a task. + Deletes a label from a [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task). operationId: DeleteTasksIDLabelsID parameters: - $ref: '#/components/parameters/TraceSpan' - - description: The ID of the task to delete the label from. + - description: | + A task ID. + Specifies the [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task) to delete the label from. in: path name: taskID required: true schema: type: string - - description: The ID of the label to delete. + - description: | + A label ID. + Specifies the label to delete. in: path name: labelID required: true @@ -15348,17 +15303,18 @@ paths: /api/v2/tasks/{taskID}/logs: get: description: | - Retrieves a list of all logs for a [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task). + Lists all log events for a [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task). - 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. + When a task runs, InfluxDB creates a `run` record in the task’s history. + Logs associated with each run provide relevant log messages, timestamps, and the exit status of the `run` attempt. Use this endpoint to retrieve only the log events for a task, without additional task metadata. operationId: GetTasksIDLogs parameters: - $ref: '#/components/parameters/TraceSpan' - - description: The task ID. + - description: A task ID. Specifies the [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task) + to retrieve logs for. in: path name: taskID required: true @@ -15370,7 +15326,7 @@ paths: application/json: examples: taskFailure: - summary: Events for a failed task run. + summary: Events for a failed task run value: events: - message: 'Started task from script: "option task = {name: \"test @@ -15387,7 +15343,7 @@ paths: runID: 09a946fc3167d000 time: "2022-07-13T08:24:37.115323Z" taskSuccess: - summary: Events for a successful task run. + summary: Events for a successful task run value: events: - message: 'Started task from script: "option task = {name: \"task1\", @@ -15402,7 +15358,8 @@ paths: schema: $ref: '#/components/schemas/Logs' description: | - Success. The response body contains an `events` list with logs for the task. + Success. + The response body contains an `events` list with logs for the task. Each log event `message` contains detail about the event. If a task run fails, InfluxDB logs an event with the reason for the failure. "400": @@ -15415,7 +15372,7 @@ paths: $ref: '#/components/responses/InternalServerError' default: $ref: '#/components/responses/GeneralServerError' - summary: Retrieve all logs for a task + summary: List logs for a task tags: - Tasks /api/v2/tasks/{taskID}/members: @@ -15424,10 +15381,14 @@ paths: description: | **Deprecated**: Tasks don't use `owner` and `member` roles. Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. + + Lists all users that have the `member` role for the specified [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task). operationId: GetTasksIDMembers parameters: - $ref: '#/components/parameters/TraceSpan' - - description: The task ID. + - description: | + A task ID. + Specifies the [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task) to retrieve members for. in: path name: taskID required: true @@ -15442,6 +15403,8 @@ paths: description: | Success. The response body contains a list of `users` that have the `member` role for a task. + + If the task has no members, the response contains an empty `users` array. default: content: application/json: @@ -15457,11 +15420,14 @@ paths: **Deprecated**: Tasks don't use `owner` and `member` roles. Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. - Adds a user to members of a task and returns the member. + Adds a specified user to members of the specified [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task) and then returns + the member. operationId: PostTasksIDMembers parameters: - $ref: '#/components/parameters/TraceSpan' - - description: The task ID. + - description: | + A [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task) ID. + Specifies the task for the member. in: path name: taskID required: true @@ -15472,7 +15438,8 @@ paths: application/json: schema: $ref: '#/components/schemas/AddResourceMemberRequestBody' - description: A user to add as a member of the task. + description: | + In the request body, provide an object that specifies the user. required: true responses: "201": @@ -15480,7 +15447,10 @@ paths: application/json: schema: $ref: '#/components/schemas/ResourceMember' - description: Created. The user is added to task members. + description: | + Created. The task `member` role is assigned to the user. + The response body contains the resource member with + role and user detail. default: content: application/json: @@ -15496,16 +15466,19 @@ paths: description: | **Deprecated**: Tasks don't use `owner` and `member` roles. Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. + + Removes a member from a [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task). operationId: DeleteTasksIDMembersID parameters: - $ref: '#/components/parameters/TraceSpan' - - description: The ID of the member to remove. + - description: A user ID. Specifies the member to remove. in: path name: userID required: true schema: type: string - - description: The task ID. + - description: A task ID. Specifies the [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task) + to remove the member from. in: path name: taskID required: true @@ -15513,7 +15486,7 @@ paths: type: string responses: "204": - description: Member removed + description: Success. The member is removed. default: content: application/json: @@ -15530,11 +15503,11 @@ paths: **Deprecated**: Tasks don't use `owner` and `member` roles. Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. - Retrieves all users that have owner permission for a task. + Lists all users that have the `owner` role for the specified task. operationId: GetTasksIDOwners parameters: - $ref: '#/components/parameters/TraceSpan' - - description: The ID of the task to retrieve owners for. + - description: A task ID. Specifies the task to retrieve owners for. in: path name: taskID required: true @@ -15582,14 +15555,17 @@ paths: **Deprecated**: Tasks don't use `owner` and `member` roles. Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. - Assigns a task `owner` role to a user. + Adds a specified user to owners of the specified task and then returns the + owner. Use this endpoint to create a _resource owner_ for the task. A _resource owner_ is a user with `role: owner` for a specific resource. operationId: PostTasksIDOwners parameters: - $ref: '#/components/parameters/TraceSpan' - - description: The task ID. + - description: | + A task ID. + Specifies the [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task) for the owner. in: path name: taskID required: true @@ -15600,7 +15576,8 @@ paths: application/json: schema: $ref: '#/components/schemas/AddResourceMemberRequestBody' - description: A user to add as an owner of the task. + description: | + In the request body, provide an object that specifies the user. required: true responses: "201": @@ -15654,16 +15631,20 @@ paths: description: | **Deprecated**: Tasks don't use `owner` and `member` roles. Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. + + Removes an owner from a [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task). operationId: DeleteTasksIDOwnersID parameters: - $ref: '#/components/parameters/TraceSpan' - - description: The ID of the owner to remove. + - description: A user ID. Specifies the owner to remove from the [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task). in: path name: userID required: true schema: type: string - - description: The task ID. + - description: | + A task ID. + Specifies the [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task) to remove the owner from. in: path name: taskID required: true @@ -15671,7 +15652,7 @@ paths: type: string responses: "204": - description: Owner removed + description: Success. The owner is removed. default: content: application/json: @@ -15684,22 +15665,25 @@ paths: /api/v2/tasks/{taskID}/runs: get: description: | - Retrieves a list of runs for a [task](https://docs.influxdata.com/influxdb/cloud/process-data/). + Lists runs for the specified [task](https://docs.influxdata.com/influxdb/cloud/process-data/). To limit which task runs are returned, pass query parameters in your request. - If no query parameters are passed, InfluxDB returns all task runs up to the default `limit`. + If you don't pass query parameters, InfluxDB returns all runs for the task + up to the default `limit`. operationId: GetTasksIDRuns parameters: - $ref: '#/components/parameters/TraceSpan' - description: | - The ID of the task to get runs for. - Only returns runs for this task. + A task ID. + Specifies the [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task) to + to list runs for. in: path name: taskID required: true schema: type: string - - description: A task run ID. Only returns runs created after this run. + - description: A task run ID. Only returns runs created after the specified + run. in: query name: after schema: @@ -15715,7 +15699,7 @@ paths: type: integer - description: | A timestamp ([RFC3339 date/time format](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#rfc3339-timestamp)). - Only returns runs scheduled after this time. + Only returns runs scheduled after the specified time. in: query name: afterTime schema: @@ -15723,7 +15707,7 @@ paths: type: string - description: | A timestamp ([RFC3339 date/time format](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#rfc3339-timestamp)). - Only returns runs scheduled before this time. + Only returns runs scheduled before the specified time. in: query name: beforeTime schema: @@ -15755,10 +15739,18 @@ paths: To _retry_ a previous run (and avoid creating a new run), use the [`POST /api/v2/tasks/{taskID}/runs/{runID}/retry` endpoint](#operation/PostTasksIDRunsIDRetry). + + #### Limitations + + - Queuing a task run requires that the task's `status` property be set to `active`. operationId: PostTasksIDRuns parameters: - $ref: '#/components/parameters/TraceSpan' - - in: path + - description: | + A task ID. + Specifies the [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task) to + to run. + in: path name: taskID required: true schema: @@ -15775,6 +15767,18 @@ paths: schema: $ref: '#/components/schemas/Run' description: Success. The run is scheduled to start. + "400": + content: + application/json: + examples: + inactiveTask: + summary: Can't run an inactive task + value: + code: invalid + message: 'failed to force run: inactive task' + schema: + $ref: '#/components/schemas/Error' + description: Bad request. "401": $ref: '#/components/responses/AuthorizationError' "500": @@ -15790,7 +15794,7 @@ paths: description: | Cancels a running [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task). - Use this endpoint with InfluxDB OSS to cancel a running task. + Use this endpoint to cancel a running task. #### InfluxDB Cloud @@ -15798,13 +15802,18 @@ paths: operationId: DeleteTasksIDRunsID parameters: - $ref: '#/components/parameters/TraceSpan' - - description: The ID of the task to cancel. + - description: | + A task ID. + Specifies the [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task) to + to cancel. in: path name: taskID required: true schema: type: string - - description: The ID of the task run to cancel. + - description: | + A task run ID. + Specifies the task run to cancel. in: path name: runID required: true @@ -15849,19 +15858,22 @@ paths: - Tasks get: description: | - Retrieves a specific run for a [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task). + Retrieves the specified run for the specified [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task). Use this endpoint to retrieve detail and logs for a specific task run. operationId: GetTasksIDRunsID parameters: - $ref: '#/components/parameters/TraceSpan' - - description: The ID of the task to retrieve runs for. + - description: | + A task ID. + Specifies the [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task) + that the task run belongs to. in: path name: taskID required: true schema: type: string - - description: The ID of the run to retrieve. + - description: A task run ID. Specifies the run to retrieve. in: path name: runID required: true @@ -15916,20 +15928,21 @@ paths: /api/v2/tasks/{taskID}/runs/{runID}/logs: get: description: | - Retrieves all logs for a task run. + Lists all logs for a task run. A log is a list of run events with `runID`, `time`, and `message` properties. - Use this endpoint to help analyze task performance and troubleshoot failed task runs. + Use this endpoint to help analyze [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task) performance and troubleshoot failed task runs. operationId: GetTasksIDRunsIDLogs parameters: - $ref: '#/components/parameters/TraceSpan' - - description: The ID of the task to get logs for. + - description: A task ID. Specifies the [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task) + that the run belongs to. in: path name: taskID required: true schema: type: string - - description: The ID of the run to get logs for. + - description: A run ID. Specifies the task run to list logs for. in: path name: runID required: true @@ -15986,34 +15999,34 @@ paths: $ref: '#/components/responses/InternalServerError' default: $ref: '#/components/responses/GeneralServerError' - summary: Retrieve all logs for a run + summary: List logs for a run tags: - Tasks /api/v2/tasks/{taskID}/runs/{runID}/retry: post: description: | - Queues a [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task) run to - retry and returns the scheduled run. + Queues a [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task) run to + retry and then returns the scheduled run. To manually start a _new_ task run, use the [`POST /api/v2/tasks/{taskID}/runs` endpoint](#operation/PostTasksIDRuns). #### Limitations - - The task must be _active_ (`status: "active"`). + - Queuing a task run requires that the task's `status` property be set to `active`. operationId: PostTasksIDRunsIDRetry parameters: - $ref: '#/components/parameters/TraceSpan' - description: | - A [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task) ID. - Specifies the task to retry. + A task ID. + Specifies the [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task) that the task run belongs to. in: path name: taskID required: true schema: type: string - description: | - A [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task) run ID. + A task run ID. Specifies the task run to retry. To find a task run ID, use the diff --git a/contracts/ref/oss.yml b/contracts/ref/oss.yml index fdf8eeb7f..350b92605 100644 --- a/contracts/ref/oss.yml +++ b/contracts/ref/oss.yml @@ -40,10 +40,10 @@ components: description: This task contains Flux that configures the task schedule and downsamples CPU data every hour. 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\")" + \"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 parameters: After: @@ -15854,7 +15854,7 @@ paths: /api/v2/tasks: get: description: | - Retrieves a list of [tasks](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task). + Lists [tasks](https://docs.influxdata.com/influxdb/v2.3/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`. @@ -15866,44 +15866,47 @@ paths: parameters: - $ref: '#/components/parameters/TraceSpan' - description: | - A [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) name. - Only returns tasks with the specified name. + A task name. + Only returns [tasks](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) + that have the specified name. Different tasks may have the same name. in: query name: name schema: type: string - description: | - A [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) ID. - Only returns tasks created after the specified task. + A task ID. + Only returns [tasks](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) created after the specified task. in: query name: after schema: type: string - description: | - A [user](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#user) ID. - Only returns tasks owned by the specified user. + A user ID. + Only returns [tasks](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) + owned by the specified [user](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#user). in: query name: user schema: type: string - description: | - An [organization](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#organization) name. - Only returns tasks owned by the specified organization. + An organization name. + Only returns tasks owned by the specified [organization](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#organization). in: query name: org schema: type: string - description: | - An [organization](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#organization) ID. - Only returns tasks owned by the specified organization. + An organization ID. + Only returns [tasks](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) owned by the specified [organization](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#organization). in: query name: orgID + required: true schema: type: string - description: | - A [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) status. - Only returns tasks that have the specified status (`active` or `inactive`). + A task status. + Only returns [tasks](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) that have the specified status. in: query name: status schema: @@ -15926,9 +15929,9 @@ paths: minimum: 1 type: integer - description: | - A [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) type (`basic` or `system`). + A task type. + Specifies the level of detail for [tasks](https://docs.influxdata.com/influxdb/v2.3/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`). in: query @@ -16033,7 +16036,9 @@ paths: --header 'Authorization: Token INFLUX_API_TOKEN' post: description: | - Creates a [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) and returns the task. + Creates a [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) and returns the task. + + Use this endpoint to create a scheduled task that runs a script. #### Related guides @@ -16047,9 +16052,17 @@ paths: requestBody: content: application/json: + examples: + TaskWithFlux: + $ref: '#/components/examples/TaskWithFluxRequest' schema: $ref: '#/components/schemas/TaskCreateRequest' - description: Provide a task object in the request body. + description: | + In the request body, provide the task. + + #### InfluxDB OSS + + - Requires either the `org` parameter or the `orgID` parameter. required: true responses: "201": @@ -16064,13 +16077,13 @@ paths: application/json: examples: missingFluxError: - summary: Task in request body is missing Flux query + summary: The request body doesn't contain a Flux query value: code: invalid message: 'failed to decode request: missing flux' orgProvidedNotFound: - summary: The org or orgID passed doesn't own the token passed in - the header + summary: The organization specified by org or orgID doesn't own + the token passed in the header value: code: invalid message: 'failed to decode request body: organization not found' @@ -16097,37 +16110,22 @@ paths: tags: - Data I/O endpoints - Tasks - x-codeSamples: - - label: 'cURL: create a task' - lang: Shell - source: | - curl http://localhost:8086/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 /api/v2/tasks/{taskID}: delete: description: | - Deletes a task and associated records. - - Use this endpoint to delete a task and all associated records (task runs, logs, and labels). + Deletes the specified [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) + and all associated records (task runs, logs, and labels). Once the task is deleted, InfluxDB cancels all scheduled runs of the task. - If you want to disable a task instead of delete it, [update the task status to `inactive`](#operation/PatchTasksID). + To disable a task instead of delete it, use + [`PATCH /api/v2/tasks/TASK_ID`](#operation/PatchTasksID) to set the task status + to `inactive`. operationId: DeleteTasksID parameters: - $ref: '#/components/parameters/TraceSpan' - - description: The ID of the task to delete. + - description: | + A task ID. + Specifies the [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) to delete. in: path name: taskID required: true @@ -16152,11 +16150,13 @@ paths: - Tasks get: description: | - Retrieves a [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task). + Retrieves the specified [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task). operationId: GetTasksID parameters: - $ref: '#/components/parameters/TraceSpan' - - description: The ID of the task to retrieve. + - description: | + A task ID. + Specifies the [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) to retrieve. in: path name: taskID required: true @@ -16185,18 +16185,22 @@ paths: - Tasks patch: description: | - Updates a task and then cancels all scheduled runs of the task. + Updates the specified [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task), + and then cancels all scheduled runs of the task. - Use this endpoint to set, modify, and clear task properties (for example: `cron`, `name`, `flux`, `status`). + Use this endpoint to set, modify, or clear task properties--for example: `cron`, `name`, `flux`, `status`. Once InfluxDB applies the update, it cancels all previously scheduled runs of the task. - To update a task, pass 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. + #### Related guides + + - [Update a task](https://docs.influxdata.com/influxdb/v2.3/process-data/manage-tasks/update-task/) + - [Task configuration options](https://docs.influxdata.com/influxdb/v2.3/process-data/task-options/) operationId: PatchTasksID parameters: - $ref: '#/components/parameters/TraceSpan' - - description: The ID of the task to update. + - description: | + A task ID. + Specifies the [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task)to update. in: path name: taskID required: true @@ -16205,9 +16209,13 @@ paths: requestBody: content: application/json: + examples: + TaskWithFlux: + $ref: '#/components/examples/TaskWithFluxRequest' schema: $ref: '#/components/schemas/TaskUpdateRequest' - description: An object that contains updated task properties to apply. + description: | + In the request body, provide the task properties to update. required: true responses: "200": @@ -16232,13 +16240,18 @@ paths: /api/v2/tasks/{taskID}/labels: get: description: | - Retrieves a list of all labels for a task. + Lists all labels for a task. - Labels may be used for grouping and filtering tasks. + Use this endpoint to list labels applied to a task. + Labels are a way to add metadata to InfluxDB resources. + You can use labels for grouping and filtering resources in the + InfluxDB UI, `influx` CLI, and InfluxDB API. operationId: GetTasksIDLabels parameters: - $ref: '#/components/parameters/TraceSpan' - - description: The ID of the task to retrieve labels for. + - description: | + A task ID. + Specifies the task to retrieve labels for. in: path name: taskID required: true @@ -16267,13 +16280,18 @@ paths: - Tasks post: description: | - Adds a label to a task. + Adds a label to a [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task). - Use this endpoint to add a label that you can use to filter tasks in the InfluxDB UI. + Use this endpoint to add a label to a task. + Labels are a way to add metadata to InfluxDB resources. + You can use labels for grouping and filtering resources in the + InfluxDB UI, `influx` CLI, and InfluxDB API. operationId: PostTasksIDLabels parameters: - $ref: '#/components/parameters/TraceSpan' - - description: The ID of the task to label. + - description: | + A task ID. + Specifies the [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) to label. in: path name: taskID required: true @@ -16284,7 +16302,8 @@ paths: application/json: schema: $ref: '#/components/schemas/LabelMapping' - description: An object that contains a _`labelID`_ to add to the task. + description: | + In the request body, provide an object that specifies the label. required: true responses: "201": @@ -16292,8 +16311,7 @@ paths: application/json: schema: $ref: '#/components/schemas/LabelResponse' - description: Success. The response body contains a list of all labels for - the task. + description: Success. The response body contains the label. "400": $ref: '#/components/responses/BadRequestError' "401": @@ -16310,17 +16328,21 @@ paths: /api/v2/tasks/{taskID}/labels/{labelID}: delete: description: | - Deletes a label from a task. + Deletes a label from a [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task). operationId: DeleteTasksIDLabelsID parameters: - $ref: '#/components/parameters/TraceSpan' - - description: The ID of the task to delete the label from. + - description: | + A task ID. + Specifies the [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) to delete the label from. in: path name: taskID required: true schema: type: string - - description: The ID of the label to delete. + - description: | + A label ID. + Specifies the label to delete. in: path name: labelID required: true @@ -16345,17 +16367,18 @@ paths: /api/v2/tasks/{taskID}/logs: get: description: | - Retrieves a list of all logs for a [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task). + Lists all log events for a [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task). - 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. + When a task runs, InfluxDB creates a `run` record in the task’s history. + Logs associated with each run provide relevant log messages, timestamps, and the exit status of the `run` attempt. Use this endpoint to retrieve only the log events for a task, without additional task metadata. operationId: GetTasksIDLogs parameters: - $ref: '#/components/parameters/TraceSpan' - - description: The task ID. + - description: A task ID. Specifies the [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) + to retrieve logs for. in: path name: taskID required: true @@ -16367,7 +16390,7 @@ paths: application/json: examples: taskFailure: - summary: Events for a failed task run. + summary: Events for a failed task run value: events: - message: 'Started task from script: "option task = {name: \"test @@ -16384,7 +16407,7 @@ paths: runID: 09a946fc3167d000 time: "2022-07-13T08:24:37.115323Z" taskSuccess: - summary: Events for a successful task run. + summary: Events for a successful task run value: events: - message: 'Started task from script: "option task = {name: \"task1\", @@ -16399,7 +16422,8 @@ paths: schema: $ref: '#/components/schemas/Logs' description: | - Success. The response body contains an `events` list with logs for the task. + Success. + The response body contains an `events` list with logs for the task. Each log event `message` contains detail about the event. If a task run fails, InfluxDB logs an event with the reason for the failure. "400": @@ -16412,7 +16436,7 @@ paths: $ref: '#/components/responses/InternalServerError' default: $ref: '#/components/responses/GeneralServerError' - summary: Retrieve all logs for a task + summary: List logs for a task tags: - Tasks /api/v2/tasks/{taskID}/members: @@ -16421,10 +16445,14 @@ paths: description: | **Deprecated**: Tasks don't use `owner` and `member` roles. Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. + + Lists all users that have the `member` role for the specified [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task). operationId: GetTasksIDMembers parameters: - $ref: '#/components/parameters/TraceSpan' - - description: The task ID. + - description: | + A task ID. + Specifies the [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) to retrieve members for. in: path name: taskID required: true @@ -16439,6 +16467,8 @@ paths: description: | Success. The response body contains a list of `users` that have the `member` role for a task. + + If the task has no members, the response contains an empty `users` array. default: content: application/json: @@ -16454,11 +16484,14 @@ paths: **Deprecated**: Tasks don't use `owner` and `member` roles. Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. - Adds a user to members of a task and returns the member. + Adds a specified user to members of the specified [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) and then returns + the member. operationId: PostTasksIDMembers parameters: - $ref: '#/components/parameters/TraceSpan' - - description: The task ID. + - description: | + A [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) ID. + Specifies the task for the member. in: path name: taskID required: true @@ -16469,7 +16502,8 @@ paths: application/json: schema: $ref: '#/components/schemas/AddResourceMemberRequestBody' - description: A user to add as a member of the task. + description: | + In the request body, provide an object that specifies the user. required: true responses: "201": @@ -16477,7 +16511,10 @@ paths: application/json: schema: $ref: '#/components/schemas/ResourceMember' - description: Created. The user is added to task members. + description: | + Created. The task `member` role is assigned to the user. + The response body contains the resource member with + role and user detail. default: content: application/json: @@ -16493,16 +16530,19 @@ paths: description: | **Deprecated**: Tasks don't use `owner` and `member` roles. Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. + + Removes a member from a [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task). operationId: DeleteTasksIDMembersID parameters: - $ref: '#/components/parameters/TraceSpan' - - description: The ID of the member to remove. + - description: A user ID. Specifies the member to remove. in: path name: userID required: true schema: type: string - - description: The task ID. + - description: A task ID. Specifies the [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) + to remove the member from. in: path name: taskID required: true @@ -16510,7 +16550,7 @@ paths: type: string responses: "204": - description: Member removed + description: Success. The member is removed. default: content: application/json: @@ -16527,11 +16567,11 @@ paths: **Deprecated**: Tasks don't use `owner` and `member` roles. Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. - Retrieves all users that have owner permission for a task. + Lists all users that have the `owner` role for the specified task. operationId: GetTasksIDOwners parameters: - $ref: '#/components/parameters/TraceSpan' - - description: The ID of the task to retrieve owners for. + - description: A task ID. Specifies the task to retrieve owners for. in: path name: taskID required: true @@ -16579,14 +16619,17 @@ paths: **Deprecated**: Tasks don't use `owner` and `member` roles. Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. - Assigns a task `owner` role to a user. + Adds a specified user to owners of the specified task and then returns the + owner. Use this endpoint to create a _resource owner_ for the task. A _resource owner_ is a user with `role: owner` for a specific resource. operationId: PostTasksIDOwners parameters: - $ref: '#/components/parameters/TraceSpan' - - description: The task ID. + - description: | + A task ID. + Specifies the [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) for the owner. in: path name: taskID required: true @@ -16597,7 +16640,8 @@ paths: application/json: schema: $ref: '#/components/schemas/AddResourceMemberRequestBody' - description: A user to add as an owner of the task. + description: | + In the request body, provide an object that specifies the user. required: true responses: "201": @@ -16651,16 +16695,20 @@ paths: description: | **Deprecated**: Tasks don't use `owner` and `member` roles. Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. + + Removes an owner from a [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task). operationId: DeleteTasksIDOwnersID parameters: - $ref: '#/components/parameters/TraceSpan' - - description: The ID of the owner to remove. + - description: A user ID. Specifies the owner to remove from the [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task). in: path name: userID required: true schema: type: string - - description: The task ID. + - description: | + A task ID. + Specifies the [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) to remove the owner from. in: path name: taskID required: true @@ -16668,7 +16716,7 @@ paths: type: string responses: "204": - description: Owner removed + description: Success. The owner is removed. default: content: application/json: @@ -16681,22 +16729,25 @@ paths: /api/v2/tasks/{taskID}/runs: get: description: | - Retrieves a list of runs for a [task](https://docs.influxdata.com/influxdb/v2.3/process-data/). + Lists runs for the specified [task](https://docs.influxdata.com/influxdb/v2.3/process-data/). To limit which task runs are returned, pass query parameters in your request. - If no query parameters are passed, InfluxDB returns all task runs up to the default `limit`. + If you don't pass query parameters, InfluxDB returns all runs for the task + up to the default `limit`. operationId: GetTasksIDRuns parameters: - $ref: '#/components/parameters/TraceSpan' - description: | - The ID of the task to get runs for. - Only returns runs for this task. + A task ID. + Specifies the [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) to + to list runs for. in: path name: taskID required: true schema: type: string - - description: A task run ID. Only returns runs created after this run. + - description: A task run ID. Only returns runs created after the specified + run. in: query name: after schema: @@ -16712,7 +16763,7 @@ paths: type: integer - description: | A timestamp ([RFC3339 date/time format](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#rfc3339-timestamp)). - Only returns runs scheduled after this time. + Only returns runs scheduled after the specified time. in: query name: afterTime schema: @@ -16720,7 +16771,7 @@ paths: type: string - description: | A timestamp ([RFC3339 date/time format](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#rfc3339-timestamp)). - Only returns runs scheduled before this time. + Only returns runs scheduled before the specified time. in: query name: beforeTime schema: @@ -16752,10 +16803,18 @@ paths: To _retry_ a previous run (and avoid creating a new run), use the [`POST /api/v2/tasks/{taskID}/runs/{runID}/retry` endpoint](#operation/PostTasksIDRunsIDRetry). + + #### Limitations + + - Queuing a task run requires that the task's `status` property be set to `active`. operationId: PostTasksIDRuns parameters: - $ref: '#/components/parameters/TraceSpan' - - in: path + - description: | + A task ID. + Specifies the [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) to + to run. + in: path name: taskID required: true schema: @@ -16772,6 +16831,18 @@ paths: schema: $ref: '#/components/schemas/Run' description: Success. The run is scheduled to start. + "400": + content: + application/json: + examples: + inactiveTask: + summary: Can't run an inactive task + value: + code: invalid + message: 'failed to force run: inactive task' + schema: + $ref: '#/components/schemas/Error' + description: Bad request. "401": $ref: '#/components/responses/AuthorizationError' "500": @@ -16787,7 +16858,7 @@ paths: description: | Cancels a running [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task). - Use this endpoint with InfluxDB OSS to cancel a running task. + Use this endpoint to cancel a running task. #### InfluxDB Cloud @@ -16795,13 +16866,18 @@ paths: operationId: DeleteTasksIDRunsID parameters: - $ref: '#/components/parameters/TraceSpan' - - description: The ID of the task to cancel. + - description: | + A task ID. + Specifies the [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) to + to cancel. in: path name: taskID required: true schema: type: string - - description: The ID of the task run to cancel. + - description: | + A task run ID. + Specifies the task run to cancel. in: path name: runID required: true @@ -16846,19 +16922,22 @@ paths: - Tasks get: description: | - Retrieves a specific run for a [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task). + Retrieves the specified run for the specified [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task). Use this endpoint to retrieve detail and logs for a specific task run. operationId: GetTasksIDRunsID parameters: - $ref: '#/components/parameters/TraceSpan' - - description: The ID of the task to retrieve runs for. + - description: | + A task ID. + Specifies the [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) + that the task run belongs to. in: path name: taskID required: true schema: type: string - - description: The ID of the run to retrieve. + - description: A task run ID. Specifies the run to retrieve. in: path name: runID required: true @@ -16913,20 +16992,21 @@ paths: /api/v2/tasks/{taskID}/runs/{runID}/logs: get: description: | - Retrieves all logs for a task run. + Lists all logs for a task run. A log is a list of run events with `runID`, `time`, and `message` properties. - Use this endpoint to help analyze task performance and troubleshoot failed task runs. + Use this endpoint to help analyze [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) performance and troubleshoot failed task runs. operationId: GetTasksIDRunsIDLogs parameters: - $ref: '#/components/parameters/TraceSpan' - - description: The ID of the task to get logs for. + - description: A task ID. Specifies the [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) + that the run belongs to. in: path name: taskID required: true schema: type: string - - description: The ID of the run to get logs for. + - description: A run ID. Specifies the task run to list logs for. in: path name: runID required: true @@ -16983,34 +17063,34 @@ paths: $ref: '#/components/responses/InternalServerError' default: $ref: '#/components/responses/GeneralServerError' - summary: Retrieve all logs for a run + summary: List logs for a run tags: - Tasks /api/v2/tasks/{taskID}/runs/{runID}/retry: post: description: | - Queues a [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) run to - retry and returns the scheduled run. + Queues a [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) run to + retry and then returns the scheduled run. To manually start a _new_ task run, use the [`POST /api/v2/tasks/{taskID}/runs` endpoint](#operation/PostTasksIDRuns). #### Limitations - - The task must be _active_ (`status: "active"`). + - Queuing a task run requires that the task's `status` property be set to `active`. operationId: PostTasksIDRunsIDRetry parameters: - $ref: '#/components/parameters/TraceSpan' - description: | - A [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) ID. - Specifies the task to retry. + A task ID. + Specifies the [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) that the task run belongs to. in: path name: taskID required: true schema: type: string - description: | - A [task](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#task) run ID. + A task run ID. Specifies the task run to retry. To find a task run ID, use the diff --git a/src/cloud.yml b/src/cloud.yml index f88afcbb2..329549154 100644 --- a/src/cloud.yml +++ b/src/cloud.yml @@ -100,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 diff --git a/src/cloud/paths/tasks.yml b/src/cloud/paths/tasks.yml index 6e47dfe5f..7f9384da0 100644 --- a/src/cloud/paths/tasks.yml +++ b/src/cloud/paths/tasks.yml @@ -198,10 +198,11 @@ post: application/json: schema: $ref: "../schemas/TaskCreateRequest.yml" + examples: TaskWithFlux: $ref: "../../common/requestBody/examples/TaskRequestExamples.yml#/TaskWithFluxRequest" TaskWithScriptID: - $ref: "../../common/requestBody/examples/TaskRequestExamples.yml#/TaskWithScriptRequest" + $ref: "../requestBody/examples/TaskRequestExamples.yml#/TaskWithScriptRequest" responses: "201": description: Success. The response body contains a `tasks` list with the task. diff --git a/src/cloud/paths/tasks_taskID.yml b/src/cloud/paths/tasks_taskID.yml index 403e58bfe..ca5601697 100644 --- a/src/cloud/paths/tasks_taskID.yml +++ b/src/cloud/paths/tasks_taskID.yml @@ -84,7 +84,7 @@ patch: TaskWithFlux: $ref: "../../common/requestBody/examples/TaskRequestExamples.yml#/TaskWithFluxRequest" TaskWithScriptID: - $ref: "../../common/requestBody/examples/TaskRequestExamples.yml#/TaskWithScriptRequest" + $ref: "../requestBody/examples/TaskRequestExamples.yml#/TaskWithScriptRequest" parameters: - $ref: "../../common/parameters/TraceSpan.yml" - in: path diff --git a/src/cloud/requestBody/examples/TaskRequestExamples.yml b/src/cloud/requestBody/examples/TaskRequestExamples.yml new file mode 100644 index 000000000..5b4346d28 --- /dev/null +++ b/src/cloud/requestBody/examples/TaskRequestExamples.yml @@ -0,0 +1,17 @@ +TaskWithScriptRequest: + summary: A task with an invokable script + description: | + Sets properties for a task that runs an _invokable script_. + value: { + "name": "CPU Total 1 Hour New", + "every": "1h", + "scriptID": "SCRIPT_ID", + "scriptParameters": + { + "rangeStart": "-1h", + "bucket": "telegraf", + "filterField": "cpu-total" + }, + "status": "active", + "description": "This task runs an invokable script every hour with the defined parameters." + } diff --git a/src/cloud/schemas/TaskCreateRequest.yml b/src/cloud/schemas/TaskCreateRequest.yml index 258ed396d..ea1b8c2ba 100644 --- a/src/cloud/schemas/TaskCreateRequest.yml +++ b/src/cloud/schemas/TaskCreateRequest.yml @@ -21,4 +21,4 @@ properties: scriptID: $ref: ./TaskProperties.yml#/scriptID scriptParameters: - $ref: ./TaskProperties.yml#/scriptParameters \ No newline at end of file + $ref: ./TaskProperties.yml#/scriptParameters diff --git a/src/common/paths/tasks.yml b/src/common/paths/tasks.yml index c19ea65c9..999ed3b61 100644 --- a/src/common/paths/tasks.yml +++ b/src/common/paths/tasks.yml @@ -150,7 +150,7 @@ post: $ref: "../schemas/TaskCreateRequest.yml" examples: TaskWithFlux: - $ref: "../../common/requestBody/examples/TaskRequestExamples.yml#/TaskWithFluxRequest" + $ref: "../requestBody/examples/TaskRequestExamples.yml#/TaskWithFluxRequest" responses: "201": description: Success. The response body contains a `tasks` list with the task. diff --git a/src/common/paths/tasks_taskID.yml b/src/common/paths/tasks_taskID.yml index b6f815969..9452fbd38 100644 --- a/src/common/paths/tasks_taskID.yml +++ b/src/common/paths/tasks_taskID.yml @@ -59,7 +59,7 @@ patch: $ref: "../schemas/TaskUpdateRequest.yml" examples: TaskWithFlux: - $ref: "../../common/requestBody/examples/TaskRequestExamples.yml#/TaskWithFluxRequest" + $ref: "../requestBody/examples/TaskRequestExamples.yml#/TaskWithFluxRequest" parameters: - $ref: "../parameters/TraceSpan.yml" - in: path diff --git a/src/common/paths/tasks_taskID_runs.yml b/src/common/paths/tasks_taskID_runs.yml index 6c357d53a..8e9146e9a 100644 --- a/src/common/paths/tasks_taskID_runs.yml +++ b/src/common/paths/tasks_taskID_runs.yml @@ -111,6 +111,8 @@ post: description: Bad request. content: application/json: + schema: + $ref: "../schemas/Error.yml" examples: inactiveTask: summary: Can't run an inactive task diff --git a/src/common/requestBody/examples/AuthorizationRequestExamples.yml b/src/common/requestBody/examples/AuthorizationRequestExamples.yml index 110b0b1d3..7a488f855 100644 --- a/src/common/requestBody/examples/AuthorizationRequestExamples.yml +++ b/src/common/requestBody/examples/AuthorizationRequestExamples.yml @@ -1,48 +1,48 @@ AuthorizationPostRequest: - summary: An authorization for a resource type - description: Creates an authorization. - value: { - "orgID": "INFLUX_ORG_ID", - "description": "iot_users read buckets", - "permissions": [ - { - "action": "read", - "resource": { - "type": "buckets" - } - } - ] - } + summary: An authorization for a resource type + description: Creates an authorization. + value: { + "orgID": "INFLUX_ORG_ID", + "description": "iot_users read buckets", + "permissions": [ + { + "action": "read", + "resource": { + "type": "buckets" + } + } + ] + } AuthorizationWithResourcePostRequest: - summary: An authorization for a resource - description: Creates an authorization for access to a specific resource. - value: { - "orgID": "INFLUX_ORG_ID", - "description": "iot_users read buckets", - "permissions": [ - { - "action": "read", + summary: An authorization for a resource + description: Creates an authorization for access to a specific resource. + value: { + "orgID": "INFLUX_ORG_ID", + "description": "iot_users read buckets", + "permissions": [ + { + "action": "read", + "resource": { + "type": "buckets", + "id": "INFLUX_BUCKET_ID" + } + } + ] + } +AuthorizationWithUserPostRequest: + summary: An authorization scoped to a user + description: Creates an authorization scoped to a specific user. + value: { + "orgID": "INFLUX_ORG_ID", + "userID": "INFLUX_USER_ID", + "description": "iot_user write to bucket", + "permissions": [ + { + "action": "write", "resource": { "type": "buckets", "id": "INFLUX_BUCKET_ID" } - } - ] - } -AuthorizationWithUserPostRequest: - summary: An authorization scoped to a user - description: Creates an authorization scoped to a specific user. - value: { - "orgID": "INFLUX_ORG_ID", - "userID": "INFLUX_USER_ID", - "description": "iot_user write to bucket", - "permissions": [ - { - "action": "write", - "resource": { - "type": "buckets", - "id": "INFLUX_BUCKET_ID" - } - } - ] - } + } + ] + } diff --git a/src/common/requestBody/examples/TaskRequestExamples.yml b/src/common/requestBody/examples/TaskRequestExamples.yml index 65bb39b4c..f0248cead 100644 --- a/src/common/requestBody/examples/TaskRequestExamples.yml +++ b/src/common/requestBody/examples/TaskRequestExamples.yml @@ -4,31 +4,13 @@ TaskWithFluxRequest: Sets the `flux` property with Flux task options and a query. value: { "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\")", + 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 contains Flux that configures the task schedule - and downsamples CPU data every hour." - } -TaskWithScriptRequest: - summary: A task with an invokable script - description: | - Sets properties for a task that runs an _invokable script_. - value: { - "name": "CPU Total 1 Hour New", - "every": "1h", - "scriptID": "SCRIPT_ID", - "scriptParameters": - { - "rangeStart": "-1h", - "bucket": "telegraf", - "filterField": "cpu-total" - }, - "status": "active", - "description": "This task runs an invokable script every hour with the defined parameters." + "description": "This task contains Flux that configures the task schedule and downsamples CPU data every hour." }