Operazioni comuni

Questa pagina fornisce esempi di alcune operazioni comuni che potresti eseguire con la libreria dei rivenditori Android comuni, tra cui:


Creare oggetti ResellerService

Utilizza le classi di fabbrica Samsung e Google per creare oggetti ResellerService. Con gli oggetti ResellerService, è disponibile un insieme comune di metodi per registrare Samsung e altri dispositivi Android.

Dispositivi Samsung

L'esempio seguente mostra come creare un oggetto ResellerService utilizzando la classe SamsungResellerServiceFactory per gestire i dispositivi Samsung.

Prima di poter procedere, devi eseguire l'onboarding con il Knox Deployment Program (KDP).

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

Altri dispositivi Android

L'esempio seguente mostra come creare un oggetto ResellerService utilizzando la classe GoogleResellerServiceFactory per gestire altri dispositivi Android (diversi da Samsung). A questo scopo, devi seguire i passaggi descritti in Inizia per la registrazione zero-touch per ottenere il tuo resellerId e la chiave dell'account di servizio.

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

Crea Customer oggetti

Un cliente che acquista dispositivi Samsung e non Samsung richiede due ID cliente.

Dispositivi Samsung

Per gestire i dispositivi Samsung, utilizza l'ID cliente Knox del cliente. Per ottenere l'ID cliente Knox, devi prima creare un oggetto Customer. A questo scopo, chiama createCustomer utilizzando un elemento SamsungResellerService creato dal SamsungResellerServiceFactory. Ecco un esempio:

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();

Se l'esito è positivo, la richiesta restituisce un oggetto CreateCustomerResponse dal quale puoi estrarre l'ID cliente Knox.

Altri dispositivi Android

Per altri dispositivi Android, il cliente richiede un ID cliente per la registrazione zero-touch. Se un cliente utilizza già la registrazione zero-touch con un altro rivendicente, utilizza il suo ID cliente esistente. In caso contrario, devi creare un oggetto Customer. Per farlo, chiama createCustomer utilizzando un ResellerService creato dal GoogleResellerServiceFactory. Ecco un esempio:

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();

In caso di esito positivo, la richiesta restituisce un oggetto CreateCustomerResponse. Puoi recuperare l'ID cliente dalla risposta.


Rivendica un gruppo di dispositivi

La rivendicazione di un dispositivo crea un'associazione tra il dispositivo e un cliente. Ad esempio, se vendi un lotto di dispositivi a un cliente, devi rivendicare i dispositivi per quel cliente.

L'esempio mostra un modo per elaborare un batch di dispositivi che include gli ordini di dispositivi di più produttori (Samsung e altri dispositivi Android) da più clienti.

Passaggio 1: organizza dispositivi e clienti

Data una tabella di IMEI, produttori e ID dei clienti a cui sono stati venduti i dispositivi, un modo per gestire gli ordini è organizzarli in due elenchi: ordini di dispositivi Samsung e ordini di altri dispositivi Android (non Samsung). Poi, per ogni elenco, raggruppa i dispositivi per cliente. Ad esempio:

Dispositivi Samsung

Nome del cliente ID cliente Samsung Knox Produttore IMEI
ABC corp 11 Samsung

1234567801

1234567802

Altri dispositivi Android

Nome del cliente ID cliente Produttore IMEI
ABC corp 21 Google 1234567803
XYZ corp 22 Sony

1234567804

1234567805

Passaggio 2: crea l'oggetto ClaimDevicesRequest

Dispositivi 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();

Altri dispositivi 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();

Passaggio 3: richiedi i dispositivi per i clienti

Per richiedere i dispositivi per i clienti, chiama il numero ClaimDevicesAsync. Questo esempio richiede due richieste separate: una dall'oggetto Samsung ResellerService e una dall'oggetto ResellerService di Google.

// Samsung devices
ClaimDevicesResponse samsungResponse = samsungResellerService.claimDevicesAsync(claimSamsungDevicesRequest);

// Other Android devices
ClaimDevicesResponse googleResponse = googleResellerService.claimDevicesAsync(claimGoogleDevicesRequest);

Una richiesta ClaimDevicesAsync restituisce un elenco di oggetti Operation, che contengono lo stato della richiesta (in corso, completata, completata con errori o non riuscita). Per controllare lo stato di un'operazione (ad esempio, se la risposta è stata IN_PROGRESS), chiama 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);

