diff --git a/beta/openapi.beta.yaml b/beta/openapi.beta.yaml index 3b987db..9a902b6 100644 --- a/beta/openapi.beta.yaml +++ b/beta/openapi.beta.yaml @@ -1,5 +1,5 @@ # Code generated by tools/betaspec from https://api-dev.doit.com/openapi.yaml — DO NOT EDIT. -# Source spec sha256: a86c9d3fbe5c8fe6c1ecf1b65bddd3955398026e6274d8ba1610b38fea0dd089 +# Source spec sha256: 0f07f4fc50d82326878f91bb89d4346e25ae717f737aa996a94a33066e0ecc9d # Curated by beta/manifest.yaml; regenerate with: go run ./tools/betaspec openapi: 3.0.1 info: @@ -266,9 +266,18 @@ paths: schema: type: string description: The unique ID of the async operation. + - name: fileOutput + in: query + description: Additionally render the operation's result as a file and return a signed URL to it in `fileOutput`. The file is generated from the result the operation already produced, not by re-running the query, and is stored beside that result for the operation's lifetime, so a repeat request for the same operation and format returns a fresh signed URL to the same file rather than rendering it again. Omit the parameter and the response is unchanged. Returns 422 when the operation predates file output support and has no stored render input; a transient rendering failure instead returns 200 with `result` and no `fileOutput`, so retry the request for the file. + schema: + type: string + enum: + - pdf + - png + example: pdf responses: "200": - description: OK — the operation succeeded; body is the report result, plus report metadata when the operation was started against a saved report. + description: OK — the operation succeeded; body is the report result, plus report metadata when the operation was started against a saved report, plus a fileOutput URL when one was requested. content: application/json: schema: @@ -338,6 +347,68 @@ paths: cacheHit: type: boolean description: If true, results were fetched from the cache. + details: + type: object + description: Optional metadata about the result. + properties: + valueAliases: + type: object + description: 'Display aliases for values that appear in `rows`, keyed by dimension id and then by the stored value (for example `{"fixed:cloud_provider": {"datadog_prod": "Datadog (prod)"}}`). Rows keep the stored values so they can be fed back into filters; apply the alias only when presenting a value. Present only when the customer has renamed a DataHub dataset whose dimension is part of the report.' + additionalProperties: + type: object + additionalProperties: + type: string + fileOutput: + type: string + format: uri + description: Signed URL the rendered file can be downloaded from. Present only when the fileOutput parameter was supplied and the file was rendered. Never a variant of the response — the result property above is returned either way, so a render that fails leaves result intact and omits fileOutput rather than failing the call. The URL is valid for 7 days; request the endpoint again for a fresh one. + example: https://storage.googleapis.com/doitintl-cmp-async-report-results/1a2b3c/f47ac10b.pdf?X-Goog-Signature=abc123 + examples: + withoutFileOutput: + summary: Results of an operation started from a saved report + value: + id: aBcD1234efGH5678ijKL + reportName: Daily cost by service + owner: analyst@example.com + type: custom + createTime: 1788912000000 + updateTime: 1789516800000 + urlUI: https://console.doit.com/customers/1a2b3c/analyze/reports/aBcD1234efGH5678ijKL + result: + schema: + - name: service + type: string + - name: cost + type: float + rows: + - - Compute Engine + - 1284.55 + - - Cloud Storage + - 96.4 + cacheHit: false + withPdfFileOutput: + summary: The same results with ?fileOutput=pdf, adding a signed URL + value: + id: aBcD1234efGH5678ijKL + reportName: Daily cost by service + owner: analyst@example.com + type: custom + createTime: 1788912000000 + updateTime: 1789516800000 + urlUI: https://console.doit.com/customers/1a2b3c/analyze/reports/aBcD1234efGH5678ijKL + result: + schema: + - name: service + type: string + - name: cost + type: float + rows: + - - Compute Engine + - 1284.55 + - - Cloud Storage + - 96.4 + cacheHit: false + fileOutput: https://storage.googleapis.com/doitintl-cmp-async-report-results/1a2b3c/f47ac10b.pdf?X-Goog-Signature=abc123 "400": $ref: "#/components/responses/400" "401": @@ -437,7 +508,7 @@ components: required: - operationId - status - - createdAt + - createTime - expireBy properties: operationId: @@ -452,7 +523,7 @@ components: - failed - canceled description: Current lifecycle status of the operation. - createdAt: + createTime: type: string format: date-time description: Time the operation was created. @@ -563,11 +634,6 @@ components: type: object description: Report configuration. properties: - metric: - deprecated: true - description: "Deprecated: Use 'metrics' instead." - allOf: - - $ref: "#/components/schemas/ExternalMetric" metrics: type: array description: The list of metrics to apply to the report. Custom metric can be used only once. Maximum number of metrics is 4. @@ -746,7 +812,7 @@ components: type: basic value: cost changeType: percentage - operator: ">=" + operator: gte values: - 50 aggregation: total @@ -775,8 +841,8 @@ components: - id: attribution type: attribution values: - - ExampleAttribution10 - - ExampleAttribution20 + - RB8DndcxODriK83IBXXf + - D7r4znsTj2UC95zGnunW inverse: true - id: cloud_provider type: fixed @@ -863,8 +929,9 @@ components: $ref: "#/components/schemas/ExternalMetric" operator: description: |- - Comparison operator for filtering metric values. Uses short names (`gt`, `gte`, …). - `limitByChange.operator` uses SQL-style symbols (`>`, `>=`, …) instead. + Comparison operator for filtering metric values: `gt` (Greater Than), `lt` (Less + Than), `lte` (Less Than or Equals), `gte` (Greater Than or Equals), `b` (Between), + `nb` (Not Between), `e` (Equals), `ne` (Not Equals). type: string enum: - gt @@ -1004,7 +1071,23 @@ components: ExternalLimitByChange: description: |- Limit by change filter. A report may configure at most two of - `metricFilter`, `limitByChange`, and top/bottom `group` limits — not all three. + `metricFilter`, `limitByChange`, and rank `group` limits — not all three. + + Without `secondaryTimeRange`, "change" is a period-over-period delta between + adjacent time buckets within the report's single range, and `metric` may be any + metric type. + + With `secondaryTimeRange` set, "change" instead compares each row's aggregate over + the primary range to its aggregate over the secondary range — the two ranges are + the two periods being compared, so a single time bucket per range (for example + "this month vs. last month") is valid. In this mode `metric` must be a basic metric + (`cost`, `usage`, or `savings`); a calculated or extended metric, or a report using + count aggregation, is rejected with + `LIMIT_BY_CHANGE_METRIC_NOT_ADDITIVE_WITH_SECONDARY`, since the cross-range delta + requires one summable number per range. A row-dimension tuple present in only one + range is treated as zero on the missing side: an absolute-change threshold is + evaluated normally, but a percentage-change threshold from zero is undefined and the + row cannot satisfy it. type: object required: - metric @@ -1022,19 +1105,22 @@ components: - absolute operator: type: string - description: Comparison operator for period-over-period deltas. + description: |- + Comparison operator for period-over-period deltas: `gt` (Greater Than), `gte` + (Greater Than or Equals), `lt` (Less Than), `lte` (Less Than or Equals), `b` + (Between), `nb` (Not Between). enum: - - ">" - - ">=" - - < - - <= - - between - - not_between + - gt + - gte + - lt + - lte + - b + - nb values: type: array description: |- - Threshold value(s). Unary operators use one entry; `between` and `not_between` - require two ordered entries. + Threshold value(s). Unary operators (`gt`, `gte`, `lt`, `lte`) use one entry; the range + operators (`b`, `nb`) require two ordered entries. items: type: number format: double @@ -1046,7 +1132,7 @@ components: type: basic value: cost changeType: percentage - operator: ">=" + operator: gte values: - 50 includeIncompleteData: false @@ -1098,7 +1184,7 @@ components: - unallocated ExternalRenderer: type: string - description: Type of visualization or output format. + description: Type of visualization or output format. cumulative_comparison requires daily datetime dimensions (year, month, day), total aggregation, one metric, a secondary time range, and no comparative or forecast. enum: - column_chart - stacked_column_chart @@ -1110,12 +1196,14 @@ components: - area_spline_chart - stacked_area_chart - treemap_chart + - sankey_chart - table - table_heatmap - table_row_heatmap - table_col_heatmap - - csv_export - - sheets_export + - column_and_line_chart + - trend_board + - cumulative_comparison ExternalSplit: type: object description: Specification of how to split costs. @@ -1208,7 +1296,7 @@ components: value: cost Limit: type: object - description: To limit the number of results based on ranking. See [Limit by top/bottom](https://help.doit.com/docs/cloud-analytics/reports/editing-your-cloud-report#limit-by-topbottom). + description: To limit the number of results based on ranking. See [Limit by rank](https://help.doit.com/docs/cloud-analytics/reports/editing-your-cloud-report#limit-by-topbottom). required: - metric properties: