Utiliser l'API Cloud Billing Budget

Découvrez comment envoyer des requêtes simples à l'API Cloud Billing Budget.

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

Avant de commencer

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

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

Identifier votre ID de compte de facturation Cloud

Pour chaque appel de l'API Cloud Billing Budget, vous aurez besoin de votre ID de compte de facturation.

Accédez à la page Manage billing accounts (Gérer les comptes de facturation) de Google Cloud Console.
À partir de l'onglet My billing accounts (Mes comptes de facturation), vous trouverez la liste des comptes de facturation Cloud par nom et par ID. Recherchez le paramètre Billing account ID (ID du compte de facturation) associé au compte pour lequel vous gérez les budgets.

Capture d'écran de la page Manage billing accounts (Gérer les comptes de facturation) indiquant l'emplacement de l'ID de compte de facturation.

Concepts clés liés au budget

Un budget peut être appliqué à l'ensemble d'un compte de facturation ou limité (filtré) en vue de surveiller des tranches de coûts spécifiques.
Un budget appliqué à l'ensemble d'un compte de facturation Cloud inclut les coûts de tous les projets Google Cloud payés par ce compte de facturation.
Si vous disposez d'un accès limité ou inexistant au compte de facturation Cloud, vous pouvez créer des budgets à un seul projet pour les projets dont vous êtes propriétaire. Si vous êtes un utilisateur de compte de facturation Cloud, vous pouvez créer des budgets à un seul projet, qui ne peuvent pas être modifiés par les utilisateurs au niveau du projet à l'aide du champ suivant OwnershipScope du budget.
Vous pouvez affiner le champ d'application du budget à l'aide de filtres, tels qu'un sous-ensemble d'organisations, de dossiers, de projets, de services et d'autres filtres budgétaires applicables à votre compte de facturation Cloud.
Vous pouvez spécifier la période du budget. Par défaut, un budget surveille les coûts encourus au cours d'un mois calendaire. En utilisant le filtre usage_period disponible dans l'API Cloud Billing Budget, vous pouvez configurer la période budgétaire sur CalendarPeriod ou CustomPeriod, vous permettant de créer des budgets pour surveiller les périodes au-delà du mois calendaire par défaut, par exemple un trimestre, un an ou une plage de dates personnalisée que vous spécifiez.
Vous pouvez définir le montant du budget sur un total que vous spécifiez, ou baser le budget sur les dépenses de la période calendaire précédente.
Vous pouvez définir des règles de seuils budgétaires pour déclencher des notifications d'alerte par e-mail. Lorsque vos coûts (réels ou prévisionnels) dépassent un pourcentage de votre budget (en fonction des règles que vous avez définies), des e-mails d'alerte sont envoyés aux destinataires que vous spécifiez.
Vous pouvez définir les règles de notification du budget, spécifier les destinataires des e-mails d'alertes budgétaires et activer l'option programmatique notifications via Pub/Sub.
Vous pouvez utiliser des sujets Pub/Sub pour les notifications automatisées (par exemple, pour transférer vos messages budgétaires vers d'autres plates-formes telles que Slack, ou pour automatiser les tâches de gestion des coûts).

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 des requêtes simples à l'API Cloud Billing Budget.

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.
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 :

curl (Linux, macOS ou Cloud Shell)

Remarque : La commande suivante suppose que vous êtes connecté à la CLI gcloud avec votre compte utilisateur en exécutant la commande gcloud init ou gcloud auth login, ou en utilisant Cloud Shell, qui vous connecte automatiquement à la CLI gcloud. Vous pouvez exécuter gcloud auth list pour vérifier le compte actuellement actif.

Exécutez la commande suivante :

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"

PowerShell (Windows)

Remarque : La commande suivante suppose que vous vous êtes connecté à la CLI gcloud avec votre compte utilisateur en exécutant la commande gcloud init ou gcloud auth login. Vous pouvez exécuter gcloud auth list pour vérifier le compte actuellement actif.

Exécutez la commande suivante :

$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

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

{
  "budgets": [
   {
      "name": "billingAccounts/000000-111111-222222/budgets/33333333-4444-5555-6666-777777777777",
      "displayName": "Forecasted spend budget with Service Filter",
      "budgetFilter": {
        "projects": [
          "projects/123456789"
        ],
        "services": [
          "services/A1E8-BE35-7EBC"
        ],
        "creditTypesTreatment": "EXCLUDE_ALL_CREDITS",
        "calendarPeriod": "MONTH"
      },
      "amount": {
        "lastPeriodAmount": {}
      },
      "thresholdRules": [
        {
          "thresholdPercent": 0.9,
          "spendBasis": "FORECASTED_SPEND"
        }
      ],
      "allUpdatesRule": {},
      "etag": "c9d6c011f6fa6b5c"
    }
  ]
}

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.
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 :

curl (Linux, macOS ou Cloud Shell)

Exécutez la commande suivante :

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"

PowerShell (Windows)

Exécutez la commande suivante :

$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

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

{
  "name": "billingAccounts/000000-111111-222222/budgets/33333333-4444-5555-6666-777777777777",
  "displayName": "Forecasted spend budget with Service Filter",
  "budgetFilter": {
    "projects": [
      "projects/123456789"
    ],
    "services": [
      "services/A1E8-BE35-7EBC"
    ],
    "creditTypesTreatment": "EXCLUDE_ALL_CREDITS",
    "calendarPeriod": "MONTH"
  },
  "amount": {
    "lastPeriodAmount": {}
  },
  "thresholdRules": [
    {
      "thresholdPercent": 0.9,
      "spendBasis": "FORECASTED_SPEND"
    }
  ],
  "allUpdatesRule": {},
  "etag": "c9d6c011f6fa6b5c"
}

Créer un budget

Cette méthode API permet d'appliquer un budget Cloud Billing au compte de facturation Cloud spécifié.

REST

Cet exemple montre comment créer un budget pour un compte de facturation Cloud donné qui est limité (filtré) en fonction d'un projet Google Cloud que vous spécifiez et définissez pour une période calendaire d'un trimestre.

Avant d'utiliser les données de requête ci-dessous, 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).
billing-account-id : numéro du compte de facturation Cloud auquel ce budget s'applique.
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": "Keep my spending down",
  "budgetFilter": {
    "projects": [
      "projects/budget-scope-project-id"
    ],
    "calendar_period": "QUARTER"
  },
  "amount": {
    "lastPeriodAmount": {}
  },
  "thresholdRules": {
    "thresholdPercent": 0.8,
    "spendBasis": "CURRENT_SPEND"
  }
}

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

