建立物件資料表

本文說明如何建立物件資料表，以便在 BigQuery 中存取 Cloud Storage 的非結構化資料。

如要建立物件資料表，您必須完成下列工作：

1. 建立資料集，用於存放物件資料表。
2. 建立連線，從 Cloud Storage 讀取物件資訊。
3. 將 Storage 物件檢視者 (roles/storage.objectViewer) 角色授予與連線相關聯的服務帳戶。
4. 使用 CREATE EXTERNAL TABLE 陳述式建立物件資料表，並與連線建立關聯。

事前準備

登入 Google Cloud 帳戶。如果您未曾使用過 Google Cloud，歡迎 建立帳戶，親自體驗實際使用我們產品的成效。新客戶還能獲得價值 $300 美元的免費抵免額，用於執行、測試及部署工作負載。

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the BigQuery and BigQuery Connection API APIs, if any are not already enabled.

Roles required to enable APIs

To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

Enable the APIs

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the BigQuery and BigQuery Connection API APIs, if any are not already enabled.

Roles required to enable APIs

To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

Enable the APIs

必要的角色

如要建立物件資料表，您必須具備下列專案角色：

• 如要建立資料集和資料表，您必須具備 BigQuery 資料編輯者 (roles/bigquery.dataEditor) 角色。
• 如要建立連線，您必須具備 BigQuery 連線管理員 (roles/bigquery.connectionAdmin) 角色。
• 如要為連線的服務帳戶授予角色，您必須具備專案 IAM 管理員 (roles/resourcemanager.projectIamAdmin) 角色。

如要查詢物件資料表，您必須具備下列專案角色：

• BigQuery 資料檢視者 (roles/bigquery.dataViewer) 角色
• BigQuery 連線使用者 (roles/bigquery.connectionUser) 角色

如要查看確切的必要權限，請展開「Required permissions」(必要權限) 部分：

所需權限

• bigquery.datasets.create
• bigquery.tables.create
• bigquery.tables.update
• bigquery.connections.create
• bigquery.connections.get
• bigquery.connections.list
• bigquery.connections.update
• bigquery.connections.use
• bigquery.connections.delete
• bigquery.connections.delegate
• storage.bucket.*
• storage.object.*
• bigquery.jobs.create
• bigquery.tables.get
• bigquery.tables.getData
• bigquery.readsessions.create

您或許還可透過自訂角色或其他預先定義的角色取得這些權限。

注意：如果使用者只需查詢資料，則「不應」具備下列權限：

• Storage 物件檢視者角色授予的權限，可直接從 Cloud Storage 讀取物件。
• 將資料表繫結至連線的能力，由 BigQuery 連線管理員角色授予。

否則，使用者可以建立沒有任何存取控管機制的新物件資料表，藉此規避資料倉儲管理員設定的控管機制。

建立資料集

建立 BigQuery 資料集，用於存放物件資料表：

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

   前往「BigQuery」

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

   

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

3. 在「Explorer」窗格中，點選專案名稱。

4. 依序點選 「View actions」(查看動作) >「Create dataset」(建立資料集)。

5. 在「Create dataset」(建立資料集) 頁面執行下列操作：

   1. 在「資料集 ID」部分，輸入資料集名稱。

   2. 在「位置類型」部分，選取「區域」或「多區域」。

      • 如果選取「Region」(區域)，請從「Region」(區域) 清單中選取位置。
      • 如果選取「Multi-region」(多區域)，請從「Multi-region」(多區域) 清單中選取「US」(美國) 或「Europe」(歐洲)。

   3. 點選「建立資料集」。

建立連線

如果您已設定預設連線，或具備 BigQuery 管理員角色，則可略過這個步驟。

為物件資料表建立要使用的 Cloud 資源連結，並取得連結的服務帳戶。

1. 前往「BigQuery」頁面

   前往「BigQuery」

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

   

3. 在「Explorer」窗格中，點選「 新增資料」。

   「新增資料」對話方塊隨即開啟。

4. 在「篩選依據」窗格的「資料來源類型」部分，選取「業務應用程式」。

   或者，您也可以在「Search for data sources」(搜尋資料來源) 欄位中輸入 Vertex AI。

5. 在「精選資料來源」部分，點選「Vertex AI」。

6. 點選「Vertex AI Models: BigQuery Federation」解決方案資訊卡。

7. 在「Connection type」(連線類型) 清單中，選取「Vertex AI remote models, remote functions, BigLake and Spanner (Cloud Resource)」(Vertex AI 遠端模型、遠端函式、BigLake 和 Spanner (Cloud 資源))。

8. 在「Connection ID」(連線 ID) 欄位中，輸入連線名稱。

9. 在「位置類型」部分，選取「區域」或「多區域」。

   • 如果選取「Region」(區域)，請從「Region」(區域) 清單中選取位置。
   • 如果選取「Multi-region」(多區域)，請從「Multi-region」(多區域) 清單中選取「US」(美國) 或「Europe」(歐洲)。

10. 點選「建立連線」。

11. 點選「前往連線」。

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

授予服務帳戶存取權

為連線的服務帳戶授予 Storage 物件檢視者角色：

控制台

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

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

2. 按一下「 新增」。

   「Add principals」(新增主體) 對話方塊隨即開啟。

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

4. 在「Select a role」(請選擇角色) 欄位中，依序選取「Cloud Storage」和「Storage Object Viewer」(Storage 物件檢視者)。

5. 按一下 [儲存]。

gcloud

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

gcloud projects add-iam-policy-binding 'PROJECT_NUMBER' --member='serviceAccount:MEMBER' --role='roles/storage.objectViewer' --condition=None

替換下列內容：

• PROJECT_NUMBER：要授予角色的專案編號。
• MEMBER：您先前複製的服務帳戶 ID。

建立物件資料表

如要建立物件資料表，請按照下列步驟操作：

SQL

使用 CREATE EXTERNAL TABLE 陳述式。

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

   前往「BigQuery」

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

   CREATE EXTERNAL TABLE `PROJECT_ID.DATASET_ID.TABLE_NAME`
   WITH CONNECTION {`PROJECT_ID.REGION.CONNECTION_ID`| DEFAULT}
   OPTIONS(
     object_metadata = 'SIMPLE',
     uris = ['BUCKET_PATH'[,...]],
     max_staleness = STALENESS_INTERVAL,
     metadata_cache_mode = 'CACHE_MODE');

   替換下列內容：

   • PROJECT_ID：您的專案 ID。
   • DATASET_ID：要包含物件資料表的資料集 ID。
   • TABLE_NAME：物件資料表的名稱。
   • REGION：連線所在的區域或多區域。
   • CONNECTION_ID：要與這個物件資料表搭配使用的 Cloud 資源連結 ID。連線會決定要使用哪個服務帳戶從 Cloud Storage 讀取資料。

     在 Google Cloud 控制台查看連線詳細資料時，連線 ID 是「Connection ID」(連線 ID) 中顯示的完整連線 ID 最後一個部分的值，例如 projects/myproject/locations/connection_location/connections/myconnection。

     如要使用 預設連線，請指定 DEFAULT，而非包含 PROJECT_ID.REGION.CONNECTION_ID 的連線字串。

   • BUCKET_PATH：Cloud Storage bucket 的路徑，其中包含物件資料表代表的物件，格式為 ['gs://bucket_name/[folder_name/]*']。

     您可以在每個路徑中使用一個星號 (*) 萬用字元，限制物件資料表包含的物件。舉例來說，如果 bucket 包含多種非結構化資料，您可以指定 ['gs://bucket_name/*.pdf']，只針對 PDF 物件建立物件資料表。詳情請參閱「Cloud Storage URI 的萬用字元支援」。

     您可以提供多個路徑，為 uris 選項指定多個 bucket，例如 ['gs://mybucket1/*', 'gs://mybucket2/folder5/*']。為達到最佳效能，每個物件資料表最多只能指定 10 個 URI。如果提供超過 10 個 bucket URI，物件資料表可支援的檔案總數會減少。

     如要進一步瞭解如何在 BigQuery 中使用 Cloud Storage URI，請參閱「Cloud Storage 資源路徑」。

   • STALENESS_INTERVAL：指定對物件資料表執行的作業是否使用快取中繼資料，以及快取中繼資料必須有多新，作業才能使用。如要進一步瞭解中繼資料快取注意事項，請參閱「中繼資料快取效能」。

     如要停用中繼資料快取功能，請指定 0。這是目前的預設做法。

     如要啟用中繼資料快取功能，請指定介於 30 分鐘至 7 天之間的間隔常值。舉例來說，如要指定 4 小時的過時時間間隔，請指定 INTERVAL 4 HOUR。如果中繼資料在過去 4 小時內重新整理過，系統會使用快取的中繼資料，對資料表執行作業。如果快取的中繼資料超過這個時間，作業就會改為從 Cloud Storage 擷取中繼資料。

   • CACHE_MODE：指定中繼資料快取要自動或手動重新整理。如要進一步瞭解中繼資料快取注意事項，請參閱「中繼資料快取效能」。

     設為 AUTOMATIC，中繼資料快取就會按照系統定義的間隔重新整理，通常介於 30 到 60 分鐘之間。

     如要按照指定時間表重新整理中繼資料快取，請設為 MANUAL。在這種情況下，您可以呼叫 BQ.REFRESH_EXTERNAL_METADATA_CACHE 系統程序來重新整理快取。

     如果 STALENESS_INTERVAL 設為大於 0 的值，則必須設定 CACHE_MODE。

3. 按一下「 執行」。

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

範例

下列範例會建立物件資料表，中繼資料快取過時時間間隔為 1 天：

CREATE EXTERNAL TABLE `my_dataset.object_table`
WITH CONNECTION `us.my-connection`
OPTIONS(
  object_metadata = 'SIMPLE',
  uris = ['gs://mybucket/*'],
  max_staleness = INTERVAL 1 DAY,
  metadata_cache_mode = 'AUTOMATIC'
);

下列範例會針對三個 Cloud Storage bucket 中的物件建立物件資料表：

CREATE EXTERNAL TABLE `my_dataset.object_table`
WITH CONNECTION `us.my-connection`
OPTIONS(
  object_metadata = 'SIMPLE',
  uris = ['gs://bucket1/*','gs://bucket2/folder1/*','gs://bucket3/*']
);

下列範例會針對 Cloud Storage bucket 中的 PDF 物件建立物件資料表：

CREATE EXTERNAL TABLE `my_dataset.object_table`
WITH CONNECTION `us.my-connection`
OPTIONS(
  object_metadata = 'SIMPLE',
  uris = ['gs://bucket1/*.pdf']
);

bq

使用 bq mk 指令。

bq mk --table \
--external_table_definition=[e-mail]_ID \
--object_metadata=SIMPLE \
--max_staleness=STALENESS_INTERVAL \
--metadata_cache_mode=CACHE_MODE \
PROJECT_ID:DATASET_ID.TABLE_NAME

替換下列內容：

• PROJECT_ID：您的專案 ID。
• DATASET_ID：要包含物件資料表的資料集 ID。
• TABLE_NAME：物件資料表的名稱。
• REGION：連線所在的區域或多區域。
• CONNECTION_ID：要與這個外部資料表搭配使用的 Cloud 資源連結 ID。連線會決定要使用哪個服務帳戶從 Cloud Storage 讀取資料。

  在 Google Cloud 控制台查看連線詳細資料時，連線 ID 是「Connection ID」(連線 ID) 中顯示的完整連線 ID 最後一個部分的值，例如 projects/myproject/locations/connection_location/connections/myconnection。

• BUCKET_PATH：Cloud Storage bucket 的路徑，其中包含物件資料表代表的物件，格式為 gs://bucket_name/[folder_name/]*。

  您可以在每個路徑中使用一個星號 (*) 萬用字元，限制物件資料表包含的物件。舉例來說，如果 bucket 包含多種非結構化資料，您可以指定 gs://bucket_name/*.pdf，只針對 PDF 物件建立物件資料表。詳情請參閱「Cloud Storage URI 的萬用字元支援」。

  您可以提供多個路徑，為 uris 選項指定多個 bucket，例如 gs://mybucket1/*,gs://mybucket2/folder5/*。

  如要進一步瞭解如何在 BigQuery 中使用 Cloud Storage URI，請參閱「Cloud Storage 資源路徑」。

• STALENESS_INTERVAL：指定針對物件資料表執行的作業是否使用快取中繼資料，以及快取中繼資料必須有多新，作業才能使用。如要進一步瞭解中繼資料快取注意事項，請參閱「中繼資料快取效能」。

  如要停用中繼資料快取功能，請指定 0。這是目前的預設做法。

  如要啟用中繼資料快取功能，請指定 30 分鐘到 7 天之間的間隔值，並使用INTERVAL 資料類型說明文件中所述的 Y-M D H:M:S 格式。舉例來說，如要指定 4 小時的過時時間間隔，請指定 0-0 0 4:0:0。如果中繼資料在過去 4 小時內重新整理過，系統會使用快取的中繼資料，對資料表執行作業。如果快取的中繼資料超過這個時間，作業就會改為從 Cloud Storage 擷取中繼資料。

• CACHE_MODE：指定中繼資料快取要自動或手動重新整理。如要進一步瞭解中繼資料快取注意事項，請參閱「中繼資料快取效能」。

  設為 AUTOMATIC，中繼資料快取就會按照系統定義的間隔重新整理，通常介於 30 到 60 分鐘之間。

  如要按照指定時間表重新整理中繼資料快取，請設為 MANUAL。在這種情況下，您可以呼叫 BQ.REFRESH_EXTERNAL_METADATA_CACHE 系統程序來重新整理快取。

  如果 STALENESS_INTERVAL 設為大於 0 的值，則必須設定 CACHE_MODE。

範例

