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

查看 BigQuery 資料集的政策洞察資料

本頁說明如何管理資料集層級的政策洞察，這些洞察是根據機器學習技術，分析 BigQuery 資料集的權限使用情形而得出的結果。政策洞察資料可協助您找出具備不必要權限的主體。

本頁著重於資料集的政策洞察。建議工具也會針對下列資源類型提供政策洞察：

資料集層級的政策洞察資訊有時會連結至角色建議。角色建議會根據資料集層級的政策洞察資訊，提供可採取的行動，協助您解決問題。

事前準備

Enable the Recommender API.
Roles required to enable APIs
To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.
Enable the API
熟悉 IAM 角色建議。
請確認您已在機構或專案層級啟用 Security Command Center 的進階或企業方案。詳情請參閱「帳單問題」。
選用：瞭解建議工具洞察。

必要的角色

如要取得管理資料集層級政策洞察資料所需的權限，請要求管理員在專案中授予您下列 IAM 角色：

BigQuery 資料擁有者 (`roles/bigquery.dataOwner`)
IAM 建議工具管理員 (`roles/recommender.iamAdmin`)
使用 gcloud CLI 或 REST API 管理資料集層級的政策洞察：服務用量消費者 (`roles/serviceusage.serviceUsageConsumer`)

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

這些預先定義的角色具備管理資料集層級政策洞察所需的權限。如要查看確切的必要權限，請展開「Required permissions」(必要權限) 部分：

所需權限

如要管理資料集層級的政策洞察，必須具備下列權限：

查看資料集層級的政策洞察資料：
- recommender.iamPolicyInsights.get
- recommender.iamPolicyInsights.list
修改資料集層級的政策洞察資料： recommender.iamPolicyInsights.update
使用 gcloud CLI 或 REST API 管理資料集層級的政策洞察： serviceusage.services.use

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

列出資料集層級政策洞察

如要列出專案的所有資料集層級政策洞察，請使用下列其中一種方法：

gcloud

使用 gcloud recommender insights list 指令，查看專案的所有資料集層級政策洞察資料。

執行指令前，請先替換下列值：

PROJECT_ID：您要列出洞察資料的專案 ID。
LOCATION：您要列出洞察資料的資料集位置。

gcloud recommender insights list --insight-type=google.iam.policy.Insight \
    --project=PROJECT_ID \
    --location=LOCATION\
    --filter="insightSubtype:PERMISSIONS_USAGE_BIGQUERY_DATASET"

輸出內容會列出指定位置中專案的所有資料集層級政策洞察資料。例如：

INSIGHT_ID                            CATEGORY  INSIGHT_STATE  LAST_REFRESH_TIME     SEVERITY  INSIGHT_SUBTYPE                     DESCRIPTION
101d03ad-6148-4628-943e-fcf1a3af6b57  SECURITY  ACTIVE         2024-02-02T08:00:00Z  LOW       PERMISSIONS_USAGE_BIGQUERY_DATASET  0 of the permissions in this role binding were used in the past 90 days.
15133dd9-4cbc-41e9-8990-b189241676d8  SECURITY  ACTIVE         2024-02-02T08:00:00Z  LOW       PERMISSIONS_USAGE_BIGQUERY_DATASET  0 of the permissions in this role binding were used in the past 90 days.
1590aeae-d5bf-4e3d-b7d5-e230212f5faf  SECURITY  ACTIVE         2024-02-02T08:00:00Z  LOW       PERMISSIONS_USAGE_BIGQUERY_DATASET  4 of the permissions in this role binding were used in the past 90 days.
280e5a14-4d09-4ac6-8e14-be7407611ad7  SECURITY  ACTIVE         2024-02-02T08:00:00Z  LOW       PERMISSIONS_USAGE_BIGQUERY_DATASET  0 of the permissions in this role binding were used in the past 90 days.
34102078-085f-45d3-ae72-81da16c75781  SECURITY  ACTIVE         2024-02-02T08:00:00Z  LOW       PERMISSIONS_USAGE_BIGQUERY_DATASET  10 of the permissions in this role binding were used in the past 90 days.

REST

Recommender API 的 insights.list 方法會列出專案的所有資料集層級政策洞察。

使用任何要求資料之前，請先替換以下項目：

PROJECT_ID：您要列出洞察資料的專案 ID。
LOCATION：您要列出洞察資料的資料集位置。

HTTP 方法和網址：

GET https://recommender.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/insightTypes/google.iam.policy.Insight/insights?filter=insightSubtype%20%3D%20PERMISSIONS_USAGE_BIGQUERY_DATASET

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

