Usa la API de Facturación de Cloud Budget para los presupuestos con límite de inversión

Obtén más información para enviar algunas solicitudes de presupuesto con límite de inversión a la API de Presupuesto de Facturación de Cloud.

Para obtener una lista completa de métodos, consulta la documentación de referencia de la API de REST.

Antes de comenzar

Debes hacer lo siguiente antes de leer esta guía:

1. Consulta Descripción general de la API de presupuesto de Facturación de Cloud.
2. Consulta Requisitos previos de la API de presupuesto de Facturación de Cloud.
3. Realiza los pasos de configuración.

Identifica el ID de la cuenta de Facturación de Cloud

Para cada llamada a la API de Cloud Billing Budget, necesitas tu ID de cuenta de Facturación de Cloud. Los presupuestos con límite de inversión se restringen a los clientes deGoogle Cloud y a las cuentas de Facturación de Cloud. Las cuentas de facturación de revendedor están fuera del alcance.

1. Ve a la página Administrar cuentas de facturación de la consola de Google Cloud .
2. En la pestaña Tus cuentas de facturación, verás la lista de cuentas de Facturación de Cloud por ID y nombre. Busca el valor del ID de cuenta de la cuenta en la que administras los presupuestos.

Conceptos y limitaciones clave del presupuesto con límite de inversión

Los presupuestos con límite de inversión usan costos brutos y estimados para activar alertas y aplicar límites de inversión, lo que bloquea el uso y la acumulación de costos hasta que se quite el límite de inversión.

Restricciones del campo de presupuesto con límite de inversión

Cuando se establece spendCap en un presupuesto, se aplican restricciones de campo estrictas al presupuesto. Consulta los comentarios a nivel de campo en Filters, BudgetAmount, ThresholdRule, NotificationsRule y OwnershipScope.

• billing-account-id: Los presupuestos con límite de inversión se restringen a los clientes propios deGoogle Cloud y a las cuentas de Facturación de Cloud. Las cuentas de facturación de revendedor están fuera del alcance.

• BudgetFilters debe incluir los siguientes parámetros:

  • Un presupuesto con límite de inversión se restringe a los presupuestos que tienen alcance (filtrados) a un solo proyecto de Google Cloud y un solo servicio apto.
  • El período del presupuesto con límite de inversión se restringe a un CalendarPeriod de un MONTH.
  • Los cálculos de costos para los límites de inversión se basan en los costos brutos y no incluyen ahorros ni créditos. Debes configurar creditTypesTreatment en EXCLUDE_ALL_CREDITS.
  • No se admiten otros filtros de presupuesto para los límites de inversión, y deben estar vacíos, incluidos resourceAncestors, credit_types, subaccounts y labels.

• El BudgetAmount debe usar un specifiedAmount. En la entrada, currencyCode es opcional. Si se especifica cuando se crea un presupuesto, el código de moneda debe coincidir con la moneda de la cuenta de Facturación de Cloud. El currencyCode se proporciona en la salida.

• ThresholdRules debe contener exactamente tres reglas con valores thresholdPercent de 0.5, 0.8 y 1.0 (50%, 80% y 100%), con un spendBasis establecido en CURRENT_SPEND o BASIS_UNSPECIFIED (FORECASTED_SPEND no se admite para los límites de inversión).

• NotificationsRule: Debe establecer enableProjectLevelRecipients en true. Todos los demás parámetros de NotificationsRule no son compatibles.

• OwnershipScope se debe establecer en OWNERSHIP_SCOPE_UNSPECIFIED o ALL_USERS (BILLING_ACCOUNT no se admite para los límites de inversión).

• Cuando creas un presupuesto con límite de inversión, el parámetro inputState debe establecerse en CONFIGURED.

Cómo funcionan los presupuestos con límite de inversión para ayudarte a controlar la inversión

• Cálculos de inversión más rápidos con costos estimados: Para aplicar con mayor rapidez un importe de límite de inversión, los presupuestos con límite de inversión usan costos brutos estimados para activar alertas y aplicar el límite de inversión. Los costos estimados se calculan en función del precio de lista de los servicios y no incluyen ahorros ni créditos.

• Pausa automática del uso y la acumulación de costos cuando se activa el límite de inversión: En el proyecto especificado, cuando los costos de uso brutos y estimados para el servicio específico superen el importe objetivo del presupuesto, se activará y aplicará el límite de inversión durante el resto del período del presupuesto. En el presupuesto, el parámetro outputState se establece en ENFORCED. Mientras se aplica un límite de inversión, se aplica lo siguiente:

  • Se detiene todo el uso nuevo del servicio específico en el proyecto indicado, incluido el uso a pedido y de pago por uso, y el uso cubierto por compromisos, como los descuentos por compromiso de uso (CUD).
  • Todas las solicitudes en curso del servicio especificado se procesan hasta completarse, y se acumulan los cargos según corresponda.
  • Los límites de inversión no detienen el uso fijo y continuo asociado con los recursos persistentes (como los servicios de procesamiento y almacenamiento), que permanecen activos y siguen acumulando cargos.
  • Importante: Mientras se encuentre en un estado de aplicación de política, no podrás editar la configuración de un presupuesto con límite de inversión ni borrarlo. Antes de editar o borrar un presupuesto aplicado, primero debes quitar el límite de inversión de forma manual.

