Como gerenciar contatos para notificações

Muitos serviços do Google Cloud, como o Cloud Billing, enviam notificações para compartilhar informações importantes com os usuários do Google Cloud. Por padrão, essas notificações são enviadas para membros com determinados papéis de gerenciamento de identidade e acesso (IAM). Com os contatos essenciais, você pode personalizar quem recebe notificações fornecendo sua própria lista de contatos.

Antes de começar

Ative a Essential Contacts API.

Ative a API

Permissões necessárias

As permissões necessárias para usar os contatos essenciais variam de acordo com o que você quer fazer.

Permissões para visualizar contatos

Para visualizar os contatos, é preciso ter um papel que inclui as seguintes permissões:

  • essentialcontacts.contacts.get
  • essentialcontacts.contacts.list

Para obter essas permissões seguindo o princípio do privilégio mínimo, peça ao administrador que conceda a você o papel de visualizador de contatos essenciais (roles/essentialContacts.viewer).

Como alternativa, o administrador pode conceder a você um papel diferente que inclua as permissões necessárias, como um papel personalizado ou um papel predefinido mais permissivo.

Certifique-se de conceder esses papéis no projeto, na pasta ou na organização a que o contato está atribuído.

Permissões para gerenciar contatos

Para editar, excluir e criar contatos, é preciso ter um papel que inclui as seguintes permissões:

  • essentialcontacts.contacts.get
  • essentialcontacts.contacts.list
  • essentialcontacts.contacts.create
  • essentialcontacts.contacts.delete
  • essentialcontacts.contacts.update

Para obter essas permissões seguindo o princípio do privilégio mínimo, peça ao administrador que conceda a você o papel de administrador de contatos essenciais (roles/essentialContacts.admin).

Como alternativa, o administrador pode conceder a você um papel diferente que inclua as permissões necessárias, como um papel personalizado ou um papel predefinido mais permissivo.

Certifique-se de conceder esses papéis no projeto, na pasta ou na organização a que o contato está atribuído.

Categorias de notificação

Há várias categorias diferentes de notificações que podem ser atribuídas a contatos. Se você não adicionar um contato para uma categoria, as notificações nessa categoria vão para o contato padrão, selecionado com base nos papéis do IAM dos membros. Recomendamos adicionar contatos personalizados. Não dependa dos contatos padrão para garantir que as pessoas certas recebam notificações sobre seu projeto, pasta ou organização.

Você pode adicionar pessoas e Grupos do Google como contatos. Para reduzir o impacto das alterações da equipe, recomendamos adicionar Grupos do Google como contatos e, depois, gerenciar a adesão a esses grupos para determinar quem recebe notificações. Essa prática ajuda a garantir que as notificações sejam sempre direcionadas aos funcionários ativos.

Consulte a tabela a seguir para saber mais sobre as categorias de notificações, o contato padrão e o contato recomendado. Use essas informações para selecionar os contatos apropriados para cada categoria.

Categoria Descrição Contato padrão Contato recomendado
Tudo Todas as notificações relacionadas ao recurso Nenhum Pessoas ou sistemas automatizados responsáveis por encaminhar ou registrar notificações.
Cobrança Notificações de faturamento e pagamento, atualizações de preço, erros, créditos Administrador da conta de faturamento (roles/billing.admin) Equipe de departamento financeiro e pessoas que gerenciam sua relação financeira com o Google, incluindo pessoas que gerenciam orçamentos, planejamento e contas relacionadas ao uso do Google Cloud
Jurídico Ações de restrição, conformidade regulatória, notificações do governo Administrador da conta de faturamento (roles/billing.admin) Conselho jurídico, gerentes de compliance, especialistas em relações governamentais e outros profissionais do gênero
Atualizações do produto Novas versões, atualizações dos termos de produtos, suspensões de uso Proprietário do projeto (roles/owner) Gerentes de produtos, arquitetos e engenheiros que podem se beneficiar de informações oportunas sobre mudanças em produtos e serviços do Google
Segurança Problemas de segurança/privacidade, notificações e vulnerabilidades Administrador da organização (roles/resourcemanager.organizationAdmin) Segurança de TI, as operações e de outras pessoas cuja função é proteger os dados da empresa e dos clientes e garantir a continuidade dos negócios
Suspensão Notificações relacionadas à suspensão imediata da conta Proprietário do projeto (roles/owner) Pessoas imediatamente responsáveis por manter a infraestrutura de TI e os aplicativos comerciais funcionando
Técnica Falhas, erros bugs e outros problemas técnicos Proprietário do projeto (roles/owner) Profissionais de TI, engenheiros de confiabilidade, administradores, listas de chamadas e outras pessoas que precisam saber dos problemas e eventos técnicos atuais e futuros que podem fazer com que seus recursos de TI funcionem incorretamente

