設定呼叫 Gemini Enterprise Agent Platform LLM 的生成式 AI 函式權限

控制台

1. 前往 Cloud de Confiance 控制台的「IAM」(身分與存取權管理) 頁面。

   前往「IAM」頁面

2. 選取專案。

3. 如要將角色授予主體，請按照下列步驟操作：

   1. 前往「IAM & Admin」(IAM 與管理) 頁面。

      前往「IAM & Admin」(IAM 與管理)

   2. 按一下 person_add「授予存取權」。

      「新增主體」對話方塊隨即開啟。

   3. 在「New principals」(新增主體) 欄位中，輸入主體 ID，例如 //iam.googleapis.com/locations/global/workforcePools/my-pool/subject/my-user@example.com 或 //iam.googleapis.com/locations/global/workforcePools/example-pool/group/example-group@example.com。

   4. 在「指派角色」部分，點選「請選擇角色」的下拉式箭頭。

   5. 搜尋並選取「Agent Platform 使用者」角色。

   6. 按一下 [Add another role] (新增其他角色)。

   7. 在「指派角色」部分，點選「請選擇角色」的下拉式箭頭。

   8. 搜尋或瀏覽至「BigQuery 工作使用者」角色，然後選取該角色。

   9. 按一下 [儲存]。

      

SQL

使用 GRANT 陳述式：

1. 前往 Cloud de Confiance 控制台的「BigQuery」頁面。

   前往「BigQuery」

2. 在查詢編輯器中輸入下列陳述式：

   GRANT `roles/aiplatform.user`, `roles/bigquery.jobUser`
   ON PROJECT `PROJECT_ID`
   TO "USER_OR_GROUP";

   請替換下列項目：

   • PROJECT_ID：您打算使用 AI.* 函式的專案。
   • USER_OR_GROUP：要授予存取權的使用者或群組，格式為 user:USER@DOMAIN 或 group:GROUP@DOMAIN。

3. 按一下「執行」play_circle。

如要進一步瞭解如何執行查詢，請參閱「執行互動式查詢」。

控制台

1. 前往「BigQuery」頁面。

   前往「BigQuery」

2. 點選左側窗格中的 explore「Explorer」。

   

   如果沒有看到左側窗格，請按一下 last_page「Expand left pane」(展開左側窗格)，開啟窗格。

3. 在「Explorer」窗格中展開專案名稱，然後按一下「Connections」。

4. 在「Connections」(連線) 頁面中，按一下「Create connection」(建立連線)。

5. 在「連線類型」中，選擇「Vertex AI 遠端模型、遠端函式、BigLake 和 Spanner (Cloud 資源)」。

6. 在「連線 ID」欄位中，輸入連線名稱。

7. 針對「位置類型」，選取連線位置。連線應與其他資源 (例如資料集) 位於同一位置。

8. 點選「建立連線」。

9. 點選「前往連線」。

10. 在「連線資訊」窗格中，複製服務帳戶 ID，以便在後續步驟中使用。

SQL

使用 CREATE CONNECTION 陳述式：

1. 前往 Cloud de Confiance 控制台的「BigQuery」頁面。

   前往「BigQuery」

2. 在查詢編輯器中輸入下列陳述式：

   CREATE CONNECTION [IF NOT EXISTS] `CONNECTION_NAME`
   OPTIONS (
     connection_type = "CLOUD_RESOURCE",
     friendly_name = "FRIENDLY_NAME",
     description = "DESCRIPTION"
     );

   請替換下列項目：

   • CONNECTION_NAME：連線名稱，格式為 PROJECT_ID.LOCATION.CONNECTION_ID、LOCATION.CONNECTION_ID 或 CONNECTION_ID。如果省略專案或位置，系統會從執行陳述式的專案和位置推斷。
   • FRIENDLY_NAME (選用)：連線的描述性名稱。
   • DESCRIPTION (選用)：連線說明。

3. 按一下「執行」play_circle。

如要進一步瞭解如何執行查詢，請參閱「執行互動式查詢」。

bq

1. 在指令列環境中建立連線：

   bq mk --connection --location=REGION --project_id=PROJECT_ID \
       --connection_type=CLOUD_RESOURCE CONNECTION_ID

   --project_id 參數會覆寫預設專案。

   更改下列內容：

   • REGION：您的連線區域
   • PROJECT_ID：您的 Cloud de Confiance 專案 ID
   • CONNECTION_ID：連線的 ID

   建立連線資源時，BigQuery 會建立專屬的系統服務帳戶，並將其與連線建立關聯。

   疑難排解：如果收到下列連線錯誤訊息，請更新 Google Cloud SDK：

   Flags parsing error: flag --connection_type=CLOUD_RESOURCE: value should be one of...
   

2. 擷取並複製服務帳戶 ID，以供後續步驟使用：

   bq show --connection PROJECT_ID.REGION.CONNECTION_ID

   輸出結果會與下列內容相似：

   name                          properties
   1234.REGION.CONNECTION_ID     {"serviceAccountId": "connection-1234-9u56h9@gcp-sa-bigquery-condel.s3ns-system.iam.gserviceaccount.com"}
   

