一般作業

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

建立 ResellerService 物件

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

Samsung 裝置

以下範例說明如何使用 SamsungResellerServiceFactory 類別建立 ResellerService 物件來管理 Samsung 裝置。

為此，您必須先加入 Knox 部署計畫 (KDP)。

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

其他 Android 裝置

以下範例說明如何使用 GoogleResellerServiceFactory 類別建立 ResellerService 物件，以管理其他 (非 Samsung) Android 裝置。在完成這項作業之前，請按照開始使用零接觸註冊機制一文中的步驟取得 resellerId 和服務帳戶金鑰。

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

建立 Customer 物件

客戶購買 Samsung 及非 Samsung 裝置時，需提供兩個客戶 ID。

Samsung 裝置

如要管理 Samsung 裝置，請使用客戶的 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。

聲明一批裝置的擁有權

認領裝置會建立裝置和客戶之間的關聯。舉例來說，如果您向客戶銷售一批裝置，就必須針對該客戶領取裝置。

本範例顯示一個處理多個裝置的方法，其中包含來自多個製造商 (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 公司 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) 裝置。

步驟 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 物件。否則，會擲回包含錯誤代碼的常見例外狀況。