向 Cloud Healthcare API 进行身份验证

本文档介绍如何以编程方式向 Cloud Healthcare API 进行身份验证。

如需详细了解 Google Cloud 身份验证，请参阅身份验证概览。

API 访问权限

Cloud Healthcare API 支持程序化访问。如何向 Cloud Healthcare API 进行身份验证取决于您访问 API 的方式。您可以通过以下方式访问该 API：

客户端库

Google API 客户端库提供以程序化方式向 Cloud Healthcare API 进行身份验证的高级语言支持。客户端库支持应用默认凭据 (ADC)；这些库会在一组已定义的位置查找凭据，并使用这些凭据对向 API 发出的请求进行身份验证。借助 ADC，您可以在本地环境或生产环境等各种环境中向应用提供凭据，而无需修改应用代码。

如需使用 ADC，您必须先向 ADC 提供凭据。

gcloud CLI

使用 gcloud CLI 访问 Cloud Healthcare API 时，您可以使用 Google 帐号登录 gcloud CLI，该帐号提供 gcloud CLI 命令使用的凭据。

如果贵组织的安全政策阻止用户帐号拥有所需的权限，您可以使用 impersonate-service-account 属性或使用 --impersonate-service-account 标志来模拟服务帐号，该标志仅影响您使用它的命令。

如需详细了解如何将 gcloud CLI 与 Cloud Healthcare API 搭配使用，请参阅 gcloud CLI 参考页面。

REST

您可以使用 gcloud CLI 凭据或应用默认凭据 (ADC) 向 Cloud Healthcare API 进行身份验证。如需详细了解 REST 请求的身份验证，请参阅使用 REST 进行身份验证。如需了解凭据类型，请参阅 gcloud CLI 凭据和 ADC 凭据。

为 Cloud Healthcare API 设置身份验证

如何设置身份验证取决于运行代码的环境。

下面列出了最常用的设置身份验证选项。 如需了解有关身份验证的更多选项和信息，请参阅 Google 身份验证。

如需完成这些说明，您必须先完成 Cloud Healthcare API 的基本设置，包括启用 API 以及安装 gcloud CLI。如需了解设置说明，请参阅使用 curl 和 PowerShell 存储医疗保健数据中的准备工作。

对于本地开发环境

如果您打算使用客户端库、运行代码示例或在本地开发环境中使用第三方工具（例如 Terraform），则必须在该环境中设置应用默认凭据 (ADC)。对于从命令行发出的 REST 请求，请使用 gcloud CLI 凭据。

如需了解本地 ADC 凭据与 gcloud CLI 凭据之间的区别，请参阅 gcloud CLI 凭据和 ADC 凭据。

客户端库或第三方工具

在本地环境中设置应用默认凭据 (ADC)：

  1. 为您的 Google 账号创建本地身份验证凭据：

    gcloud auth application-default login

系统会显示登录屏幕。登录后，您的凭据会存储在 ADC 使用的本地凭据文件中。

如需详细了解如何在本地环境中使用 ADC，请参阅本地开发环境。

从命令行发出的 REST 请求

从命令行发出 REST 请求时，您可以在发送请求的命令中包含 gcloud auth print-access-token 来使用 gcloud CLI 凭据。

以下示例列出了指定项目的服务帐号。您可以对任何 REST 请求使用相同的模式。

在使用任何请求数据之前，请先进行以下替换：

  • PROJECT_ID：您的 Google Cloud 项目 ID。

如需发送您的请求，请展开以下选项之一：

响应类似于以下内容。在响应中：

  • UNIQUE_ID 是服务帐号的唯一稳定数字 ID。
  • DISPLAY_NAME 是服务帐号的用户指定的名称，能让人看懂
{
  "accounts": [
    {
      "name": "projects/PROJECT_IDserviceAccounts/PROJECT_ID@appspot.gserviceaccount.com",
      "projectId": "PROJECT_ID",
      "uniqueId": "UNIQUE_ID",
      "email": "PROJECT_ID@appspot.gserviceaccount.com",
      "displayName": "DISPLAY_NAME",
      "oauth2ClientId": "UNIQUE_ID"
    },
    ...
  ]
}

在 Google Cloud 上

