Benefit Recommendations - List

Serviço:: Cost Management

Versão da API:: 2025-03-01

Lista de recomendações para o plano de poupança de compra.

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

Com parâmetros opcionais:

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

Parâmetros de URI

Nome	Em	Obrigatório	Tipo	Description
billingScope	path	True	string	O escopo associado às operações de recomendação de benefício. Isso inclui '/subscriptions/{subscriptionId}/' para o escopo da assinatura, '/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}' para o escopo do grupo de recursos, /providers/Microsoft.Billing/billingAccounts/{billingAccountId}' para o escopo do contrato empresarial e '/providers/Microsoft.Billing/billingAccountId/{billingAccountId}/billingProfiles/{billingProfileId}' para o escopo do perfil de cobrança
api-version	query	True	string minLength: 1	A versão da API a ser usada para esta operação.
$expand	query		string	Pode ser usado para expandir as propriedades por: propriedades/uso, propriedades/allRecommendationDetails
$filter	query		string	Pode ser usado para filtrar benefitRecommendations por: propriedades/escopo com valores permitidos ['Single', 'Shared'] e valor padrão 'Shared'; e properties/lookBackPeriod com valores permitidos ['Last7Days', 'Last30Days', 'Last60Days'] e o valor padrão 'Last60Days'; properties/term with allowed values ['P1Y', 'P3Y'] and default value 'P3Y'; properties/subscriptionId; properties/resourceGroup
$orderby	query		string	Pode ser usado para ordenar as recomendações por: properties/armSkuName. Para o plano de poupança, os resultados estão em ordem por padrão. Não é necessário usar essa cláusula.

Respostas

Nome	Tipo	Description
200 OK	benefitRecommendationsListResult	A operação do Azure foi concluída com êxito.
Other Status Codes	ErrorResponse	Uma resposta de erro inesperada.

Segurança

azure_auth

Fluxo do OAuth2 do Azure Active Directory.

Tipo: oauth2
Flow: implicit
URL de Autorização: https://login.microsoftonline.com/common/oauth2/authorize

Escopos

Nome	Description
user_impersonation	representar sua conta de usuário

Exemplos

BenefitRecommendationsBillingAccountList

Solicitação de exemplo

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

Resposta de exemplo

Código de status:: 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"
        }
      }
    }
  ]
}

Definições

Nome	Description
allSavingsBenefitDetails	Detalhes da recomendação do benefício.
allSavingsList	A lista de todas as recomendações de benefício com os detalhes da recomendação.
BenefitKind	Tipo/tipo do benefício.
benefitRecommendationModel	detalhes da recomendação do plano de benefícios.
benefitRecommendationsListResult	Resultado da listagem de recomendações de benefícios.
createdByType	O tipo de identidade que criou o recurso.
ErrorDetails	Os detalhes do erro.
ErrorResponse	A resposta de erro indica que o serviço não é capaz de processar a solicitação de entrada. O motivo é fornecido na mensagem de erro. \n\nAlgumas respostas de erro: \n\n * 429 Solicitações demais - A solicitação é limitada. Tente novamente depois de aguardar o tempo especificado no cabeçalho "x-ms-ratelimit-microsoft.consumption-retry-after". \n\n * 503 ServiçoIndisponível - O serviço está temporariamente indisponível. Tente novamente depois de aguardar o tempo especificado no cabeçalho "Retry-After".
Grain	Grão que corresponde ao valor.
LookBackPeriod	O número de dias que costumava olhar para trás.
recommendationUsageDetails	Encargos sob demanda entre firstConsumptionDate e lastConsumptionDate que foram usados para recomendações de benefício de computação.
Scope	É meio que o escopo de recomendação.
sharedScopeBenefitRecommendationProperties	As propriedades da recomendação de benefício quando o escopo é 'Compartilhado'.
singleScopeBenefitRecommendationProperties	As propriedades das recomendações de benefício quando o escopo é 'Single'.
systemData	Metadados relativos à criação e última modificação do recurso.
Term	Grão que corresponde ao valor.

allSavingsBenefitDetails

Objeto

Detalhes da recomendação do benefício.

