Budgets - Create Or Update

Reference

Service:: Consumption

API Version:: 2024-08-01

The operation to create or update a budget. You can optionally provide an eTag if desired as a form of concurrency control. To obtain the latest eTag for a given budget, perform a get operation prior to your put operation.

PUT https://management.azure.com/{scope}/providers/Microsoft.Consumption/budgets/{budgetName}?api-version=2024-08-01

URI Parameters

Name	In	Required	Type	Description
budgetName	path	True	string	Budget Name.
scope	path	True	string	The scope associated with budget operations. This includes '/subscriptions/{subscriptionId}/' for subscription scope, '/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}' for resourceGroup scope, '/providers/Microsoft.Billing/billingAccounts/{billingAccountId}' for Billing Account scope, '/providers/Microsoft.Billing/billingAccounts/{billingAccountId}/departments/{departmentId}' for Department scope, '/providers/Microsoft.Billing/billingAccounts/{billingAccountId}/enrollmentAccounts/{enrollmentAccountId}' for EnrollmentAccount scope, '/providers/Microsoft.Management/managementGroups/{managementGroupId}' for Management Group scope, '/providers/Microsoft.Billing/billingAccounts/{billingAccountId}/billingProfiles/{billingProfileId}' for billingProfile scope, '/providers/Microsoft.Billing/billingAccounts/{billingAccountId}/invoiceSections/{invoiceSectionId}' for invoiceSection scope.
api-version	query	True	string	Version of the API to be used with the client request. The current version is 2023-03-01.

Request Body

Name	Required	Type	Description
properties.amount	True	number	The total amount of cost to track with the budget
properties.category	True	CategoryType	The category of the budget, whether the budget tracks cost or usage.
properties.timeGrain	True	TimeGrainType	The time covered by a budget. Tracking of the amount will be reset based on the time grain. BillingMonth, BillingQuarter, and BillingAnnual are only supported by WD customers
properties.timePeriod	True	BudgetTimePeriod	Has start and end date of the budget. The start date must be first of the month and should be less than the end date. Budget start date must be on or after June 1, 2017. Future start date should not be more than twelve months. Past start date should be selected within the timegrain period. There are no restrictions on the end date.
eTag		string	eTag of the resource. To handle concurrent update scenario, this field will be used to determine whether the user is updating the latest version or not.
properties.filter		BudgetFilter	May be used to filter budgets by user-specified dimensions and/or tags.
properties.notifications		<string, Notification>	Dictionary of notifications associated with the budget. Budget can have up to five notifications.

Responses

Name	Type	Description
200 OK	Budget	OK. The request has succeeded.
201 Created	Budget	Created.
Other Status Codes	ErrorResponse	Error response describing why the operation failed.

Security

azure_auth

Azure Active Directory OAuth2 Flow.

Type: oauth2
Flow: implicit
Authorization URL: https://login.microsoftonline.com/common/oauth2/authorize

Scopes

Name	Description
user_impersonation	impersonate your user account

Examples

CreateOrUpdateBudget

Sample request

HTTP

PUT https://management.azure.com/subscriptions/00000000-0000-0000-0000-000000000000/providers/Microsoft.Consumption/budgets/TestBudget?api-version=2024-08-01

{
  "eTag": "\"1d34d016a593709\"",
  "properties": {
    "category": "Cost",
    "amount": 100.65,
    "timeGrain": "Monthly",
    "timePeriod": {
      "startDate": "2017-10-01T00:00:00Z",
      "endDate": "2018-10-31T00:00:00Z"
    },
    "filter": {
      "and": [
        {
          "dimensions": {
            "name": "ResourceId",
            "operator": "In",
            "values": [
              "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/MYDEVTESTRG/providers/Microsoft.Compute/virtualMachines/MSVM2",
              "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/MYDEVTESTRG/providers/Microsoft.Compute/virtualMachines/platformcloudplatformGeneric1"
            ]
          }
        },
        {
          "tags": {
            "name": "category",
            "operator": "In",
            "values": [
              "Dev",
              "Prod"
            ]
          }
        },
        {
          "tags": {
            "name": "department",
            "operator": "In",
            "values": [
              "engineering",
              "sales"
            ]
          }
        }
      ]
    },
    "notifications": {
      "Actual_GreaterThan_80_Percent": {
        "enabled": true,
        "operator": "GreaterThan",
        "threshold": 80,
        "locale": "en-us",
        "contactEmails": [
          "johndoe@contoso.com",
          "janesmith@contoso.com"
        ],
        "contactRoles": [
          "Contributor",
          "Reader"
        ],
        "contactGroups": [
          "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/MYDEVTESTRG/providers/microsoft.insights/actionGroups/SampleActionGroup"
        ],
        "thresholdType": "Actual"
      }
    }
  }
}