如需对 Google Cloud 上运行的工作负载进行身份验证，您需要使用运行代码的计算资源的服务帐号凭据。例如，您可以将服务帐号附加到 Compute Engine 虚拟机 (VM) 实例、Cloud Run 服务或 Dataflow 作业。 对于在 Google Cloud 计算资源上运行的代码，此方法是首选身份验证方法。

对于大多数服务，您必须在创建将运行代码的资源时附加服务帐号；您无法稍后添加或替换服务帐号。Compute Engine 是一个例外项，可让您随时将服务帐号附加到虚拟机实例。

  1. 设置身份验证：

    1. 创建服务帐号： 

      gcloud iam service-accounts create SERVICE_ACCOUNT_NAME

      将 SERVICE_ACCOUNT_NAME 替换为服务帐号的名称。

    2. 如需提供对项目和资源的访问权限，请向服务帐号授予角色： 

      gcloud projects add-iam-policy-binding PROJECT_ID --member="serviceAccount:SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com" --role=ROLE

      请替换以下内容：

      • SERVICE_ACCOUNT_NAME：服务帐号的名称
      • PROJECT_ID：您在其中创建服务帐号的项目的 ID
      • ROLE：要授予的角色
    3. 要向服务帐号授予其他角色，请按照上一步中的说明运行命令。

    4. 为您的 Google 帐号授予一个可让您使用服务帐号的角色并将服务帐号关联到其他资源的角色：

      gcloud iam service-accounts add-iam-policy-binding SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com --member="user:USER_EMAIL" --role=roles/iam.serviceAccountUser

      替换以下内容：

      • SERVICE_ACCOUNT_NAME：服务帐号的名称
      • PROJECT_ID：您在其中创建服务帐号的项目的 ID
      • USER_EMAIL：您的 Google 帐号的电子邮件地址

  2. 创建将运行代码的资源，并将服务帐号附加到该资源。例如，如果您使用 Compute Engine：

    创建 Compute Engine 实例。按如下所示的方式配置实例：
    • 将 INSTANCE_NAME 替换为您偏好的实例名称。
    • 将 --zone 标志设置为您要在其中创建实例的可用区。
    • 将 --service-account 标志设置为您创建的服务账号的电子邮件地址。
    gcloud compute instances create INSTANCE_NAME --zone=ZONE --service-account=SERVICE_ACCOUNT_EMAIL

在本地或在其他云服务提供商上

从 Google Cloud 外部设置身份验证的首选方法是使用工作负载身份联合。如需了解详情，请参阅身份验证文档中的本地或其他云服务提供商。

Cloud Healthcare API 中的访问权限控制

向 Cloud Healthcare API 进行身份验证后，您必须有权访问 Google Cloud 资源。Cloud Healthcare API 使用 Identity and Access Management (IAM) 进行授权。

如需详细了解 Cloud Healthcare API 的角色，请参阅使用 IAM 进行访问权限控制。如需详细了解 IAM 和授权，请参阅 IAM 概览。

使用 JSON 网络令牌（JWT）的服务帐号授权

您可以直接使用签名的 JSON Web 令牌 (JWT) 作为不记名令牌（而非 OAuth 2.0 访问令牌）对 Cloud Healthcare API 进行授权调用。Cloud Healthcare API 不需要特定的令牌生成方法。您可以在 JWT.io 上找到一系列用于创建 JWT 的帮助程序客户端库。当您使用已签名的 JWT 时，可以避免在进行 API 调用之前向 Google 授权服务器发出网络请求。

在使用 JWT 时，请在 aud 字段中指定 https://healthcare.googleapis.com/。

如需使用 JWT 而不是 OAuth 2.0 访问令牌授权调用 Cloud Healthcare API，请按照附录：不使用 OAuth 的服务帐号授权中的说明操作。

您创建的 JWT 应类似于以下示例：

{
  "alg": "RS256",
  "typ": "JWT",
  "kid": "PRIVATE_KEY_ID"
}
.
{
  "iss": "SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com",
  "sub": "SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com",
  "aud": "https://healthcare.googleapis.com/",
  "iat": CURRENT_UNIX_TIME,
  "exp": EXPIRATION_TIME
}

后续步骤