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

Funções exigidas

Para ter as permissões necessárias para gerenciar contatos, peça ao administrador para conceder a você os seguintes papéis de IAM no projeto, na pasta ou na organização a que o contato foi atribuído:

Para acessar os contatos: Leitor de contatos essenciais (roles/essentialcontacts.viewer)
Para acessar, editar, excluir e criar contatos: Administrador de contatos essenciais (roles/essentialcontacts.admin)

Para mais informações sobre como conceder papéis, consulte Gerenciar acesso.

Esses papéis predefinidos contêm as permissões necessárias para gerenciar contatos. Para conferir as permissões exatas necessárias, expanda a seção Permissões necessárias:

Permissões necessárias

As seguintes permissões são necessárias para gerenciar contatos:

Para conferir os contatos, faça o seguinte:
- essentialcontacts.contacts.get
- essentialcontacts.contacts.list
Para editar, excluir e criar contatos, faça o seguinte:
- essentialcontacts.contacts.create
- essentialcontacts.contacts.delete
- essentialcontcts.contacts.update

Talvez você também consiga receber essas permissões com papéis personalizados ou outros papéis predefinidos.

Categorias de notificação

Você pode atribuir contatos a várias categorias de notificações. Se você não adicionar um contato a uma categoria, as notificações nessa categoria vão para o contato substituto, que é selecionado com base nos papéis do IAM dos membros. Recomendamos adicionar contatos personalizados, e não depender de contatos substitutos, para ajudar a garantir que as pessoas corretas recebam notificações para seu projeto, pasta ou organização.

Você pode adicionar pessoas e grupos como contatos. Para reduzir o impacto das mudanças nos funcionários, recomendamos adicionar grupos como contatos e gerenciar a associação deles para determinar quem recebe as notificações. Essa prática ajuda a garantir que as notificações sejam sempre enviadas aos funcionários ativos.

Consulte a tabela a seguir para saber mais sobre categorias de notificações, contatos substitutos e recomendações. Se você não atribuir um contato a uma determinada categoria, as notificações serão enviadas para o contato substituto.

Categoria	Descrição	Examples	Contato substituto	Contato recomendado
Tudo	Todas as notificações de todas as outras categorias	N/A	N/A	Pessoas ou sistemas automatizados responsáveis pelo roteamento ou registro de um número potencialmente grande de notificações
Faturamento	Notificações de faturamento e pagamento	Atualizações de preços, erros e 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
Legal	Notificações de compliance legal	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	Mudanças nos produtos do Google	Novas versões, atualizações de termos do produto, suspensões	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	Notificações sobre problemas de segurança/privacidade	Vulnerabilidades, incidentes de dados e ataques	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 e do projeto	Compliance da avaliação da Apigee, violações de direitos autorais e mineração de moedas	Proprietário do projeto (`roles/owner`)	Pessoas imediatamente responsáveis por manter a infraestrutura de TI e os aplicativos comerciais funcionando
Técnica	Eventos técnicos e outros problemas operacionais	Erros de configuração do Logging, atualizações da Prevenção contra perda de dados e status do Actions on Google	Proprietário do projeto (`roles/owner`)	Profissionais de TI, engenheiros de confiabilidade, administradores, listas de plantão e outras pessoas que precisam saber sobre eventos e problemas técnicos atuais e futuros para gerenciar melhor os recursos de TI e evitar interrupções
Incidentes técnicos	Para clientes do Suporte Premium, uma subcategoria da categoria técnica para notificações de interrupção	Falhas temporárias não planejadas, problemas de serviço	N/A	Profissionais de TI, engenheiros de confiabilidade, administradores, listas de plantão e outras pessoas que precisam reagir a interrupções

Idiomas compatíveis

Nos Contatos essenciais, cada contato tem uma configuração de idioma preferencial. Os criadores de notificações podem consultar essa configuração ao enviar notificações.