curl (Linux、macOS 或 Cloud Shell)

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

執行下列指令：

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "x-goog-user-project: PROJECT_ID" \
     "https://recommender.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/insightTypes/google.iam.policy.Insight/insights?filter=insightSubtype%20%3D%20PERMISSIONS_USAGE_BIGQUERY_DATASET"

PowerShell (Windows)

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

執行下列指令：

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred"; "x-goog-user-project" = "PROJECT_ID" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://recommender.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/insightTypes/google.iam.policy.Insight/insights?filter=insightSubtype%20%3D%20PERMISSIONS_USAGE_BIGQUERY_DATASET" | Select-Object -Expand Content

回應會列出指定位置中專案的所有資料集層級政策洞察資料。例如：

{
  "insights": [
    {
      "name": "projects/1069248613794/locations/us/insightTypes/google.iam.policy.Insight/insights/101d03ad-6148-4628-943e-fcf1a3af6b57",
      "description": "0 of the permissions in this role binding were used in the past 90 days.",
      "content": {
        "role": "roles/bigquery.dataEditor",
        "member": "projectEditor:my-project",
        "condition": {
          "expression": "",
          "title": "",
          "description": "",
          "location": ""
        },
        "exercisedPermissions": [],
        "inferredPermissions": [],
        "currentTotalPermissionsCount": "37"
      },
      "lastRefreshTime": "2024-02-02T08:00:00Z",
      "observationPeriod": "7779600s",
      "stateInfo": {
        "state": "ACTIVE"
      },
      "category": "SECURITY",
      "associatedRecommendations": [
        {
          "recommendation": "projects/1069248613794/locations/us/recommenders/google.iam.policy.Recommender/recommendations/9327f952-1ceb-488e-9e49-f17eb21f6e5e"
        }
      ],
      "targetResources": [
        "//bigquery.googleapis.com/projects/my-project/datasets/dataset-1"
      ],
      "insightSubtype": "PERMISSIONS_USAGE_BIGQUERY_DATASET",
      "etag": "\"35d4af47524d3f0c\"",
      "severity": "LOW"
    },
    {
      "name": "projects/1069248613794/locations/us/insightTypes/google.iam.policy.Insight/insights/15133dd9-4cbc-41e9-8990-b189241676d8",
      "description": "0 of the permissions in this role binding were used in the past 90 days.",
      "content": {
        "role": "roles/bigquery.dataViewer",
        "member": "projectViewer:my-project",
        "condition": {
          "expression": "",
          "title": "",
          "description": "",
          "location": ""
        },
        "exercisedPermissions": [],
        "inferredPermissions": [],
        "currentTotalPermissionsCount": "17"
      },
      "lastRefreshTime": "2024-02-02T08:00:00Z",
      "observationPeriod": "7779600s",
      "stateInfo": {
        "state": "ACTIVE"
      },
      "category": "SECURITY",
      "associatedRecommendations": [
        {
          "recommendation": "projects/1069248613794/locations/us/recommenders/google.iam.policy.Recommender/recommendations/bc9b4c28-cc93-4a91-97ea-ff67e3cef1b4"
        }
      ],
      "targetResources": [
        "//bigquery.googleapis.com/projects/my-project/datasets/dataset-2"
      ],
      "insightSubtype": "PERMISSIONS_USAGE_BIGQUERY_DATASET",
      "etag": "\"eafa79df1b329063\"",
      "severity": "LOW"
    }
  ]
}

如要進一步瞭解洞察資料的組成部分，請參閱本頁的「查看資料集層級的政策洞察資料」。

取得單一資料集層級的政策洞察

如要進一步瞭解單一洞察資料，包括洞察資料的說明、狀態和任何相關聯的建議，請使用下列其中一種方法：

gcloud

使用 gcloud recommender insights describe 指令和洞察 ID，查看單一洞察的相關資訊。

INSIGHT_ID：要查看的洞察 ID。如要找出 ID，請列出專案的洞察。
PROJECT_ID：您要管理洞察資料的專案 ID。
LOCATION：您要取得洞察資料的資料集位置。

gcloud recommender insights describe INSIGHT_ID \
    --insight-type=google.iam.policy.Insight \
    --project=PROJECT_ID \
    --location=LOCATION

