feat: add API ImportCustomer for Cloud Channel API

Google APIs · copybara-github · commit bf57b2c88187 · 2021-09-03T11:20:10.000-07:00
docs: update comments for a few fields

PiperOrigin-RevId: 394721709
diff --git a/google/cloud/channel/v1/cloudchannel_v1.yaml b/google/cloud/channel/v1/cloudchannel_v1.yaml
@@ -13,6 +13,12 @@ types:
 - name: google.cloud.channel.v1.SubscriberEvent
 - name: google.cloud.channel.v1.TransferEntitlementsResponse
 
+documentation:
+  summary: |-
+    The Cloud Channel API enables Google Cloud partners to have a single
+    unified resale platform and APIs across all of Google Cloud including GCP,
+    Workspace, Maps and Chrome.
+
 http:
   rules:
   - selector: google.longrunning.Operations.CancelOperation
diff --git a/google/cloud/channel/v1/customers.proto b/google/cloud/channel/v1/customers.proto
@@ -54,7 +54,8 @@ message Customer {
   // Secondary contact email. You need to provide an alternate email to create
   // different domains if a primary contact email already exists. Users will
   // receive a notification with credentials when you create an admin.google.com
-  // account. Secondary emails are also recovery email addresses.
+  // account. Secondary emails are also recovery email addresses. Alternate
+  // emails are optional when you create Team customers.
   string alternate_email = 5;
 
   // Required. The customer's primary domain. Must match the primary contact
@@ -87,10 +88,10 @@ message Customer {
 
 // Contact information for a customer account.
 message ContactInfo {
-  // The customer account contact's first name.
+  // The customer account contact's first name. Optional for Team customers.
   string first_name = 1;
 
-  // The customer account contact's last name.
+  // The customer account contact's last name. Optional for Team customers.
   string last_name = 2;
 
   // Output only. The customer account contact's display name, formatted as a
@@ -99,7 +100,7 @@ message ContactInfo {
 
   // The customer account's contact email. Required for entitlements that create
   // admin.google.com accounts, and serves as the customer's username for those
-  // accounts.
+  // accounts. Use this email to invite Team customers.
   string email = 5;
 
   // Optional. The customer account contact's job title.
diff --git a/google/cloud/channel/v1/service.proto b/google/cloud/channel/v1/service.proto
@@ -188,6 +188,34 @@ service CloudChannelService {
     option (google.api.method_signature) = "name";
   }
 
+  // Imports a [Customer][google.cloud.channel.v1.Customer] from the Cloud Identity associated with the provided
+  // Cloud Identity ID or domain before a TransferEntitlements call. If a
+  // linked Customer already exists and overwrite_if_exists is true, it will
+  // update that Customer's data.
+  //
+  // Possible error codes:
+  //
+  // * PERMISSION_DENIED: The reseller account making the request is different
+  // from the reseller account in the API request.
+  // * NOT_FOUND: Cloud Identity doesn't exist or was deleted.
+  // * INVALID_ARGUMENT: Required parameters are missing, or the auth_token is
+  // expired or invalid.
+  // * ALREADY_EXISTS: A customer already exists and has conflicting critical
+  // fields. Requires an overwrite.
+  //
+  // Return value:
+  // The [Customer][google.cloud.channel.v1.Customer].
+  rpc ImportCustomer(ImportCustomerRequest) returns (Customer) {
+    option (google.api.http) = {
+      post: "/v1/{parent=accounts/*}/customers:import"
+      body: "*"
+      additional_bindings {
+        post: "/v1/{parent=accounts/*/channelPartnerLinks/*}/customers:import"
+        body: "*"
+      }
+    };
+  }
+
   // Creates a Cloud Identity for the given customer using the customer's
   // information, or the information provided here.
   //
@@ -1026,6 +1054,52 @@ message DeleteCustomerRequest {
   ];
 }
 
+// Request message for [CloudChannelService.ImportCustomer][google.cloud.channel.v1.CloudChannelService.ImportCustomer]
+message ImportCustomerRequest {
+  // Specifies the identity of the transfer customer.
+  // A customer's cloud_identity_id or domain is required to look up the
+  // customer's Cloud Identity. For Team customers, only the cloud_identity_id
+  // option is valid.
+  oneof customer_identity {
+    // Required. Customer domain.
+    string domain = 2 [(google.api.field_behavior) = REQUIRED];
+
+    // Required. Customer's Cloud Identity ID
+    string cloud_identity_id = 3 [(google.api.field_behavior) = REQUIRED];
+  }
+
+  // Required. The resource name of the reseller's account.
+  // Parent takes the format: accounts/{account_id} or
+  // accounts/{account_id}/channelPartnerLinks/{channel_partner_id}
+  string parent = 1 [(google.api.field_behavior) = REQUIRED];
+
+  // Optional. The super admin of the resold customer generates this token to
+  // authorize a reseller to access their Cloud Identity and purchase
+  // entitlements on their behalf. You can omit this token after authorization.
+  // See https://support.google.com/a/answer/7643790 for more details.
+  string auth_token = 4 [(google.api.field_behavior) = OPTIONAL];
+
+  // Required. Choose to overwrite an existing customer if found.
+  // This must be set to true if there is an existing customer with a
+  // conflicting region code or domain.
+  bool overwrite_if_exists = 5 [(google.api.field_behavior) = REQUIRED];
+
+  // Optional. Cloud Identity ID of a channel partner who will be the direct reseller for
+  // the customer's order. This field is required for 2-tier transfer scenarios
+  // and can be provided via the request Parent binding as well.
+  string channel_partner_id = 6 [(google.api.field_behavior) = OPTIONAL];
+
+  // Optional. Specifies the customer that will receive imported Cloud Identity
+  // information.
+  // Format: accounts/{account_id}/customers/{customer_id}
+  string customer = 7 [
+    (google.api.field_behavior) = OPTIONAL,
+    (google.api.resource_reference) = {
+      type: "cloudchannel.googleapis.com/Customer"
+    }
+  ];
+}
+
 // Request message for [CloudChannelService.ProvisionCloudIdentity][google.cloud.channel.v1.CloudChannelService.ProvisionCloudIdentity]
 message ProvisionCloudIdentityRequest {
   // Required. Resource name of the customer.