Quando você adiciona um contato no console do Google Cloud, o console do Google Cloud configura automaticamente o idioma preferido do contato com base nas configurações de idioma preferido do criador de 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.

Idiomas compatíveis

Idioma	Código do idioma
Africâner	af
Albanês	sq
Amárico	am
Árabe	ar
Árabe (egípcio)	ar-EG
Armênio	hy
Azerbaijano	az
Basco	eu
Bielo-russo	be
Bengalês	bn
Bósnio	bs
Búlgaro	bg
Birmanês	my
Catalão	ca
Chinês	zh
Chinês (Hong Kong)	zh-HK
Chinês (Taiwan)	zh-TW
Croata	hr
Tcheco	cs
Dinamarquês	da
Holandês	nl
Inglês	en
Inglês (Austrália)	en-AU
Inglês (Reino Unido)	en-GB
English (US)	en-US
Estoniano	et
Filipino	fil
Finlandês	fi
Francês	fr
Francês (Canadá)	fr-CA
Galego	gl
Alemão	de
Georgiano	ka
Grego	el
Guzerate	gu
Hebraico	iw
Híndi	hi
Húngaro	hu
Islandês	is
Indonésio	id
Irlandês	ga
Italiano	it
Japonês	ja
Javanês	jv
Canarês	kn
Cazaque	kk
Khmer	km
Coreano	ko
Quirguiz	ky
Laosiano	lo
Letão	lv
Lituano	lt
Macedônio	mk
Malaio	ms
Malaiala	ml
Marata	mr
Mongol	mn
Nepalês	ne
Norueguês	no
Pashto	ps
Persa	fa
Polonês	pl
Português	pt
Português (Brasil)	pt-BR
Português (Portugal)	pt-PT
punjabi	pa
Romeno	ro
Russo	ru
Sérvio	sr
Sindi	sd
Cingalês	si
Eslovaco	sk
Esloveno	sl
Somali	so
Espanhol	es
Espanhol (América Latina)	es-419
Suaíli	sw
Sueco	sv
Tâmil	ta
Télugo	te
Tailandês	th
Turco	tr
Turcomano	tk
Ucraniano	uk
Urdu	ur
Usbeque	uz
Vietnamita	vi
Galês	cy
Zulu	zu

Práticas recomendadas para 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	Faturamento Jurídico Segurança¹
Nível de pasta/projeto	Tudo Atualizações do produto Segurança¹ Suspensão Técnica²

¹ O nível em que você atribui os contatos de segurança depende das práticas de segurança específicas da sua organização. Por exemplo, se cada proprietário de projeto for responsável pela segurança dos próprios projetos, atribua seus contatos de segurança no nível do projeto. No entanto, se um grupo para toda a organização gerenciar a segurança de todos os projetos, você atribuirá seus contatos de segurança no nível da organização.

² Os contatos da categoria técnica recebem um grande número de notificações por e-mail. Atribua esses contatos na pasta ou no nível do projeto para permitir que eles processem o fluxo de notificações recebidas.

Atribuir contatos para notificações de falha temporária e interrupção

Se você é cliente do Suporte Premium, é possível atribuir contatos para receber notificações de interrupção e interrupção pela subcategoria "Incidentes técnicos". Isso permite direcionar notificações de falhas temporárias de alto impacto para contatos que precisam se concentrar em falhas temporárias, sem a distração de outras notificações técnicas.

Para garantir que as notificações sejam enviadas aos contatos apropriados, lembre-se do seguinte comportamento de herança ao atribuir contatos à subcategoria "Incidentes técnicos":

Se você atribuir um contato de incidentes técnicos em um projeto ou uma pasta, as notificações de falha temporária serão enviadas apenas para:
- O contato de Incidentes técnicos do projeto ou da pasta
- Contatos de Incidentes técnicos herdados da organização ou pasta pai.
Se você não atribuir um contato de incidentes técnicos em um projeto ou pasta, as notificações de interrupção só serão enviadas para:
- O contato Técnico do projeto ou da pasta
- Contatos de Incidentes técnicos herdados da organização ou pasta pai.
Se um contato de incidente técnico não for atribuído ou herdado e nenhum contato técnico for atribuído, as notificações de interrupção não serão enviadas

