REST Resource: billingAccounts.locations.recommenders.recommendations

Resource: Recommendation

A recommendation along with a suggested action. E.g., a rightsizing recommendation for an underutilized VM, IAM role recommendations, etc

JSON representation 
{
  "name": string,
  "description": string,
  "recommenderSubtype": string,
  "lastRefreshTime": string,
  "primaryImpact": {
    object (Impact)
  },
  "additionalImpact": [
    {
      object (Impact)
    }
  ],
  "priority": enum (Priority),
  "content": {
    object (RecommendationContent)
  },
  "stateInfo": {
    object (RecommendationStateInfo)
  },
  "etag": string,
  "associatedInsights": [
    {
      object (InsightReference)
    }
  ],
  "xorGroupId": string,
  "targetResources": [
    string
  ]
}
Fields
name

string

Name of recommendation.
description

string

Free-form human readable summary in English. The maximum length is 500 characters.
recommenderSubtype

string

Contains an identifier for a subtype of recommendations produced for the same recommender. Subtype is a function of content and impact, meaning a new subtype might be added when significant changes to content or primaryImpact.category are introduced. See the Recommenders section to see a list of subtypes for a given Recommender.

Examples: For recommender = "google.iam.policy.Recommender", recommenderSubtype can be one of "REMOVE_ROLE"/"REPLACE_ROLE"
lastRefreshTime

string (Timestamp format)

Last time this recommendation was refreshed by the system that created it in the first place.

A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z" and "2014-10-02T15:01:23.045123456Z".
primaryImpact

object (Impact)

The primary impact that this recommendation can have while trying to optimize for one category.
additionalImpact[]

object (Impact)

Optional set of additional impact that this recommendation may have when trying to optimize for the primary category. These may be positive or negative.
priority

enum (Priority)

Recommendation's priority.
content

object (RecommendationContent)

Content of the recommendation describing recommended changes to resources.
stateInfo

object (RecommendationStateInfo)

Information for state. Contains state and metadata.
etag

string

Fingerprint of the Recommendation. Provides optimistic locking when updating states.
associatedInsights[]

object (InsightReference)

Insights that led to this recommendation.
xorGroupId

string

Corresponds to a mutually exclusive group ID within a recommender. A non-empty ID indicates that the recommendation belongs to a mutually exclusive group. This means that only one recommendation within the group is suggested to be applied.
targetResources[]

string

Fully qualified resource names that this recommendation is targeting.

Impact

Contains the impact a recommendation can have for a given category.

JSON representation 
{
  "category": enum (Category),

  // Union field projection can be only one of the following:
  "costProjection": {
    object (CostProjection)
  },
  "securityProjection": {
    object (SecurityProjection)
  },
  "sustainabilityProjection": {
    object (SustainabilityProjection)
  },
  "reliabilityProjection": {
    object (ReliabilityProjection)
  }
  // End of list of possible types for union field projection.
}
Fields
category

enum (Category)

Category that is being targeted.
Union field projection. Contains projections (if any) for this category. projection can be only one of the following:
costProjection

object (CostProjection)

Use with CategoryType.COST
securityProjection

object (SecurityProjection)

Use with CategoryType.SECURITY
sustainabilityProjection

object (SustainabilityProjection)

Use with CategoryType.SUSTAINABILITY
reliabilityProjection

object (ReliabilityProjection)

Use with CategoryType.RELIABILITY

Category

The category of the impact.

Enums
CATEGORY_UNSPECIFIED Default unspecified category. Don't use directly.
COST Indicates a potential increase or decrease in cost.
SECURITY Indicates a potential increase or decrease in security.
PERFORMANCE Indicates a potential increase or decrease in performance.
MANAGEABILITY Indicates a potential increase or decrease in manageability.
SUSTAINABILITY Indicates a potential increase or decrease in sustainability.
RELIABILITY Indicates a potential increase or decrease in reliability.

CostProjection

Contains metadata about how much money a recommendation can save or incur.

JSON representation 
{
  "cost": {
    object (Money)
  },
  "duration": string,
  "costInLocalCurrency": {
    object (Money)
  },
  "pricingType": enum (PricingType)
}
Fields
cost

object (Money)

An approximate projection on amount saved or amount incurred. Negative cost units indicate cost savings and positive cost units indicate increase. See google.type.Money documentation for positive/negative units.