Nome	Tipo	Description
averageUtilizationPercentage	number (decimal)	Percentual de utilização média estimado para os 'totalHours' no período de pesquisa, com esse compromisso.
benefitCost	number (decimal)	O custo estimado com benefício para os 'totalHours' no período de pesquisa. É igual a (commitmentAmount * totalHours)
commitmentAmount	number (decimal)	O valor do compromisso no commitmentGranularity.
coveragePercentage	number (decimal)	Percentual estimado de cobertura de benefícios para 'totalHours' no período de pesquisa, com esse compromisso.
overageCost	number (decimal)	A diferença entre o custo total e o custo de benefício para os 'totalHours' no período de pesquisa.
savingsAmount	number (decimal)	O valor economizado para os 'totalHours' no período de pesquisa, comprando a quantidade recomendada do benefício.
savingsPercentage	number (decimal)	A economia em porcentagem para os 'totalHours' no período de pesquisa, comprando a quantidade recomendada de benefício.
totalCost	number (decimal)	Custo total, que é a soma do custo do benefício e do custo excedente.
wastageCost	number (decimal)	Parte não usada estimada do 'benefitCost'.

allSavingsList

Objeto

A lista de todas as recomendações de benefício com os detalhes da recomendação.

Nome	Tipo	Description
nextLink	string (uri)	O link (URL) para a próxima página de resultados.
value	allSavingsBenefitDetails[]	A lista de recomendações de benefícios com os detalhes da recomendação..

BenefitKind

Enumeração

Tipo/tipo do benefício.

Valor	Description
IncludedQuantity	O benefício é IncludedQuantity.
Reservation	O benefício é Reserva.
SavingsPlan	O benefício é o SavingsPlan.

benefitRecommendationModel

Objeto

detalhes da recomendação do plano de benefícios.

Nome	Tipo	Description
id	string (arm-id)	ID de recurso totalmente qualificada para o recurso. Por exemplo, "/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/{resourceProviderNamespace}/{resourceType}/{resourceName}"
kind	BenefitKind	Reserva ou SavingsPlan.
name	string	O nome do recurso
properties	benefitRecommendationProperties: sharedScopeBenefitRecommendationProperties singleScopeBenefitRecommendationProperties	As propriedades das recomendações de benefício.
systemData	systemData	Metadados do Azure Resource Manager que contêm informações createdBy e modifiedBy.
type	string	O tipo do recurso. Por exemplo, "Microsoft.Compute/virtualMachines" ou "Microsoft.Storage/storageAccounts"

benefitRecommendationsListResult

Objeto

Resultado da listagem de recomendações de benefícios.

Nome	Tipo	Description
nextLink	string	O link (url) para a próxima página de resultados.
value	benefitRecommendationModel[]	A lista de recomendações de benefícios.

createdByType

Enumeração

O tipo de identidade que criou o recurso.

Valor	Description
User
Application
ManagedIdentity
Key

ErrorDetails

Objeto

Os detalhes do erro.

Nome	Tipo	Description
code	string	Código de erro.
message	string	Mensagem de erro indicando por que a operação falhou.

ErrorResponse

Objeto

A resposta de erro indica que o serviço não é capaz de processar a solicitação de entrada. O motivo é fornecido na mensagem de erro. \n\nAlgumas respostas de erro: \n\n * 429 Solicitações demais - A solicitação é limitada. Tente novamente depois de aguardar o tempo especificado no cabeçalho "x-ms-ratelimit-microsoft.consumption-retry-after". \n\n * 503 ServiçoIndisponível - O serviço está temporariamente indisponível. Tente novamente depois de aguardar o tempo especificado no cabeçalho "Retry-After".

Nome	Tipo	Description
error	ErrorDetails	Os detalhes do erro.

Grain

Enumeração

Grão que corresponde ao valor.

Valor	Description
Hourly	A granulação por hora corresponde ao valor por hora.
Daily	A granulação por hora corresponde ao valor por dia.
Monthly	A granulação por hora corresponde ao valor por mês.

LookBackPeriod

Enumeração

O número de dias que costumava olhar para trás.

Valor	Description
Last7Days	7 dias usados para olhar para trás.
Last30Days	30 dias usados para olhar para trás.
Last60Days	60 dias usados para olhar para trás.

recommendationUsageDetails

Objeto

Encargos sob demanda entre firstConsumptionDate e lastConsumptionDate que foram usados para recomendações de benefício de computação.

Nome	Tipo	Description
charges	number[] (decimal)	Encargos sob demanda para cada hora entre firstConsumptionDate e lastConsumptionDate que foram usados para recomendações de benefício de computação.
usageGrain	Grain	O grão do uso. Valores com suporte: 'Por hora'

Scope

Enumeração

É meio que o escopo de recomendação.

Valor	Description
Single	Recomendação de escopo único.
Shared	Recomendação de escopo.

sharedScopeBenefitRecommendationProperties

Objeto

As propriedades da recomendação de benefício quando o escopo é 'Compartilhado'.

