查看及套用機構政策建議

本頁說明如何查看、解讀及套用組織政策建議。機構政策建議可協助您設定適當的機構政策，不會中斷系統運作。

事前準備

啟用 Organization Policy API 和 Recommender API。
啟用 API 時所需的角色
如要啟用 API，您需要服務使用情形管理員 IAM 角色 (roles/serviceusage.serviceUsageAdmin)，其中包含 serviceusage.services.enable 權限。瞭解如何授予角色。
啟用 API
設定驗證方法。

選取這個頁面上的分頁，瞭解如何使用範例：
gcloud

在 Google Cloud 控制台中啟用 Cloud Shell。

啟用 Cloud Shell

Google Cloud 主控台底部會開啟一個 Cloud Shell 工作階段，並顯示指令列提示。Cloud Shell 是已安裝 Google Cloud CLI 的殼層環境，並已針對您目前的專案設定好相關值。工作階段可能要幾秒鐘的時間才能初始化。
REST

如要在本機開發環境中使用本頁的 REST API 範例，請使用您提供給 gcloud CLI 的憑證。
詳情請參閱 Google Cloud 驗證說明文件中的「使用 REST 進行驗證」。
瞭解機構政策建議。

必要的 IAM 角色

本節說明使用機構政策最佳化建議時所需的 IAM 角色和權限。

如要取得管理組織政策建議所需的權限，請要求管理員在您要管理建議的資源 (專案、資料夾或組織) 中，授予下列 IAM 角色：

如要查看機構政策建議：機構政策建議工具檢視者 (roles/recommender.orgPolicyViewer)
如要套用及關閉機構政策建議：機構政策建議工具管理員 (roles/recommender.orgPolicyAdmin)
如要管理組織政策：機構政策管理員 (roles/orgpolicy.policyAdmin)

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

這些預先定義的角色具備管理組織政策建議所需的權限。如要查看確切的必要權限，請展開「Required permissions」(必要權限) 部分：

所需權限

必須具備下列權限，才能管理組織政策建議：

如要查看機構政策建議：
- recommender.orgPolicyRecommendations.get
- recommender.orgPolicyRecommendations.list
如要套用及略過組織政策建議，請按照下列步驟操作：
- recommender.orgPolicyRecommendations.get
- recommender.orgPolicyRecommendations.list
- recommender.orgPolicyRecommendations.update
如要管理組織政策：
- orgpolicy.policy.get
- orgpolicy.policy.set
- orgpolicy.constraints.list
- orgpolicy.policies.create
- orgpolicy.policies.delete
- orgpolicy.policies.list
- orgpolicy.policies.update

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

限制

組織政策建議工具的預先發布版有下列限制：

只有提供建議的專案、資料夾和機構，才能查看洞察資料。
系統只會針對特定資源或其任何子項資源上未設定的限制條件提供建議。

支援的限制

建議僅適用於下列機構政策限制：

建立服務帳戶金鑰 (iam.managed.disableServiceAccountKeyCreation)
上傳服務帳戶金鑰 (iam.managed.disableServiceAccountKeyUpload)
通訊協定轉送規則 (compute.managed.restrictProtocolForwardingCreationForTypes)

查看及套用建議

您可以使用 Google Cloud CLI 和 Recommender API，查看及套用機構政策建議。

gcloud

查看建議：

如要列出建議，請執行 gcloud recommender recommendations list 指令：

gcloud recommender recommendations list \
    --location=global \
    --recommender=google.orgpolicy.policy.Recommender \
    --RESOURCE_TYPE=RESOURCE_ID \
    --filter="recommenderSubtype:RECOMMENDER_SUBTYPE" \
    --format=FORMAT

替換下列值：

