Configurar notificações programáticas

Este documento explica como configurar notificações de orçamento programático e anomalia de custo (pré-lançamento) usando o Pub/Sub.

Os orçamentos e as anomalias de custo geralmente são configurados para enviar notificações por e-mail. Se você usa orçamentos ou a detecção de anomalias de custo como uma ferramenta de controle de custos, as notificações por e-mail podem não ser o melhor método para garantir a ação imediata de controle dos custos. É possível configurar e usar notificações programáticas para automatizar as respostas de controle de custos. Exemplos de respostas automatizadas de controle de custos incluem:

Limitações

Permissões exigidas para a tarefa

Notificações de orçamento

Para configurar notificações de orçamento programático, você precisa ter permissões para criar ou modificar orçamentos e tópicos do Pub/Sub. Você precisa de um conjunto diferente de permissões, dependendo do seu nível de acesso.

Usuários com permissões na conta do Cloud Billing Apenas usuários com permissões no nível do projeto (Prévia)

Se a organização usa papéis personalizados para autenticação, você precisa das seguintes permissões:

Para que papéis personalizados modifiquem um orçamento existente do Cloud Billing e o conectem a um tópico existente do Pub/Sub, é necessário ter as seguintes permissões:

Para receber as permissões necessárias usando funções predefinidas, peça ao administrador para conceder a você uma das seguintes funções predefinidas do IAM do Cloud Billing na sua conta do Cloud Billing:

E peça ao administrador que conceda a você o seguinte papel no projeto de destino que contém os tópicos do Pub/Sub:

Se a organização usa papéis personalizados para autenticação, você precisa das seguintes permissões:

Para receber as permissões necessárias usando papéis predefinidos, peça ao administrador para conceder a você um dos seguintes papéis predefinidos do IAM do Cloud Billing no projeto:

E peça ao administrador que conceda a você o seguinte papel no projeto de destino que contém os tópicos do Pub/Sub:

Notificações de anomalias

Para configurar notificações de anomalias programáticas, você precisa ter permissões para criar ou modificar anomalias e tópicos do Pub/Sub. Você precisa ter permissões na conta do Cloud Billing.

Usuários com permissões na conta do Cloud Billing (pré-lançamento)

Para receber as permissões necessárias usando papéis predefinidos, peça ao administrador para conceder a você um dos seguintes papéis predefinidos do IAM do Cloud Billing na sua conta do Cloud Billing:

E peça ao administrador que conceda a você o seguinte papel no projeto de destino que contém os tópicos do Pub/Sub:

Criar um tópico do Pub/Sub

Para configurar notificações de orçamento programático ou anomalias, primeiro você precisa criar um tópico do Pub/Sub. Se você já tiver configurado um tópico do Pub/Sub para orçamentos ou anomalias de custo, pule esta etapa.

  1. Acesse a página Google Cloud Pub/Sub do console.

    Faça login no Google Cloud console Pub/Sub

  2. Selecione um projeto para conter o tópico do Pub/Sub.

    Ao configurar tópicos do Pub/Sub para notificações de faturamento, recomendamos usar um projeto de administração de FinOps para conter os tópicos do Pub/Sub relacionados ao faturamento.

  3. Clique em Criar tópico.

  4. No campo ID do tópico, forneça um nome para o tópico.

  5. Mantenha as configurações padrão de assinatura e criptografia e clique em Criar.

Conectar seu tópico do Pub/Sub

Para permitir que notificações programáticas recebam mensagens do Pub/Sub com o status atual do seu orçamento ou anomalia, conecte seu orçamento ou anomalia ao tópico do Pub/Sub.

Notificações de orçamento

Para conectar um tópico do Pub/Sub a um orçamento do Cloud Billing, siga estas etapas:

