向 API 进行身份验证

本页面介绍如何对向 Cloud Healthcare API 发出的请求进行授权。

获取服务帐号密钥文件

要创建服务帐号并下载密钥文件,请执行以下操作:

Cloud Console

  1. 在 Cloud Console 中,转到创建服务帐号密钥页面。

    转到“创建服务帐号密钥”页面
  2. 服务帐号列表中,选择新的服务帐号
  3. 服务帐号名称字段中,输入一个名称。
  4. 角色列表中,选择项目 > Owner

    注意角色字段会为您的服务帐号授予资源访问权限。您稍后可以使用 Cloud Console 查看和更改此字段。如果您开发的是正式版应用,请指定比项目 > Owner 更为精细的权限。如需了解详情,请参阅为服务帐号授予角色
  5. 点击创建。包含密钥的 JSON 文件就会下载到计算机。

命令行

您可以使用本地机器上的 Cloud SDK 或在 Cloud Shell 中运行以下命令。

  1. 创建服务帐号。将 [NAME] 替换为服务帐号的名称。

    gcloud iam service-accounts create [NAME]
  2. 向服务帐号授予权限。将 [PROJECT_ID] 替换为您的项目 ID。

    gcloud projects add-iam-policy-binding [PROJECT_ID] --member "serviceAccount:[NAME]@[PROJECT_ID].iam.gserviceaccount.com" --role "roles/owner"
    注意角色字段会为您的服务帐号授予资源访问权限。您稍后可以使用 Cloud Console 查看和更改此字段。如果您开发的是正式版应用,请指定比项目 > Owner 更为精细的权限。如需了解详情,请参阅向服务帐号授予角色
  3. 生成密钥文件。将 [FILE_NAME] 替换为密钥文件的名称。

    gcloud iam service-accounts keys create [FILE_NAME].json --iam-account [NAME]@[PROJECT_ID].iam.gserviceaccount.com

为应用提供凭据

Cloud Healthcare API 可以使用特定语言的 Google 客户端库来对应用进行身份验证并调用 Google Cloud。例如,借助 Python 版 Google API 客户端库,您可以使用凭据构建服务对象,然后对其进行调用

您可以自动手动提供凭据。自动提供的凭据在测试和实验时非常有用,但可能很难确定您的应用正在使用哪些凭据。您也可以手动提供凭据。

设置环境变量

您可以通过将环境变量 GOOGLE_APPLICATION_CREDENTIALS 设置为包含服务帐号密钥的 JSON 文件的文件路径,向应用代码或命令提供身份验证凭据。

请注意,如果您在 Compute Engine、Google Kubernetes Engine (GKE) 或 App Engine 上运行应用,则仅在使用服务帐户而非这些服务提供的默认服务帐户时,才需要设置 GOOGLE_APPLICATION_CREDENTIALS 环境变量。

以下步骤展示了如何设置 GOOGLE_APPLICATION_CREDENTIALS 环境变量:

curl 命令

如果您使用的是 curl,请运行以下命令。将 PATH 替换为包含服务帐号密钥的 JSON 文件的文件路径,将 FILE_NAME 替换为文件名。此变量仅适用于当前的 shell 会话,因此,如果您打开新的会话,请重新设置该变量。

export GOOGLE_APPLICATION_CREDENTIALS=PATH/FILE_NAME

例如:

export GOOGLE_APPLICATION_CREDENTIALS="/home/user/Downloads/service-account.json"

PowerShell

如果您使用的是 Windows PowerShell,请运行以下命令。将 PATH 替换为包含服务帐号密钥的 JSON 文件的文件路径,将 FILE_NAME 替换为文件名。此变量仅适用于当前的 shell 会话,因此,如果您打开新的会话,请重新设置该变量。

$env:GOOGLE_APPLICATION_CREDENTIALS="PATH/FILE_NAME"

例如:

$env:GOOGLE_APPLICATION_CREDENTIALS="C:\Users\username\Downloads\service_account.json"

设置 GOOGLE_APPLICATION_CREDENTIALS 环境变量后,应用默认凭据(ADC)可以隐式确定您的凭据。

自动查找凭据

Google API 客户端库会使用应用默认凭据(ADC)自动查找应用的凭据。

当您的代码使用客户端库时,客户端库会按以下顺序检查您的凭据:

  1. ADC 会检查是否已设置环境变量 GOOGLE_APPLICATION_CREDENTIALS。如果设置了该变量,则 ADC 使用该变量指向的服务帐号文件。设置环境变量介绍了如何设置环境变量。
  2. 如果未设置环境变量,则当您的应用在任何服务上运行时,ADC 会使用 Compute Engine,Google Kubernetes Engine(GKE)或 App Engine 提供的默认服务帐号。

如果 ADC 无法使用上述任何凭据,则会引发错误。

以下代码示例展示了如何使用 ADC。该示例并未明确指定应用凭据。但是,只要设置了 GOOGLE_APPLICATION_CREDENTIALS 环境变量,或者只要应用在 Compute Engine,GKE 或 App Engine 上运行,ADC 就可以隐式找到凭据并将其存储在 auth 变量中。

Node.js

使用 Node.js 客户端库

const {google} = require('googleapis');
const healthcare = google.healthcare('v1');

const createDataset = async () => {
  const auth = await google.auth.getClient({
    scopes: ['https://www.googleapis.com/auth/cloud-platform'],
  });
  google.options({auth});

  // TODO(developer): uncomment these lines before running the sample
  // const cloudRegion = 'us-central1';
  // const projectId = 'adjective-noun-123';
  // const datasetId = 'my-dataset';
  const parent = `projects/${projectId}/locations/${cloudRegion}`;
  const request = {parent, datasetId};

  await healthcare.projects.locations.datasets.create(request);
  console.log(`Created dataset: ${datasetId}`);
};

createDataset();

手动获取和提供服务帐号凭据

您可以手动创建和获取服务帐号凭据,然后将凭据以其代码传递给您的应用。如需了解详情,请参阅手动获取和提供服务帐号凭据

使用 JSON 网络令牌(JWT)的服务帐号授权

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

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

要使用 JWT 而不是访问令牌授权对 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
   }
   

后续步骤