常见操作

本页面提供了使用通用 Android 转销商库执行的一些常见操作示例，包括：

创建 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 公司 11 Samsung

1234567801

1234567802

其他 Android 设备

客户名称 客户 ID 制造商 IMEI
ABC 公司 21 Google 1234567803
XYZ 公司 22 Sony

1234567804

1234567805

第 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。此示例需要两个单独的请求：一个来自三星 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。此示例需要两个单独的请求：一个来自三星 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 对象。否则会抛出包含错误代码的常见异常。