一般的な操作

このページでは、Common Android Reseller Library で実行する一般的な操作の例を紹介します。

ResellerService オブジェクトの作成

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

Samsung デバイス

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

その前に、Knox デプロイ プログラム（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 つを示します。

ステップ 1: デバイスとお客様を整理する

デバイスの IMEI、メーカー、デバイスを販売したお客様の ID の表が用意されている場合、注文を管理する方法の一つとして、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 に電話します。この例では、Samsung ResellerService オブジェクトと Google ResellerService オブジェクトの 2 つのリクエストが必要です。

// 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 オブジェクトの 2 つのリクエストが必要です。

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 オブジェクトを返します。そうでない場合は、エラーコードを含む一般的な例外をスローします。