RESOURCE_TYPE：要列出建議的資源類型。請使用 project、folder 或 organization 值。
RESOURCE_ID：您要列出建議的 Google Cloud 專案、資料夾或機構 ID。專案 ID 為英數字元字串，例如 my-project。資料夾和機構 ID 為數字，例如 123456789012。
RECOMMENDER_SUBTYPE：選用。您要查看建議的子類型 ID。有效子類型包括：
- ADD_POLICY_DISABLE_SERVICE_ACCOUNT_KEY_CREATION 提供 iam.managed.disableServiceAccountKeyCreation 限制的建議。
- ADD_POLICY_DISABLE_SERVICE_ACCOUNT_KEY_UPLOAD 提供 iam.managed.disableServiceAccountKeyUpload 限制的建議
FORMAT：回應格式。請使用 json 或 yaml 值。

回應類似下列範例。在本例中，系統分析了兩項資源的外部服務帳戶金鑰，但未偵測到任何違規事項。因此，建議您設定 iam.managed.disableServiceAccountKeyCreation，避免日後違規。

[
  {
    "associatedInsights": [
      {
        "insight": "projects/123456789012/locations/global/insightTypes/google.orgpolicy.policy.Insight/insights/fb927dc1-9695-4436-0000-f0f285007c0f"
      }
    ],
    "content": {
      "operationGroups": [
        {
          "operations": [
            {
              "action": "add",
              "path": "/",
              "resource": "//orgpolicy.googleapis.com/projects/123456789012/policies/iam.managed.disableServiceAccountKeyCreation",
              "resourceType": "orgpolicy.googleapis.com/Policy",
              "value": {
                "etag": "",
                "name": "projects/123456789012/policies/iam.managed.disableServiceAccountKeyCreation",
                "spec": {
                  "etag": "",
                  "inheritFromParent": false,
                  "reset": false,
                  "rules": [
                    {
                      "enforce": true
                    }
                  ]
                }
              }
            }
          ]
        }
      ],
      "overview": {
        "constraint": {
          "id": "constraints/iam.managed.disableServiceAccountKeyCreation",
          "name": "Disable service account key creation"
        },
        "enforcedResources": [
          {
            "numOfResources": "2",
            "resourceType": "iam.googleapis.com/ServiceAccountKey"
          },
          {
            "numOfResources": "1",
            "resourceType": "cloudresourcemanager.googleapis.com/Project"
          }
        ]
      }
    },
    "description": "After analyzing 3 resources and finding 0 violations, Organization Policy Recommender recommends that you disable the creation of service account external keys on your project by enforcing constraints/iam.managed.disableServiceAccountKeyCreation.",
    "etag": "\"826e992a0f9793ff\"",
    "lastRefreshTime": "2024-12-07T08:00:00Z",
    "name": "projects/123456789012/locations/global/recommenders/google.orgpolicy.policy.Recommender/recommendations/fb927dc1-9695-4436-0000-f0f285007c0f",
    "primaryImpact": {
      "category": "SECURITY"
    },
    "priority": "P1",
    "recommenderSubtype": "ADD_POLICY_DISABLE_SERVICE_ACCOUNT_KEY_CREATION",
    "stateInfo": {
      "state": "ACTIVE",
      "stateMetadata": {
        "reviewedBy": "alice",
        "priority": "high"
      }
    },
    "targetResources": [
      "//cloudresourcemanager.googleapis.com/projects/123456789012"
    ]
  }
]

如要進一步瞭解最佳化建議的各個部分，請參閱「瞭解最佳化建議」一文。

如何套用建議：

使用 gcloud recommender recommendations mark-claimed 指令將建議狀態變更為 CLAIMED，防止建議在您套用時變更：

gcloud recommender recommendations mark-claimed \
    RECOMMENDATION_ID \
    --location=global \
    --recommender=google.orgpolicy.policy.Recommender \
    --RESOURCE_TYPE=RESOURCE_ID \
    --format=FORMAT \
    --etag=ETAG \
    --state-metadata=STATE_METADATA

替換下列值：

RECOMMENDATION_ID：建議的專屬 ID。這項值會顯示在建議的 name 欄位結尾。在上述範例中，ID 是 fb927dc1-9695-4436-0000-f0f285007c0f。