Usuários com permissões na conta do Cloud Billing Apenas usuários com permissões no nível do projeto (Prévia)

  1. Faça login na página Orçamentos e alertas no Google Cloud console.

    Abrir orçamentos e alertas
  2. No prompt, escolha a conta do Cloud Billing em que você quer gerenciar os orçamentos.

    A página Orçamentos e alertas é aberta para a conta de faturamento selecionada.

  3. Selecione o orçamento que você quer conectar ou crie um novo.
  4. Na seção Ações, em Gerenciar notificações, selecione Conectar um tópico do Pub/Sub a este orçamento.
  5. No campo Projeto, clique em Selecionar um projeto e escolha o projeto que contém os tópicos do Pub/Sub que você configurou.
  6. Em Selecionar um tópico do Pub/Sub, escolha um tópico existente ou crie um novo clicando em Criar um tópico.
    • Se você criar um novo tópico, no campo ID do tópico, forneça um nome para o tópico e clique em Criar tópico.
    • Depois de criar o tópico, ele é selecionado automaticamente.
  7. Clique em Salvar.

  1. Faça login no painel do Google Cloud console e selecione um projeto.

    Abrir o Google Cloud console
  2. Selecione o projeto em que você quer gerenciar os orçamentos.
  3. Navegue até a seção Faturamento: abra o Google Cloud console Menu de navegação e selecione Faturamento.

    Se for solicitado que você escolha a conta de faturamento que quer visualizar e gerenciar, clique em Ir para a conta de faturamento vinculada para conferir a conta de faturamento vinculada ao projeto selecionado.

    A página Visão geral do faturamento é aberta para a conta de faturamento selecionada.

  4. Na seção Gerenciamento de custos do menu de navegação Faturamento, selecione Orçamentos e alertas.
  5. Selecione o orçamento que você quer conectar ou crie um novo.
  6. Na seção Ações, em Gerenciar notificações, selecione Conectar um tópico do Pub/Sub a este orçamento.
  7. No campo Projeto, clique em Selecionar um projeto e escolha o projeto que contém os tópicos do Pub/Sub que você configurou.
  8. Em Selecionar um tópico do Pub/Sub, escolha um tópico existente ou crie um novo clicando em Criar um tópico.
    • Se você criar um novo tópico, no campo ID do tópico, forneça um nome para o tópico e clique em Criar tópico.
    • Depois de criado, o tópico será selecionado.
  9. Clique em Salvar.

Notificações de anomalias

Para conectar um tópico do Pub/Sub a uma anomalia de custo, siga estas etapas:

Usuários com permissões na conta do Cloud Billing (pré-lançamento)

  1. Faça login na página Anomalias no console do Google Cloud .

    Abrir anomalias

  2. No prompt, escolha a conta do Cloud Billing em que você quer gerenciar anomalias.

    A página Anomalias é aberta para a conta de faturamento selecionada.

  3. Clique em Gerenciar anomalias.
  4. Insira um valor de Limite de anomalia para Impacto de custo. Esse valor é o limite que aciona as notificações. Se você não fornecer um valor, o limite será definido como zero, e as notificações serão enviadas para todas as anomalias.
  5. Na seção Notificações do Pub/Sub, selecione Conectar um tópico do Pub/Sub para receber atualizações programáticas sobre anomalias.
  6. No menu suspenso exibido, selecione o tópico do Pub/Sub que você quer conectar para receber notificações.
    • Os tópicos são listados por projeto. Talvez seja necessário mudar o projeto que você está visualizando para encontrar o tópico que você quer selecionar.
    • Se você quiser criar um novo tópico, mude para o projeto de sua preferência antes de clicar em Criar um tópico.
  7. Clique em Salvar.

Formato da notificação

As notificações enviadas ao tópico do Pub/Sub são compostas de duas partes:

  • Atributos: um conjunto de pares de chave-valor com a descrição do evento.

  • Dados: uma string que contém um objeto JSON com a descrição dos detalhes do alerta de orçamento.

Notificações de orçamento

Atributos