• Quita un límite de inversión aplicado para restablecer los servicios y la inversión: Cuando se aplica un límite de inversión, se bloquea el uso del servicio específico en el proyecto indicado hasta que se quite el límite. Puedes quitar un límite de inversión de las siguientes maneras:

  • Quitar automáticamente un límite de inversión: Un límite de inversión aplicado se quita automáticamente al comienzo del siguiente período presupuestario (por lo general, el primer día del mes siguiente). Cuando se quita automáticamente un límite de inversión, el importe de inversión del presupuesto se restablece a cero, el estado del límite de inversión se restablece a CONFIGURED y se desbloquean los servicios especificados, lo que restablece el funcionamiento normal de las llamadas a la API.

  • Quita un límite de inversión de forma manual: Si necesitas revertir un bloqueo de uso durante el mismo período de presupuesto en el que se aplica el límite de inversión, puedes editar el presupuesto para quitarlo de forma manual. Quitar un límite de inversión de forma manual tiene los siguientes resultados:

    • Si quitas manualmente un límite de inversión, se restablecerá el funcionamiento normal de las llamadas a la API.
    • Si quitas el límite de inversión de forma manual estableciendo el estado del límite de inversión en AWAITING_NEXT_PERIOD, el límite de inversión no se volverá a activar durante el resto del período presupuestario, a menos que edites el presupuesto más adelante para aumentar el importe del límite de inversión y establezcas el inputState en CONFIGURED.

  Después de que se quita un límite de inversión, los servicios pueden tardar hasta una hora en volver a funcionar con normalidad.

• Restablecimiento automático de los presupuestos con límite de inversión: Al comienzo del siguiente período presupuestario (por lo general, el primer día del mes siguiente), todos los presupuestos con límite de inversión se restablecen automáticamente, lo que establece el importe de inversión bruto estimado en cero y el estado del límite de inversión en CONFIGURED.

Limitación de cuota: Cada cuenta de Facturación de Cloud individual puede tener varios miles de presupuestos asociados a ella a la vez. Consulta Cuotas y límites para obtener información adicional y los límites actuales.

Llama a la API

En los siguientes ejemplos, se muestra cómo enviar algunas solicitudes a la API de Facturación de Cloud Budget para administrar los presupuestos con límite de inversión.

Cómo crear un presupuesto con límite de inversión

Este método de la API crea un presupuesto con límite de gasto de Facturación de Cloud aplicado a un solo proyecto y servicio apto.

POST https://billingbudgets.googleapis.com/v1/billingAccounts/billing-account-id/budgets

{
  "displayName": "My Gemini API Spend Cap",
  "budgetFilter": {
    "projects": [
      "projects/budget-scope-project-id"
    ],
    "services": [
      "services/AEFD-7695-64FA"
    ],
    "creditTypesTreatment": "EXCLUDE_ALL_CREDITS",
    "calendarPeriod": "MONTH"
 },
 "amount": {
   "specifiedAmount": {
     "units": "100",
     "nanos": 0
   }
 },
 "thresholdRules": [
   { "thresholdPercent": 0.5 },
   { "thresholdPercent": 0.8 },
   { "thresholdPercent": 1.0 }
 ],
 "notificationsRule": {
   "enableProjectLevelRecipients": true
 },
 "spendCap": {
   "inputState": "CONFIGURED"
 }
}

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "x-goog-user-project: api-user-project-id" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://billingbudgets.googleapis.com/v1/billingAccounts/billing-account-id/budgets"

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred"; "x-goog-user-project" = "api-user-project-id" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://billingbudgets.googleapis.com/v1/billingAccounts/billing-account-id/budgets" | Select-Object -Expand Content

{
  "name": "billingAccounts/000000-111111-222222/budgets/33333333-4444-5555-6666-777777777777",
  "displayName": "My Gemini API Spend Cap",
  "budgetFilter": {
    "projects": [
      "projects/123456789"
    ],
    "services": [
      "services/AEFD-7695-64FA"
    ],
    "creditTypesTreatment": "EXCLUDE_ALL_CREDITS",
    "calendarPeriod": "MONTH"
  },
  "amount": {
    "specifiedAmount": {
       "currencyCode": "USD",
       "units": "100"
     }
  },
  "thresholdRules": [
    {
      "thresholdPercent": 0.5,
      "spendBasis": "CURRENT_SPEND"
    },
    {
      "thresholdPercent": 0.8,
      "spendBasis": "CURRENT_SPEND"
    },
    {
      "thresholdPercent": 1,
      "spendBasis": "CURRENT_SPEND"
    }
  ],
  "notificationsRule": {
    "enableProjectLevelRecipients": true
  },
  "etag": "1790365289674138",
  "spendCap": {
    "outputState": "CONFIGURED"
  }
}

