Operações comuns

Esta página fornece exemplos de algumas operações comuns que podem ser realizadas com a biblioteca comum de revendedor do Android, incluindo as seguintes:

Criar objetos ResellerService

Use as classes de fábrica da Samsung e do Google para criar objetos ResellerService. Com objetos ResellerService, um conjunto comum de métodos está disponível para registrar Samsung e outros dispositivos Android.

Dispositivos Samsung

O exemplo abaixo mostra como criar um objeto ResellerService usando a classe SamsungResellerServiceFactory para gerenciar dispositivos Samsung.

Antes de fazer isso, você precisa integrar ao Programa de implantação do Knox (KDP).

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

Outros dispositivos Android

O exemplo abaixo mostra como criar um objeto ResellerService usando a classe GoogleResellerServiceFactory para gerenciar outros dispositivos Android que não sejam da Samsung. Antes de fazer isso, siga as etapas em Primeiros passos para o registro sem toque para receber o resellerId e a chave de conta de serviço.

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

Criar objetos Customer

Um cliente que compra dispositivos Samsung e outros dispositivos exige dois IDs de cliente.

Dispositivos Samsung

Para gerenciar dispositivos Samsung, use o ID de cliente Knox do cliente. Para conseguir o ID de cliente Knox, primeiro você precisa criar um objeto Customer. Para fazer isso, chame createCustomer usando um SamsungResellerService criado no SamsungResellerServiceFactory. Veja um exemplo:

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 for bem-sucedida, a solicitação retornará um objeto CreateCustomerResponse, de onde é possível extrair o ID de cliente do Knox.

Outros dispositivos Android

Para outros dispositivos Android, o cliente exige um ID de registro sem toque. Se um cliente já usar o registro sem toque com outro revendedor, você usará o ID de cliente atual dele. Caso contrário, você precisará criar um objeto Customer. Para fazer isso, chame createCustomer usando um ResellerService criado no GoogleResellerServiceFactory. Veja um exemplo:

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

Se for bem-sucedida, a solicitação retornará um objeto CreateCustomerResponse. É possível recuperar o ID do cliente na resposta.

Reivindicar um lote de dispositivos

A reivindicação de um dispositivo cria uma associação entre ele e o cliente. Por exemplo, se você vende um lote de dispositivos para um cliente, precisa reivindicar os dispositivos desse cliente.

Este exemplo mostra uma maneira de processar um lote de dispositivos que inclui pedidos de vários fabricantes (Samsung e outros dispositivos Android) de vários clientes.

Etapa 1: organizar dispositivos e clientes

Considerando uma tabela de IMEIs, fabricantes e IDs de dispositivos dos clientes para os quais os dispositivos foram vendidos, uma maneira de gerenciar pedidos é organizar os pedidos em duas listas: pedidos de dispositivos Samsung e outros pedidos por dispositivos Android (que não sejam da Samsung). Em seguida, para cada lista, agrupe os dispositivos por cliente. Exemplo:

Dispositivos Samsung

Nome do cliente ID de cliente Samsung Knox Fabricante IMEI
Empresa ABC 11 Samsung

1234567801

1234567802

Outros dispositivos Android

Nome do cliente ID de cliente Fabricante IMEI
Empresa ABC 21 Google 1234567803
Empresa XYZ 22 Sony

1234567804

1234567805

Etapa 2: criar o objeto ClaimDevicesRequest

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

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

Etapa 3: reivindicar dispositivos para os clientes

Se quiser reivindicar dispositivos para clientes, ligue para ClaimDevicesAsync. Esse exemplo requer duas solicitações separadas: uma do objeto ResellerService da Samsung e outra do objeto ResellerService do Google.

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

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

Uma solicitação ClaimDevicesAsync retorna uma lista de objetos Operation, que contêm o status da solicitação (em andamento, concluída, com erros ou com falha). Para verificar o status de uma operação (por exemplo, se a resposta retornau IN_PROGRESS), chame 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);

Cancelar a reivindicação de um lote de dispositivos

Se um dispositivo não for reivindicado, ele será desassociado de um cliente. Talvez seja necessário cancelar a reivindicação de um dispositivo se o pedido dele for cancelado ou se a entrega de dispositivos não for concluída. Para cancelar a reivindicação de um lote de dispositivos, siga estas etapas:

Etapa 1: criar o objeto UnclaimDevicesRequest

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

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

Etapa 2: cancelar a reivindicação de dispositivos

Para cancelar a reivindicação de dispositivos, chame UnclaimDevicesAsync. Esse exemplo requer duas solicitações separadas: uma do objeto ResellerService da Samsung e outra do objeto ResellerService do Google.

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

Uma solicitação UnclaimDevicesAsync retorna uma lista de objetos Operation, que contêm o status da solicitação (em andamento, concluída, com erros ou com falha). Para verificar o status de uma operação (por exemplo, se a resposta retornar IN_PROGRESS), chame getOperation.

Dispositivos Samsung

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

Outros dispositivos Android

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

Trocar um dispositivo Samsung

Se um dispositivo precisar ser substituído por qualquer motivo, a troca poderá ser feita. Este exemplo presume que você está trocando um dispositivo Samsung por outro Samsung.

Etapa 1: criar um objeto 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();

Etapa 2: chamar UnclaimDeviceAsync

UnclaimDevicesResponse samsungResponse = samsungResellerService.unclaimDevicesAsync(unclaimSamsungDevicesRequest);

Uma solicitação UnclaimDevicesAsync retorna uma lista de objetos Operation, que contém o status da solicitação (em andamento, concluída, com erros ou com falha). Para verificar o status de uma operação (por exemplo, se a resposta retornar IN_PROGRESS), chame getOperation:

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

Etapa 3: criar um objeto 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();

Etapa 4: chamar ClaimDeviceAsync

ClaimDevicesResponse samsungResponse = samsungResellerService.claimDevicesAsync(claimSamsungDevicesRequest);

Uma solicitação ClaimDevicesAsync retorna uma lista de objetos Operation, que contém o status da solicitação (em andamento, concluída, com erros ou com falha). Para verificar o status de uma operação (por exemplo, se a resposta retornar IN_PROGRESS), chame getOperation:

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

Trocar um dispositivo Android (não Samsung)

Se um dispositivo precisar ser substituído por qualquer motivo, a troca poderá ser feita. Este exemplo presume que você está trocando um dispositivo Android (não Samsung) por outro dispositivo Android (não Samsung).

Etapa 1: criar um objeto UnclaimDeviceRequest

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

Etapa 2: chamar UnclaimDevice

googleResponse = googleResellerService.unclaimDevice(unclaimGoogleDeviceRequest);

Etapa 3: criar um objeto 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();

Etapa 4: chamar ClaimDevice

ClaimDeviceResponse response = googleResellerService.claimDevice(claimGoogleDeviceRequest);

Se for bem-sucedida, a chamada retornará um objeto ClaimDeviceResponse contendo o deviceId. Caso contrário, será gerada uma exceção comum contendo um código de erro.