Python

import google.api_core.exceptions
from google.cloud import bigquery_connection_v1

client = bigquery_connection_v1.ConnectionServiceClient()


def create_connection(
    project_id: str,
    location: str,
    connection_id: str,
):
    """Creates a BigQuery connection to a Cloud Resource.

    Cloud Resource connection creates a service account which can then be
    granted access to other Google Cloud resources for federated queries.

    Args:
        project_id: The Google Cloud project ID.
        location: The location of the connection (for example, "us-central1").
        connection_id: The ID of the connection to create.
    """

    parent = client.common_location_path(project_id, location)

    connection = bigquery_connection_v1.Connection(
        friendly_name="Example Connection",
        description="A sample connection for a Cloud Resource.",
        cloud_resource=bigquery_connection_v1.CloudResourceProperties(),
    )

    try:
        created_connection = client.create_connection(
            parent=parent, connection_id=connection_id, connection=connection
        )
        print(f"Successfully created connection: {created_connection.name}")
        print(f"Friendly name: {created_connection.friendly_name}")
        print(
            f"Service Account: {created_connection.cloud_resource.service_account_id}"
        )

    except google.api_core.exceptions.AlreadyExists:
        print(f"Connection with ID '{connection_id}' already exists.")
        print("Please use a different connection ID.")
    except Exception as e:
        print(f"An unexpected error occurred while creating the connection: {e}")

Node.js

const {ConnectionServiceClient} =
  require('@google-cloud/bigquery-connection').v1;
const {status} = require('@grpc/grpc-js');

const client = new ConnectionServiceClient();

/**
 * Creates a new BigQuery connection to a Cloud Resource.
 *
 * A Cloud Resource connection creates a service account that can be granted access
 * to other Google Cloud resources.
 *
 * @param {string} projectId The Google Cloud project ID. for example, 'example-project-id'
 * @param {string} location The location of the project to create the connection in. for example, 'us-central1'
 * @param {string} connectionId The ID of the connection to create. for example, 'example-connection-id'
 */
async function createConnection(projectId, location, connectionId) {
  const parent = client.locationPath(projectId, location);

  const connection = {
    friendlyName: 'Example Connection',
    description: 'A sample connection for a Cloud Resource',
    // The service account for this cloudResource will be created by the API.
    // Its ID will be available in the response.
    cloudResource: {},
  };

  const request = {
    parent,
    connectionId,
    connection,
  };

  try {
    const [response] = await client.createConnection(request);

    console.log(`Successfully created connection: ${response.name}`);
    console.log(`Friendly name: ${response.friendlyName}`);

    console.log(`Service Account: ${response.cloudResource.serviceAccountId}`);
  } catch (err) {
    if (err.code === status.ALREADY_EXISTS) {
      console.log(`Connection '${connectionId}' already exists.`);
    } else {
      console.error(`Error creating connection: ${err.message}`);
    }
  }
}

Terraform

請使用 google_bigquery_connection 資源。

如要向 BigQuery 進行驗證，請設定應用程式預設憑證。詳情請參閱「設定用戶端程式庫的驗證作業」。

下列範例會在 US 區域中建立名為 my_cloud_resource_connection 的 Cloud 資源連結：

# This queries the provider for project information.
data "google_project" "default" {}

# This creates a cloud resource connection in the US region named my_cloud_resource_connection.
# Note: The cloud resource nested object has only one output field - serviceAccountId.
resource "google_bigquery_connection" "default" {
  connection_id = "my_cloud_resource_connection"
  project       = data.google_project.default.project_id
  location      = "US"
  cloud_resource {}
}

如要在 Cloud de Confiance 專案中套用 Terraform 設定，請完成下列各節的步驟。

準備 Cloud Shell

1. 啟動 Cloud Shell。

2. 設定要套用 Terraform 設定的預設 Cloud de Confiance 專案。

   每項專案只需要執行一次這個指令，且可以在任何目錄中執行。

   export GOOGLE_CLOUD_PROJECT=PROJECT_ID

   如果您在 Terraform 設定檔中設定明確值，環境變數就會遭到覆寫。

準備目錄

每個 Terraform 設定檔都必須有自己的目錄 (也稱為根模組)。

1. 在 Cloud Shell 中建立目錄，並在該目錄中建立新檔案。檔案名稱的副檔名必須是 .tf，例如 main.tf。在本教學課程中，這個檔案稱為 main.tf。

   mkdir DIRECTORY && cd DIRECTORY && touch main.tf

2. 如果您正在學習教學課程，可以複製每個章節或步驟中的程式碼範例。

   將程式碼範例複製到新建立的 main.tf 中。

   視需要從 GitHub 複製程式碼。如果 Terraform 代码片段是端對端解決方案的一部分，建議您這麼做。

