Benefit Recommendations - List

服務:

Cost Management

API 版本:

2025-03-01

購買節省方案的建議清單。

GET https://management.azure.com/{billingScope}/providers/Microsoft.CostManagement/benefitRecommendations?api-version=2025-03-01

含選擇性參數:

GET https://management.azure.com/{billingScope}/providers/Microsoft.CostManagement/benefitRecommendations?api-version=2025-03-01&$filter={$filter}&$orderby={$orderby}&$expand={$expand}

URI 參數

名稱	位於	必要	類型	Description
billingScope	path	True	string	與權益建議作業相關聯的範圍。 這包括訂用帳戶範圍的 '/subscriptions/{subscriptionId}/' 、資源群組範圍的 '/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}'、/providers/Microsoft.Billing/billingAccounts/{billingAccountId}'，以及計費配置文件範圍的 '/providers/Microsoft.Billing/billingAccounts/{billingAccountId}/billingProfiles/{billingProfileId}'
api-version	query	True	string minLength: 1	要用於這項作業的 API 版本。
$expand	query		string	可用來依下列方式展開屬性：properties/usage、properties/allRecommendationDetails
$filter	query		string	可用來依下列方式篩選 benefitRecommendations：具有允許值的屬性/範圍 ['Single'、'Shared'] 和預設值 'Shared';和 properties/lookBackPeriod，允許的值 ['Last7Days'， 'Last30Days'， 'Last60Days'] 和預設值 'Last60Days';屬性/字詞，允許的值 ['P1Y'， 'P3Y'] 和預設值 'P3Y';properties/subscriptionId;properties/resourceGroup
$orderby	query		string	可用來依下列方式排序建議：properties/armSkuName。 針對節省方案，結果預設會依序排列。 不需要使用這個子句。

回應

名稱	類型	Description
200 OK	benefitRecommendationsListResult	Azure 作業已順利完成。
Other Status Codes	ErrorResponse	未預期的錯誤回應。

安全性

azure_auth

Azure Active Directory OAuth2 Flow。

類型: oauth2
Flow: implicit
授權 URL: https://login.microsoftonline.com/common/oauth2/authorize

範圍

名稱	Description
user_impersonation	模擬您的用戶帳戶

範例

BenefitRecommendationsBillingAccountList

範例要求

HTTP

GET https://management.azure.com/providers/Microsoft.Billing/billingAccounts/123456/providers/Microsoft.CostManagement/benefitRecommendations?api-version=2025-03-01&$filter=properties/lookBackPeriod eq 'Last7Days' AND properties/term eq 'P1Y'&$expand=properties/usage,properties/allRecommendationDetails

Python

from azure.identity import DefaultAzureCredential

from azure.mgmt.costmanagement import CostManagementClient

"""
# PREREQUISITES
    pip install azure-identity
    pip install azure-mgmt-costmanagement
# USAGE
    python benefit_recommendations_by_billing_account.py

    Before run the sample, please set the values of the client ID, tenant ID and client secret
    of the AAD application as environment variables: AZURE_CLIENT_ID, AZURE_TENANT_ID,
    AZURE_CLIENT_SECRET. For more info about how to get the value, please see:
    https://docs.microsoft.com/azure/active-directory/develop/howto-create-service-principal-portal
"""


def main():
    client = CostManagementClient(
        credential=DefaultAzureCredential(),
    )

    response = client.benefit_recommendations.list(
        billing_scope="providers/Microsoft.Billing/billingAccounts/123456",
    )
    for item in response:
        print(item)


# x-ms-original-file: 2025-03-01/BenefitRecommendationsByBillingAccount.json
if __name__ == "__main__":
    main()

To use the Azure SDK library in your project, see this documentation. To provide feedback on this code sample, open a GitHub issue

Go

package armcostmanagement_test

import (
	"context"
	"log"

	"github.com/Azure/azure-sdk-for-go/sdk/azcore/to"
	"github.com/Azure/azure-sdk-for-go/sdk/azidentity"
	"github.com/Azure/azure-sdk-for-go/sdk/resourcemanager/costmanagement/armcostmanagement/v3"
)