RESOURCE_TYPE：要管理建議的資源類型。請使用 project、folder 或 organization 值。

RESOURCE_ID：您要列出建議的 Google Cloud專案、資料夾或機構 ID。專案 ID 為英數字串，例如 my-project。資料夾和機構 ID 都是數字，例如 123456789012。

FORMAT：回應格式。請使用 json 或 yaml 值。

ETAG：建議版本的 ID，例如 "7caf4103d7669e12"。請注意，這個值可以包含引號。

STATE_METADATA：選用。以半形逗號分隔的鍵/值組合，內含您選擇的建議中繼資料。例如：--state-metadata=reviewedBy=alice,priority=high。中繼資料會取代建議中的 stateInfo.stateMetadata 欄位。

如果指令成功執行，回應會顯示建議處於 CLAIMED 狀態，如下列範例所示。為求明確，範例省略了大部分的欄位：


  {
    "description": "After analyzing 3 resources and finding 0 violations, Organization Policy Recommender recommends that you disable the creation of service account external keys on your project by enforcing constraints/iam.managed.disableServiceAccountKeyCreation.",
    "etag": "\"826e992a0f9793ff\"",
    "lastRefreshTime": "2024-12-07T08:00:00Z",
    "name": "projects/123456789012/locations/global/recommenders/google.orgpolicy.policy.Recommender/recommendations/fb927dc1-9695-4436-0000-f0f285007c0f",
    "primaryImpact": {
      "category": "SECURITY"
    },
    "priority": "P1",
    "recommenderSubtype": "ADD_POLICY_DISABLE_SERVICE_ACCOUNT_KEY_CREATION",
    "stateInfo": {
      "state": "CLAIMED",
      "stateMetadata": {\
        "reviewedBy": "alice",
        "priority": "high"
      }
    },
    "targetResources": [
      "//cloudresourcemanager.googleapis.com/projects/123456789012"
    ]
  }

更新及套用 RESOURCE_TYPE 和 RESOURCE_ID 指定的專案、資料夾或機構組織政策，以反映建議。
如果可以套用建議，請將建議狀態更新為 SUCCEEDED；如果無法套用建議，請更新為 FAILED：
```
gcloud recommender recommendations COMMAND \
    RECOMMENDATION_ID \
    --location=global \
    --recommender=google.iam.policy.Recommender \
    --RESOURCE_TYPE=RESOURCE_ID \
    --format=FORMAT \
    --etag=ETAG \
    --state-metadata=STATE_METADATA
```
替換下列值：
- COMMAND：如果成功套用最佳化建議，請使用 mark-succeeded；如果無法套用最佳化建議，請使用 mark-failed。
- RECOMMENDATION_ID：建議的專屬 ID。這項值會顯示在建議的 name 欄位結尾。在上述範例中，ID 是 fb927dc1-9695-4436-0000-f0f285007c0f。
- RESOURCE_TYPE：要管理建議的資源類型。請使用 project、folder 或 organization 值。
- RESOURCE_ID：您要列出建議的 Google Cloud專案、資料夾或機構 ID。專案 ID 為英數字串，例如 my-project。資料夾和機構 ID 都是數字，例如 123456789012。
- FORMAT：回應格式。請使用 json 或 yaml 值。
- ETAG：建議版本的 ID，例如 "7caf4103d7669e12"。請注意，這個值可以包含引號。
- STATE_METADATA：選用。以半形逗號分隔的鍵/值組合，內含您選擇的建議中繼資料。例如：--state-metadata=reviewedBy=alice,priority=high。中繼資料會取代建議中的 stateInfo.stateMetadata 欄位。
舉例來說，如果您將建議標示為成功，回應就會顯示建議處於 SUCCEEDED 狀態。為求明確，這個範例省略了大部分的欄位：
```
  {
    "description": "After analyzing 3 resources and finding 0 violations, Organization Policy Recommender recommends that you disable the creation of service account external keys on your project by enforcing constraints/iam.managed.disableServiceAccountKeyCreation.",
    "etag": "\"826e992a0f9793ff\"",
    "lastRefreshTime": "2024-12-07T08:00:00Z",
    "name": "projects/123456789012/locations/global/recommenders/google.orgpolicy.policy.Recommender/recommendations/fb927dc1-9695-4436-0000-f0f285007c0f",
    "primaryImpact": {
      "category": "SECURITY"
    },
    "priority": "P1",
    "recommenderSubtype": "ADD_POLICY_DISABLE_SERVICE_ACCOUNT_KEY_CREATION",
    "stateInfo": {
      "state": "SUCCEEDED",
      "stateMetadata": {
        "reviewedBy": "alice",
        "priority": "high"
      }
    },
    "targetResources": [
      "//cloudresourcemanager.googleapis.com/projects/123456789012"
    ]
  }
```
如要還原機構政策的變更，請將機構政策設為原始設定，也就是相關洞察資料的 configuredPolicy 欄位中提供的設定。

