管理湖泊、可用區和資產的中繼資料

本指南說明湖泊、可用區和資產的 Knowledge Catalog (舊稱 Dataplex Universal Catalog) 中繼資料，以及如何使用 Dataplex API 管理中繼資料。

總覽

Knowledge Catalog 會掃描下列項目：

  • 資料湖泊中的結構化和半結構化資料資產，可將資料表中繼資料擷取至資料表實體
  • 圖片和文字等非結構化資料，可將檔案集中繼資料擷取到檔案集實體中

您可以使用 Dataplex Metadata API 執行下列操作：

  • 查看、編輯及刪除資料表和檔案集實體中繼資料
  • 建立自己的資料表或檔案集實體中繼資料

您可以使用下列方式分析知識目錄中繼資料：

  • Data Catalog (已淘汰)：用於搜尋和標記
  • Dataproc Metastore 和 BigQuery，用於查詢資料表的中繼資料和進行分析處理

Dataplex API

本節將概述 Dataplex API 中的湖泊、可用區和資產資源，以及這些資源的相關重要資源。

控制層 API

您可以使用 Dataplex 控制層 API 建立及管理湖泊、可用區和資產資源。

  • 湖泊： Knowledge Catalog 服務執行個體，可管理機構內各專案的儲存空間資源。

  • 區域： 湖泊內資產的邏輯分組。在湖泊中使用多個可用區，根據資料準備程度、工作負載或機構結構來整理資料。

  • 資產：儲存資源，資料儲存在 Cloud Storage bucket 或 BigQuery 資料集中，並附加至湖泊中的區域。

Metadata API

使用 Dataplex Metadata API 建立及管理資料表、檔案集實體和分區中的中繼資料。Knowledge Catalog 會掃描湖泊中的資料資產，或您提供的資料資產，藉此建立實體和分割區。實體和分割區會保留相關聯資產和實體儲存位置的參照。

基本概念

資料表實體：

結構化資料的中繼資料，且結構定義明確。表格實體會根據實體 ID 和資料位置進行專屬識別。您可以在 BigQuery 和 Dataproc Metastore 中查詢資料表實體中繼資料：

  • Cloud Storage 物件：Cloud Storage 物件的中繼資料，可透過 Cloud Storage API 存取。
  • BigQuery 資料表：BigQuery 資料表的中繼資料，可透過 BigQuery API 存取。
檔案集實體：

非結構化資料的中繼資料，通常沒有結構定義。檔案集會以實體 ID 和資料位置做為專屬 ID。每個檔案集都有資料格式。

分區：

資料表或檔案集實體中資料子集的中繼資料，由一組鍵/值組合和資料位置識別。

試用 API

請參閱 Knowledge Catalog lakes.zones.entities 和 lakes.zones.partitions API 參考文件頁面，查看與各個 API 相關聯的參數和欄位。使用各 API 方法參考說明文件隨附的「Try this API」面板，透過不同參數和欄位發出 API 要求。您可以建構、查看及提交要求，不必產生憑證，然後查看服務傳回的回應。

以下各節提供相關資訊，協助您瞭解及使用 Knowledge Catalog 中繼資料 API。

實體

列出實體

如要限制服務傳回的實體清單，請將 filter 查詢參數新增至 list entities 要求網址。

取得實體

根據預設，Get Entity 回應會包含基本實體中繼資料。如要擷取其他結構定義中繼資料，請將 view 查詢參數新增至要求網址。

相容性詳細資料：雖然中繼資料 API 會集中註冊 Knowledge Catalog 中繼資料，但只有與 BigQuery 和 Apache Hive Metastore 相容的實體資料表，才會發布至 BigQuery 和 Dataproc Metastore。Get Entity API 會傳回 CompatibilityStatus 訊息，指出資料表中繼資料是否與 BigQuery 和 Hive Metastore 相容，如果不相容，也會說明原因。

更新實體

