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
• Tạo đối tượng Customer
• Xác nhận quyền sở hữu một lô thiết bị
• Huỷ xác nhận quyền sở hữu một lô thiết bị
• Trao đổi thiết bị Samsung
• Trao đổi thiết bị Android (không phải Samsung)

---

Tạo đối tượng ResellerService

Sử dụng các lớp nhà máy của Samsung và Google để tạo đố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 lớp SamsungResellerServiceFactory để quản lý các thiết bị Samsung.

Trước khi có thể làm việc này, bạn cần tham gia 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 thấy cách tạo đối tượng ResellerService bằng lớp GoogleResellerServiceFactory để quản lý các thiết bị Android khác (không phải của 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 đăng ký không cần tiếp xúc để lấy resellerId và khoá tài khoản dịch vụ.

Cảnh báo: Khoá tài khoản dịch vụ có thể trở thành rủi ro bảo mật nếu không được quản lý cẩn thận. Để được tư vấn, hãy xem các phương pháp hay nhất để quản lý khoá API.

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

---

Tạo đối tượng Customer

Khách hàng mua thiết bị Samsung và thiết bị không phải Samsung cần có 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. Để lấy mã khách hàng Knox, 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 cách sử dụng SamsungResellerService được tạo từ SamsungResellerServiceFactory. Ví dụ:

CreateCustomerRequest request = CreateCustomerRequest.newBuilder()
    .setCustomerName("TestCustomer") .addPrimaryEmails("[e-mail]")
    .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à bạn có thể dùng để 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 cần có mã khách hàng đăng ký không tiếp xúc. Nếu khách hàng đã sử dụng tính năng đăng ký không tiếp xúc với một đại lý khác, bạn hãy sử dụng mã khách hàng hiện có 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 từ GoogleResellerServiceFactory. Sau đây là ví dụ:

CreateCustomerRequest request = CreateCustomerRequest.newBuilder()
    .setCustomerName("TestCustomer")
    .addPrimaryEmails("[e-mail]")
    .addSecondaryEmails("[e-mail]")
    .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 từ phản hồi.

---

Xác nhận quyền sở hữu một lô 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 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 cho thấy một cách để xử lý một lô thiết bị, trong đó có đơn đặt hàng 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 số IMEI, nhà sản xuất và mã nhận dạng của khách hàng đã mua thiết bị, một cách để quản lý đơn đặt hàng là sắp xếp các đơn đặt hàng đó thành hai danh sách: đơn đặt hàng thiết bị Samsung và đơ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 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
ABC corp	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 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 ResellerService của Samsung và một yêu cầu 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, trong đó chứa trạng thái của yêu cầu (đang tiến hành, hoàn tất, hoàn tất kèm theo 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 một loạt thiết bị

Thao tá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 thiết bị nếu đơn đặt hàng thiết bị bị huỷ hoặc không thể hoàn tất quá trình vận chuyển thiết bị. Để huỷ xác nhận quyền sở hữu 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 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 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, trong đó chứa trạng thái của yêu cầu (đang tiến hành, hoàn tất, hoàn tất kèm theo 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ị đó. Ví dụ này giả định rằng bạn đang trao đổi một thiết bị Samsung cho 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 đó chứa trạng thái của yêu cầu (đang tiến hành, hoàn tất, hoàn tất kèm theo 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 đố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ề một danh sách đối tượng Operation chứa trạng thái của yêu cầu (đang xử lý, hoàn thành, hoàn thành 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 thế 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 Samsung) cho một thiết bị Android (không phải Samsung) khác.

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 đố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ề một đố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.