// Generated from example definition: 2025-03-01/BenefitRecommendationsByBillingAccount.json
func ExampleBenefitRecommendationsClient_NewListPager() {
	cred, err := azidentity.NewDefaultAzureCredential(nil)
	if err != nil {
		log.Fatalf("failed to obtain a credential: %v", err)
	}
	ctx := context.Background()
	clientFactory, err := armcostmanagement.NewClientFactory(cred, nil)
	if err != nil {
		log.Fatalf("failed to create client: %v", err)
	}
	pager := clientFactory.NewBenefitRecommendationsClient().NewListPager("providers/Microsoft.Billing/billingAccounts/123456", &armcostmanagement.BenefitRecommendationsClientListOptions{
		Expand: to.Ptr("properties/usage,properties/allRecommendationDetails"),
		Filter: to.Ptr("properties/lookBackPeriod eq 'Last7Days' AND properties/term eq 'P1Y'")})
	for pager.More() {
		page, err := pager.NextPage(ctx)
		if err != nil {
			log.Fatalf("failed to advance page: %v", err)
		}
		for _, v := range page.Value {
			// You could use page here. We use blank identifier for just demo purposes.
			_ = v
		}
		// If the HTTP response code is 200 as defined in example definition, your page structure would look as follows. Please pay attention that all the values in the output are fake values for just demo purposes.
		// page = armcostmanagement.BenefitRecommendationsClientListResponse{
		// 	BenefitRecommendationsListResult: armcostmanagement.BenefitRecommendationsListResult{
		// 		Value: []*armcostmanagement.BenefitRecommendationModel{
		// 			{
		// 				Name: to.Ptr("00000000-0000-0000-0000-000000000000"),
		// 				Type: to.Ptr("Microsoft.CostManagement/benefitRecommendations"),
		// 				ID: to.Ptr("/providers/Microsoft.Billing/billingAccounts/123456/providers/Microsoft.CostManagement/benefitRecommendations/00000000-0000-0000-0000-000000000000"),
		// 				Kind: to.Ptr(armcostmanagement.BenefitKindSavingsPlan),
		// 				Properties: &armcostmanagement.SharedScopeBenefitRecommendationProperties{
		// 					AllRecommendationDetails: &armcostmanagement.AllSavingsList{
		// 						Value: []*armcostmanagement.AllSavingsBenefitDetails{
		// 							{
		// 							},
		// 							{
		// 							},
		// 						},
		// 					},
		// 					ArmSKUName: to.Ptr("Compute_Savings_Plan"),
		// 					CommitmentGranularity: to.Ptr(armcostmanagement.GrainHourly),
		// 					CurrencyCode: to.Ptr("USD"),
		// 					FirstConsumptionDate: to.Ptr(func() time.Time { t, _ := time.Parse(time.RFC3339Nano, "2022-10-18T00:00:00Z"); return t}()),
		// 					LastConsumptionDate: to.Ptr(func() time.Time { t, _ := time.Parse(time.RFC3339Nano, "2022-10-25T00:00:00Z"); return t}()),
		// 					LookBackPeriod: to.Ptr(armcostmanagement.LookBackPeriodLast7Days),
		// 					RecommendationDetails: &armcostmanagement.AllSavingsBenefitDetails{
		// 					},
		// 					Scope: to.Ptr(armcostmanagement.ScopeShared),
		// 					Term: to.Ptr(armcostmanagement.TermP1Y),
		// 					TotalHours: to.Ptr[int32](168),
		// 					Usage: &armcostmanagement.RecommendationUsageDetails{
		// 						Charges: []*float64{
		// 						},
		// 						UsageGrain: to.Ptr(armcostmanagement.GrainHourly),
		// 					},
		// 				},
		// 			},
		// 		},
		// 	},
		// }
	}
}

To use the Azure SDK library in your project, see this documentation. To provide feedback on this code sample, open a GitHub issue

JavaScript

const { CostManagementClient } = require("@azure/arm-costmanagement");
const { DefaultAzureCredential } = require("@azure/identity");

/**
 * This sample demonstrates how to list of recommendations for purchasing savings plan.
 *
 * @summary list of recommendations for purchasing savings plan.
 * x-ms-original-file: 2025-03-01/BenefitRecommendationsByBillingAccount.json
 */
