本页提供了一些常见操作的示例,您可以使用 Common Android Reseller Library 执行这些操作,包括:
创建 ResellerService
对象
使用 Samsung 和 Google 工厂类创建 ResellerService
对象。借助 ResellerService
对象,您可以使用一组常用方法来注册三星和其他 Android 设备。
三星设备
以下示例展示了如何使用 SamsungResellerServiceFactory
类创建 ResellerService
对象来管理三星设备。
在此之前,您需要通过 Knox 部署计划 (KDP) 进行初始配置。
ResellerService samsungResellerService = SamsungResellerServiceFactory.createResellerService(resellerId, serviceAccountKeyFilePath, clientIdentifier);
其他 Android 设备
以下示例展示了如何使用 GoogleResellerServiceFactory
类创建 ResellerService
对象来管理其他(非三星)Android 设备。在执行此操作之前,您需要按照零触摸注册功能使用入门中的步骤获取 resellerId
和服务账号密钥。
ResellerService googleResellerService = GoogleResellerServiceFactory.createResellerService(resellerId, serviceAccountKeyFilePath);
创建 Customer
对象
购买三星设备和非三星设备的客户需要两个客户 ID。
三星设备
如需管理三星设备,您需要使用客户的 Knox 客户 ID。要获取 Knox 客户 ID,您需要先创建一个 Customer
对象。为此,请使用从 SamsungResellerServiceFactory
创建的 SamsungResellerService
调用 createCustomer
。示例如下:
CreateCustomerRequest request = CreateCustomerRequest.newBuilder()
.setCustomerName("TestCustomer") .addPrimaryEmails("superAdmin@gmail.com")
.putVendorParams("country", "US") .putVendorParams("firstName", "Avery")
.putVendorParams("lastName", "Yamada") .putVendorParams("service", "KME")
.build();
CreateCustomerResponse response = samsungResellerService.createCustomer(request);
String companyId = response.getCustomer().getCompanyReference().getCompanyId();
如果成功,请求会返回一个 CreateCustomerResponse
对象,您可以从中提取 Knox 客户 ID。
其他 Android 设备
对于其他 Android 设备,客户需要提供零触摸注册客户 ID。如果客户已通过其他转销商使用免触摸注册,您可以使用其现有的客户 ID。否则,您需要创建一个 Customer
对象。为此,请使用从 GoogleResellerServiceFactory
创建的 ResellerService
调用 createCustomer
。下面举例说明:
CreateCustomerRequest request = CreateCustomerRequest.newBuilder()
.setCustomerName("TestCustomer")
.addPrimaryEmails("owner@gmail.com")
.addSecondaryEmails("admin@gmail.com")
.build();
CreateCustomerResponse response = googleResellerService.createCustomer(request);
String companyId = response.getCustomer().getCompanyReference().getCompanyId();
如果成功,请求会返回 CreateCustomerResponse
对象。您可以从响应中检索客户 ID。
声明一批设备
声明设备会在设备和客户之间建立关联。例如,如果您向客户销售一批设备,则需要为该客户声明设备。
此示例展示了处理一批设备的一种方法,其中包括来自多个客户的多个制造商(三星和其他 Android 设备)的设备订单。
第 1 步:整理设备和客户
假设您有一个表格,其中包含设备 IMEI、制造商和设备售出的客户 ID,那么管理订单的方法之一是将其整理成两个列表:三星设备订单和其他 Android(非三星)设备订单。然后,针对每个列表,按客户对设备进行分组。例如:
三星设备
客户名称 | Samsung Knox 客户 ID | 制造商 | IMEI |
---|---|---|---|
ABC Corp | 11 |
Samsung |
|
其他 Android 设备
客户名称 | 客户 ID | 制造商 | IMEI |
---|---|---|---|
ABC 公司 | 21 |
Google |
1234567803 |
XYZ 公司 | 22 |
Sony |
|
第 2 步:创建 ClaimDevicesRequest
对象
三星设备
// Note: You can only claim devices for a single customer in each request.
ClaimDevicesRequest claimSamsungDevicesRequest = ClaimDevicesRequest.newBuilder()
.addClaims(
DeviceClaim.newBuilder()
.setCustomer(
CompanyReference.newBuilder()
.setVendor(Vendor.SAMSUNG)
.setCompanyId("11")
.build())
.setDeviceIdentifier(
DeviceIdentifier.newBuilder()
.setImei("1234567801")
.setManufacturer("Samsung")
.build())
.build())
.addClaims(
DeviceClaim.newBuilder()
.setCustomer(
CompanyReference.newBuilder()
.setVendor(Vendor.SAMSUNG)
.setCompanyId("11")
.build())
.setDeviceIdentifier(
DeviceIdentifier.newBuilder()
.setImei("1234567802")
.setManufacturer("Samsung")
.build())
.build())
.build();
其他 Android 设备
ClaimDevicesRequest claimGoogleDevicesRequest = ClaimDevicesRequest.newBuilder()
.addClaims(
DeviceClaim.newBuilder()
.setCustomer(
CompanyReference.newBuilder()
.setVendor(Vendor.GOOGLE)
.setCompanyId("21")
.build())
.setDeviceIdentifier(
DeviceIdentifier.newBuilder()
.setImei("1234567803")
.setManufacturer("Google")
.build())
.build())
.addClaims(
DeviceClaim.newBuilder()
.setCustomer(
CompanyReference.newBuilder()
.setVendor(Vendor.GOOGLE)
.setCompanyId("22")
.build())
.setDeviceIdentifier(
DeviceIdentifier.newBuilder()
.setImei("1234567804")
.setManufacturer("Sony")
.build())
.build())
.addClaims(
DeviceClaim.newBuilder()
.setCustomer(
CompanyReference.newBuilder()
.setVendor(Vendor.GOOGLE)
.setCompanyId("22")
.build())
.setDeviceIdentifier(
DeviceIdentifier.newBuilder()
.setImei("1234567805")
.setManufacturer("Sony")
.build())
.build())
.build();
第 3 步:为客户认领设备
如需为客户声明设备,请致电 ClaimDevicesAsync
。此示例需要发出两个单独的请求:一个来自 Samsung ResellerService
对象,另一个来自 Google ResellerService
对象。
// Samsung devices
ClaimDevicesResponse samsungResponse = samsungResellerService.claimDevicesAsync(claimSamsungDevicesRequest);
// Other Android devices
ClaimDevicesResponse googleResponse = googleResellerService.claimDevicesAsync(claimGoogleDevicesRequest);
ClaimDevicesAsync
请求会返回一个 Operation
对象列表,其中包含请求的状态(进行中、已完成、已完成但有错误或失败)。如需检查操作的状态(例如,响应是否返回了 IN_PROGRESS
),请调用 getOperation
。
// Samsung devices
GetOperationRequest samsungOperationRequest = GetOperationRequest.newBuilder().setOperationId(samsungOperationId).build();
Operation samsungOperation = samsungResellerService.getOperation(samsungOperationRequest);
// Other Android devices
GetOperationRequest googleOperationRequest = GetOperationRequest.newBuilder().setOperationId(googleOperationId).build();
Operation googleOperation = googleResellerService.getOperation(googleOperationRequest);
取消声明一批设备
取消认领设备会解除设备与客户之间的关联。如果设备订单被取消或设备配送无法成功完成,您可能需要取消对设备的声明。如需取消声明一批设备,请按以下步骤操作:
第 1 步:创建 UnclaimDevicesRequest
对象
三星设备
// Each request can only unclaim devices belonging to a single customer. The request must also
// include the customer's Samsung Knox customer ID.
UnclaimDevicesRequest unclaimSamsungDevicesRequest = UnclaimDevicesRequest.newBuilder()
.putVendorParams("customerId", "11")
.addUnclaims(
DeviceUnclaim.newBuilder()
.setDeviceIdentifier(
DeviceIdentifier.newBuilder()
.setImei("1234567801")
.build())
.build())
.addUnclaims(
DeviceUnclaim.newBuilder()
.setDeviceIdentifier(
DeviceIdentifier.newBuilder()
.setImei("1234567802")
.build())
.build())
.build();
其他 Android 设备
UnclaimDevicesRequest unclaimGoogleDevicesRequest = UnclaimDevicesRequest.newBuilder()
.addUnclaims(
DeviceUnclaim.newBuilder()
.setDeviceIdentifier(
DeviceIdentifier.newBuilder()
.setImei("1234567803")
.build())
.build())
.addUnclaims(
DeviceUnclaim.newBuilder()
.setDeviceIdentifier(
DeviceIdentifier.newBuilder()
.setImei("1234567804")
.build())
.build())
.addUnclaims(
DeviceUnclaim.newBuilder()
.setDeviceIdentifier(
DeviceIdentifier.newBuilder()
.setImei("1234567805")
.build())
.build())
.build();
第 2 步:取消声明设备所有权
如需取消声明设备,请调用 UnclaimDevicesAsync
。此示例需要发出两个单独的请求:一个来自 Samsung ResellerService
对象,另一个来自 Google ResellerService
对象。
UnclaimDevicesResponse samsungResponse = samsungResellerService.unclaimDevicesAsync(unclaimSamsungDevicesRequest);
UnclaimDevicesResponse googleResponse = googleResellerService.unclaimDevicesAsync(unclaimGoogleDevicesRequest);
UnclaimDevicesAsync
请求会返回一个 Operation
对象列表,其中包含请求的状态(进行中、已完成、已完成但有错误或失败)。如需检查操作的状态(例如,响应是否返回了 IN_PROGRESS
),请调用 getOperation
。
三星设备
GetOperationRequest samsungOperationRequest = GetOperationRequest.newBuilder().setOperationId(samsungOperationId).build();
Operation samsungOperation = samsungResellerService.getOperation(samsungOperationRequest);
其他 Android 设备
GetOperationRequest googleOperationRequest = GetOperationRequest.newBuilder().setOperationId(googleOperationId).build();
Operation googleOperation = googleResellerService.getOperation(googleOperationRequest);
更换三星设备
如果设备因任何原因需要更换,您可以进行换货。此示例假定您要将三星设备更换为另一台三星设备。
第 1 步:创建 UnclaimDeviceRequest
对象
// Note: The request must include the customer's Samsung Knox customer ID.
UnclaimDevicesRequest unclaimSamsungDevicesRequest = UnclaimDevicesRequest.newBuilder()
.putVendorParams("customerId", "11")
.addUnclaims(
DeviceUnclaim.newBuilder()
.setDeviceIdentifier(
DeviceIdentifier.newBuilder()
.setImei("1234567801")
.build())
.build())
.build();
第 2 步:调用 UnclaimDeviceAsync
UnclaimDevicesResponse samsungResponse = samsungResellerService.unclaimDevicesAsync(unclaimSamsungDevicesRequest);
UnclaimDevicesAsync
请求会返回一个 Operation
对象列表,其中包含请求的状态(进行中、已完成、已完成但有错误或失败)。如需检查操作的状态(例如,响应是否返回了 IN_PROGRESS
),请调用 getOperation
:
GetOperationRequest samsungOperationRequest = GetOperationRequest.newBuilder().setOperationId(samsungOperationId).build();
Operation samsungOperation = samsungResellerService.getOperation(samsungOperationRequest);
第 3 步:创建 ClaimDeviceRequest
对象
ClaimDevicesRequest claimSamsungDevicesRequest = ClaimDevicesRequest.newBuilder()
.addClaims(
DeviceClaim.newBuilder()
.setCustomer(
CompanyReference.newBuilder()
.setVendor(Vendor.SAMSUNG)
.setCompanyId("11")
.build())
.setDeviceIdentifier(
DeviceIdentifier.newBuilder()
.setImei("1234567806")
.setManufacturer("Samsung")
.build())
.build())
.build();
第 4 步:调用 ClaimDeviceAsync
ClaimDevicesResponse samsungResponse = samsungResellerService.claimDevicesAsync(claimSamsungDevicesRequest);
ClaimDevicesAsync
请求会返回一个 Operation
对象列表,其中包含请求的状态(进行中、已完成、已完成但有错误或失败)。如需检查操作的状态(例如,如果响应返回 IN_PROGRESS
),请调用 getOperation
:
GetOperationRequest samsungOperationRequest = GetOperationRequest.newBuilder().setOperationId(samsungOperationId).build();
Operation samsungOperation = samsungResellerService.getOperation(samsungOperationRequest);
换货 Android(非三星)设备
如果设备因任何原因需要更换,您可以进行换货。此示例假定您要将 Android(非三星)设备更换为另一部 Android(非三星)设备。
第 1 步:创建 UnclaimDeviceRequest
对象
UnclaimDeviceRequest unclaimGoogleDeviceRequest = UnclaimDeviceRequest.newBuilder()
.setUnclaim(
DeviceUnclaim.newBuilder()
.setDeviceIdentifier(
DeviceIdentifier.newBuilder()
.setImei("1234567803")
.build())
.build())
.build();
第 2 步:调用 UnclaimDevice
googleResponse = googleResellerService.unclaimDevice(unclaimGoogleDeviceRequest);
第 3 步:创建 ClaimDeviceRequest
对象
ClaimDeviceRequest claimGoogleDeviceRequest = ClaimDeviceRequest.newBuilder()
.setClaim(
DeviceClaim.newBuilder()
.setCustomer(
CompanyReference.newBuilder()
.setVendor(Vendor.GOOGLE)
.setCompanyId("21")
.build())
.setDeviceIdentifier(
DeviceIdentifier.newBuilder()
.setImei("1234567807")
.setManufacturer("Google")
.build())
.build())
.build();
第 4 步:调用 ClaimDevice
ClaimDeviceResponse response = googleResellerService.claimDevice(claimGoogleDeviceRequest);
如果成功,该调用会返回包含 deviceId
的 ClaimDeviceResponse
对象。否则,它会抛出包含错误代码的常见异常。