Sample response

Status code:: 201

{
  "id": "subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/MYDEVTESTRG/providers/Microsoft.Consumption/budgets/TestBudget",
  "name": "TestBudget",
  "type": "Microsoft.Consumption/budgets",
  "eTag": "\"1d34d012214157f\"",
  "properties": {
    "category": "Cost",
    "amount": 100.65,
    "timeGrain": "Monthly",
    "timePeriod": {
      "startDate": "2017-10-01T00:00:00Z",
      "endDate": "2018-10-31T00:00:00Z"
    },
    "filter": {
      "and": [
        {
          "dimensions": {
            "name": "ResourceId",
            "operator": "In",
            "values": [
              "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/MYDEVTESTRG/providers/Microsoft.Compute/virtualMachines/MSVM2",
              "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/MYDEVTESTRG/providers/Microsoft.Compute/virtualMachines/platformcloudplatformGeneric1"
            ]
          }
        },
        {
          "tags": {
            "name": "category",
            "operator": "In",
            "values": [
              "Dev",
              "Prod"
            ]
          }
        },
        {
          "tags": {
            "name": "department",
            "operator": "In",
            "values": [
              "engineering",
              "sales"
            ]
          }
        }
      ]
    },
    "currentSpend": {
      "amount": 80.89,
      "unit": "USD"
    },
    "notifications": {
      "Actual_GreaterThan_80_Percent": {
        "enabled": true,
        "operator": "GreaterThan",
        "threshold": 80,
        "locale": "en-us",
        "contactEmails": [
          "johndoe@contoso.com",
          "janesmith@contoso.com"
        ],
        "contactRoles": [
          "Contributor",
          "Reader"
        ],
        "contactGroups": [
          "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/MYDEVTESTRG/providers/microsoft.insights/actionGroups/SampleActionGroup"
        ],
        "thresholdType": "Actual"
      }
    }
  }
}

Status code:: 200

{
  "id": "subscriptions/00000000-0000-0000-0000-000000000000/providers/Microsoft.Consumption/budgets/TestBudget",
  "name": "TestBudget",
  "type": "Microsoft.Consumption/budgets",
  "eTag": "\"1d34d012214157f\"",
  "properties": {
    "category": "Cost",
    "amount": 100.65,
    "timeGrain": "Monthly",
    "timePeriod": {
      "startDate": "2017-10-01T00:00:00Z",
      "endDate": "2018-10-31T00:00:00Z"
    },
    "filter": {
      "and": [
        {
          "dimensions": {
            "name": "ResourceId",
            "operator": "In",
            "values": [
              "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/MYDEVTESTRG/providers/Microsoft.Compute/virtualMachines/MSVM2",
              "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/MYDEVTESTRG/providers/Microsoft.Compute/virtualMachines/platformcloudplatformGeneric1"
            ]
          }
        },
        {
          "tags": {
            "name": "category",
            "operator": "In",
            "values": [
              "Dev",
              "Prod"
            ]
          }
        },
        {
          "tags": {
            "name": "department",
            "operator": "In",
            "values": [
              "engineering",
              "sales"
            ]
          }
        }
      ]
    },
    "currentSpend": {
      "amount": 80.89,
      "unit": "USD"
    },
    "notifications": {
      "Actual_GreaterThan_80_Percent": {
        "enabled": true,
        "operator": "GreaterThan",
        "threshold": 80,
        "locale": "en-us",
        "contactEmails": [
          "johndoe@contoso.com",
          "janesmith@contoso.com"
        ],
        "contactRoles": [
          "Contributor",
          "Reader"
        ],
        "contactGroups": [
          "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/MYDEVTESTRG/providers/microsoft.insights/actionGroups/SampleActionGroup"
        ],
        "thresholdType": "Actual"
      }
    }
  }
}

