常见操作

本页提供了一些常见操作的示例，您可以使用 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

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