Idiomas compatíveis

Nos contatos essenciais, cada contato tem a configuração de idioma preferencial. Os criadores de notificações podem fazer referência a essa configuração ao enviar notificações.

Quando você adiciona um contato, o Console do Cloud configura automaticamente o idioma preferido com base nas configurações de idioma preferido do criador desse contato. Ao adicionar um contato usando a API, você configura manualmente o idioma de preferência do contato usando um código de idioma. Esse código pode ser qualquer um dos idiomas compatíveis com os contatos essenciais.

Como decidir a quem atribuir contatos

Você pode atribuir contatos no nível do projeto, da pasta ou da organização.

Os contatos são herdados por meio da hierarquia de recursos do Google Cloud. Como resultado, se você adicionar um contato no nível da organização, eles receberão notificações sobre a organização e sobre todas as pastas e projetos na organização. Da mesma forma, se você adicionar um contato no nível da pasta, eles receberão notificações sobre a pasta e todos os projetos e pastas dentro dela.

O local a que você decide atribuir contatos depende da estrutura da organização. No entanto, geralmente recomendamos atribuir contatos nos seguintes níveis, com base na respectiva categoria de notificação:

Nível recomendado Categoria da notificação
Nível da organização
  • Cobrança
  • Jurídico
  • Segurança1
Nível de pasta/projeto
  • Tudo
  • Atualizações do produto
  • Segurança1
  • Suspensão
  • Técnica

1 O nível ao qual você deve atribuir contatos de segurança depende das práticas de segurança específicas da sua organização. Por exemplo, se os proprietários de projetos individuais forem responsáveis pela segurança dos próprios projetos, você atribuirá seus contatos de segurança no nível do projeto. No entanto, se um grupo abrangente da organização gerenciar a segurança de todos os projetos, será necessário atribuir os contatos de segurança no nível da organização.

Como listar contatos

Para listar todos os contatos do seu projeto, pasta ou organização, faça o seguinte:

Console

  1. No Console do Cloud, acesse a página Contatos essenciais.

    Acessar a página "Contatos essenciais"

  2. Certifique-se de que o nome do projeto, pasta ou organização apareça no seletor de projetos na parte superior da página. O seletor de projeto informa de qual projeto, pasta ou organização você está gerenciando contatos.

  3. Para listar os contatos por categoria, selecione Categoria. Para listar os contatos em ordem alfabética, selecione Contatos.

REST

Como listar contatos

Para visualizar os contatos que foram definidos em um projeto, pasta ou organização específica, use o método contacts.list da API Essential Contacts.

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

  • RESOURCE_TYPE: o tipo de recurso para o qual você quer listar os contatos. Use o valor projects, folders ou organizations.
  • RESOURCE_ID: seu projeto do Google Cloud, a organização ou o ID da pasta.
  • PAGE_SIZE: opcional. O número de contatos a serem incluídos na resposta. O valor padrão é 50, e o valor máximo é 100. Se o número de contatos for maior que o tamanho da página, a resposta conterá um token de paginação que pode ser usado para recuperar a próxima página de resultados.
  • NEXT_PAGE_TOKEN: opcional. O token de paginação retornado em uma resposta anterior usando esse método. Se especificada, a lista de contatos começa onde a resposta anterior foi finalizada.

