管理通知联系人

许多 Google Cloud 服务(例如 Cloud Billing)都会发送通知,以便与 Google Cloud 用户共享重要信息。默认情况下,这些通知将发送给具有某些 Identity and Access Management (IAM) 角色的成员。借助“重要联系人”,您可以通过提供自己的联系人列表来自定义接收通知的人员。

准备工作

启用 Essential Contacts API。

启用 API

所需权限

使用重要联系人所需的权限取决于您要执行的操作。

查看联系人所需的权限

如需查看联系人,您需要具备包含以下权限的角色:

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

如需获得这些权限,同时遵循最小权限原则,请让管理员向您授予 Essential Contacts Viewer 角色 (roles/essentialContacts.viewer)。

或者,管理员也可以向您授予具有所需权限的其他角色,例如自定义角色或更宽松的预定义角色

请务必针对分配了联系人的项目、文件夹或组织授予这些角色。

管理联系人所需的权限

如需修改、删除和创建联系人,您需要具备包含以下权限的角色:

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

如需获得这些权限,同时遵循最小权限原则,请让管理员向您授予 Essential Contacts Admin 角色 (roles/essentialContacts.admin)。

或者,管理员也可以向您授予具有所需权限的其他角色,例如自定义角色或更宽松的预定义角色

请务必针对分配了联系人的项目、文件夹或组织授予这些角色。

通知类别

您可以为多种不同类别的通知分配联系人。如果您没有为类别添加联系人,则该类别中的通知将进入默认联系人,默认联系人是根据成员的 IAM 角色选择的。建议添加自定义联系人,而不要依赖于默认联系人,从而帮助确保合适的人员能够收到您的项目、文件夹或组织的通知。

您可以将个人和 Google 群组添加为联系人。为降低人员更改造成的影响,我们建议将 Google 群组添加为联系人,然后管理这些群组的成员资格,以确定哪些人会收到通知。这种做法有助于确保通知始终发送给在职员工。

请查看下表,了解通知的类别、默认联系人和推荐的联系人。请使用此信息为每个类别选择合适的联系人。

类别 说明 默认联系人 推荐的联系人
全部 与资源相关的所有通知 负责路由或记录通知的人员或自动化系统
结算 结算和付款通知、价格更新、错误、赠金 Billing Account Administrator (roles/billing.admin) 财务部门员工和负责管理您与 Google 之间财务关系的人员,包括管理预算、规划以及与 Google Cloud 使用相关的帐号的人员
法律 强制措施、法规遵从、政府通知 Billing Account Administrator (roles/billing.admin) 法律顾问、合规性管理人员、政府关系专家以及其他相关专业人员
产品最新动态 新版本、产品条款更新和弃用情况 Project Owner (roles/owner) 能够通过及时了解 Google 产品和服务的变化而从中受益的产品经理、架构师和工程师。
安全 安全/隐私权问题、通知和漏洞 Organization Administrator (roles/resourcemanager.organizationAdmin) IT 安全、运营安全以及负责保护公司和客户数据并确保业务连续性的其他人
暂停 与立即暂停帐号相关的通知 Project Owner (roles/owner) 立即负责维护 IT 基础架构和业务应用启动和正常运行的人员
技术 服务中断、错误、Bug 及其他技术问题 Project Owner (roles/owner) IT 专业人员、可靠性工程师、管理员、值班人员清单,以及需要知道当前存在和即将发生从而导致 IT 资源无法正常运行的技术问题的其他人员

支持的语言

在“重要联系人”中,每位联系人都有首选语言设置。通知创建者可以在发送通知时参考此设置。

在 Cloud Console 中添加联系人时,Cloud Console 会根据联系人创建者的首选语言设置自动配置联系人的首选语言。使用 API 添加联系人时,您需要使用语言代码手动配置联系人的首选语言。该语言代码可以引用“重要联系人”支持的任何语言。

决定分配联系人的位置

您可以在项目、文件夹或单位级别分配联系人。

联系人通过 Google Cloud 资源层次结构继承。因此,如果您在组织级层添加联系人,他们会收到组织的通知以及组织中所有文件夹和项目的通知。同样,如果您在文件夹级层添加联系人,则他们将会收到文件夹的通知以及文件夹中所有文件夹和项目的通知。

您决定分配联系人的位置取决于您的组织结构。但是,我们通常建议根据联系人的通知类别在下列级层指定联系人:

推荐级层 通知类别
组织级层
  • 结算
  • 法律
  • 安全1
文件夹/项目级层
  • 全部
  • 产品最新动态
  • 安全1
  • 暂停
  • 技术