使用這個 API 編輯實體中繼資料，包括由您或 Knowledge Catalog 管理實體中繼資料。

  • 這個 API 會完全取代所有可變動的實體欄位。下列實體欄位為不可變更，如果您在更新要求中指定這些欄位，系統會忽略這些欄位：
  • 為所有可變動的 Entity 欄位指定值，包括所有結構定義欄位，即使值沒有變更也一樣。
  • 提供 etag 欄位。如要取得 etag，請先提交 entities.get 要求，這會在回應中傳回實體的 etag。
  • 更新結構定義欄位：您可以更新 Knowledge Catalog 探索到的資料表結構定義，提高準確度：
    • 如果結構定義是檔案集，請將所有結構定義欄位留空。
    • 如要定義重複欄位，請將 mode 設為 REPEATED。如要定義結構欄位，請將型別設為 RECORD。
    • 您可以設定架構的 userManaged 欄位，指定是由您還是知識目錄管理表格中繼資料。預設設定為由 Knowledge Catalog 管理。如果 userManaged 設為 true，且 EntityView 設為 SCHEMA 或 FULL，則這項設定會納入 entities.get 要求傳回的資訊中。
  • 更新分區欄位：
    • 對於非 Hive 樣式的分區資料，Knowledge Catalog 探索功能會自動產生分區索引鍵。舉例來說，如果是資料路徑 gs://root/2020/12/31，系統會產生分區鍵 p0、p1 和 p2。如要讓查詢更直覺，您可以將 p0、p1 和 p2 分別更新為 year、month 和 day。
    • 如果將分區樣式更新為 Hive 樣式，分區欄位將無法變更。
  • 更新其他中繼資料欄位：您可以更新自動產生的 mimeType、 CompressionFormat、 CsvOptions 和 JsonOptions 欄位，協助 Knowledge Catalog 探索資料。知識目錄探索功能會在下次執行時使用新值。

建立實體

使用 entities.create API 建立資料表或檔案集的中繼資料實體。填寫必填和相關的選填欄位，或讓知識目錄探索服務填寫選填欄位。

刪除實體

  • 提供 etag 欄位。如要取得 etag，請先提交 entities.get 要求，這會在回應中傳回實體的 etag。

如果刪除原始資料儲存區中資料表或檔案集的基礎資料，系統會在下次 Discovery 掃描時自動刪除資料表或檔案集的中繼資料。如果整理後資料儲存區中資料表的基礎資料遭到刪除，系統不會一併刪除資料表的中繼資料，而是會回報資料遺失動作。如要解決這個問題，請透過中繼資料 API 明確刪除資料表中繼資料實體。

分區

列出分割區

如要限制服務傳回的分區清單，請將 filter 查詢參數新增至 list partitions 要求網址。

範例：

  • ?filter="Country=US AND State=CA AND City=Sunnyvale"
  • ?filter="year < 2000 AND month > 12 AND Date > 10"

取得分區

如要取得分區，請在網址結尾附加分區鍵值，完成要求網址，格式應為 partitions/value1/value2/…./value10。

舉例來說，如果分割區有值 {Country=US, State=CA, City=Sunnyvale}，則 GET 請求網址應以 /partitions/US/CA/Sunnyvale 結尾。

重要事項：附加的網址值必須經過雙重編碼。舉例來說，url_encode(url_encode(value)) 可用於編碼「US:CA/CA#Sunnyvale」，讓要求網址以 /partitions/US%253ACA/CA%2523Sunnyvale 結尾。回應中的名稱欄位會保留編碼格式。

建立分區

如要為資料來源建立自訂分區，請使用 partitions.create API。使用 Cloud Storage 路徑指定必要的位置欄位。

刪除分區

在要求網址結尾附加分割區鍵值，完成要求網址，格式為 partitions/value1/value2/…./value10。

舉例來說，如果分割區有值 {Country=US, State=CA, City=Sunnyvale}，要求網址應以 /partitions/US/CA/Sunnyvale 結尾。

重要事項：附加的網址值必須符合 RFC-1034， 否則必須經過雙重編碼，例如 US:/CA#/Sunnyvale 編碼為 US%3A/CA%3A/Sunnyvale。

後續步驟