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 de límite de inversión a la API de Presupuesto de Facturación de Cloud.

Para obtener una lista completa de los 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 limitan a los clientes de primera parte Google Cloud y a las cuentas de Facturación de Cloud. Las cuentas de facturación de revendedores están fuera del alcance.

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

La página Administrar facturación muestra la ubicación del ID de tu cuenta de facturación.

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

Los presupuestos con límite de inversión utilizan costos brutos 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 estrictas de campos al presupuesto. Consulta los comentarios a nivel del campo en Filters, BudgetAmount, ThresholdRule, NotificationsRule y OwnershipScope.

  • billing-account-id: Los presupuestos con límite de inversión se limitan a los clientes deGoogle Cloud propios 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 limita a los presupuestos que se definen (filtran) para un solo Google Cloud proyecto y un solo servicio apto.
    • El período del presupuesto para un presupuesto con límite de inversión se limita a 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 como 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 al crear 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 de 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. No se admiten todos los demás parámetros de NotificationsRule.

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

  • Cuando crees 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 más rápido un límite de inversión, los presupuestos con límite de inversión usan costos brutos y 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 estimados del servicio específico superen el importe objetivo de tu presupuesto, se activará el límite de inversión y se aplicará durante el resto del período presupuestario. 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 pausa todo el uso nuevo del servicio específico en el proyecto especificado, incluido el uso según demanda, el uso de pago por uso y el uso cubierto por compromisos, como los descuentos por compromiso de uso (CUD) y la capacidad de procesamiento aprovisionada (PT).
    • Todas las solicitudes en curso del servicio especificado se procesan hasta su finalización, y se acumulan los cargos según corresponda.
    • Los límites de inversión no pausan ningún uso fijo en curso asociado con recursos persistentes (como los servicios de procesamiento y almacenamiento), que permanecen activos y siguen acumulando cargos.
    • Importante: Mientras se encuentre en un estado aplicado, no podrás editar la configuración de un presupuesto con límite de inversión ni borrar el presupuesto. Antes de editar o borrar un presupuesto aplicado, primero debes quitar manualmente el límite de inversión.

  • 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 especificado hasta que se quita el límite de inversión. Puedes aumentar un límite de inversión de las siguientes maneras:

    • Levantar automáticamente un límite de inversión: Un límite de inversión aplicado se levanta automáticamente al comienzo del próximo 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 la función normal de las llamadas a la API.

    • Cómo quitar manualmente un límite de inversión: 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 quitar manualmente el límite de inversión. Quitar manualmente un límite de inversión tiene los siguientes resultados:

      • Si aumentas manualmente un límite de inversión, se restablecerá el funcionamiento normal de las llamadas a la API.
      • Si quitas manualmente el límite de inversión 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 posteriormente para aumentar el importe del límite de inversión y establecer el inputState en CONFIGURED.

    Después de que se levanta un límite de inversión, es posible que los servicios tarden 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 Presupuestos de Facturación de Cloud para administrar los presupuestos de límite de inversión.

Crea un presupuesto con límite de inversión

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

REST

En este ejemplo, se muestra cómo crear un presupuesto con límite de inversión para el uso del servicio de la API de Gemini en un proyecto específico. El presupuesto se limita (filtra) a un solo proyecto de Google Cloud que especifiques, a un solo servicio apto y se establece para un importe de presupuesto mensual de USD 100.

Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

  • projects/budget-scope-project-id: El ID del proyecto Google Cloud que deseas establecer como unalcance del presupuesto(budgetFilter).
  • services/eligible-service_id: Uno de los IDs de servicio aptos que deseas establecer como un alcance del presupuesto (budgetFilter). En el ejemplo, usamos el ID de servicio AEFD-7695-64FA para el servicio de la API de Gemini.
  • billing-account-id: Es el ID de la cuenta de Facturación de Cloud a la que se aplica este presupuesto. Los presupuestos con límite de inversión se limitan a los clientes Google Cloud internos y las cuentas de Facturación de Cloud. Las cuentas de facturación de revendedor están fuera del alcance.
  • api-user-project-id: Es el proyecto Google Cloud en el que la API de Presupuesto de Facturación de Cloud está habilitada.

Método HTTP y URL: 

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

Cuerpo JSON de la solicitud:

{
  "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"
 }
}

Para enviar tu solicitud, expande una de estas opciones:

Deberías recibir una respuesta JSON similar a la que se muestra a continuación:

