domains.proto 37 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885886887888889890891892893894895896897898899900901902903904905906907908909910911912913914915916917918919920921922923924925926927928929930931932933934935936937938939940941942943944945946947948949950951952953954955956957958959960961962963964965966967968969970971972973974975976977978979980981982983
  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.domains.v1alpha2;
  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/longrunning/operations.proto";
  21. import "google/protobuf/field_mask.proto";
  22. import "google/protobuf/timestamp.proto";
  23. import "google/type/money.proto";
  24. import "google/type/postal_address.proto";
  25. option go_package = "google.golang.org/genproto/googleapis/cloud/domains/v1alpha2;domains";
  26. option java_multiple_files = true;
  27. option java_outer_classname = "DomainsProto";
  28. option java_package = "com.google.cloud.domains.v1alpha2";
  29. // The Cloud Domains API enables management and configuration of domain names.
  30. service Domains {
  31. option (google.api.default_host) = "domains.googleapis.com";
  32. option (google.api.oauth_scopes) = "https://www.googleapis.com/auth/cloud-platform";
  33. // Searches for available domain names similar to the provided query.
  34. //
  35. // Availability results from this method are approximate; call
  36. // `RetrieveRegisterParameters` on a domain before registering to confirm
  37. // availability.
  38. rpc SearchDomains(SearchDomainsRequest) returns (SearchDomainsResponse) {
  39. option (google.api.http) = {
  40. get: "/v1alpha2/{location=projects/*/locations/*}/registrations:searchDomains"
  41. };
  42. option (google.api.method_signature) = "location,query";
  43. }
  44. // Gets parameters needed to register a new domain name, including price and
  45. // up-to-date availability. Use the returned values to call `RegisterDomain`.
  46. rpc RetrieveRegisterParameters(RetrieveRegisterParametersRequest) returns (RetrieveRegisterParametersResponse) {
  47. option (google.api.http) = {
  48. get: "/v1alpha2/{location=projects/*/locations/*}/registrations:retrieveRegisterParameters"
  49. };
  50. option (google.api.method_signature) = "location,domain_name";
  51. }
  52. // Registers a new domain name and creates a corresponding `Registration`
  53. // resource.
  54. //
  55. // Call `RetrieveRegisterParameters` first to check availability of the domain
  56. // name and determine parameters like price that are needed to build a call to
  57. // this method.
  58. //
  59. // A successful call creates a `Registration` resource in state
  60. // `REGISTRATION_PENDING`, which resolves to `ACTIVE` within 1-2
  61. // minutes, indicating that the domain was successfully registered. If the
  62. // resource ends up in state `REGISTRATION_FAILED`, it indicates that the
  63. // domain was not registered successfully, and you can safely delete the
  64. // resource and retry registration.
  65. rpc RegisterDomain(RegisterDomainRequest) returns (google.longrunning.Operation) {
  66. option (google.api.http) = {
  67. post: "/v1alpha2/{parent=projects/*/locations/*}/registrations:register"
  68. body: "*"
  69. };
  70. option (google.api.method_signature) = "parent,registration,yearly_price";
  71. option (google.longrunning.operation_info) = {
  72. response_type: "Registration"
  73. metadata_type: "OperationMetadata"
  74. };
  75. }
  76. // Lists the `Registration` resources in a project.
  77. rpc ListRegistrations(ListRegistrationsRequest) returns (ListRegistrationsResponse) {
  78. option (google.api.http) = {
  79. get: "/v1alpha2/{parent=projects/*/locations/*}/registrations"
  80. };
  81. option (google.api.method_signature) = "parent";
  82. }
  83. // Gets the details of a `Registration` resource.
  84. rpc GetRegistration(GetRegistrationRequest) returns (Registration) {
  85. option (google.api.http) = {
  86. get: "/v1alpha2/{name=projects/*/locations/*/registrations/*}"
  87. };
  88. option (google.api.method_signature) = "name";
  89. }
  90. // Updates select fields of a `Registration` resource, notably `labels`. To
  91. // update other fields, use the appropriate custom update method:
  92. //
  93. // * To update management settings, see `ConfigureManagementSettings`
  94. // * To update DNS configuration, see `ConfigureDnsSettings`
  95. // * To update contact information, see `ConfigureContactSettings`
  96. rpc UpdateRegistration(UpdateRegistrationRequest) returns (google.longrunning.Operation) {
  97. option (google.api.http) = {
  98. patch: "/v1alpha2/{registration.name=projects/*/locations/*/registrations/*}"
  99. body: "registration"
  100. };
  101. option (google.api.method_signature) = "registration,update_mask";
  102. option (google.longrunning.operation_info) = {
  103. response_type: "Registration"
  104. metadata_type: "OperationMetadata"
  105. };
  106. }
  107. // Updates a `Registration`'s management settings.
  108. rpc ConfigureManagementSettings(ConfigureManagementSettingsRequest) returns (google.longrunning.Operation) {
  109. option (google.api.http) = {
  110. post: "/v1alpha2/{registration=projects/*/locations/*/registrations/*}:configureManagementSettings"
  111. body: "*"
  112. };
  113. option (google.api.method_signature) = "registration,management_settings,update_mask";
  114. option (google.longrunning.operation_info) = {
  115. response_type: "Registration"
  116. metadata_type: "OperationMetadata"
  117. };
  118. }
  119. // Updates a `Registration`'s DNS settings.
  120. rpc ConfigureDnsSettings(ConfigureDnsSettingsRequest) returns (google.longrunning.Operation) {
  121. option (google.api.http) = {
  122. post: "/v1alpha2/{registration=projects/*/locations/*/registrations/*}:configureDnsSettings"
  123. body: "*"
  124. };
  125. option (google.api.method_signature) = "registration,dns_settings,update_mask";
  126. option (google.longrunning.operation_info) = {
  127. response_type: "Registration"
  128. metadata_type: "OperationMetadata"
  129. };
  130. }
  131. // Updates a `Registration`'s contact settings. Some changes require
  132. // confirmation by the domain's registrant contact .
  133. rpc ConfigureContactSettings(ConfigureContactSettingsRequest) returns (google.longrunning.Operation) {
  134. option (google.api.http) = {
  135. post: "/v1alpha2/{registration=projects/*/locations/*/registrations/*}:configureContactSettings"
  136. body: "*"
  137. };
  138. option (google.api.method_signature) = "registration,contact_settings,update_mask";
  139. option (google.longrunning.operation_info) = {
  140. response_type: "Registration"
  141. metadata_type: "OperationMetadata"
  142. };
  143. }
  144. // Exports a `Registration` that you no longer want to use with
  145. // Cloud Domains. You can continue to use the domain in
  146. // [Google Domains](https://domains.google/) until it expires.
  147. //
  148. // If the export is successful:
  149. //
  150. // * The resource's `state` becomes `EXPORTED`, meaning that it is no longer
  151. // managed by Cloud Domains
  152. // * Because individual users can own domains in Google Domains, the calling
  153. // user becomes the domain's sole owner. Permissions for the domain are
  154. // subsequently managed in Google Domains.
  155. // * Without further action, the domain does not renew automatically.
  156. // The new owner can set up billing in Google Domains to renew the domain
  157. // if needed.
  158. rpc ExportRegistration(ExportRegistrationRequest) returns (google.longrunning.Operation) {
  159. option (google.api.http) = {
  160. post: "/v1alpha2/{name=projects/*/locations/*/registrations/*}:export"
  161. body: "*"
  162. };
  163. option (google.api.method_signature) = "name";
  164. option (google.longrunning.operation_info) = {
  165. response_type: "Registration"
  166. metadata_type: "OperationMetadata"
  167. };
  168. }
  169. // Deletes a `Registration` resource.
  170. //
  171. // This method only works on resources in one of the following states:
  172. //
  173. // * `state` is `EXPORTED` with `expire_time` in the past
  174. // * `state` is `REGISTRATION_FAILED`
  175. rpc DeleteRegistration(DeleteRegistrationRequest) returns (google.longrunning.Operation) {
  176. option (google.api.http) = {
  177. delete: "/v1alpha2/{name=projects/*/locations/*/registrations/*}"
  178. };
  179. option (google.api.method_signature) = "name";
  180. option (google.longrunning.operation_info) = {
  181. response_type: "google.protobuf.Empty"
  182. metadata_type: "OperationMetadata"
  183. };
  184. }
  185. // Gets the authorization code of the `Registration` for the purpose of
  186. // transferring the domain to another registrar.
  187. //
  188. // You can call this method only after 60 days have elapsed since the initial
  189. // domain registration.
  190. rpc RetrieveAuthorizationCode(RetrieveAuthorizationCodeRequest) returns (AuthorizationCode) {
  191. option (google.api.http) = {
  192. get: "/v1alpha2/{registration=projects/*/locations/*/registrations/*}:retrieveAuthorizationCode"
  193. };
  194. option (google.api.method_signature) = "registration";
  195. }
  196. // Resets the authorization code of the `Registration` to a new random string.
  197. //
  198. // You can call this method only after 60 days have elapsed since the initial
  199. // domain registration.
  200. rpc ResetAuthorizationCode(ResetAuthorizationCodeRequest) returns (AuthorizationCode) {
  201. option (google.api.http) = {
  202. post: "/v1alpha2/{registration=projects/*/locations/*/registrations/*}:resetAuthorizationCode"
  203. body: "*"
  204. };
  205. option (google.api.method_signature) = "registration";
  206. }
  207. }
  208. // The `Registration` resource facilitates managing and configuring domain name
  209. // registrations.
  210. //
  211. //
  212. // To create a new `Registration` resource, find a suitable domain name by
  213. // calling the `SearchDomains` method with a query to see available domain name
  214. // options. After choosing a name, call `RetrieveRegisterParameters` to
  215. // ensure availability and obtain information like pricing, which is needed to
  216. // build a call to `RegisterDomain`.
  217. //
  218. message Registration {
  219. option (google.api.resource) = {
  220. type: "domains.googleapis.com/Registration"
  221. pattern: "projects/{project}/locations/{location}/registrations/{registration}"
  222. };
  223. // Possible states of a `Registration`.
  224. enum State {
  225. // The state is undefined.
  226. STATE_UNSPECIFIED = 0;
  227. // The domain is being registered.
  228. REGISTRATION_PENDING = 1;
  229. // The domain registration failed. You can delete resources in this state
  230. // to allow registration to be retried.
  231. REGISTRATION_FAILED = 2;
  232. // The domain is registered and operational. The domain renews automatically
  233. // as long as it remains in this state.
  234. ACTIVE = 6;
  235. // The domain is suspended and inoperative. For more details, see the
  236. // `issues` field.
  237. SUSPENDED = 7;
  238. // The domain has been exported from Cloud Domains to
  239. // [Google Domains](https://domains.google/). You can no longer update it
  240. // with this API, and information shown about it may be stale. Without further action, domains in this
  241. // state expire at their `expire_time`. You can delete the resource
  242. // after the `expire_time` has passed.
  243. EXPORTED = 8;
  244. }
  245. // Possible issues with a `Registration` that require attention.
  246. enum Issue {
  247. // The issue is undefined.
  248. ISSUE_UNSPECIFIED = 0;
  249. // Contact the Cloud Support team to resolve a problem with this domain.
  250. CONTACT_SUPPORT = 1;
  251. // [ICANN](https://icann.org/) requires verification of the email address
  252. // in the `Registration`'s `contact_settings.registrant_contact` field. To
  253. // verify the email address, follow the
  254. // instructions in the email the `registrant_contact` receives following
  255. // registration. If you do not complete email verification within
  256. // 14 days of registration, the domain is suspended. To resend the
  257. // verification email, call ConfigureContactSettings and provide the current
  258. // `registrant_contact.email`.
  259. UNVERIFIED_EMAIL = 2;
  260. }
  261. // Output only. Name of the `Registration` resource, in the format
  262. // `projects/*/locations/*/registrations/<domain_name>`.
  263. string name = 1 [(google.api.field_behavior) = OUTPUT_ONLY];
  264. // Required. Immutable. The domain name. Unicode domain names must be expressed in Punycode format.
  265. string domain_name = 2 [
  266. (google.api.field_behavior) = REQUIRED,
  267. (google.api.field_behavior) = IMMUTABLE
  268. ];
  269. // Output only. The creation timestamp of the `Registration` resource.
  270. google.protobuf.Timestamp create_time = 3 [(google.api.field_behavior) = OUTPUT_ONLY];
  271. // Output only. The expiration timestamp of the `Registration`.
  272. google.protobuf.Timestamp expire_time = 6 [(google.api.field_behavior) = OUTPUT_ONLY];
  273. // Output only. The state of the `Registration`
  274. State state = 7 [(google.api.field_behavior) = OUTPUT_ONLY];
  275. // Output only. The set of issues with the `Registration` that require attention.
  276. repeated Issue issues = 8 [(google.api.field_behavior) = OUTPUT_ONLY];
  277. // Set of labels associated with the `Registration`.
  278. map<string, string> labels = 9;
  279. // Settings for management of the `Registration`, including renewal, billing,
  280. // and transfer. You cannot update these with the `UpdateRegistration`
  281. // method. To update these settings, use the `ConfigureManagementSettings`
  282. // method.
  283. ManagementSettings management_settings = 10;
  284. // Settings controlling the DNS configuration of the `Registration`. You
  285. // cannot update these with the `UpdateRegistration` method. To update these
  286. // settings, use the `ConfigureDnsSettings` method.
  287. DnsSettings dns_settings = 11;
  288. // Required. Settings for contact information linked to the `Registration`. You cannot
  289. // update these with the `UpdateRegistration` method. To update these
  290. // settings, use the `ConfigureContactSettings` method.
  291. ContactSettings contact_settings = 12 [(google.api.field_behavior) = REQUIRED];
  292. // Output only. Pending contact settings for the `Registration`. Updates to the
  293. // `contact_settings` field that change its `registrant_contact` or `privacy`
  294. // fields require email confirmation by the `registrant_contact`
  295. // before taking effect. This field is set only if there are pending updates
  296. // to the `contact_settings` that have not yet been confirmed. To confirm the
  297. // changes, the `registrant_contact` must follow the instructions in the
  298. // email they receive.
  299. ContactSettings pending_contact_settings = 13 [(google.api.field_behavior) = OUTPUT_ONLY];
  300. // Output only. Set of options for the `contact_settings.privacy` field that this
  301. // `Registration` supports.
  302. repeated ContactPrivacy supported_privacy = 14 [(google.api.field_behavior) = OUTPUT_ONLY];
  303. }
  304. // Defines renewal, billing, and transfer settings for a `Registration`.
  305. message ManagementSettings {
  306. // Defines how the `Registration` is renewed.
  307. enum RenewalMethod {
  308. // The renewal method is undefined.
  309. RENEWAL_METHOD_UNSPECIFIED = 0;
  310. // The domain is automatically renewed each year .
  311. //
  312. // To disable automatic renewals, export the domain by calling
  313. // `ExportRegistration` .
  314. AUTOMATIC_RENEWAL = 1;
  315. // The domain must be explicitly renewed each year before its
  316. // `expire_time`. This option is only available when the `Registration`
  317. // is in state `EXPORTED`.
  318. //
  319. // To manage the domain's current billing and
  320. // renewal settings, go to [Google Domains](https://domains.google/).
  321. MANUAL_RENEWAL = 2;
  322. }
  323. // Output only. The renewal method for this `Registration`.
  324. RenewalMethod renewal_method = 3 [(google.api.field_behavior) = OUTPUT_ONLY];
  325. // Controls whether the domain can be transferred to another registrar.
  326. TransferLockState transfer_lock_state = 4;
  327. }
  328. // Defines the DNS configuration of a `Registration`, including name servers,
  329. // DNSSEC, and glue records.
  330. message DnsSettings {
  331. // Configuration for an arbitrary DNS provider.
  332. message CustomDns {
  333. // Required. A list of name servers that store the DNS zone for this domain. Each name
  334. // server is a domain name, with Unicode domain names expressed in
  335. // Punycode format.
  336. repeated string name_servers = 1 [(google.api.field_behavior) = REQUIRED];
  337. // The list of DS records for this domain, which are used to enable DNSSEC.
  338. // The domain's DNS provider can provide the values to set here. If this
  339. // field is empty, DNSSEC is disabled.
  340. repeated DsRecord ds_records = 2;
  341. }
  342. // Configuration for using the free DNS zone provided by Google Domains as a
  343. // `Registration`'s `dns_provider`. You cannot configure the DNS zone itself
  344. // using the API. To configure the DNS zone, go to
  345. // [Google Domains](https://domains.google/).
  346. message GoogleDomainsDns {
  347. // Output only. A list of name servers that store the DNS zone for this domain. Each name
  348. // server is a domain name, with Unicode domain names expressed in
  349. // Punycode format. This field is automatically populated with the name
  350. // servers assigned to the Google Domains DNS zone.
  351. repeated string name_servers = 1 [(google.api.field_behavior) = OUTPUT_ONLY];
  352. // Required. The state of DS records for this domain. Used to enable or disable
  353. // automatic DNSSEC.
  354. DsState ds_state = 2 [(google.api.field_behavior) = REQUIRED];
  355. // Output only. The list of DS records published for this domain. The list is
  356. // automatically populated when `ds_state` is `DS_RECORDS_PUBLISHED`,
  357. // otherwise it remains empty.
  358. repeated DsRecord ds_records = 3 [(google.api.field_behavior) = OUTPUT_ONLY];
  359. }
  360. // Defines a Delegation Signer (DS) record, which is needed to enable DNSSEC
  361. // for a domain. It contains a digest (hash) of a DNSKEY record that must be
  362. // present in the domain's DNS zone.
  363. message DsRecord {
  364. // List of algorithms used to create a DNSKEY. Certain
  365. // algorithms are not supported for particular domains.
  366. enum Algorithm {
  367. // The algorithm is unspecified.
  368. ALGORITHM_UNSPECIFIED = 0;
  369. // DSA/SHA1. Not recommended for new deployments.
  370. DSA = 3;
  371. // ECC. Not recommended for new deployments.
  372. ECC = 4;
  373. // RSA/SHA-1. Not recommended for new deployments.
  374. RSASHA1 = 5;
  375. // DSA-NSEC3-SHA1. Not recommended for new deployments.
  376. DSANSEC3SHA1 = 6;
  377. // RSA/SHA1-NSEC3-SHA1. Not recommended for new deployments.
  378. RSASHA1NSEC3SHA1 = 7;
  379. // RSA/SHA-256.
  380. RSASHA256 = 8;
  381. // RSA/SHA-512.
  382. RSASHA512 = 10;
  383. // GOST R 34.10-2001.
  384. ECCGOST = 12;
  385. // ECDSA Curve P-256 with SHA-256.
  386. ECDSAP256SHA256 = 13;
  387. // ECDSA Curve P-384 with SHA-384.
  388. ECDSAP384SHA384 = 14;
  389. // Ed25519.
  390. ED25519 = 15;
  391. // Ed448.
  392. ED448 = 16;
  393. }
  394. // List of hash functions that may have been used to generate a digest of a
  395. // DNSKEY.
  396. enum DigestType {
  397. // The DigestType is unspecified.
  398. DIGEST_TYPE_UNSPECIFIED = 0;
  399. // SHA-1. Not recommended for new deployments.
  400. SHA1 = 1;
  401. // SHA-256.
  402. SHA256 = 2;
  403. // GOST R 34.11-94.
  404. GOST3411 = 3;
  405. // SHA-384.
  406. SHA384 = 4;
  407. }
  408. // The key tag of the record. Must be set in range 0 -- 65535.
  409. int32 key_tag = 1;
  410. // The algorithm used to generate the referenced DNSKEY.
  411. Algorithm algorithm = 2;
  412. // The hash function used to generate the digest of the referenced DNSKEY.
  413. DigestType digest_type = 3;
  414. // The digest generated from the referenced DNSKEY.
  415. string digest = 4;
  416. }
  417. // Defines a host on your domain that is a DNS name server for your domain
  418. // and/or other domains. Glue records are a way of making the IP address of a
  419. // name server known, even when it serves DNS queries for its parent domain.
  420. // For example, when `ns.example.com` is a name server for `example.com`, the
  421. // host `ns.example.com` must have a glue record to break the circular DNS
  422. // reference.
  423. message GlueRecord {
  424. // Required. Domain name of the host in Punycode format.
  425. string host_name = 1 [(google.api.field_behavior) = REQUIRED];
  426. // List of IPv4 addresses corresponding to this host in the standard decimal
  427. // format (e.g. `198.51.100.1`). At least one of `ipv4_address` and
  428. // `ipv6_address` must be set.
  429. repeated string ipv4_addresses = 2;
  430. // List of IPv6 addresses corresponding to this host in the standard
  431. // hexadecimal format (e.g. `2001:db8::`). At least one of
  432. // `ipv4_address` and `ipv6_address` must be set.
  433. repeated string ipv6_addresses = 3;
  434. }
  435. // The publication state of DS records for a `Registration`.
  436. enum DsState {
  437. // DS state is unspecified.
  438. DS_STATE_UNSPECIFIED = 0;
  439. // DNSSEC is disabled for this domain. No DS records for this domain are
  440. // published in the parent DNS zone.
  441. DS_RECORDS_UNPUBLISHED = 1;
  442. // DNSSEC is enabled for this domain. Appropriate DS records for this domain
  443. // are published in the parent DNS zone. This option is valid only if the
  444. // DNS zone referenced in the `Registration`'s `dns_provider` field is
  445. // already DNSSEC-signed.
  446. DS_RECORDS_PUBLISHED = 2;
  447. }
  448. // The DNS provider of the registration.
  449. oneof dns_provider {
  450. // An arbitrary DNS provider identified by its name servers.
  451. CustomDns custom_dns = 1;
  452. // The free DNS zone provided by
  453. // [Google Domains](https://domains.google/).
  454. GoogleDomainsDns google_domains_dns = 2;
  455. }
  456. // The list of glue records for this `Registration`. Commonly empty.
  457. repeated GlueRecord glue_records = 4;
  458. }
  459. // Defines the contact information associated with a `Registration`.
  460. //
  461. // [ICANN](https://icann.org/) requires all domain names to have associated
  462. // contact information. The `registrant_contact` is considered the
  463. // domain's legal owner, and often the other contacts are identical.
  464. message ContactSettings {
  465. // Details required for a contact associated with a `Registration`.
  466. message Contact {
  467. // Required. Postal address of the contact.
  468. google.type.PostalAddress postal_address = 1 [(google.api.field_behavior) = REQUIRED];
  469. // Required. Email address of the contact.
  470. string email = 2 [(google.api.field_behavior) = REQUIRED];
  471. // Required. Phone number of the contact in international format. For example,
  472. // `"+1-800-555-0123"`.
  473. string phone_number = 3 [(google.api.field_behavior) = REQUIRED];
  474. // Fax number of the contact in international format. For example,
  475. // `"+1-800-555-0123"`.
  476. string fax_number = 4;
  477. }
  478. // Required. Privacy setting for the contacts associated with the `Registration`.
  479. ContactPrivacy privacy = 1 [(google.api.field_behavior) = REQUIRED];
  480. // Required. The registrant contact for the `Registration`.
  481. //
  482. // *Caution: Anyone with access to this email address, phone number,
  483. // and/or postal address can take control of the domain.*
  484. //
  485. // *Warning: For new `Registration`s, the registrant will receive an email
  486. // confirmation that they must complete within 14 days to avoid domain
  487. // suspension.*
  488. Contact registrant_contact = 2 [(google.api.field_behavior) = REQUIRED];
  489. // Required. The administrative contact for the `Registration`.
  490. Contact admin_contact = 3 [(google.api.field_behavior) = REQUIRED];
  491. // Required. The technical contact for the `Registration`.
  492. Contact technical_contact = 4 [(google.api.field_behavior) = REQUIRED];
  493. }
  494. // Request for the `SearchDomains` method.
  495. message SearchDomainsRequest {
  496. // Required. String used to search for available domain names.
  497. string query = 1 [(google.api.field_behavior) = REQUIRED];
  498. // Required. The location. Must be in the format `projects/*/locations/*`.
  499. string location = 2 [
  500. (google.api.field_behavior) = REQUIRED,
  501. (google.api.resource_reference) = {
  502. type: "locations.googleapis.com/Location"
  503. }
  504. ];
  505. }
  506. // Response for the `SearchDomains` method.
  507. message SearchDomainsResponse {
  508. // Results of the domain name search.
  509. repeated RegisterParameters register_parameters = 1;
  510. }
  511. // Request for the `RetrieveRegisterParameters` method.
  512. message RetrieveRegisterParametersRequest {
  513. // Required. The domain name. Unicode domain names must be expressed in Punycode format.
  514. string domain_name = 1 [(google.api.field_behavior) = REQUIRED];
  515. // Required. The location. Must be in the format `projects/*/locations/*`.
  516. string location = 2 [
  517. (google.api.field_behavior) = REQUIRED,
  518. (google.api.resource_reference) = {
  519. type: "locations.googleapis.com/Location"
  520. }
  521. ];
  522. }
  523. // Response for the `RetrieveRegisterParameters` method.
  524. message RetrieveRegisterParametersResponse {
  525. // Parameters to use when calling the `RegisterDomain` method.
  526. RegisterParameters register_parameters = 1;
  527. }
  528. // Request for the `RegisterDomain` method.
  529. message RegisterDomainRequest {
  530. // Required. The parent resource of the `Registration`. Must be in the
  531. // format `projects/*/locations/*`.
  532. string parent = 1 [
  533. (google.api.field_behavior) = REQUIRED,
  534. (google.api.resource_reference) = {
  535. type: "locations.googleapis.com/Location"
  536. }
  537. ];
  538. // Required. The complete `Registration` resource to be created.
  539. Registration registration = 2 [(google.api.field_behavior) = REQUIRED];
  540. // The list of domain notices that you acknowledge. Call
  541. // `RetrieveRegisterParameters` to see the notices that need acknowledgement.
  542. repeated DomainNotice domain_notices = 3;
  543. // The list of contact notices that the caller acknowledges. The notices
  544. // required here depend on the values specified in
  545. // `registration.contact_settings`.
  546. repeated ContactNotice contact_notices = 4;
  547. // Required. Yearly price to register or renew the domain.
  548. // The value that should be put here can be obtained from
  549. // RetrieveRegisterParameters or SearchDomains calls.
  550. google.type.Money yearly_price = 5 [(google.api.field_behavior) = REQUIRED];
  551. // When true, only validation will be performed, without actually registering
  552. // the domain. Follows:
  553. // https://cloud.google.com/apis/design/design_patterns#request_validation
  554. bool validate_only = 6;
  555. }
  556. // Request for the `ListRegistrations` method.
  557. message ListRegistrationsRequest {
  558. // Required. The project and location from which to list `Registration`s, specified in
  559. // the format `projects/*/locations/*`.
  560. string parent = 1 [
  561. (google.api.field_behavior) = REQUIRED,
  562. (google.api.resource_reference) = {
  563. type: "locations.googleapis.com/Location"
  564. }
  565. ];
  566. // Maximum number of results to return.
  567. int32 page_size = 2;
  568. // When set to the `next_page_token` from a prior response, provides the next
  569. // page of results.
  570. string page_token = 3;
  571. // Filter expression to restrict the `Registration`s returned.
  572. //
  573. // The expression must specify the field name, a comparison operator, and the
  574. // value that you want to use for filtering. The value must be a string, a
  575. // number, a boolean, or an enum value. The comparison operator should be one
  576. // of =, !=, >, <, >=, <=, or : for prefix or wildcard matches.
  577. //
  578. // For example, to filter to a specific domain name, use an expression like
  579. // `domainName="example.com"`. You can also check for the existence of a
  580. // field; for example, to find domains using custom DNS settings, use an
  581. // expression like `dnsSettings.customDns:*`.
  582. //
  583. // You can also create compound filters by combining expressions with the
  584. // `AND` and `OR` operators. For example, to find domains that are suspended
  585. // or have specific issues flagged, use an expression like
  586. // `(state=SUSPENDED) OR (issue:*)`.
  587. string filter = 4;
  588. }
  589. // Response for the `ListRegistrations` method.
  590. message ListRegistrationsResponse {
  591. // A list of `Registration`s.
  592. repeated Registration registrations = 1;
  593. // When present, there are more results to retrieve. Set `page_token` to this
  594. // value on a subsequent call to get the next page of results.
  595. string next_page_token = 2;
  596. }
  597. // Request for the `GetRegistration` method.
  598. message GetRegistrationRequest {
  599. // Required. The name of the `Registration` to get, in the format
  600. // `projects/*/locations/*/registrations/*`.
  601. string name = 1 [
  602. (google.api.field_behavior) = REQUIRED,
  603. (google.api.resource_reference) = {
  604. type: "domains.googleapis.com/Registration"
  605. }
  606. ];
  607. }
  608. // Request for the `UpdateRegistration` method.
  609. message UpdateRegistrationRequest {
  610. // Fields of the `Registration` to update.
  611. Registration registration = 1;
  612. // Required. The field mask describing which fields to update as a comma-separated list.
  613. // For example, if only the labels are being updated, the `update_mask` would
  614. // be `"labels"`.
  615. google.protobuf.FieldMask update_mask = 2 [(google.api.field_behavior) = REQUIRED];
  616. }
  617. // Request for the `ConfigureManagementSettings` method.
  618. message ConfigureManagementSettingsRequest {
  619. // Required. The name of the `Registration` whose management settings are being updated,
  620. // in the format `projects/*/locations/*/registrations/*`.
  621. string registration = 1 [
  622. (google.api.field_behavior) = REQUIRED,
  623. (google.api.resource_reference) = {
  624. type: "domains.googleapis.com/Registration"
  625. }
  626. ];
  627. // Fields of the `ManagementSettings` to update.
  628. ManagementSettings management_settings = 2;
  629. // Required. The field mask describing which fields to update as a comma-separated list.
  630. // For example, if only the transfer lock is being updated, the `update_mask`
  631. // would be `"transfer_lock_state"`.
  632. google.protobuf.FieldMask update_mask = 3 [(google.api.field_behavior) = REQUIRED];
  633. }
  634. // Request for the `ConfigureDnsSettings` method.
  635. message ConfigureDnsSettingsRequest {
  636. // Required. The name of the `Registration` whose DNS settings are being updated,
  637. // in the format `projects/*/locations/*/registrations/*`.
  638. string registration = 1 [
  639. (google.api.field_behavior) = REQUIRED,
  640. (google.api.resource_reference) = {
  641. type: "domains.googleapis.com/Registration"
  642. }
  643. ];
  644. // Fields of the `DnsSettings` to update.
  645. DnsSettings dns_settings = 2;
  646. // Required. The field mask describing which fields to update as a comma-separated list.
  647. // For example, if only the name servers are being updated for an existing
  648. // Custom DNS configuration, the `update_mask` would be
  649. // `"custom_dns.name_servers"`.
  650. //
  651. // When changing the DNS provider from one type to another, pass the new
  652. // provider's field name as part of the field mask. For example, when changing
  653. // from a Google Domains DNS configuration to a Custom DNS configuration, the
  654. // `update_mask` would be `"custom_dns"`. //
  655. google.protobuf.FieldMask update_mask = 3 [(google.api.field_behavior) = REQUIRED];
  656. // Validate the request without actually updating the DNS settings.
  657. bool validate_only = 4;
  658. }
  659. // Request for the `ConfigureContactSettings` method.
  660. message ConfigureContactSettingsRequest {
  661. // Required. The name of the `Registration` whose contact settings are being updated,
  662. // in the format `projects/*/locations/*/registrations/*`.
  663. string registration = 1 [
  664. (google.api.field_behavior) = REQUIRED,
  665. (google.api.resource_reference) = {
  666. type: "domains.googleapis.com/Registration"
  667. }
  668. ];
  669. // Fields of the `ContactSettings` to update.
  670. ContactSettings contact_settings = 2;
  671. // Required. The field mask describing which fields to update as a comma-separated list.
  672. // For example, if only the registrant contact is being updated, the
  673. // `update_mask` would be `"registrant_contact"`.
  674. google.protobuf.FieldMask update_mask = 3 [(google.api.field_behavior) = REQUIRED];
  675. // The list of contact notices that the caller acknowledges. The notices
  676. // required here depend on the values specified in `contact_settings`.
  677. repeated ContactNotice contact_notices = 4;
  678. // Validate the request without actually updating the contact settings.
  679. bool validate_only = 5;
  680. }
  681. // Request for the `ExportRegistration` method.
  682. message ExportRegistrationRequest {
  683. // Required. The name of the `Registration` to export,
  684. // in the format `projects/*/locations/*/registrations/*`.
  685. string name = 1 [
  686. (google.api.field_behavior) = REQUIRED,
  687. (google.api.resource_reference) = {
  688. type: "domains.googleapis.com/Registration"
  689. }
  690. ];
  691. }
  692. // Request for the `DeleteRegistration` method.
  693. message DeleteRegistrationRequest {
  694. // Required. The name of the `Registration` to delete,
  695. // in the format `projects/*/locations/*/registrations/*`.
  696. string name = 1 [
  697. (google.api.field_behavior) = REQUIRED,
  698. (google.api.resource_reference) = {
  699. type: "domains.googleapis.com/Registration"
  700. }
  701. ];
  702. }
  703. // Request for the `RetrieveAuthorizationCode` method.
  704. message RetrieveAuthorizationCodeRequest {
  705. // Required. The name of the `Registration` whose authorization code is being retrieved,
  706. // in the format `projects/*/locations/*/registrations/*`.
  707. string registration = 1 [
  708. (google.api.field_behavior) = REQUIRED,
  709. (google.api.resource_reference) = {
  710. type: "domains.googleapis.com/Registration"
  711. }
  712. ];
  713. }
  714. // Request for the `ResetAuthorizationCode` method.
  715. message ResetAuthorizationCodeRequest {
  716. // Required. The name of the `Registration` whose authorization code is being reset,
  717. // in the format `projects/*/locations/*/registrations/*`.
  718. string registration = 1 [
  719. (google.api.field_behavior) = REQUIRED,
  720. (google.api.resource_reference) = {
  721. type: "domains.googleapis.com/Registration"
  722. }
  723. ];
  724. }
  725. // Parameters required to register a new domain.
  726. message RegisterParameters {
  727. // Possible availability states of a domain name.
  728. enum Availability {
  729. // The availability is unspecified.
  730. AVAILABILITY_UNSPECIFIED = 0;
  731. // The domain is available for registration.
  732. AVAILABLE = 1;
  733. // The domain is not available for registration. Generally this means it is
  734. // already registered to another party.
  735. UNAVAILABLE = 2;
  736. // The domain is not currently supported by Cloud Domains, but may
  737. // be available elsewhere.
  738. UNSUPPORTED = 3;
  739. // Cloud Domains is unable to determine domain availability, generally
  740. // due to system maintenance at the domain name registry.
  741. UNKNOWN = 4;
  742. }
  743. // The domain name. Unicode domain names are expressed in Punycode format.
  744. string domain_name = 1;
  745. // Indicates whether the domain is available for registration. This value is
  746. // accurate when obtained by calling `RetrieveRegisterParameters`, but is
  747. // approximate when obtained by calling `SearchDomains`.
  748. Availability availability = 2;
  749. // Contact privacy options that the domain supports.
  750. repeated ContactPrivacy supported_privacy = 3;
  751. // Notices about special properties of the domain.
  752. repeated DomainNotice domain_notices = 4;
  753. // Price to register or renew the domain for one year.
  754. google.type.Money yearly_price = 5;
  755. }
  756. // Defines an authorization code.
  757. message AuthorizationCode {
  758. // The Authorization Code in ASCII. It can be used to transfer the domain
  759. // to or from another registrar.
  760. string code = 1;
  761. }
  762. // Represents the metadata of the long-running operation. Output only.
  763. message OperationMetadata {
  764. // The time the operation was created.
  765. google.protobuf.Timestamp create_time = 1;
  766. // The time the operation finished running.
  767. google.protobuf.Timestamp end_time = 2;
  768. // Server-defined resource path for the target of the operation.
  769. string target = 3;
  770. // Name of the verb executed by the operation.
  771. string verb = 4;
  772. // Human-readable status of the operation, if any.
  773. string status_detail = 5;
  774. // API version used to start the operation.
  775. string api_version = 6;
  776. }
  777. // Defines a set of possible contact privacy settings for a `Registration`.
  778. //
  779. // [ICANN](https://icann.org/) maintains the WHOIS database, a publicly
  780. // accessible mapping from domain name to contact information, and requires that
  781. // each domain name have an entry. Choose from these options to control how much
  782. // information in your `ContactSettings` is published.
  783. enum ContactPrivacy {
  784. // The contact privacy settings are undefined.
  785. CONTACT_PRIVACY_UNSPECIFIED = 0;
  786. // All the data from `ContactSettings` is publicly available. When setting
  787. // this option, you must also provide a
  788. // `PUBLIC_CONTACT_DATA_ACKNOWLEDGEMENT` in the `contact_notices` field of the
  789. // request.
  790. PUBLIC_CONTACT_DATA = 1;
  791. // None of the data from `ContactSettings` is publicly available. Instead,
  792. // proxy contact data is published for your domain. Email sent to the proxy
  793. // email address is forwarded to the registrant's email address. Cloud Domains
  794. // provides this privacy proxy service at no additional cost.
  795. PRIVATE_CONTACT_DATA = 2;
  796. // Some data from `ContactSettings` is publicly available. The actual
  797. // information redacted depends on the domain. For details, see [the
  798. // registration privacy
  799. // article](https://support.google.com/domains/answer/3251242).
  800. REDACTED_CONTACT_DATA = 3;
  801. }
  802. // Notices about special properties of certain domains.
  803. enum DomainNotice {
  804. // The notice is undefined.
  805. DOMAIN_NOTICE_UNSPECIFIED = 0;
  806. // Indicates that the domain is preloaded on the HTTP Strict Transport
  807. // Security list in browsers. Serving a website on such domain requires
  808. // an SSL certificate. For details, see
  809. // [how to get an SSL
  810. // certificate](https://support.google.com/domains/answer/7638036).
  811. HSTS_PRELOADED = 1;
  812. }
  813. // Notices related to contact information.
  814. enum ContactNotice {
  815. // The notice is undefined.
  816. CONTACT_NOTICE_UNSPECIFIED = 0;
  817. // Required when setting the `privacy` field of `ContactSettings` to
  818. // `PUBLIC_CONTACT_DATA`, which exposes contact data publicly.
  819. PUBLIC_CONTACT_DATA_ACKNOWLEDGEMENT = 1;
  820. }
  821. // Possible states of a `Registration`'s transfer lock.
  822. enum TransferLockState {
  823. // The state is unspecified.
  824. TRANSFER_LOCK_STATE_UNSPECIFIED = 0;
  825. // The domain is unlocked and can be transferred to another registrar.
  826. UNLOCKED = 1;
  827. // The domain is locked and cannot be transferred to another registrar.
  828. LOCKED = 2;
  829. }