Using the API

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

A typical interaction with the Recommender API is:

  • List recommendations currently available by recommender
  • Mark a recommendations that you intend to apply as claimed
  • Apply the recommendation using gcloud commands or REST API calls specific to the resource type (for example, Cloud IAM roles or Compute Engine VM instances)
  • Mark the recommendation as succeeded or failed

For information about changing the state of recommendations in the Boogle Cloud Console, refer to the documentation 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 Boogle 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, g.u.00rz.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. These permissions vary by recommender. See Recommenders for a table of links to information about each recommender, including the required permissions.

List recommendations

To list recommendations in the target project:

gcloud

Enter the following:

gcloud beta 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 beta recommender recommendations list \
    --project=example-project \
    --location=us-central1-a \
    --recommender=g.u.00rz.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/v1beta1/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/v1beta1/projects/example-project/locations/us-central1-a/recommenders/g.u.00rz.compute.instance.MachineTypeRecommender/recommendations"

This operation outputs the current VM instance sizing recommendations in the target project as a list of Recommendation entities 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/g.u.00rz.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:

  • A name field in the following format:

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

    where RECOMMENDATION_ID uniquely identifies the recommendation

  • An etag field that is associated with the current recommendation state.

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

Mark a recommendation as claimed

You can mark a recommendation as claimed to indicate that you intend to apply the recommended changes to the associated resource. When a recommendation is is claimed, your user name is assigned as the actor for the recommendation and Recommender does not update the recommendation with newer content.

To mark a recommendation as claimed:

gcloud

Enter the following:

gcloud beta recommender recommendations mark-claimed \
    RECOMMENDATION_ID \
    --project=${PROJECT} \
    --location=${LOCATION} \
    --recommender=${RECOMMENDER} \
    --etag=etag \
    --state-metadata=STATE_METADATA
    --format=FORMAT

where:

  • RECOMMENDATION_ID is the ID of a recommendation that you retrieved from a previous call to list recommendations
  • etag is the returned etag representing the recommendation state
  • STATE_METADATA is an optional metadata about the operation. Specify the metadata as a common-separated list of KEY=VALUE pairs. This option is available when you mark a recommendation as claimed, succeeded, or failed.

For example:

gcloud beta recommender recommendations mark-claimed \
    a523ff7e-ed03-4143-a3a5-5b396b99cba9 \
    --project=example-project \
    --location=us-central1-a \
    --recommender=g.u.00rz.compute.instance.MachineTypeRecommender \
    --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/v1beta1/projects/${PROJECT}/locations/${LOCATION}/recommenders/${RECOMMENDER}/recommendations/RECOMMENDATION_ID:markClaimed \
<< EOM
{
  "etag": "etag",
  "stateMetadata": STATE_METADATA
}
EOM

where:

  • RECOMMENDATION_ID is the ID of a recommendation that you retrieved from a previous call to list recommendations
  • etag is the returned etag representing the recommendation state
  • STATE_METADATA is an optional field with additional metadata about the operation. Specify the metadata as key:value pairs. This field is available when you mark a recommendation as claimed, succeeded, or failed.

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/v1beta1/projects/example-project/locations/us-central1-a/recommenders/g.u.00rz.compute.instance.MachineTypeRecommender/recommendations/8f20d509-83d2-45d2-8152-1b8d5d7d5831:markClaimed \
<< EOM
{
  "etag": "\"280b34810bba8a1a\""
  "stateMetadata": {
    "priority" : "high",
    "tracking_number": "12345"
  }
}
EOM

This operation returns the Recommendation entity 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": "\"5e3a63cccf1e0964\"",
  "lastRefreshTime": "2019-06-28T06:49:21Z",
  "name": "projects/32428390823/locations/us-central1-a/recommenders/g.u.00rz.compute.instance.MachineTypeRecommender/recommendations/a523ff7e-ed03-4143-a3a5-5b396b99cba9",
  "primaryImpact": { ... },
  "stateInfo": {
    "state": "CLAIMED"
  }
}

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

Applying recommendations

After you have marked a recommendation as claimed, you can apply the recommendation using gcloud commands or REST API calls that 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 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"

Changing the state of a recommendation

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

To mark a recommendation as succeeded:

gcloud

Enter the following:

gcloud beta recommender recommendations STATE_CHANGE \
    RECOMMENDATION_ID \
    --project=${PROJECT} \
    --location=${LOCATION} \
    --recommender=${RECOMMENDER} \
    --etag=etag \
    --state-metadata=priority=high,tracking_number=12345
    --format=FORMAT

Where

  • STATE_CHANGE is the change you want to make to a recommendation.
  • STATE_METADATA is optional metadata about the operation. Specify the metadata as a common-separated list of KEY=VALUE pairs. This option is available when you mark a recommendation as claimed, succeeded, or failed.

Valid values are:

  • mark-succeeded to mark the recommendation as succeeded.
  • mark-failed to mark the recommendation as failed.

For example:

gcloud beta recommender recommendations mark-succeeded \
    a523ff7e-ed03-4143-a3a5-5b396b99cba9 \
    --project=example-project \
    --location=us-central1-a \
    --recommender=g.u.00rz.compute.instance.MachineTypeRecommender \
    --etag='"5e3a63cccf1e0964"' \
    --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/v1beta1/projects/${PROJECT}/locations/${LOCATION}/recommenders/${RECOMMENDER}/recommendations/RECOMMENDATION_ID:markSucceeded \
<< EOM
{
  "etag": "etag"
  "stateMetadata": STATE_METADATA
}
EOM

where:

  • RECOMMENDATION_ID is the ID of a recommendation that you retrieved from a previous call to list recommendations
  • STATE_CHANGE is the change you want to make to a recommendation. Valid values are:
    • markSucceeded to mark the recommendation as succeeded.
    • markFailed to mark the recommendation as failed.
  • etag is the returned etag representing the recommendation state
  • STATE_METADATA is an optional field with additional metadata about the operation. Specify the metadata as key:value pairs. This field is available when you mark a recommendation as claimed, succeeded, or failed.

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

This operation returns the Recommendation entity 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/g.u.00rz.compute.instance.MachineTypeRecommender/recommendations/a523ff7e-ed03-4143-a3a5-5b396b99cba9",
  "primaryImpact": { ... },
  "stateInfo": {
    "state": "SUCCEEDED",
    "stateMetadata": {
      "priority" : "high",
      "tracking_number": "12345"
    }
  }
}

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

Was this page helpful? Let us know how we did:

Send feedback about...

Recommender Documentation