async function benefitRecommendationsBillingAccountList() {
  const credential = new DefaultAzureCredential();
  const client = new CostManagementClient(credential);
  const resArray = new Array();
  for await (const item of client.benefitRecommendations.list(
    "providers/Microsoft.Billing/billingAccounts/123456",
    {
      filter: "properties/lookBackPeriod eq 'Last7Days' AND properties/term eq 'P1Y'",
      expand: "properties/usage,properties/allRecommendationDetails",
    },
  )) {
    resArray.push(item);
  }

  console.log(resArray);
}

To use the Azure SDK library in your project, see this documentation. To provide feedback on this code sample, open a GitHub issue

範例回覆

狀態碼:

200

{
  "value": [
    {
      "name": "00000000-0000-0000-0000-000000000000",
      "type": "Microsoft.CostManagement/benefitRecommendations",
      "id": "/providers/Microsoft.Billing/billingAccounts/123456/providers/Microsoft.CostManagement/benefitRecommendations/00000000-0000-0000-0000-000000000000",
      "kind": "SavingsPlan",
      "properties": {
        "allRecommendationDetails": {
          "value": [
            {
              "averageUtilizationPercentage": 99.33,
              "benefitCost": 52.002,
              "commitmentAmount": 0.164,
              "coveragePercentage": 54.609,
              "overageCost": 144.841,
              "savingsAmount": 21.424,
              "savingsPercentage": 9.815,
              "totalCost": 196.843,
              "wastageCost": 0.035
            },
            {
              "averageUtilizationPercentage": 81.474,
              "benefitCost": 83.754,
              "commitmentAmount": 0.161,
              "coveragePercentage": 56.748,
              "overageCost": 120.389,
              "savingsAmount": 14.124,
              "savingsPercentage": 6.47,
              "totalCost": 204.143,
              "wastageCost": 0.1
            }
          ]
        },
        "armSkuName": "Compute_Savings_Plan",
        "commitmentGranularity": "Hourly",
        "costWithoutBenefit": 218.267,
        "currencyCode": "USD",
        "firstConsumptionDate": "2022-10-18T00:00:00Z",
        "lastConsumptionDate": "2022-10-25T00:00:00Z",
        "lookBackPeriod": "Last7Days",
        "recommendationDetails": {
          "averageUtilizationPercentage": 99.33,
          "benefitCost": 52.002,
          "commitmentAmount": 0.164,
          "coveragePercentage": 54.609,
          "overageCost": 144.841,
          "savingsAmount": 21.424,
          "savingsPercentage": 9.815,
          "totalCost": 196.843,
          "wastageCost": 0.035
        },
        "scope": "Shared",
        "term": "P1Y",
        "totalHours": 168,
        "usage": {
          "charges": [
            1,
            1,
            0,
            1,
            1,
            1,
            1,
            1,
            1,
            1,
            1,
            1,
            1,
            1,
            1,
            1,
            1,
            1,
            1,
            1,
            1,
            1,
            1,
            1,
            1,
            1,
            1,
            1,
            1,
            1,
            1,
            1,
            1,
            1,
            1,
            1,
            1,
            1,
            1,
            1,
            1,
            1,
            2,
            2,
            2,
            2
          ],
          "usageGrain": "Hourly"
        }
      }
    }
  ]
}

定義

名稱	Description
allSavingsBenefitDetails	權益建議詳細數據。
allSavingsList	包含建議詳細數據的所有權益建議清單。
BenefitKind	福利的種類和類型。
benefitRecommendationModel	權益方案建議詳細數據。
benefitRecommendationsListResult	列出權益建議的結果。
createdByType	建立資源的身分識別類型。
ErrorDetails	錯誤的詳細數據。
ErrorResponse	錯誤回應表示服務無法處理傳入要求。 錯誤訊息中會提供原因。 \n\n一些錯誤回應：\n\n * 429 TooManyRequests - 請求被限速。 等候 「x-ms-ratelimit-microsoft.consumption-retry-after」 標頭中指定的時間後重試。 \n\n * 503 服務不可用 - 服務暫時無法使用。 等候 「Retry-After」 標頭中指定的時間後重試。
Grain	穀物，對應於價值。
LookBackPeriod	過去回頭看的天數。
recommendationUsageDetails	firstConsumptionDate 與 lastConsumptionDate 之間的隨選費用，用於計算權益建議。
Scope	這算是推薦範圍。
sharedScopeBenefitRecommendationProperties	當範圍為 「共用」時，權益建議的屬性。
singleScopeBenefitRecommendationProperties	當範圍為 『Single』 時，權益建議的屬性。
systemData	與建立和上次修改資源相關的元數據。
Term	穀物，對應於價值。

