本頁面由 Cloud Translation API 翻譯而成。

Dataproc Metastore 管理員介面

本頁面說明如何使用 Dataproc Metastore 管理員介面。

管理員介面提供集中式工具，可檢查及管理儲存在 Dataproc Metastore 服務中的中繼資料，而且不必連線至 Dataproc 叢集或 Hive 執行個體。您可以改用 gcloud CLI 或 Dataproc Metastore API 管理中繼資料。

舉例來說，您可以使用管理員介面，直接在後端中繼資料上執行 SQL 查詢，擷取特定資料表名稱。這個程序的步驟比一般工作流程少，例如建立 Dataproc 叢集、使用 SSH 連線至叢集、啟動 Hive 執行個體，然後最後執行查詢 (例如 SELECT * FROM table_name)。

因此，管理員介面可協助您節省時間，並減少擷取資料所需的 Google Cloud 資源。

事前準備

必要的角色

如要取得使用 Dataproc Metastore 管理員介面所需的權限，請要求管理員根據最低權限原則，授予您專案的下列 IAM 角色：

如要查詢 Dataproc Metastore 中繼資料：使用者帳戶或服務帳戶的中繼資料查詢管理員 (roles/metastore.metadataQueryAdmin)
如要變更中繼資料的資源位置 (包括資料庫、資料表和分區)，或將資料表移至其他資料庫：
- 使用者帳戶或服務帳戶中的中繼資料變更管理員 (roles/metastore.metadataMutateAdmin)
- 使用者帳戶或服務帳戶的 Dataproc Metastore 編輯者 (roles/metastore.editor)

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

這些預先定義的角色包含使用 Dataproc Metastore 管理員介面所需的權限。如要查看確切的必要權限，請展開「必要權限」部分：

所需權限

如要使用 Dataproc Metastore 管理員介面，您必須具備下列權限：

如要查詢 Dataproc Metastore 中繼資料： metastore.services.queryMetadata
如要變更或移動 Dataproc Metastore 資料表，請按照下列步驟操作： metastore.services.mutateMetadata

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

如要進一步瞭解特定 Dataproc Metastore 角色和權限，請參閱 Dataproc Metastore 身分與存取權管理總覽。

支援的管理員作業

您只能使用 gcloud CLI 或 Dataproc Metastore API 執行管理介面作業。 Google Cloud 控制台不支援管理員介面作業。

管理員介面支援下列作業。

唯讀作業。
- 查詢中繼資料。
警告： 請只以互動方式執行唯讀查詢。請勿在對正式作業至關重要的程序中，自動化或執行非交互式唯讀查詢。如果基礎資料庫結構定義在未經通知的情況下變更，執行非交互式查詢可能會導致問題。
讀取和寫入作業。
- 變更中繼資料的資源位置，包括資料庫、資料表和分區。
- 變更表格屬性，例如自訂鍵/值組合。
- 將資料表移至其他資料庫。

查詢中繼資料

這項作業可讓您使用 SQL 查詢，在資料庫中查詢中繼資料資訊。執行查詢後，系統會將結果轉儲至 artifacts Google Cloud 儲存體。

執行這項作業前，請注意下列注意事項：

支援的作業僅限 read-only MySQL 或 Spanner 查詢。如果查詢嘗試修改資料，該作業就會失敗。
輸出檔案最多包含 1000 列。這項設定無法變更。
系統不會自動刪除輸出檔案。您必須手動從 Google Cloud 儲存體中刪除這些項目。如果不刪除這些檔案，可能會產生額外的儲存空間費用。

gcloud CLI

如要查詢中繼資料，請執行下列 gcloud metastore services query-metadata 指令：
```
gcloud metastore services query-metadata SERVICE \
  --location=LOCATION \
  --query=QUERY
```
更改下列內容：
- SERVICE：Dataproc Metastore 服務的名稱。
- LOCATION：Dataproc Metastore 服務所在的 Google Cloud 區域。
- QUERY：指定 metadata 的 SQL 查詢。
  - 如果您使用 MySQL 資料庫，請使用一般 MySQL 查詢。
  - 如果您使用 Spanner 資料庫，請使用 GoogleSQL 查詢。
查看artifacts Google Cloud bucket 中的輸出檔案。

REST

curl -X POST -s -i \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -X POST -d '{"query": "QUERY"}' \
  -H "Content-Type:application/json" \
  https://metastore.googleapis.com/projects/PROJECT_ID/locations/LOCATION/services/SERVICE:queryMetadata

更改下列內容：

QUERY：您用來指定中繼資料的 SQL 查詢。
- 如果您使用 MySQL 資料庫，請使用一般 MySQL 查詢。
- 如果您使用 Spanner 資料庫，請使用 GoogleSQL 查詢。
PROJECT_ID：Dataproc Metastore 服務所在的 Google Cloud 專案 ID。
SERVICE：Dataproc Metastore 服務的名稱。
LOCATION：Dataproc Metastore 所在的區域。

