Utilizzo dell'API Cloud Billing Budget per i budget con limite di spesa

Scopri come inviare alcune richieste di budget con limite di spesa all'API Cloud Billing Budget.

Per un elenco completo dei metodi, consulta la documentazione di riferimento dell'API REST.

Prima di iniziare

Prima di leggere questa guida, devi:

  1. Leggi la panoramica dell'API Cloud Billing Budget.
  2. Leggi i prerequisiti dell'API Cloud Billing Budget.
  3. Esegui la procedura di configurazione.

Identificare l'ID account di fatturazione Cloud

Per ogni chiamata all'API Cloud Billing Budget, devi disporre dell'ID account di fatturazione Cloud. I budget con limite di spesa sono limitati ai clienti proprietari Google Cloud e agli account di fatturazione Cloud. Gli account di fatturazione rivenditore non rientrano nell'ambito di questa verifica.

  1. Vai alla Google Cloud pagina Gestisci account di fatturazione della console.
  2. Nella scheda I tuoi account di fatturazione, visualizzi l'elenco degli account di fatturazione Cloud per nome e ID. Individua il valore dell'ID account per l'account in cui gestisci i budget.

La pagina Gestisci fatturazione che mostra la posizione dell'ID account di fatturazione.

Concetti chiave e limitazioni del budget con limite di spesa

I budget con limite di spesa utilizzano i costi lordi stimati per attivare gli avvisi e applicare i limiti di spesa, bloccando l'utilizzo e l'accumulo di costi fino a quando il limite di spesa non viene rimosso.

Limitazioni dei campi del budget con limite di spesa

Quando spendCap è impostato su un budget, si applicano limitazioni rigide ai campi del budget. Visualizza i commenti a livello di campo su Filters, BudgetAmount, ThresholdRule, NotificationsRule, e OwnershipScope.

  • billing-account-id: i budget con limite di spesa sono limitati ai clienti Google Cloud proprietari e agli account di fatturazione Cloud. Gli account di fatturazione del rivenditore non rientrano nell'ambito.

  • BudgetFilters deve includere i seguenti parametri:

    • Un budget con limite di spesa è limitato ai budget con ambito (filtrati) a un singolo Google Cloud progetto e a un singolo servizio idoneo.
    • L'intervallo di tempo del periodo di budget per un budget con limite di spesa è limitato a un CalendarPeriod di un MONTH.
    • I calcoli dei costi per i limiti di spesa si basano sui costi lordi e non includono risparmi e crediti. Devi impostare creditTypesTreatment su EXCLUDE_ALL_CREDITS.
    • Altri filtri del budget non sono supportati per i limiti di spesa e devono essere vuoti, inclusi resourceAncestors, credit_types, subaccounts e labels.

  • BudgetAmount deve utilizzare un specifiedAmount. Nell'input, currencyCode è facoltativo. Se specificato durante la creazione di un budget, il codice valuta deve corrispondere alla valuta dell'account di fatturazione Cloud. currencyCode viene fornito nell'output.

  • ThresholdRules deve contenere esattamente tre regole con valori thresholdPercent di 0.5, 0.8 e 1.0 (50%, 80% e 100%), con un spendBasis impostato su CURRENT_SPEND o BASIS_UNSPECIFIED (FORECASTED_SPEND non è supportato per i limiti di spesa).

  • NotificationsRule deve impostare enableProjectLevelRecipients su true. Tutti gli altri parametri NotificationsRule non sono supportati.

  • OwnershipScope deve essere impostato su OWNERSHIP_SCOPE_UNSPECIFIED o ALL_USERS (BILLING_ACCOUNT non è supportato per i limiti di spesa).

  • Quando crei un budget con limite di spesa, il parametro inputState deve essere impostato su CONFIGURED.