Definitions

Name	Description
Budget	A budget resource.
BudgetComparisonExpression	The comparison expression to be used in the budgets.
BudgetFilter	May be used to filter budgets by resource group, resource, or meter.
BudgetFilterProperties	The Dimensions or Tags to filter a budget by.
BudgetOperatorType	The operator to use for comparison.
BudgetTimePeriod	The start and end date for a budget.
CategoryType	The category of the budget, whether the budget tracks cost or usage.
CultureCode	Language in which the recipient will receive the notification
CurrentSpend	The current amount of cost which is being tracked for a budget.
ErrorDetails	The details of the error.
ErrorResponse	Error response indicates that the service is not able to process the incoming request. The reason is provided in the error message. Some Error responses: 429 TooManyRequests - Request is throttled. Retry after waiting for the time specified in the "x-ms-ratelimit-microsoft.consumption-retry-after" header. 503 ServiceUnavailable - Service is temporarily unavailable. Retry after waiting for the time specified in the "Retry-After" header. 504 Gateway Timeout - Service timed out while processing the request. Reduce the date range in the request, if possible.
ForecastSpend	The forecasted cost which is being tracked for a budget.
Notification	The notification associated with a budget.
OperatorType	The comparison operator.
ThresholdType	The type of threshold
TimeGrainType	The time covered by a budget. Tracking of the amount will be reset based on the time grain. BillingMonth, BillingQuarter, and BillingAnnual are only supported by WD customers

Budget

A budget resource.

Name	Type	Description
eTag	string	eTag of the resource. To handle concurrent update scenario, this field will be used to determine whether the user is updating the latest version or not.
id	string	Resource Id.
name	string	Resource name.
properties.amount	number	The total amount of cost to track with the budget
properties.category	CategoryType	The category of the budget, whether the budget tracks cost or usage.
properties.currentSpend	CurrentSpend	The current amount of cost which is being tracked for a budget.
properties.filter	BudgetFilter	May be used to filter budgets by user-specified dimensions and/or tags.
properties.forecastSpend	ForecastSpend	The forecasted cost which is being tracked for a budget.
properties.notifications	<string, Notification>	Dictionary of notifications associated with the budget. Budget can have up to five notifications.
properties.timeGrain	TimeGrainType	The time covered by a budget. Tracking of the amount will be reset based on the time grain. BillingMonth, BillingQuarter, and BillingAnnual are only supported by WD customers
properties.timePeriod	BudgetTimePeriod	Has start and end date of the budget. The start date must be first of the month and should be less than the end date. Budget start date must be on or after June 1, 2017. Future start date should not be more than twelve months. Past start date should be selected within the timegrain period. There are no restrictions on the end date.
type	string	Resource type.

BudgetComparisonExpression

The comparison expression to be used in the budgets.

Name	Type	Description
name	string	The name of the column to use in comparison.
operator	BudgetOperatorType	The operator to use for comparison.
values	string[]	Array of values to use for comparison

BudgetFilter

May be used to filter budgets by resource group, resource, or meter.

Name	Type	Description
and	BudgetFilterProperties[]	The logical "AND" expression. Must have at least 2 items.
dimensions	BudgetComparisonExpression	Has comparison expression for a dimension
tags	BudgetComparisonExpression	Has comparison expression for a tag

BudgetFilterProperties

The Dimensions or Tags to filter a budget by.

Name	Type	Description
dimensions	BudgetComparisonExpression	Has comparison expression for a dimension
tags	BudgetComparisonExpression	Has comparison expression for a tag

BudgetOperatorType

The operator to use for comparison.

Name	Type	Description
In	string