allSavingsBenefitDetails

Object

權益建議詳細數據。

名稱	類型	Description
averageUtilizationPercentage	number (decimal)	回首期間 'totalHours' 的估計平均使用率百分比，並具有此承諾。
benefitCost	number (decimal)	回首期間“totalHours”的估計成本。 它等於 （commitmentAmount * totalHours）
commitmentAmount	number (decimal)	承諾用量金額。
coveragePercentage	number (decimal)	在回顧期間內，“totalHours”的估計權益涵蓋百分比，並具有此承諾。
overageCost	number (decimal)	回首期間『totalHours』的總成本和權益成本之間的差異。
savingsAmount	number (decimal)	在回首期間，購買建議的權益數量，以節省 「totalHours」金額。
savingsPercentage	number (decimal)	在回首期間，購買建議的權益數量，以 「totalHours」 的百分比節省。
totalCost	number (decimal)	總成本，這是權益成本和超額成本的總和。
wastageCost	number (decimal)	'benefitCost' 的估計未使用部分。

allSavingsList

Object

包含建議詳細數據的所有權益建議清單。

名稱	類型	Description
nextLink	string (uri)	結果下一頁的連結（URL）。
value	allSavingsBenefitDetails[]	具有建議詳細數據的權益建議清單。

BenefitKind

列舉型別

福利的種類和類型。

值	Description
IncludedQuantity	權益為 IncludedQuantity。
Reservation	權益是保留。
SavingsPlan	權益是 SavingsPlan。

benefitRecommendationModel

Object

權益方案建議詳細數據。

名稱	類型	Description
id	string (arm-id)	資源的完整資源標識碼。 例如 “/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/{resourceProviderNamespace}/{resourceType}/{resourceName}”
kind	BenefitKind	Reservation 或 SavingsPlan。
name	string	資源的名稱
properties	benefitRecommendationProperties: sharedScopeBenefitRecommendationProperties singleScopeBenefitRecommendationProperties	權益建議的屬性。
systemData	systemData	包含 createdBy 和 modifiedBy 資訊的 Azure Resource Manager 元數據。
type	string	資源的類型。 例如“Microsoft.Compute/virtualMachines” 或 “Microsoft.Storage/storageAccounts”

benefitRecommendationsListResult

Object

列出權益建議的結果。

名稱	類型	Description
nextLink	string	結果下一頁的連結（url）。
value	benefitRecommendationModel[]	權益建議的清單。

createdByType

列舉型別

建立資源的身分識別類型。

值	Description
User
Application
ManagedIdentity
Key

ErrorDetails

Object

錯誤的詳細數據。

名稱	類型	Description
code	string	錯誤碼。
message	string	錯誤訊息，指出作業失敗的原因。

ErrorResponse

Object

錯誤回應表示服務無法處理傳入要求。 錯誤訊息中會提供原因。 \n\n一些錯誤回應：\n\n * 429 TooManyRequests - 請求被限速。 等候 「x-ms-ratelimit-microsoft.consumption-retry-after」 標頭中指定的時間後重試。 \n\n * 503 服務不可用 - 服務暫時無法使用。 等候 「Retry-After」 標頭中指定的時間後重試。

名稱	類型	Description
error	ErrorDetails	錯誤的詳細數據。

Grain

列舉型別

穀物，對應於價值。

值	Description
Hourly	每小時粒紋對應至每小時的值。
Daily	每小時粒紋會對應到每天的值。
Monthly	每小時粒紋會對應至每個月的值。

LookBackPeriod

列舉型別

過去回頭看的天數。

值	Description
Last7Days	7 天過去回頭。
Last30Days	30 天過去回頭。
Last60Days	60 天過去回頭。

recommendationUsageDetails

Object