Come funzionano i budget con limite di spesa per aiutarti a controllare la spesa

  • Calcoli della spesa più rapidi utilizzando i costi stimati: per un'applicazione più rapida di un importo del limite di spesa, i budget del limite di spesa utilizzano costi lordi stimati per attivare gli avvisi e applicare il limite di spesa. I costi stimati vengono calcolati in base al prezzo di listino dei servizi e non includono risparmi e crediti.

  • Messa in pausa automatica dell'utilizzo e dell'accumulo dei costi quando viene attivato il limite di spesa: Nel progetto specificato, quando i costi di utilizzo lordi stimati per il servizio specifico superano l'importo target del budget, il limite di spesa viene attivato e applicato per il resto del periodo di budget. Nel budget, il parametro outputState è impostato su ENFORCED. Mentre è in vigore un limite di spesa, si applica quanto segue:

    • Tutto l'utilizzo nuovo per il servizio specifico nel progetto specificato viene messo in pausa, incluso l'utilizzo on demand, con pagamento a consumo e l'utilizzo coperto da impegni come gli sconti per impegno di utilizzo (CUD) e il throughput riservato.
    • Tutte le richieste in volo del servizio specificato vengono elaborate fino al completamento, con l'addebito delle tariffe applicabili.
    • I limiti di spesa non mettono in pausa l'utilizzo fisso in corso associato a risorse persistenti (come i servizi di calcolo e di archiviazione), che rimangono attive e continuano ad accumulare addebiti.
    • Importante: quando è in stato di applicazione, non puoi modificare le impostazioni di un budget con limite di spesa o eliminare il budget. Prima di modificare o eliminare un budget forzato, devi prima rimuovere manualmente il limite di spesa.

  • Rimuovere un limite di spesa applicato per ripristinare i servizi e la spesa: quando viene applicato un limite di spesa, l'utilizzo del servizio specifico nel progetto specificato viene bloccato finché il limite di spesa non viene rimosso. Puoi rimuovere un limite di spesa nei seguenti modi:

    • Rimozione automatica di un limite di spesa: un limite di spesa imposto viene rimosso automaticamente all'inizio del periodo di budget successivo (in genere il primo giorno del mese successivo). Quando un limite di spesa viene rimosso automaticamente, l'importo della spesa del budget viene reimpostato su zero, lo stato del limite di spesa viene reimpostato su CONFIGURED e i servizi specificati vengono sbloccati, ripristinando la normale funzionalità delle chiamate API.

    • Rimozione manuale di un limite di spesa: se devi annullare un blocco dell'utilizzo durante lo stesso periodo di budget in cui viene applicato il limite di spesa, puoi modificare il budget per rimuovere manualmente il limite di spesa. La rimozione manuale di un limite di spesa ha i seguenti risultati:

      • L'aumento manuale di un limite di spesa ripristina il normale funzionamento delle chiamate API.
      • Se rimuovi manualmente il limite di spesa impostando lo stato del limite di spesa su AWAITING_NEXT_PERIOD, il limite di spesa non verrà riattivato per il resto del periodo di budget, a meno che tu non modifiche successivamente il budget per aumentare l'importo del limite di spesa e impostare inputState su CONFIGURED.

    Dopo la rimozione di un limite di spesa, potrebbe essere necessaria fino a un'ora prima che i servizi riprendano completamente a funzionare normalmente.

  • Reimpostazione automatica dei budget con limite di spesa: all'inizio del periodo di budget successivo (in genere il primo giorno del mese successivo), tutti i budget con limite di spesa vengono reimpostati automaticamente, impostando l'importo della spesa lorda stimata su zero e lo stato del limite di spesa su CONFIGURED.

Limitazione della quota: ogni account di fatturazione Cloud può avere diverse migliaia di budget associati contemporaneamente. Consulta la sezione Quote e limiti per i limiti attuali e ulteriori informazioni.

Chiamare l'API

Gli esempi seguenti mostrano come inviare alcune richieste all'API Budget di fatturazione Cloud per gestire i budget con limite di spesa.

Creare un budget con limite di spesa

