Thao tác phổ biến

Trang này cung cấp ví dụ về một số thao tác phổ biến mà bạn có thể thực hiện với Thư viện đại lý Android phổ biến, bao gồm:

Tạo đối tượng ResellerService

Sử dụng các lớp nhà máy của Samsung và Google để tạo các đối tượng ResellerService. Với các đối tượng ResellerService, bạn có thể sử dụng một tập hợp phương thức phổ biến để đăng ký cho Samsung và các thiết bị Android khác.

Thiết bị Samsung

Ví dụ bên dưới cho biết cách tạo đối tượng ResellerService bằng cách sử dụng lớp SamsungResellerServiceFactory để quản lý các thiết bị Samsung.

Để thực hiện việc này, bạn cần giới thiệu với Chương trình triển khai Knox (KDP).

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

Các thiết bị Android khác

Ví dụ bên dưới cho biết cách tạo đối tượng ResellerService bằng cách sử dụng lớp GoogleResellerServiceFactory để quản lý các thiết bị Android khác (không phải Samsung). Trước khi có thể thực hiện việc này, bạn cần làm theo các bước trong phần Bắt đầu thiết lập tự động để nhận khóa resellerId và khóa tài khoản dịch vụ.

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

Tạo đối tượng Customer

Một khách hàng mua thiết bị Samsung và không phải Samsung yêu cầu hai mã khách hàng.

Thiết bị Samsung

Để quản lý thiết bị Samsung, bạn hãy dùng mã khách hàng Knox của khách hàng. Để có được mã khách hàng Kxx, trước tiên, bạn cần tạo một đối tượng Customer. Để thực hiện việc này, hãy gọi createCustomer bằng SamsungResellerService đã tạo từ SamsungResellerServiceFactory. Ví dụ:

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

Nếu thành công, yêu cầu sẽ trả về một đối tượng CreateCustomerResponse mà từ đó bạn có thể trích xuất Mã khách hàng Knox.

Các thiết bị Android khác

Đối với các thiết bị Android khác, khách hàng yêu cầu mã khách hàng đăng ký thiết lập tự động. Nếu khách hàng đã sử dụng chương trình thiết lập tự động với một đại lý khác, thì bạn sẽ sử dụng mã khách hàng hiện tại của họ. Nếu không, bạn cần tạo đối tượng Customer. Để thực hiện việc này, hãy gọi createCustomer bằng ResellerService được tạo từ GoogleResellerServiceFactory. Sau đây là ví dụ:

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

Nếu thành công, yêu cầu sẽ trả về một đối tượng CreateCustomerResponse. Bạn có thể truy xuất mã khách hàng từ phản hồi.

Xác nhận quyền sở hữu lô thiết bị

Việc xác nhận quyền sở hữu một thiết bị sẽ tạo ra mối liên kết giữa thiết bị và khách hàng. Ví dụ: nếu bán một lô thiết bị cho một khách hàng, bạn sẽ xác nhận quyền sở hữu các thiết bị đó cho khách hàng đó.

Ví dụ này chỉ về một cách xử lý hàng loạt thiết bị, bao gồm thứ tự thiết bị của nhiều nhà sản xuất (Samsung và các thiết bị Android khác) từ nhiều khách hàng.

Bước 1: Sắp xếp thiết bị và khách hàng

Với bảng IMEI của nhà sản xuất, nhà sản xuất và mã khách hàng mà bạn đã bán thiết bị, có một cách để quản lý đơn đặt hàng là sắp xếp chúng thành hai danh sách: đơn đặt hàng thiết bị Samsung và các đơn đặt hàng thiết bị Android khác (không phải Samsung). Sau đó, đối với mỗi danh sách, hãy nhóm thiết bị theo khách hàng. Ví dụ:

Thiết bị Samsung

Tên khách hàng ID khách hàng Samsung Knox Nhà sản xuất Số IMEI
Công ty ABC 11 Samsung

1234567801

1234567802

Các thiết bị Android khác

Tên khách hàng Mã khách hàng Nhà sản xuất Số IMEI
Công ty ABC 21 Google 1234567803
Công ty XYZ 22 Sony

1234567804

1234567805

Bước 2: Tạo đối tượng ClaimDevicesRequest

Thiết bị 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();

Các thiết bị Android khác

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

Bước 3: Xác nhận quyền sở hữu thiết bị cho khách hàng

Để xác nhận quyền sở hữu thiết bị cho khách hàng, hãy gọi ClaimDevicesAsync. Ví dụ này yêu cầu hai yêu cầu riêng biệt: một yêu cầu từ đối tượng Samsung ResellerService và một yêu cầu từ đối tượng Google ResellerService.

// Samsung devices
ClaimDevicesResponse samsungResponse = samsungResellerService.claimDevicesAsync(claimSamsungDevicesRequest);

// Other Android devices
ClaimDevicesResponse googleResponse = googleResellerService.claimDevicesAsync(claimGoogleDevicesRequest);

Yêu cầu ClaimDevicesAsync trả về danh sách các đối tượng Operation, trong đó có trạng thái của yêu cầu (đang tiến hành, đã hoàn tất, đã hoàn tất nhưng có lỗi hoặc không thành công). Để kiểm tra trạng thái của một thao tác (ví dụ: nếu phản hồi trả về IN_PROGRESS), hãy gọi 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);

Huỷ xác nhận quyền sở hữu lô thiết bị

