recommender_service.proto 16 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422
  1. // Copyright 2020 Google LLC
  2. //
  3. // Licensed under the Apache License, Version 2.0 (the "License");
  4. // you may not use this file except in compliance with the License.
  5. // You may obtain a copy of the License at
  6. //
  7. // http://www.apache.org/licenses/LICENSE-2.0
  8. //
  9. // Unless required by applicable law or agreed to in writing, software
  10. // distributed under the License is distributed on an "AS IS" BASIS,
  11. // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  12. // See the License for the specific language governing permissions and
  13. // limitations under the License.
  14. syntax = "proto3";
  15. package google.cloud.recommender.v1beta1;
  16. import "google/api/annotations.proto";
  17. import "google/api/client.proto";
  18. import "google/api/field_behavior.proto";
  19. import "google/api/resource.proto";
  20. import "google/cloud/recommender/v1beta1/insight.proto";
  21. import "google/cloud/recommender/v1beta1/recommendation.proto";
  22. option csharp_namespace = "Google.Cloud.Recommender.V1Beta1";
  23. option go_package = "google.golang.org/genproto/googleapis/cloud/recommender/v1beta1;recommender";
  24. option java_multiple_files = true;
  25. option java_outer_classname = "RecommenderProto";
  26. option java_package = "com.google.cloud.recommender.v1beta1";
  27. option objc_class_prefix = "CREC";
  28. // Provides insights and recommendations for cloud customers for various
  29. // categories like performance optimization, cost savings, reliability, feature
  30. // discovery, etc. Insights and recommendations are generated automatically
  31. // based on analysis of user resources, configuration and monitoring metrics.
  32. service Recommender {
  33. option (google.api.default_host) = "recommender.googleapis.com";
  34. option (google.api.oauth_scopes) = "https://www.googleapis.com/auth/cloud-platform";
  35. // Lists insights for a Cloud project. Requires the recommender.*.list IAM
  36. // permission for the specified insight type.
  37. rpc ListInsights(ListInsightsRequest) returns (ListInsightsResponse) {
  38. option (google.api.http) = {
  39. get: "/v1beta1/{parent=projects/*/locations/*/insightTypes/*}/insights"
  40. additional_bindings {
  41. get: "/v1beta1/{parent=billingAccounts/*/locations/*/insightTypes/*}/insights"
  42. }
  43. additional_bindings {
  44. get: "/v1beta1/{parent=folders/*/locations/*/insightTypes/*}/insights"
  45. }
  46. additional_bindings {
  47. get: "/v1beta1/{parent=organizations/*/locations/*/insightTypes/*}/insights"
  48. }
  49. };
  50. option (google.api.method_signature) = "parent";
  51. }
  52. // Gets the requested insight. Requires the recommender.*.get IAM permission
  53. // for the specified insight type.
  54. rpc GetInsight(GetInsightRequest) returns (Insight) {
  55. option (google.api.http) = {
  56. get: "/v1beta1/{name=projects/*/locations/*/insightTypes/*/insights/*}"
  57. additional_bindings {
  58. get: "/v1beta1/{name=billingAccounts/*/locations/*/insightTypes/*/insights/*}"
  59. }
  60. additional_bindings {
  61. get: "/v1beta1/{name=folders/*/locations/*/insightTypes/*/insights/*}"
  62. }
  63. additional_bindings {
  64. get: "/v1beta1/{name=organizations/*/locations/*/insightTypes/*/insights/*}"
  65. }
  66. };
  67. option (google.api.method_signature) = "name";
  68. }
  69. // Marks the Insight State as Accepted. Users can use this method to
  70. // indicate to the Recommender API that they have applied some action based
  71. // on the insight. This stops the insight content from being updated.
  72. //
  73. // MarkInsightAccepted can be applied to insights in ACTIVE state. Requires
  74. // the recommender.*.update IAM permission for the specified insight.
  75. rpc MarkInsightAccepted(MarkInsightAcceptedRequest) returns (Insight) {
  76. option (google.api.http) = {
  77. post: "/v1beta1/{name=projects/*/locations/*/insightTypes/*/insights/*}:markAccepted"
  78. body: "*"
  79. additional_bindings {
  80. post: "/v1beta1/{name=billingAccounts/*/locations/*/insightTypes/*/insights/*}:markAccepted"
  81. body: "*"
  82. }
  83. additional_bindings {
  84. post: "/v1beta1/{name=folders/*/locations/*/insightTypes/*/insights/*}:markAccepted"
  85. body: "*"
  86. }
  87. additional_bindings {
  88. post: "/v1beta1/{name=organizations/*/locations/*/insightTypes/*/insights/*}:markAccepted"
  89. body: "*"
  90. }
  91. };
  92. option (google.api.method_signature) = "name,state_metadata,etag";
  93. }
  94. // Lists recommendations for a Cloud project. Requires the recommender.*.list
  95. // IAM permission for the specified recommender.
  96. rpc ListRecommendations(ListRecommendationsRequest) returns (ListRecommendationsResponse) {
  97. option (google.api.http) = {
  98. get: "/v1beta1/{parent=projects/*/locations/*/recommenders/*}/recommendations"
  99. additional_bindings {
  100. get: "/v1beta1/{parent=billingAccounts/*/locations/*/recommenders/*}/recommendations"
  101. }
  102. additional_bindings {
  103. get: "/v1beta1/{parent=folders/*/locations/*/recommenders/*}/recommendations"
  104. }
  105. additional_bindings {
  106. get: "/v1beta1/{parent=organizations/*/locations/*/recommenders/*}/recommendations"
  107. }
  108. };
  109. option (google.api.method_signature) = "parent,filter";
  110. }
  111. // Gets the requested recommendation. Requires the recommender.*.get
  112. // IAM permission for the specified recommender.
  113. rpc GetRecommendation(GetRecommendationRequest) returns (Recommendation) {
  114. option (google.api.http) = {
  115. get: "/v1beta1/{name=projects/*/locations/*/recommenders/*/recommendations/*}"
  116. additional_bindings {
  117. get: "/v1beta1/{name=billingAccounts/*/locations/*/recommenders/*/recommendations/*}"
  118. }
  119. additional_bindings {
  120. get: "/v1beta1/{name=folders/*/locations/*/recommenders/*/recommendations/*}"
  121. }
  122. additional_bindings {
  123. get: "/v1beta1/{name=organizations/*/locations/*/recommenders/*/recommendations/*}"
  124. }
  125. };
  126. option (google.api.method_signature) = "name";
  127. }
  128. // Marks the Recommendation State as Claimed. Users can use this method to
  129. // indicate to the Recommender API that they are starting to apply the
  130. // recommendation themselves. This stops the recommendation content from being
  131. // updated. Associated insights are frozen and placed in the ACCEPTED state.
  132. //
  133. // MarkRecommendationClaimed can be applied to recommendations in CLAIMED or
  134. // ACTIVE state.
  135. //
  136. // Requires the recommender.*.update IAM permission for the specified
  137. // recommender.
  138. rpc MarkRecommendationClaimed(MarkRecommendationClaimedRequest) returns (Recommendation) {
  139. option (google.api.http) = {
  140. post: "/v1beta1/{name=projects/*/locations/*/recommenders/*/recommendations/*}:markClaimed"
  141. body: "*"
  142. additional_bindings {
  143. post: "/v1beta1/{name=billingAccounts/*/locations/*/recommenders/*/recommendations/*}:markClaimed"
  144. body: "*"
  145. }
  146. additional_bindings {
  147. post: "/v1beta1/{name=folders/*/locations/*/recommenders/*/recommendations/*}:markClaimed"
  148. body: "*"
  149. }
  150. additional_bindings {
  151. post: "/v1beta1/{name=organizations/*/locations/*/recommenders/*/recommendations/*}:markClaimed"
  152. body: "*"
  153. }
  154. };
  155. option (google.api.method_signature) = "name,state_metadata,etag";
  156. }
  157. // Marks the Recommendation State as Succeeded. Users can use this method to
  158. // indicate to the Recommender API that they have applied the recommendation
  159. // themselves, and the operation was successful. This stops the recommendation
  160. // content from being updated. Associated insights are frozen and placed in
  161. // the ACCEPTED state.
  162. //
  163. // MarkRecommendationSucceeded can be applied to recommendations in ACTIVE,
  164. // CLAIMED, SUCCEEDED, or FAILED state.
  165. //
  166. // Requires the recommender.*.update IAM permission for the specified
  167. // recommender.
  168. rpc MarkRecommendationSucceeded(MarkRecommendationSucceededRequest) returns (Recommendation) {
  169. option (google.api.http) = {
  170. post: "/v1beta1/{name=projects/*/locations/*/recommenders/*/recommendations/*}:markSucceeded"
  171. body: "*"
  172. additional_bindings {
  173. post: "/v1beta1/{name=billingAccounts/*/locations/*/recommenders/*/recommendations/*}:markSucceeded"
  174. body: "*"
  175. }
  176. additional_bindings {
  177. post: "/v1beta1/{name=folders/*/locations/*/recommenders/*/recommendations/*}:markSucceeded"
  178. body: "*"
  179. }
  180. additional_bindings {
  181. post: "/v1beta1/{name=organizations/*/locations/*/recommenders/*/recommendations/*}:markSucceeded"
  182. body: "*"
  183. }
  184. };
  185. option (google.api.method_signature) = "name,state_metadata,etag";
  186. }
  187. // Marks the Recommendation State as Failed. Users can use this method to
  188. // indicate to the Recommender API that they have applied the recommendation
  189. // themselves, and the operation failed. This stops the recommendation content
  190. // from being updated. Associated insights are frozen and placed in the
  191. // ACCEPTED state.
  192. //
  193. // MarkRecommendationFailed can be applied to recommendations in ACTIVE,
  194. // CLAIMED, SUCCEEDED, or FAILED state.
  195. //
  196. // Requires the recommender.*.update IAM permission for the specified
  197. // recommender.
  198. rpc MarkRecommendationFailed(MarkRecommendationFailedRequest) returns (Recommendation) {
  199. option (google.api.http) = {
  200. post: "/v1beta1/{name=projects/*/locations/*/recommenders/*/recommendations/*}:markFailed"
  201. body: "*"
  202. additional_bindings {
  203. post: "/v1beta1/{name=billingAccounts/*/locations/*/recommenders/*/recommendations/*}:markFailed"
  204. body: "*"
  205. }
  206. additional_bindings {
  207. post: "/v1beta1/{name=folders/*/locations/*/recommenders/*/recommendations/*}:markFailed"
  208. body: "*"
  209. }
  210. additional_bindings {
  211. post: "/v1beta1/{name=organizations/*/locations/*/recommenders/*/recommendations/*}:markFailed"
  212. body: "*"
  213. }
  214. };
  215. option (google.api.method_signature) = "name,state_metadata,etag";
  216. }
  217. }
  218. // Request for the `ListInsights` method.
  219. message ListInsightsRequest {
  220. // Required. The container resource on which to execute the request.
  221. // Acceptable formats:
  222. //
  223. // 1.
  224. // "projects/[PROJECT_NUMBER]/locations/[LOCATION]/insightTypes/[INSIGHT_TYPE_ID]",
  225. //
  226. // LOCATION here refers to GCP Locations:
  227. // https://cloud.google.com/about/locations/
  228. // INSIGHT_TYPE_ID refers to supported insight types:
  229. // https://cloud.google.com/recommender/docs/insights/insight-types.
  230. string parent = 1 [
  231. (google.api.field_behavior) = REQUIRED,
  232. (google.api.resource_reference) = {
  233. type: "recommender.googleapis.com/InsightType"
  234. }
  235. ];
  236. // Optional. The maximum number of results to return from this request. Non-positive
  237. // values are ignored. If not specified, the server will determine the number
  238. // of results to return.
  239. int32 page_size = 2 [(google.api.field_behavior) = OPTIONAL];
  240. // Optional. If present, retrieves the next batch of results from the preceding call to
  241. // this method. `page_token` must be the value of `next_page_token` from the
  242. // previous response. The values of other method parameters must be identical
  243. // to those in the previous call.
  244. string page_token = 3 [(google.api.field_behavior) = OPTIONAL];
  245. // Optional. Filter expression to restrict the insights returned. Supported
  246. // filter fields: state
  247. // Eg: `state:"DISMISSED" or state:"ACTIVE"
  248. string filter = 4 [(google.api.field_behavior) = OPTIONAL];
  249. }
  250. // Response to the `ListInsights` method.
  251. message ListInsightsResponse {
  252. // The set of insights for the `parent` resource.
  253. repeated Insight insights = 1;
  254. // A token that can be used to request the next page of results. This field is
  255. // empty if there are no additional results.
  256. string next_page_token = 2;
  257. }
  258. // Request to the `GetInsight` method.
  259. message GetInsightRequest {
  260. // Required. Name of the insight.
  261. string name = 1 [
  262. (google.api.field_behavior) = REQUIRED,
  263. (google.api.resource_reference) = {
  264. type: "recommender.googleapis.com/Insight"
  265. }
  266. ];
  267. }
  268. // Request for the `MarkInsightAccepted` method.
  269. message MarkInsightAcceptedRequest {
  270. // Required. Name of the insight.
  271. string name = 1 [
  272. (google.api.field_behavior) = REQUIRED,
  273. (google.api.resource_reference) = {
  274. type: "recommender.googleapis.com/Insight"
  275. }
  276. ];
  277. // Optional. State properties user wish to include with this state. Full replace of the
  278. // current state_metadata.
  279. map<string, string> state_metadata = 2 [(google.api.field_behavior) = OPTIONAL];
  280. // Required. Fingerprint of the Insight. Provides optimistic locking.
  281. string etag = 3 [(google.api.field_behavior) = REQUIRED];
  282. }
  283. // Request for the `ListRecommendations` method.
  284. message ListRecommendationsRequest {
  285. // Required. The container resource on which to execute the request.
  286. // Acceptable formats:
  287. //
  288. // 1.
  289. // "projects/[PROJECT_NUMBER]/locations/[LOCATION]/recommenders/[RECOMMENDER_ID]",
  290. //
  291. // LOCATION here refers to GCP Locations:
  292. // https://cloud.google.com/about/locations/
  293. // RECOMMENDER_ID refers to supported recommenders:
  294. // https://cloud.google.com/recommender/docs/recommenders.
  295. string parent = 1 [
  296. (google.api.field_behavior) = REQUIRED,
  297. (google.api.resource_reference) = {
  298. type: "recommender.googleapis.com/Recommender"
  299. }
  300. ];
  301. // Optional. The maximum number of results to return from this request. Non-positive
  302. // values are ignored. If not specified, the server will determine the number
  303. // of results to return.
  304. int32 page_size = 2 [(google.api.field_behavior) = OPTIONAL];
  305. // Optional. If present, retrieves the next batch of results from the preceding call to
  306. // this method. `page_token` must be the value of `next_page_token` from the
  307. // previous response. The values of other method parameters must be identical
  308. // to those in the previous call.
  309. string page_token = 3 [(google.api.field_behavior) = OPTIONAL];
  310. // Filter expression to restrict the recommendations returned. Supported
  311. // filter fields: state_info.state
  312. // Eg: `state_info.state:"DISMISSED" or state_info.state:"FAILED"
  313. string filter = 5;
  314. }
  315. // Response to the `ListRecommendations` method.
  316. message ListRecommendationsResponse {
  317. // The set of recommendations for the `parent` resource.
  318. repeated Recommendation recommendations = 1;
  319. // A token that can be used to request the next page of results. This field is
  320. // empty if there are no additional results.
  321. string next_page_token = 2;
  322. }
  323. // Request to the `GetRecommendation` method.
  324. message GetRecommendationRequest {
  325. // Required. Name of the recommendation.
  326. string name = 1 [
  327. (google.api.field_behavior) = REQUIRED,
  328. (google.api.resource_reference) = {
  329. type: "recommender.googleapis.com/Recommendation"
  330. }
  331. ];
  332. }
  333. // Request for the `MarkRecommendationClaimed` Method.
  334. message MarkRecommendationClaimedRequest {
  335. // Required. Name of the recommendation.
  336. string name = 1 [
  337. (google.api.field_behavior) = REQUIRED,
  338. (google.api.resource_reference) = {
  339. type: "recommender.googleapis.com/Recommendation"
  340. }
  341. ];
  342. // State properties to include with this state. Overwrites any existing
  343. // `state_metadata`.
  344. // Keys must match the regex /^[a-z0-9][a-z0-9_.-]{0,62}$/.
  345. // Values must match the regex /^[a-zA-Z0-9_./-]{0,255}$/.
  346. map<string, string> state_metadata = 2;
  347. // Required. Fingerprint of the Recommendation. Provides optimistic locking.
  348. string etag = 3 [(google.api.field_behavior) = REQUIRED];
  349. }
  350. // Request for the `MarkRecommendationSucceeded` Method.
  351. message MarkRecommendationSucceededRequest {
  352. // Required. Name of the recommendation.
  353. string name = 1 [
  354. (google.api.field_behavior) = REQUIRED,
  355. (google.api.resource_reference) = {
  356. type: "recommender.googleapis.com/Recommendation"
  357. }
  358. ];
  359. // State properties to include with this state. Overwrites any existing
  360. // `state_metadata`.
  361. // Keys must match the regex /^[a-z0-9][a-z0-9_.-]{0,62}$/.
  362. // Values must match the regex /^[a-zA-Z0-9_./-]{0,255}$/.
  363. map<string, string> state_metadata = 2;
  364. // Required. Fingerprint of the Recommendation. Provides optimistic locking.
  365. string etag = 3 [(google.api.field_behavior) = REQUIRED];
  366. }
  367. // Request for the `MarkRecommendationFailed` Method.
  368. message MarkRecommendationFailedRequest {
  369. // Required. Name of the recommendation.
  370. string name = 1 [
  371. (google.api.field_behavior) = REQUIRED,
  372. (google.api.resource_reference) = {
  373. type: "recommender.googleapis.com/Recommendation"
  374. }
  375. ];
  376. // State properties to include with this state. Overwrites any existing
  377. // `state_metadata`.
  378. // Keys must match the regex /^[a-z0-9][a-z0-9_.-]{0,62}$/.
  379. // Values must match the regex /^[a-zA-Z0-9_./-]{0,255}$/.
  380. map<string, string> state_metadata = 2;
  381. // Required. Fingerprint of the Recommendation. Provides optimistic locking.
  382. string etag = 3 [(google.api.field_behavior) = REQUIRED];
  383. }