curl (Linux, macOS ou Cloud Shell)

Enregistrez le corps de la requête dans un fichier nommé request.json, puis exécutez la commande suivante :

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"

PowerShell (Windows)

Enregistrez le corps de la requête dans un fichier nommé request.json, puis exécutez la commande suivante :

$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

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

{
  "name": "billingAccounts/000000-111111-222222/budgets/33333333-4444-5555-6666-777777777777",
  "displayName": "Keep my spending down",
  "budgetFilter": {
    "projects": [
      "projects/123456789"
    ],
    "creditTypesTreatment": "INCLUDE_ALL_CREDITS",
    "calendar_period": "QUARTER"
  },
  "amount": {
    "lastPeriodAmount": {}
  },
  "thresholdRules": {
    "thresholdPercent": 0.8,
    "spendBasis": "CURRENT_SPEND"
  },
  "allUpdatesRule": {},
  "etag": "f7928d8010160668"
}

Mettre à jour un budget

Cette méthode API permet de modifier un budget Cloud Billing existant afin de modifier le montant du budget, ainsi que les filtres de budget (champ d'application du budget), la période du budget ou les règles de seuil.

REST

Cet exemple montre comment mettre à jour un budget existant pour définir un champ d'application (filtre) en fonction d'un projet Google Cloud que vous spécifiez, et pour mettre à jour la période du budget à partir d'un mois à un budget trimestriel.

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

projects/budget-scope-project-id : projet Google Cloud que vous souhaitez définir en tant que champ d'application du budget (budgetFilter).
billing-account-id : numéro du compte de facturation Cloud auquel ce budget s'applique.
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

Corps JSON de la requête :

{
  "budget": {
    "displayName": "My fancy budget",
    "budgetFilter": {
      "projects": [
        "projects/budget-scope-project-id"
      ],
      "calendar_period": "QUARTER"
    },
   "amount": {
      "specifiedAmount": {
        "units": 500
      }
    },
    "thresholdRules": {
      "thresholdPercent": 0.8,
      "spendBasis": "CURRENT_SPEND"
    }
  }
}

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

curl (Linux, macOS ou Cloud Shell)

Enregistrez le corps de la requête dans un fichier nommé request.json, puis exécutez la commande suivante :

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"

PowerShell (Windows)

Enregistrez le corps de la requête dans un fichier nommé request.json, puis exécutez la commande suivante :

$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" | Select-Object -Expand Content

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

{
  "name": "billingAccounts/000000-111111-222222/budgets/33333333-4444-5555-6666-777777777777",
  "displayName": "My fancy budget",
  "budgetFilter": {
    "projects": [
      "projects/123456789"
    ],
    "creditTypesTreatment": "INCLUDE_ALL_CREDITS",
    "calendar_period": "QUARTER"
  },
  "amount": {
    "specifiedAmount": {
      "units": 500
    }
  },
  "thresholdRules": {
    "thresholdPercent": 0.8,
    "spendBasis": "CURRENT_SPEND"
  },
  "allUpdatesRule": {},
  "etag": "f7928d8010160668"
}

Supprimer un budget

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

REST

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 :

curl (Linux, macOS ou Cloud Shell)

Exécutez la commande suivante :

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"

PowerShell (Windows)

Exécutez la commande suivante :

$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

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

{}

Prérequis