Annullare la rivendicazione di un batch di dispositivi

Se annulli la rivendicazione di un dispositivo, il dispositivo viene scollegato da un cliente. Potresti dover annullare la rivendicazione di un dispositivo se l'ordine di un dispositivo viene annullato o se non è possibile completare una spedizione di dispositivi. Per annullare la rivendicazione di un gruppo di dispositivi, segui questi passaggi:

Passaggio 1: crea l'oggetto UnclaimDevicesRequest

Dispositivi 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();

Altri dispositivi 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();

Passaggio 2: annulla la rivendicazione dei dispositivi

Per annullare la rivendicazione dei dispositivi, chiama UnclaimDevicesAsync. Questo esempio richiede due richieste separate: una dall'oggetto ResellerService Samsung e una dall'oggetto ResellerService Google.

UnclaimDevicesResponse samsungResponse = samsungResellerService.unclaimDevicesAsync(unclaimSamsungDevicesRequest);
UnclaimDevicesResponse googleResponse = googleResellerService.unclaimDevicesAsync(unclaimGoogleDevicesRequest);

Una richiesta UnclaimDevicesAsync restituisce un elenco di oggetti Operation, che contengono lo stato della richiesta (in corso, completata, completata con errori o non riuscita). Per controllare lo stato di un'operazione (ad esempio, se la risposta ha restituito IN_PROGRESS), chiama getOperation.

Dispositivi Samsung

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

Altri dispositivi Android

GetOperationRequest googleOperationRequest = GetOperationRequest.newBuilder().setOperationId(googleOperationId).build();
Operation googleOperation = googleResellerService.getOperation(googleOperationRequest);

Sostituire un dispositivo Samsung

Se un dispositivo deve essere sostituito per qualsiasi motivo, puoi cambiarlo. Questo esempio presuppone che tu stia per cambiare un dispositivo Samsung con un altro dispositivo Samsung.

Passaggio 1: crea un oggetto 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();

Passaggio 2: chiama UnclaimDeviceAsync

UnclaimDevicesResponse samsungResponse = samsungResellerService.unclaimDevicesAsync(unclaimSamsungDevicesRequest);

Una richiesta UnclaimDevicesAsync restituisce un elenco di oggetti Operation, che contengono lo stato della richiesta (in corso, completata, completata con errori o non riuscita). Per controllare lo stato di un'operazione (ad esempio, se la risposta è stata IN_PROGRESS), chiama getOperation:

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

Passaggio 3: crea un oggetto 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();

Passaggio 4: chiama ClaimDeviceAsync

ClaimDevicesResponse samsungResponse = samsungResellerService.claimDevicesAsync(claimSamsungDevicesRequest);

Una richiesta ClaimDevicesAsync restituisce un elenco di oggetti Operation, che contengono lo stato della richiesta (in corso, completata, completata con errori o non riuscita). Per controllare lo stato di un'operazione (ad esempio, se la risposta è stata IN_PROGRESS), chiama getOperation:

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

Sostituire un dispositivo Android (non Samsung)

Se un dispositivo deve essere sostituito per qualsiasi motivo, puoi cambiarlo. Questo esempio presuppone che tu stia per cambiare un dispositivo Android (diverso da Samsung) con un altro dispositivo Android (diverso da Samsung).

Passaggio 1: crea un oggetto UnclaimDeviceRequest

UnclaimDeviceRequest unclaimGoogleDeviceRequest = UnclaimDeviceRequest.newBuilder()
    .setUnclaim(
        DeviceUnclaim.newBuilder()
            .setDeviceIdentifier(
                DeviceIdentifier.newBuilder()
                    .setImei("1234567803")
                    .build())
            .build())
    .build();

Passaggio 2: chiama UnclaimDevice

googleResponse = googleResellerService.unclaimDevice(unclaimGoogleDeviceRequest);

Passaggio 3: crea un oggetto 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();

Passaggio 4: chiama ClaimDevice

ClaimDeviceResponse response = googleResellerService.claimDevice(claimGoogleDeviceRequest);

In caso di esito positivo, la chiamata restituisce un oggetto ClaimDeviceResponse contenente il valore deviceId. In caso contrario, viene generata un'eccezione comune contenente un codice di errore.