以下範例顯示範例指令，可從名為 DBS 的資料庫執行 select * 查詢。

curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" -X POST -d  '{"query": "select * from DBS;"}' \
  https://metastore.googleapis.com/projects/dpms/locations/us-central1/services/dpms1:queryMetadata

解讀查詢中繼資料作業的輸出內容

首次執行查詢中繼資料指令時，Dataproc Metastore 會自動在資料集 Google Cloud 值區中建立 Google Cloud 資料夾。這個資料夾的名稱為 query-results。每次成功執行查詢 (API 呼叫) 後，系統都會在 query-results 資料夾中建立一個新資料夾 (使用隨機產生的 UUID 命名)。

每個新資料夾都包含 result manifest 檔案，其中包含查詢結果。這個資料夾的位置會在 API 呼叫的回應中傳回。

舉例來說，在回應中，resultManifestUri 欄位會包含檔案的位置。

"response": {
    "@type": "type.googleapis.com/google.cloud.metastore.QueryMetadataResponse",
    "resultManifestUri": "gs://gcs-bucket-6a3638b8-e319-46363-ad33-e632a5e/query-results/800156f5-2d13-4b80-bec3-2345a9e880f6/result-manifest"
  }

result manifest 檔案的輸出結果會與下列內容類似：

{
  "status": {
    "code": 0,
    "message": "Query results are successfully uploaded to cloud storage",
    "details": []
  },
  "filenames": ["result-001"]
}

結果資訊清單檔案詳細資料：

status 欄位會顯示查詢是否成功。
如果查詢執行成功，filenames 欄位會列出所有建立的檔案。這些檔案與 result manifest 檔案位於同一個資料夾中。
如果查詢失敗，details 欄位會顯示錯誤訊息。

變更中繼資料的資源位置

這項作業可讓您變更資料庫、資料表或分區的資源位置。

執行這項指令時，系統只會更新父目錄或相應的中繼資料資源。此指令不會將任何現有資料轉移至新位置。

gcloud CLI

如要變更中繼資料的資源位置，請執行下列 gcloud metastore services alter-metadata-resource-location 指令：
```
gcloud metastore services alter-metadata-resource-location SERVICE \
  --location=LOCATION \
  --resource_name=RESOURCE_NAME \
  --location_uri=LOCATION_URI
```
更改下列內容：
- SERVICE：Dataproc Metastore 服務的名稱。
- LOCATION：Dataproc Metastore 服務所在的 Google Cloud 區域。
- RESOURCE_NAME：您要變更的資料庫、資料表或區隔名稱。
- LOCATION_URI：RESOURCE_NAME 內容的新 Cloud Storage 路徑。這個值是您要將中繼資料資源位置移至的位置路徑。路徑開頭必須為 gs://。例如：gs://bucket/object。
確認資源位置變更已成功。

REST

curl -X POST -s -i \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  POST -d '{"resource_name": "RESOURCE_NAME", "location_uri":"LOCATION_URI"}' \
  -H "Content-Type:application/json" \
  https://metastore.googleapis.com/projects/PROJECT_ID/locations/LOCATION/services/SERVICE:alterLocation

更改下列內容：

PROJECT_ID：Dataproc Metastore 服務所在的 Google Cloud 專案 ID。
SERVICE：Dataproc Metastore 服務的名稱。
LOCATION：Dataproc Metastore 所在的區域。
RESOURCE_NAME：您要變更的資料庫、資料表或區隔名稱。
LOCATION_URI：RESOURCE_NAME 內容的新 Cloud Storage 路徑。這個值是您要將中繼資料資源位置移至的位置路徑。路徑開頭必須為 gs://。例如：gs://bucket/object。

以下範例顯示將名為 test-table2 的資料表移至新 Cloud Storage 值區的範例指令。

 curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
   -H "Content-Type: application/json" \
   -X POST -d  '{"resource_name": "databases/testdb1/tables/test-table2",
   "location_uri":"gs://gcs-bucket-dpms1-9425bd83-b794-4f1c-9e79-2d833f758cc1/empty"}'
   https://metastore.googleapis.com/projects/dpms/locations/us-central1/services/dpms1:alterLocation

變更資料表屬性

這個作業可讓您變更資料表的屬性，例如用來儲存資料的自訂鍵/值組合。舉例來說，您可以將 properties.customerID_1 的鍵/值組合變更為 properties.customerID_2。

gcloud CLI

