Use the API - Recommendations

This page explains how to view and managerecommendations inRecommender by usinggcloud commandsor theREST API.

A typical recommendation interaction with the Recommender API is:

1. List the recommendations for aspecific project.

2. Mark a recommendation that you intend toapply asclaimed, or mark a recommendation that you don't intend to applyasdismissed.

3. Apply the recommendation. You can do this automaticallyusing Active Assistin 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 youuse are specific to the resource type. For example, to change the size of aVM instance in response to a recommendation from the VM instance sizingrecommender, you use Compute Enginegcloud commands or calls tothe Compute EngineREST API.

   When you perform these operations, you identify the target resource by usingthe value of theresource field in theOperationsGroup array in thereturnedRecommendationentity. 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

4. Mark the recommendation assucceeded orfailed.

Note that only recommendations retrieved through the API can be interacted withusing the API orBigQuery Export.

For information about changing the state of recommendations in theGoogle Cloud console, refer to the documentation forActive Assistor for the appropriaterecommender.

gcloud config set projectPROJECT_ID

PROJECT=TARGET_PROJECT_IDLOCATION=LOCATION_IDRECOMMENDER=RECOMMENDER_ID

• TARGET_PROJECT_ID is the project whose recommendationsyou want to list. This can be a different project than your current project.

  • Forgcloud commands, you must use the project ID
  • For API requests, you can use the project number or project ID. Projectnumber is recommended.

  The project number is returned in responses from both the API andgcloudcommands.

• LOCATION_ID is the Google Cloudlocation where resourcesassociated with the recommendations are located (for example,global orus-central1-a).

• RECOMMENDER_ID is the fully-qualifiedrecommender ID (for example,google.compute.instance.MachineTypeRecommender).

SeeRecommenders for a table of links toinformation about each recommender, including supported locations andrecommender IDs.

Set permissions

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

• For requesters who include abilling project in their request. The projectused in the request must be in good standing, and the user must have a role inthe project that contains theserviceusage.services.use permission. TheService Usage Consumer role contains the required permission.
• Each recommender requires specific permissions. SeeRecommenders for a table of links toinformation about each recommender, including the required permissions.

List recommendations

As shown in thegcloud Beta tab, you can list all of your project'srecommendations without having to specify a location and recommender. Thisfeature is in Preview.

The GA feature requires that you specify aproject, location, and recommender. For details, see thegcloud tab.

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

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

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

gcloud recommender recommendations list \    --project=example-project \    --location=us-central1-a \    --recommender=google.compute.instance.MachineTypeRecommender \    --format=json

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"

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 recommendationsin the target project as a list ofRecommendationentities in the specified format.

The output is similar to the following:

[  {    "content": {      "operationGroups": [        {          "operations": [            {              "action": "test",              "path": "/machineType",              "resource": "//compute.googleapis.com/projects/example-project/zones/us-central1-a/instances/instance-1",              "resourceType": "compute.googleapis.com/Instance",              "valueMatcher": {                "matchesPattern": ".*zones/us-central1-a/machineTypes/n1-standard-4"              }            },            {              "action": "replace",              "path": "/machineType",              "resource": "//compute.googleapis.com/projects/example-project/zones/us-central1-a/instances/instance-1",              "resourceType": "compute.googleapis.com/Instance",              "value": "zones/us-central1-a/machineTypes/custom-2-5120"            }          ]        }      ]    },    "description": "Save cost by changing machine type from n1-standard-4 to custom-2-5120.",    "etag": "\"280b34810bba8a1a\"",    "lastRefreshTime": "2019-06-28T06:49:21Z",    "name": "projects/32428390823/locations/us-central1-a/recommenders/google.compute.instance.MachineTypeRecommender/recommendations/a523ff7e-ed03-4143-a3a5-5b396b99cba9",    "primaryImpact": { ... },    "stateInfo": {      "state": "ACTIVE"    },    "recommenderSubtype": "CHANGE_MACHINE_TYPE"  }]

Note that the returned recommendations include the following fields:

• Aname field in the following format:

  projects/PROJECT_ID/locations/LOCATION/recommenders/RECOMMENDER_ID/recommendations/RECOMMENDATION_ID

  whereRECOMMENDATION_ID uniquely identifies the recommendation

• Anetag field that is associated with the current recommendation state.

When you reference a recommendation using subsequentGoogle Cloud CLI commands orREST API calls, you reference both the recommendation ID and etag, which makessure that any operations are performed only if the recommendation has notbeen modified since you last retrieved it.

Change the state of a recommendation

You can mark a recommendation as claimed to indicate that you intend to applythe recommended changes to the associated resource. When a recommendation isclaimed, your username is assigned as the actor for the recommendation, andRecommender does not update the recommendation with newer content.

You can mark a recommendation as dismissed to indicate that you don't intend toapply the recommended changes to the associated resource or that you don't wantto continue to see the recommendation. When a recommendation is dismissed, itwill no longer appear as an ACTIVE recommendation. Recommender mightcontinue to update the recommendation with newer content.

After you have applied a recommendation, you can mark it as succeeded or failed.

To change the state of a recommendation, complete the following steps:

gcloud recommender recommendationsSTATE_CHANGE \RECOMMENDATION_ID \    --project=${PROJECT} \    --location=${LOCATION} \    --recommender=${RECOMMENDER} \    --etag=ETAG \    --state-metadata=STATE_METADATA \    --format=FORMAT

gcloud recommender recommendations mark-succeeded \    a523ff7e-ed03-4143-a3a5-5b396b99cba9 \    --project=example-project \    --location=us-central1-a \    --recommender=google.compute.instance.MachineTypeRecommender \    --etag='"5e3a63cccf1e0964"' \    --state-metadata=priority=high,tracking_number=12345 \    --format=json

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}/recommenders/${RECOMMENDER}/recommendations/RECOMMENDATION_ID:STATE_CHANGE \<< EOM{  "etag": "ETAG"  "stateMetadata":STATE_METADATA}EOM

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/us-central1-a/recommenders/google.compute.instance.MachineTypeRecommender/recommendations/8f20d509-83d2-45d2-8152-1b8d5d7d5831:markSucceeded \<< EOM{  "etag": "\"280b34810bba8a1a\""  "stateMetadata": {    "priority" : "high",    "tracking_number": "12345"  }}EOM

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

The output is similar to the following:

{  "content": {    "operationGroups": [ ... ]  },  "description": "Save cost by changing machine type from n1-standard-4 to custom-2-5120.",  "etag": "\"5e3a63cccf1e053c\"",  "lastRefreshTime": "2019-06-28T06:49:21Z",  "name": "projects/32428390823/locations/us-central1-a/recommenders/google.compute.instance.MachineTypeRecommender/recommendations/a523ff7e-ed03-4143-a3a5-5b396b99cba9",  "primaryImpact": { ... },  "stateInfo": {    "state": "SUCCEEDED",    "stateMetadata": {      "priority" : "high",      "tracking_number": "12345"    }  }}

Note that the value of thestate field has changed toSUCCEEDED.