Utiliser l'API Cloud Billing Budget pour les budgets avec un plafond de dépenses

Découvrez comment envoyer des requêtes de budget avec un plafond de dépenses à l'API Cloud Billing Budget.

Pour obtenir la liste complète des méthodes, consultez la documentation de référence de l'API REST.

Avant de commencer

Avant de lire ce guide, procédez comme suit :

  1. Consultez la section Présentation de l'API Cloud Billing Budget.
  2. Consultez la section Conditions préalables à l'utilisation de l'API Cloud Billing Budget.
  3. Effectuez la procédure de configuration.

Identifier votre ID de compte de facturation Cloud

Pour chaque appel de l'API Cloud Billing Budget, vous avez besoin de votre ID de compte de facturation Cloud. Les budgets avec plafond de dépenses sont réservés aux clientsGoogle Cloud propriétaires et aux comptes de facturation Cloud. Les comptes de facturation des revendeurs ne sont pas concernés.

  1. Accédez à la page Gérer les comptes de facturation de la Google Cloud console.
  2. Dans l'onglet Vos comptes de facturation, vous voyez la liste des comptes de facturation Cloud par nom et ID. Recherchez la valeur de l'ID de compte pour le compte dans lequel vous gérez les budgets.

Page "Gérer la facturation" indiquant l'emplacement de l'ID de votre compte de facturation.

Concepts clés et limites concernant les budgets avec limite de dépenses

Les budgets avec plafond de dépenses utilisent les coûts bruts estimés pour déclencher des alertes et appliquer des limites de dépenses, ce qui bloque l'utilisation et l'accumulation de coûts jusqu'à ce que le plafond de dépenses soit levé.

Restrictions concernant le champ "Budget avec plafond de dépenses"

