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

查看及套用機構政策最佳化建議

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

事前準備

Enable the Organization Policy and Recommender APIs.
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 APIs
設定驗證方法。

Select the tab for how you plan to use the samples on this page:
gcloud

In the Google Cloud console, activate Cloud Shell.

Activate Cloud Shell

At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.
REST

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

必要 IAM 角色

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

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

如要查看機構政策建議，請按照下列步驟操作：組織政策建議工具檢視者 (roles/recommender.orgPolicyViewer)
如要套用及關閉機構政策建議：機構政策建議工具管理員 (roles/recommender.orgPolicyAdmin)
如要管理機構政策：機構政策管理員 (roles/orgpolicy.policyAdmin)

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

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

所需權限

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

如要查看機構政策建議：
- 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`