REST

查看建議：

如要列出專案、資料夾或機構的所有可用建議，請使用 Recommender API 的 recommendations.list 方法。

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

RESOURCE_TYPE：要管理建議的資源類型。請使用 projects、folders 或 organizations 值。
RESOURCE_ID：您要管理建議的Google Cloud 專案、資料夾或組織 ID。專案 ID 為英數字串，例如 my-project。資料夾和機構 ID 為數字，例如 123456789012。
PAGE_SIZE：選用。這項要求傳回的結果數上限。如未指定，伺服器會決定要傳回的結果數量。如果建議數量大於頁面大小，回應會包含分頁符記，可用於擷取下一頁結果。
PAGE_TOKEN：選用。這個方法先前傳回的回應中包含的分頁符記。如果指定，建議清單會從上一個要求結束的位置開始。
FILTER：選用。篩選運算式，用於限制傳回的建議。您可以根據「stateInfo.state」欄位篩選建議。例如 stateInfo.state:"DISMISSED" 或 stateInfo.state:"FAILED"。
PROJECT_ID：您的 Google Cloud 專案 ID。專案 ID 為英數字串，例如 my-project。

HTTP 方法和網址：

GET https://recommender.googleapis.com/v1/RESOURCE_TYPE/RESOURCE_ID/locations/global/recommenders/google.orgpolicy.policy.Recommender/recommendations?pageSize=PAGE_SIZE&pageToken=PAGE_TOKEN&filter=FILTER

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

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/RESOURCE_TYPE/RESOURCE_ID/locations/global/recommenders/google.orgpolicy.policy.Recommender/recommendations?pageSize=PAGE_SIZE&pageToken=PAGE_TOKEN&filter=FILTER"

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/RESOURCE_TYPE/RESOURCE_ID/locations/global/recommenders/google.orgpolicy.policy.Recommender/recommendations?pageSize=PAGE_SIZE&pageToken=PAGE_TOKEN&filter=FILTER" | Select-Object -Expand Content

回應類似下列範例。在本範例中，系統分析了兩項資源的外部服務帳戶金鑰，但未偵測到任何違規事項。因此，建議您將 iam.managed.disableServiceAccountKeyCreation 設為「否」，以免日後違規。