1 您应分配安全联系人的级别取决于组织的具体安全做法。例如,如果各个项目所有者负责其项目的安全性,则您可以在项目级层分配安全联系人。但是,如果组织范围的群组管理所有项目的安全性,则您可以在组织级层分配安全联系人。

列出联系人

要列出项目、文件夹或组织中的所有联系人,请执行以下操作:

控制台

  1. 在 Cloud Console 中,转到重要联系人页面。

    转到“重要联系人”页面

  2. 确保您的项目、文件夹或组织的名称显示在页面顶部的项目选择器中。项目选择器会显示您当前要管理哪个项目、文件夹或组织的联系人。

  3. 要按类别列出联系人,请选择类别。要按字母顺序列出联系人,请选择联系人

REST

列出联系人

如需查看已在特定项目、文件夹或组织中设置的联系人,请使用 Essentials Contacts API 的 contacts.list 方法。

在使用下面的请求数据之前,请先进行以下替换:

  • RESOURCE_TYPE:要为其列出联系人的资源类型。使用值 projectsfoldersorganizations
  • RESOURCE_ID:您的 Google Cloud 项目、组织或文件夹 ID。
  • PAGE_SIZE:可选。响应中包含的联系人数量。默认值为 50,最大值为 100。如果联系人数量超过页面大小,则响应将包含可用于检索下一页结果的分页令牌。
  • NEXT_PAGE_TOKEN:可选。此方法之前的响应中返回的分页令牌。如果已指定,则联系人列表将从上一个响应结束的位置开始。

请求:

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

根据您发送的请求,请展开以下选项之一:

您应该收到类似以下内容的 JSON 响应:

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

列出联系人和继承的联系人

子资源(文件夹和项目)会从其祖先实体(组织和其他文件夹)继承联系人。要列出资源的所有联系人和继承的联系人,请使用 Essential Contacts API 的 contacts.compute 方法。

在使用下面的请求数据之前,请先进行以下替换:

  • RESOURCE_TYPE:要为其计算联系人的资源类型。使用值 projectsfoldersorganizations
  • RESOURCE_ID:您的 Google Cloud 项目、组织或文件夹 ID。
  • NOTIFICATION_CATEGORY:您要计算联系人的通知类别。您可以重复此字段以列出多个通知类别的联系人。此 NOTIFICATION_CATEGORY 可以是以下任一值:ALLBILLINGLEGALPRODUCT_UPDATESSECURITYSUSPENSIONTECHNICALNOTIFICATION_CATEGORY_UNSPECIFIED。选择 ALL 值可列出所有类别的联系人。
  • PAGE_SIZE:可选。响应中包含的联系人数量。默认值为 50,最大值为 100。如果联系人数量超过页面大小,则响应将包含可用于检索下一页结果的分页令牌。
  • NEXT_PAGE_TOKEN:可选。此方法之前的响应中返回的分页令牌。如果已指定,则联系人列表将从上一个响应结束的位置开始。

请求:

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

根据您发送的请求,请展开以下选项之一:

响应列出了资源的所有联系人和继承的联系人:

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

管理个别联系人

您可以在 Cloud Console 的重要联系人页面上或通过 REST API 管理各个联系人。

添加联系人

如需添加联系人,请执行以下操作:

控制台

  1. 在 Cloud Console 中,转到重要联系人页面。

    转到“重要联系人”页面

  2. 确保您的项目、文件夹或组织的名称显示在页面顶部的项目选择器中。项目选择器会显示您当前要管理哪个项目、文件夹或组织的联系人。

  3. 点击 添加联系人

  4. 电子邮件确认电子邮件字段中,输入联系人的电子邮件地址。

  5. 通知类别下拉菜单中,选择您希望联系人接收相关信息的通知类别。如需查看通知类别和建议的联系人的列表,请参阅本页面上的识别联系人

  6. 点击保存

REST

要添加新联系人,请使用 Essentials Contacts API 的 contacts.create 方法。

在使用下面的请求数据之前,请先进行以下替换:

  • RESOURCE_TYPE:要为其列出联系人的资源类型。使用值 projectsfoldersorganizations
  • RESOURCE_ID:您的 Google Cloud 项目、组织或文件夹 ID。
  • EMAIL:您的联系人的电子邮件地址。创建联系人后,您便无法更改此字段。
  • NOTIFICATION_CATEGORY_1NOTIFICATION_CATEGORY_2:您希望联系人接收相关信息的通知类别。此值可以是以下任一值:ALLBILLINGLEGALPRODUCT_UPDATESSECURITYSUSPENSIONTECHNICAL

    如需查看每个类别的建议联系人列表,请参阅本页中的识别联系人

  • LANGUAGE:联系人首选通知语言的语言代码。您可以添加任何支持的语言的语言代码。

