Esta página foi traduzida pela API Cloud Translation.

Como usar a API Cloud Billing Budget

Saiba como enviar algumas solicitações simples para a API Cloud Billing Budget.

Para acessar uma lista completa de métodos, consulte a documentação de referência da API REST ou da API RPC.

Antes de começar

Faça o seguinte antes de ler este guia:

Leia a Visão geral da API Cloud Billing Budget.
Leia os Pré-requisitos da API Cloud Billing Budget.
Execute as etapas de configuração.

Identificar o ID da sua conta de faturamento do Cloud

Para todas as chamadas da API Cloud Billing Budget, você precisará do ID da sua conta de faturamento.

Acesse a página "Gerenciar contas de faturamento" do Console do Google Cloud.
Na guia Minhas contas de faturamento, você vê a lista de contas por nome e ID. Localize o ID da conta de faturamento em que você gerenciará os orçamentos.

Captura de tela da página "Gerenciar contas faturamento" com o local do ID da conta de faturamento.

Principais conceitos do orçamento

É possível aplicar um orçamento a uma conta de faturamento inteira ou com escopo (filtrado) usando filtros de orçamento granulares para monitorar partes específicas dos custos.
Um orçamento aplicado a uma Conta de faturamento do Cloud inteira inclui os custos de todos os projetos do Google Cloud pagos por ela.
Se você tiver acesso limitado ou nenhum acesso à conta do Cloud Billing, poderá criar orçamentos de projeto único para seus projetos. Se você é um usuário no nível da conta do Cloud Billing, é possível criar orçamentos de projeto único que não podem ser modificados por usuários no nível do projeto usando o OwnershipScope no orçamento.
É possível restringir o escopo do orçamento usando filtros aplicáveis à conta do Cloud Billing, como um subconjunto de organizações, pastas, projetos, serviços e outros filtros de orçamento.
É possível especificar o período do orçamento. Por padrão, um orçamento monitora os custos incorridos durante um mês. Usando o filtro usage_period disponível na API Cloud Billing Budget, é possível configurar o período de orçamento como um CalendarPeriod ou um CustomPeriod, permitindo criar orçamentos para monitorar períodos além do mês padrão, como um trimestre, um ano ou um período personalizado que você especificar.
É possível definir o valor do orçamento como um valor total especificado ou basear-se no gasto do período anterior.
Você pode definir regras de limite para acionar notificações de alerta por e-mail. Quando os custos (custos reais ou previstos) excederem uma porcentagem do orçamento (com base nas regras definidas), os e-mails de alerta serão enviados aos destinatários especificados.
É possível definir as regras de notificação do orçamento para definir os destinatários de e-mail dos alertas de orçamento e ativar a programação programática notificações usando o Pub/Sub.
É possível usar tópicos do Pub/Sub para notificações programáticas. Por exemplo, para encaminhar mensagens de orçamento para outras mídias, como Slack ou automatizar tarefas de gerenciamento de custos).

Limitação de cota: cada conta do Cloud Billing pode ter vários milhares de orçamentos associados a ela por vez. Consulte Cotas e limites para ver os limites atuais e outras informações.

Como chamar a API

Nos exemplos a seguir, mostramos como enviar algumas solicitações simples à API Cloud Billing Budget.

Listar orçamentos

Nesse método de API, todos os orçamentos definidos para uma determinada Conta de faturamento do Cloud são listados.

REST

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

billing-account-id: ID da conta de faturamento do Google Cloud a que os orçamentos são aplicados.
project-id: o projeto do Google Cloud em que a API Cloud Billing Budget está ativada.

Método HTTP e URL:

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

Para enviar a solicitação, expanda uma destas opções:

curl (Linux, macOS ou Cloud Shell)

Observação: o comando a seguir pressupõe que você fez login na CLI gcloud com sua conta de usuário executando gcloud init ou gcloud auth login, ou usando o Cloud Shell, que faz login automaticamente na CLI gcloud. . É possível verificar a conta ativa atual executando gcloud auth list.

execute o seguinte comando:

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)

