向 Vertex AI Search for Retail 进行身份验证

本文档介绍了如何以编程方式向 Vertex AI Search for Retail 进行身份验证。如何向 Vertex AI Search for Retail 进行身份验证，取决于您用于访问该 API 的界面以及运行代码的环境。

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

API 访问权限

适用于零售的 Vertex AI Search 支持程序化访问。您可以通过以下方式访问 API：

• 客户端库
• REST

客户端库

面向零售业的 Vertex AI Search 客户端库提供了高级语言支持，以便以编程方式向适用于零售业的 Vertex AI Search 进行身份验证。 为了对 Google Cloud API 的调用进行身份验证，客户端库支持应用默认凭据 (ADC)；这些库会在一组定义的位置查找凭据，并使用这些凭据对发送到 API 的请求进行身份验证。借助 ADC，您可以在各种环境（例如本地开发或生产环境）中为您的应用提供凭据，而无需修改应用代码。

REST

您可以使用 gcloud CLI 凭据或使用应用默认凭据向 Vertex AI Search for Retail API 进行身份验证。如需详细了解 REST 请求身份验证，请参阅使用 REST 时进行身份验证。如需了解凭据类型，请参阅 gcloud CLI 凭据和 ADC 凭据。

API 密钥

API 密钥提供了一种将 API 调用与项目相关联的方法，用于结算和配额目的，而无需确定调用者的身份。API 密钥只能用于支持 API 密钥的 API 方法。

适用于零售的 Vertex AI Search 支持为以下 API 方法使用 API 密钥：

• userEvents.collect

如需详细了解如何将 API 密钥与适用于零售的 Vertex AI Search 搭配使用，请参阅创建 API 密钥。 如需了解有关使用 API 密钥的一般信息，请参阅使用 API 密钥进行身份验证。

Vertex AI Search for Retail 的用户凭据和 ADC

向 ADC 提供凭据的一种方法是使用 gcloud CLI 将您的用户凭据插入凭据文件中。此文件位于本地文件系统上，ADC 可以找到它。然后，ADC 使用提供的用户凭据对请求进行身份验证。此方法通常用于本地开发。

如果您使用此方法，在尝试向 Vertex AI Search for Retail 进行身份验证时可能会遇到身份验证错误。如需详细了解此错误及其解决方法，请参阅用户凭据不起作用。

为 Vertex AI Search for Retail 设置身份验证

设置身份验证的方式取决于代码在其中运行的环境。

以下是最常用的身份验证设置选项。如需了解有关身份验证的更多选项和信息，请参阅在 Google 进行身份验证。

在完成这些说明之前，您必须按照准备工作中所述完成 Vertex AI Search for Retail 的基本设置。

对于本地开发环境

您可以通过以下方式为本地开发环境设置凭据：

• 客户端库或第三方工具的用户凭据
• 从命令行发出的 REST 请求的用户凭据

客户端库或第三方工具

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

1. 安装 Google Cloud CLI，然后通过运行以下命令初始化 Google Cloud CLI：

   gcloud init

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

   gcloud auth application-default login

   注意：如果 gcloud CLI 输出警告，提示您的账号没有 serviceusage.services.use 权限，则某些 gcloud CLI 命令和客户端库可能无法正常运行。请让管理员授予您 Service Usage Consumer IAM 角色 (roles/serviceusage.serviceUsageConsumer)，然后运行以下命令：

   gcloud auth application-default set-quota-project PROJECT_ID

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

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

从命令行发出的 REST 请求

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

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

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

• PROJECT_ID：您的 Google Cloud 项目 ID。

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

curl（Linux、macOS 或 Cloud Shell）

执行以下命令：

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "x-goog-user-project: PROJECT_ID" \
     "https://iam.googleapis.com/v1/projects/PROJECT_ID/serviceAccounts"

PowerShell (Windows)

执行以下命令：

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

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://iam.googleapis.com/v1/projects/PROJECT_ID/serviceAccounts" | Select-Object -Expand Content

 

如需详细了解如何使用 REST 和 gRPC 进行身份验证，请参阅使用 REST 时进行身份验证。如需了解本地 ADC 凭据与 gcloud CLI 凭据之间的区别，请参阅 gcloud CLI 凭据和 ADC 凭据。

在 Google Cloud 上

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

对于大多数服务，您必须在创建将运行代码的资源时关联服务账号；您之后无法添加或替换服务账号。Compute Engine 是一个例外，它允许您随时将服务账号关联到虚拟机实例。

使用 gcloud CLI 创建服务账号并将其关联到您的资源：

1. 安装 Google Cloud CLI，然后通过运行以下命令初始化 Google Cloud CLI：

   gcloud init

2. Set up authentication:

   1. Create the service account:

      gcloud iam service-accounts create SERVICE_ACCOUNT_NAME

      Replace SERVICE_ACCOUNT_NAME with a name for the service account.

   2. To provide access to your project and your resources, grant a role to the service account:

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

      Replace the following:

      • SERVICE_ACCOUNT_NAME: the name of the service account
      • PROJECT_ID: the project ID where you created the service account
      • ROLE: the role to grant
      Note: The --role flag affects which resources the service account can access in your project. You can revoke these roles or grant additional roles later. In production environments, do not grant the Owner, Editor, or Viewer roles. Instead, grant a predefined role or custom role that meets your needs.
   3. To grant another role to the service account, run the command as you did in the previous step.

   4. Grant the required role to the principal that will attach the service account to other resources.

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

      Replace the following:

      • SERVICE_ACCOUNT_NAME: the name of the service account
      • PROJECT_ID: the project ID where you created the service account
      • USER_EMAIL: the email address for a Google Account

3. 创建将运行代码的资源，并将服务账号关联到该资源。例如，如果您使用 Compute Engine：

   Create a Compute Engine instance. Configure the instance as follows:
   • 将 INSTANCE_NAME 替换为您偏好的实例名称。
   • 将 --zone 标志设置为您要在其中创建实例的可用区。
   • 将 --service-account 标志设置为您创建的服务账号的电子邮件地址。

   gcloud compute instances create INSTANCE_NAME --zone=ZONE --service-account=SERVICE_ACCOUNT_EMAIL

如需详细了解如何向 Google API 进行身份验证，请参阅在 Google 进行身份验证。

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

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

适用于 Vertex AI Search for Retail 的访问权限控制

向 Vertex AI Search for Retail 进行身份验证后，您必须有权访问 Google Cloud 资源。适用于零售的 Vertex AI Search 使用 Identity and Access Management (IAM) 进行授权。

如需详细了解 Vertex AI Search for Retail 的角色，请参阅 Identity and Access Management (IAM)。如需详细了解 IAM 和授权，请参阅 IAM 概览。

后续步骤

• 了解 Google Cloud 身份验证方法。
• 请参阅身份验证使用场景列表。