一般的な操作

このページでは、次のような、一般的な Android 販売パートナー ライブラリで実行できる一般的なオペレーションの例を示します。

ResellerService オブジェクトを作成する

Samsung と Google のファクトリ クラスを使用して、ResellerService オブジェクトを作成します。ResellerService オブジェクトを使用すると、Samsung などの Android デバイスを登録するための共通のメソッドセットを使用できます。

Samsung デバイス

次の例は、SamsungResellerServiceFactory クラスを使用して Samsung デバイスを管理する ResellerService オブジェクトの作成方法を示しています。

これを行うには、Knox Deployment Program（KDP）を使用してオンボーディングする必要があります。

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

その他の Android デバイス

以下の例は、GoogleResellerServiceFactory クラスを使用して ResellerService オブジェクトを作成し、他の（Samsung 以外の）Android デバイスを管理する方法を示しています。これを行うには、ゼロタッチ登録のスタートガイドの手順に沿って、resellerId とサービス アカウント キーを取得する必要があります。

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

Customer オブジェクトを作成する

お客様が Samsung と Samsung 以外のデバイスを購入する場合は、2 つのお客様 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 の表を前提として、注文を管理する 1 つの方法は、Samsung デバイスの注文と、Android 以外の Samsung 以外のデバイスの注文を 2 つのリストにまとめることです。次に、リストごとにお客様別にデバイスをグループ化します。例:

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 を呼び出します。この例では、2 つの別個のリクエストが必要です。1 つは Samsung ResellerService オブジェクトからのリクエストで、もう 1 つは 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 を呼び出します。この例では、2 つの別々のリクエストが必要です。1 つは Samsung ResellerService オブジェクトからのリクエストで、もう 1 つは 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 オブジェクトを返します。それ以外の場合は、エラーコードを含む一般的な例外がスローされます。