Solicitação:

GET essentialcontacts.googleapis.com/v1alpha1/RESOURCE_TYPE/RESOURCE_ID/contacts?pageSize=PAGE_SIZE&pageToken=NEXT_PAGE_TOKEN

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

Você receberá uma resposta JSON semelhante a esta:

{
  "contacts": [
    {
      "name": "projects/my-projects/contacts/1",
      "email": "my-contact-1@my-domain.com",
      "notificationCategorySubscriptions": [
        "ALL"
      ],
      "languageTag": "en-US"
    },
    {
      "name": "projects/my-projects/contacts/2",
      "email": "my-contact-2@my-domain.com",
      "notificationCategorySubscriptions": [
        "BILLING"
      ],
      "languageTag": "en-US"
    }
  ]
}

Como listar contatos e contatos herdados

Os recursos filhos (pastas e projetos) herdam os contatos dos ancestrais (organizações e outras pastas). Se quiser listar todos os contatos e contatos herdados de um recurso, use o método contacts.compute da API Corees Contacts.

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

  • RESOURCE_TYPE: o tipo de recurso para os qual você quer calcular os contatos. Use o valor projects, folders ou organizations.
  • RESOURCE_ID: seu projeto do Google Cloud, a organização ou o ID da pasta.
  • NOTIFICATION_CATEGORY: as categorias de notificações para as quais você quer calcular contatos. Você pode repetir esse campo para listar contatos de várias categorias de notificação. A NOTIFICATION_CATEGORY pode ser qualquer um dos seguintes valores: ALL, BILLING, LEGAL, PRODUCT_UPDATES, SECURITY, SUSPENSION, TECHNICAL e NOTIFICATION_CATEGORY_UNSPECIFIED. Escolher um valor de ALL lista os contatos de todas as categorias.
  • PAGE_SIZE: opcional. O número de contatos a serem incluídos na resposta. O valor padrão é 50, e o valor máximo é 100. Se o número de contatos for maior que o tamanho da página, a resposta conterá um token de paginação que pode ser usado para recuperar a próxima página de resultados.
  • NEXT_PAGE_TOKEN: opcional. O token de paginação retornado em uma resposta anterior usando esse método. Se especificada, a lista de contatos começa onde a resposta anterior foi finalizada.

Solicitação:

GET essentialcontacts.googleapis.com/v1alpha1/RESOURCE_TYPE/RESOURCE_ID/contacts:compute?notificationCategories=NOTIFICATION_CATEGORY&pageSize=PAGE_SIZE&pageToken=NEXT_PAGE_TOKEN

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

A resposta lista todos os contatos e os contatos herdados do recurso:

{
  "contacts": [
    {
      "name": "projects/my-projects/contacts/1",
      "email": "my-project-contact-1@my-domain.com",
      "notificationCategorySubscriptions": [
        "ALL"
      ],
      "languageTag": "en-US"
    },
    {
      "name": "projects/my-projects/contacts/2",
      "email": "my-project-contact-2@my-domain.com",
      "notificationCategorySubscriptions": [
        "BILLING"
      ],
      "languageTag": "en-US"
    },
    {
      "name": "organizations/my-organization/contacts/1",
      "email": "my-organization-contact@my-domain.com",
      "notificationCategorySubscriptions": [
        "ALL"
      ],
      "languageTag": "en-US"
    }
  ]
}

Como gerenciar contatos individuais

É possível gerenciar contatos individuais na página Contatos essenciais, no Console do Cloud ou usando a API REST.

Como adicionar um contato

Para adicionar um contato, faça o seguinte:

