使用資料網域

預覽

這項產品或功能適用《服務專屬條款》中「一般服務條款」一節的《正式發布前產品條款》。正式發布前的產品和功能是按照「原樣」提供，支援範圍可能有限。 詳情請參閱推出階段說明。

資料網域使用者可以透過資料網域，將搜尋結果縮小至特定業務情境、搜尋 BigQuery 資料集、資料表和資料產品，以及探索特定網域邊界內的中繼資料。

事前準備

如要依網域執行搜尋，請先確認您具備所需角色，並已啟用相關 API。

啟用 API

如果尚未啟用，請啟用 Dataplex API。

啟用 API 所需的角色

如要啟用 API，您必須具備 serviceusage.services.enable 權限。如果您建立了專案，可能已透過擁有者角色 (roles/owner) 取得這項權限。否則，您可以透過服務使用情形管理員角色 (roles/serviceusage.serviceUsageAdmin) 取得這項權限。瞭解如何授予角色。

啟用 API

必要的角色

如要取得使用資料網域搜尋及探索中繼資料所需的權限，請要求管理員授予您專案或資料網域的下列 IAM 角色：

• 查看探索用網域項目的中繼資料：Dataplex 資料網域項目讀取者 (roles/dataplex.dataDomainEntryReader)
• 查看網域設定和繫結： Dataplex 資料網域設定檢視者 (roles/dataplex.dataDomainViewer)

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

您或許也能透過自訂角色或其他預先定義的角色，取得必要權限。

瀏覽網域階層

如要進一步瞭解如何瀏覽網域階層，請參閱「查看位置中的資料網域和子網域」。

尋找資料網域中的資源

如要依網域搜尋資源，請按照下列步驟操作：

控制台

1. 在 Google Cloud 控制台，依序前往「Knowledge Catalog」 >「Search」(搜尋) 頁面。

   前往「Search」(搜尋) 頁面

2. 按一下「試用自然搜尋」，啟用自然搜尋功能。

3. 按一下 [篩選器]。

4. 在「範圍」欄位中，從清單選取「網域」。

5. 在「Select domain」(選取網域) 欄位中，選取要縮小結果範圍的網域。視需要新增其他篩選條件。

或者，您也可以使用「在網域中搜尋」選單選項，在網域中尋找資源：

1. 前往 Google Cloud 控制台的「Data domains」(資料網域) 頁面。

   前往「資料網域」

2. 從 more_vert 選單中選取「在網域內搜尋」。這項操作會自動開啟已套用「網域」篩選條件的搜尋視窗。

3. 使用搜尋欄位尋找網域中的資源。

REST

如要搜尋資料網域範圍內的項目，請使用 projects.locations.searchEntries 方法，並在 contexts 參數中提供網域路徑。

注意： searchEntries 路徑中的位置可以是 global (用於完整展開) 或特定區域，具體取決於搜尋後端設定。

使用任何要求資料之前，請先修改下列項目的值：

• PROJECT_ID： Google Cloud 專案的 ID。
• LOCATION_ID：搜尋查詢的區域 (或 global)。
• QUERY：搜尋查詢字串。
• DOMAIN_ID：資料網域的專屬 ID，用於定義搜尋範圍情境。

HTTP 方法和網址：

POST https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID:searchEntries

JSON 要求主體：

{
  "query": "QUERY",
  "contexts": [ "projects/PROJECT_ID/locations/LOCATION_ID/dataDomains/DOMAIN_ID" ],
  "semantic_search": true,
  "page_size": 100
}

請展開以下其中一個選項，以傳送要求：

curl (Linux、macOS 或 Cloud Shell)

注意：下列指令假設您已執行 gcloud init 或 gcloud auth login，透過使用者帳戶登入 gcloud CLI，或已使用 Cloud Shell 自動登入 gcloud CLI。您可以執行 gcloud auth list，查看目前使用的帳戶。

將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID:searchEntries"

PowerShell (Windows)

注意：下列指令假設您已執行 gcloud init 或 gcloud auth login，透過使用者帳戶登入 gcloud CLI。您可以執行 gcloud auth list，查看目前使用的帳戶。

將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID:searchEntries" | Select-Object -Expand Content

您應該會收到執行成功的狀態碼 (2xx) 和空白回應。

擷取資料網域的背景資訊

您可以使用 lookupContext 方法，根據資料網域擷取的業務背景資訊，為 AI 代理建立基準。lookupContext 方法支援資料網域的方式如下：

• 資料網域的背景資訊。您可以在 resources 清單中傳遞代表資料網域的項目。回覆包含資料網域的中繼資料，例如說明和網域階層中的父項資料網域。
• 資料資產的資料領域成員資格。擷取一或多個資料網域中資料資產的環境時，回應會包含 dataDomains 欄位，列出資產所屬的資料網域，從最明確的網域開始，依序向上層網域排列。

如要擷取資料網域的內容，請傳送下列要求：

curl --request POST \
  'https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION:lookupContext' \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H 'Content-Type: application/json' \
  -d '{
    "resources": [
      "projects/PROJECT_ID/locations/LOCATION/entryGroups/@dataplex/entries/projects/PROJECT_NUMBER/locations/LOCATION/dataDomains/DATA_DOMAIN_ID"
    ],
    "options": {
      "format": "yaml"
    }
  }'

更改下列內容：

• PROJECT_ID：包含資料網域的專案 ID。
• PROJECT_NUMBER：包含資料網域的專案編號。
• LOCATION：資料網域的位置。
• DATA_DOMAIN_ID：資料網域的 ID。

如要進一步瞭解 lookupContext 方法，請參閱「擷取資料資產的背景資訊」。

限制

在網域環境外搜尋資源時 (例如使用全域搜尋)，網域的曝光度權限不適用。您只會看到基礎系統 (例如 BigQuery) 中有權存取的資源。

假設資料網域包含 BigQuery 資料集。您擁有網域的「Dataplex Data Domain Entry Reader」角色，但沒有直接在 BigQuery 中查看資料集的權限：

• 在網域內搜尋：由於網域權限適用於您，因此搜尋結果會顯示資料集。
• 在網域外搜尋：搜尋結果不會顯示資料集。一般搜尋不適用網域權限，您也無法在 BigQuery 中直接存取。

後續步驟

• 進一步瞭解資料網域。
• 瞭解如何建立資料網域。
• 瞭解如何管理資料網域資源。