Limitar domínios permitidos para contatos

Para restringir os domínios de endereço de e-mail que os novos contatos podem ter, defina a restrição da política da organização constraints/essentialcontacts.allowedContactDomains. Os contatos existentes não são afetados por essa restrição.

Para saber como definir restrições de política da organização, consulte Restrições da política da organização.

Como listar contatos

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

Console

No console do Google Cloud, acesse a página Contatos essenciais.

Acessar a página "Contatos essenciais"
Verifique se o nome do projeto, da pasta ou da organização aparece no seletor de recursos na parte superior da página. O seletor de recursos informa de qual projeto, pasta ou organização você está gerenciando contatos.
Para listar os contatos por categoria, selecione Categoria. Para listar os contatos em ordem alfabética, selecione Contatos.

Observação:se você estiver visualizando contatos de um recurso filho (pasta ou projeto) que herda contatos de ancestrais (organizações ou outras pastas), verá os contatos herdados de todos os ancestrais que têm permissão para visualizar contatos.
Observação:ao visualizar os contatos de uma organização ou pasta, você não vê contatos dos recursos filhos.

gcloud

No Console do Google Cloud, ative o Cloud Shell.

Ativar o Cloud Shell

Na parte inferior do Console do Google Cloud, uma sessão do Cloud Shell é iniciada e exibe um prompt de linha de comando. O Cloud Shell é um ambiente shell com a CLI do Google Cloud já instalada e com valores já definidos para o projeto atual. A inicialização da sessão pode levar alguns segundos.
Com a Google Cloud CLI, é possível listar os contatos definidos em um recurso ou listar todos os contatos e os herdados de um recurso.
Como listar contatos definidos em um recurso

Para ver os contatos que foram definidos em um projeto, uma pasta ou uma organização específica, use o comando gcloud essential-contacts list:
```
gcloud essential-contacts list --RESOURCE_TYPE="RESOURCE_ID"
```
Substitua os seguintes valores:
- RESOURCE_TYPE: o tipo de recurso para o qual você quer listar os contatos. Use o valor project, folder ou organization.
- RESOURCE_ID: seu projeto do Google Cloud, a organização ou o ID da pasta. Os IDs do projeto são strings alfanuméricas, como my-project. Os códigos de pastas e organizações são numéricos, como 123456789012.
Como alternativa, se você não especificar um tipo ou ID de recurso, a CLI gcloud listará os contatos do projeto atual.

A resposta é semelhante a:
```
---
email: my-contact-1@example.com
languageTag: en-US
name: projects/my-projects/contacts/1
notificationCategorySubscriptions:
- ALL
---
email: my-contact-2@example.com
languageTag: en-US
name: projects/my-projects/contacts/2
notificationCategorySubscriptions:
- BILLING
---
```
Como listar contatos e contatos herdados

Os recursos filhos (pastas e projetos) herdam os contatos dos ancestrais (organizações e outras pastas). Se você quiser listar todos os contatos e os contatos herdados de um recurso, use o comando gcloud essential-contacts compute:

Observação: você só poderá ver os contatos herdados de um ancestral de um recurso se conseguir visualizar os contatos do ancestral. Para isso, precisa de um papel no ancestral que inclua as permissões necessárias, como o de visualizador de contatos essenciais (roles/essentialcontacts.viewer).
```
gcloud essential-contacts compute --notification-categories="NOTIFICATION_CATEGORY" \
  --RESOURCE_TYPE="RESOURCE_ID"
```
Substitua os seguintes valores:

