From 5202cfe3e5c2907a1a21a4c6d4bd0812029b6aa3 Mon Sep 17 00:00:00 2001 From: Google APIs Date: Wed, 1 Jul 2020 10:14:31 -0700 Subject: [PATCH] feat: adds methods for interacting with insights PiperOrigin-RevId: 319247865 --- google/cloud/recommender/v1/BUILD.bazel | 12 ++ google/cloud/recommender/v1/insight.proto | 135 ++++++++++++++++++ .../cloud/recommender/v1/recommendation.proto | 15 +- .../v1/recommender_grpc_service_config.json | 12 ++ .../recommender/v1/recommender_service.proto | 131 +++++++++++++++-- google/cloud/recommender/v1beta1/BUILD.bazel | 11 ++ 6 files changed, 301 insertions(+), 15 deletions(-) create mode 100644 google/cloud/recommender/v1/insight.proto diff --git a/google/cloud/recommender/v1/BUILD.bazel b/google/cloud/recommender/v1/BUILD.bazel index 23705d7f..5224237e 100644 --- a/google/cloud/recommender/v1/BUILD.bazel +++ b/google/cloud/recommender/v1/BUILD.bazel @@ -1,4 +1,13 @@ # This file was automatically generated by BuildFileGenerator +# https://github.com/googleapis/gapic-generator/tree/master/rules_gapic/bazel + +# Most of the manual changes to this file will be overwritten. +# It's **only** allowed to change the following rule attribute values: +# - names of *_gapic_assembly_* rules +# - certain parameters of *_gapic_library rules, including but not limited to: +# * extra_protoc_parameters +# * extra_protoc_file_parameters +# The complete list of preserved parameters can be found in the source code. # This is an API workspace, having public visibility by default makes perfect sense. package(default_visibility = ["//visibility:public"]) @@ -12,6 +21,7 @@ load("@com_google_googleapis_imports//:imports.bzl", "proto_library_with_info") proto_library( name = "recommender_proto", srcs = [ + "insight.proto", "recommendation.proto", "recommender_service.proto", ], @@ -303,6 +313,7 @@ ruby_gapic_library( name = "recommender_ruby_gapic", src = ":recommender_proto_with_info", gapic_yaml = "recommender_gapic.yaml", + grpc_service_config = "recommender_grpc_service_config.json", package = "google.cloud.recommender.v1", service_yaml = "recommender_v1.yaml", deps = [ @@ -347,6 +358,7 @@ csharp_gapic_library( name = "recommender_csharp_gapic", src = ":recommender_proto_with_info", gapic_yaml = "recommender_gapic.yaml", + grpc_service_config = "recommender_grpc_service_config.json", package = "google.cloud.recommender.v1", service_yaml = "recommender_v1.yaml", deps = [ diff --git a/google/cloud/recommender/v1/insight.proto b/google/cloud/recommender/v1/insight.proto new file mode 100644 index 00000000..783a7147 --- /dev/null +++ b/google/cloud/recommender/v1/insight.proto @@ -0,0 +1,135 @@ +// Copyright 2020 Google LLC +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +syntax = "proto3"; + +package google.cloud.recommender.v1; + +import "google/api/resource.proto"; +import "google/protobuf/duration.proto"; +import "google/protobuf/struct.proto"; +import "google/protobuf/timestamp.proto"; + +option csharp_namespace = "Google.Cloud.Recommender.V1"; +option go_package = "google.golang.org/genproto/googleapis/cloud/recommender/v1;recommender"; +option java_multiple_files = true; +option java_outer_classname = "InsightProto"; +option java_package = "com.google.cloud.recommender.v1"; +option objc_class_prefix = "CREC"; +option (google.api.resource_definition) = { + type: "recommender.googleapis.com/InsightType" + pattern: "projects/{project}/locations/{location}/insightTypes/{insight_type}" +}; + +// An insight along with the information used to derive the insight. The insight +// may have associated recomendations as well. +message Insight { + option (google.api.resource) = { + type: "recommender.googleapis.com/Insight" + pattern: "projects/{project}/locations/{location}/insightTypes/{insight_type}/insights/{insight}" + }; + + // Reference to an associated recommendation. + message RecommendationReference { + // Recommendation resource name, e.g. + // projects/[PROJECT_NUMBER]/locations/[LOCATION]/recommenders/[RECOMMENDER_ID]/recommendations/[RECOMMENDATION_ID] + string recommendation = 1; + } + + // Insight category. + enum Category { + // Unspecified category. + CATEGORY_UNSPECIFIED = 0; + + // The insight is related to cost. + COST = 1; + + // The insight is related to security. + SECURITY = 2; + + // The insight is related to performance. + PERFORMANCE = 3; + + // This insight is related to manageability. + MANAGEABILITY = 4; + } + + // Name of the insight. + string name = 1; + + // Free-form human readable summary in English. The maximum length is 500 + // characters. + string description = 2; + + // Fully qualified resource names that this insight is targeting. + repeated string target_resources = 9; + + // Insight subtype. Insight content schema will be stable for a given subtype. + string insight_subtype = 10; + + // A struct of custom fields to explain the insight. + // Example: "grantedPermissionsCount": "1000" + google.protobuf.Struct content = 3; + + // Timestamp of the latest data used to generate the insight. + google.protobuf.Timestamp last_refresh_time = 4; + + // Observation period that led to the insight. The source data used to + // generate the insight ends at last_refresh_time and begins at + // (last_refresh_time - observation_period). + google.protobuf.Duration observation_period = 5; + + // Information state and metadata. + InsightStateInfo state_info = 6; + + // Category being targeted by the insight. + Category category = 7; + + // Fingerprint of the Insight. Provides optimistic locking when updating + // states. + string etag = 11; + + // Recommendations derived from this insight. + repeated RecommendationReference associated_recommendations = 8; +} + +// Information related to insight state. +message InsightStateInfo { + // Represents insight state. + enum State { + // Unspecified state. + STATE_UNSPECIFIED = 0; + + // Insight is active. Content for ACTIVE insights can be updated by Google. + // ACTIVE insights can be marked DISMISSED OR ACCEPTED. + ACTIVE = 1; + + // Some action has been taken based on this insight. Insights become + // accepted when a recommendation derived from the insight has been marked + // CLAIMED, SUCCEEDED, or FAILED. ACTIVE insights can also be marked + // ACCEPTED explicitly. Content for ACCEPTED insights is immutable. ACCEPTED + // insights can only be marked ACCEPTED (which may update state metadata). + ACCEPTED = 2; + + // Insight is dismissed. Content for DISMISSED insights can be updated by + // Google. DISMISSED insights can be marked as ACTIVE. + DISMISSED = 3; + } + + // Insight state. + State state = 1; + + // A map of metadata for the state, provided by user or automations systems. + map state_metadata = 2; +} diff --git a/google/cloud/recommender/v1/recommendation.proto b/google/cloud/recommender/v1/recommendation.proto index 15e2bca1..aa8321ee 100644 --- a/google/cloud/recommender/v1/recommendation.proto +++ b/google/cloud/recommender/v1/recommendation.proto @@ -1,4 +1,4 @@ -// Copyright 2019 Google LLC. +// Copyright 2020 Google LLC // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. @@ -11,7 +11,6 @@ // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. // See the License for the specific language governing permissions and // limitations under the License. -// syntax = "proto3"; @@ -41,6 +40,13 @@ message Recommendation { pattern: "projects/{project}/locations/{location}/recommenders/{recommender}/recommendations/{recommendation}" }; + // Reference to an associated insight. + message InsightReference { + // Insight resource name, e.g. + // projects/[PROJECT_NUMBER]/locations/[LOCATION]/insightTypes/[INSIGHT_TYPE_ID]/insights/[INSIGHT_ID] + string insight = 1; + } + // Name of recommendation. string name = 1; @@ -81,6 +87,9 @@ message Recommendation { // Fingerprint of the Recommendation. Provides optimistic locking when // updating states. string etag = 11; + + // Insights that led to this recommendation. + repeated InsightReference associated_insights = 14; } // Contains what resources are changing and how they are changing. @@ -233,7 +242,7 @@ message Impact { // Information for state. Contains state and metadata. message RecommendationStateInfo { - // Represents Recommendation State + // Represents Recommendation State. enum State { // Default state. Don't use directly. STATE_UNSPECIFIED = 0; diff --git a/google/cloud/recommender/v1/recommender_grpc_service_config.json b/google/cloud/recommender/v1/recommender_grpc_service_config.json index b21bddfe..7d66cd7e 100644 --- a/google/cloud/recommender/v1/recommender_grpc_service_config.json +++ b/google/cloud/recommender/v1/recommender_grpc_service_config.json @@ -2,6 +2,14 @@ "methodConfig": [ { "name": [ + { + "service": "google.cloud.recommender.v1beta1.Recommender", + "method": "ListInsights" + }, + { + "service": "google.cloud.recommender.v1beta1.Recommender", + "method": "GetInsight" + }, { "service": "google.cloud.recommender.v1.Recommender", "method": "ListRecommendations" @@ -25,6 +33,10 @@ }, { "name": [ + { + "service": "google.cloud.recommender.v1beta1.Recommender", + "method": "MarkInsightAccepted" + }, { "service": "google.cloud.recommender.v1.Recommender", "method": "MarkRecommendationClaimed" diff --git a/google/cloud/recommender/v1/recommender_service.proto b/google/cloud/recommender/v1/recommender_service.proto index 97a04f5a..4f24a050 100644 --- a/google/cloud/recommender/v1/recommender_service.proto +++ b/google/cloud/recommender/v1/recommender_service.proto @@ -1,4 +1,4 @@ -// Copyright 2019 Google LLC. +// Copyright 2020 Google LLC // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. @@ -11,7 +11,6 @@ // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. // See the License for the specific language governing permissions and // limitations under the License. -// syntax = "proto3"; @@ -21,6 +20,7 @@ import "google/api/annotations.proto"; import "google/api/client.proto"; import "google/api/field_behavior.proto"; import "google/api/resource.proto"; +import "google/cloud/recommender/v1/insight.proto"; import "google/cloud/recommender/v1/recommendation.proto"; option csharp_namespace = "Google.Cloud.Recommender.V1"; @@ -30,14 +30,46 @@ option java_outer_classname = "RecommenderProto"; option java_package = "com.google.cloud.recommender.v1"; option objc_class_prefix = "CREC"; -// Provides recommendations for cloud customers for various categories like -// performance optimization, cost savings, reliability, feature discovery, etc. -// These recommendations are generated automatically based on analysis of user -// resources, configuration and monitoring metrics. +// Provides insights and recommendations for cloud customers for various +// categories like performance optimization, cost savings, reliability, feature +// discovery, etc. Insights and recommendations are generated automatically +// based on analysis of user resources, configuration and monitoring metrics. service Recommender { option (google.api.default_host) = "recommender.googleapis.com"; option (google.api.oauth_scopes) = "https://www.googleapis.com/auth/cloud-platform"; + // Lists insights for a Cloud project. Requires the recommender.*.list IAM + // permission for the specified insight type. + rpc ListInsights(ListInsightsRequest) returns (ListInsightsResponse) { + option (google.api.http) = { + get: "/v1/{parent=projects/*/locations/*/insightTypes/*}/insights" + }; + option (google.api.method_signature) = "parent"; + } + + // Gets the requested insight. Requires the recommender.*.get IAM permission + // for the specified insight type. + rpc GetInsight(GetInsightRequest) returns (Insight) { + option (google.api.http) = { + get: "/v1/{name=projects/*/locations/*/insightTypes/*/insights/*}" + }; + option (google.api.method_signature) = "name"; + } + + // Marks the Insight State as Accepted. Users can use this method to + // indicate to the Recommender API that they have applied some action based + // on the insight. This stops the insight content from being updated. + // + // MarkInsightAccepted can be applied to insights in ACTIVE state. Requires + // the recommender.*.update IAM permission for the specified insight. + rpc MarkInsightAccepted(MarkInsightAcceptedRequest) returns (Insight) { + option (google.api.http) = { + post: "/v1/{name=projects/*/locations/*/insightTypes/*/insights/*}:markAccepted" + body: "*" + }; + option (google.api.method_signature) = "name,state_metadata,etag"; + } + // Lists recommendations for a Cloud project. Requires the recommender.*.list // IAM permission for the specified recommender. rpc ListRecommendations(ListRecommendationsRequest) returns (ListRecommendationsResponse) { @@ -57,10 +89,10 @@ service Recommender { option (google.api.method_signature) = "name"; } - // Mark the Recommendation State as Claimed. Users can use this method to + // Marks the Recommendation State as Claimed. Users can use this method to // indicate to the Recommender API that they are starting to apply the // recommendation themselves. This stops the recommendation content from being - // updated. + // updated. Associated insights are frozen and placed in the ACCEPTED state. // // MarkRecommendationClaimed can be applied to recommendations in CLAIMED, // SUCCEEDED, FAILED, or ACTIVE state. @@ -75,10 +107,11 @@ service Recommender { option (google.api.method_signature) = "name,state_metadata,etag"; } - // Mark the Recommendation State as Succeeded. Users can use this method to + // Marks the Recommendation State as Succeeded. Users can use this method to // indicate to the Recommender API that they have applied the recommendation // themselves, and the operation was successful. This stops the recommendation - // content from being updated. + // content from being updated. Associated insights are frozen and placed in + // the ACCEPTED state. // // MarkRecommendationSucceeded can be applied to recommendations in ACTIVE, // CLAIMED, SUCCEEDED, or FAILED state. @@ -93,10 +126,11 @@ service Recommender { option (google.api.method_signature) = "name,state_metadata,etag"; } - // Mark the Recommendation State as Failed. Users can use this method to + // Marks the Recommendation State as Failed. Users can use this method to // indicate to the Recommender API that they have applied the recommendation // themselves, and the operation failed. This stops the recommendation content - // from being updated. + // from being updated. Associated insights are frozen and placed in the + // ACCEPTED state. // // MarkRecommendationFailed can be applied to recommendations in ACTIVE, // CLAIMED, SUCCEEDED, or FAILED state. @@ -112,6 +146,79 @@ service Recommender { } } +// Request for the `ListInsights` method. +message ListInsightsRequest { + // Required. The container resource on which to execute the request. + // Acceptable formats: + // + // 1. + // "projects/[PROJECT_NUMBER]/locations/[LOCATION]/insightTypes/[INSIGHT_TYPE_ID]", + // + // LOCATION here refers to GCP Locations: + // https://cloud.google.com/about/locations/ + string parent = 1 [ + (google.api.field_behavior) = REQUIRED, + (google.api.resource_reference) = { + type: "recommender.googleapis.com/InsightType" + } + ]; + + // Optional. The maximum number of results to return from this request. Non-positive + // values are ignored. If not specified, the server will determine the number + // of results to return. + int32 page_size = 2 [(google.api.field_behavior) = OPTIONAL]; + + // Optional. If present, retrieves the next batch of results from the preceding call to + // this method. `page_token` must be the value of `next_page_token` from the + // previous response. The values of other method parameters must be identical + // to those in the previous call. + string page_token = 3 [(google.api.field_behavior) = OPTIONAL]; + + // Optional. Filter expression to restrict the insights returned. Supported + // filter fields: state + // Eg: `state:"DISMISSED" or state:"ACTIVE" + string filter = 4 [(google.api.field_behavior) = OPTIONAL]; +} + +// Response to the `ListInsights` method. +message ListInsightsResponse { + // The set of insights for the `parent` resource. + repeated Insight insights = 1; + + // A token that can be used to request the next page of results. This field is + // empty if there are no additional results. + string next_page_token = 2; +} + +// Request to the `GetInsight` method. +message GetInsightRequest { + // Required. Name of the insight. + string name = 1 [ + (google.api.field_behavior) = REQUIRED, + (google.api.resource_reference) = { + type: "recommender.googleapis.com/Insight" + } + ]; +} + +// Request for the `MarkInsightAccepted` method. +message MarkInsightAcceptedRequest { + // Required. Name of the insight. + string name = 1 [ + (google.api.field_behavior) = REQUIRED, + (google.api.resource_reference) = { + type: "recommender.googleapis.com/Insight" + } + ]; + + // Optional. State properties user wish to include with this state. Full replace of the + // current state_metadata. + map state_metadata = 2 [(google.api.field_behavior) = OPTIONAL]; + + // Required. Fingerprint of the Insight. Provides optimistic locking. + string etag = 3 [(google.api.field_behavior) = REQUIRED]; +} + // Request for the `ListRecommendations` method. message ListRecommendationsRequest { // Required. The container resource on which to execute the request. diff --git a/google/cloud/recommender/v1beta1/BUILD.bazel b/google/cloud/recommender/v1beta1/BUILD.bazel index c0a96b13..be97b86f 100644 --- a/google/cloud/recommender/v1beta1/BUILD.bazel +++ b/google/cloud/recommender/v1beta1/BUILD.bazel @@ -1,4 +1,13 @@ # This file was automatically generated by BuildFileGenerator +# https://github.com/googleapis/gapic-generator/tree/master/rules_gapic/bazel + +# Most of the manual changes to this file will be overwritten. +# It's **only** allowed to change the following rule attribute values: +# - names of *_gapic_assembly_* rules +# - certain parameters of *_gapic_library rules, including but not limited to: +# * extra_protoc_parameters +# * extra_protoc_file_parameters +# The complete list of preserved parameters can be found in the source code. # This is an API workspace, having public visibility by default makes perfect sense. package(default_visibility = ["//visibility:public"]) @@ -303,6 +312,7 @@ ruby_gapic_library( name = "recommender_ruby_gapic", src = ":recommender_proto_with_info", gapic_yaml = "recommender_gapic.yaml", + grpc_service_config = "recommender_grpc_service_config.json", package = "google.cloud.recommender.v1beta1", service_yaml = "recommender_v1beta1.yaml", deps = [ @@ -347,6 +357,7 @@ csharp_gapic_library( name = "recommender_csharp_gapic", src = ":recommender_proto_with_info", gapic_yaml = "recommender_gapic.yaml", + grpc_service_config = "recommender_grpc_service_config.json", package = "google.cloud.recommender.v1beta1", service_yaml = "recommender_v1beta1.yaml", deps = [