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.- For
LOCATION_ID is the Google Cloud location where resources associated with the insights are located (for example,
global
orus-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:my-service-account@example-project.iam.gserviceaccount.com", "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": "admin123@example-project.iam.gserviceaccount.com", "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
.