A user's permissions may affect whether the cost is computed using list prices or custom contract prices.
duration

string (Duration format)

Duration for which this cost applies.

A duration in seconds with up to nine fractional digits, ending with 's'. Example: "3.5s".
costInLocalCurrency

object (Money)

The approximate cost savings in the billing account's local currency.
pricingType

enum (PricingType)

How the cost is calculated.

PricingType

The type of savings a cost projection is based on.

Enums
PRICING_TYPE_UNSPECIFIED Default pricing type.
LIST_PRICE The price listed by GCP for all customers.
CUSTOM_PRICE A price derived from past usage and billing.

SecurityProjection

Contains various ways of describing the impact on Security.

JSON representation 
{
  "details": {
    object
  }
}
Fields
details

object (Struct format)

This field can be used by the recommender to define details specific to security impact.

SustainabilityProjection

Contains metadata about how much sustainability a recommendation can save or incur.

JSON representation 
{
  "kgCO2e": number,
  "duration": string
}
Fields
kgCO2e

number

Carbon Footprint generated in kg of CO2 equivalent. Chose kgCO2e so that the name renders correctly in camelCase (kgCO2e).
duration

string (Duration format)

Duration for which this sustanability applies.

A duration in seconds with up to nine fractional digits, ending with 's'. Example: "3.5s".

ReliabilityProjection

Contains information on the impact of a reliability recommendation.

JSON representation 
{
  "risks": [
    enum (RiskType)
  ],
  "details": {
    object
  }
}
Fields
risks[]

enum (RiskType)

Reliability risks mitigated by this recommendation.
details

object (Struct format)

Per-recommender projection.

RiskType

The risk associated with the reliability issue.

Enums
RISK_TYPE_UNSPECIFIED Default unspecified risk. Don't use directly.
SERVICE_DISRUPTION Potential service downtime.
DATA_LOSS Potential data loss.
ACCESS_DENY Potential access denial. The service is still up but some or all clients can't access it.

Priority

Recommendation priority levels.

Enums
PRIORITY_UNSPECIFIED Recommendation has unspecified priority.
P4 Recommendation has P4 priority (lowest priority).
P3 Recommendation has P3 priority (second lowest priority).
P2 Recommendation has P2 priority (second highest priority).
P1 Recommendation has P1 priority (highest priority).

RecommendationContent

Contains what resources are changing and how they are changing.

JSON representation 
{
  "operationGroups": [
    {
      object (OperationGroup)
    }
  ],
  "overview": {
    object
  }
}
Fields
operationGroups[]

object (OperationGroup)

Operations to one or more Google Cloud resources grouped in such a way that, all operations within one group are expected to be performed atomically and in an order.
overview

object (Struct format)

Condensed overview information about the recommendation.

OperationGroup

Group of operations that need to be performed atomically.

JSON representation 
{
  "operations": [
    {
      object (Operation)
    }
  ]
}
Fields
operations[]

object (Operation)

List of operations across one or more resources that belong to this group. Loosely based on RFC6902 and should be performed in the order they appear.

Operation

Contains an operation for a resource loosely based on the JSON-PATCH format with support for:

  • Custom filters for describing partial array patch.
  • Extended path values for describing nested arrays.
  • Custom fields for describing the resource for which the operation is being described.
  • Allows extension to custom operations not natively supported by RFC6902. See https://tools.ietf.org/html/rfc6902 for details on the original RFC.
JSON representation 
{
  "action": string,
  "resourceType": string,
  "resource": string,
  "path": string,
  "sourceResource": string,
  "sourcePath": string,
  "pathFilters": {
    string: value,
    ...
  },
  "pathValueMatchers": {
    string: {
      object (ValueMatcher)
    },
    ...
  },

  // Union field path_value can be only one of the following:
  "value": value,
  "valueMatcher": {
    object (ValueMatcher)
  }
  // End of list of possible types for union field path_value.
}
Fields
action

string

Type of this operation. Contains one of 'add', 'remove', 'replace', 'move', 'copy', 'test' and 'custom' operations. This field is case-insensitive and always populated.
resourceType

string

Type of GCP resource being modified/tested. This field is always populated. Example: cloudresourcemanager.googleapis.com/Project, compute.googleapis.com/Instance
resource

string

Contains the fully qualified resource name. This field is always populated. ex: //cloudresourcemanager.googleapis.com/projects/foo.
path