{
  "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 existente de límite de inversión de Facturación de Cloud y anular manualmente un límite de inversión aplicado.

REST

En este ejemplo, se muestra cómo aumentar manualmente un límite de inversión de ENFORCED en un presupuesto existente actualizando el parámetro SpendCap.inputState a AWAITING_NEXT_PERIOD.

Importante: Cuando el spend_cap.output_state es ENFORCED, primero debes levantar el límite de inversión enviando una solicitud de UpdateBudget para modificar el spend_cap.input_state, por ejemplo, estableciendo el input_state en AWAITING_NEXT_PERIOD, lo que levantará el límite. Si intentas modificar cualquier otro campo del presupuesto mientras el presupuesto se encuentra en un estado aplicado, la solicitud de actualización fallará con FAILED_PRECONDITION.

Para llamar a este método, necesitas el budget-id del presupuesto que deseas actualizar. Puedes obtener el ID de presupuesto del resultado createBudget cuando creas tu presupuesto, o del resultado listBudgets si enumeras todos tus presupuestos.

Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

  • billing-account-id: Es el ID de la cuenta de Facturación de Cloud a la que se aplica este presupuesto. Los presupuestos con límite de inversión se limitan a los clientes Google Cloud internos y las cuentas de Facturación de Cloud. Las cuentas de facturación de revendedor están fuera del alcance.
  • budget-id: el ID del presupuesto que deseas actualizar.
  • api-user-project-id: El proyecto Google Cloud en el que la API de Facturación de Cloud Budget está habilitada.

Método HTTP y URL: 

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

Cuerpo JSON de la solicitud:

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

Para enviar tu solicitud, expande una de estas opciones:

Deberías recibir una respuesta JSON similar a la que se muestra a continuación:

{
  "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 existente de límite de inversión de Facturación de Cloud para cambiar el importe del presupuesto y los filtros de presupuesto (alcance del presupuesto).

REST

En este ejemplo, se muestra cómo actualizar un presupuesto de límite de inversión existente para cambiar el importe del presupuesto. Si el estado del límite de inversión es AWAITING_NEXT_PERIOD, en este ejemplo, también se muestra cómo restablecer un límite de inversión aumentado actualizando el parámetro SpendCap.inputState a CONFIGURED.

Para llamar a este método, necesitas el budget-id del presupuesto que deseas actualizar. Puedes obtener el ID de presupuesto del resultado createBudget cuando creas tu presupuesto, o del resultado listBudgets si enumeras todos tus presupuestos.

Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

  • projects/budget-scope-project-id: El Google Cloud ID del proyecto que deseas establecer como alcance del presupuesto (budgetFilter).
  • services/eligible-service_id: Uno de los IDs de servicio aptos que deseas establecer como un alcance del presupuesto (budgetFilter). En el ejemplo, usamos el ID de servicio AEFD-7695-64FA para el servicio de la API de Gemini.
  • billing-account-id: Es el ID de la cuenta de Facturación de Cloud a la que se aplica este presupuesto. Los presupuestos con límite de inversión se limitan a los clientes Google Cloud internos y las cuentas de Facturación de Cloud. Las cuentas de facturación de revendedor están fuera del alcance.
  • budget-id: el ID del presupuesto que deseas actualizar.
  • api-user-project-id: El proyecto Google Cloud en el que la API de Facturación de Cloud Budget está habilitada.

Método HTTP y URL: 

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

Cuerpo JSON de la solicitud:

{
  "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"
 }
}

Para enviar tu solicitud, expande una de estas opciones:

Deberías recibir una respuesta JSON similar a la que se muestra a continuación:

{
  "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.

REST

Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

  • billing-account-id: Es el ID de la cuenta de Facturación de Cloud a la que se aplican los presupuestos. Los presupuestos con límite de inversión se limitan a los clientes Google Cloud internos y las cuentas de Facturación de Cloud. Las cuentas de facturación de revendedor están fuera del alcance.
  • project-id: Es el proyecto Google Cloud en el que está habilitada la API de Presupuesto de Facturación de Cloud.

Método HTTP y URL: 

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

Para enviar tu solicitud, expande una de estas opciones:

Deberías recibir una respuesta JSON similar a la que se muestra a continuación:

{
  "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.

REST

Para llamar a este método, necesitas el budget-id del presupuesto que deseas actualizar. Puedes obtener el ID de presupuesto del resultado createBudget cuando creas tu presupuesto, o del resultado listBudgets si enumeras todos tus presupuestos.

Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

  • billing-account-id: Es el ID de la cuenta de Facturación de Cloud a la que se aplica este presupuesto. Los presupuestos con límite de inversión se limitan a los clientes Google Cloud internos y las cuentas de Facturación de Cloud. Las cuentas de facturación de revendedor están fuera del alcance.
  • budget-id: el ID del presupuesto que deseas obtener.
  • project-id: Es el proyecto Google Cloud en el que está habilitada la API de Presupuesto de Facturación de Cloud.

Método HTTP y URL: 

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

Para enviar tu solicitud, expande una de estas opciones:

Deberías recibir una respuesta JSON similar a la que se muestra a continuación:

{
  "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.

REST

Para llamar a este método, necesitas el budget-id del presupuesto que deseas actualizar. Puedes obtener el ID de presupuesto del resultado createBudget cuando creas tu presupuesto, o del resultado listBudgets si enumeras todos tus presupuestos.

Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

  • billing-account-id: Es el ID de la cuenta de Facturación de Cloud a la que se aplica este presupuesto.
  • budget-id: el ID del presupuesto que deseas borrar.
  • project-id: Es el proyecto Google Cloud en el que está habilitada la API de Presupuesto de Facturación de Cloud.

Método HTTP y URL: 

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

Para enviar tu solicitud, expande una de estas opciones:

Deberías recibir una respuesta JSON similar a la que se muestra a continuación:

{}

Anterior
Usa la API de Budget para presupuestos solo de alertas