Use the API - Insights

This page explains how to view and manage insights in Recommender using gcloud commands or the REST API.

A typical insight interaction with the Recommender API is:

List the insights for a specific project
Mark an insight that you intend to take action on as accepted

For information about changing the state of insights in the Google Cloud console, refer to the documentation for the Recommendation Hub or for the appropriate insight type.

Set the default project

Set the default project if you haven't done so already:

gcloud config set project PROJECT_ID

where PROJECT_ID is the ID of your project.

Set environment variables

Set environment variables for Recommender interactions:

PROJECT=TARGET_PROJECT_ID
LOCATION=LOCATION_ID
INSIGHT_TYPE=INSIGHT_TYPE_ID

where:

TARGET_PROJECT_ID is the project whose insights you want to list. This can be a different project than your current project.
- For gcloud commands, you must use the project ID
- For API requests, you can use the project number or project ID. Project number is recommended.
The project number is returned in responses from both the API and gcloud commands.
LOCATION_ID is the Google Cloud location where resources associated with the insights are located (for example, global or us-central1-a).
INSIGHT_TYPE_ID is the fully-qualified insight type ID (for example, google.iam.policy.Insight).

See Insight types for a table of links to information about each insight type, including supported locations and insight type IDs.

Set permissions

You must have permissions to access insights in the target project.

For requesters who include a billing project in their request. The project used in the request must be in good standing, and the user must have a role in the project that contains the serviceusage.services.use permission. The Service Usage Consumer role contains the required permission.
Each insight type requires specific permissions. See Insight types for a table of links to information about each insight type, including the required permissions.

List insights

As shown in the gcloud Beta tab, you can list all of your project's insights without having to specify a location and recommender. This feature is in Preview.

The GA feature requires that you specify a project, location, and recommender. For details, see the gcloud tab.

gcloud Beta

Enter the following:

gcloud beta recommender insights list \
    --project=${PROJECT} \
    --format=FORMAT

where FORMAT is a supported Google Cloud CLI output format, such as json.

For example:

gcloud beta recommender insights list \
    --project=example-project \
    --format=json

gcloud

Enter the following:

gcloud recommender insights list \
    --project=${PROJECT} \
    --location=${LOCATION} \
    --insight-type=${INSIGHT_TYPE} \
    --format=FORMAT

where FORMAT is a supported gcloud output format (for example, json).

For example:

gcloud recommender insights list \
    --project=example-project \
    --location=global \
    --insight-type=google.iam.policy.Insight \
    --format=json

REST

Enter the following:

curl \
    -H "Authorization: Bearer $(gcloud auth print-access-token)"  \
    -H "x-goog-user-project: ${PROJECT}" \
    "https://recommender.googleapis.com/v1/projects/${PROJECT}/locations/${LOCATION}/insightTypes/${INSIGHT_TYPE}/insights"

For example:

curl \
    -H "Authorization: Bearer $(gcloud auth print-access-token)"  \
    -H "x-goog-user-project: example-project" \
    "https://recommender.googleapis.com/v1/projects/example-project/locations/us-central1-a/insightTypes/google.iam.policy.Insight/insights"

This operation outputs the current IAM policy insights in the target project as a list of Insight entities in the specified format.

The output is similar to the following:

[
  {
    "category": "SECURITY",
    "content": {
      "condition": {
        "description": "",
        "expression": "",
        "location": "",
        "title": ""
      },
      "exercisedPermissions": [],
      "inferredPermissions": [],
      "member": "user:[email protected]",
      "role": "roles/iam.securityReviewer"
    },
    "description": "0 permission checks were authorized by this policy binding tuple.",
    "etag": "\"45f4e2c63f6952e8\"",
    "insightSubtype": "PERMISSIONS_USAGE",
    "lastRefreshTime": "2020-03-06T08:00:00Z",
    "name": "projects/32428390823/locations/global/insightTypes/google.iam.policy.Insight/insights/a523ff7e-ed03-4143-a3a5-5b396b99cba9",
    "observationPeriod": "7776000s",
    "stateInfo": {
      "state": "ACTIVE",
    },
    "targetResources": [
      "//cloudresourcemanager.googleapis.com/projects/32428390823"
    ],
  }
]