Việc huỷ xác nhận quyền sở hữu thiết bị sẽ huỷ liên kết thiết bị đó với khách hàng. Bạn có thể cần huỷ xác nhận quyền sở hữu đối với thiết bị nếu đơn đặt hàng thiết bị bị huỷ hoặc giao hàng thiết bị không thể hoàn tất thành công. Để huỷ xác nhận quyền sở hữu đối với một lô thiết bị, hãy làm theo các bước sau:

Bước 1: Tạo đối tượng UnclaimDevicesRequest

Thiết bị 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();

Các thiết bị Android khác

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

Bước 2: Huỷ xác nhận quyền sở hữu thiết bị

Để huỷ xác nhận quyền sở hữu thiết bị, hãy gọi UnclaimDevicesAsync. Ví dụ này yêu cầu hai yêu cầu riêng biệt: một yêu cầu từ đối tượng Samsung ResellerService và một yêu cầu từ đối tượng Google ResellerService.

UnclaimDevicesResponse samsungResponse = samsungResellerService.unclaimDevicesAsync(unclaimSamsungDevicesRequest);
UnclaimDevicesResponse googleResponse = googleResellerService.unclaimDevicesAsync(unclaimGoogleDevicesRequest);

Yêu cầu UnclaimDevicesAsync trả về danh sách các đối tượng Operation, trong đó có trạng thái của yêu cầu (đang tiến hành, đã hoàn tất, đã hoàn tất nhưng có lỗi, hoặc không thành công) Để kiểm tra trạng thái của một thao tác (ví dụ: nếu phản hồi trả về IN_PROGRESS), hãy gọi getOperation.

Thiết bị Samsung

GetOperationRequest samsungOperationRequest = GetOperationRequest.newBuilder().setOperationId(samsungOperationId).build();
Operation samsungOperation = samsungResellerService.getOperation(samsungOperationRequest);

Các thiết bị Android khác

GetOperationRequest googleOperationRequest = GetOperationRequest.newBuilder().setOperationId(googleOperationId).build();
Operation googleOperation = googleResellerService.getOperation(googleOperationRequest);

Trao đổi thiết bị Samsung

Nếu cần thay thiết bị vì bất kỳ lý do gì, bạn có thể đổi thiết bị đó. Ví dụ này giả định bạn đang trao đổi một thiết bị Samsung với một thiết bị Samsung khác.

Bước 1: Tạo đối tượng 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();

Bước 2: Gọi UnclaimDeviceAsync

UnclaimDevicesResponse samsungResponse = samsungResellerService.unclaimDevicesAsync(unclaimSamsungDevicesRequest);

Yêu cầu UnclaimDevicesAsync trả về danh sách các đối tượng Operation, trong đó có trạng thái của yêu cầu (đang tiến hành, đã hoàn tất, đã hoàn tất nhưng có lỗi hoặc không thành công). Để kiểm tra trạng thái của một thao tác (ví dụ: nếu phản hồi trả về IN_PROGRESS), hãy gọi getOperation:

GetOperationRequest samsungOperationRequest = GetOperationRequest.newBuilder().setOperationId(samsungOperationId).build();
Operation samsungOperation = samsungResellerService.getOperation(samsungOperationRequest);

Bước 3: Tạo một đối tượng 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();

Bước 4: Gọi ClaimDeviceAsync

ClaimDevicesResponse samsungResponse = samsungResellerService.claimDevicesAsync(claimSamsungDevicesRequest);

Yêu cầu ClaimDevicesAsync trả về danh sách các đối tượng Operation, trong đó có trạng thái của yêu cầu (đang tiến hành, đã hoàn tất, đã hoàn tất nhưng có lỗi hoặc không thành công). Để kiểm tra trạng thái của một thao tác (ví dụ: nếu phản hồi trả về IN_PROGRESS), hãy gọi getOperation:

GetOperationRequest samsungOperationRequest = GetOperationRequest.newBuilder().setOperationId(samsungOperationId).build();
Operation samsungOperation = samsungResellerService.getOperation(samsungOperationRequest);

Trao đổi thiết bị Android (không phải Samsung)

Nếu cần thay thiết bị vì bất kỳ lý do gì, bạn có thể đổi thiết bị đó. Ví dụ này giả định rằng bạn đang trao đổi một thiết bị Android (không phải của Samsung) với một thiết bị Android khác (không phải Samsung).

Bước 1: Tạo đối tượng UnclaimDeviceRequest

UnclaimDeviceRequest unclaimGoogleDeviceRequest = UnclaimDeviceRequest.newBuilder()
    .setUnclaim(
        DeviceUnclaim.newBuilder()
            .setDeviceIdentifier(
                DeviceIdentifier.newBuilder()
                    .setImei("1234567803")
                    .build())
            .build())
    .build();

Bước 2: Gọi UnclaimDevice

googleResponse = googleResellerService.unclaimDevice(unclaimGoogleDeviceRequest);

Bước 3: Tạo một đối tượng 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();

Bước 4: Gọi ClaimDevice

ClaimDeviceResponse response = googleResellerService.claimDevice(claimGoogleDeviceRequest);

Nếu thành công, lệnh gọi sẽ trả về đối tượng ClaimDeviceResponse chứa deviceId. Nếu không, hệ thống sẽ gửi một trường hợp ngoại lệ phổ biến chứa mã lỗi.