一般作業

本頁提供一些常見的操作範例 Android 通用經銷商程式庫，包括：

建立 ResellerService 物件

使用 Samsung 和 Google 工廠類別建立 ResellerService 物件。 使用 ResellerService 物件時，可透過一組常用方法註冊 Samsung 和其他 Android 裝置。

Samsung 裝置

以下範例說明如何使用ResellerService 管理 Samsung 裝置的 SamsungResellerServiceFactory 類別。

您必須先開始使用 與 Knox 部署計畫 (KDP) 合作。

ResellerService samsungResellerService = SamsungResellerServiceFactory.createResellerService(resellerId, serviceAccountKeyFilePath, clientIdentifier);

其他 Android 裝置

以下範例說明如何使用ResellerService 管理其他 (非 Samsung) Android 的 GoogleResellerServiceFactory 類別 裝置。在這之前，您需要先按照「開始使用 適用於零接觸註冊機制 以取得 resellerId 和服務帳戶金鑰。

ResellerService googleResellerService = GoogleResellerServiceFactory.createResellerService(resellerId, serviceAccountKeyFilePath);

建立 Customer 物件

購買 Samsung 和非 Samsung 裝置的客戶必須使用兩個客戶 ID。

Samsung 裝置

如要管理 Samsung 裝置，請使用客戶的 Knox 客戶 ID。若要取得 您需要先建立 Customer 物件，才能使用 Knox 客戶 ID。方法如下 使用從createCustomerSamsungResellerService SamsungResellerServiceFactory。範例如下：

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 物件。方法是使用 ResellerService 呼叫 createCustomer 透過 GoogleResellerServiceFactory 建立。範例如下：

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 物件。你可以 請從回應中擷取客戶編號。

領取一批裝置

聲明裝置擁有權後，裝置就會與客戶建立關聯。適用對象 假設您銷售整批裝置給客戶， 客戶的裝置。

本例是處理大量裝置 (包括 多家製造商 (Samsung 和其他 Android) 的裝置訂單 裝置) 使用。

步驟 1：整理裝置和客戶

提供一張裝置 IMEI、製造商和客戶 ID 表格 裝置售出後，管理訂單的其中一種方式是 清單：Samsung 裝置訂單以及其他 Android (非 Samsung) 裝置訂單。 然後依客戶將每份清單的裝置分組。例如：

Samsung 裝置

客戶名稱 Samsung Knox 客戶 ID 製造商 IMEI
ABC 公司 11 Samsung

1234567801

1234567802

其他 Android 裝置

客戶名稱 客戶 ID 製造商 IMEI
ABC 公司 21 Google 1234567803
XYZ Corp 22 Sony

1234567804

1234567805

步驟 2：建立 ClaimDevicesRequest 物件

Samsung 裝置

// 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 物件

Samsung 裝置

// 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。

Samsung 裝置

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);

換貨 Samsung 裝置

如果裝置因故需要更換，您可以換貨。這個 範例假設您正在交換其他 Samsung 裝置的 Samsung 裝置 裝置。

步驟 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 (非 Samsung) 裝置

如果裝置因故需要更換，您可以換貨。這個 範例假設您以 Android (非 Samsung) 裝置交換 Android (非 Samsung) 裝置 其他 Android (非 Samsung) 裝置。

步驟 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);

如果成功，呼叫會傳回包含 ClaimDeviceResponse 物件 deviceId。否則，系統會擲回包含錯誤代碼的常見例外狀況。