Cómo aumentar un límite de inversión con PATCH

Usa el método de la API PATCH para modificar un presupuesto con límite de inversión de Facturación de Cloud existente y quitar manualmente un límite de inversión aplicado.

PATCH https://billingbudgets.googleapis.com/v1/billingAccounts/billing-account-id/budgets/budget-id?updateMask=spendCap.inputState

{
  "spendCap": {
    "inputState": "AWAITING_NEXT_PERIOD"
 }
}

curl -X PATCH \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "x-goog-user-project: api-user-project-id" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://billingbudgets.googleapis.com/v1/billingAccounts/billing-account-id/budgets/budget-id?updateMask=spendCap.inputState"

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred"; "x-goog-user-project" = "api-user-project-id" }

Invoke-WebRequest `
    -Method PATCH `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://billingbudgets.googleapis.com/v1/billingAccounts/billing-account-id/budgets/budget-id?updateMask=spendCap.inputState" | Select-Object -Expand Content

{
  "name": "billingAccounts/000000-111111-222222/budgets/33333333-4444-5555-6666-777777777777",
  "displayName": "My Gemini API Spend Cap",
  "budgetFilter": {
    "projects": [
      "projects/123456789"
    ],
    "services": [
      "services/AEFD-7695-64FA"
    ],
    "creditTypesTreatment": "EXCLUDE_ALL_CREDITS",
    "calendarPeriod": "MONTH"
  },
  "amount": {
    "specifiedAmount": {
       "currencyCode": "USD",
       "units": "100"
     }
  },
  "thresholdRules": [
    {
      "thresholdPercent": 0.5,
      "spendBasis": "CURRENT_SPEND"
    },
    {
      "thresholdPercent": 0.8,
      "spendBasis": "CURRENT_SPEND"
    },
    {
      "thresholdPercent": 1,
      "spendBasis": "CURRENT_SPEND"
    }
  ],
  "notificationsRule": {
    "enableProjectLevelRecipients": true
  },
  "etag": "1790365289674138",
  "spendCap": {
    "outputState": "AWAITING_NEXT_PERIOD",
    "reconciling": true
  }
}

Actualiza un presupuesto con límite de inversión con PATCH

Usa este método de la API para modificar un presupuesto con límite de inversión de Facturación de Cloud existente y cambiar el importe del presupuesto y los filtros de presupuesto (alcance del presupuesto).

PATCH https://billingbudgets.googleapis.com/v1/billingAccounts/billing-account-id/budgets/budget-id?updateMask=amount.specifiedAmount,spendCap.inputState

{
  "displayName": "My Gemini API Spend Cap",
  "budgetFilter": {
    "projects": [
      "projects/budget-scope-project-id"
    ],
    "services": [
      "services/AEFD-7695-64FA"
    ],
    "creditTypesTreatment": "EXCLUDE_ALL_CREDITS",
    "calendarPeriod": "MONTH"
 },
 "amount": {
   "specifiedAmount": {
     "units": "500",
     "nanos": 0
   }
 },
 "thresholdRules": [
   { "thresholdPercent": 0.5 },
   { "thresholdPercent": 0.8 },
   { "thresholdPercent": 1.0 }
 ],
 "notificationsRule": {
   "enableProjectLevelRecipients": true
 },
 "spendCap": {
   "inputState": "CONFIGURED"
 }
}

curl -X PATCH \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "x-goog-user-project: api-user-project-id" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://billingbudgets.googleapis.com/v1/billingAccounts/billing-account-id/budgets/budget-id?updateMask=amount.specifiedAmount,spendCap.inputState"

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred"; "x-goog-user-project" = "api-user-project-id" }

Invoke-WebRequest `
    -Method PATCH `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://billingbudgets.googleapis.com/v1/billingAccounts/billing-account-id/budgets/budget-id?updateMask=amount.specifiedAmount,spendCap.inputState" | Select-Object -Expand Content