輸出內容會詳細顯示洞察資料。舉例來說，以下洞察資訊指出，專案 my-project (projectEditor:my-project) 中具有「編輯者」角色的所有使用者，在資料集 dataset-1 中都具有「BigQuery 資料編輯者」角色 (roles/bigquery.dataEditor)，但過去 90 天內，該角色中的任何權限都未曾使用：

associatedRecommendations:
- recommendation: projects/1069248613794/locations/us/recommenders/google.iam.policy.Recommender/recommendations/9327f951-1ceb-488e-9e49-f17eb21f6e5e
category: SECURITY
content:
  condition:
    description: ''
    expression: ''
    location: ''
    title: ''
  currentTotalPermissionsCount: '37'
  exercisedPermissions: []
  inferredPermissions: []
  member: projectEditor:my-project
  role: roles/bigquery.dataEditor
description: 0 of the permissions in this role binding were used in the past 90 days.
etag: '"5f2f352a738f7a24"'
insightSubtype: PERMISSIONS_USAGE_BIGQUERY_DATASET
lastRefreshTime: '2024-02-04T08:00:00Z'
name: projects/1069248613794/locations/us/insightTypes/google.iam.policy.Insight/insights/101d03ad-6148-4628-943e-fcf1a3af6b57
observationPeriod: 7776000s
severity: LOW
stateInfo:
  state: ACTIVE
targetResources:
- //bigquery.googleapis.com/projects/my-project/datasets/dataset-1

如要進一步瞭解洞察資料的組成元素，請參閱本頁的「查看資料集層級的政策洞察資料」。

REST

Recommender API 的 insights.get 方法會取得單一洞察資料。

使用任何要求資料之前，請先替換以下項目：

PROJECT_ID：您要管理洞察資料的專案 ID。
LOCATION：您要取得洞察資料的資料集位置。
INSIGHT_ID：要查看的洞察 ID。如果您不知道洞察 ID，可以列出專案中的洞察來找出 ID。洞察 ID 是洞察name欄位中 insights/ 後方的所有內容。

HTTP 方法和網址：

GET https://recommender.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/insightTypes/google.iam.policy.Insight/insights/INSIGHT_ID

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

curl (Linux、macOS 或 Cloud Shell)

執行下列指令：

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "x-goog-user-project: PROJECT_ID" \
     "https://recommender.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/insightTypes/google.iam.policy.Insight/insights/INSIGHT_ID"

PowerShell (Windows)

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

執行下列指令：

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred"; "x-goog-user-project" = "PROJECT_ID" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://recommender.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/insightTypes/google.iam.policy.Insight/insights/INSIGHT_ID" | Select-Object -Expand Content

回覆會包含洞察資訊。舉例來說，以下洞察資訊指出，專案 my-project (projectEditor:my-project) 中具有「編輯者」角色的所有使用者，在資料集 dataset-1 中都具有「BigQuery 資料編輯者」角色 (roles/bigquery.dataEditor)，但過去 90 天內，該角色中的任何權限都未曾使用：

{
  "name": "projects/1069248613794/locations/us/insightTypes/google.iam.policy.Insight/insights/101d03ad-6148-4628-943e-fcf1a3af6b57",
  "description": "0 of the permissions in this role binding were used in the past 90 days.",
  "content": {
    "role": "roles/bigquery.dataEditor",
    "member": "projectEditor:my-project",
    "condition": {
      "expression": "",
      "title": "",
      "description": "",
      "location": ""
    },
    "exercisedPermissions": [],
    "inferredPermissions": [],
    "currentTotalPermissionsCount": "37"
  },
  "lastRefreshTime": "2024-02-02T08:00:00Z",
  "observationPeriod": "7779600s",
  "stateInfo": {
    "state": "ACTIVE"
  },
  "category": "SECURITY",
  "associatedRecommendations": [
    {
      "recommendation": "projects/1069248613794/locations/us/recommenders/google.iam.policy.Recommender/recommendations/9327f952-1ceb-488e-9e49-f17eb21f6e5e"
    }
  ],
  "targetResources": [
    "//bigquery.googleapis.com/projects/my-project/datasets/dataset-1"
  ],
  "insightSubtype": "PERMISSIONS_USAGE_BIGQUERY_DATASET",
  "etag": "\"35d4af47524d3f0c\"",
  "severity": "LOW"
}

如要進一步瞭解洞察資料的組成元素，請參閱本頁的「查看資料集層級的政策洞察資料」。

查看資料集層級的政策洞察

取得單一洞察後，您可以查看其內容，瞭解洞察所強調的資源用量模式。

