「Retail」は「小売業向け Vertex AI Search」に名称変更されます。現在、新しいブランディングを反映するようにコンテンツの更新を進めています。

このページは Cloud Translation API によって翻訳されました。

Vertex AI Search for Retail に対して認証する

このドキュメントでは、小売業向け Vertex AI Search に対する認証をプログラムで行う方法について説明します。小売業向け Vertex AI Search に対する認証方法は、API へのアクセスに使用するインターフェースと、コードが実行されている環境によって異なります。

Google Cloud の認証の詳細については、認証の概要をご覧ください。

API アクセス

Vertex AI Search for Retail は、プログラムによるアクセスをサポートしています。次の方法で API にアクセスできます。

クライアントライブラリ
REST

クライアントライブラリ

Vertex AI Search for Retail クライアントライブラリは、Vertex AI Search for Retail に対する認証をプログラムで行うための高水準言語のサポートを提供します。Google Cloud APIs の呼び出しを認証するために、クライアントライブラリではアプリケーションのデフォルト認証情報（ADC）がサポートされています。このライブラリは、一連の定義済みのロケーションの中から認証情報を探し、その認証情報を使用して API へのリクエストを認証します。ADC を使用すると、アプリケーションコードを変更することなく、ローカルでの開発や本番環境など、さまざまな環境のアプリケーションで認証情報を使用できるようになります。

REST

Vertex AI Search for retail API の認証には、gcloud CLI 認証情報またはアプリケーションのデフォルト認証情報を使用します。REST リクエストの認証の詳細については、REST を使用して認証するをご覧ください。認証情報の種類については、gcloud CLI の認証情報と ADC の認証情報をご覧ください。

API キー

API キーは、API 呼び出しをプロジェクトに関連付ける方法であり、呼び出し元の身元を特定することなく、請求と割り当てに関する処理を行うのに使用されます。API キーは、API キーをサポートする API メソッドでのみ使用できます。

小売業向け Vertex AI Search は、次の API メソッドで API キーをサポートしています。

userEvents.collect

Vertex AI Search for Retail で API キーを使用する方法については、API キーを作成するをご覧ください。API キーの使用に関する一般的な情報については、API キーを使用して認証するをご覧ください。

Vertex AI Search for Retail のユーザー認証情報と ADC

認証情報を ADC に渡す一つの方法は、gcloud CLI を使用してユーザー認証情報を認証情報ファイルに挿入することです。このファイルは、ADC が検出できるローカルファイルシステムに配置されます。次に、ADC は指定されたユーザー認証情報を使用してリクエストを認証します。多くの場合、この方法はローカルでの開発で使用されます。

この方法では、小売業向け Vertex AI Search の認証時に認証エラーが発生することがあります。このエラーと対処方法の詳細については、ユーザーの認証情報が機能しないをご覧ください。

Vertex AI Search for Retail の認証を設定する

認証の設定方法は、コードが実行されている環境によって異なります。

認証の設定には、次のオプションが最も一般的に使用されます。認証のその他のオプションと詳細については、認証方法をご覧ください。

これらの手順を完了する前に、始める前にで説明されているように、Vertex AI Search for Retail の基本設定を完了する必要があります。

ローカル開発環境の場合

ローカル開発環境の認証情報は、次の方法で設定できます。

クライアントライブラリまたはサードパーティツールのユーザー認証情報
コマンドラインからの REST リクエストに対するユーザー認証情報
サービスアカウントの権限借用

クライアントライブラリまたはサードパーティツール

ローカル環境でアプリケーションのデフォルト認証情報（ADC）を設定します。

Install the Google Cloud CLI, then initialize it by running the following command:
```
gcloud init
```
If you're using a local shell, then create local authentication credentials for your user account:
```
gcloud auth application-default login
```
You don't need to do this if you're using Cloud Shell.
Note: If the gcloud CLI prints a warning that your account doesn't have the serviceusage.services.use permission, then some gcloud CLI commands and client libraries might not work. Ask an administrator to grant you the Service Usage Consumer IAM role (roles/serviceusage.serviceUsageConsumer), then run the following command:
```
gcloud auth application-default set-quota-project PROJECT_ID
```
ログイン画面が表示されます。ログインすると、ADC で使用されるローカル認証情報ファイルに認証情報が保存されます。

ローカル環境での 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 構成をご覧ください。

サービスアカウントの権限借用

ほとんどの場合、ユーザー認証情報を使用してローカル開発環境から認証できます。これが不可能な場合、またはサービスアカウントに割り当てられた権限をテストする必要がある場合は、サービスアカウントの権限借用を使用できます。iam.serviceAccounts.getAccessToken 権限が必要です。この権限は、サービスアカウントトークン作成者（roles/iam.serviceAccountTokenCreator）IAM ロールに含まれています。

サービスアカウントの権限借用を使用するように gcloud CLI を設定するには、gcloud config set コマンドを使用します。

gcloud config set auth/impersonate_service_account SERVICE_ACCT_EMAIL

一部の言語では、サービスアカウントの権限借用を使用して、クライアントライブラリで使用するローカル ADC ファイルを作成できます。このアプローチは、Go、Java、Node.js、Python のクライアントライブラリでのみサポートされています。他の言語ではサポートされていません。サービスアカウントの権限借用を使用してローカル ADC ファイルを設定するには、gcloud auth application-default login コマンドで --impersonate-service-account フラグを使用します。

gcloud auth application-default login --impersonate-service-account=SERVICE_ACCT_EMAIL

サービスアカウントの権限借用の詳細については、サービスアカウントの権限借用を使用するをご覧ください。

Google Cloud

Google Cloud で実行されているワークロードを認証するには、Compute Engine 仮想マシン（VM）インスタンスなど、コードが実行されているコンピューティングリソースにアタッチされているサービスアカウントの認証情報を使用します。このアプローチは、Google Cloud コンピューティングリソースで実行されているコードの推奨認証方法です。

ほとんどのサービスでは、コードを実行するリソースの作成時にサービスアカウントを関連付ける必要があります。サービスアカウントを後から追加または置換することはできません。Compute Engine は例外で、サービスアカウントをいつでも VM インスタンスに関連付けることができます。

gcloud CLI を使用してサービスアカウントを作成し、リソースに接続します。

Install the Google Cloud CLI, then initialize it by running the following command:
```
gcloud init
```
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
コードを実行するリソースを作成し、そのリソースにサービスアカウントを関連付けます。たとえば、Compute Engine を使用する場合は次のようになります。
Create a Compute Engine instance. Configure the instance as follows:
- INSTANCE_NAME を必要なインスタンス名に置き換えます。
- インスタンスを作成するゾーンに --zone フラグを設定します。
- --service-account フラグに、作成したサービスアカウントのメールアドレスを設定します。

Google API に対する認証について詳しくは、認証方法をご覧ください。

オンプレミスまたは別のクラウドプロバイダ

Google Cloud の外部から認証を設定する際の推奨方法は、Workload Identity 連携の使用です。詳細については、認証ドキュメントのオンプレミスまたは他のクラウドプロバイダの ADC を設定するをご覧ください。

Vertex AI Search for Retail のアクセス制御

小売業向け Vertex AI Search に対する認証を行った後、Google Cloud リソースへのアクセスが許可されている必要があります。小売業向け Vertex AI Search は、Identity and Access Management（IAM）を使用して認可を行います。

小売業向け Vertex AI Search のロールの詳細については、Identity and Access Management（IAM）をご覧ください。 IAM と認可の詳細については、IAM の概要をご覧ください。

次のステップ

Google Cloud の認証方法を確認する。
認証のユースケースを確認する。