string

Path to the target field being operated on. If the operation is at the resource level, then path should be "/". This field is always populated.
sourceResource

string

Can be set with action 'copy' to copy resource configuration across different resources of the same type. Example: A resource clone can be done via action = 'copy', path = "/", from = "/", sourceResource = and resource_name = . This field is empty for all other values of action.
sourcePath

string

Can be set with action 'copy' or 'move' to indicate the source field within resource or sourceResource, ignored if provided for other operation types.
pathFilters

map (key: string, value: value (Value format))

Set of filters to apply if path refers to array elements or nested array elements in order to narrow down to a single unique element that is being tested/modified. This is intended to be an exact match per filter. To perform advanced matching, use pathValueMatchers.

  • Example:
{
  "/versions/*/name" : "it-123"
  "/versions/*/targetSize/percent": 20
}
  • Example:
{
  "/bindings/*/role": "roles/owner"
  "/bindings/*/condition" : null
}
  • Example:
{
  "/bindings/*/role": "roles/owner"
  "/bindings/*/members/*" : ["x@example.com", "y@example.com"]
}

When both pathFilters and pathValueMatchers are set, an implicit AND must be performed.

An object containing a list of "key": value pairs. Example: { "name": "wrench", "mass": "1.3kg", "count": "3" }.
pathValueMatchers

map (key: string, value: object (ValueMatcher))

Similar to pathFilters, this contains set of filters to apply if path field refers to array elements. This is meant to support value matching beyond exact match. To perform exact match, use pathFilters. When both pathFilters and pathValueMatchers are set, an implicit AND must be performed.

An object containing a list of "key": value pairs. Example: { "name": "wrench", "mass": "1.3kg", "count": "3" }.
Union field path_value. One of the fields in the following block will be set and intend to describe a value for 'path' field. path_value can be only one of the following:
value

value (Value format)

Value for the path field. Will be set for actions:'add'/'replace'. Maybe set for action: 'test'. Either this or valueMatcher will be set for 'test' operation. An exact match must be performed.
valueMatcher

object (ValueMatcher)

Can be set for action 'test' for advanced matching for the value of 'path' field. Either this or value will be set for 'test' operation.

RecommendationStateInfo

Information for state. Contains state and metadata.

JSON representation 
{
  "state": enum (State),
  "stateMetadata": {
    string: string,
    ...
  }
}
Fields
state

enum (State)

The state of the recommendation, Eg ACTIVE, SUCCEEDED, FAILED.
stateMetadata

map (key: string, value: string)

A map of metadata for the state, provided by user or automations systems.

An object containing a list of "key": value pairs. Example: { "name": "wrench", "mass": "1.3kg", "count": "3" }.

State

Represents Recommendation State.

Enums
STATE_UNSPECIFIED Default state. Don't use directly.
ACTIVE

Recommendation is active and can be applied. Recommendations content can be updated by Google.

ACTIVE recommendations can be marked as CLAIMED, SUCCEEDED, or FAILED.
CLAIMED

Recommendation is in claimed state. Recommendations content is immutable and cannot be updated by Google.

CLAIMED recommendations can be marked as CLAIMED, SUCCEEDED, or FAILED.
SUCCEEDED

Recommendation is in succeeded state. Recommendations content is immutable and cannot be updated by Google.

SUCCEEDED recommendations can be marked as SUCCEEDED, or FAILED.
FAILED

Recommendation is in failed state. Recommendations content is immutable and cannot be updated by Google.

FAILED recommendations can be marked as SUCCEEDED, or FAILED.
DISMISSED

Recommendation is in dismissed state. Recommendation content can be updated by Google.

DISMISSED recommendations can be marked as ACTIVE.

InsightReference

Reference to an associated insight.

JSON representation 
{
  "insight": string
}
Fields
insight

string

Insight resource name, e.g. projects/[PROJECT_NUMBER]/locations/[LOCATION]/insightTypes/[INSIGHT_TYPE_ID]/insights/[INSIGHT_ID]

Methods

get

 Gets the requested recommendation.

list

 Lists recommendations for the specified Cloud Resource.

markClaimed

 Marks the Recommendation State as Claimed.

markDismissed

 Mark the Recommendation State as Dismissed.

markFailed

 Marks the Recommendation State as Failed.

markSucceeded

 Marks the Recommendation State as Succeeded.