Note that the returned insights include the following fields:

A name field in the following format:

projects/PROJECT_ID/locations/LOCATION/insightTypes/INSIGHT_TYPE_ID/insights/INSIGHT_ID

where INSIGHT_ID uniquely identifies the insight

An etag field that is associated with the current insight state.

When you reference an insight using subsequent gcloud commands or REST API calls, you reference both the insight ID and etag, which makes sure that any operations are performed only if the insight has not been modified since you last retrieved it.

Mark an insight as accepted

You can mark an insight as accepted to indicate that you intend to take or have taken an action on an associated resource based on the information provided in the insight. When an insight is accepted, your user name is assigned as the actor for the insight, and Recommender will not update the insight with newer content.

To mark an insight as accepted:

gcloud

Enter the following:

gcloud recommender insights mark-accepted \
    INSIGHT_ID \
    --project=${PROJECT} \
    --location=${LOCATION} \
    --insight-type=${INSIGHT_TYPE} \
    --etag=etag \
    --state-metadata=STATE_METADATA
    --format=FORMAT

where:

INSIGHT_ID is the ID of an insight retrieved from a previous call to list insights
etag is the returned etag representing the insight state
STATE_METADATA is an optional metadata about the operation. Specify the metadata as a comma-separated list of KEY=VALUE pairs.

For example:

gcloud recommender insights mark-accepted \
    a523ff7e-ed03-4143-a3a5-5b396b99cba9 \
    --project=example-project \
    --location=global \
    --insight-type=google.iam.policy.Insight \
    --etag='"280b34810bba8a1a"' \
    --state-metadata=priority=high,tracking_number=12345
    --format=json

REST

Enter the following:

curl -X POST \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $(gcloud auth print-access-token)"  \
    -H "x-goog-user-project: ${PROJECT}" \
    --data-binary @- \
    https://recommender.googleapis.com/v1/projects/${PROJECT}/locations/${LOCATION}/insightTypes/${INSIGHT_TYPE}/insights/INSIGHT_ID:markAccepted \
<< EOM
{
  "etag": "etag",
  "stateMetadata": STATE_METADATA
}
EOM

where:

INSIGHT_ID is the ID of an insight retrieved from a previous call to list insights
etag is the returned etag representing the insight state
STATE_METADATA is an optional field with additional metadata about the operation. Specify the metadata as key:value pairs.

For example:

curl -X POST \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $(gcloud auth print-access-token)"  \
    -H "x-goog-user-project: example-project" \
    --data-binary @- \
    https://recommender.googleapis.com/v1/projects/example-project/locations/global/insightTypes/google.iam.policy.Insight/insights/a523ff7e-ed03-4143-a3a5-5b396b99cba9:markAccepted \
<< EOM
{
  "etag": "\"280b34810bba8a1a\""
  "stateMetadata": {
    "priority" : "high",
    "tracking_number": "12345"
  }
}
EOM

This operation returns the Insight entity in the specified format after the operation has taken place.

The output is similar to the following:

{
  "category": "SECURITY",
  "content": { ...  },
  "description": "0 permission checks were authorized by this policy binding tuple.",
  "etag": "\"356ae51165729f38\"",
  "insightSubtype": "PERMISSIONS_USAGE",
  "lastModifiedUser": "[email protected]",
  "lastRefreshTime": "2020-03-06T08:00:00Z",
  "name": "projects/32428390823/locations/global/insightTypes/google.iam.policy.Insight/insights/a523ff7e-ed03-4143-a3a5-5b396b99cba9",
  "observationPeriod": "7776000s",
  "stateInfo": {
    "state": "ACCEPTED",
    "stateMetadata": {
      "priority" : "high",
      "tracking_number": "12345"
    }
  },
  "targetResources": [
    "//cloudresourcemanager.googleapis.com/projects/32428390823"
  ],
  "userLastUpdateTime": "2020-03-31T20:57:50.509855Z"
}

Note that the value of the state field has changed to ACCEPTED.