Nome	Tipo	Description
allRecommendationDetails	allSavingsList	A lista de todas as recomendações de benefício com os detalhes da recomendação.
armSkuName	string	Nome da SKU do ARM. 'Compute_Savings_Plan' para SavingsPlan.
commitmentGranularity	Grain	Granulação da quantidade de compromisso proposta. Valores com suporte: 'Por hora'
costWithoutBenefit	number (decimal)	O custo atual sem benefício corresponde a 'totalHours' no período de pesquisa.
currencyCode	string	Um identificador de código de moeda ISO 4217 para os custos e valores de economia.
firstConsumptionDate	string (date-time)	A primeira data de uso usada para procurar a computação das recomendações.
lastConsumptionDate	string (date-time)	A última data de uso usada para procurar a computação das recomendações.
lookBackPeriod	LookBackPeriod	O número de dias de uso avaliado para calcular as recomendações.
recommendationDetails	allSavingsBenefitDetails	Os detalhes da recomendação proposta.
scope	string: Shared	Escopo do benefício. Por exemplo, Single ou Shared.
term	Term	Período de prazo do benefício. Por exemplo, P1Y ou P3Y.
totalHours	integer (int32)	As horas totais para as quais o custo é coberto. É igual ao número de registros em uma propriedade 'properties/usage/charges'.
usage	recommendationUsageDetails	Encargos sob demanda entre firstConsumptionDate e lastConsumptionDate que foram usados para recomendações de benefício de computação.

singleScopeBenefitRecommendationProperties

Objeto

As propriedades das recomendações de benefício quando o escopo é 'Single'.

Nome	Tipo	Description
allRecommendationDetails	allSavingsList	A lista de todas as recomendações de benefício com os detalhes da recomendação.
armSkuName	string	Nome da SKU do ARM. 'Compute_Savings_Plan' para SavingsPlan.
commitmentGranularity	Grain	Granulação da quantidade de compromisso proposta. Valores com suporte: 'Por hora'
costWithoutBenefit	number (decimal)	O custo atual sem benefício corresponde a 'totalHours' no período de pesquisa.
currencyCode	string	Um identificador de código de moeda ISO 4217 para os custos e valores de economia.
firstConsumptionDate	string (date-time)	A primeira data de uso usada para procurar a computação das recomendações.
lastConsumptionDate	string (date-time)	A última data de uso usada para procurar a computação das recomendações.
lookBackPeriod	LookBackPeriod	O número de dias de uso avaliado para calcular as recomendações.
recommendationDetails	allSavingsBenefitDetails	Os detalhes da recomendação proposta.
resourceGroup	string	O grupo de recursos para o qual essa recomendação de escopo único serve. Aplicável somente se a recomendação for para escopo 'Único' e escopo de solicitação 'ResourceGroup'.
scope	string: Single	Escopo do benefício. Por exemplo, Single ou Shared.
subscriptionId	string	A ID da assinatura para a qual essa recomendação de escopo único serve. Aplicável somente se a recomendação for para o escopo 'Single'.
term	Term	Período de prazo do benefício. Por exemplo, P1Y ou P3Y.
totalHours	integer (int32)	As horas totais para as quais o custo é coberto. É igual ao número de registros em uma propriedade 'properties/usage/charges'.
usage	recommendationUsageDetails	Encargos sob demanda entre firstConsumptionDate e lastConsumptionDate que foram usados para recomendações de benefício de computação.

systemData

Objeto

Metadados relativos à criação e última modificação do recurso.

Nome	Tipo	Description
createdAt	string (date-time)	O carimbo de data/hora da criação de recursos (UTC).
createdBy	string	A identidade que criou o recurso.
createdByType	createdByType	O tipo de identidade que criou o recurso.
lastModifiedAt	string (date-time)	O carimbo de data/hora da última modificação do recurso (UTC)
lastModifiedBy	string	A identidade que modificou o recurso pela última vez.
lastModifiedByType	createdByType	O tipo de identidade que modificou o recurso pela última vez.

Term

Enumeração

Grão que corresponde ao valor.

Valor	Description
P1Y	O prazo do benefício é de 1 ano.
P3Y	O prazo do benefício é de 3 anos.

Compartilhar via

Benefit Recommendations - List

Parâmetros de URI

Respostas

Segurança

azure_auth

Escopos

Exemplos

BenefitRecommendationsBillingAccountList

Solicitação de exemplo

Resposta de exemplo

Definições

allSavingsBenefitDetails

allSavingsList

BenefitKind

benefitRecommendationModel

benefitRecommendationsListResult

createdByType

ErrorDetails

ErrorResponse

Grain

LookBackPeriod

recommendationUsageDetails

Scope

sharedScopeBenefitRecommendationProperties

singleScopeBenefitRecommendationProperties

systemData

Term