firstConsumptionDate 與 lastConsumptionDate 之間的隨選費用，用於計算權益建議。

名稱	類型	Description
charges	number[] (decimal)	firstConsumptionDate 與 lastConsumptionDate 之間每小時的隨選費用，用於計算權益建議。
usageGrain	Grain	使用量的粒紋。 支援的值：'Hourly'

Scope

列舉型別

這算是推薦範圍。

值	Description
Single	單一範圍建議。
Shared	共享範圍建議。

sharedScopeBenefitRecommendationProperties

Object

當範圍為 「共用」時，權益建議的屬性。

名稱	類型	Description
allRecommendationDetails	allSavingsList	包含建議詳細數據的所有權益建議清單。
armSkuName	string	ARM SKU 名稱。 SavingsPlan 的 'Compute_Savings_Plan'。
commitmentGranularity	Grain	建議承諾用量的粒紋。 支援的值：'Hourly'
costWithoutBenefit	number (decimal)	目前沒有權益的成本，對應於回首期間內的「totalHours」。
currencyCode	string	成本與節省金額的 ISO 4217 貨幣代碼識別碼。
firstConsumptionDate	string (date-time)	用來回頭查看建議的第一個使用日期。
lastConsumptionDate	string (date-time)	用來回頭查看建議的最後一個使用日期。
lookBackPeriod	LookBackPeriod	評估用於計算建議的使用量天數。
recommendationDetails	allSavingsBenefitDetails	建議的詳細數據。
scope	string: Shared	權益範圍。 例如，Single 或 Shared。
term	Term	權益的期限。 例如，P1Y 或 P3Y。
totalHours	integer (int32)	費用涵蓋的總時數。 其等於屬性 『properties/usage/charges』 中的記錄數目。
usage	recommendationUsageDetails	firstConsumptionDate 與 lastConsumptionDate 之間的隨選費用，用於計算權益建議。

singleScopeBenefitRecommendationProperties

Object

當範圍為 『Single』 時，權益建議的屬性。

名稱	類型	Description
allRecommendationDetails	allSavingsList	包含建議詳細數據的所有權益建議清單。
armSkuName	string	ARM SKU 名稱。 SavingsPlan 的 'Compute_Savings_Plan'。
commitmentGranularity	Grain	建議承諾用量的粒紋。 支援的值：'Hourly'
costWithoutBenefit	number (decimal)	目前沒有權益的成本，對應於回首期間內的「totalHours」。
currencyCode	string	成本與節省金額的 ISO 4217 貨幣代碼識別碼。
firstConsumptionDate	string (date-time)	用來回頭查看建議的第一個使用日期。
lastConsumptionDate	string (date-time)	用來回頭查看建議的最後一個使用日期。
lookBackPeriod	LookBackPeriod	評估用於計算建議的使用量天數。
recommendationDetails	allSavingsBenefitDetails	建議的詳細數據。
resourceGroup	string	此單一範圍建議的資源群組。 只有在建議適用於 『Single』 範圍和 『ResourceGroup』 要求範圍時才適用。
scope	string: Single	權益範圍。 例如，Single 或 Shared。
subscriptionId	string	此單一範圍建議的訂用帳戶標識碼。 只有在建議適用於「單一」範圍時，才適用。
term	Term	權益的期限。 例如，P1Y 或 P3Y。
totalHours	integer (int32)	費用涵蓋的總時數。 其等於屬性 『properties/usage/charges』 中的記錄數目。
usage	recommendationUsageDetails	firstConsumptionDate 與 lastConsumptionDate 之間的隨選費用，用於計算權益建議。

systemData

Object

與建立和上次修改資源相關的元數據。

名稱	類型	Description
createdAt	string (date-time)	資源建立的時間戳（UTC）。
createdBy	string	建立資源的身分識別。
createdByType	createdByType	建立資源的身分識別類型。
lastModifiedAt	string (date-time)	資源上次修改的時間戳記 （UTC）
lastModifiedBy	string	上次修改資源的身分識別。
lastModifiedByType	createdByType	上次修改資源的身分識別類型。

Term

列舉型別

穀物，對應於價值。

值	Description
P1Y	福利期限為 1 年。
P3Y	福利期限為 3 年。