使用 REST 时进行身份验证

本页面介绍如何在向 Google API 发出 REST 请求时进行身份验证。

如需了解如何在使用 Google 客户端库时进行身份验证，请参阅使用客户端库进行身份验证。

须知事项

如需运行本页中的示例，请完成以下步骤：

1. Install the Google Cloud CLI.

2. To initialize the gcloud CLI, run the following command:

   gcloud init

3. Enable the Cloud Resource Manager and Identity and Access Management (IAM) APIs:

   gcloud services enable cloudresourcemanager.googleapis.com iam.googleapis.com

如果您不想使用 gcloud CLI，可以跳过这些步骤，改用服务账号模拟或元数据服务器生成令牌。

凭据类型

您可以使用以下类型的凭据对 REST 调用进行身份验证：

• 您的 gcloud CLI 凭据。

  这种方法是在本地开发环境中为 REST 方法提供凭据的最简单、最安全的方式。如果您的用户账号具有您要调用的方法所需的 Identity and Access Management (IAM) 权限，则这是首选方法。

  您的 gcloud 凭据与您使用 gcloud CLI 提供给 ADC 的凭据不同。如需了解详情，请参阅 gcloud CLI 身份验证配置和 ADC 配置。

• 提供给应用默认凭据 (ADC) 的凭据。

  这是在生产环境中对 REST 调用进行身份验证的首选选项，因为 ADC 从运行代码的资源（例如 Compute Engine 虚拟机）中查找凭据。您还可以使用 ADC 在本地开发环境中进行身份验证。在这种情况下，gcloud CLI 会在本地文件系统中创建包含凭据的文件。

• 通过模拟服务账号提供的凭据。

  此方法需要更多设置。如果您想使用现有凭据获取其他服务账号的短期有效凭据（例如，在本地使用服务账号进行测试或请求临时提升的权限），请使用此方法。

• 元数据服务器返回的凭据。

  此方法仅适用于可访问元数据服务器的环境。 元数据服务器返回的凭据与应用默认凭据使用关联的服务账号找到的凭据相同，但您可以明确从元数据服务器请求访问令牌，然后通过 REST 请求提供它。查询元数据服务器以获取凭据需要 HTTP GET 请求；此方法不依赖于 Google Cloud CLI。

gcloud CLI 凭据

如需运行以下示例，您需要拥有项目的 resourcemanager.projects.get 权限。resourcemanager.projects.get 权限包含在若干角色中，例如 Browser 角色 (roles/browser)。

1. 使用 gcloud auth print-access-token 命令插入从用户凭据生成的访问令牌。

   以下示例会获取指定项目的详细信息。您可以对任何 REST 请求使用相同的模式。

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

   • PROJECT_ID：您的 Google Cloud 项目 ID 或名称。

   如需发送请求，请选择以下方式之一：

   curl

   执行以下命令：

   curl -X GET \
        -H "Authorization: Bearer $(gcloud auth print-access-token)" \
        "https://cloudresourcemanager.googleapis.com/v3/projects/PROJECT_ID"

   PowerShell

   执行以下命令：

   $cred = gcloud auth print-access-token
   $headers = @{ "Authorization" = "Bearer $cred" }
   
   Invoke-WebRequest `
       -Method GET `
       -Headers $headers `
       -Uri "https://cloudresourcemanager.googleapis.com/v3/projects/PROJECT_ID" | Select-Object -Expand Content

   系统会返回项目的详细信息。

对于需要配额项目的 API，您必须为请求明确设置配额项目。如需了解详情，请参阅本页面中的通过 REST 请求设置配额项目。

应用默认凭据

如需运行以下示例，与您提供给 ADC 的凭据关联的主账号需要项目的 resourcemanager.projects.get 权限。resourcemanager.projects.get 权限包含在若干角色中，例如 Browser 角色 (roles/browser)。

1. 向 ADC 提供凭据。

   如果您在 Google Cloud 计算资源上运行，则不应向 ADC 提供用户凭据。请改用关联的服务账号来提供凭据。如需了解详情，请参阅为已关联服务账号的资源设置 ADC。

2. 使用 gcloud auth application-default print-access-token 命令将 ADC 返回的访问令牌插入 REST 请求。

   以下示例会获取指定项目的详细信息。您可以对任何 REST 请求使用相同的模式。

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

   • PROJECT_ID：您的 Google Cloud 项目 ID 或名称。

   如需发送请求，请选择以下方式之一：

   curl

   执行以下命令：

   curl -X GET \
        -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
        "https://cloudresourcemanager.googleapis.com/v3/projects/PROJECT_ID"

   PowerShell

   执行以下命令：

   $cred = gcloud auth application-default print-access-token
   $headers = @{ "Authorization" = "Bearer $cred" }
   
   Invoke-WebRequest `
       -Method GET `
       -Headers $headers `
       -Uri "https://cloudresourcemanager.googleapis.com/v3/projects/PROJECT_ID" | Select-Object -Expand Content

   系统会返回项目的详细信息。

   如果您的请求返回有关此 API 不支持最终用户凭据的错误消息，请参阅本页面中的通过 REST 请求设置配额项目。

模拟的服务账号