Observação: o comando a seguir pressupõe que você fez login na CLI gcloud com sua conta de usuário executando gcloud init ou gcloud auth login . É possível verificar a conta ativa atual executando gcloud auth list.

execute o seguinte comando:

$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

Você receberá uma resposta JSON semelhante a esta:

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

Receber orçamento

Nesse método de API, receba os detalhes de um determinado orçamento.

REST

Para chamar esse método, você precisa do budget-id do orçamento que quer atualizar. Receba o ID do orçamento da saída createBudget, ao criar o orçamento, ou da saída listBudgets, se você listar todos os seus orçamentos.

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

billing-account-id: o ID da conta de faturamento do Google Cloud a que este orçamento é aplicado.
budget-id: o ID do orçamento que você quer receber.
project-id: o projeto do Google Cloud em que a API Cloud Billing Budget está ativada.

Método HTTP e URL:

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

Para enviar a solicitação, expanda uma destas opções:

curl (Linux, macOS ou Cloud Shell)

execute o seguinte comando:

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)

execute o seguinte comando:

$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

Você receberá uma resposta JSON semelhante a esta:

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

Criar orçamento

Nesse método de API, é criado um orçamento do Faturamento do Cloud aplicado à conta do Cloud Billing especificada.

REST

Nesta amostra, apresentamos como criar um orçamento para uma determinada conta de faturamento do Cloud que está com escopo (filtrada) por um projeto do Google Cloud que você especifica e define para um período de calendário de um trimestre.

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

projects/budget-scope-project-id: o ID do projeto do Google Cloud que você quer definir como um escopo de orçamento (budgetFilter).
billing-account-id: o ID da conta de faturamento do Google Cloud a que este orçamento é aplicado.
api-user-project-id: o projeto do Google Cloud em que a API Cloud Billing Budget está ativada.

Método HTTP e URL:

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

Corpo JSON da solicitação:

{
  "displayName": "Keep my spending down",
  "budgetFilter": {
    "projects": [
      "projects/budget-scope-project-id"
    ],
    "calendar_period": "QUARTER"
  },
  "amount": {
    "lastPeriodAmount": {}
  },
  "thresholdRules": {
    "thresholdPercent": 0.8,
    "spendBasis": "CURRENT_SPEND"
  }
}

Para enviar a solicitação, expanda uma destas opções:

curl (Linux, macOS ou Cloud Shell)

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir:

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)

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir:

$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

Você receberá uma resposta JSON semelhante a esta:

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

Atualizar orçamento

Use esse método de API para modificar um orçamento do Cloud Billing para alterar o valor de orçamento e os filtros de orçamento (Escopo do orçamento), período de orçamento ou regras de limite.

REST

Nesta amostra, apresentamos como atualizar um orçamento existente para definir um escopo (filtro) por um projeto do Google Cloud que você especifica e para atualizar o período do orçamento de um por mês orçamento para um orçamento trimestral .

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

projects/budget-scope-project-id: o projeto do Google Cloud que você quer definir como um escopo de orçamento (budgetFilter).
billing-account-id: o ID da conta de faturamento do Google Cloud a que este orçamento é aplicado.
budget-id: o ID do orçamento que você quer atualizar.
api-user-project-id: o projeto do Google Cloud em que a API Cloud Billing Budget está ativada.

Método HTTP e URL:

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

Corpo JSON da solicitação:

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

Para enviar a solicitação, expanda uma destas opções:

curl (Linux, macOS ou Cloud Shell)

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir:

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)

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir:

$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

Você receberá uma resposta JSON semelhante a esta:

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

Excluir orçamento

Use esse método de API para excluir um orçamento atual do Faturamento do Cloud.

REST

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

billing-account-id: o ID da conta de faturamento do Google Cloud a que este orçamento é aplicado.
budget-id: o ID do orçamento que você quer excluir.
project-id: o projeto do Google Cloud em que a API Cloud Billing Budget está ativada.

Método HTTP e URL:

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

Para enviar a solicitação, expanda uma destas opções:

curl (Linux, macOS ou Cloud Shell)

execute o seguinte comando:

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)

execute o seguinte comando:

$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

Você receberá uma resposta JSON semelhante a esta:

{}

Configuração