Console

  1. No Console do Cloud, acesse a página Contatos essenciais.

    Acessar a página "Contatos essenciais"

  2. Certifique-se de que o nome do projeto, pasta ou organização apareça no seletor de projetos na parte superior da página. O seletor de projeto informa de qual projeto, pasta ou organização você está gerenciando contatos.

  3. Clique em Adicionar contato.

  4. Nos campos E-mail e Confirmar e-mail, insira o endereço de e-mail do contato.

  5. No menu suspenso Categorias de notificação, selecione as categorias de notificação das quais você quer que o contato receba comunicações. Para ver uma lista de categorias de notificação e contatos recomendados, consulte Como identificar contatos nesta página.

  6. Clique em Save.

REST

Para adicionar um novo contato, use o método contacts.create da API Essential Contacts.

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

  • RESOURCE_TYPE: o tipo de recurso para o qual você quer listar os contatos. Use o valor projects, folders ou organizations.
  • RESOURCE_ID: seu projeto do Google Cloud, a organização ou o ID da pasta.
  • EMAIL: o endereço de e-mail do seu contato. Não é possível alterar esse campo depois de criar o contato.
  • NOTIFICATION_CATEGORY_1 e NOTIFICATION_CATEGORY_2: as categorias de notificação das quais você quer que o contato receba comunicações. Esse valor pode ser qualquer um destes: ALL, BILLING, LEGAL, PRODUCT_UPDATES, SECURITY, SUSPENSION, TECHNICAL.

    Se quiser ver uma lista de contatos recomendados para cada categoria, consulte Como identificar contatos nesta página.

  • LANGUAGE: o código para o idioma de notificação preferencial do contato. É possível incluir o código de um dos idiomas compatíveis.

Solicitação:

POST essentialcontacts.googleapis.com/v1alpha1/RESOURCE_TYPE/RESOURCE_ID/contacts

Corpo da solicitação:

{
  "email": "EMAIL",
  "notificationCategorySubscriptions": [
    "NOTIFICATION_CATEGORY_1",
    "NOTIFICATION_CATEGORY_2"
  ],
  "languageTag": "LANGUAGE"
}

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

Você receberá uma resposta JSON semelhante a esta:

{
  "name": "projects/my-project/contacts/3",
  "email": "my-new-contact@my-domain.com",
  "notificationCategorySubscriptions": [
    "SUSPENSION",
    "TECHNICAL"
  ],
  "languageTag": "en"
}

Como alterar um contato

Para alterar as categorias atribuídas a um contato, faça o seguinte:

Console

  1. No Console do Cloud, acesse a página Contatos essenciais.

    Acessar a página "Contatos essenciais"

  2. Certifique-se de que o nome do projeto, pasta ou organização apareça no seletor de projetos na parte superior da página. O seletor de projeto informa de qual projeto, pasta ou organização você está gerenciando contatos.

  3. Ao lado de Visualizar por, selecione Contato.

  4. Clique em ao lado do contato cuja categoria você quer alterar.

  5. Selecione as categorias de notificação que você quer no menu suspenso Categorias de notificação e clique em Salvar.

REST

Para alterar as assinaturas de notificação ou o idioma preferido de um contato existente, use o método contacts.patch da API Essential Contacts.

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

  • RESOURCE_TYPE: o tipo de recurso para o qual você quer listar os contatos. Use o valor projects, folders ou organizations.
  • RESOURCE_ID: seu projeto do Google Cloud, a organização ou o ID da pasta.
  • CONTACT_ID: o ID numérico do contato. Para ver os códigos de todos os contatos no seu projeto, pasta ou organização, liste seus contatos.
  • UPDATE_MASK: opcional. Uma máscara que descreve os campos do contato que você alterou. O formato da máscara é uma lista separada por vírgulas de nomes de campos totalmente qualificados, por exemplo: notificationCategorySubscriptions,languageTag.
  • EMAIL: o endereço de e-mail do seu contato. Este campo precisa corresponder ao endereço de e-mail associado ao CONTACT_ID que você inclui na solicitação.
  • NOTIFICATION_CATEGORY_1 e NOTIFICATION_CATEGORY_2: opcional. As categorias de notificação atualizadas que você quer que o contato receba. Este valor pode ser qualquer um dos seguintes: ALL, BILLING, LEGAL, PRODUCT_UPDATES, SECURITY, SUSPENSION, TECHNICAL.

    Se quiser ver uma lista de contatos recomendados para cada categoria, consulte Como identificar contatos nesta página.

  • LANGUAGE: o código para o idioma de notificação preferencial do contato. É possível incluir o código de um dos idiomas compatíveis.