Os atributos são pares de chave-valor incluídos em todas as notificações enviadas pelo Faturamento do Cloud para seu tópico do Pub/Sub. As notificações sempre contêm o seguinte conjunto de pares de chave-valor, independentemente da carga útil.

Nome do atributo Exemplo Descrição
billingAccountId 01D4EE-079462-DFD6EC O identificador da conta de faturamento do Cloud que detém o orçamento.
budgetId de72f49d-779b-4945-a127-4d6ce8def0bb O identificador do alerta de orçamento na conta de faturamento do Cloud.
schemaVersion 1.0 A versão do esquema de notificações.

Dados

Os detalhes do alerta de orçamento são retornados em uma string UTF-8 codificada em base64 que contém um objeto JSON com as seguintes propriedades:

Dados Exemplo Descrição
budgetDisplayName "My Personal Budget" O nome legível atribuído ao orçamento.
costAmount 140.321 O valor acumulado dos custos. O tipo de custo monitorado depende dos filtros e das configurações do orçamento.
costIntervalStart "2021-02-01T08:00:00Z" O início do período de alerta do orçamento. `costAmount` inclui os custos de uso a partir dessa data. Esse é o primeiro dia do período do orçamento (mês, trimestre, ano ou período personalizado) em que o uso do orçamento ocorreu.
budgetAmount 152.557 O valor alocado no orçamento.
budgetAmountType "SPECIFIED_AMOUNT" O tipo de valor do orçamento. Pode ser um dos seguintes valores:
  • "SPECIFIED_AMOUNT": um valor fixo.
  • "LAST_MONTH_COST": total de custos incorridos durante o último mês.
  • "LAST_PERIODS_COST": os custos incorridos durante o último período de calendário não mensal, como um trimestre ou um ano.
alertThresholdExceeded 0.9 O limite máximo de alertas de custo real configurado foi excedido. O valor está em formato decimal (por exemplo, 0,9 é 90%). Essa chave não está presente se o custo real não exceder um limite.
forecastThresholdExceeded 0.2 O alerta de limite máximo de custo previsto foi excedido. O valor é uma porcentagem em formato decimal (por exemplo, 0,2 é 20%). Essa chave não estará presente se o custo previsto não exceder nenhum limite.
currencyCode "USD" A moeda do alerta de orçamento. Todos os custos e valores orçamentários do alerta estão nessa moeda.

Notificações de anomalias

Atributos

Os atributos são pares de chave-valor contidos em todas as notificações enviadas pelo Faturamento do Cloud para seu tópico do Pub/Sub. As notificações sempre contêm o seguinte conjunto de pares de chave-valor, independentemente do payload da notificação.

Nome do atributo Exemplo Descrição
escopo scope_project O escopo da anomalia.
billingAccountName billingAccounts/01D4EE-079462-DFD6EC O identificador da conta do Cloud Billing em que a anomalia ocorreu.
resourceDisplayName My project O nome de exibição do recurso em que a anomalia ocorreu.
resourceName projects/123456 O identificador do recurso em que a anomalia ocorreu.
SchemaVersion 1.0 A versão do esquema do Pub/Sub.

Dados

Os detalhes do alerta de anormalidade são retornados em uma string UTF-8 codificada em base64 que contém um objeto JSON com as seguintes propriedades:

Dados Exemplo Descrição
anomalyName billingAccounts/01D4EE-079462-DFD6EC/anomalies/aaa O nome do recurso da anomalia.
billingAccountName billingAccounts/01D4EE-079462-DFD6EC O identificador da conta de faturamento.
resourceName "projects/12345" O identificador do recurso em que a anomalia ocorreu.
resourceDisplayName "My project" O nome de exibição do recurso em que a anomalia ocorreu.
detectionDate "2024-02-01T08:00:00Z" A data em que a anomalia de custo foi detectada.
Scope SCOPE_PROJECT Indica o escopo da anomalia.
expectedSpendAmount {
"currencyCode": "USD",
"units": "8",
"nanos": 988106832
}
 		O gasto esperado para o recurso.
