build: use bazel build (#90)

Author: alexander-fenster

packages/google-cloud-recommender/protos/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<string, string> state_metadata = 2;
+}

packages/google-cloud-recommender/protos/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;

packages/google-cloud-recommender/protos/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<string, string> 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.