Use the API - Recommendations

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

A typical recommendation interaction with the Recommender API is:

List the recommendations for a specific project.
Mark a recommendation that you intend to apply as claimed, or mark a recommendation that you don't intend to apply as dismissed.
Apply the recommendation. You can do this automatically using Active Assist in the Google Cloud console, or manually using the Google Cloud CLI commands, REST API calls, or other tools.

When you manually apply the recommendation, the commands or calls that you use are specific to the resource type. For example, to change the size of a VM instance in response to a recommendation from the VM instance sizing recommender, you use Compute Engine gcloud commands or calls to the Compute Engine REST API.

When you perform these operations, you identify the target resource by using the value of the resource field in the OperationsGroup array in the returned Recommendation entity. This field is in the following format:
```
//API_NAME/RESOURCE_PATH
```
For example:
```
//compute.googleapis.com/projects/example-project/zones/us-central1-a/instances/instance-1
```
Mark the recommendation as succeeded or failed.

Note that only recommendations retrieved through the API can be interacted with using the API or BigQuery Export.

For information about changing the state of recommendations in the Google Cloud console, refer to the documentation for Active Assist or for the appropriate recommender.

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
RECOMMENDER=RECOMMENDER_ID

where:

TARGET_PROJECT_ID is the project whose recommendations 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 recommendations are located (for example, global or us-central1-a).
RECOMMENDER_ID is the fully-qualified recommender ID (for example, google.compute.instance.MachineTypeRecommender).

See Recommenders for a table of links to information about each recommender, including supported locations and recommender IDs.

Set permissions

You must have permissions to access recommendations 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 recommender requires specific permissions. See Recommenders for a table of links to information about each recommender, including the required permissions.

List recommendations

As shown in the gcloud Beta tab, you can list all of your project's recommendations 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 recommendations list \
    --project=${PROJECT} \
    --format=FORMAT

where FORMAT is a supported gcloud output format, such as json.

For example:

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

gcloud

Enter the following:

gcloud recommender recommendations list \
    --project=${PROJECT} \
    --location=${LOCATION} \
    --recommender=${RECOMMENDER} \
    --format=FORMAT

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

For example:

gcloud recommender recommendations list \
    --project=example-project \
    --location=us-central1-a \
    --recommender=google.compute.instance.MachineTypeRecommender \
    --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}/recommenders/${RECOMMENDER}/recommendations"

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/recommenders/google.compute.instance.MachineTypeRecommender/recommendations"

This operation outputs the current VM instance sizing recommendations in the target project as a list of