Questo metodo API crea un budget con limite di spesa per la fatturazione Cloud applicato a un singolo progetto e a un servizio idoneo.

REST

Questo esempio mostra come creare un budget con limite di spesa per l'utilizzo del servizio API Gemini in un progetto specifico. Il budget è limitato (filtrato) a un singolo Google Cloud progetto specificato, a un singolo servizio idoneo e impostato su un importo del budget mensile di 100 $.

Prima di utilizzare i dati della richiesta, apporta le sostituzioni seguenti:

  • projects/budget-scope-project-id: l' Google Cloud ID progetto che vuoi impostare come ambito del budget (budgetFilter).
  • services/eligible-service_id: uno degli ID servizio idonei che vuoi impostare come ambito del budget (budgetFilter). Nell'esempio, utilizziamo l'ID servizio AEFD-7695-64FA per il servizio API Gemini.
  • billing-account-id: l'ID dell'account di fatturazione Cloud a cui si applica questo budget. I budget con limite di spesa sono limitati ai clienti proprietari Google Cloud e agli account di fatturazione Cloud. Gli account di fatturazione rivenditore non rientrano nell'ambito.
  • api-user-project-id: Il progetto Google Cloud in cui è abilitata l'API Cloud Billing Budget.

Metodo HTTP e URL: 

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

Corpo JSON della richiesta: 

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

Per inviare la richiesta, espandi una di queste opzioni:

Dovresti ricevere una risposta JSON simile alla seguente:

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

Rimuovere un limite di spesa utilizzando PATCH

Utilizza il metodo API PATCH per modificare un budget con limite di spesa per la fatturazione Cloud esistente e aumentare manualmente un limite di spesa applicato.

REST

Questo esempio mostra come aumentare manualmente un limite di spesa ENFORCED per un budget esistente aggiornando il parametro SpendCap.inputState a AWAITING_NEXT_PERIOD.

Importante:quando spend_cap.output_state è ENFORCED, devi prima aumentare il limite di spesa inviando una richiesta UpdateBudget per modificare spend_cap.input_state, ad esempio impostando input_state su AWAITING_NEXT_PERIOD, in modo da aumentare il limite. Se tenti di modificare qualsiasi altro campo del budget mentre il budget è in uno stato forzato, la richiesta di aggiornamento non andrà a buon fine e verrà visualizzato FAILED_PRECONDITION.

Per chiamare questo metodo, devi disporre di budget-id del budget che vuoi aggiornare. Puoi ottenere l'ID budget dall'output createBudget quando crei il budget o dall'output listBudgets se elenchi tutti i budget.

Prima di utilizzare i dati della richiesta, apporta le sostituzioni seguenti:

  • billing-account-id: l'ID dell'account di fatturazione Cloud a cui si applica questo budget. I budget con limite di spesa sono limitati ai clienti proprietari Google Cloud e agli account di fatturazione Cloud. Gli account di fatturazione rivenditore non rientrano nell'ambito.
  • budget-id: L'ID del budget che vuoi aggiornare.
  • api-user-project-id: il progetto Google Cloud in cui è abilitata l'API Budget di fatturazione Cloud.

Metodo HTTP e URL: 

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

Corpo JSON della richiesta: 

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

Per inviare la richiesta, espandi una di queste opzioni:

Dovresti ricevere una risposta JSON simile alla seguente:

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

Aggiornare un budget con limite di spesa utilizzando PATCH

Utilizza questo metodo API per modificare un budget con limite di spesa per la fatturazione Cloud esistente per cambiare l'importo del budget e i filtri del budget (ambito del budget).

REST

Questo esempio mostra come aggiornare un budget con limite di spesa esistente per modificare l'importo del budget. Se lo stato del limite di spesa è AWAITING_NEXT_PERIOD, questo esempio mostra anche come reimpostare un limite di spesa aumentato aggiornando il parametro SpendCap.inputState a CONFIGURED.

