{ "swagger": "2.0", "info": { "title": "CostManagementClient", "description": "CostManagement management client provides access to CostManagement resources for Azure Enterprise Subscriptions.", "version": "2024-08-01" }, "tags": [ { "name": "Benefits API", "description": "APIs for getting benefit recommendations and benefit utilization summaries." } ], "host": "management.azure.com", "schemes": [ "https" ], "consumes": [ "application/json" ], "produces": [ "application/json" ], "security": [ { "azure_auth": [ "user_impersonation" ] } ], "securityDefinitions": { "azure_auth": { "type": "oauth2", "description": "Azure Active Directory OAuth2 Flow.", "authorizationUrl": "https://login.microsoftonline.com/common/oauth2/authorize", "flow": "implicit", "scopes": { "user_impersonation": "impersonate your user account" } } }, "paths": { "/{billingScope}/providers/Microsoft.CostManagement/benefitRecommendations": { "get": { "tags": [ "BenefitRecommendations" ], "description": "List of recommendations for purchasing savings plan.", "externalDocs": { "url": "https://docs.microsoft.com/en-us/rest/api/CostManagement/" }, "x-ms-examples": { "BenefitRecommendationsBillingAccountList": { "$ref": "./examples/BenefitRecommendationsByBillingAccount.json" } }, "operationId": "BenefitRecommendations_List", "parameters": [ { "$ref": "#/parameters/benefitRecommendationsFilterParameter" }, { "name": "$orderby", "in": "query", "description": "May be used to order the recommendations by: properties/armSkuName. For the savings plan, the results are in order by default. There is no need to use this clause.", "type": "string", "x-ms-parameter-location": "method" }, { "name": "$expand", "in": "query", "description": "May be used to expand the properties by: properties/usage, properties/allRecommendationDetails", "type": "string", "x-ms-parameter-location": "method" }, { "$ref": "../../../../../../common-types/resource-management/v2/types.json#/parameters/ApiVersionParameter" }, { "$ref": "#/parameters/billingScopeBenefitRecommendationParameter" } ], "responses": { "200": { "description": "OK. The request has succeeded.", "schema": { "$ref": "#/definitions/benefitRecommendationsListResult" } }, "default": { "description": "Error response describing why the operation failed.", "schema": { "$ref": "common-types.json#/definitions/ErrorResponse" } } }, "x-ms-pageable": { "nextLinkName": "nextLink" } } }, "/providers/Microsoft.Billing/billingAccounts/{billingAccountId}/providers/Microsoft.CostManagement/benefitUtilizationSummaries": { "get": { "tags": [ "BenefitUtilizationSummaries" ], "operationId": "BenefitUtilizationSummaries_ListByBillingAccountId", "description": "Lists savings plan utilization summaries for the enterprise agreement scope. Supported at grain values: 'Daily' and 'Monthly'.", "externalDocs": { "url": "https://docs.microsoft.com/en-us/rest/api/cost-management/" }, "parameters": [ { "$ref": "../../../../../../common-types/resource-management/v2/types.json#/parameters/ApiVersionParameter" }, { "$ref": "common-types.json#/parameters/billingAccountIdParameter" }, { "$ref": "#/parameters/grainParameter" }, { "name": "filter", "in": "query", "description": "Supports filtering by properties/benefitId, properties/benefitOrderId and properties/usageDate.", "required": false, "type": "string", "x-ms-parameter-location": "method" } ], "responses": { "200": { "description": "OK. The request has succeeded.", "schema": { "$ref": "#/definitions/BenefitUtilizationSummariesListResult" } }, "default": { "description": "Error response describing why the operation failed.", "schema": { "$ref": "common-types.json#/definitions/ErrorResponse" } } }, "x-ms-examples": { "SavingsPlanUtilizationSummaries-BillingAccount": { "$ref": "./examples/BenefitUtilizationSummaries/SavingsPlan-BillingAccount.json" } }, "x-ms-pageable": { "nextLinkName": "nextLink" } } }, "/providers/Microsoft.Billing/billingAccounts/{billingAccountId}/billingProfiles/{billingProfileId}/providers/Microsoft.CostManagement/benefitUtilizationSummaries": { "get": { "tags": [ "BenefitUtilizationSummaries" ], "operationId": "BenefitUtilizationSummaries_ListByBillingProfileId", "description": "Lists savings plan utilization summaries for billing profile. Supported at grain values: 'Daily' and 'Monthly'.", "externalDocs": { "url": "https://docs.microsoft.com/en-us/rest/api/cost-management/" }, "parameters": [ { "$ref": "../../../../../../common-types/resource-management/v2/types.json#/parameters/ApiVersionParameter" }, { "$ref": "common-types.json#/parameters/billingAccountIdParameter" }, { "$ref": "common-types.json#/parameters/billingProfileIdParameter" }, { "$ref": "#/parameters/grainParameter" }, { "name": "filter", "in": "query", "description": "Supports filtering by properties/benefitId, properties/benefitOrderId and properties/usageDate.", "required": false, "type": "string", "x-ms-parameter-location": "method" } ], "responses": { "200": { "description": "OK. The request has succeeded.", "schema": { "$ref": "#/definitions/BenefitUtilizationSummariesListResult" } }, "default": { "description": "Error response describing why the operation failed.", "schema": { "$ref": "common-types.json#/definitions/ErrorResponse" } } }, "x-ms-examples": { "SavingsPlanUtilizationSummaries-BillingProfile": { "$ref": "./examples/BenefitUtilizationSummaries/SavingsPlan-BillingProfile.json" } }, "x-ms-pageable": { "nextLinkName": "nextLink" } } }, "/providers/Microsoft.BillingBenefits/savingsPlanOrders/{savingsPlanOrderId}/providers/Microsoft.CostManagement/benefitUtilizationSummaries": { "get": { "tags": [ "BenefitUtilizationSummaries" ], "operationId": "BenefitUtilizationSummaries_ListBySavingsPlanOrder", "description": "Lists the savings plan utilization summaries for daily or monthly grain.", "externalDocs": { "url": "https://docs.microsoft.com/en-us/rest/api/cost-management/" }, "x-ms-examples": { "SavingsPlanUtilizationSummariesDaily": { "$ref": "./examples/BenefitUtilizationSummaries/SavingsPlan-SavingsPlanOrderId-Daily.json" } }, "parameters": [ { "$ref": "../../../../../../common-types/resource-management/v2/types.json#/parameters/ApiVersionParameter" }, { "name": "$filter", "description": "Supports filtering by properties/usageDate.", "in": "query", "required": false, "type": "string" }, { "$ref": "#/parameters/grainParameter" }, { "$ref": "#/parameters/savingsPlanOrderIdParameter" } ], "responses": { "200": { "description": "OK. The request has succeeded.", "schema": { "$ref": "#/definitions/BenefitUtilizationSummariesListResult" } }, "default": { "description": "Error response describing why the operation failed.", "schema": { "$ref": "common-types.json#/definitions/ErrorResponse" } } }, "x-ms-pageable": { "nextLinkName": "nextLink" } } }, "/providers/Microsoft.BillingBenefits/savingsPlanOrders/{savingsPlanOrderId}/savingsPlans/{savingsPlanId}/providers/Microsoft.CostManagement/benefitUtilizationSummaries": { "get": { "tags": [ "BenefitUtilizationSummaries" ], "operationId": "BenefitUtilizationSummaries_ListBySavingsPlanId", "description": "Lists the savings plan utilization summaries for daily or monthly grain.", "externalDocs": { "url": "https://docs.microsoft.com/en-us/rest/api/cost-management/" }, "x-ms-examples": { "SavingsPlanUtilizationSummariesMonthlyWithSavingsPlanId": { "$ref": "./examples/BenefitUtilizationSummaries/SavingsPlan-SavingsPlanId-Monthly.json" } }, "parameters": [ { "$ref": "../../../../../../common-types/resource-management/v2/types.json#/parameters/ApiVersionParameter" }, { "name": "$filter", "description": "Supports filtering by properties/usageDate.", "in": "query", "required": false, "type": "string" }, { "$ref": "#/parameters/grainParameter" }, { "$ref": "#/parameters/savingsPlanOrderIdParameter" }, { "$ref": "#/parameters/savingsPlanIdParameter" } ], "responses": { "200": { "description": "OK. The request has succeeded.", "schema": { "$ref": "#/definitions/BenefitUtilizationSummariesListResult" } }, "default": { "description": "Error response describing why the operation failed.", "schema": { "$ref": "common-types.json#/definitions/ErrorResponse" } } }, "x-ms-pageable": { "nextLinkName": "nextLink" } } }, "/providers/Microsoft.Billing/billingAccounts/{billingAccountId}/providers/Microsoft.CostManagement/generateBenefitUtilizationSummariesReport": { "post": { "tags": [ "BenefitUtilizationSummariesAsync" ], "operationId": "GenerateBenefitUtilizationSummariesReport_GenerateByBillingAccount", "description": "Triggers generation of a benefit utilization summaries report for the provided billing account. This API supports only enrollment accounts.", "externalDocs": { "url": "https://docs.microsoft.com/rest/api/cost-management/" }, "x-ms-examples": { "GenerateUtilizationSummariesReportByBillingAccount": { "$ref": "./examples/BenefitUtilizationSummaries/Async/GenerateBenefitUtilizationSummariesReportByBillingAccount.json" } }, "x-ms-long-running-operation": true, "x-ms-long-running-operation-options": { "final-state-via": "location" }, "parameters": [ { "$ref": "common-types.json#/parameters/billingAccountIdParameter" }, { "$ref": "../../../../../../common-types/resource-management/v2/types.json#/parameters/ApiVersionParameter" }, { "name": "benefitUtilizationSummariesRequest", "description": "Async Benefit Utilization Summary report to be created.", "in": "body", "required": true, "schema": { "$ref": "#/definitions/BenefitUtilizationSummariesRequest" } } ], "responses": { "200": { "description": "The status of the generation of the benefit utilization summaries report. This could be in progress, failed, or completed.", "schema": { "$ref": "#/definitions/BenefitUtilizationSummariesOperationStatus" } }, "202": { "description": "Accepted. Request will be processed. Use the location header to check the status.", "headers": { "Location": { "description": "The URL to check the status of the asynchronous operation.", "type": "string" }, "Retry-After": { "description": "The amount of delay to use while the status of the operation is checked. The value is expressed in seconds.", "format": "int32", "type": "integer" } } }, "default": { "description": "Error response describing why the operation failed.", "schema": { "$ref": "../../../../../../common-types/resource-management/v5/types.json#/definitions/ErrorResponse" } } } } }, "/providers/Microsoft.Billing/billingAccounts/{billingAccountId}/billingProfiles/{billingProfileId}/providers/Microsoft.CostManagement/generateBenefitUtilizationSummariesReport": { "post": { "tags": [ "BenefitUtilizationSummariesAsync" ], "operationId": "GenerateBenefitUtilizationSummariesReport_GenerateByBillingProfile", "description": "Triggers generation of a benefit utilization summaries report for the provided billing account and billing profile.", "externalDocs": { "url": "https://docs.microsoft.com/rest/api/cost-management/" }, "x-ms-examples": { "GenerateUtilizationSummariesReportByBillingProfile": { "$ref": "./examples/BenefitUtilizationSummaries/Async/GenerateBenefitUtilizationSummariesReportByBillingProfile.json" } }, "x-ms-long-running-operation": true, "x-ms-long-running-operation-options": { "final-state-via": "location" }, "parameters": [ { "$ref": "common-types.json#/parameters/billingAccountIdParameter" }, { "$ref": "common-types.json#/parameters/billingProfileIdParameter" }, { "$ref": "../../../../../../common-types/resource-management/v2/types.json#/parameters/ApiVersionParameter" }, { "name": "benefitUtilizationSummariesRequest", "description": "Async Benefit Utilization Summary report to be created.", "in": "body", "required": true, "schema": { "$ref": "#/definitions/BenefitUtilizationSummariesRequest" } } ], "responses": { "200": { "description": "The status of the generation of the benefit utilization summaries report. This could be in progress, failed, or completed.", "schema": { "$ref": "#/definitions/BenefitUtilizationSummariesOperationStatus" } }, "202": { "description": "Accepted. Request will be processed. Use the location header to check the status.", "headers": { "Location": { "description": "The URL to check the status of the asynchronous operation.", "type": "string" }, "Retry-After": { "description": "The amount of delay to use while the status of the operation is checked. The value is expressed in seconds.", "format": "int32", "type": "integer" } } }, "default": { "description": "Error response describing why the operation failed.", "schema": { "$ref": "../../../../../../common-types/resource-management/v5/types.json#/definitions/ErrorResponse" } } } } }, "/providers/Microsoft.Capacity/reservationorders/{reservationOrderId}/providers/Microsoft.CostManagement/generateBenefitUtilizationSummariesReport": { "post": { "tags": [ "BenefitUtilizationSummariesAsync" ], "operationId": "GenerateBenefitUtilizationSummariesReport_GenerateByReservationOrderId", "description": "Triggers generation of a benefit utilization summaries report for the provided reservation order.", "externalDocs": { "url": "https://docs.microsoft.com/rest/api/cost-management/" }, "x-ms-examples": { "GenerateUtilizationSummariesReportByReservationOrder": { "$ref": "./examples/BenefitUtilizationSummaries/Async/GenerateBenefitUtilizationSummariesReportByReservationOrder.json" } }, "x-ms-long-running-operation": true, "x-ms-long-running-operation-options": { "final-state-via": "location" }, "parameters": [ { "$ref": "#/parameters/reservationOrderIdParameter" }, { "$ref": "../../../../../../common-types/resource-management/v2/types.json#/parameters/ApiVersionParameter" }, { "name": "benefitUtilizationSummariesRequest", "description": "Async Benefit Utilization Summary report to be created.", "in": "body", "required": true, "schema": { "$ref": "#/definitions/BenefitUtilizationSummariesRequest" } } ], "responses": { "200": { "description": "The status of the generation of the benefit utilization summaries report. This could be in progress, failed, or completed.", "schema": { "$ref": "#/definitions/BenefitUtilizationSummariesOperationStatus" } }, "202": { "description": "Accepted. Request will be processed. Use the location header to check the status.", "headers": { "Location": { "description": "The URL to check the status of the asynchronous operation.", "type": "string" }, "Retry-After": { "description": "The amount of delay to use while the status of the operation is checked. The value is expressed in seconds.", "format": "int32", "type": "integer" } } }, "default": { "description": "Error response describing why the operation failed.", "schema": { "$ref": "../../../../../../common-types/resource-management/v5/types.json#/definitions/ErrorResponse" } } } } }, "/providers/Microsoft.Capacity/reservationorders/{reservationOrderId}/reservations/{reservationId}/providers/Microsoft.CostManagement/generateBenefitUtilizationSummariesReport": { "post": { "tags": [ "BenefitUtilizationSummariesAsync" ], "operationId": "GenerateBenefitUtilizationSummariesReport_GenerateByReservationId", "description": "Triggers generation of a benefit utilization summaries report for the provided reservation.", "externalDocs": { "url": "https://docs.microsoft.com/rest/api/cost-management/" }, "x-ms-examples": { "GenerateUtilizationSummariesReportByReservation": { "$ref": "./examples/BenefitUtilizationSummaries/Async/GenerateBenefitUtilizationSummariesReportByReservation.json" } }, "x-ms-long-running-operation": true, "x-ms-long-running-operation-options": { "final-state-via": "location" }, "parameters": [ { "$ref": "#/parameters/reservationOrderIdParameter" }, { "$ref": "#/parameters/reservationIdParameter" }, { "$ref": "../../../../../../common-types/resource-management/v2/types.json#/parameters/ApiVersionParameter" }, { "name": "benefitUtilizationSummariesRequest", "description": "Async Benefit Utilization Summary report to be created.", "in": "body", "required": true, "schema": { "$ref": "#/definitions/BenefitUtilizationSummariesRequest" } } ], "responses": { "200": { "description": "The status of the generation of the benefit utilization summaries report. This could be in progress, failed, or completed.", "schema": { "$ref": "#/definitions/BenefitUtilizationSummariesOperationStatus" } }, "202": { "description": "Accepted. Request will be processed. Use the location header to check the status.", "headers": { "Location": { "description": "The URL to check the status of the asynchronous operation.", "type": "string" }, "Retry-After": { "description": "The amount of delay to use while the status of the operation is checked. The value is expressed in seconds.", "format": "int32", "type": "integer" } } }, "default": { "description": "Error response describing why the operation failed.", "schema": { "$ref": "../../../../../../common-types/resource-management/v5/types.json#/definitions/ErrorResponse" } } } } }, "/providers/Microsoft.BillingBenefits/savingsPlanOrders/{savingsPlanOrderId}/providers/Microsoft.CostManagement/generateBenefitUtilizationSummariesReport": { "post": { "tags": [ "BenefitUtilizationSummariesAsync" ], "operationId": "GenerateBenefitUtilizationSummariesReport_GenerateBySavingsPlanOrderId", "description": "Triggers generation of a benefit utilization summaries report for the provided savings plan order.", "externalDocs": { "url": "https://docs.microsoft.com/rest/api/cost-management/" }, "x-ms-examples": { "GenerateUtilizationSummariesReportBySavingsPlanOrder": { "$ref": "./examples/BenefitUtilizationSummaries/Async/GenerateBenefitUtilizationSummariesReportBySavingsPlanOrder.json" } }, "x-ms-long-running-operation": true, "x-ms-long-running-operation-options": { "final-state-via": "location" }, "parameters": [ { "$ref": "#/parameters/savingsPlanOrderIdParameter" }, { "$ref": "../../../../../../common-types/resource-management/v2/types.json#/parameters/ApiVersionParameter" }, { "name": "benefitUtilizationSummariesRequest", "description": "Async Benefit Utilization Summary report to be created.", "in": "body", "required": true, "schema": { "$ref": "#/definitions/BenefitUtilizationSummariesRequest" } } ], "responses": { "200": { "description": "The status of the generation of the benefit utilization summaries report. This could be in progress, failed, or completed.", "schema": { "$ref": "#/definitions/BenefitUtilizationSummariesOperationStatus" } }, "202": { "description": "Accepted. Request will be processed. Use the location header to check the status.", "headers": { "Location": { "description": "The URL to check the status of the asynchronous operation.", "type": "string" }, "Retry-After": { "description": "The amount of delay to use while the status of the operation is checked. The value is expressed in seconds.", "format": "int32", "type": "integer" } } }, "default": { "description": "Error response describing why the operation failed.", "schema": { "$ref": "../../../../../../common-types/resource-management/v5/types.json#/definitions/ErrorResponse" } } } } }, "/providers/Microsoft.BillingBenefits/savingsPlanOrders/{savingsPlanOrderId}/savingsPlans/{savingsPlanId}/providers/Microsoft.CostManagement/generateBenefitUtilizationSummariesReport": { "post": { "tags": [ "BenefitUtilizationSummariesAsync" ], "operationId": "GenerateBenefitUtilizationSummariesReport_GenerateBySavingsPlanId", "description": "Triggers generation of a benefit utilization summaries report for the provided savings plan.", "externalDocs": { "url": "https://docs.microsoft.com/rest/api/cost-management/" }, "x-ms-examples": { "GenerateUtilizationSummariesReportBySavingsPlan": { "$ref": "./examples/BenefitUtilizationSummaries/Async/GenerateBenefitUtilizationSummariesReportBySavingsPlan.json" } }, "x-ms-long-running-operation": true, "x-ms-long-running-operation-options": { "final-state-via": "location" }, "parameters": [ { "$ref": "#/parameters/savingsPlanOrderIdParameter" }, { "$ref": "#/parameters/savingsPlanIdParameter" }, { "$ref": "../../../../../../common-types/resource-management/v2/types.json#/parameters/ApiVersionParameter" }, { "name": "benefitUtilizationSummariesRequest", "description": "Async Benefit Utilization Summary report to be created.", "in": "body", "required": true, "schema": { "$ref": "#/definitions/BenefitUtilizationSummariesRequest" } } ], "responses": { "200": { "description": "The status of the generation of the benefit utilization summaries report. This could be in progress, failed, or completed.", "schema": { "$ref": "#/definitions/BenefitUtilizationSummariesOperationStatus" } }, "202": { "description": "Accepted. Request will be processed. Use the location header to check the status.", "headers": { "Location": { "description": "The URL to check the status of the asynchronous operation.", "type": "string" }, "Retry-After": { "description": "The amount of delay to use while the status of the operation is checked. The value is expressed in seconds.", "format": "int32", "type": "integer" } } }, "default": { "description": "Error response describing why the operation failed.", "schema": { "$ref": "../../../../../../common-types/resource-management/v5/types.json#/definitions/ErrorResponse" } } } } } }, "definitions": { "benefitRecommendationsListResult": { "type": "object", "properties": { "value": { "type": "array", "description": "The list of benefit recommendations.", "readOnly": true, "items": { "$ref": "#/definitions/benefitRecommendationModel" } }, "nextLink": { "type": "string", "description": "The link (URL) to the next page of results.", "readOnly": true, "format": "uri" } }, "description": "Result of listing benefit recommendations." }, "benefitRecommendationModel": { "type": "object", "description": "benefit plan recommendation details.", "allOf": [ { "$ref": "#/definitions/BenefitResource" } ], "properties": { "properties": { "type": "object", "$ref": "#/definitions/benefitRecommendationProperties" } } }, "benefitRecommendationProperties": { "type": "object", "description": "The properties of the benefit recommendations.", "discriminator": "scope", "properties": { "firstConsumptionDate": { "type": "string", "description": "The first usage date used for looking back for computing the recommendations.", "readOnly": true, "format": "date-time" }, "lastConsumptionDate": { "type": "string", "description": "The last usage date used for looking back for computing the recommendations.", "readOnly": true, "format": "date-time" }, "lookBackPeriod": { "description": "The number of days of usage evaluated for computing the recommendations.", "$ref": "#/definitions/LookBackPeriod" }, "totalHours": { "type": "integer", "format": "int32", "description": "The total hours for which the cost is covered. Its equal to number of records in a property 'properties/usage/charges'.", "readOnly": true }, "usage": { "type": "object", "description": "On-demand charges between firstConsumptionDate and lastConsumptionDate that were used for computing benefit recommendations.", "$ref": "#/definitions/recommendationUsageDetails" }, "armSkuName": { "description": "ARM SKU name. 'Compute_Savings_Plan' for SavingsPlan.", "type": "string", "readOnly": true }, "term": { "description": "Term period of the benefit. For example, P1Y or P3Y.", "$ref": "#/definitions/Term" }, "commitmentGranularity": { "description": "Grain of the proposed commitment amount. Supported values: 'Hourly'", "$ref": "#/definitions/Grain" }, "currencyCode": { "type": "string", "description": "An ISO 4217 currency code identifier for the costs and savings amounts.", "readOnly": true }, "costWithoutBenefit": { "type": "number", "format": "decimal", "description": "The current cost without benefit, corresponds to 'totalHours' in the look-back period.", "readOnly": true }, "recommendationDetails": { "type": "object", "description": "The details of the proposed recommendation.", "$ref": "#/definitions/allSavingsBenefitDetails" }, "allRecommendationDetails": { "type": "object", "description": "The list of all benefit recommendations with the recommendation details.", "readOnly": true, "$ref": "#/definitions/allSavingsList" }, "scope": { "description": "Benefit scope. For example, Single or Shared.", "$ref": "#/definitions/RecommendationScope" } }, "required": [ "scope" ] }, "singleScopeBenefitRecommendationProperties": { "type": "object", "description": "The properties of the benefit recommendations when scope is 'Single'.", "x-ms-discriminator-value": "Single", "properties": { "subscriptionId": { "type": "string", "description": "The subscription ID that this single scope recommendation is for. Applicable only if recommendation is for 'Single' scope.", "readOnly": true }, "resourceGroup": { "type": "string", "description": "The resource group that this single scope recommendation is for. Applicable only if recommendation is for 'Single' scope and 'ResourceGroup' request scope.", "readOnly": true } }, "allOf": [ { "$ref": "#/definitions/benefitRecommendationProperties" } ] }, "sharedScopeBenefitRecommendationProperties": { "type": "object", "description": "The properties of the benefit recommendation when scope is 'Shared'.", "x-ms-discriminator-value": "Shared", "allOf": [ { "$ref": "#/definitions/benefitRecommendationProperties" } ] }, "recommendationUsageDetails": { "type": "object", "description": "On-demand charges between firstConsumptionDate and lastConsumptionDate that were used for computing benefit recommendations.", "properties": { "usageGrain": { "description": "The grain of the usage. Supported values: 'Hourly'", "$ref": "#/definitions/Grain" }, "charges": { "type": "array", "description": "On-demand charges for each hour between firstConsumptionDate and lastConsumptionDate that were used for computing benefit recommendations.", "readOnly": true, "items": { "type": "number", "format": "decimal" } } } }, "allSavingsList": { "type": "object", "properties": { "value": { "type": "array", "description": "The list of benefit recommendations with the recommendation details..", "readOnly": true, "items": { "$ref": "#/definitions/allSavingsBenefitDetails" }, "x-ms-identifiers": [] }, "nextLink": { "type": "string", "description": "The link (URL) to the next page of results.", "readOnly": true, "format": "uri" } }, "description": "The list of all benefit recommendations with the recommendation details." }, "allSavingsBenefitDetails": { "description": "Benefit recommendation details.", "type": "object", "properties": { "overageCost": { "type": "number", "format": "decimal", "description": "The difference between total cost and benefit cost for the 'totalHours' in the look-back period.", "readOnly": true }, "benefitCost": { "type": "number", "format": "decimal", "description": "The estimated cost with benefit for the 'totalHours' in the look-back period. It's equal to (commitmentAmount * totalHours)", "readOnly": true }, "totalCost": { "type": "number", "format": "decimal", "description": "Total cost, which is sum of benefit cost and overage cost.", "readOnly": true }, "savingsAmount": { "type": "number", "format": "decimal", "description": "The amount saved for the 'totalHours' in the look-back period, by purchasing the recommended quantity of the benefit.", "readOnly": true }, "savingsPercentage": { "type": "number", "format": "decimal", "description": "The savings in percentage for the 'totalHours' in the look-back period, by purchasing the recommended quantity of benefit.", "readOnly": true }, "coveragePercentage": { "description": "Estimated benefit coverage percentage for the 'totalHours' in the look-back period, with this commitment.", "type": "number", "format": "decimal", "readOnly": true }, "commitmentAmount": { "description": "The commitment amount at the commitmentGranularity.", "type": "number", "format": "decimal", "readOnly": true }, "averageUtilizationPercentage": { "description": "Estimated average utilization percentage for the 'totalHours' in the look-back period, with this commitment.", "type": "number", "format": "decimal", "readOnly": true }, "wastageCost": { "description": "Estimated unused portion of the 'benefitCost'.", "type": "number", "format": "decimal", "readOnly": true } } }, "BenefitKind": { "type": "string", "description": "Kind/type of the benefit.", "enum": [ "IncludedQuantity", "Reservation", "SavingsPlan" ], "x-ms-enum": { "name": "benefitKind", "modelAsString": true, "values": [ { "value": "IncludedQuantity", "description": "Benefit is IncludedQuantity.", "name": "IncludedQuantity" }, { "value": "Reservation", "description": "Benefit is Reservation.", "name": "Reservation" }, { "value": "SavingsPlan", "description": "Benefit is SavingsPlan.", "name": "SavingsPlan" } ] } }, "RecommendationScope": { "type": "string", "description": "Kind of the recommendation scope.", "enum": [ "Single", "Shared" ], "x-ms-enum": { "name": "scope", "modelAsString": true, "values": [ { "value": "Single", "description": "Single scope recommendation.", "name": "Single" }, { "value": "Shared", "description": "Shared scope recommendation.", "name": "Shared" } ] } }, "Grain": { "type": "string", "description": "Grain which corresponds to value.", "enum": [ "Hourly", "Daily", "Monthly" ], "x-ms-enum": { "name": "grain", "modelAsString": true, "values": [ { "value": "Hourly", "description": "Hourly grain corresponds to value per hour.", "name": "Hourly" }, { "value": "Daily", "description": "Hourly grain corresponds to value per day.", "name": "Daily" }, { "value": "Monthly", "description": "Hourly grain corresponds to value per month.", "name": "Monthly" } ] } }, "Term": { "type": "string", "description": "Grain which corresponds to value.", "enum": [ "P1Y", "P3Y" ], "x-ms-enum": { "name": "term", "modelAsString": true, "values": [ { "value": "P1Y", "description": "Benefit term is 1 year.", "name": "P1Y" }, { "value": "P3Y", "description": "Benefit term is 3 years.", "name": "P3Y" } ] } }, "LookBackPeriod": { "type": "string", "description": "The number of days used to look back.", "enum": [ "Last7Days", "Last30Days", "Last60Days" ], "x-ms-enum": { "name": "lookBackPeriod", "modelAsString": true, "values": [ { "value": "Last7Days", "description": "7 days used to look back.", "name": "Last7Days" }, { "value": "Last30Days", "description": "30 days used to look back.", "name": "Last30Days" }, { "value": "Last60Days", "description": "60 days used to look back.", "name": "Last60Days" } ] } }, "BenefitResource": { "type": "object", "description": "The benefit resource model definition.", "allOf": [ { "$ref": "../../../../../../common-types/resource-management/v2/types.json#/definitions/Resource" } ], "properties": { "kind": { "description": "Reservation or SavingsPlan.", "$ref": "#/definitions/BenefitKind" } }, "x-ms-azure-resource": true }, "BenefitUtilizationSummariesListResult": { "description": "List of benefit utilization summaries.", "type": "object", "properties": { "value": { "description": "The list of benefit utilization summaries.", "type": "array", "readOnly": true, "items": { "$ref": "#/definitions/BenefitUtilizationSummary" } }, "nextLink": { "description": "The link (URL) to the next page of results.", "type": "string", "readOnly": true, "format": "uri" } } }, "BenefitUtilizationSummary": { "description": "Benefit utilization summary resource.", "discriminator": "kind", "type": "object", "required": [ "kind" ], "allOf": [ { "$ref": "../../../../../../common-types/resource-management/v2/types.json#/definitions/Resource" } ], "properties": { "kind": { "description": "Supported values: 'SavingsPlan'.", "$ref": "#/definitions/BenefitKind" } } }, "BenefitUtilizationSummaryProperties": { "description": "The properties of a benefit utilization summary.", "type": "object", "properties": { "armSkuName": { "description": "ARM SKU name. For example, 'Compute_Savings_Plan' for savings plan.", "type": "string", "readOnly": true }, "benefitId": { "description": "The benefit ID is the identifier of the benefit.", "type": "string", "readOnly": true }, "benefitOrderId": { "description": "The benefit order ID is the identifier for a benefit purchase.", "type": "string", "readOnly": true }, "benefitType": { "description": "The benefit type. Supported values: 'SavingsPlan'.", "$ref": "#/definitions/BenefitKind" }, "usageDate": { "description": "Date corresponding to the utilization summary record. If the grain of data is monthly, value for this field will be first day of the month.", "type": "string", "format": "date-time", "readOnly": true } } }, "IncludedQuantityUtilizationSummary": { "description": "Included Quantity utilization summary resource.", "x-ms-discriminator-value": "IncludedQuantity", "type": "object", "allOf": [ { "$ref": "#/definitions/BenefitUtilizationSummary" } ], "properties": { "properties": { "x-ms-client-flatten": true, "$ref": "#/definitions/IncludedQuantityUtilizationSummaryProperties", "title": "Benefit utilization summary for benefit kind Included Quantity." } } }, "IncludedQuantityUtilizationSummaryProperties": { "type": "object", "description": "Included Quantity utilization summary properties.", "allOf": [ { "$ref": "#/definitions/BenefitUtilizationSummaryProperties" } ], "properties": { "utilizationPercentage": { "description": "This is the utilized percentage for the benefit ID.", "type": "number", "format": "decimal", "readOnly": true } } }, "SavingsPlanUtilizationSummary": { "description": "Savings plan utilization summary resource.", "x-ms-discriminator-value": "SavingsPlan", "type": "object", "allOf": [ { "$ref": "#/definitions/BenefitUtilizationSummary" } ], "properties": { "properties": { "x-ms-client-flatten": true, "$ref": "#/definitions/SavingsPlanUtilizationSummaryProperties", "title": "Benefit utilization Summary for benefit kind savings plan." } } }, "SavingsPlanUtilizationSummaryProperties": { "type": "object", "description": "Savings plan utilization summary properties.", "allOf": [ { "$ref": "#/definitions/BenefitUtilizationSummaryProperties" } ], "properties": { "avgUtilizationPercentage": { "description": "This is the average hourly utilization for each date range that corresponds to given grain (Daily, Monthly). Suppose the API call is for usageDate > 2024-08-01 and usageDate < 2022-10-31 at a daily granularity. There will be one record per benefit id for each day. For a single day, the avgUtilizationPercentage value will be equal to the average of the set of values where the set contains 24 utilization percentage entries one for each hour in a specific day.", "type": "number", "format": "decimal", "readOnly": true }, "minUtilizationPercentage": { "description": "This is the minimum hourly utilization for each date range that corresponds to given grain (Daily, Monthly). Suppose the API call is for usageDate > 2024-08-01 and usageDate < 2022-10-31 at a daily granularity. There will be one record per benefit id for each day. For a single day, the minUtilizationPercentage value will be equal to the smallest in the set of values where the set contains 24 utilization percentage entries one for each hour in a specific day. If on the day 2022-10-18, the lowest utilization percentage was 10% at hour 4, then the value for the minUtilizationPercentage in the response will be 10%.", "type": "number", "format": "decimal", "readOnly": true }, "maxUtilizationPercentage": { "description": "This is the maximum hourly utilization for each date range that corresponds to given grain (Daily, Monthly). Suppose the API call is for usageDate > 2024-08-01 and usageDate < 2022-10-31 at a daily granularity. There will be one record per benefit id for each day. For a single day, the maxUtilizationPercentage value will be equal to the largest in the set of values where the set contains 24 utilization percentage entries one for each hour in a specific day. If on the day 2022-10-18, the largest utilization percentage was 90% at hour 5, then the value for the maxUtilizationPercentage in the response will be 90%.", "type": "number", "format": "decimal", "readOnly": true } } }, "BenefitUtilizationSummariesOperationStatus": { "type": "object", "description": "Status of a benefit utilization summaries report. Provides Async Benefit Utilization Summaries Request input, status, and report sas url.", "properties": { "input": { "$ref": "#/definitions/BenefitUtilizationSummariesRequest", "description": "Input given to create the benefit utilization summaries report." }, "status": { "description": "The status of the creation of the benefit utilization summaries report.", "$ref": "#/definitions/AsyncOperationStatusEnum" }, "properties": { "description": "Contains sas url to the async benefit utilization summaries report and a date that the url is valid until. These values will be empty if the report is in a Running or Failed state", "$ref": "#/definitions/AsyncOperationStatusProperties" } } }, "AsyncOperationStatusEnum": { "description": "Enum representing the status of an async operation.", "type": "string", "enum": [ "Running", "Complete", "Failed" ], "x-ms-enum": { "name": "OperationStatusType", "modelAsString": true } }, "AsyncOperationStatusProperties": { "description": "Object representing the report url and valid until date of the async report generated.", "type": "object", "properties": { "reportUrl": { "description": "Sas url to the async benefit utilization summaries report. Will be empty if the report is in Running or Failed state.", "$ref": "#/definitions/BenefitUtilizationSummaryReportSchema", "x-ms-secret": true }, "secondaryReportUrl": { "description": "Sas url to async benefit utilization summaries report in secondary storage in case of primary outage. Will be empty if the report is in Running or Failed state.", "$ref": "#/definitions/BenefitUtilizationSummaryReportSchema", "x-ms-secret": true }, "validUntil": { "description": "The date that the sas url provided in reportUrl expires.", "type": "string", "format": "date-time" } } }, "BenefitUtilizationSummaryReportSchema": { "description": "The CSV file from the reportUrl and secondaryReportUrl blob link will consist of the following columns of benefit utilization data. UtilizedPercentage will be 0 for savings plans reports and non data bricks reservations. Utilization percentages will be 0 for data bricks reservations.", "type": "string", "enum": [ "Kind", "AvgUtilizationPercentage", "BenefitOrderId", "BenefitId", "BenefitType", "MaxUtilizationPercentage", "MinUtilizationPercentage", "UsageDate", "UtilizedPercentage" ], "x-ms-enum": { "name": "BenefitUtilizationSummaryReportSchema", "modelAsString": true } }, "BenefitUtilizationSummariesRequest": { "description": "Properties of an async benefit utilization summaries request.", "type": "object", "required": [ "startDate", "endDate", "grain" ], "properties": { "billingAccountId": { "description": "Billing account the benefit utilization summaries report is for. Required for billing account and billing profile scopes. Not supported for any benefit scopes.", "type": "string" }, "billingProfileId": { "description": "Billing profile id the benefit utilization summaries report is for. Required for billing profile scope. Not supported for billing account or any benefit scopes.", "type": "string" }, "benefitOrderId": { "description": "Benefit order id the benefit utilization summaries report is for. Required for benefit order and benefit id scopes. Not supported for any billing scopes.", "type": "string" }, "benefitId": { "description": "Benefit id the benefit utilization summaries report is for. Required for benefit id scope. Not supported for benefit order or any billing scopes.", "type": "string" }, "grain": { "description": "The grain the summaries data is served at in the report. Accepted values are 'Daily' or 'Monthly'.", "$ref": "#/definitions/Grain" }, "startDate": { "description": "The start date of the summaries data that will be served in the report.", "type": "string", "format": "date-time" }, "endDate": { "description": "The end date of the summaries data that will be served in the report.", "type": "string", "format": "date-time" }, "kind": { "description": "The type of benefit data requested. Required for billing account and billing profile scopes. Implied and not to be passed at benefit scopes. Supported values are Reservation and SavingsPlan", "$ref": "#/definitions/BenefitKind" } } } }, "parameters": { "benefitAsyncOperationIdParameter": { "description": "Operation id of the report being generated", "in": "path", "name": "operationId", "required": true, "type": "string", "x-ms-parameter-location": "method" }, "benefitRecommendationsFilterParameter": { "name": "$filter", "in": "query", "description": "Can be used to filter benefitRecommendations by: properties/scope with allowed values ['Single', 'Shared'] and default value 'Shared'; and properties/lookBackPeriod with allowed values ['Last7Days', 'Last30Days', 'Last60Days'] and default value 'Last60Days'; properties/term with allowed values ['P1Y', 'P3Y'] and default value 'P3Y'; properties/subscriptionId; properties/resourceGroup", "type": "string", "x-ms-parameter-location": "method" }, "billingScopeBenefitRecommendationParameter": { "name": "billingScope", "in": "path", "description": "The scope associated with benefit recommendation operations. This includes '/subscriptions/{subscriptionId}/' for subscription scope, '/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}' for resource group scope, /providers/Microsoft.Billing/billingAccounts/{billingAccountId}' for enterprise agreement scope, and '/providers/Microsoft.Billing/billingAccounts/{billingAccountId}/billingProfiles/{billingProfileId}' for billing profile scope", "required": true, "type": "string", "x-ms-parameter-location": "method", "x-ms-skip-url-encoding": true }, "grainParameter": { "description": "Grain.", "in": "query", "required": false, "x-ms-parameter-location": "method", "type": "string", "name": "grainParameter", "enum": [ "Hourly", "Daily", "Monthly" ], "x-ms-enum": { "name": "grainParameter", "modelAsString": true, "values": [ { "value": "Hourly", "description": "Hourly grain corresponds to value per hour.", "name": "Hourly" }, { "value": "Daily", "description": "Hourly grain corresponds to value per day.", "name": "Daily" }, { "value": "Monthly", "description": "Hourly grain corresponds to value per month.", "name": "Monthly" } ] } }, "reservationIdParameter": { "description": "Reservation ID", "in": "path", "name": "reservationId", "required": true, "type": "string", "x-ms-parameter-location": "method" }, "reservationOrderIdParameter": { "description": "Reservation Order ID", "in": "path", "name": "reservationOrderId", "required": true, "type": "string", "x-ms-parameter-location": "method" }, "savingsPlanIdParameter": { "description": "Savings plan ID.", "in": "path", "name": "savingsPlanId", "required": true, "type": "string", "x-ms-parameter-location": "method" }, "savingsPlanOrderIdParameter": { "description": "Savings plan order ID.", "in": "path", "name": "savingsPlanOrderId", "required": true, "type": "string", "x-ms-parameter-location": "method" } } }