Configurar notificações programáticas

Neste documento, explicamos como configurar notificações programáticas de orçamento e anomalia de custo (pré-lançamento) usando o Pub/Sub.

Orçamentos e anomalias de custo normalmente 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 uma 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áticas, você precisa de 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 para envolvidos no 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 para conectá-lo a um tópico existente do Pub/Sub, 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 Cloud Billing IAM na sua conta do Cloud Billing:

Peça ao administrador para conceder 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 Cloud Billing IAM no projeto:

Peça ao administrador para conceder 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 programáticas de anomalias, você precisa de permissões para criar ou modificar anomalias e tópicos do Pub/Sub. Você precisa ter permissões de conta do Cloud Billing.

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

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

  • billing.accounts.get na conta do Cloud Billing.
  • billing.accounts.getIamPolicy na conta do Cloud Billing.
  • billing.anomalies.get na conta do Cloud Billing.
  • billing.anomalies.list na conta do Cloud Billing.
  • pubsub.topics.setIamPolicy no projeto de destino que contém os tópicos do Pub/Sub que você quer usar.
  • pubsub.topics.list no projeto de destino que contém os tópicos do Pub/Sub que você quer usar.
  • pubsub.subscriptions.consume no projeto de destino (ou na assinatura) que contém as assinaturas do Pub/Sub que você quer usar.

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:

Peça ao administrador para conceder 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 programáticas de orçamento ou anomalia, primeiro é necessário criar um tópico do Pub/Sub. Se você já configurou um tópico do Pub/Sub para orçamentos ou anomalias de custo, pule esta etapa.

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

    Faça login no Pub/Sub do console do Google Cloud

  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 que você use 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 as notificações programáticas recebam mensagens do Pub/Sub com o status atual do orçamento ou da anomalia, conecte o orçamento ou a 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 para envolvidos no projeto (Prévia)

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

    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 atual ou clique em Criar um tópico.
    • Se você estiver criando um novo tópico, no campo ID do tópico, forneça um nome de tópico e clique em Criar tópico.
    • Depois de criar o tópico, ele será selecionado automaticamente.
  7. Clique em Salvar.

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

    Abrir o console do Google Cloud
  2. Selecione o projeto em que você quer gerenciar os orçamentos.
  3. Acesse a seção Faturamento: abra o menu de navegação do console do Google Cloud 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 visualizar a conta de faturamento que está 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 atual ou clique em Criar um tópico.
    • Se você estiver criando um novo tópico, no campo ID do tópico, forneça um nome de 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 .

    Anomalias abertas

  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 que aparece, 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 trocar o projeto que você está visualizando para encontrar o tópico que quer selecionar.
    • Se quiser criar um novo tópico, mude para o projeto preferido 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 do Cloud Billing que é proprietária do orçamento.
budgetId de72f49d-779b-4945-a127-4d6ce8def0bb O identificador do alerta de orçamento na conta do Cloud Billing.
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 por humanos 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": custos totais incorridos durante o último mês.
  • "LAST_PERIODS_COST": os custos incorridos durante o último período civil 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 estará presente se o custo real não exceder nenhum 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 Cloud Billing 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
scope 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 anomalia 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 com o recurso.
deviationAmount 31.01 A diferença entre o gasto real e o esperado.
deviationPercentage 18.77 A porcentagem 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.

Entrega de notificações ao Pub/Sub

Depois de conectar seu orçamento ou anomalia a um tópico do Pub/Sub, você 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 frequência é diferente da frequê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 só oferece 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 uma configuração incorreta 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 só 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 à configuração incorreta do tópico do Pub/Sub, você não será notificado.

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, confira os exemplos a seguir de respostas programáticas de controle de custos: