Google 會運用 AI 技術將內容翻譯成你偏好的語言，但可能會出錯。

使用 Knowledge Catalog 管理資源

本文件說明如何使用 Knowledge Catalog 搜尋及管理 Spanner 資源。

Knowledge Catalog 會編錄 Google Cloud中 Spanner 執行個體、資料庫、資料表、資料欄和檢視表的中繼資料，讓 AI 代理和數據分析工具擷取有依據的相關背景資訊。

關於 Knowledge Catalog 和 Spanner

Knowledge Catalog 將 Spanner 和其他 Google Cloud 服務中的資源稱為「資產」。在 Knowledge Catalog 中，每個 Spanner 資產 (例如執行個體、資料庫、資料表或檢視表) 都會以目錄項目表示，其中儲存了資源的技術和業務中繼資料 (切面)。

您可以在下列工作流程中使用 Knowledge Catalog，探索及瞭解 Spanner 資產：

分析：瞭解資料資產之間的依附關係，並評估資產是否適合特定用途。
變更管理：追蹤各資料庫的結構修改。
資料移動：追蹤管道來源和目的地。
結構定義演變：監控資料表和資料欄定義隨時間的變化。
情境 AI 建立基準：為 AI 代理提供結構定義和業務情境。

Knowledge Catalog 會自動為 Spanner 資源編目下列中繼資料：

資源名稱和完整名稱 (FQN)
位置 (區域)
建立和上次修改的時間戳記
結構定義 (適用於資料表和檢視表)
資料欄資料類型、可為空值和主鍵指標
說明和使用者標籤

Knowledge Catalog 中繼資料探索功能會自動掃描連結的資料來源 (例如 Spanner)，找出資料表、檢視表和資料庫等資料資產。接著，Knowledge Catalog 會從資產中擷取技術中繼資料，例如結構定義、說明和位置。

Spanner 會定期將中繼資料同步至 Knowledge Catalog，通常是每六小時一次，因此 Spanner 資產的中繼資料變更可能需要約六小時才會生效。

事前準備

將 Knowledge Catalog 與 Spanner 搭配使用前，請先完成下列設定工作：

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.
為專案啟用 Dataplex API。

啟用 Dataplex API

必要的角色

如要取得在 Knowledge Catalog 管理 Spanner 資產所需的權限，請要求管理員在專案中授予您下列 IAM 角色：

查看 Spanner 資源：Cloud Spanner 檢視者 (roles/spanner.viewer)
在 Knowledge Catalog 中搜尋及查看項目：Dataplex Catalog 檢視者 (roles/dataplex.catalogViewer)
建立及管理切面類型：
- Dataplex 切面類型擁有者 (roles/dataplex.aspectTypeOwner)
- Dataplex Catalog 管理員 (roles/dataplex.catalogAdmin)
附加或修改切面：
- Dataplex Catalog 編輯者 (roles/dataplex.catalogEditor)
- Dataplex 項目和 EntryLink 擁有者 (roles/dataplex.entryOwner)
- Dataplex 切面類型使用者 (roles/dataplex.aspectTypeUser)

如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和組織的存取權」。

這些預先定義的角色具備在 Knowledge Catalog 管理 Spanner 資產所需的權限。如要查看確切的必要權限，請展開「Required permissions」(必要權限) 部分：

所需權限

您必須具備下列權限，才能在 Knowledge Catalog 管理 Spanner 資產：

建立切面類型：dataplex.aspectTypes.create
搜尋 Spanner 執行個體：
- dataplex.projects.search
- spanner.instances.get
搜尋 Spanner 資料庫、資料表和檢視表：
- dataplex.projects.search
- spanner.databases.get
查看 Spanner 執行個體的各個面向：
- dataplex.aspectTypes.get
- spanner.instances.get
查看 Spanner 資料庫、資料表和檢視表的切面：
- dataplex.aspectTypes.get
- spanner.databases.get
使用切面類型將切面附加至 Spanner 資源：
- dataplex.aspectTypes.use
- dataplex.entries.update

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

搜尋 Spanner 資產

Knowledge Catalog 支援語意搜尋，可讓您使用日常用語尋找資源，不必使用複雜的搜尋語法。例如，輸入 List all Spanner tables related to sales 等查詢。

您也可以使用特定關鍵字、篩選器和以述詞為基礎的搜尋語法來搜尋資源。

如要在 Knowledge Catalog 搜尋 Spanner 資產，請按照下列步驟操作：

在 Google Cloud 控制台，前往 Knowledge Catalog 的「Search」(搜尋) 頁面。

前往「Search」(搜尋) 頁面
在「Filters」(篩選器) 面板的「Systems」(系統) 下方，選取「Spanner」。

Knowledge Catalog 會顯示您在 Google Cloud 專案中可存取的所有 Spanner 資產。
在搜尋欄位中輸入自然語言查詢，例如 List all Spanner tables related to sales。
選用：在「搜尋」頁面使用篩選搜尋功能。在「Type」(類型)、「Projects」(專案)、「Locations」(位置)和「Aspect types」(切面類型) 下方選取篩選器。
選用：在搜尋欄位中，於 system=spanner 後方附加搜尋參數。請以空格分隔多個參數，或使用括號和邏輯運算子 AND、OR 和 NOT。

舉例來說，如要只查看資料庫，請輸入下列查詢：
```
system=spanner type=database
```
您也可以使用 type=service 搜尋執行個體，或使用 instance_config=CONFIGURATION_NAME 搜尋執行個體設定。

如需更多查詢選項，請參閱「Knowledge Catalog 的搜尋語法」。
在搜尋結果清單中，按一下資產名稱，即可在 Knowledge Catalog 中開啟該資產的項目詳細資料頁面。

在項目詳細資料頁面中，您可以執行下列操作：

如要查看資產摘要並新增說明，請前往「詳細資料」分頁，然後在「總覽」部分點選「新增」。
如要查看或附加業務和作業中繼資料，請前往「Details」(詳細資料) 分頁，然後在「Aspects」(切面) 部分，點選「Optional aspects」(選用切面) 旁的「Add」(新增)。
如要查看執行個體的成員資料庫，請按一下「Entry list」(項目清單) 分頁標籤，然後點選「Show all children entries in search」(在搜尋中顯示所有子項目)。
如要檢查資料表的資料欄資料類型、鍵和定義，請按一下「Schema」(結構定義) 分頁標籤。

用途：從執行個體向下鑽研至資料欄

在這個用途中，您會搜尋 Spanner 執行個體，然後向下鑽研至執行個體中列出的其中一個資料庫，查看其資料表和資料欄。

前往 Google Cloud 控制台的 Knowledge Catalog「Search」(搜尋) 頁面：

前往「Search」(搜尋) 頁面
在「Filters」(篩選器) 面板的「Systems」(系統) 下方，選取「Spanner」。
如要在 Knowledge Catalog 中查看所有 Spanner 執行個體，請在搜尋欄位中輸入自然語言查詢，例如 List all Spanner instances，然後按下 Enter。
選取執行個體名稱。
在「Spanner details」(Spanner 詳細資料) 頁面中，按一下「Entry list」(項目清單) 分頁標籤，然後按一下「Show all children entries in search」(在搜尋結果中顯示所有子項項目)。

Knowledge Catalog 會顯示執行個體中的資料庫。如果沒有「Entry list」(項目清單) 分頁，請返回「Search」(搜尋) 頁面，然後選擇其他執行個體。
選取資料庫名稱。在「Spanner database details」(Spanner 資料庫詳細資料) 頁面中，按一下「Entry list」(項目清單) 分頁標籤，然後按一下「Show all children entries in search」(在搜尋結果中顯示所有子項目)。

Knowledge Catalog 會顯示資料庫中的資料表。
選取資料表名稱，然後在「Spanner table details」(Spanner 資料表詳細資料) 頁面中，按一下「Schema」(結構定義) 即可查看資料表資料欄。
選用：如要為資料欄新增切面，請選取資料欄，然後按一下「Add aspect」(新增切面)。

使用切面充實中繼資料

如要充實中繼資料，並依自訂情境搜尋資產，您可以根據切面類型 (可重複使用的範本) 建立切面，並附加至 Spanner 資產。您可以運用切面，新增結構化業務中繼資料，例如資料擁有權、治理分類或保留政策。

舉例來說，您可以將下列切面附加至包含身分證字號 (個人識別資訊 (PII)) 的資料欄：

pii:true
pii_type:SSN

如要將切面附加至 Spanner 資產，請按照下列步驟操作：

在 Knowledge Catalog 的「Search」(搜尋) 頁面，按一下要擴充的資產。
在項目詳細資料頁面的「Details」(詳細資料) 分頁中，前往「Aspects」(切面) 區段。
在「選用切面」旁，點選「新增」。
搜尋並選取要新增的切面類型，例如資料治理或隱私權的自訂結構定義。
在「Add aspect」(新增切面) 視窗中，指定必要的切面欄位。
按一下 [儲存]。

如需建立切面類型和管理切面的詳細操作說明，請參閱「管理切面和充實中繼資料」。

匯出及匯入切面

將 Spanner 執行個體移至其他執行個體設定時，系統會刪除 Knowledge Catalog 中與來源執行個體設定相關聯的項目和層面。如要保留自訂切面，請按照下列步驟操作：

匯出與來源執行個體設定中項目相關聯的切面。
將執行個體移至目的地執行個體設定。
將切面匯入目的地執行個體設定。

從來源執行個體設定匯出切面

移動執行個體前，請使用 Google Cloud CLI、Dataplex API 或中繼資料匯出工作，擷取來源執行個體設定中 Spanner 項目的切面：

gcloud

如要擷取 @spanner 系統項目群組中 Spanner 項目的切面，請使用 gcloud dataplex entries lookup 指令：

gcloud dataplex entries lookup SOURCE_ENTRY_ID \
  --entry-group=@spanner \
  --location=LOCATION \
  --project=PROJECT_ID \
  --view=all

更改下列內容：

SOURCE_ENTRY_ID：來源執行個體設定中 Spanner 資源的項目 ID。

如何找出項目 ID

如要尋找項目名稱或翻譯完整名稱 (FQN) (例如 spanner:PROJECT_ID.INSTANCE_CONFIG_ID.INSTANCE_ID.DATABASE_ID.TABLE_ID)，請使用 gcloud dataplex entries search 指令。
LOCATION：Spanner 執行個體設定的區域，例如 us-central1。
PROJECT_ID：包含 Spanner 執行個體的 Google Cloud 專案 ID。

REST API

如要擷取 @spanner 系統項目群組中 Spanner 項目的切面，請將 GET 要求傳送至 projects.locations.lookupEntry 端點。

curl -X GET \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "Accept: application/json" \
"https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION:lookupEntry?entry=projects/PROJECT_ID/locations/LOCATION/entryGroups/@spanner/entries/SOURCE_ENTRY_ID&view=ALL"

更改下列內容：

ACCESS_TOKEN：應用程式用來向服務驗證身分的存取權杖。例如，使用 $(gcloud auth print-access-token)。
PROJECT_ID：包含 Spanner 執行個體的 Google Cloud 專案 ID。
LOCATION：Spanner 執行個體設定的區域，例如 us-central1。
SOURCE_ENTRY_ID：來源執行個體設定中 Spanner 資源的項目 ID。

如何找出項目 ID

如要尋找項目名稱或翻譯完整名稱 (FQN) (例如 spanner:PROJECT_ID.INSTANCE_CONFIG_ID.INSTANCE_ID.DATABASE_ID.TABLE_ID)，請使用 gcloud dataplex entries search 指令。