Solicitação:

PATCH essentialcontacts.googleapis.com/v1alpha1/RESOURCE_TYPE/RESOURCE_ID/contacts/CONTACT_ID?updateMask="UPDATE_MASK"

Corpo da solicitação:

{
  "name": "RESOURCE_TYPE/RESOURCE_ID/contact/CONTACT_ID",
  "email": "EMAIL",
  "notificationCategorySubscriptions": [
    "NOTIFICATION_CATEGORY_1",
    "NOTIFICATION_CATEGORY_2"
  ],
  "languageTag": "LANGUAGE"
}

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

Você receberá uma resposta JSON semelhante a esta:

{
  "name": "projects/my-project/contacts/2",
  "email": "my-new-contact@my-domain.com",
  "notificationCategorySubscriptions": [
    "ALL"
  ],
  "languageTag": "en"
}

Como excluir um contato

Para excluir um contato, faça o seguinte:

Console

  1. No Console do Cloud, acesse a página Contatos essenciais.

    Acessar a página "Contatos essenciais"

  2. Certifique-se de que o nome do projeto, pasta ou organização apareça no seletor de projetos na parte superior da página. O seletor de projeto informa de qual projeto, pasta ou organização você está gerenciando contatos.

  3. Ao lado de Visualizar por, selecione Contato.

  4. Clique em ao lado do endereço de e-mail do contato que você quer excluir. Na caixa de diálogo, confirme a exclusão do contato.

REST

Para excluir um contato, use o método contacts.delete da API Essential Contacts.

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

  • RESOURCE_TYPE: o tipo de recurso para o qual você quer listar os contatos. Use o valor projects, folders ou organizations.
  • RESOURCE_ID: seu projeto do Google Cloud, a organização ou o ID da pasta.
  • CONTACT_ID: o ID numérico do contato. Para ver os códigos de todos os contatos no seu projeto, pasta ou organização, liste seus contatos.

Solicitação:

DELETE essentialcontacts.googleapis.com/v1alpha1/RESOURCE_TYPE/RESOURCE_ID/contacts/CONTACT_ID

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

Se a solicitação for bem-sucedida, o corpo da resposta estará vazio.

Como gerenciar contatos por categoria

No Console do Cloud, também é possível gerenciar contatos por categoria acessando a guia Categoria na página Contatos essenciais.

Para adicionar, alterar ou excluir os contatos atribuídos a uma única categoria, faça o seguinte:

  1. No Console do Cloud, acesse a página Contatos essenciais.

    Acessar a página "Contatos essenciais"

  2. Certifique-se de que o nome do projeto, pasta ou organização apareça no seletor de projetos na parte superior da página. O seletor de projeto informa de qual projeto, pasta ou organização você está gerenciando contatos.

  3. Ao lado de Visualizar por, selecione Categoria.

  4. Clique em na mesma linha da categoria com os contatos que você quer gerenciar.

  5. Gerencie os contatos atribuídos à categoria:

    • Para adicionar um novo contato, clique em Adicionar contato e siga as etapas para adicionar um contato descrito nesta página.
    • Para alterar a categoria a que um contato é atribuído, clique em ao lado do contato cuja categoria você quer alterar. Em seguida, selecione as categorias de notificação que você quer no menu suspenso Categorias de notificação e clique em Salvar.

    • Para excluir um contato, clique em ao lado do endereço de e-mail do contato.

A seguir