cloud_billing.proto 15 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360
  1. // Copyright 2019 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. //
  15. syntax = "proto3";
  16. package google.cloud.billing.v1;
  17. import "google/api/annotations.proto";
  18. import "google/api/client.proto";
  19. import "google/api/field_behavior.proto";
  20. import "google/api/resource.proto";
  21. import "google/iam/v1/iam_policy.proto";
  22. import "google/iam/v1/policy.proto";
  23. import "google/protobuf/field_mask.proto";
  24. option go_package = "google.golang.org/genproto/googleapis/cloud/billing/v1;billing";
  25. option java_multiple_files = true;
  26. option java_outer_classname = "CloudBillingProto";
  27. option java_package = "com.google.cloud.billing.v1";
  28. // Retrieves GCP Console billing accounts and associates them with projects.
  29. service CloudBilling {
  30. option (google.api.default_host) = "cloudbilling.googleapis.com";
  31. option (google.api.oauth_scopes) = "https://www.googleapis.com/auth/cloud-platform";
  32. // Gets information about a billing account. The current authenticated user
  33. // must be a [viewer of the billing
  34. // account](https://cloud.google.com/billing/docs/how-to/billing-access).
  35. rpc GetBillingAccount(GetBillingAccountRequest) returns (BillingAccount) {
  36. option (google.api.http) = {
  37. get: "/v1/{name=billingAccounts/*}"
  38. };
  39. option (google.api.method_signature) = "name";
  40. }
  41. // Lists the billing accounts that the current authenticated user has
  42. // permission to
  43. // [view](https://cloud.google.com/billing/docs/how-to/billing-access).
  44. rpc ListBillingAccounts(ListBillingAccountsRequest) returns (ListBillingAccountsResponse) {
  45. option (google.api.http) = {
  46. get: "/v1/billingAccounts"
  47. };
  48. option (google.api.method_signature) = "";
  49. }
  50. // Updates a billing account's fields.
  51. // Currently the only field that can be edited is `display_name`.
  52. // The current authenticated user must have the `billing.accounts.update`
  53. // IAM permission, which is typically given to the
  54. // [administrator](https://cloud.google.com/billing/docs/how-to/billing-access)
  55. // of the billing account.
  56. rpc UpdateBillingAccount(UpdateBillingAccountRequest) returns (BillingAccount) {
  57. option (google.api.http) = {
  58. patch: "/v1/{name=billingAccounts/*}"
  59. body: "account"
  60. };
  61. option (google.api.method_signature) = "name,account";
  62. }
  63. // Creates a billing account.
  64. // This method can only be used to create
  65. // [billing subaccounts](https://cloud.google.com/billing/docs/concepts)
  66. // by GCP resellers.
  67. // When creating a subaccount, the current authenticated user must have the
  68. // `billing.accounts.update` IAM permission on the master account, which is
  69. // typically given to billing account
  70. // [administrators](https://cloud.google.com/billing/docs/how-to/billing-access).
  71. // This method will return an error if the master account has not been
  72. // provisioned as a reseller account.
  73. rpc CreateBillingAccount(CreateBillingAccountRequest) returns (BillingAccount) {
  74. option (google.api.http) = {
  75. post: "/v1/billingAccounts"
  76. body: "billing_account"
  77. };
  78. option (google.api.method_signature) = "billing_account";
  79. }
  80. // Lists the projects associated with a billing account. The current
  81. // authenticated user must have the `billing.resourceAssociations.list` IAM
  82. // permission, which is often given to billing account
  83. // [viewers](https://cloud.google.com/billing/docs/how-to/billing-access).
  84. rpc ListProjectBillingInfo(ListProjectBillingInfoRequest) returns (ListProjectBillingInfoResponse) {
  85. option (google.api.http) = {
  86. get: "/v1/{name=billingAccounts/*}/projects"
  87. };
  88. option (google.api.method_signature) = "name";
  89. }
  90. // Gets the billing information for a project. The current authenticated user
  91. // must have [permission to view the
  92. // project](https://cloud.google.com/docs/permissions-overview#h.bgs0oxofvnoo
  93. // ).
  94. rpc GetProjectBillingInfo(GetProjectBillingInfoRequest) returns (ProjectBillingInfo) {
  95. option (google.api.http) = {
  96. get: "/v1/{name=projects/*}/billingInfo"
  97. };
  98. option (google.api.method_signature) = "name";
  99. }
  100. // Sets or updates the billing account associated with a project. You specify
  101. // the new billing account by setting the `billing_account_name` in the
  102. // `ProjectBillingInfo` resource to the resource name of a billing account.
  103. // Associating a project with an open billing account enables billing on the
  104. // project and allows charges for resource usage. If the project already had a
  105. // billing account, this method changes the billing account used for resource
  106. // usage charges.
  107. //
  108. // *Note:* Incurred charges that have not yet been reported in the transaction
  109. // history of the GCP Console might be billed to the new billing
  110. // account, even if the charge occurred before the new billing account was
  111. // assigned to the project.
  112. //
  113. // The current authenticated user must have ownership privileges for both the
  114. // [project](https://cloud.google.com/docs/permissions-overview#h.bgs0oxofvnoo
  115. // ) and the [billing
  116. // account](https://cloud.google.com/billing/docs/how-to/billing-access).
  117. //
  118. // You can disable billing on the project by setting the
  119. // `billing_account_name` field to empty. This action disassociates the
  120. // current billing account from the project. Any billable activity of your
  121. // in-use services will stop, and your application could stop functioning as
  122. // expected. Any unbilled charges to date will be billed to the previously
  123. // associated account. The current authenticated user must be either an owner
  124. // of the project or an owner of the billing account for the project.
  125. //
  126. // Note that associating a project with a *closed* billing account will have
  127. // much the same effect as disabling billing on the project: any paid
  128. // resources used by the project will be shut down. Thus, unless you wish to
  129. // disable billing, you should always call this method with the name of an
  130. // *open* billing account.
  131. rpc UpdateProjectBillingInfo(UpdateProjectBillingInfoRequest) returns (ProjectBillingInfo) {
  132. option (google.api.http) = {
  133. put: "/v1/{name=projects/*}/billingInfo"
  134. body: "project_billing_info"
  135. };
  136. option (google.api.method_signature) = "name,project_billing_info";
  137. }
  138. // Gets the access control policy for a billing account.
  139. // The caller must have the `billing.accounts.getIamPolicy` permission on the
  140. // account, which is often given to billing account
  141. // [viewers](https://cloud.google.com/billing/docs/how-to/billing-access).
  142. rpc GetIamPolicy(google.iam.v1.GetIamPolicyRequest) returns (google.iam.v1.Policy) {
  143. option (google.api.http) = {
  144. get: "/v1/{resource=billingAccounts/*}:getIamPolicy"
  145. };
  146. option (google.api.method_signature) = "resource";
  147. }
  148. // Sets the access control policy for a billing account. Replaces any existing
  149. // policy.
  150. // The caller must have the `billing.accounts.setIamPolicy` permission on the
  151. // account, which is often given to billing account
  152. // [administrators](https://cloud.google.com/billing/docs/how-to/billing-access).
  153. rpc SetIamPolicy(google.iam.v1.SetIamPolicyRequest) returns (google.iam.v1.Policy) {
  154. option (google.api.http) = {
  155. post: "/v1/{resource=billingAccounts/*}:setIamPolicy"
  156. body: "*"
  157. };
  158. option (google.api.method_signature) = "resource,policy";
  159. }
  160. // Tests the access control policy for a billing account. This method takes
  161. // the resource and a set of permissions as input and returns the subset of
  162. // the input permissions that the caller is allowed for that resource.
  163. rpc TestIamPermissions(google.iam.v1.TestIamPermissionsRequest) returns (google.iam.v1.TestIamPermissionsResponse) {
  164. option (google.api.http) = {
  165. post: "/v1/{resource=billingAccounts/*}:testIamPermissions"
  166. body: "*"
  167. };
  168. option (google.api.method_signature) = "resource,permissions";
  169. }
  170. }
  171. // A billing account in [GCP Console](https://console.cloud.google.com/).
  172. // You can assign a billing account to one or more projects.
  173. message BillingAccount {
  174. // The resource name of the billing account. The resource name has the form
  175. // `billingAccounts/{billing_account_id}`. For example,
  176. // `billingAccounts/012345-567890-ABCDEF` would be the resource name for
  177. // billing account `012345-567890-ABCDEF`.
  178. string name = 1 [(google.api.resource_reference) = {
  179. type: "cloudbilling.googleapis.com/BillingAccount"
  180. }];
  181. // Output only. True if the billing account is open, and will therefore be charged for any
  182. // usage on associated projects. False if the billing account is closed, and
  183. // therefore projects associated with it will be unable to use paid services.
  184. bool open = 2 [(google.api.field_behavior) = OUTPUT_ONLY];
  185. // The display name given to the billing account, such as `My Billing
  186. // Account`. This name is displayed in the GCP Console.
  187. string display_name = 3;
  188. // If this account is a
  189. // [subaccount](https://cloud.google.com/billing/docs/concepts), then this
  190. // will be the resource name of the master billing account that it is being
  191. // resold through.
  192. // Otherwise this will be empty.
  193. string master_billing_account = 4;
  194. }
  195. // Encapsulation of billing information for a GCP Console project. A project
  196. // has at most one associated billing account at a time (but a billing account
  197. // can be assigned to multiple projects).
  198. message ProjectBillingInfo {
  199. // The resource name for the `ProjectBillingInfo`; has the form
  200. // `projects/{project_id}/billingInfo`. For example, the resource name for the
  201. // billing information for project `tokyo-rain-123` would be
  202. // `projects/tokyo-rain-123/billingInfo`. This field is read-only.
  203. string name = 1;
  204. // The ID of the project that this `ProjectBillingInfo` represents, such as
  205. // `tokyo-rain-123`. This is a convenience field so that you don't need to
  206. // parse the `name` field to obtain a project ID. This field is read-only.
  207. string project_id = 2;
  208. // The resource name of the billing account associated with the project, if
  209. // any. For example, `billingAccounts/012345-567890-ABCDEF`.
  210. string billing_account_name = 3;
  211. // True if the project is associated with an open billing account, to which
  212. // usage on the project is charged. False if the project is associated with a
  213. // closed billing account, or no billing account at all, and therefore cannot
  214. // use paid services. This field is read-only.
  215. bool billing_enabled = 4;
  216. }
  217. // Request message for `GetBillingAccount`.
  218. message GetBillingAccountRequest {
  219. // Required. The resource name of the billing account to retrieve. For example,
  220. // `billingAccounts/012345-567890-ABCDEF`.
  221. string name = 1 [
  222. (google.api.field_behavior) = REQUIRED,
  223. (google.api.resource_reference) = {
  224. type: "cloudbilling.googleapis.com/BillingAccount"
  225. }
  226. ];
  227. }
  228. // Request message for `ListBillingAccounts`.
  229. message ListBillingAccountsRequest {
  230. // Requested page size. The maximum page size is 100; this is also the
  231. // default.
  232. int32 page_size = 1;
  233. // A token identifying a page of results to return. This should be a
  234. // `next_page_token` value returned from a previous `ListBillingAccounts`
  235. // call. If unspecified, the first page of results is returned.
  236. string page_token = 2;
  237. // Options for how to filter the returned billing accounts.
  238. // Currently this only supports filtering for
  239. // [subaccounts](https://cloud.google.com/billing/docs/concepts) under a
  240. // single provided reseller billing account.
  241. // (e.g. "master_billing_account=billingAccounts/012345-678901-ABCDEF").
  242. // Boolean algebra and other fields are not currently supported.
  243. string filter = 3;
  244. }
  245. // Response message for `ListBillingAccounts`.
  246. message ListBillingAccountsResponse {
  247. // A list of billing accounts.
  248. repeated BillingAccount billing_accounts = 1;
  249. // A token to retrieve the next page of results. To retrieve the next page,
  250. // call `ListBillingAccounts` again with the `page_token` field set to this
  251. // value. This field is empty if there are no more results to retrieve.
  252. string next_page_token = 2;
  253. }
  254. // Request message for `CreateBillingAccount`.
  255. message CreateBillingAccountRequest {
  256. // Required. The billing account resource to create.
  257. // Currently CreateBillingAccount only supports subaccount creation, so
  258. // any created billing accounts must be under a provided master billing
  259. // account.
  260. BillingAccount billing_account = 1 [(google.api.field_behavior) = REQUIRED];
  261. }
  262. // Request message for `UpdateBillingAccount`.
  263. message UpdateBillingAccountRequest {
  264. // Required. The name of the billing account resource to be updated.
  265. string name = 1 [
  266. (google.api.field_behavior) = REQUIRED,
  267. (google.api.resource_reference) = {
  268. type: "cloudbilling.googleapis.com/BillingAccount"
  269. }
  270. ];
  271. // Required. The billing account resource to replace the resource on the server.
  272. BillingAccount account = 2 [(google.api.field_behavior) = REQUIRED];
  273. // The update mask applied to the resource.
  274. // Only "display_name" is currently supported.
  275. google.protobuf.FieldMask update_mask = 3;
  276. }
  277. // Request message for `ListProjectBillingInfo`.
  278. message ListProjectBillingInfoRequest {
  279. // Required. The resource name of the billing account associated with the projects that
  280. // you want to list. For example, `billingAccounts/012345-567890-ABCDEF`.
  281. string name = 1 [
  282. (google.api.field_behavior) = REQUIRED,
  283. (google.api.resource_reference) = {
  284. type: "cloudbilling.googleapis.com/BillingAccount"
  285. }
  286. ];
  287. // Requested page size. The maximum page size is 100; this is also the
  288. // default.
  289. int32 page_size = 2;
  290. // A token identifying a page of results to be returned. This should be a
  291. // `next_page_token` value returned from a previous `ListProjectBillingInfo`
  292. // call. If unspecified, the first page of results is returned.
  293. string page_token = 3;
  294. }
  295. // Request message for `ListProjectBillingInfoResponse`.
  296. message ListProjectBillingInfoResponse {
  297. // A list of `ProjectBillingInfo` resources representing the projects
  298. // associated with the billing account.
  299. repeated ProjectBillingInfo project_billing_info = 1;
  300. // A token to retrieve the next page of results. To retrieve the next page,
  301. // call `ListProjectBillingInfo` again with the `page_token` field set to this
  302. // value. This field is empty if there are no more results to retrieve.
  303. string next_page_token = 2;
  304. }
  305. // Request message for `GetProjectBillingInfo`.
  306. message GetProjectBillingInfoRequest {
  307. // Required. The resource name of the project for which billing information is
  308. // retrieved. For example, `projects/tokyo-rain-123`.
  309. string name = 1 [(google.api.field_behavior) = REQUIRED];
  310. }
  311. // Request message for `UpdateProjectBillingInfo`.
  312. message UpdateProjectBillingInfoRequest {
  313. // Required. The resource name of the project associated with the billing information
  314. // that you want to update. For example, `projects/tokyo-rain-123`.
  315. string name = 1 [(google.api.field_behavior) = REQUIRED];
  316. // The new billing information for the project. Read-only fields are ignored;
  317. // thus, you can leave empty all fields except `billing_account_name`.
  318. ProjectBillingInfo project_billing_info = 2;
  319. }