[
  {
    "associatedInsights": [
      {
        "insight": "projects/123456789012/locations/global/insightTypes/google.orgpolicy.policy.Insight/insights/66d543f3-845d-49d6-a26b-80d84804d8a8"
      }
    ],
    "content": {
      "operationGroups": [
        {
          "operations": [
            {
              "action": "add",
              "path": "/",
              "resource": "//orgpolicy.googleapis.com/projects/123456789012/policies/iam.managed.disableServiceAccountKeyCreation",
              "resourceType": "orgpolicy.googleapis.com/Policy",
              "value": {
                "etag": "",
                "name": "projects/123456789012/policies/iam.managed.disableServiceAccountKeyCreation",
                "spec": {
                  "etag": "",
                  "inheritFromParent": false,
                  "reset": false,
                  "rules": [
                    {
                      "enforce": true
                    }
                  ]
                }
              }
            }
          ]
        }
      ],
      "overview": {
        "constraint": {
          "id": "constraints/iam.managed.disableServiceAccountKeyCreation",
          "name": "Disable service account key creation"
        },
        "enforcedResources": [
          {
            "numOfResources": "2",
            "resourceType": "iam.googleapis.com/ServiceAccountKey"
          },
          {
            "numOfResources": "1",
            "resourceType": "cloudresourcemanager.googleapis.com/Project"
          }
        ]
      }
    },
    "description": "After analyzing 3 resources and finding 0 violations, Organization Policy Recommender recommends that you disable the creation of service account external keys on your project by enforcing constraints/iam.managed.disableServiceAccountKeyCreation.",
    "etag": "\"826e992a0f9793ff\"",
    "lastRefreshTime": "2024-12-07T08:00:00Z",
    "name": "projects/123456789012/locations/global/recommenders/google.orgpolicy.policy.Recommender/recommendations/fb927dc1-9695-4436-0000-f0f285007c0f",
    "primaryImpact": {
      "category": "SECURITY"
    },
    "priority": "P1",
    "recommenderSubtype": "ADD_POLICY_DISABLE_SERVICE_ACCOUNT_KEY_CREATION",
    "stateInfo": {
      "state": "ACTIVE",
      "stateMetadata": {
        "reviewedBy": "alice",
        "priority": "high"
      }
    },
    "targetResources": [
      "//cloudresourcemanager.googleapis.com/projects/123456789012"
    ]
  }
]

如要進一步瞭解最佳化建議的各個部分，請參閱「瞭解最佳化建議」一文。

如何套用建議：

將建議標示為CLAIMED：

如要將建議標示為 CLAIMED，防止建議在您套用時變更，請使用 Recommender API 的 recommendations.markClaimed 方法。

使用任何要求資料之前，請先修改下列項目的值：
- RESOURCE_TYPE：要管理建議的資源類型。請使用 projects、folders 或 organizations 值。
- RESOURCE_ID：您要管理建議的Google Cloud 專案、資料夾或組織 ID。專案 ID 為英數字串，例如 my-project。資料夾和機構 ID 為數字，例如 123456789012。
- RECOMMENDATION_ID：建議的專屬 ID。這個值會顯示在建議的 name 欄位結尾。舉例來說，如果 name 欄位為 projects/example-project/locations/global/recommenders/google.iam.policy.Recommender/recommendations/fb927dc1-9695-4436-0000-f0f285007c0f，則建議 ID 為 fb927dc1-9695-4436-0000-f0f285007c0f。
- ETAG：建議中 etag 欄位的值，例如 "dd0686e7136a4cbb"。使用反斜線逸出引號，例如 "\"df7308cca9719dcc\""。
- STATE_METADATA：選用。這個物件包含鍵/值組合，其中含有您選擇的建議中繼資料。例如：{"reviewedBy": "alice", "priority": "high"}。中繼資料會取代建議中的 stateInfo.stateMetadata 欄位。
- PROJECT_ID：您的 Google Cloud 專案 ID。專案 ID 為英數字串，例如 my-project。
HTTP 方法和網址：
```
POST https://recommender.googleapis.com/v1/RESOURCE_TYPE/RESOURCE_ID/locations/global/recommenders/google.orgpolicy.policy.Recommender/recommendations/RECOMMENDATION_ID:markClaimed
```
JSON 要求主體：
```
{
  "etag": "ETAG",
  "stateMetadata": {
    "STATE_METADATA"
  }
}
```
請展開以下其中一個選項，以傳送要求：
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 "x-goog-user-project: PROJECT_ID" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://recommender.googleapis.com/v1/RESOURCE_TYPE/RESOURCE_ID/locations/global/recommenders/google.orgpolicy.policy.Recommender/recommendations/RECOMMENDATION_ID:markClaimed"
```
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/RESOURCE_TYPE/RESOURCE_ID/locations/global/recommenders/google.orgpolicy.policy.Recommender/recommendations/RECOMMENDATION_ID:markClaimed" | Select-Object -Expand Content
```
回應會以 CLAIMED 狀態顯示建議，如下列範例所示。為求明確，這個範例省略了大部分的欄位：
```
{
  "description": "After analyzing 3 resources and finding 0 violations, Organization Policy Recommender recommends that you disable the creation of service account external keys on your project by enforcing constraints/iam.managed.disableServiceAccountKeyCreation.",
  "etag": "\"826e992a0f9793ff\"",
  "lastRefreshTime": "2024-12-07T08:00:00Z",
  "name": "projects/123456789012/locations/global/recommenders/google.orgpolicy.policy.Recommender/recommendations/fb927dc1-9695-4436-0000-f0f285007c0f",
  "primaryImpact": {
    "category": "SECURITY"
  },
  "priority": "P1",
  "recommenderSubtype": "ADD_POLICY_DISABLE_SERVICE_ACCOUNT_KEY_CREATION",
  "stateInfo": {
    "state": "CLAIMED",
    "stateMetadata": {
      "reviewedBy": "alice",
      "priority": "high"
    }
  },
  "targetResources": [
    "//cloudresourcemanager.googleapis.com/projects/123456789012"
  ]
}
```
更新專案、資料夾或機構的組織政策 (由 RESOURCE_TYPE 和 RESOURCE_ID 指定)，確保政策符合建議。
如果成功套用建議，請將建議狀態更新為 SUCCEEDED；如果無法套用建議，請更新為 FAILED：
SUCCEEDED