洞察內容取決於子類型。資料集層級的政策洞察 (google.iam.policy.Insight) 洞察具有 PERMISSIONS_USAGE_BIGQUERY_DATASET 子類型。

PERMISSIONS_USAGE_BIGQUERY_DATASET 洞察包含下列元件，但不一定會依序顯示：

associatedRecommendations：與洞察相關聯的任何建議 ID。如果沒有與洞察資料相關的建議，這個欄位會留空。
category：IAM 洞察的類別一律為 SECURITY。
content：針對特定角色，回報主體的權限使用情形。這個欄位包含下列元件：
- condition：附加至繫結的任何條件，可授予主體角色。如果沒有條件，這個欄位會包含空白條件。
- exercisedPermissions：主體在觀察期間使用的角色權限。
- inferredPermissions：Recommender 透過 ML 判斷主體可能需要的角色權限 (根據主體已使用的權限)。
- member：已分析權限使用情形的主體。
- role：已分析權限用量的角色。
description：洞察的易讀摘要。
etag：洞察目前狀態的專屬 ID。每次洞察資料變更時，系統都會指派新的 etag 值。

如要變更洞察資料的狀態，您必須提供現有洞察資料的 etag。使用 etag 可確保只有在洞察資料自上次擷取後未變更時，才會執行任何作業。
insightSubtype：洞察子類型。
lastRefreshTime：洞察資料上次更新的日期，表示用於產生洞察資料的資料新鮮度。
name：洞察的名稱，格式如下：
```
projects/PROJECT_ID/locations/LOCATION/insightTypes/google.iam.policy.Insight/insights/INSIGHT_ID
```
預留位置的值如下：
- PROJECT_ID：洞察生成所在專案的 ID。
- LOCATION：洞察所屬資料集的位置。
- INSIGHT_ID：洞察的專屬 ID。
observationPeriod：洞察發生前的時間範圍。用來生成洞察的來源資料結束於 lastRefreshTime，開始於 lastRefreshTime 減去 observationPeriod。
stateInfo：提案後，洞察資料會經歷多種狀態轉換：
- ACTIVE：洞察資料已產生，但未採取任何行動，或採取行動後未更新洞察資料的狀態。基礎資料變更時，系統會更新有效的洞察資料。
- ACCEPTED：已根據洞察資料採取行動。當相關聯的建議標示為 CLAIMED、SUCCEEDED 或 FAILED，或是直接接受洞察資料時，系統就會接受洞察資料。洞察資料處於 ACCEPTED 狀態時，洞察資料內容無法變更。接受的洞察資料會在接受後保留 90 天。
targetResources：洞察資訊所屬資料集的完整資源名稱。例如： //bigquery.googleapis.com/projects/my-project/datasets/my-dataset。

將資料集層級的政策洞察標示為 `ACCEPTED`

如果根據有效洞察資料採取行動，您可以將該洞察資料標示為 ACCEPTED。ACCEPTED 狀態會告知 Recommender API 您已根據這項洞察資料採取行動，有助於改善建議。

接受的洞察資料在標示為 ACCEPTED 後，會保留 90 天。

gcloud

使用 gcloud recommender insights mark-accepted 指令並提供洞察 ID，將洞察標示為 ACCEPTED。

INSIGHT_ID：要查看的洞察 ID。如要找出 ID，請列出專案的洞察。
PROJECT_ID：您要管理洞察資料的專案 ID。
LOCATION：要將洞察標示為 ACCEPTED 的資料集位置。
ETAG：洞察版本的 ID。如要取得 etag，請按照下列步驟操作：
1. 使用 gcloud recommender insights describe 指令取得洞察資料。
2. 從輸出內容中找出並複製 etag 值，包括前後的引號。例如："d3cdec23cc712bd0"。

gcloud recommender insights mark-accepted INSIGHT_ID \
    --insight-type=google.iam.policy.Insight \
    --project=PROJECT_ID \
    --location=LOCATION \
    --etag=ETAG

輸出內容會顯示洞察資料，現在狀態為 ACCEPTED：

associatedRecommendations:
- recommendation: projects/1069248613794/locations/us/recommenders/google.iam.policy.Recommender/recommendations/9327f951-1ceb-488e-9e49-f17eb21f6e5e
category: SECURITY
content:
  condition:
    description: ''
    expression: ''
    location: ''
    title: ''
  currentTotalPermissionsCount: '37'
  exercisedPermissions: []
  inferredPermissions: []
  member: projectEditor:my-project
  role: roles/bigquery.dataEditor