下列範例會建立物件資料表，中繼資料快取過時時間間隔為 1 天：

bq mk --table \
--external_table_definition=gs://mybucket/*@us.my-connection \
--object_metadata=SIMPLE \
--max_staleness=0-0 1 0:0:0 \
--metadata_cache_mode=AUTOMATIC \
my_dataset.object_table

下列範例會針對三個 Cloud Storage bucket 中的物件建立物件資料表：

bq mk --table \
--external_table_definition=gs://bucket1/*,gs://bucket2/folder1/*,gs://bucket3/*@us.my-connection \
--object_metadata=SIMPLE \
my_dataset.object_table

下列範例會針對 Cloud Storage bucket 中的 PDF 物件建立物件資料表：

bq mk --table \
--external_table_definition=gs://bucket1/*[e-mail]-connection \
--object_metadata=SIMPLE \
my_dataset.object_table

API

呼叫 tables.insert 方法。在傳入的 Table 資源中，加入 ExternalDataConfiguration 物件，並將 objectMetadata 欄位設為 SIMPLE。

以下範例說明如何使用 curl 呼叫這個方法：

ACCESS_TOKEN=$(gcloud auth print-access-token) curl \
-H "Authorization: Bearer ${ACCESS_TOKEN}" \
-H "Content-Type: application/json" \
-X POST \
-d '{"tableReference": {"projectId": "my_project", "datasetId": "my_dataset", "tableId": "object_table_name"}, "externalDataConfiguration": {"objectMetadata": "SIMPLE", "sourceUris": ["gs://mybucket/*"]}}' \
https://www.googleapis.com/bigquery/v2/projects/my_project/datasets/my_dataset/tables

Terraform

這個範例會建立物件資料表，並啟用中繼資料快取功能，以及手動重新整理。

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

物件資料表要指定的索引鍵欄位為 google_bigquery_table.external_data_configuration.object_metadata、google_bigquery_table.external_data_configuration.metadata_cache_mode 和 google_bigquery_table.max_staleness。如要進一步瞭解各項資源，請參閱 Terraform BigQuery 說明文件。

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

# This creates a connection in the US region named "my-connection-id".
# This connection is used to access the bucket.
resource "google_bigquery_connection" "default" {
  connection_id = "my-connection-id"
  location      = "US"
  cloud_resource {}
}

# This grants the previous connection IAM role access to the bucket.
resource "google_project_iam_member" "default" {
  role    = "roles/storage.objectViewer"
  project = data.google_project.default.project_id
  member  = "serviceAccount:${google_bigquery_connection.default.cloud_resource[0].service_account_id}"
}

# This defines a Google BigQuery dataset.
resource "google_bigquery_dataset" "default" {
  dataset_id = "my_dataset_id"
}

# This creates a bucket in the US region named "my-bucket" with a pseudorandom suffix.
resource "random_id" "bucket_name_suffix" {
  byte_length = 8
}
resource "google_storage_bucket" "default" {
  name                        = "my-bucket-${random_id.bucket_name_suffix.hex}"
  location                    = "US"
  force_destroy               = true
  uniform_bucket_level_access = true
}

# This defines a BigQuery object table with manual metadata caching.
resource "google_bigquery_table" "default" {
  table_id   = "my-table-id"
  dataset_id = google_bigquery_dataset.default.dataset_id
  external_data_configuration {
    connection_id = google_bigquery_connection.default.name
    autodetect    = false
    # `object_metadata is` required for object tables. For more information, see
    # https://registry.terraform.io/providers/hashicorp/google/latest/docs/resources/bigquery_table#object_metadata
    object_metadata = "SIMPLE"
    # This defines the source for the prior object table.
    source_uris = [
      "gs://${google_storage_bucket.default.name}/*",
    ]

    metadata_cache_mode = "MANUAL"
  }

  # This ensures that the connection can access the bucket
  # before Terraform creates a table.
  depends_on = [
    google_project_iam_member.default
  ]
}

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

準備 Cloud Shell

1. 啟動 Cloud Shell。

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

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

   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. 開啟 Google Cloud 專案即可查看結果。在 Google Cloud 控制台的使用者介面中，前往資源頁面，確認 Terraform 已建立或更新資源。

注意：Terraform 範例通常會假設 Google Cloud 專案已啟用必要的 API。

查詢物件資料表

您可以像查詢其他 BigQuery 資料表一樣查詢物件資料表，例如：

SELECT *
FROM mydataset.myobjecttable;

查詢物件資料表會傳回基礎物件的中繼資料。詳情請參閱「物件資料表結構定義」。

後續步驟

• 瞭解如何針對圖片物件資料表執行推論。
• 瞭解如何使用遠端函式分析物件資料表。