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

Dataproc Metastore 管理員介面

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

管理員介面提供集中式工具，可檢查及管理 Dataproc Metastore 服務中儲存的中繼資料，完全不必連線至 Dataproc 叢集或 Hive 執行個體。您可以改用 Google Cloud 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 控制台不支援管理員介面作業。

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

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

如果管理員介面不支援其他作業，您可以直接查詢 Hive 中繼存放區。舉例來說，如要列出 Dataproc Metastore 執行個體中的所有資料表，您可以直接查詢 Hive Metastore 結構定義。在這種情況下，您可以執行 select * from TBLS 列出服務中儲存的所有資料表。

查詢中繼資料

這項作業可讓您使用 SQL 查詢，在資料庫中查詢中繼資料資訊。查詢執行完畢後，結果會傾印到 artifacts Google Cloud bucket。

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

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

gcloud CLI

如要查詢中繼資料，請執行下列 gcloud metastore services query-metadata 指令：
```
gcloud metastore services query-metadata SERVICE \
  --location=LOCATION \
  --query=QUERY
```
更改下列內容：
- ：Dataproc Metastore 服務的名稱。SERVICE
- LOCATION：Dataproc Metastore 服務所在的 Google Cloud 區域。
- QUERY：用於指定中繼資料的 SQL 查詢。
  - 如果您使用 MySQL 資料庫，請使用一般 MySQL 查詢。
  - 如果您使用 Spanner 資料庫，請使用 GoogleSQL 查詢。
在構件 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 bucket。

 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
```
更改下列內容：
- ：Dataproc Metastore 服務的名稱。SERVICE
- 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

更改下列內容：

：Dataproc Metastore 服務的名稱。SERVICE
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

後續步驟