如要將建議標示為 SUCCEEDED，表示您已套用建議，請使用 Recommender API 的 recommendations.markSucceeded 方法。

使用任何要求資料之前，請先修改下列項目的值：
- RESOURCE_TYPE：要管理建議的資源類型。請使用 projects、folders 或 organizations 值。
- RESOURCE_ID：您要管理建議的Google Cloud 專案、資料夾或組織 ID。專案 ID 為英數字串，例如 my-project。資料夾和機構 ID 為數字，例如 123456789012。
- RECOMMENDATION_ID：建議的專屬 ID。這個值會顯示在建議的 name 欄位結尾。舉例來說，如果 name 欄位為 projects/example-project/locations/global/recommenders/google.iam.policy.Recommender/recommendations/fb927dc1-9695-4436-0000-f0f285007c0f，則建議 ID 為 fb927dc1-9695-4436-0000-f0f285007c0f。
- ETAG：建議中 etag 欄位的值，例如 "dd0686e7136a4cbb"。使用反斜線逸出引號，例如 "\"df7308cca9719dcc\""。
- STATE_METADATA：選用。這個物件包含鍵/值組合，其中含有您選擇的建議中繼資料。例如：{"reviewedBy": "alice", "priority": "high"}。中繼資料會取代建議中的 stateInfo.stateMetadata 欄位。
- PROJECT_ID：您的 Google Cloud 專案 ID。專案 ID 為英數字串，例如 my-project。
HTTP 方法和網址：
POST https://recommender.googleapis.com/v1/RESOURCE_TYPE/RESOURCE_ID/locations/global/recommenders/google.orgpolicy.policy.Recommender/recommendations/RECOMMENDATION_ID:markSucceeded
JSON 要求主體：
{ "etag": "ETAG", "stateMetadata": { "STATE_METADATA" } }
請展開以下其中一個選項，以傳送要求：
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 "x-goog-user-project: PROJECT_ID" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://recommender.googleapis.com/v1/RESOURCE_TYPE/RESOURCE_ID/locations/global/recommenders/google.orgpolicy.policy.Recommender/recommendations/RECOMMENDATION_ID:markSucceeded"
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/RESOURCE_TYPE/RESOURCE_ID/locations/global/recommenders/google.orgpolicy.policy.Recommender/recommendations/RECOMMENDATION_ID:markSucceeded" | Select-Object -Expand Content
回應會以 SUCCEEDED 狀態顯示建議，如下列範例所示。為求明確，這個範例省略了大部分的欄位：
{ "description": "After analyzing 3 resources and finding 0 violations, Organization Policy Recommender recommends that you disable the creation of service account external keys on your project by enforcing constraints/iam.managed.disableServiceAccountKeyCreation.", "etag": "\"826e992a0f9793ff\"", "lastRefreshTime": "2024-12-07T08:00:00Z", "name": "projects/123456789012/locations/global/recommenders/google.orgpolicy.policy.Recommender/recommendations/fb927dc1-9695-4436-0000-f0f285007c0f", "primaryImpact": { "category": "SECURITY" }, "priority": "P1", "recommenderSubtype": "ADD_POLICY_DISABLE_SERVICE_ACCOUNT_KEY_CREATION", "stateInfo": { "state": "SUCCEEDED", "stateMetadata": { "reviewedBy": "alice", "priority": "high" } }, "targetResources": [ "//cloudresourcemanager.googleapis.com/projects/123456789012" ] }
FAILED