Antes de usar algum dos dados de solicitação abaixo, faça as substituições a seguir:
- NOTIFICATION_CATEGORIES: uma lista separada por vírgulas das categorias de notificações para as quais você quer calcular os contatos. A lista pode conter qualquer um dos seguintes valores: all, billing, legal, product-updates, security, suspension, technical, technical-incidents e notification-category-unspecified. Escolher um valor de all lista os contatos para todas as categorias.
- RESOURCE_TYPE: o tipo de recurso para os qual você quer calcular os contatos. Use o valor project, folder ou organization.
- RESOURCE_ID: seu projeto do Google Cloud, a organização ou o ID da pasta. Os IDs do projeto são strings alfanuméricas, como my-project. Os códigos de pastas e organizações são numéricos, como 123456789012.
Se você não especificar um tipo de recurso e um ID, a CLI gcloud listará os contatos do projeto atual.

A resposta lista todos os contatos e os contatos herdados do recurso:
```
---
email: my-contact-1@example.com
languageTag: en-US
name: projects/my-projects/contacts/1
notificationCategorySubscriptions:
- ALL
---
email: my-contact-2@example.com
languageTag: en-US
name: projects/my-projects/contacts/2
notificationCategorySubscriptions:
- BILLING
---
email: my-organization-contact@example.com
languageTag: en-US
name: organizations/my-organization/contacts/1
notificationCategorySubscriptions:
- ALL
---
```

REST

Com a API REST de contatos essenciais, é possível listar os contatos definidos em um recurso ou listar todos os contatos e contatos herdados de um recurso.

Como listar contatos definidos em um recurso

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

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. Os IDs do projeto são strings alfanuméricas, como my-project. Os códigos de pastas e organizações são numéricos, como 123456789012.
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/v1/RESOURCE_TYPE/RESOURCE_ID/contacts?pageSize=PAGE_SIZE&pageToken=NEXT_PAGE_TOKEN

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 application-default print-access-token) \
https://essentialcontacts.googleapis.com/v1/RESOURCE_TYPE/RESOURCE_ID/contacts?pageSize=PAGE_SIZE&pageToken=NEXT_PAGE_TOKEN

PowerShell (Windows)

execute o seguinte comando:

$cred = gcloud auth application-default print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
  -Method GET `
  -Headers $headers `
  -Uri "https://essentialcontacts.googleapis.com/v1/RESOURCE_TYPE/RESOURCE_ID/contacts?pageSize=PAGE_SIZE&pageToken=NEXT_PAGE_TOKEN" | Select-Object -Expand Content

Depois de enviar a solicitação, você receberá uma resposta JSON semelhante à seguinte:

