一般作業

本頁面提供一些常見作業的範例，您可以使用通用 Android 經銷商程式庫執行這些作業，包括：

建立 ResellerService 物件

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

Samsung 裝置

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

您必須先加入 Knox 部署計畫 (KDP)，才能進行這項操作。

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

其他 Android 裝置

以下範例說明如何使用 GoogleResellerServiceFactory 類別建立 ResellerService 物件，以便管理其他 (非三星) 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 物件。否則，會擲回含有錯誤代碼的一般例外狀況。