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 cùng Thư viện đại lý Android chung, 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 nhóm phương thức phổ biến để đăng ký 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 SamsungResellerServiceFactory để quản lý thiết bị Samsung.

Trước khi có thể thực hiện việc này, bạn cần tham gia nhờ 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 của Samsung) thiết bị. 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 bài viết Bắt đầu để thiết lập tự động để lấy resellerId và khoá 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 của Samsung yêu cầu hai mã khách hàng.

Thiết bị Samsung

Để quản lý các thiết bị Samsung, bạn hãy sử dụng Mã khách hàng Knox của khách hàng. Để tải Knox Mã khách hàng, trước tiên, bạn cần tạo một đối tượng Customer. Để làm như vậy, gọi createCustomer bằng SamsungResellerService được 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 từ đó bạn có thể trích xuất ID 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 thiết lập tự động mã khách hàng. Nếu khách hàng đã sử dụng quy trình thiết lập tự động với một khách hàng khác đại lý, bạn 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 một Đối tượng Customer. Để thực hiện việc này, hãy gọi createCustomer bằng ResellerService được tạo qua 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 này sẽ trả về đối tượng CreateCustomerResponse. Bạn có thể truy xuất mã khách hàng trong phản hồi.

Xác nhận một loạt thiết bị

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

Ví dụ này cho thấy một cách để xử lý một loạt thiết bị bao gồm đơn đặt hàng thiết bị từ nhiều nhà sản xuất (Samsung và các hãng Android khác thiết bị) từ nhiều khách hàng.

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

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

Thiết bị Samsung

Tên khách hàng Mã khách hàng Samsung Knox Nhà sản xuất 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 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 thiết bị cho khách hàng

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

// 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. Danh sách này chứa trạng thái của yêu cầu (đang tiến hành, đã hoàn thành, hoàn tất 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), 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 một loạt thiết bị

Khi huỷ xác nhận quyền sở hữu một thiết bị, thiết bị đó sẽ bị huỷ liên kết với khách hàng. Bạn có thể cần huỷ xác nhận quyền sở hữu một thiết bị nếu đơn đặt hàng thiết bị bị huỷ hoặc lô hàng thiết bị không thể hoàn tất thành công. Cách huỷ xác nhận quyền sở hữu một loạt 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 thiết bị

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

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. Danh sách này chứa trạng thái của yêu cầu (đang tiến hành, đã hoàn thành, hoàn tất 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);

Đổi thiết bị Samsung

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

Bước 1: Tạo một đố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. Danh sách này chứa trạng thái của yêu cầu (đang tiến hành, đã hoàn thành, hoàn tất 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), 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. Danh sách này chứa trạng thái của yêu cầu (đang tiến hành, đã hoàn thành, hoàn tất 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), gọi getOperation:

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

Đổi thiết bị Android (không phải của Samsung)

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

Bước 1: Tạo một đố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, thao tác này sẽ gửi một ngoại lệ phổ biến có chứa mã lỗi.