Per chiamare questo metodo, devi disporre di budget-id del budget che vuoi aggiornare. Puoi ottenere l'ID budget dall'output createBudget quando crei il budget o dall'output listBudgets se elenchi tutti i budget.

Prima di utilizzare i dati della richiesta, apporta le sostituzioni seguenti:

  • projects/budget-scope-project-id: l'ID progetto Google Cloud che vuoi impostare come ambito del budget (budgetFilter).
  • services/eligible-service_id: uno degli ID servizio idonei che vuoi impostare come ambito del budget (budgetFilter). Nell'esempio, utilizziamo l'ID servizio AEFD-7695-64FA per il servizio API Gemini.
  • billing-account-id: l'ID dell'account di fatturazione Cloud a cui si applica questo budget. I budget con limite di spesa sono limitati ai clienti proprietari Google Cloud e agli account di fatturazione Cloud. Gli account di fatturazione rivenditore non rientrano nell'ambito.
  • budget-id: L'ID del budget che vuoi aggiornare.
  • api-user-project-id: il progetto Google Cloud in cui è abilitata l'API Budget di fatturazione Cloud.

Metodo HTTP e URL: 

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

Corpo JSON della richiesta: 

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

Per inviare la richiesta, espandi una di queste opzioni:

Dovresti ricevere una risposta JSON simile alla seguente:

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

Elenco budget

Questo metodo API elenca tutti i budget disponibili per un determinato account di fatturazione Cloud.

REST

Prima di utilizzare i dati della richiesta, apporta le sostituzioni seguenti:

  • billing-account-id: l'ID dell'account di fatturazione Cloud a cui si applicano i budget. I budget con limite di spesa sono limitati ai clienti proprietari Google Cloud e agli account di fatturazione Cloud. Gli account di fatturazione rivenditore non rientrano nell'ambito.
  • project-id: il progetto Google Cloud in cui è abilitata l'API Cloud Billing Budget.

Metodo HTTP e URL: 

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

Per inviare la richiesta, espandi una di queste opzioni:

Dovresti ricevere una risposta JSON simile alla seguente:

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

Ottieni budget

Questo metodo API recupera i dettagli di un budget specifico.

REST

Per chiamare questo metodo, devi disporre di budget-id del budget che vuoi aggiornare. Puoi ottenere l'ID budget dall'output createBudget quando crei il budget o dall'output listBudgets se elenchi tutti i budget.

Prima di utilizzare i dati della richiesta, apporta le sostituzioni seguenti:

  • billing-account-id: l'ID dell'account di fatturazione Cloud a cui si applica questo budget. I budget con limite di spesa sono limitati ai clienti proprietari Google Cloud e agli account di fatturazione Cloud. Gli account di fatturazione rivenditore non rientrano nell'ambito.
  • budget-id: l'ID del budget che vuoi ottenere.
  • project-id: il progetto Google Cloud in cui è abilitata l'API Cloud Billing Budget.

Metodo HTTP e URL: 

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

Per inviare la richiesta, espandi una di queste opzioni:

Dovresti ricevere una risposta JSON simile alla seguente:

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

Eliminare un budget

Utilizza questo metodo API per eliminare un budget di fatturazione Cloud esistente.

REST

Per chiamare questo metodo, devi disporre di budget-id del budget che vuoi aggiornare. Puoi ottenere l'ID budget dall'output createBudget quando crei il budget o dall'output listBudgets se elenchi tutti i budget.

Prima di utilizzare i dati della richiesta, apporta le sostituzioni seguenti:

  • billing-account-id: l'ID dell'account di fatturazione Cloud a cui si applica questo budget.
  • budget-id: l'ID del budget che vuoi eliminare.
  • project-id: il progetto Google Cloud in cui è abilitata l'API Cloud Billing Budget.

Metodo HTTP e URL: 

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

Per inviare la richiesta, espandi una di queste opzioni:

Dovresti ricevere una risposta JSON simile alla seguente:

{}

Indietro
Utilizzo dell'API Budget per i budget solo avvisi