{
  "contacts": [
    {
      "name": "projects/my-projects/contacts/1",
      "email": "my-contact-1@example.com",
      "notificationCategorySubscriptions": [
        "ALL"
      ],
      "languageTag": "en-US"
    },
    {
      "name": "projects/my-projects/contacts/2",
      "email": "my-contact-2@example.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. Os IDs do projeto são strings alfanuméricas, como my-project. Os códigos de pastas e organizações são numéricos, como 123456789012.
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. O NOTIFICATION_CATEGORY pode ser qualquer um destes valores: ALL, BILLING, LEGAL, PRODUCT_UPDATES, SECURITY, SUSPENSION, TECHNICAL, TECHNICAL_INCIDENTS e NOTIFICATION_CATEGORY_UNSPECIFIED. Escolher um valor de ALL lista os contatos para 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/v1/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:

curl (Linux, macOS ou Cloud Shell)

execute o seguinte comando:

curl -X GET \
-H "Authorization: Bearer "$(gcloud auth application-default print-access-token) \
https://essentialcontacts.googleapis.com/v1/RESOURCE_TYPE/RESOURCE_ID/contacts:compute?notificationCategories=NOTIFICATION_CATEGORY&pageSize=PAGE_SIZE&pageToken=NEXT_PAGE_TOKEN

PowerShell (Windows)

execute o seguinte comando:

$cred = gcloud auth application-default print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
  -Method GET `
  -Headers $headers `
  -Uri "https://essentialcontacts.googleapis.com/v1/RESOURCE_TYPE/RESOURCE_ID/contacts:compute?notificationCategories=NOTIFICATION_CATEGORIES&pageSize=PAGE_SIZE&pageToken=NEXT_PAGE_TOKEN" | Select-Object -Expand Content

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

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

Como gerenciar contatos essenciais individuais

É possível adicionar ou remover contatos ou atribuir categorias de notificação a eles na página Contatos essenciais do console do Google Cloud ou usando a API REST.

Como adicionar um contato

Para adicionar um contato, faça o seguinte:

Console

No console do Google Cloud, acesse a página Contatos essenciais.

Acessar a página "Contatos essenciais"
Verifique se o nome do projeto, da pasta ou da organização aparece no seletor de recursos na parte superior da página. O seletor de recursos informa de qual projeto, pasta ou organização você está gerenciando contatos.
Clique em Adicionar contato.
Nos campos E-mail e Confirmar e-mail, insira o endereço de e-mail do contato.
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.
Clique em Save.

gcloud

No Console do Google Cloud, ative o Cloud Shell.

Ativar o Cloud Shell

Na parte inferior do Console do Google Cloud, uma sessão do Cloud Shell é iniciada e exibe um prompt de linha de comando. O Cloud Shell é um ambiente shell com a CLI do Google Cloud já instalada e com valores já definidos para o projeto atual. A inicialização da sessão pode levar alguns segundos.
Para adicionar um novo contato, use o comando gcloud Essentials-contacts create:
```
gcloud essential-contacts create --email="EMAIL" \
    --notification-categories="NOTIFICATION_CATEGORIES" \
    --language="LANGUAGE" \
    --RESOURCE_TYPE="RESOURCE_ID"
```
Substitua os seguintes valores:
- EMAIL: o endereço de e-mail do seu contato. Não será possível alterar esse campo depois de criar o contato.
- NOTIFICATION_CATEGORIES: uma lista separada por vírgulas das categorias de notificação das quais você quer que o contato receba comunicações. A lista pode conter qualquer um destes valores: all, billing, legal, product-updates, security, suspension, technical, incidentes técnicos e notification-category-unspecified. Escolher um valor de all lista os contatos para todas as categorias.
  Para ver uma lista de contatos recomendados para cada categoria, consulte Como identificar contatos nesta página.
- LANGUAGE: o código do idioma preferido para notificação do seu contato. É possível incluir o código de qualquer um dos idiomas com suporte.
- RESOURCE_TYPE: o tipo de recurso para o qual você quer criar um contato. Use o valor project, folder ou organization.
- RESOURCE_ID: o ID do projeto, da organização ou da pasta do Google Cloud. Os IDs do projeto são strings alfanuméricas, como my-project. Os códigos de pastas e organizações são numéricos, como 123456789012.
Se você não especificar um tipo de recurso e ID, a CLI gcloud vai criar um contato no projeto atual.

Se o comando for bem-sucedido, nenhuma resposta será retornada.

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 criar um contato. Use o valor projects, folders ou organizations.
RESOURCE_ID: seu projeto do Google Cloud, a organização ou o ID da pasta. Os IDs do projeto são strings alfanuméricas, como my-project. Os códigos de pastas e organizações são numéricos, como 123456789012.
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 uma das seguintes opções: ALL, BILLING, LEGAL, PRODUCT_UPDATES, SECURITY, SUSPENSION, TECHNICAL, TECHNICAL_INCIDENTS.

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/v1/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:

curl (Linux, macOS ou Cloud Shell)

Salve o corpo da solicitação em um arquivo chamado request.json e execute o seguinte comando:

curl -X POST \
-H "Authorization: Bearer "$(gcloud auth application-default print-access-token) \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
https://essentialcontacts.googleapis.com/v1/RESOURCE_TYPE/RESOURCE_ID/contacts

PowerShell (Windows)

Salve o corpo da solicitação em um arquivo chamado request.json e execute o seguinte comando:

$cred = gcloud auth application-default print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
  -Method POST `
  -Headers $headers `
  -ContentType: "application/json; charset=utf-8" `
  -InFile request.json `
  -Uri "https://essentialcontacts.googleapis.com/v1/RESOURCE_TYPE/RESOURCE_ID/contacts" | Select-Object -Expand Content

Depois de enviar a solicitação, você receberá uma resposta JSON semelhante à seguinte:

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

Como alterar um contato

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

Console

No console do Google Cloud, acesse a página Contatos essenciais.

Acessar a página "Contatos essenciais"
Verifique se o nome do projeto, da pasta ou da organização aparece no seletor de recursos na parte superior da página. O seletor de recursos informa de qual projeto, pasta ou organização você está gerenciando contatos.
Ao lado de Visualizar por, selecione Contato.
Clique em ao lado do contato cuja categoria você quer alterar.
Selecione as categorias de notificação que você quer no menu suspenso Categorias de notificação e clique em Salvar.

gcloud

No Console do Google Cloud, ative o Cloud Shell.

Ativar o Cloud Shell

Na parte inferior do Console do Google Cloud, uma sessão do Cloud Shell é iniciada e exibe um prompt de linha de comando. O Cloud Shell é um ambiente shell com a CLI do Google Cloud já instalada e com valores já definidos para o projeto atual. A inicialização da sessão pode levar alguns segundos.
Para atualizar um contato existente, use o comando gcloud Essentials-contacts update:
```
gcloud essential-contacts update CONTACT_ID \
    --notification-categories="NOTIFICATION_CATEGORIES" \
    --language="LANGUAGE"
    --RESOURCE_TYPE="RESOURCE_ID"
```
Substitua os seguintes valores:
- CONTACT_ID: o ID numérico do contato que você quer atualizar. Para ver os IDs de todos os contatos no seu projeto, pasta ou organização, liste seus contatos. O ID numérico é tudo o que aparece depois de contacts no nome do contato.
- NOTIFICATION_CATEGORIES: uma lista separada por vírgulas das novas categorias de notificação das quais você quer que o contato receba comunicações. Essa lista vai substituir a lista de categorias de notificação.
  A lista pode conter qualquer um destes valores: all, billing, legal, product-updates, security, suspension, technical, incidentes técnicos e notification-category-unspecified. Escolher um valor de all lista os contatos para todas as categorias.
  
  Para ver uma lista de contatos recomendados para cada categoria, consulte Como identificar contatos nesta página.
- LANGUAGE: o código do idioma preferido para notificação do seu contato. É possível incluir o código de qualquer um dos idiomas com suporte.
- RESOURCE_TYPE: o tipo de recurso em que o contato está definido. Use o valor project, folder ou organization.
- RESOURCE_ID: o ID do projeto, da organização ou da pasta do Google Cloud em que o contato é definido. Os IDs do projeto são strings alfanuméricas, como my-project. Os IDs de pastas e organizações são numéricos, como 123456789012.
Se você não especificar um tipo de recurso e ID, a CLI gcloud vai atualizar o contato com o ID especificado no projeto atual. Se não houver nenhum contato com o ID especificado, a CLI gcloud retornará um erro.

Se o comando for bem-sucedido, nenhuma resposta será retornada.

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. Os IDs do projeto são strings alfanuméricas, como my-project. Os códigos de pastas e organizações são numéricos, como 123456789012.
CONTACT_ID: o ID numérico do contato que você quer atualizar. Para ver os IDs de todos os contatos no seu projeto, pasta ou organização, liste seus contatos. O ID numérico é tudo que vem depois de contacts no nome do contato.
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. Esse valor pode ser qualquer uma das seguintes opções: ALL, BILLING, LEGAL, PRODUCT_UPDATES, SECURITY, SUSPENSION, TECHNICAL, TECHNICAL_INCIDENTS.

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/v1/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:

curl (Linux, macOS ou Cloud Shell)

Salve o corpo da solicitação em um arquivo chamado request.json e execute o seguinte comando:

curl -X PATCH \
-H "Authorization: Bearer "$(gcloud auth application-default print-access-token) \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
https://essentialcontacts.googleapis.com/v1/RESOURCE_TYPE/RESOURCE_ID/contacts/CONTACT_ID?updateMask="UPDATE_MASK"

PowerShell (Windows)

Salve o corpo da solicitação em um arquivo chamado request.json e execute o seguinte comando:

$cred = gcloud auth application-default print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
  -Method PATCH `
  -Headers $headers `
  -ContentType: "application/json; charset=utf-8" `
  -InFile request.json `
  -Uri "https://essentialcontacts.googleapis.com/v1/RESOURCE_TYPE/RESOURCE_ID/contacts/CONTACT_ID?updateMask="UPDATE_MASK"" | Select-Object -Expand Content

Depois de enviar a solicitação, você receberá uma resposta JSON semelhante à seguinte:

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

Como excluir um contato

Para excluir um contato, faça o seguinte:

Console

No console do Google Cloud, acesse a página Contatos essenciais.

Acessar a página "Contatos essenciais"
Verifique se o nome do projeto, da pasta ou da organização aparece no seletor de recursos na parte superior da página. O seletor de recursos informa de qual projeto, pasta ou organização você está gerenciando contatos.
Ao lado de Visualizar por, selecione Contato.
Clique em ao lado do endereço de e-mail do contato que você quer excluir. Depois, na caixa de diálogo, confirme que você quer excluir o contato.

gcloud

No Console do Google Cloud, ative o Cloud Shell.

Ativar o Cloud Shell

Na parte inferior do Console do Google Cloud, uma sessão do Cloud Shell é iniciada e exibe um prompt de linha de comando. O Cloud Shell é um ambiente shell com a CLI do Google Cloud já instalada e com valores já definidos para o projeto atual. A inicialização da sessão pode levar alguns segundos.
Para excluir um contato atual, use o comando gcloud Essentials-contacts delete:
```
gcloud essential-contacts delete CONTACT_ID \
    --RESOURCE_TYPE="RESOURCE_ID"
```
Substitua os seguintes valores:
- CONTACT_ID: o ID numérico do contato que você quer excluir. Para ver os IDs de todos os contatos no seu projeto, pasta ou organização, liste seus contatos. O ID numérico é tudo o que aparece depois de contacts no nome do contato.
- RESOURCE_TYPE: o tipo de recurso em que o contato está definido. Use o valor project, folder ou organization.
- RESOURCE_ID: o ID do projeto, da organização ou da pasta do Google Cloud em que o contato é definido. Os IDs do projeto são strings alfanuméricas, como my-project. Os IDs de pastas e organizações são numéricos, como 123456789012.
Se você não especificar um tipo de recurso e ID, a CLI gcloud vai excluir o contato com o ID especificado no projeto atual. Se não houver nenhum contato com o ID especificado, a CLI gcloud retornará um erro.

Se o comando for bem-sucedido, nenhuma resposta será retornada.

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. Os IDs do projeto são strings alfanuméricas, como my-project. Os códigos de pastas e organizações são numéricos, como 123456789012.
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/v1/RESOURCE_TYPE/RESOURCE_ID/contacts/CONTACT_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 application-default print-access-token) \
https://essentialcontacts.googleapis.com/v1/RESOURCE_TYPE/RESOURCE_ID/contacts/CONTACT_ID

PowerShell (Windows)

execute o seguinte comando:

$cred = gcloud auth application-default print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
  -Method DELETE `
  -Headers $headers `
  -Uri "https://essentialcontacts.googleapis.com/v1/RESOURCE_TYPE/RESOURCE_ID/contacts/CONTACT_ID" | Select-Object -Expand Content

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

Como gerenciar contatos por categoria

No console do Google Cloud, também é possível gerenciar contatos por categoria na guia Categoria da página Contatos essenciais.

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

No console do Google Cloud, acesse a página Contatos essenciais.

Acessar a página "Contatos essenciais"
Verifique se o nome do projeto, da pasta ou da organização aparece no seletor de recursos na parte superior da página. O seletor de recursos informa de qual projeto, pasta ou organização você está gerenciando contatos.
Ao lado de Visualizar por, selecione Categoria.
Clique em na mesma linha da categoria com os contatos que você quer gerenciar.
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.
  
  Observação: não é possível alterar o endereço de e-mail de um contato. Para alterar um endereço de e-mail, adicione um novo contato com o endereço de e-mail atualizado e exclua o contato antigo.
- Para excluir um contato, clique em ao lado do endereço de e-mail do contato.

Como verificar transmissões de e-mail

É possível enviar um e-mail de teste aos contatos em cada categoria para verificar se as contas de e-mail são capazes de receber e-mails do Google Cloud.

Para enviar um e-mail de teste para contatos de uma categoria específica, faça o seguinte:

No console do Google Cloud, acesse a página Contatos essenciais.

Acessar a página "Contatos essenciais"
Verifique se o nome do projeto, da pasta ou da organização aparece no seletor de recursos na parte superior da página. O seletor de recursos exibe o projeto, a pasta ou a organização de que você está gerenciando contatos.
Ao lado de Visualizar por, selecione Categoria.
Clique em na mesma linha da categoria cujos contatos você quer enviar e-mails de teste.
Marque as caixas de seleção ao lado dos contatos para quem você quer enviar e-mails.
Clique em Enviar. Um e-mail de teste é enviado aos contatos selecionados.

Observação :é possível enviar no máximo um e-mail de teste a cada 24 horas para cada contato, por categoria e recurso.
Fale com cada contato para garantir que eles receberam um e-mail de teste de gcp-essential-contacts-noreply@google.com.

Como gerenciar contatos com o Terraform

O Terraform pode ser usado para gerenciar seus contatos de notificação. Os contatos têm o seguinte formato na linguagem do Terraform:

resource "google_essential_contacts_contact" "contact" {
  parent = "RESOURCE_TYPE/RESOURCE_ID"
  email = "EMAIL"
  language_tag = "LANGUAGE"
  notification_category_subscriptions = NOTIFICATION_CATEGORIES
}

Ao criar um contato, substitua os seguintes valores:

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. Os IDs do projeto são strings alfanuméricas, como my-project. Os códigos de pastas e organizações são numéricos, como 123456789012.
EMAIL: o endereço de e-mail do seu contato. Não é possível alterar esse campo depois de criar o contato.
LANGUAGE: opcional. O código do idioma preferido para notificação do contato. É possível incluir o código de idioma de qualquer um dos idiomas suportados.
NOTIFICATION_CATEGORIES: uma matriz das categorias de notificação sobre as quais você quer que o contato receba comunicações. Por exemplo, ["BILLING", "LEGAL"].

Essa matriz pode conter qualquer um dos seguintes valores: ALL, BILLING, LEGAL, PRODUCT_UPDATES, SECURITY, SUSPENSION, TECHNICAL, TECHNICAL_INCIDENTS.

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

Para adicionar, modificar ou remover um contato, adicionar, modificar ou remover um recurso de contato no arquivo de configuração do Terraform.

Para mais detalhes, consulte a documentação dos Contatos essenciais do Terraform (em inglês).

A seguir

Saiba como associar um domínio a um projeto para fins de verificação.
Entenda como gerenciar suas preferências de notificação.