{
  "name": "billingAccounts/000000-111111-222222/budgets/33333333-4444-5555-6666-777777777777",
  "displayName": "My Gemini API Spend Cap",
  "budgetFilter": {
    "projects": [
      "projects/123456789"
    ],
    "services": [
      "services/AEFD-7695-64FA"
    ],
    "creditTypesTreatment": "EXCLUDE_ALL_CREDITS",
    "calendarPeriod": "MONTH"
  },
  "amount": {
    "specifiedAmount": {
       "currencyCode": "USD",
       "units": "500"
     }
  },
  "thresholdRules": [
    {
      "thresholdPercent": 0.5,
      "spendBasis": "CURRENT_SPEND"
    },
    {
      "thresholdPercent": 0.8,
      "spendBasis": "CURRENT_SPEND"
    },
    {
      "thresholdPercent": 1,
      "spendBasis": "CURRENT_SPEND"
    }
  ],
  "notificationsRule": {
    "enableProjectLevelRecipients": true
  },
  "etag": "1790365289674138",
  "spendCap": {
    "outputState": "CONFIGURED"
  }
}

Mostrar presupuestos

Este método de API enumera todos los presupuestos disponibles para una cuenta de facturación de Cloud determinada.

GET https://billingbudgets.googleapis.com/v1/billingAccounts/billing-account-id/budgets

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "x-goog-user-project: project-id" \
     "https://billingbudgets.googleapis.com/v1/billingAccounts/billing-account-id/budgets"

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred"; "x-goog-user-project" = "project-id" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://billingbudgets.googleapis.com/v1/billingAccounts/billing-account-id/budgets" | Select-Object -Expand Content

{
  "budgets": [
   {
      "name": "billingAccounts/000000-111111-222222/budgets/33333333-4444-5555-6666-777777777777",
      "displayName": "Gemini API Spend Cap in My Project",
      "budgetFilter": {
        "projects": [
          "projects/987654321"
        ],
        "services": [
          "services/AEFD-7695-64FA"
        ],
        "creditTypesTreatment": "EXCLUDE_ALL_CREDITS",
        "calendarPeriod": "MONTH"
      },
      "amount": {
        "specifiedAmount": {
          "currencyCode": "USD",
          "units": "500"
        }
      },
      "thresholdRules": [
        {
          "thresholdPercent": 0.5,
          "spendBasis": "CURRENT_SPEND"
        },
        {
          "thresholdPercent": 0.8,
          "spendBasis": "CURRENT_SPEND"
        },
        {
          "thresholdPercent": 1,
          "spendBasis": "CURRENT_SPEND"
        }
      ],
      "notificationsRule": {
        "enableProjectLevelRecipients": true
      },
      "allUpdatesRule": {},
      "etag": "17fc365289f74138c",
      "spendCap": {
        "outputState": "ENFORCED"
      }
    }
  ]
}

Obtén el presupuesto

Este método de API obtiene los detalles de un presupuesto determinado.

GET https://billingbudgets.googleapis.com/v1/billingAccounts/billing-account-id/budgets/budget-id

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "x-goog-user-project: project-id" \
     "https://billingbudgets.googleapis.com/v1/billingAccounts/billing-account-id/budgets/budget-id"

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred"; "x-goog-user-project" = "project-id" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://billingbudgets.googleapis.com/v1/billingAccounts/billing-account-id/budgets/budget-id" | Select-Object -Expand Content

{
  "name": "billingAccounts/000000-111111-222222/budgets/33333333-4444-5555-6666-777777777777",
  "displayName": "Cloud Run Spend Cap in My Project",
  "budgetFilter": {
    "projects": [
      "projects/987654321"
    ],
    "services": [
      "services/152E-C115-5142"
    ],
    "creditTypesTreatment": "EXCLUDE_ALL_CREDITS",
    "calendarPeriod": "MONTH"
  },
  "amount": {
    "specifiedAmount": {
       "currencyCode": "USD",
       "units": "450"
     }
  },
  "thresholdRules": [
    {
      "thresholdPercent": 0.5,
      "spendBasis": "CURRENT_SPEND"
    },
    {
      "thresholdPercent": 0.8,
      "spendBasis": "CURRENT_SPEND"
    },
    {
      "thresholdPercent": 1,
      "spendBasis": "CURRENT_SPEND"
    }
  ],
  "notificationsRule": {
    "enableProjectLevelRecipients": true
  },
  "allUpdatesRule": {},
  "etag": "c9d6c011f6fa6b5c",
  "spendCap": {
    "outputState": "CONFIGURED"
  }
}

Borra un presupuesto

Usa este método de la API para borrar un presupuesto existente de Facturación de Cloud.

DELETE https://billingbudgets.googleapis.com/v1/billingAccounts/billing-account-id/budgets/budget-id

curl -X DELETE \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "x-goog-user-project: project-id" \
     "https://billingbudgets.googleapis.com/v1/billingAccounts/billing-account-id/budgets/budget-id"

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred"; "x-goog-user-project" = "project-id" }

Invoke-WebRequest `
    -Method DELETE `
    -Headers $headers `
    -Uri "https://billingbudgets.googleapis.com/v1/billingAccounts/billing-account-id/budgets/budget-id" | Select-Object -Expand Content

{}