BudgetTimePeriod

The start and end date for a budget.

Name	Type	Description
endDate	string	The end date for the budget. If not provided, we default this to 10 years from the start date.
startDate	string	The start date for the budget.

CategoryType

The category of the budget, whether the budget tracks cost or usage.

Name	Type	Description
Cost	string

CultureCode

Language in which the recipient will receive the notification

Name	Type	Description
cs-cz	string
da-dk	string
de-de	string
en-gb	string
en-us	string
es-es	string
fr-fr	string
hu-hu	string
it-it	string
ja-jp	string
ko-kr	string
nb-no	string
nl-nl	string
pl-pl	string
pt-br	string
pt-pt	string
ru-ru	string
sv-se	string
tr-tr	string
zh-cn	string
zh-tw	string

CurrentSpend

The current amount of cost which is being tracked for a budget.

Name	Type	Description
amount	number	The total amount of cost which is being tracked by the budget.
unit	string	The unit of measure for the budget amount.

ErrorDetails

The details of the error.

Name	Type	Description
code	string	Error code.
message	string	Error message indicating why the operation failed.

ErrorResponse

Error response indicates that the service is not able to process the incoming request. The reason is provided in the error message.

Some Error responses:

429 TooManyRequests - Request is throttled. Retry after waiting for the time specified in the "x-ms-ratelimit-microsoft.consumption-retry-after" header.
503 ServiceUnavailable - Service is temporarily unavailable. Retry after waiting for the time specified in the "Retry-After" header.
504 Gateway Timeout - Service timed out while processing the request. Reduce the date range in the request, if possible.

Name	Type	Description
error	ErrorDetails	The details of the error.

ForecastSpend

The forecasted cost which is being tracked for a budget.

Name	Type	Description
amount	number	The forecasted cost for the total time period which is being tracked by the budget. This value is only provided if the budget contains a forecast alert type.
unit	string	The unit of measure for the budget amount.

Notification

The notification associated with a budget.

Name	Type	Default value	Description
contactEmails	string[]		Email addresses to send the budget notification to when the threshold is exceeded. Must have at least one contact email or contact group specified at the Subscription or Resource Group scopes. All other scopes must have at least one contact email specified.
contactGroups	string[]		Action groups to send the budget notification to when the threshold is exceeded. Must be provided as a fully qualified Azure resource id. Only supported at Subscription or Resource Group scopes.
contactRoles	string[]		Contact roles to send the budget notification to when the threshold is exceeded.
enabled	boolean		The notification is enabled or not.
locale	CultureCode		Language in which the recipient will receive the notification
operator	OperatorType		The comparison operator.
threshold	number		Threshold value associated with a notification. Notification is sent when the cost exceeded the threshold. It is always percent and has to be between 0 and 1000.
thresholdType	ThresholdType	Actual	The type of threshold

OperatorType

The comparison operator.

Name	Type	Description
EqualTo	string	Alert will be triggered if the evaluated cost is the same as threshold value. Note: It’s not recommended to use this OperatorType as there’s low chance of cost being exactly the same as threshold value, leading to missing of your alert. This OperatorType will be deprecated in future.
GreaterThan	string	Alert will be triggered if the evaluated cost is greater than the threshold value. Note: This is the recommended OperatorType while configuring Budget Alert.
GreaterThanOrEqualTo	string	Alert will be triggered if the evaluated cost is greater than or equal to the threshold value.

ThresholdType

The type of threshold

Name	Type	Description
Actual	string	Actual costs budget alerts notify when the actual accrued cost exceeds the allocated budget .
Forecasted	string	Forecasted costs budget alerts provide advanced notification that your spending trends are likely to exceed your allocated budget, as it relies on forecasted cost predictions.

TimeGrainType

The time covered by a budget. Tracking of the amount will be reset based on the time grain. BillingMonth, BillingQuarter, and BillingAnnual are only supported by WD customers

Name	Type	Description
Annually	string
BillingAnnual	string
BillingMonth	string
BillingQuarter	string
Monthly	string
Quarterly	string

Partilhar via