本頁提供了一些常見 Android 經銷商程式庫的常見操作範例,包括:
建立 ResellerService
物件
使用 Samsung 和 Google 工廠類別來建立 ResellerService
物件。
使用 ResellerService
物件時,可以使用一組常見的方法來註冊 Samsung 和其他 Android 裝置。
Samsung 裝置
以下範例說明如何使用 SamsungResellerServiceFactory
類別建立 ResellerService
物件來管理 Samsung 裝置。
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 |
|
其他 Android 裝置
客戶名稱 | 客戶 ID | 製造商 | IMEI |
---|---|---|---|
ABC 公司 | 21 |
Google |
1234567803 |
XYZ 公司 | 22 |
Sony |
|
步驟 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
物件。否則,會擲回包含錯誤代碼的常見例外狀況。