若要模拟服务账号以生成访问令牌，最简单的方法是使用 gcloud CLI。不过，如果您需要以编程方式生成令牌，或者不想使用 gcloud CLI，则可以使用“冒充”功能生成短期有效的令牌。

如需详细了解如何模拟服务账号，请参阅使用服务账号模拟。

1. 查看所需权限。

   • 您要用于执行模拟的主账号必须对模拟的服务账号（也称为具有权限的服务账号）具有 iam.serviceAccounts.getAccessToken 权限。iam.serviceAccounts.getAccessToken 权限包含在 Service Account Token Creator 角色 (roles/iam.serviceAccountTokenCreator) 中。如果您使用的是用户账号，则需要添加此权限，即使您拥有项目的 Owner 角色 (roles/owner) 也是如此。如需了解详情，请参阅设置所需权限。

2. 确定或创建具有权限的服务账号（您将模拟的服务账号）。

   具有特权的服务账号必须具有进行 API 方法调用所需的权限。

gcloud

1. 使用带有 --impersonate-service-account 标志的 gcloud auth print-access-token 命令，将具有权限的服务账号的访问令牌插入您的 REST 请求中。

以下示例会获取指定项目的详细信息。您可以对任何 REST 请求使用相同的模式。

如需运行此示例，您模拟的服务账号需要 resourcemanager.projects.get 权限。resourcemanager.projects.get 权限包含在若干角色中，例如 Browser 角色 (roles/browser)。

进行以下替换：

• PRIV_SA：具有权限的服务账号的电子邮件地址。例如 [e-mail]。

• PROJECT_ID：您的 Google Cloud 项目 ID 或名称。

curl -X GET \
    -H "Authorization: Bearer $(gcloud auth print-access-token --impersonate-service-account=PRIV_SA)" \
    "https://cloudresourcemanager.googleapis.com/v3/projects/PROJECT_ID"

短期有效的令牌

如需使用服务账号模拟功能生成短期有效令牌，请按照创建短期有效的访问令牌中的说明操作。

元数据服务器

如需从元数据服务器获取访问令牌，您必须使用有权访问元数据服务器的服务进行 REST 调用：

• Compute Engine
• App Engine 标准环境
• App Engine 柔性环境
• Cloud Run 函数
• Cloud Run
• Google Kubernetes Engine
• Cloud Build

您可以使用 curl 等命令行工具获取访问令牌，然后将其插入 REST 请求。

1. 查询元数据服务器以获取访问令牌：

   curl "http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/default/token" \
       -H "Metadata-Flavor: Google"
   

   该请求会返回类似于以下示例的响应：

   {
         "access_token":"ya29.AHES6ZRN3-HlhAPya30GnW_bHSb_QtAi85nHq39HE3C2LTrCARA",
         "expires_in":3599,
         "token_type":"Bearer"
    }
   

2. 将访问令牌插入 REST 请求，进行以下替换：

   • ACCESS_TOKEN：上一步返回的访问令牌。
   • PROJECT_ID：您的 Google Cloud 项目 ID 或名称。

   curl -X GET \
       -H "Authorization: Bearer ACCESS_TOKEN" \
       "https://cloudresourcemanager.googleapis.com/v3/projects/PROJECT_ID"
   

通过 REST 请求设置配额项目

如需使用用户凭据调用某些 API，您还必须设置结算用量并用于跟踪配额的项目。如果您的 API 调用返回错误消息，表示不支持用户凭据或未设置配额项目，则必须为请求明确设置配额项目。如需设置配额项目，请在请求中添加 x-goog-user-project 标头。

如需详细了解何时可能会遇到此问题，请参阅用户凭据不起作用。

您必须拥有项目的 serviceusage.services.use IAM 权限才能将其指定为结算项目。Service Usage Consumer IAM 角色可提供 serviceusage.services.use 权限。如果您没有任何项目的 serviceusage.services.use 权限，请与您的安全管理员或项目所有者联系，他们可以为您授予项目的 Service Usage Consumer 角色。

以下示例使用 Cloud Translation API 将“hello”一词翻译为西班牙语。Cloud Translation API 是一种需要指定配额项目的 API。如需运行该示例，请创建一个名为 request.json 的文件，其中应包含请求正文内容。

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

• PROJECT_ID：用作结算项目的 Google Cloud 项目的 ID 或名称。

请求 JSON 正文：

{
  "q": "hello",
  "source": "en",
  "target": "es"
}

如需发送请求，请选择以下方式之一：

curl

将请求正文保存在名为 request.json 的文件中，然后执行以下命令：

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "x-goog-user-project: PROJECT_ID" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://translation.googleapis.com/language/translate/v2"

PowerShell

将请求正文保存在名为 request.json 的文件中，然后执行以下命令：

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred"; "x-goog-user-project" = "PROJECT_ID" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://translation.googleapis.com/language/translate/v2" | Select-Object -Expand Content

翻译请求发送成功。您可以试试去掉 x-goog-user-project 标头运行该命令，看看如果不指定结算项目会发生什么情况。

后续步骤

• 大致了解身份验证。
• 了解如何使用客户端库进行身份验证。
• 了解 gcloud CLI 身份验证配置和 ADC 配置。