Lorsque spendCap est défini sur un budget, des restrictions strictes concernant les champs s'appliquent au budget. Consultez les commentaires au niveau des champs sur Filters, BudgetAmount, ThresholdRule, NotificationsRule et OwnershipScope.

  • billing-account-id : les budgets avec un plafond de dépenses sont limités aux clientsGoogle Cloud propriétaires et aux comptes de facturation Cloud. Les comptes de facturation de revendeur ne sont pas concernés.

  • BudgetFilters doit inclure les paramètres suivants :

    • Un budget avec un plafond de dépenses est limité aux budgets dont le champ d'application (filtré) est défini sur un seul Google Cloud projet et un seul service éligible.
    • La période du budget avec un plafond de dépenses est limitée à CalendarPeriod MONTH.
    • Les calculs des coûts pour les plafonds de dépenses sont basés sur les coûts bruts et n'incluent pas les économies ni les crédits. Vous devez définir creditTypesTreatment sur EXCLUDE_ALL_CREDITS.
    • Les autres filtres de budget ne sont pas compatibles avec les limites de dépenses et doivent être vides, y compris resourceAncestors, credit_types, subaccounts et labels.

  • BudgetAmount doit utiliser un specifiedAmount. currencyCode est facultatif en entrée. Si vous spécifiez un code de devise lors de la création d'un budget, il doit correspondre à la devise du compte de facturation Cloud. Le currencyCode est fourni dans le résultat.

  • ThresholdRules doit contenir exactement trois règles avec des valeurs thresholdPercent de 0.5, 0.8 et 1.0 (50%, 80 % et 100%), avec une valeur spendBasis définie sur CURRENT_SPEND ou BASIS_UNSPECIFIED (FORECASTED_SPEND n'est pas compatible avec les plafonds de dépenses).

  • NotificationsRule doit définir enableProjectLevelRecipients sur true. Tous les autres paramètres NotificationsRule ne sont pas acceptés.

  • OwnershipScope doit être défini sur OWNERSHIP_SCOPE_UNSPECIFIED ou ALL_USERS (BILLING_ACCOUNT n'est pas accepté pour les limites de dépenses).

  • Lorsque vous créez un budget avec un plafond de dépenses, le paramètre inputState doit être défini sur CONFIGURED.

Comment les budgets avec plafond de dépenses vous aident à contrôler vos dépenses

  • Calcul plus rapide des dépenses à l'aide des coûts estimés : pour appliquer plus rapidement un montant de plafond de dépenses, les budgets de plafond de dépenses utilisent des coûts bruts et estimés pour déclencher des alertes et appliquer le plafond de dépenses. Les coûts estimés sont calculés en fonction du prix catalogue des services et n'incluent pas les économies ni les crédits.

  • Mise en pause automatique de l'utilisation et de l'accumulation des coûts lorsque le plafond de dépenses est déclenché : Dans le projet spécifié, lorsque vos coûts d'utilisation bruts et estimés pour le service spécifique dépassent le montant cible de votre budget, le plafond de dépenses est déclenché et appliqué pour le reste de la période budgétaire. Dans le budget, le paramètre outputState est défini sur ENFORCED. Lorsqu'un plafond de dépenses est appliqué, les conditions suivantes s'appliquent :

    • Toute nouvelle utilisation du service spécifique dans le projet spécifié est suspendue, y compris l'utilisation à la demande, avec paiement à l'usage et l'utilisation couverte par des engagements tels que les remises sur engagement d'utilisation et le débit provisionné.
    • Toutes les requêtes en cours du service spécifié sont traitées jusqu'à leur terme, et les frais sont facturés le cas échéant.
    • Les plafonds de dépenses ne mettent pas en pause l'utilisation fixe et continue associée aux ressources persistantes (telles que les services de calcul et de stockage), qui restent actives et continuent de générer des frais.
    • Important : Lorsque le budget est en état appliqué, vous ne pouvez pas modifier ses paramètres ni le supprimer. Avant de modifier ou de supprimer un budget appliqué, vous devez d'abord lever manuellement le plafond de dépenses.

  • Lever un plafond de dépenses appliqué pour restaurer les services et les dépenses : lorsqu'un plafond de dépenses est appliqué, l'utilisation du service spécifique dans le projet spécifié est bloquée jusqu'à ce que le plafond de dépenses soit levé. Vous pouvez lever un plafond de dépenses de différentes manières :

    • Lever automatiquement un plafond de dépenses : un plafond de dépenses appliqué est automatiquement levé au début de la période budgétaire suivante (généralement le premier jour du mois suivant). Lorsqu'un plafond de dépenses est levé automatiquement, le montant des dépenses du budget est réinitialisé à zéro, l'état du plafond de dépenses est réinitialisé sur CONFIGURED et les services spécifiés sont débloqués, ce qui restaure le fonctionnement normal des appels d'API.

    • Lever manuellement un plafond de dépenses : si vous devez annuler un blocage de l'utilisation au cours de la même période budgétaire où le plafond de dépenses est appliqué, vous pouvez modifier le budget pour lever manuellement le plafond de dépenses. La levée manuelle d'un plafond de dépenses a les conséquences suivantes :

      • Si vous supprimez manuellement un plafond de dépenses, les appels d'API retrouveront leur fonctionnement normal.
      • Si vous levez manuellement le plafond de dépenses en définissant l'état du plafond de dépenses sur AWAITING_NEXT_PERIOD, il ne sera pas déclenché à nouveau pour le reste de la période budgétaire, sauf si vous modifiez ensuite le budget pour augmenter le montant du plafond de dépenses et définissez inputState sur CONFIGURED.

    Une fois le plafond de dépenses levé, la reprise complète des services peut prendre jusqu'à une heure.

  • Réinitialisation automatique des budgets avec plafond de dépenses : au début de la période budgétaire suivante (généralement le premier jour du mois suivant), tous les budgets avec plafond de dépenses sont automatiquement réinitialisés. Le montant des dépenses brutes estimées est alors défini sur zéro et l'état du plafond de dépenses est défini sur CONFIGURED.

Limite de quota Chaque compte de facturation Cloud individuel peut avoir plusieurs milliers de budgets associés à la fois. Pour connaître les limites actuelles et d'autres informations, consultez la section Quotas et limites.

Appeler l'API

Les exemples suivants montrent comment envoyer quelques requêtes à l'API Cloud Billing Budget pour gérer les budgets avec un plafond de dépenses.

Créer un budget avec un plafond de dépenses

Cette méthode API permet de créer un budget de plafond de dépenses Cloud Billing appliqué à un seul projet et à un service éligible.

REST

Cet exemple montre comment créer un budget avec un plafond de dépenses pour l'utilisation du service API Gemini dans un projet spécifique. Le budget est limité (filtré) à un seul projet Google Cloud que vous spécifiez, à un seul service éligible et défini sur un montant budgétaire mensuel de 100 $.

Avant d'utiliser les données de requête, effectuez les remplacements suivants :

  • projects/budget-scope-project-id : ID du projet Google Cloud que vous souhaitez définir en tant que champ d'application du budget (budgetFilter).
  • services/eligible-service_id : l'un des ID de service éligibles que vous souhaitez définir en tant que champ d'application du budget (budgetFilter). Dans l'exemple, nous utilisons l'ID de service AEFD-7695-64FA pour le service API Gemini.
  • billing-account-id : numéro du compte de facturation Cloud auquel ce budget s'applique. Les budgets avec plafond de dépenses sont réservés aux clients propriétaires Google Cloud et aux comptes de facturation Cloud. Les comptes de facturation revendeur ne sont pas concernés.
  • api-user-project-id : projet Google Cloud dans lequel l'API Cloud Billing Budget est activée.

Méthode HTTP et URL : 

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

Corps JSON de la requête :

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

Pour envoyer votre requête, développez l'une des options suivantes :

Vous devriez recevoir une réponse JSON de ce type :

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

Lever un plafond de dépenses à l'aide de PATCH

Utilisez la méthode d'API PATCH pour modifier un budget de plafond de dépenses Cloud Billing existant afin de supprimer manuellement un plafond de dépenses appliqué.

REST

Cet exemple montre comment supprimer manuellement un plafond de dépenses ENFORCED sur un budget existant en mettant à jour le paramètre SpendCap.inputState sur AWAITING_NEXT_PERIOD.

Important : Lorsque spend_cap.output_state est défini sur ENFORCED, vous devez d'abord lever le plafond de dépenses en envoyant une requête UpdateBudget pour modifier spend_cap.input_state, par exemple en définissant input_state sur AWAITING_NEXT_PERIOD, ce qui lèvera le plafond. Si vous tentez de modifier un autre champ de budget alors que le budget est dans un état appliqué, la requête de mise à jour échouera avec FAILED_PRECONDITION.

Pour appeler cette méthode, vous avez besoin du budget-id du budget que vous souhaitez mettre à jour. Vous pouvez obtenir l'ID du budget à partir de la sortie createBudget lorsque vous créez votre budget ou de la sortie listBudgets si vous répertoriez tous vos budgets.

Avant d'utiliser les données de requête ci-dessous, effectuez les remplacements suivants :

  • billing-account-id : numéro du compte de facturation Cloud auquel ce budget s'applique. Les budgets avec plafond de dépenses sont réservés aux clients propriétaires Google Cloud et aux comptes de facturation Cloud. Les comptes de facturation revendeur ne sont pas concernés.
  • budget-id : ID du budget que vous souhaitez mettre à jour.
  • api-user-project-id : projet Google Cloud dans lequel l'API Cloud Billing Budget est activée.

Méthode HTTP et URL : 

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

Corps JSON de la requête :

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

Pour envoyer votre requête, développez l'une des options suivantes :

Vous devriez recevoir une réponse JSON de ce type :

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

Mettre à jour un budget plafonné à l'aide de PATCH

Cette méthode API permet de modifier un budget de plafond de dépenses Cloud Billing existant afin de modifier le montant du budget et les filtres de budget (champ d'application du budget).

REST

Cet exemple montre comment mettre à jour un budget de plafond de dépenses existant pour modifier le montant du budget. Si l' état du plafond de dépenses est AWAITING_NEXT_PERIOD, cet exemple montre également comment réinitialiser un plafond de dépenses supprimé en mettant à jour le paramètre SpendCap.inputState sur CONFIGURED.

Pour appeler cette méthode, vous avez besoin du budget-id du budget que vous souhaitez mettre à jour. Vous pouvez obtenir l'ID du budget à partir de la sortie createBudget lorsque vous créez votre budget ou de la sortie listBudgets si vous répertoriez tous vos budgets.

Avant d'utiliser les données de requête, effectuez les remplacements suivants :

  • projects/budget-scope-project-id : ID du projet Google Cloud que vous souhaitez définir en tant que champ d'application du budget (budgetFilter).
  • services/eligible-service_id : l'un des ID de service éligibles que vous souhaitez définir en tant que champ d'application du budget (budgetFilter). Dans l'exemple, nous utilisons l'ID de service AEFD-7695-64FA pour le service API Gemini.
  • billing-account-id : numéro du compte de facturation Cloud auquel ce budget s'applique. Les budgets avec plafond de dépenses sont réservés aux clients propriétaires Google Cloud et aux comptes de facturation Cloud. Les comptes de facturation revendeur ne sont pas concernés.
  • budget-id : ID du budget que vous souhaitez mettre à jour.
  • api-user-project-id : projet Google Cloud dans lequel l'API Cloud Billing Budget est activée.

Méthode HTTP et URL : 

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

Corps JSON de la requête :

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

Pour envoyer votre requête, développez l'une des options suivantes :

Vous devriez recevoir une réponse JSON de ce type :

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

Répertorier les budgets

Cette méthode API permet de répertorier tous les budgets disponibles pour un compte de facturation Cloud donné.

REST

Avant d'utiliser les données de requête ci-dessous, effectuez les remplacements suivants :

  • billing-account-id : ID du compte de facturation Cloud auquel les budgets s'appliquent. Les budgets avec plafond de dépenses sont réservés aux clients propriétaires Google Cloud et aux comptes de facturation Cloud. Les comptes de facturation revendeur ne sont pas concernés.
  • project-id : projet Google Cloud dans lequel l'API Cloud Billing Budget est activée.

Méthode HTTP et URL : 

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

Pour envoyer votre requête, développez l'une des options suivantes :

Vous devriez recevoir une réponse JSON de ce type :

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

Obtenir le budget

Cette méthode API permet d'obtenir les détails d'un budget particulier.

REST

Pour appeler cette méthode, vous avez besoin du budget-id du budget que vous souhaitez mettre à jour. Vous pouvez obtenir l'ID du budget à partir de la sortie createBudget lorsque vous créez votre budget ou de la sortie listBudgets si vous répertoriez tous vos budgets.

Avant d'utiliser les données de requête ci-dessous, effectuez les remplacements suivants :

  • billing-account-id : numéro du compte de facturation Cloud auquel ce budget s'applique. Les budgets avec plafond de dépenses sont réservés aux clients propriétaires Google Cloud et aux comptes de facturation Cloud. Les comptes de facturation revendeur ne sont pas concernés.
  • budget-id : ID du budget que vous souhaitez obtenir.
  • project-id : projet Google Cloud dans lequel l'API Cloud Billing Budget est activée.

Méthode HTTP et URL : 

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

Pour envoyer votre requête, développez l'une des options suivantes :

Vous devriez recevoir une réponse JSON de ce type :

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

Supprimer un budget

Cette méthode API permet de supprimer un budget Cloud Billing existant.

REST

Pour appeler cette méthode, vous avez besoin du budget-id du budget que vous souhaitez mettre à jour. Vous pouvez obtenir l'ID du budget à partir de la sortie createBudget lorsque vous créez votre budget ou de la sortie listBudgets si vous répertoriez tous vos budgets.

Avant d'utiliser les données de requête ci-dessous, effectuez les remplacements suivants :

  • billing-account-id : numéro du compte de facturation Cloud auquel ce budget s'applique.
  • budget-id : ID du budget que vous souhaitez supprimer.
  • project-id : projet Google Cloud dans lequel l'API Cloud Billing Budget est activée.

Méthode HTTP et URL : 

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

Pour envoyer votre requête, développez l'une des options suivantes :

Vous devriez recevoir une réponse JSON de ce type :

{}

Précédent
Utiliser l'API Budget pour les budgets "alertes uniquement"