如要將建議標示為 FAILED，表示您無法套用建議，請使用 Recommender API 的 recommendations.markFailed 方法。

使用任何要求資料之前，請先修改下列項目的值：
- RESOURCE_TYPE：要管理建議的資源類型。請使用 projects、folders 或 organizations 值。
- RESOURCE_ID：您要管理建議的Google Cloud 專案、資料夾或組織 ID。專案 ID 為英數字串，例如 my-project。資料夾和機構 ID 為數字，例如 123456789012。
- RECOMMENDATION_ID：建議的專屬 ID。這個值會顯示在建議的 name 欄位結尾。舉例來說，如果 name 欄位為 projects/example-project/locations/global/recommenders/google.iam.policy.Recommender/recommendations/fb927dc1-9695-4436-0000-f0f285007c0f，則建議 ID 為 fb927dc1-9695-4436-0000-f0f285007c0f。
- ETAG：建議中 etag 欄位的值，例如 "dd0686e7136a4cbb"。使用反斜線逸出引號，例如 "\"df7308cca9719dcc\""。
- STATE_METADATA：選用。這個物件包含鍵/值組合，其中含有您選擇的建議中繼資料。例如：{"reviewedBy": "alice", "priority": "high"}。中繼資料會取代建議中的 stateInfo.stateMetadata 欄位。
- PROJECT_ID：您的 Google Cloud 專案 ID。專案 ID 為英數字串，例如 my-project。
HTTP 方法和網址：
POST https://recommender.googleapis.com/v1/RESOURCE_TYPE/RESOURCE_ID/locations/global/recommenders/google.orgpolicy.policy.Recommender/recommendations/RECOMMENDATION_ID:markFailed
JSON 要求主體：
{ "etag": "ETAG", "stateMetadata": { "STATE_METADATA" } }
請展開以下其中一個選項，以傳送要求：
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 "x-goog-user-project: PROJECT_ID" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://recommender.googleapis.com/v1/RESOURCE_TYPE/RESOURCE_ID/locations/global/recommenders/google.orgpolicy.policy.Recommender/recommendations/RECOMMENDATION_ID:markFailed"
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/RESOURCE_TYPE/RESOURCE_ID/locations/global/recommenders/google.orgpolicy.policy.Recommender/recommendations/RECOMMENDATION_ID:markFailed" | Select-Object -Expand Content
回應會以 FAILED 狀態顯示建議，如下列範例所示。為求明確，這個範例省略了大部分的欄位：
{ "description": "After analyzing 3 resources and finding 0 violations, Organization Policy Recommender recommends that you disable the creation of service account external keys on your project by enforcing constraints/iam.managed.disableServiceAccountKeyCreation.", "etag": "\"826e992a0f9793ff\"", "lastRefreshTime": "2024-12-07T08:00:00Z", "name": "projects/123456789012/locations/global/recommenders/google.orgpolicy.policy.Recommender/recommendations/fb927dc1-9695-4436-0000-f0f285007c0f", "primaryImpact": { "category": "SECURITY" }, "priority": "P1", "recommenderSubtype": "ADD_POLICY_DISABLE_SERVICE_ACCOUNT_KEY_CREATION", "stateInfo": { "state": "FAILED", "stateMetadata": { "reviewedBy": "alice", "priority": "high" } }, "targetResources": [ "//cloudresourcemanager.googleapis.com/projects/123456789012" ] }