3. 查看並修改範例參數，套用至您的環境。
4. 儲存變更。
5. 初始化 Terraform。每個目錄只需執行一次這項操作。

   terraform init

   如要使用最新版 Google 供應商，請加入 -upgrade 選項：

   terraform init -upgrade

套用變更

1. 查看設定，確認 Terraform 即將建立或更新的資源符合您的預期：

   terraform plan

   視需要修正設定。

2. 執行下列指令並在提示中輸入 yes，套用 Terraform 設定：

   terraform apply

   等待 Terraform 顯示「Apply complete!」訊息。

3. 開啟 Cloud de Confiance 專案，查看結果。在 Cloud de Confiance 控制台中，前往 UI 中的資源，確認 Terraform 已建立或更新這些資源。

控制台

1. 前往「IAM & Admin」(IAM 與管理) 頁面。

   前往「IAM & Admin」(IAM 與管理)

2. 按一下 person_add「授予存取權」。

   「新增主體」對話方塊隨即開啟。

3. 在「新增主體」欄位，輸入先前複製的服務帳戶 ID。

4. 在「指派角色」部分，按一下「新增角色」。

5. 搜尋「Agent Platform User」角色並選取，然後按一下「套用」。

6. 按一下 [儲存]。

SQL

使用 GRANT 陳述式：

1. 前往 Cloud de Confiance 控制台的「BigQuery」頁面。

   前往「BigQuery」

2. 在查詢編輯器中輸入下列陳述式：

   GRANT `roles/aiplatform.user`
   ON PROJECT `PROJECT_ID`
   TO "connection:CONNECTION_NAME";

   請替換下列項目：

   • PROJECT_ID：您打算使用 Agent Platform 的專案。
   • CONNECTION_NAME：連線名稱，格式為 PROJECT_ID.LOCATION.CONNECTION_ID 或 LOCATION.CONNECTION_ID。如果省略專案，系統會從執行陳述式的專案推斷。

3. 按一下「執行」play_circle。

如要進一步瞭解如何執行查詢，請參閱「執行互動式查詢」。

gcloud

使用 gcloud projects add-iam-policy-binding 指令：

gcloud projects add-iam-policy-binding PROJECT_ID \
--member="serviceAccount:$(bq show --format=prettyjson --connection $PROJECT_ID.$REGION.$CONNECTION_ID | jq -r .cloudResource.serviceAccountId)"
--role=roles/aiplatform.user

更改下列內容：

• PROJECT_ID：專案名稱。
• REGION：建立連線的位置。
• CONNECTION_ID：您建立的連線名稱。

Terraform

請使用 google_bigquery_connection 資源。

如要向 BigQuery 進行驗證，請設定應用程式預設憑證。詳情請參閱「設定用戶端程式庫的驗證作業」。

以下範例會將 IAM 角色存取權授予 Cloud 資源連結的服務帳戶：

## This grants IAM role access to the service account of the connection created in the previous step.
resource "google_project_iam_member" "aiplatformpermission" {
  project = data.google_project.default.project_id
  role    = "roles/aiplatform.user"
  member  = "serviceAccount:${google_bigquery_connection.default.cloud_resource[0].service_account_id}"
}

如要在 Cloud de Confiance 專案中套用 Terraform 設定，請完成下列各節的步驟。

準備 Cloud Shell

1. 啟動 Cloud Shell。

2. 設定要套用 Terraform 設定的預設 Cloud de Confiance 專案。

   每項專案只需要執行一次這個指令，且可以在任何目錄中執行。

   export GOOGLE_CLOUD_PROJECT=PROJECT_ID

   如果您在 Terraform 設定檔中設定明確值，環境變數就會遭到覆寫。

準備目錄

每個 Terraform 設定檔都必須有自己的目錄 (也稱為根模組)。

1. 在 Cloud Shell 中建立目錄，並在該目錄中建立新檔案。檔案名稱的副檔名必須是 .tf，例如 main.tf。在本教學課程中，這個檔案稱為 main.tf。

   mkdir DIRECTORY && cd DIRECTORY && touch main.tf

2. 如果您正在學習教學課程，可以複製每個章節或步驟中的程式碼範例。

   將程式碼範例複製到新建立的 main.tf 中。

   視需要從 GitHub 複製程式碼。如果 Terraform 代码片段是端對端解決方案的一部分，建議您這麼做。

3. 查看並修改範例參數，套用至您的環境。
4. 儲存變更。
5. 初始化 Terraform。每個目錄只需執行一次這項操作。

   terraform init

   如要使用最新版 Google 供應商，請加入 -upgrade 選項：

   terraform init -upgrade

套用變更

1. 查看設定，確認 Terraform 即將建立或更新的資源符合您的預期：

   terraform plan

   視需要修正設定。

2. 執行下列指令並在提示中輸入 yes，套用 Terraform 設定：

   terraform apply

   等待 Terraform 顯示「Apply complete!」訊息。

3. 開啟 Cloud de Confiance 專案，查看結果。在 Cloud de Confiance 控制台中，前往 UI 中的資源，確認 Terraform 已建立或更新這些資源。