actualSpendAmount 196.22 O gasto real do recurso.
deviationAmount 31.01 A diferença entre o gasto real e o esperado.
deviationPercentage 18.77 A porcentagem do valor de desvio do gasto esperado.
Root cause 
root_causes {
resource: "services/XXX-XXXX-XXX"
display_name: "BigQuery"
cause_type: CAUSE_TYPE_SERVICE
deviation {
  expected_spend {
    currency_code: "USD"
    units: "5000"
  }
  actual_spend {
    currency_code: "USD"
    units: "5000"
  }
  deviation_amount {
    currency_code: "USD"
    units: "5000"
  }
  deviation_percentage: "Infinity"
}
sub_causes {
  resource: "locations/us-west1",
  display_name: "us-west1",
  cause_type: CAUSE_TYPE_LOCATION,
  deviation {
    expected_spend {
      currency_code: "USD",
    }
    actual_spend {
      currency_code: "USD",
      units:"5000"
    }
    deviation_amount {
      currency_code: "USD",
      units: "5000"
    }
    deviation_percentage: "Infinity"
  }
  sub_causes {
    resource: "services/XXXX-XXXX-XXXX/skus/XXXX-XXXX-XXXX"
    display_name: "Some display name"
    cause_type: CAUSE_TYPE_SKU
    deviation {
      expected_spend {
        currency_code: "USD"
      }
      actual_spend {
        currency_code: "USD"
        units: 5000
      }
      deviation_amount {
        currency_code: "USD"
        units: 5000
      }
      deviation_percentage: "Infinity"
    }
  }
  sub_causes {
    resource: "services/XXXX-XXXX-XXXX/skus/XXXX-XXXX-XXXX"
    display_name: "Some display name"
    cause_type: CAUSE_TYPE_SKU
    deviation {
      expected_spend {
        currency_code: "USD"
        units: "1"
        nanos: 5413077
      }
      actual_spend {
        currency_code: "USD"
        units: "1",
        nanos: 122606000
      }
      deviation_amount {
        currency_code: "USD"
        nanos: 117192923
      }
      deviation_percentage:11.656196419841217
    }
  }
}
}
Um campo repetido que contém informações sobre a causa raiz da anomalia.

Garantias de entrega de notificações ao Pub/Sub

Depois de conectar seu orçamento ou anomalia a um tópico do Pub/Sub, você vai receber notificações programáticas da seguinte maneira:

Notificações de orçamento

  • As notificações de orçamento são enviadas ao tópico do Pub/Sub várias vezes por dia com o status atual do seu orçamento. Essa cadência é diferente da cadência dos e-mails de alerta de orçamento, que são enviados apenas quando um limite de orçamento é atingido.
  • As notificações de Pub/Sub são enviadas mesmo que a conta de faturamento do Cloud não tenha nenhum uso.
  • Pode levar várias horas para você receber a primeira notificação do Pub/Sub.
  • O Pub/Sub somente garante a entrega pelo menos uma vez. É possível receber uma mensagem várias vezes, e as mensagens podem chegar fora de ordem.
  • Se a entrega falhar devido a um erro de configuração do tópico do Pub/Sub, você não vai receber uma notificação.

Pode haver uma falha na entrega por um dos seguintes motivos:

Notificações de anomalias

  • As notificações de anomalia são enviadas ao tópico do Pub/Sub somente quando o limite é atingido.
  • O Pub/Sub garante apenas a entrega pelo menos uma vez. É possível receber uma mensagem várias vezes, e as mensagens podem chegar fora de ordem.
  • Se a entrega falhar devido a um erro de configuração do tópico do Pub/Sub, você não vai receber uma notificação.

Pode haver uma falha na entrega por um dos seguintes motivos:

Para mais informações, consulte Publicar e receber mensagens no Pub/Sub.

A seguir

Para saber mais sobre como usar notificações programáticas, consulte os seguintes exemplos de respostas de controle de custos programático: