service.proto 18 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530
  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.notebooks.v1beta1;
  16. import "google/api/annotations.proto";
  17. import "google/api/field_behavior.proto";
  18. import "google/cloud/notebooks/v1beta1/environment.proto";
  19. import "google/cloud/notebooks/v1beta1/instance.proto";
  20. import "google/longrunning/operations.proto";
  21. import "google/protobuf/timestamp.proto";
  22. import "google/api/client.proto";
  23. option csharp_namespace = "Google.Cloud.Notebooks.V1Beta1";
  24. option go_package = "google.golang.org/genproto/googleapis/cloud/notebooks/v1beta1;notebooks";
  25. option php_namespace = "Google\\Cloud\\Notebooks\\V1beta1";
  26. option ruby_package = "Google::Cloud::Notebooks::V1beta1";
  27. option java_multiple_files = true;
  28. option java_outer_classname = "NotebooksProto";
  29. option java_package = "com.google.cloud.notebooks.v1beta1";
  30. // API v1beta1 service for Cloud AI Platform Notebooks.
  31. service NotebookService {
  32. option (google.api.default_host) = "notebooks.googleapis.com";
  33. option (google.api.oauth_scopes) =
  34. "https://www.googleapis.com/auth/cloud-platform";
  35. // Lists instances in a given project and location.
  36. rpc ListInstances(ListInstancesRequest) returns (ListInstancesResponse) {
  37. option (google.api.http) = {
  38. get: "/v1beta1/{parent=projects/*/locations/*}/instances"
  39. };
  40. }
  41. // Gets details of a single Instance.
  42. rpc GetInstance(GetInstanceRequest) returns (Instance) {
  43. option (google.api.http) = {
  44. get: "/v1beta1/{name=projects/*/locations/*/instances/*}"
  45. };
  46. }
  47. // Creates a new Instance in a given project and location.
  48. rpc CreateInstance(CreateInstanceRequest)
  49. returns (google.longrunning.Operation) {
  50. option (google.api.http) = {
  51. post: "/v1beta1/{parent=projects/*/locations/*}/instances"
  52. body: "instance"
  53. };
  54. option (google.longrunning.operation_info) = {
  55. response_type: "Instance"
  56. metadata_type: "OperationMetadata"
  57. };
  58. }
  59. // Registers an existing legacy notebook instance to the Notebooks API server.
  60. // Legacy instances are instances created with the legacy Compute Engine
  61. // calls. They are not manageable by the Notebooks API out of the box. This
  62. // call makes these instances manageable by the Notebooks API.
  63. rpc RegisterInstance(RegisterInstanceRequest)
  64. returns (google.longrunning.Operation) {
  65. option (google.api.http) = {
  66. post: "/v1beta1/{parent=projects/*/locations/*}/instances:register"
  67. body: "*"
  68. };
  69. option (google.longrunning.operation_info) = {
  70. response_type: "Instance"
  71. metadata_type: "OperationMetadata"
  72. };
  73. }
  74. // Updates the guest accelerators of a single Instance.
  75. rpc SetInstanceAccelerator(SetInstanceAcceleratorRequest)
  76. returns (google.longrunning.Operation) {
  77. option (google.api.http) = {
  78. patch: "/v1beta1/{name=projects/*/locations/*/instances/*}:setAccelerator"
  79. body: "*"
  80. };
  81. option (google.longrunning.operation_info) = {
  82. response_type: "Instance"
  83. metadata_type: "OperationMetadata"
  84. };
  85. }
  86. // Updates the machine type of a single Instance.
  87. rpc SetInstanceMachineType(SetInstanceMachineTypeRequest)
  88. returns (google.longrunning.Operation) {
  89. option (google.api.http) = {
  90. patch: "/v1beta1/{name=projects/*/locations/*/instances/*}:setMachineType"
  91. body: "*"
  92. };
  93. option (google.longrunning.operation_info) = {
  94. response_type: "Instance"
  95. metadata_type: "OperationMetadata"
  96. };
  97. }
  98. // Updates the labels of an Instance.
  99. rpc SetInstanceLabels(SetInstanceLabelsRequest)
  100. returns (google.longrunning.Operation) {
  101. option (google.api.http) = {
  102. patch: "/v1beta1/{name=projects/*/locations/*/instances/*}:setLabels"
  103. body: "*"
  104. };
  105. option (google.longrunning.operation_info) = {
  106. response_type: "Instance"
  107. metadata_type: "OperationMetadata"
  108. };
  109. }
  110. // Deletes a single Instance.
  111. rpc DeleteInstance(DeleteInstanceRequest)
  112. returns (google.longrunning.Operation) {
  113. option (google.api.http) = {
  114. delete: "/v1beta1/{name=projects/*/locations/*/instances/*}"
  115. };
  116. option (google.longrunning.operation_info) = {
  117. response_type: "google.protobuf.Empty"
  118. metadata_type: "OperationMetadata"
  119. };
  120. }
  121. // Starts a notebook instance.
  122. rpc StartInstance(StartInstanceRequest)
  123. returns (google.longrunning.Operation) {
  124. option (google.api.http) = {
  125. post: "/v1beta1/{name=projects/*/locations/*/instances/*}:start"
  126. body: "*"
  127. };
  128. option (google.longrunning.operation_info) = {
  129. response_type: "Instance"
  130. metadata_type: "OperationMetadata"
  131. };
  132. }
  133. // Stops a notebook instance.
  134. rpc StopInstance(StopInstanceRequest) returns (google.longrunning.Operation) {
  135. option (google.api.http) = {
  136. post: "/v1beta1/{name=projects/*/locations/*/instances/*}:stop"
  137. body: "*"
  138. };
  139. option (google.longrunning.operation_info) = {
  140. response_type: "Instance"
  141. metadata_type: "OperationMetadata"
  142. };
  143. }
  144. // Resets a notebook instance.
  145. rpc ResetInstance(ResetInstanceRequest)
  146. returns (google.longrunning.Operation) {
  147. option (google.api.http) = {
  148. post: "/v1beta1/{name=projects/*/locations/*/instances/*}:reset"
  149. body: "*"
  150. };
  151. option (google.longrunning.operation_info) = {
  152. response_type: "Instance"
  153. metadata_type: "OperationMetadata"
  154. };
  155. }
  156. // Allows notebook instances to
  157. // report their latest instance information to the Notebooks
  158. // API server. The server will merge the reported information to
  159. // the instance metadata store. Do not use this method directly.
  160. rpc ReportInstanceInfo(ReportInstanceInfoRequest)
  161. returns (google.longrunning.Operation) {
  162. option (google.api.http) = {
  163. post: "/v1beta1/{name=projects/*/locations/*/instances/*}:report"
  164. body: "*"
  165. };
  166. option (google.longrunning.operation_info) = {
  167. response_type: "Instance"
  168. metadata_type: "OperationMetadata"
  169. };
  170. }
  171. // Check if a notebook instance is upgradable.
  172. rpc IsInstanceUpgradeable(IsInstanceUpgradeableRequest)
  173. returns (IsInstanceUpgradeableResponse) {
  174. option (google.api.http) = {
  175. get: "/v1beta1/{notebook_instance=projects/*/locations/*/instances/*}:isUpgradeable"
  176. };
  177. }
  178. // Upgrades a notebook instance to the latest version.
  179. rpc UpgradeInstance(UpgradeInstanceRequest)
  180. returns (google.longrunning.Operation) {
  181. option (google.api.http) = {
  182. post: "/v1beta1/{name=projects/*/locations/*/instances/*}:upgrade"
  183. body: "*"
  184. };
  185. option (google.longrunning.operation_info) = {
  186. response_type: "Instance"
  187. metadata_type: "OperationMetadata"
  188. };
  189. }
  190. // Allows notebook instances to
  191. // call this endpoint to upgrade themselves. Do not use this method directly.
  192. rpc UpgradeInstanceInternal(UpgradeInstanceInternalRequest)
  193. returns (google.longrunning.Operation) {
  194. option (google.api.http) = {
  195. post: "/v1beta1/{name=projects/*/locations/*/instances/*}:upgradeInternal"
  196. body: "*"
  197. };
  198. option (google.longrunning.operation_info) = {
  199. response_type: "Instance"
  200. metadata_type: "OperationMetadata"
  201. };
  202. }
  203. // Lists environments in a project.
  204. rpc ListEnvironments(ListEnvironmentsRequest)
  205. returns (ListEnvironmentsResponse) {
  206. option (google.api.http) = {
  207. get: "/v1beta1/{parent=projects/*/locations/*}/environments"
  208. };
  209. }
  210. // Gets details of a single Environment.
  211. rpc GetEnvironment(GetEnvironmentRequest) returns (Environment) {
  212. option (google.api.http) = {
  213. get: "/v1beta1/{name=projects/*/locations/*/environments/*}"
  214. };
  215. }
  216. // Creates a new Environment.
  217. rpc CreateEnvironment(CreateEnvironmentRequest)
  218. returns (google.longrunning.Operation) {
  219. option (google.api.http) = {
  220. post: "/v1beta1/{parent=projects/*/locations/*}/environments"
  221. body: "environment"
  222. };
  223. option (google.longrunning.operation_info) = {
  224. response_type: "Environment"
  225. metadata_type: "OperationMetadata"
  226. };
  227. }
  228. // Deletes a single Environment.
  229. rpc DeleteEnvironment(DeleteEnvironmentRequest)
  230. returns (google.longrunning.Operation) {
  231. option (google.api.http) = {
  232. delete: "/v1beta1/{name=projects/*/locations/*/environments/*}"
  233. };
  234. option (google.longrunning.operation_info) = {
  235. response_type: "google.protobuf.Empty"
  236. metadata_type: "OperationMetadata"
  237. };
  238. }
  239. }
  240. // Represents the metadata of the long-running operation.
  241. message OperationMetadata {
  242. // The time the operation was created.
  243. google.protobuf.Timestamp create_time = 1;
  244. // The time the operation finished running.
  245. google.protobuf.Timestamp end_time = 2;
  246. // Server-defined resource path for the target of the operation.
  247. string target = 3;
  248. // Name of the verb executed by the operation.
  249. string verb = 4;
  250. // Human-readable status of the operation, if any.
  251. string status_message = 5;
  252. // Identifies whether the user has requested cancellation
  253. // of the operation. Operations that have successfully been cancelled
  254. // have [Operation.error][] value with a
  255. // [google.rpc.Status.code][google.rpc.Status.code] of 1, corresponding to
  256. // `Code.CANCELLED`.
  257. bool requested_cancellation = 6;
  258. // API version used to start the operation.
  259. string api_version = 7;
  260. // API endpoint name of this operation.
  261. string endpoint = 8;
  262. }
  263. // Request for listing notebook instances.
  264. message ListInstancesRequest {
  265. // Required. Format:
  266. // `parent=projects/{project_id}/locations/{location}`
  267. string parent = 1 [(google.api.field_behavior) = REQUIRED];
  268. // Maximum return size of the list call.
  269. int32 page_size = 2;
  270. // A previous returned page token that can be used to continue listing
  271. // from the last result.
  272. string page_token = 3;
  273. }
  274. // Response for listing notebook instances.
  275. message ListInstancesResponse {
  276. // A list of returned instances.
  277. repeated Instance instances = 1;
  278. // Page token that can be used to continue listing from the last result in the
  279. // next list call.
  280. string next_page_token = 2;
  281. // Locations that could not be reached. For example,
  282. // ['us-west1-a', 'us-central1-b'].
  283. // A ListInstancesResponse will only contain either instances or unreachables,
  284. repeated string unreachable = 3;
  285. }
  286. // Request for getting a notebook instance.
  287. message GetInstanceRequest {
  288. // Required. Format:
  289. // `projects/{project_id}/locations/{location}/instances/{instance_id}`
  290. string name = 1 [(google.api.field_behavior) = REQUIRED];
  291. }
  292. // Request for creating a notebook instance.
  293. message CreateInstanceRequest {
  294. // Required. Format:
  295. // `parent=projects/{project_id}/locations/{location}`
  296. string parent = 1 [(google.api.field_behavior) = REQUIRED];
  297. // Required. User-defined unique ID of this instance.
  298. string instance_id = 2 [(google.api.field_behavior) = REQUIRED];
  299. // Required. The instance to be created.
  300. Instance instance = 3 [(google.api.field_behavior) = REQUIRED];
  301. }
  302. // Request for registering a notebook instance.
  303. message RegisterInstanceRequest {
  304. // Required. Format:
  305. // `parent=projects/{project_id}/locations/{location}`
  306. string parent = 1 [(google.api.field_behavior) = REQUIRED];
  307. // Required. User defined unique ID of this instance. The `instance_id` must
  308. // be 1 to 63 characters long and contain only lowercase letters,
  309. // numeric characters, and dashes. The first character must be a lowercase
  310. // letter and the last character cannot be a dash.
  311. string instance_id = 2 [(google.api.field_behavior) = REQUIRED];
  312. }
  313. // Request for setting instance accelerator.
  314. message SetInstanceAcceleratorRequest {
  315. // Required. Format:
  316. // `projects/{project_id}/locations/{location}/instances/{instance_id}`
  317. string name = 1 [(google.api.field_behavior) = REQUIRED];
  318. // Required. Type of this accelerator.
  319. Instance.AcceleratorType type = 2 [(google.api.field_behavior) = REQUIRED];
  320. // Required. Count of cores of this accelerator. Note that not all
  321. // combinations of `type` and `core_count` are valid. Check [GPUs on Compute
  322. // Engine](https://cloud.google.com/compute/docs/gpus/#gpus-list) to find a
  323. // valid combination. TPUs are not supported.
  324. int64 core_count = 3 [(google.api.field_behavior) = REQUIRED];
  325. }
  326. // Request for setting instance machine type.
  327. message SetInstanceMachineTypeRequest {
  328. // Required. Format:
  329. // `projects/{project_id}/locations/{location}/instances/{instance_id}`
  330. string name = 1 [(google.api.field_behavior) = REQUIRED];
  331. // Required. The [Compute Engine machine
  332. // type](https://cloud.google.com/compute/docs/machine-types).
  333. string machine_type = 2 [(google.api.field_behavior) = REQUIRED];
  334. }
  335. // Request for setting instance labels.
  336. message SetInstanceLabelsRequest {
  337. // Required. Format:
  338. // `projects/{project_id}/locations/{location}/instances/{instance_id}`
  339. string name = 1 [(google.api.field_behavior) = REQUIRED];
  340. // Labels to apply to this instance.
  341. // These can be later modified by the setLabels method
  342. map<string, string> labels = 2;
  343. }
  344. // Request for deleting a notebook instance.
  345. message DeleteInstanceRequest {
  346. // Required. Format:
  347. // `projects/{project_id}/locations/{location}/instances/{instance_id}`
  348. string name = 1 [(google.api.field_behavior) = REQUIRED];
  349. }
  350. // Request for starting a notebook instance
  351. message StartInstanceRequest {
  352. // Required. Format:
  353. // `projects/{project_id}/locations/{location}/instances/{instance_id}`
  354. string name = 1 [(google.api.field_behavior) = REQUIRED];
  355. }
  356. // Request for stopping a notebook instance
  357. message StopInstanceRequest {
  358. // Required. Format:
  359. // `projects/{project_id}/locations/{location}/instances/{instance_id}`
  360. string name = 1 [(google.api.field_behavior) = REQUIRED];
  361. }
  362. // Request for reseting a notebook instance
  363. message ResetInstanceRequest {
  364. // Required. Format:
  365. // `projects/{project_id}/locations/{location}/instances/{instance_id}`
  366. string name = 1 [(google.api.field_behavior) = REQUIRED];
  367. }
  368. // Request for notebook instances to report information to Notebooks API.
  369. message ReportInstanceInfoRequest {
  370. // Required. Format:
  371. // `projects/{project_id}/locations/{location}/instances/{instance_id}`
  372. string name = 1 [(google.api.field_behavior) = REQUIRED];
  373. // Required. The VM hardware token for authenticating the VM.
  374. // https://cloud.google.com/compute/docs/instances/verifying-instance-identity
  375. string vm_id = 2 [(google.api.field_behavior) = REQUIRED];
  376. // The metadata reported to Notebooks API. This will be merged to the instance
  377. // metadata store
  378. map<string, string> metadata = 3;
  379. }
  380. // Request for checking if a notebook instance is upgradeable.
  381. message IsInstanceUpgradeableRequest {
  382. // Required. Format:
  383. // `projects/{project_id}/locations/{location}/instances/{instance_id}`
  384. string notebook_instance = 1 [(google.api.field_behavior) = REQUIRED];
  385. }
  386. // Response for checking if a notebook instance is upgradeable.
  387. message IsInstanceUpgradeableResponse {
  388. // If an instance is upgradeable.
  389. bool upgradeable = 1;
  390. // The version this instance will be upgraded to if calling the upgrade
  391. // endpoint. This field will only be populated if field upgradeable is true.
  392. string upgrade_version = 2;
  393. // Additional information about upgrade.
  394. string upgrade_info = 3;
  395. }
  396. // Request for upgrading a notebook instance
  397. message UpgradeInstanceRequest {
  398. // Required. Format:
  399. // `projects/{project_id}/locations/{location}/instances/{instance_id}`
  400. string name = 1 [(google.api.field_behavior) = REQUIRED];
  401. }
  402. // Request for upgrading a notebook instance from within the VM
  403. message UpgradeInstanceInternalRequest {
  404. // Required. Format:
  405. // `projects/{project_id}/locations/{location}/instances/{instance_id}`
  406. string name = 1 [(google.api.field_behavior) = REQUIRED];
  407. // Required. The VM hardware token for authenticating the VM.
  408. // https://cloud.google.com/compute/docs/instances/verifying-instance-identity
  409. string vm_id = 2 [(google.api.field_behavior) = REQUIRED];
  410. }
  411. // Request for listing environments.
  412. message ListEnvironmentsRequest {
  413. // Required. Format: `projects/{project_id}/locations/{location}`
  414. string parent = 1 [(google.api.field_behavior) = REQUIRED];
  415. // Maximum return size of the list call.
  416. int32 page_size = 2;
  417. // A previous returned page token that can be used to continue listing from
  418. // the last result.
  419. string page_token = 3;
  420. }
  421. // Response for listing environments.
  422. message ListEnvironmentsResponse {
  423. // A list of returned environments.
  424. repeated Environment environments = 1;
  425. // A page token that can be used to continue listing from the last result
  426. // in the next list call.
  427. string next_page_token = 2;
  428. // Locations that could not be reached.
  429. repeated string unreachable = 3;
  430. }
  431. // Request for getting a notebook environment.
  432. message GetEnvironmentRequest {
  433. // Required. Format:
  434. // `projects/{project_id}/locations/{location}/environments/{environment_id}`
  435. string name = 1 [(google.api.field_behavior) = REQUIRED];
  436. }
  437. // Request for creating a notebook environment.
  438. message CreateEnvironmentRequest {
  439. // Required. Format: `projects/{project_id}/locations/{location}`
  440. string parent = 1 [(google.api.field_behavior) = REQUIRED];
  441. // Required. User-defined unique ID of this environment. The `environment_id`
  442. // must be 1 to 63 characters long and contain only lowercase letters, numeric
  443. // characters, and dashes. The first character must be a lowercase letter and
  444. // the last character cannot be a dash.
  445. string environment_id = 2 [(google.api.field_behavior) = REQUIRED];
  446. // Required. The environment to be created.
  447. Environment environment = 3 [(google.api.field_behavior) = REQUIRED];
  448. }
  449. // Request for deleting a notebook environment.
  450. message DeleteEnvironmentRequest {
  451. // Required. Format:
  452. // `projects/{project_id}/locations/{location}/environments/{environment_id}`
  453. string name = 1 [(google.api.field_behavior) = REQUIRED];
  454. }