description: 0 of the permissions in this role binding were used in the past 90 days.
etag: '"5f2f352a738f7a24"'
insightSubtype: PERMISSIONS_USAGE_BIGQUERY_DATASET
lastRefreshTime: '2024-02-04T08:00:00Z'
name: projects/1069248613794/locations/us/insightTypes/google.iam.policy.Insight/insights/101d03ad-6148-4628-943e-fcf1a3af6b57
observationPeriod: 7776000s
severity: LOW
stateInfo:
  state: ACCEPTED
targetResources:
- //bigquery.googleapis.com/projects/my-project/datasets/dataset-1

如要進一步瞭解洞察資料的狀態資訊，請參閱本頁的「查看資料集層級的政策洞察資料」。

REST

Recommender API 的 insights.markAccepted 方法會將洞察標示為 ACCEPTED。

使用任何要求資料之前，請先替換以下項目：

PROJECT_ID：您要管理洞察資料的專案 ID。
LOCATION：要將洞察標示為 ACCEPTED 的資料集位置。
INSIGHT_ID：要查看的洞察 ID。如果您不知道洞察 ID，可以列出專案中的洞察來找出 ID。洞察 ID 是洞察name欄位中 insights/ 後方的所有內容。
ETAG：洞察版本的 ID。如要取得 etag，請按照下列步驟操作：
1. 使用 insights.get 方法取得洞察資料。
2. 從回應中找出並複製 etag 值。

HTTP 方法和網址：

POST https://recommender.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/insightTypes/google.iam.policy.Insight/insights/INSIGHT_ID:markAccepted

JSON 要求主體：

{
  "etag": "ETAG"
}

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

curl (Linux、macOS 或 Cloud Shell)

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

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "x-goog-user-project: PROJECT_ID" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://recommender.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/insightTypes/google.iam.policy.Insight/insights/INSIGHT_ID:markAccepted"

PowerShell (Windows)

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

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

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred"; "x-goog-user-project" = "PROJECT_ID" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://recommender.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/insightTypes/google.iam.policy.Insight/insights/INSIGHT_ID:markAccepted" | Select-Object -Expand Content

回應包含洞察資料，現在會顯示 ACCEPTED 的狀態：

{
  "name": "projects/1069248613794/locations/us/insightTypes/google.iam.policy.Insight/insights/101d03ad-6148-4628-943e-fcf1a3af6b57",
  "description": "0 of the permissions in this role binding were used in the past 90 days.",
  "content": {
    "role": "roles/bigquery.dataEditor",
    "member": "projectEditor:my-project",
    "condition": {
      "expression": "",
      "title": "",
      "description": "",
      "location": ""
    },
    "exercisedPermissions": [],
    "inferredPermissions": [],
    "currentTotalPermissionsCount": "37"
  },
  "lastRefreshTime": "2024-02-02T08:00:00Z",
  "observationPeriod": "7779600s",
  "stateInfo": {
    "state": "ACCEPTED"
  },
  "category": "SECURITY",
  "associatedRecommendations": [
    {
      "recommendation": "projects/1069248613794/locations/us/recommenders/google.iam.policy.Recommender/recommendations/9327f952-1ceb-488e-9e49-f17eb21f6e5e"
    }
  ],
  "targetResources": [
    "//bigquery.googleapis.com/projects/my-project/datasets/dataset-1"
  ],
  "insightSubtype": "PERMISSIONS_USAGE_BIGQUERY_DATASET",
  "etag": "\"35d4af47524d3f0c\"",
  "severity": "LOW"
}

如要進一步瞭解洞察資料的狀態資訊，請參閱本頁的「查看資料集層級的政策洞察資料」。

後續步驟

瞭解如何查看及套用 BigQuery 資料集的政策建議。
使用 Active Assist 查看及管理專案的所有建議，包括 IAM 建議。

查看 BigQuery 資料集的政策洞察資料 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

事前準備

必要的角色

所需權限

列出資料集層級政策洞察

gcloud

REST

curl (Linux、macOS 或 Cloud Shell)

PowerShell (Windows)

取得單一資料集層級的政策洞察

gcloud

REST

curl (Linux、macOS 或 Cloud Shell)

PowerShell (Windows)

查看資料集層級的政策洞察

將資料集層級的政策洞察標示為 ACCEPTED

gcloud

REST

curl (Linux、macOS 或 Cloud Shell)

PowerShell (Windows)

後續步驟

查看 BigQuery 資料集的政策洞察資料

將資料集層級的政策洞察標示為 `ACCEPTED`