From b4c73face84fefb967ef6c72f0eae64faf67895f Mon Sep 17 00:00:00 2001 From: Google APIs Date: Wed, 3 Jul 2019 15:55:29 -0700 Subject: [PATCH] Synchronize new proto/yaml changes. PiperOrigin-RevId: 256453142 --- .../artman_recommender_v1beta1.yaml | 34 +++ .../recommender/recommender_v1beta1.yaml | 19 ++ .../recommender/v1beta1/recommendation.proto | 234 ++++++++++++++++++ .../v1beta1/recommender_gapic.yaml | 174 +++++++++++++ .../v1beta1/recommender_service.proto | 190 ++++++++++++++ 5 files changed, 651 insertions(+) create mode 100644 google/cloud/recommender/artman_recommender_v1beta1.yaml create mode 100644 google/cloud/recommender/recommender_v1beta1.yaml create mode 100644 google/cloud/recommender/v1beta1/recommendation.proto create mode 100644 google/cloud/recommender/v1beta1/recommender_gapic.yaml create mode 100644 google/cloud/recommender/v1beta1/recommender_service.proto diff --git a/google/cloud/recommender/artman_recommender_v1beta1.yaml b/google/cloud/recommender/artman_recommender_v1beta1.yaml new file mode 100644 index 00000000..e66456bf --- /dev/null +++ b/google/cloud/recommender/artman_recommender_v1beta1.yaml @@ -0,0 +1,34 @@ +common: + api_name: recommender + api_version: v1beta1 + organization_name: google-cloud + proto_deps: + - name: google-common-protos + src_proto_paths: + - v1beta1 + service_yaml: recommender_v1beta1.yaml + gapic_yaml: v1beta1/recommender_gapic.yaml +artifacts: +- name: gapic_config + type: GAPIC_CONFIG +- name: java_gapic + type: GAPIC + language: JAVA +- name: python_gapic + type: GAPIC + language: PYTHON +- name: nodejs_gapic + type: GAPIC + language: NODEJS +- name: php_gapic + type: GAPIC + language: PHP +- name: go_gapic + type: GAPIC + language: GO +- name: ruby_gapic + type: GAPIC + language: RUBY +- name: csharp_gapic + type: GAPIC + language: CSHARP diff --git a/google/cloud/recommender/recommender_v1beta1.yaml b/google/cloud/recommender/recommender_v1beta1.yaml new file mode 100644 index 00000000..d72478e8 --- /dev/null +++ b/google/cloud/recommender/recommender_v1beta1.yaml @@ -0,0 +1,19 @@ +type: google.api.Service +config_version: 3 +name: recommender.googleapis.com +title: Recommender API + +apis: +- name: google.cloud.recommender.v1beta1.Recommender + +backend: + rules: + - selector: 'google.cloud.recommender.v1beta1.Recommender.*' + deadline: 30.0 + +authentication: + rules: + - selector: 'google.cloud.recommender.v1beta1.Recommender.*' + oauth: + canonical_scopes: |- + https://www.googleapis.com/auth/cloud-platform diff --git a/google/cloud/recommender/v1beta1/recommendation.proto b/google/cloud/recommender/v1beta1/recommendation.proto new file mode 100644 index 00000000..8980de0c --- /dev/null +++ b/google/cloud/recommender/v1beta1/recommendation.proto @@ -0,0 +1,234 @@ +// Copyright 2019 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.v1beta1; + +import "google/protobuf/duration.proto"; +import "google/protobuf/struct.proto"; +import "google/protobuf/timestamp.proto"; +import "google/type/money.proto"; + +option csharp_namespace = "Google.Cloud.Recommender.V1Beta1"; +option go_package = "google.golang.org/genproto/googleapis/cloud/recommender/v1beta1;recommender"; +option java_multiple_files = true; +option java_package = "com.google.cloud.recommender.v1beta1"; +option objc_class_prefix = "CREC"; + +// A recommendation along with a suggested action. E.g., a rightsizing +// recommendation for an underutilized VM, IAM role recommendations, etc +message Recommendation { + // Name of recommendation. + // + // A project recommendation is represented as + // projects/[PROJECT_NUMBER]/locations/[LOCATION]/recommenders/[RECOMMENDER_ID]/recommendations/[RECOMMENDATION_ID] + string name = 1; + + // Free-form human readable summary in English. The maximum length is 500 + // characters. + string description = 2; + + // 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 will be added when either content or primary impact category + // changes. + // + // Examples: + // For recommender = "google.iam.policy.RoleRecommender", + // recommender_subtype can be one of "REMOVE_ROLE"/"REPLACE_ROLE" + string recommender_subtype = 12; + + // Last time this recommendation was refreshed by the system that created it + // in the first place. + google.protobuf.Timestamp last_refresh_time = 4; + + // The primary impact that this recommendation can have while trying to + // optimize for one category. + Impact primary_impact = 5; + + // Optional set of additional impact that this recommendation may have when + // trying to optimize for the primary category. These may be positive + // or negative. + repeated Impact additional_impact = 6; + + // Content of the recommendation describing recommended changes to resources. + RecommendationContent content = 7; + + // Information for state. Contains state and metadata. + RecommendationStateInfo state_info = 10; + + // Fingerprint of the Recommendation. Provides optimistic locking when + // updating states. + string etag = 11; +} + +// Contains what resources are changing and how they are changing. +message RecommendationContent { + // 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. + repeated OperationGroup operation_groups = 2; +} + +// Group of operations that need to be performed atomically. +message OperationGroup { + // 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. + repeated Operation operations = 1; +} + +// Contains an operation for a resource inspired by 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. +message Operation { + // Type of this operation. Contains one of 'and', 'remove', 'replace', 'move', + // 'copy', 'test' and custom operations. This field is case-insensitive and + // always populated. + string action = 1; + + // Type of GCP resource being modified/tested. This field is always populated. + // Example: cloudresourcemanager.googleapis.com/Project, + // compute.googleapis.com/Instance + string resource_type = 2; + + // Contains the fully qualified resource name. This field is always populated. + // ex: //cloudresourcemanager.googleapis.com/projects/foo. + string resource = 3; + + // 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. + string path = 4; + + // 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 = "/", + // source_resource = and resource_name = . + // This field is empty for all other values of `action`. + string source_resource = 5; + + // Can be set with action 'copy' or 'move' to indicate the source field within + // resource or source_resource, ignored if provided for other operation types. + string source_path = 6; + + // Value for the `path` field. Set if action is 'add'/'replace'/'test'. + google.protobuf.Value value = 7; + + // 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. + // Note that this is intended to be an exact match per filter. + // Example: { + // "/versions/*/name" : "it-123" + // "/versions/*/targetSize/percent": 20 + // } + // Example: { + // "/bindings/*/role": "roles/admin" + // "/bindings/*/condition" : null + // } + // Example: { + // "/bindings/*/role": "roles/admin" + // "/bindings/*/members/*" : ["x@google.com", "y@google.com"] + // } + map path_filters = 8; +} + +// Contains metadata about how much money a recommendation can save or incur. +message CostProjection { + // 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. + google.type.Money cost = 1; + + // Duration for which this cost applies. + google.protobuf.Duration duration = 2; +} + +// Contains the impact a recommendation can have for a given category. +message Impact { + // The category of the impact. + enum Category { + // Default unspecified category. Don't use directly. + CATEGORY_UNSPECIFIED = 0; + + // Indicates a potential increase or decrease in cost. + COST = 1; + + // Indicates a potential increase or decrease in security. + SECURITY = 2; + + // Indicates a potential increase or decrease in performance. + PERFORMANCE = 3; + } + + // Category that is being targeted. + Category category = 1; + + // Contains projections (if any) for this category. + oneof projection { + // Use with CategoryType.COST + CostProjection cost_projection = 100; + } +} + +// Information for state. Contains state and metadata. +message RecommendationStateInfo { + // Represents Recommendation State + enum State { + // Default state. Don't use directly. + STATE_UNSPECIFIED = 0; + + // Recommendation is active and can be applied. Recommendations content can + // be updated by Google. + // + // ACTIVE recommendations can be marked as CLAIMED, SUCCEEDED, or FAILED. + ACTIVE = 1; + + // 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. + CLAIMED = 6; + + // Recommendation is in succeeded state. Recommendations content is + // immutable and cannot be updated by Google. + // + // SUCCEEDED recommendations can be marked as SUCCEEDED, or FAILED. + SUCCEEDED = 3; + + // Recommendation is in failed state. Recommendations content is immutable + // and cannot be updated by Google. + // + // FAILED recommendations can be marked as SUCCEEDED, or FAILED. + FAILED = 4; + + // Recommendation is in dismissed state. Recommendation content can be + // updated by Google. + // + // DISMISSED recommendations can be marked as ACTIVE. + DISMISSED = 5; + } + + // The state of the recommendation, Eg ACTIVE, SUCCEEDED, FAILED. + 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/v1beta1/recommender_gapic.yaml b/google/cloud/recommender/v1beta1/recommender_gapic.yaml new file mode 100644 index 00000000..2acecf31 --- /dev/null +++ b/google/cloud/recommender/v1beta1/recommender_gapic.yaml @@ -0,0 +1,174 @@ +type: com.google.api.codegen.ConfigProto +config_schema_version: 1.0.0 +# The settings of generated code in a specific language. +language_settings: + java: + package_name: com.google.cloud.recommender.v1beta1 + python: + package_name: google.cloud.recommender_v1beta1.gapic + go: + package_name: cloud.google.com/go/recommender/apiv1beta1 + csharp: + package_name: Google.Cloud.Recommender.V1beta1 + ruby: + package_name: Google::Cloud::Recommender::V1beta1 + php: + package_name: Google\Cloud\Recommender\V1beta1 + nodejs: + package_name: recommender.v1beta1 +# A list of API interface configurations. +interfaces: +# The fully qualified name of the API interface. +- name: google.cloud.recommender.v1beta1.Recommender + # A list of resource collection configurations. + # Consists of a name_pattern and an entity_name. + # The name_pattern is a pattern to describe the names of the resources of this + # collection, using the platform's conventions for URI patterns. A generator + # may use this to generate methods to compose and decompose such names. The + # pattern should use named placeholders as in `shelves/{shelf}/books/{book}`; + # those will be taken as hints for the parameter names of the generated + # methods. If empty, no name methods are generated. + # The entity_name is the name to be used as a basis for generated methods and + # classes. + collections: + - name_pattern: projects/{project}/locations/{location}/recommenders/{recommender} + entity_name: recommender + - name_pattern: projects/{project}/locations/{location}/recommenders/{recommender}/recommendations/{recommendation} + entity_name: recommendation + # Definition for retryable codes. + retry_codes_def: + - name: idempotent + retry_codes: + - DEADLINE_EXCEEDED + - UNAVAILABLE + - name: non_idempotent + retry_codes: [] + # Definition for retry/backoff parameters. + retry_params_def: + - name: default + initial_retry_delay_millis: 100 + retry_delay_multiplier: 1.3 + max_retry_delay_millis: 60000 + initial_rpc_timeout_millis: 20000 + rpc_timeout_multiplier: 1 + max_rpc_timeout_millis: 20000 + total_timeout_millis: 600000 + # A list of method configurations. + # Common properties: + # + # name - The simple name of the method. + # + # flattening - Specifies the configuration for parameter flattening. + # Describes the parameter groups for which a generator should produce method + # overloads which allow a client to directly pass request message fields as + # method parameters. This information may or may not be used, depending on + # the target language. + # Consists of groups, which each represent a list of parameters to be + # flattened. Each parameter listed must be a field of the request message. + # + # required_fields - Fields that are always required for a request to be + # valid. + # + # page_streaming - Specifies the configuration for paging. + # Describes information for generating a method which transforms a paging + # list RPC into a stream of resources. + # Consists of a request and a response. + # The request specifies request information of the list method. It defines + # which fields match the paging pattern in the request. The request consists + # of a page_size_field and a token_field. The page_size_field is the name of + # the optional field specifying the maximum number of elements to be + # returned in the response. The token_field is the name of the field in the + # request containing the page token. + # The response specifies response information of the list method. It defines + # which fields match the paging pattern in the response. The response + # consists of a token_field and a resources_field. The token_field is the + # name of the field in the response containing the next page token. The + # resources_field is the name of the field in the response containing the + # list of resources belonging to the page. + # + # retry_codes_name - Specifies the configuration for retryable codes. The + # name must be defined in interfaces.retry_codes_def. + # + # retry_params_name - Specifies the configuration for retry/backoff + # parameters. The name must be defined in interfaces.retry_params_def. + # + # field_name_patterns - Maps the field name of the request type to + # entity_name of interfaces.collections. + # Specifies the string pattern that the field must follow. + # + # timeout_millis - Specifies the default timeout for a non-retrying call. If + # the call is retrying, refer to retry_params_name instead. + methods: + - name: ListRecommendations + flattening: + groups: + - parameters: + - parent + required_fields: + - parent + page_streaming: + request: + page_size_field: page_size + token_field: page_token + response: + token_field: next_page_token + resources_field: recommendations + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + parent: recommender + timeout_millis: 60000 + - name: GetRecommendation + flattening: + groups: + - parameters: + - name + required_fields: + - name + retry_codes_name: idempotent + retry_params_name: default + field_name_patterns: + name: recommendation + timeout_millis: 60000 + - name: MarkRecommendationClaimed + flattening: + groups: + - parameters: + - name + - etag + required_fields: + - name + - etag + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + name: recommendation + timeout_millis: 60000 + - name: MarkRecommendationSucceeded + flattening: + groups: + - parameters: + - name + - etag + required_fields: + - name + - etag + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + name: recommendation + timeout_millis: 60000 + - name: MarkRecommendationFailed + flattening: + groups: + - parameters: + - name + - etag + required_fields: + - name + - etag + retry_codes_name: non_idempotent + retry_params_name: default + field_name_patterns: + name: recommendation + timeout_millis: 60000 diff --git a/google/cloud/recommender/v1beta1/recommender_service.proto b/google/cloud/recommender/v1beta1/recommender_service.proto new file mode 100644 index 00000000..49a076ae --- /dev/null +++ b/google/cloud/recommender/v1beta1/recommender_service.proto @@ -0,0 +1,190 @@ +// Copyright 2019 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.v1beta1; + +import "google/api/annotations.proto"; +import "google/cloud/recommender/v1beta1/recommendation.proto"; +import "google/longrunning/operations.proto"; +import "google/api/client.proto"; + +option csharp_namespace = "Google.Cloud.Recommmender.V1Beta1"; +option go_package = "google.golang.org/genproto/googleapis/cloud/recommender/v1beta1;recommender"; +option java_multiple_files = true; +option java_outer_classname = "RecommenderProto"; +option java_package = "com.google.cloud.recommender.v1beta1"; +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. +service Recommender { + option (google.api.default_host) = "recommender.googleapis.com"; + option (google.api.oauth_scopes) = "https://www.googleapis.com/auth/cloud-platform"; + + // Lists recommendations for a Cloud project. Requires the recommender.*.list + // IAM permission for the specified recommender. + rpc ListRecommendations(ListRecommendationsRequest) returns (ListRecommendationsResponse) { + option (google.api.http) = { + get: "/v1beta1/{parent=projects/*/locations/*/recommenders/*}/recommendations" + }; + } + + // Gets the requested recommendation. Requires the recommender.*.get + // IAM permission for the specified recommender. + rpc GetRecommendation(GetRecommendationRequest) returns (Recommendation) { + option (google.api.http) = { + get: "/v1beta1/{name=projects/*/locations/*/recommenders/*/recommendations/*}" + }; + } + + // Mark 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. + // + // MarkRecommendationClaimed can be applied to recommendations in CLAIMED, + // SUCCEEDED, FAILED, or ACTIVE state. + // + // Requires the recommender.*.update IAM permission for the specified + // recommender. + rpc MarkRecommendationClaimed(MarkRecommendationClaimedRequest) returns (Recommendation) { + option (google.api.http) = { + post: "/v1beta1/{name=projects/*/locations/*/recommenders/*/recommendations/*}:markClaimed" + body: "*" + }; + } + + // Mark 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. + // + // MarkRecommendationSucceeded can be applied to recommendations in ACTIVE, + // CLAIMED, SUCCEEDED, or FAILED state. + // + // Requires the recommender.*.update IAM permission for the specified + // recommender. + rpc MarkRecommendationSucceeded(MarkRecommendationSucceededRequest) returns (Recommendation) { + option (google.api.http) = { + post: "/v1beta1/{name=projects/*/locations/*/recommenders/*/recommendations/*}:markSucceeded" + body: "*" + }; + } + + // Mark 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. + // + // MarkRecommendationFailed can be applied to recommendations in ACTIVE, + // CLAIMED, SUCCEEDED, or FAILED state. + // + // Requires the recommender.*.update IAM permission for the specified + // recommender. + rpc MarkRecommendationFailed(MarkRecommendationFailedRequest) returns (Recommendation) { + option (google.api.http) = { + post: "/v1beta1/{name=projects/*/locations/*/recommenders/*/recommendations/*}:markFailed" + body: "*" + }; + } +} + +// Request for the `ListRecommendations` method. +message ListRecommendationsRequest { + // Required. The container resource on which to execute the request. + // Acceptable formats: + // + // 1. + // "projects/[PROJECT_NUMBER]/locations/[LOCATION]/recommenders/[RECOMMENDER_ID]", + // + // LOCATION here refers to GCP Locations: + // https://cloud.google.com/about/locations/ + string parent = 1; + + // 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; + + // 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; + + // Filter expression to restrict the recommendations returned. Supported + // filter fields: state_info.state + // Eg: `state_info.state:"DISMISSED" or state_info.state:"FAILED" + string filter = 5; +} + +// Response to the `ListRecommendations` method. +message ListRecommendationsResponse { + // The set of recommendations for the `parent` resource. + repeated Recommendation recommendations = 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 `GetRecommendation` method. +message GetRecommendationRequest { + // Name of the recommendation. + string name = 1; +} + +// Request for the `MarkRecommendationClaimed` Method. +message MarkRecommendationClaimedRequest { + // Name of the recommendation. + string name = 1; + + // State properties to include with this state. Overwrites any existing + // `state_metadata`. + map state_metadata = 2; + + // Fingerprint of the Recommendation. Provides optimistic locking. + string etag = 3; +} + +// Request for the `MarkRecommendationSucceeded` Method. +message MarkRecommendationSucceededRequest { + // Name of the recommendation. + string name = 1; + + // State properties to include with this state. Overwrites any existing + // `state_metadata`. + map state_metadata = 2; + + // Fingerprint of the Recommendation. Provides optimistic locking. + string etag = 3; +} + +// Request for the `MarkRecommendationFailed` Method. +message MarkRecommendationFailedRequest { + // Name of the recommendation. + string name = 1; + + // State properties to include with this state. Overwrites any existing + // `state_metadata`. + map state_metadata = 2; + + // Fingerprint of the Recommendation. Provides optimistic locking. + string etag = 3; +}