匯出工作

如要將多個項目的中繼資料批次匯出至 Cloud Storage，請執行中繼資料匯出工作。

將執行個體移至目的地執行個體設定

將切面匯入目的地執行個體設定前，請先完成下列操作：

將 Spanner 執行個體移至目的地執行個體設定。等待已移動執行個體的 Spanner 中繼資料同步至 Knowledge Catalog，這項作業約需六小時。
如要確認同步作業已完成，請使用下列任一方法搜尋已移動的執行個體：
- 在 Knowledge Catalog 的「Search」(搜尋) 頁面中，輸入下列查詢：
```
system=spanner instance_config=DESTINATION_CONFIG_NAME
```
- 執行 gcloud dataplex entries search 指令：
```
gcloud dataplex entries search "fqn=spanner:PROJECT_ID.DESTINATION_CONFIG_ID.INSTANCE_ID" \
    --project=PROJECT_ID
```
當指令傳回目的地執行個體設定的項目時，同步作業即完成。

將面向匯入目的地執行個體設定

中繼資料同步後，請將複製的切面附加至目的地執行個體設定中的項目：

gcloud

如要將複製的切面附加至目的地執行個體設定中的項目，請使用 gcloud dataplex entries update-aspects 指令：

gcloud dataplex entries update-aspects DESTINATION_ENTRY_ID \
  --entry-group=@spanner \
  --location=DESTINATION_LOCATION \
  --project=PROJECT_ID \
  --aspects=ASPECTS_FILE

更改下列內容：

DESTINATION_ENTRY_ID：目的地執行個體設定中，已遷移 Spanner 資源的項目 ID。
DESTINATION_LOCATION：目的地 Spanner 執行個體設定的區域，例如 us-central1。
PROJECT_ID：包含 Spanner 執行個體的 Google Cloud 專案 ID。
ASPECTS_FILE：JSON 或 YAML 檔案的路徑，其中包含要新增或更新的切面。

REST API

如要將匯出的切面附加至目的地執行個體設定中的項目，請使用 projects.locations.entryGroups.entries.patch REST API 方法，如下例所示：

curl -X PATCH \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{"aspects":{"ASPECT_KEY":{"data":{"FIELD_NAME":"FIELD_VALUE"}}}}' \
"https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/DESTINATION_LOCATION/entryGroups/@spanner/entries/DESTINATION_ENTRY_ID?updateMask=aspects"

更改下列內容：

ACCESS_TOKEN：應用程式用來向服務驗證身分的存取權杖。例如，使用 $(gcloud auth print-access-token)。
ASPECT_KEY：切面鍵，格式為 PROJECT_ID.ASPECT_LOCATION.ASPECT_TYPE_ID (適用於項目層級切面) 或 PROJECT_ID.ASPECT_LOCATION.ASPECT_TYPE_ID@Schema.COLUMN_NAME (適用於資料欄層級切面)。
FIELD_NAME 和 FIELD_VALUE：切面類型定義的欄位名稱和值。
PROJECT_ID：Spanner 執行個體所在專案的 ID。
DESTINATION_LOCATION：目的地 Spanner 執行個體設定的區域，例如 us-central1。
DESTINATION_ENTRY_ID：目的地執行個體設定中，已遷移 Spanner 資源的項目 ID。

匯入工作

如要從 Cloud Storage 批次匯入多個項目的切面，請執行中繼資料匯入工作。

使用 Knowledge Catalog 管理資源 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

關於 Knowledge Catalog 和 Spanner

事前準備

必要的角色

所需權限

搜尋 Spanner 資產

用途：從執行個體向下鑽研至資料欄

使用切面充實中繼資料

匯出及匯入切面

從來源執行個體設定匯出切面

gcloud

REST API

匯出工作

將執行個體移至目的地執行個體設定

將面向匯入目的地執行個體設定

gcloud

REST API

匯入工作

後續步驟

使用 Knowledge Catalog 管理資源