如要變更資料表屬性，請執行下列 gcloud metastore services alter-table-properties 指令：
```
gcloud metastore services alter-table-properties SERVICE \
  --location=LOCATION \
  --table-name=TABLE_NAME \
  --update-mask=UPDATE_MASK \
  --properties=PROPERTIES
```
更改下列內容：
- SERVICE：Dataproc Metastore 服務的名稱。
- LOCATION：Dataproc Metastore 服務所在的 Google Cloud 區域。
- TABLE_NAME：包含您要修改的屬性 (以以下格式 databases/{database_id}/tables/{table_id} 表示) 的資料表名稱。
- UPDATE_MASK：您要更新的現有資源值。使用半形逗號分隔的清單來描述鍵/值組合，例如 properties.1,properties.2,properties.3,...。
- PROPERTIES：資料表的新屬性。使用以半形逗號分隔的清單來描述鍵/值組合。例如：a=1,b=2,c=3,...。您在此處列出的值會覆寫 UPDATE_MASK 中的值。

REST

curl -X POST -s -i \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  POST -d '{"table_name": "TABLE_NAME", "update_mask":"UPDATE_MASK", "properties":PROPERTIES}'\
  -H "Content-Type:application/json" \
  https://metastore.googleapis.com/projects/PROJECT_ID/locations/LOCATION/services/SERVICE:alterTableProperties

更改下列內容：

SERVICE：Dataproc Metastore 服務的名稱。
LOCATION：Dataproc Metastore 服務所在的 Google Cloud 區域。
TABLE_NAME：包含您要修改的屬性 (以以下格式 databases/{database_id}/tables/{table_id} 表示) 的資料表名稱。
UPDATE_MASK：您要更新的現有屬性值。使用半形逗號分隔的清單來描述鍵/值組合，例如 properties.1,properties.2,properties.3,...。
PROPERTIES：資料表的新屬性。使用半形逗號分隔的清單來描述鍵/值組合，例如 a=1,b=2,c=3,...。您在這裡列出的值會覆寫 UPDATE_MASK 中的值。

以下範例顯示用於變更名為 test-table 的資料表屬性的範例指令。在本範例中，現有的鍵/值組合 properties.customerID_1 會更新為新值 properties.customerID_2

  curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
   -H "Content-Type: application/json"
   -X POST -d  '{"table_name": "databases/default/tables/test-table", "update_mask":{"paths":"properties.customerID_1"}, "properties":{"customerID_1":"customerID_2"}}' https://metastore.googleapis.com/projects/dpms-p

將資料表移至其他資料庫

這項作業可讓您將內部資料表 (受管理的資料表) 移至其他資料庫。在這種情況下，資料庫父目錄和資料都會一併移動。

您無法移動儲存在外部資料表中的資料。

gcloud CLI

如要將資料表移至其他資料庫，請執行下列 gcloud metastore services move-table-to-database 指令：
```
gcloud metastore services move-table-to-database SERVICE \
  --location=LOCATION \
  --db_name=DB_NAME \
  --table_name=TABLE_NAME \
  --destination_db_name=DESTINATION_DB_NAME
```
更改下列內容：
- SERVICE：Dataproc Metastore 服務的名稱。
- LOCATION：Dataproc Metastore 服務所在的 Google Cloud 區域。
- DB_NAME：包含要移動的資料表的來源資料庫名稱。
- TABLE_NAME：要移動的資料表名稱。
- DESTINATION_DB_NAME：要將資料表移至的新資料庫名稱。
確認資料表變更已成功。

REST

curl -X POST -s -i \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  POST -d '{"table_name": "TABLE_NAME", "db_name": "DB_NAME", "destination_db_name": "DESTINATION_DB_NAME"}'\
  -H "Content-Type:application/json" \
  https://metastore.googleapis.com/projects/PROJECT_ID/locations/LOCATION/services/SERVICE:moveTableToDatabase

更改下列內容：

PROJECT_ID：Dataproc Metastore 服務所在的 Google Cloud 專案 ID。
SERVICE：Dataproc Metastore 服務的名稱。
LOCATION：Dataproc Metastore 所在的區域。
DB_NAME：包含要移動的資料表的來源資料庫名稱。
TABLE_NAME：要移動的資料表名稱。
DESTINATION_DB_NAME：要將資料表移至的新資料庫名稱。

以下範例顯示可將名為 testdb1 的資料庫移至名為 testdb2 的其他資料庫的範例指令。

curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
 -H "Content-Type: application/json"
 -X POST -d  '{"table_name": "testtb1", "db_name": "testdb1",
 "destination_db_name": "testdb2"}' https://metastore.googleapis.com/projects/dpms/locations/asia-northeast2/services/dpms1:moveTableToDatabase

Dataproc Metastore 管理員介面 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

事前準備

必要的角色

所需權限

支援的管理員作業

查詢中繼資料

gcloud CLI

REST

解讀查詢中繼資料作業的輸出內容

變更中繼資料的資源位置

gcloud CLI

REST

變更資料表屬性

gcloud CLI

REST

將資料表移至其他資料庫

gcloud CLI

REST

後續步驟

Dataproc Metastore 管理員介面