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

本指南說明湖泊、區域和資產的 Dataplex Universal Catalog 中繼資料， 以及如何使用 Dataplex Universal Catalog API 管理這些資料。

總覽

Dataplex Universal Catalog 會掃描下列項目：

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

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

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

您可以使用下列工具分析 Dataplex Universal Catalog 中繼資料：

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

Dataplex Universal Catalog API

本節將摘要說明 Dataplex Universal Catalog API 和主要資源。

控制層 API

Dataplex Universal Catalog 控制層 API 可用於建立及管理 lake、可用區和資產資源。

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

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

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

Metadata API

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

基本概念

資料表實體：

適用於結構化資料的中繼資料，且結構定義明確。表格實體會以實體 ID 和資料位置做為專屬 ID。您可以在 BigQuery 和 Dataproc Metastore 中查詢資料表實體中繼資料：

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

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

分區：

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

試用 API

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

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

實體

列出實體

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

取得實體

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

相容性詳細資料：雖然 Dataplex 通用目錄中繼資料會集中登錄在中繼資料 API 中，但只有與 BigQuery 和 Apache Hive 中繼存放區相容的實體資料表，才會發布至 BigQuery 和 Dataproc Metastore。Get Entity API 會傳回 CompatibilityStatus 訊息，指出資料表中繼資料是否與 BigQuery 和 Hive Metastore 相容，如果不相容，則會說明原因。

更新實體

使用這個 API 編輯實體中繼資料，包括您或 Dataplex Universal Catalog 是否要管理實體中繼資料。

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

建立實體

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

刪除實體

  • 提供 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。

後續步驟