请求:

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

请求正文:

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

根据您发送的请求,请展开以下选项之一:

您应该收到类似以下内容的 JSON 响应:

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

更改联系人

如需更改将联系人分配到哪个类别,请执行以下操作:

控制台

  1. 在 Cloud Console 中,转到重要联系人页面。

    转到“重要联系人”页面

  2. 确保您的项目、文件夹或组织的名称显示在页面顶部的项目选择器中。项目选择器会显示您当前要管理哪个项目、文件夹或组织的联系人。

  3. 查看方式旁边,选择联系人

  4. 点击您要更改其类别的联系人旁边的

  5. 通知类别下拉菜单中选择所需的通知类别,然后点击保存

REST

如需更改现有联系人的通知订阅或首选语言,请使用 Essential Contacts API 的 contacts.patch 方法。

在使用下面的请求数据之前,请先进行以下替换:

  • RESOURCE_TYPE:要为其列出联系人的资源类型。使用值 projectsfoldersorganizations
  • RESOURCE_ID:您的 Google Cloud 项目、组织或文件夹 ID。
  • CONTACT_ID:联系人的数字 ID。要查看项目、文件夹或组织中所有联系人的 ID,请列出联系人
  • UPDATE_MASK:可选。描述您更改了联系人的哪个字段的掩码。掩码的格式是以英文逗号分隔的完全限定字段名称列表,例如:notificationCategorySubscriptions,languageTag
  • EMAIL:您的联系人的电子邮件地址。此字段必须与您在请求中添加的 CONTACT_ID 关联的电子邮件地址一致。
  • NOTIFICATION_CATEGORY_1NOTIFICATION_CATEGORY_2:可选。您希望联系人接收相关信息的已更新通知类别。此值可以是以下任一值:ALLBILLINGLEGALPRODUCT_UPDATESSECURITYSUSPENSIONTECHNICAL

    如需查看每个类别的建议联系人列表,请参阅本页中的识别联系人

  • LANGUAGE:联系人首选通知语言的语言代码。您可以添加任何支持的语言的语言代码。

请求:

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

请求正文:

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

根据您发送的请求,请展开以下选项之一:

您应该收到类似以下内容的 JSON 响应:

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

删除联系人

如需删除联系人,请执行以下操作:

控制台

  1. 在 Cloud Console 中,转到重要联系人页面。

    转到“重要联系人”页面

  2. 确保您的项目、文件夹或组织的名称显示在页面顶部的项目选择器中。项目选择器会显示您当前要管理哪个项目、文件夹或组织的联系人。

  3. 查看方式旁边,选择联系人

  4. 点击您想要删除的联系人的电子邮件地址旁边的 。然后在对话框中确认您想要删除联系人。

REST

要删除联系人,请使用 Essentials Contacts API 的 contacts.delete 方法。

在使用下面的请求数据之前,请先进行以下替换:

  • RESOURCE_TYPE:要为其列出联系人的资源类型。使用值 projectsfoldersorganizations
  • RESOURCE_ID:您的 Google Cloud 项目、组织或文件夹 ID。
  • CONTACT_ID:联系人的数字 ID。要查看项目、文件夹或组织中所有联系人的 ID,请列出联系人

请求:

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

根据您发送的请求,请展开以下选项之一:

如果请求成功,则响应正文将为空。

按类别管理联系人

在 Cloud Console 中,您还可以通过转到重要联系人页面上的类别标签页,按类别管理联系人。

如需添加、更改或删除分配给单个类别的联系人,请执行以下操作:

  1. 在 Cloud Console 中,转到重要联系人页面。

    转到“重要联系人”页面

  2. 确保您的项目、文件夹或组织的名称显示在页面顶部的项目选择器中。项目选择器会显示您当前要管理哪个项目、文件夹或组织的联系人。

  3. 查看方式旁边,选择类别

  4. 点击您要管理其联系人的类别所在的行中的

  5. 管理分配给该类别的联系人:

    • 如需添加新联系人,请点击添加联系人,然后按照本页中所述的相关步骤添加联系人
    • 如需更改将联系人分配到哪个类别,请点击要更改其类别的联系人旁边的 。然后,从通知类别下拉菜单中选择所需的通知类别,然后点击保存

    • 要删除联系人,请点击该联系人的电子邮件地址旁边的

后续步骤