瞭解建議

每項建議都包含相關資訊，協助您瞭解建議的原因，以及組織政策設定的變更建議。核心屬性包括：

description：建議的摘要，方便使用者閱讀。
recommenderSubtype：建議子類型的 ID。每個限制條件都有專屬的 recommenderSubtype。
content：包含機構政策的建議變更。
- overview：建議的簡要總覽資訊。
- constraint：提供限制的相關資訊。
- enforced_resources：提供資訊，說明套用建議後，這項機構政策會影響哪些資源。
- operationGroups：套用建議時，對機構政策執行的一或多項作業。
associatedInsights：導致這項建議的洞察資源名稱。

如要進一步瞭解建議的屬性，請參閱建議參考資料。

如果資源或其任何子項資源未設定支援的組織政策，系統就會為這些資源產生洞察資料和建議。如要查看這項建議所依據的組織政策設定，請查看與建議相關聯的組織政策洞察。這些洞察資料會列在 associatedInsights 欄位中。如要查看與建議相關聯的機構政策洞察資料，請按照下列步驟操作：

找出「associatedInsights」欄位中屬於機構政策洞察的洞察資料。組織政策洞察的洞察類型為 google.orgpolicy.policy.Insight。此類型會顯示在 insight 欄位中的 insightTypes 後方。
複製機構政策洞察的 ID。ID 是「insight」欄位中「insights/」後的所有內容。舉例來說，如果洞察欄位顯示 projects/123456789012/locations/us/insightTypes/google.orgpolicy.policy.Insight/insights/fb927dc1-9695-4436-0000-f0f285007c0f，洞察 ID 就是 fb927dc1-9695-4436-0000-f0f285007c0f。
按照操作說明，使用您複製的洞察 ID 取得機構政策洞察。

將建議匯出至 BigQuery

如要查看貴機構所有建議的每日快照 (包括機構政策建議)，您可以將建議匯出至 BigQuery。

如要將建議匯出至 BigQuery，您需要使用 BigQuery 資料移轉服務設定資料移轉作業。如要瞭解如何設定資料轉移作業，請參閱「將建議匯出至 BigQuery」一文。

後續步驟

進一步瞭解建議工具。
瞭解如何使用機構政策洞察。

查看及套用機構政策建議

事前準備

gcloud

REST

必要的 IAM 角色

所需權限

限制

支援的限制

查看及套用建議

gcloud

REST

curl (Linux、macOS 或 Cloud Shell)

PowerShell (Windows)

curl (Linux、macOS 或 Cloud Shell)

PowerShell (Windows)

`SUCCEEDED`

curl (Linux、macOS 或 Cloud Shell)

PowerShell (Windows)

`FAILED`

curl (Linux、macOS 或 Cloud Shell)

PowerShell (Windows)

瞭解建議

將建議匯出至 BigQuery

後續步驟

查看及套用機構政策建議 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

事前準備

gcloud

REST

必要的 IAM 角色

所需權限

限制

支援的限制

查看及套用建議

gcloud

REST

curl (Linux、macOS 或 Cloud Shell)

PowerShell (Windows)

curl (Linux、macOS 或 Cloud Shell)

PowerShell (Windows)

SUCCEEDED

curl (Linux、macOS 或 Cloud Shell)

PowerShell (Windows)

FAILED

curl (Linux、macOS 或 Cloud Shell)

PowerShell (Windows)

瞭解建議

將建議匯出至 BigQuery

後續步驟

查看及套用機構政策建議

`SUCCEEDED`

`FAILED`