Como funciona

Introdução

A API de registro sem toque ajuda os revendedores a automatizar a integração. As ferramentas de vendas da sua organização podem incorporar o registro sem toque, tornando seus usuários e clientes mais produtivos. Use a API para ajudar seus usuários a:

• Atribua os dispositivos comprados à conta de registro sem toque de um cliente.
• Criação da conta de registro sem toque para clientes
• Anexe o telefone da sua organização e os metadados de pedidos aos dispositivos.
• Criação de relatórios sobre dispositivos atribuídos aos seus clientes

Este documento apresenta a API e explica os padrões. Para explorar a API por conta própria, confira um guia de início rápido para Java, .NET ou Python.

Conceitos da API

Os clientes e os dispositivos são os principais recursos que você usa na API. Para criar clientes, chame create. Você pode criar dispositivos usando os métodos da API de declaração (veja abaixo). Sua organização também pode criar clientes e dispositivos usando o portal de registro sem toque.

Cliente

Empresas para que sua organização vende dispositivos Os clientes têm um name e um ID. Use um cliente quando quiser reivindicar ou encontrar o dispositivo dele. Para saber mais, consulte Customer.

Dispositivo

Um dispositivo Android ou ChromeOS com registro sem toque que sua organização vende para um cliente. Os dispositivos têm IDs de hardware, metadados e declarações do cliente. Os dispositivos são essenciais para a API, então eles podem ser usados em quase todos os métodos. Para saber mais, consulte Device.

DeviceIdentifier

Encapsula os IDs de hardware, como IMEI ou MEID, para identificar um dispositivo fabricado. Use um DeviceIdentifier para segmentar o dispositivo que você quer encontrar, atualizar ou reivindicar. Para saber mais, leia Identificadores.

DeviceMetadata

Armazena pares de chave-valor de metadados do dispositivo. Use DeviceMetadata para armazenar os metadados da sua organização. Para saber mais, leia Metadados do dispositivo.

Para listar todos os métodos e recursos da API que seu app pode usar, consulte a Referência da API.

Criar clientes

Para dispositivos Android, o revendedor é responsável por criar a conta do cliente em nome do cliente. O cliente usará essa conta para acessar o portal sem toque e definir as configurações de provisionamento para os dispositivos. Isso não é necessário para dispositivos ChromeOS que já têm uma conta do Google Workspace e serão usados para definir as configurações de provisionamento.

Chame o método create da API para criar contas de cliente para o registro sem toque. Como os clientes veem o nome da empresa no portal de registro sem toque, o usuário do app precisa confirmar se ele está correto. Não é possível editar o nome de um cliente depois de criá-lo.

Você precisa incluir pelo menos um endereço de e-mail corporativo associado a uma Conta do Google para ser o proprietário. Não é possível usar contas pessoais do Gmail com a API. Se o cliente precisar de ajuda para associar a conta, envie as instruções em Associar uma Conta do Google.

Observação :a API retorna um erro quando um ou mais endereços de e-mail não estão associados a uma Conta do Google. Quando isso acontecer, peça ao usuário para verificar se há uma Conta do Google para cada endereço de e-mail. O Google não fornece uma API para verificar se um endereço de e-mail está associado a uma Conta do Google.

Depois que você cria um cliente chamando a API, ele gerencia o acesso dos funcionários ao portal. Não é possível editar os usuários dos clientes usando a API. O snippet abaixo mostra como criar um cliente:

Java

// Provide the customer data as a Company type.
// The API requires a name and owners.
Company customer = new Company();
customer.setCompanyName("XYZ Corp");
customer.setOwnerEmails(Arrays.asList("[e-mail]", "[e-mail]"));
customer.setAdminEmails(Collections.singletonList("[e-mail]"));

// Use our reseller ID for the parent resource name.
String parentResource = String.format("partners/%d", PARTNER_ID);

// Call the API to create the customer using the values in the company object.
CreateCustomerRequest body = new CreateCustomerRequest();
body.setCustomer(customer);
Company response = service.partners().customers().create(parentResource, body).execute();

.NET

// Provide the customer data as a Company type.
// The API requires a name and owners.
var customer = new Company
{
    CompanyName = "XYZ Corp",
    OwnerEmails = new String[] { "[e-mail]", "[e-mail]" },
    AdminEmails = new String[] { "[e-mail]" }
};

// Use our reseller ID for the parent resource name.
var parentResource = String.Format("partners/{0}", PartnerId);

// Call the API to create the customer using the values in the company object.
var body = new CreateCustomerRequest
{
    Customer = customer
};
var request = service.Partners.Customers.Create(body, parentResource);
var response = request.Execute();

Python

# Provide the customer data as a Company type. The API requires
# a name and at least one owner.
company = {'companyName':'XYZ Corp', \
  'ownerEmails':['[e-mail]', '[e-mail]'], \
  'adminEmails':['[e-mail]']}

# Use our reseller ID for the parent resource name.
parent_resource = 'partners/{0}'.format(PARTNER_ID)

# Call the API to create the customer using the values in the company object.
response = service.partners().customers().create(parent=parent_resource,
    body={'customer':company}).execute()

Para saber mais sobre os papéis de proprietário e administrador para funcionários do cliente, leia Usuários do portal.

Reivindicar dispositivos para clientes

Depois que seus clientes comprarem dispositivos, eles vão precisar definir configurações de provisionamento para esses dispositivos na própria conta. A reivindicação adiciona o dispositivo ao registro sem toque e permite que o cliente defina configurações de provisionamento.

O registro de provisionamento de um dispositivo tem uma seção para o registro sem toque. Você atribui o dispositivo reivindicando a seção de registro sem toque do registro para um cliente. Chame os métodos partners.devices.claim ou partners.devices.claimAsync com o cliente como argumento. Sempre forneça SECTION_TYPE_ZERO_TOUCH como um valor para sectionType.

É necessário cancelar a reivindicação (veja abaixo) do dispositivo de um cliente antes de reivindicar o mesmo dispositivo para outro cliente. Os métodos de declaração validate os campos DeviceIdentifier, incluindo o IMEI, MEID ou o número de série, o nome do fabricante e modelo, além do ID atestado para dispositivos ChromeOS ao criar um novo dispositivo.

O snippet abaixo mostra como reivindicar um dispositivo:

Java

// Identify the device to claim.
DeviceIdentifier identifier = new DeviceIdentifier();
// The manufacturer value is optional but recommended for cellular devices
identifier.setManufacturer("Google");
identifier.setImei("098765432109875");

// Create the body to connect the customer with the device.
ClaimDeviceRequest body = new ClaimDeviceRequest();
body.setDeviceIdentifier(identifier);
body.setCustomerId(customerId);
body.setSectionType("SECTION_TYPE_ZERO_TOUCH");

// Claim the device.
ClaimDeviceResponse response = service.partners().devices().claim(PARTNER_ID, body).execute();

.NET

// Identify the device to claim.
var deviceIdentifier = new DeviceIdentifier
{
    // The manufacturer value is optional but recommended for cellular devices
    Manufacturer = "Google",
    Imei = "098765432109875"
};

// Create the body to connect the customer with the device.
ClaimDeviceRequest body = new ClaimDeviceRequest
{
    DeviceIdentifier = deviceIdentifier,
    CustomerId = CustomerId,
    SectionType = "SECTION_TYPE_ZERO_TOUCH"
};

// Claim the device.
var response = service.Partners.Devices.Claim(body, PartnerId).Execute();

Python

# Identify the device to claim.
# The manufacturer value is optional but recommended for cellular devices
device_identifier = {'manufacturer':'Google', 'imei':'098765432109875'}

# Create the body to connect the customer with the device.
request_body = {'deviceIdentifier':device_identifier, \
    'customerId':customer_id, \
    'sectionType':'SECTION_TYPE_ZERO_TOUCH'}

# Claim the device.
response = service.partners().devices().claim(partnerId=PARTNER_ID,
    body=request_body).execute()

Removendo reivindicação do dispositivo

Sua organização pode cancelar a reivindicação de um dispositivo de um cliente. Cancelar a reivindicação de um dispositivo o remove do registro sem toque. Um revendedor pode cancelar a reivindicação de um dispositivo que ele quer migrar para outra conta, seja devolvido ou reivindicado por engano. Chame o método partners.devices.unclaim ou partners.devices.unclaimAsync para cancelar a reivindicação de um dispositivo de um cliente.

Cuidado: solicite que o usuário do seu app confirme se tem o dispositivo correto antes de chamar APIs de cancelamento de reivindicação. Cancelar a reivindicação de um dispositivo remove a configuração de provisionamento do cliente e o dispositivo deixa de ser gerenciado após a redefinição para a configuração original.

Fornecedores

É possível usar fornecedores para representar parceiros revendedores na sua rede de revendedores, operadores locais em uma rede de revendedores global ou qualquer organização que venda dispositivos em seu nome. Os fornecedores ajudam a separar seus usuários, clientes e dispositivos:

• Os fornecedores criados não podem ver sua conta de registro sem toque ou as contas uns dos outros.
• É possível visualizar os clientes e dispositivos dos seus fornecedores e cancelar o registro dos dispositivos deles. No entanto, não é possível atribuir dispositivos aos clientes dos seus fornecedores.

Importante :um fornecedor é um tipo especial de revendedor. Os fornecedores aparecem e se comportam (no portal e nas APIs) da mesma forma que um revendedor, exceto que um fornecedor não pode ter outros.

Use o portal para criar fornecedores para sua organização. Não é possível usar a API. O papel da conta precisa ser Proprietário para criar um novo fornecedor. Se sua organização tiver fornecedores, chame partners.vendors.list para listar seus fornecedores e partners.vendors.customers.list para conseguir os clientes deles. O exemplo a seguir usa esses dois métodos para imprimir um relatório que mostra o status dos Termos de Serviço para os clientes dos fornecedores:

Java

// First, get the organization's vendors.
String parentResource = String.format("partners/%d", PARTNER_ID);
ListVendorsResponse results = service.partners().vendors().list(parentResource).execute();
if (results.getVendors() == null) {
  return;
}

// For each vendor, report the company name and a maximum 5 customers.
for (Company vendor: results.getVendors()) {
  System.out.format("\n%s customers\n", vendor.getCompanyName());
  System.out.println("---");
  // Use the vendor's API resource name as the parent resource.
  AndroidProvisioningPartner.Partners.Vendors.Customers.List customerRequest =
      service.partners().vendors().customers().list(vendor.getName());
  customerRequest.setPageSize(5);
  ListVendorCustomersResponse customerResponse = customerRequest.execute();

  List<Company> customers = customerResponse.getCustomers();
  if (customers == null) {
    System.out.println("No customers");
    break;
  } else {
    for (Company customer: customers) {
      System.out.format("%s: %s\n",
          customer.getCompanyName(),
          customer.getTermsStatus());
    }
  }
}

.NET

// First, get the organization's vendors.
var parentResource = String.Format("partners/{0}", PartnerId);
var results = service.Partners.Vendors.List(parentResource).Execute();
if (results.Vendors == null)
{
    return;
}

// For each vendor, report the company name and a maximum 5 customers.
foreach (Company vendor in results.Vendors)
{
    Console.WriteLine("\n{0} customers", vendor);
    Console.WriteLine("---");
    // Use the vendor's API resource name as the parent resource.
    PartnersResource.VendorsResource.CustomersResource.ListRequest customerRequest =
        service.Partners.Vendors.Customers.List(vendor.Name);
    customerRequest.PageSize = 5;
    var customerResponse = customerRequest.Execute();

    IList<Company> customers = customerResponse.Customers;
    if (customers == null)
    {
        Console.WriteLine("No customers");
        break;
    }
    else
    {
        foreach (Company customer in customers)
        {
            Console.WriteLine("{0}: {1}", customer.Name, customer.TermsStatus);
        }
    }
}

Python

# First, get the organization's vendors.
parent_resource = 'partners/{0}'.format(PARTNER_ID)
vendor_response = service.partners().vendors().list(
    parent=parent_resource).execute()
if 'vendors' not in vendor_response:
  return

# For each vendor, report the company name and a maximum 5 customers.
for vendor in vendor_response['vendors']:
  print '\n{0} customers'.format(vendor['companyName'])
  print '---'
  # Use the vendor's API resource name as the parent resource.
  customer_response = service.partners().vendors().customers().list(
      parent=vendor['name'], pageSize=5).execute()
  if 'customers' not in customer_response:
    print 'No customers'
    break
  for customer in customer_response['customers']:
    print '  {0}: {1}'.format(customer['name'], customer['termsStatus'])

Se você tiver uma coleção de dispositivos, talvez precise saber qual revendedor ou fornecedor reivindicou o dispositivo. Para conseguir o ID numérico do revendedor, inspecione o valor do campo resellerId no registro de declaração de um dispositivo.

Sua organização pode cancelar a reivindicação de um dispositivo reivindicado pelo fornecedor. Para outras chamadas de API que modificam dispositivos, verifique se a organização reivindicou o dispositivo antes de chamar o método da API. O exemplo a seguir mostra como fazer isso:

Java

// Get the devices claimed for two customers: one of our organization's
// customers and one of our vendor's customers.
FindDevicesByOwnerRequest body = new FindDevicesByOwnerRequest();
body.setSectionType("SECTION_TYPE_ZERO_TOUCH");
body.setCustomerId(Arrays.asList(resellerCustomerId, vendorCustomerId));
body.setLimit(MAX_PAGE_SIZE);
FindDevicesByOwnerResponse response =
    service.partners().devices().findByOwner(PARTNER_ID, body).execute();
if (response.getDevices() == null) {
  return;
}

for (Device device: response.getDevices()) {
  // Confirm the device was claimed by our reseller and not a vendor before
  // updating metadata in another method.
  for (DeviceClaim claim: device.getClaims()) {
    if (claim.getResellerId() == PARTNER_ID) {
      updateDeviceMetadata(device.getDeviceId());
      break;
    }
  }
}

.NET

// Get the devices claimed for two customers: one of our organization's
// customers and one of our vendor's customers.
FindDevicesByOwnerRequest body = new FindDevicesByOwnerRequest
{
    Limit = MaxPageSize,
    SectionType = "SECTION_TYPE_ZERO_TOUCH",
    CustomerId = new List<long?>
    {
        resellerCustomerId,
        vendorCustomerId
    }
};
var response = service.Partners.Devices.FindByOwner(body, PartnerId).Execute();
if (response.Devices == null)
{
    return;
}

foreach (Device device in response.Devices)
{
    // Confirm the device was claimed by our reseller and not a vendor before
    // updating metadata in another method.
    foreach (DeviceClaim claim in device.Claims)
    {
        if (claim.ResellerId == PartnerId)
        {
            UpdateDeviceMetadata(device.DeviceId);
            break;
        }
    }
}

Python

# Get the devices claimed for two customers: one of our organization's
# customers and one of our vendor's customers.
request_body = {'limit':MAX_PAGE_SIZE, \
  'pageToken':None, \
  'customerId':[reseller_customer_id, vendor_customer_id], \
  'sectionType':'SECTION_TYPE_ZERO_TOUCH'}
response = service.partners().devices().findByOwner(partnerId=PARTNER_ID,
    body=request_body).execute()

for device in response['devices']:
  # Confirm the device was claimed by our reseller and not a vendor before
  # updating metadata in another method.
  for claim in device['claims']:
    if claim['resellerId'] == PARTNER_ID:
      update_device_metadata(device['deviceId'])
      break

Operações em lote de longa duração

A API inclui versões assíncronas dos métodos do dispositivo. Esses métodos permitem o processamento em lote de muitos dispositivos, enquanto os métodos síncronos processam um dispositivo para cada solicitação de API. Os nomes de métodos assíncronos têm um sufixo Async, por exemplo, claimAsync.

Métodos de API assíncronos retornam um resultado antes da conclusão do processamento. Métodos assíncronos também ajudam seu app (ou ferramenta) a permanecer responsivo para os usuários enquanto eles aguardam a conclusão de uma operação de longa duração. Seu app precisa verificar o status da operação periodicamente.

Operações

Use um Operation para rastrear uma operação em lote de longa duração. Uma chamada bem-sucedida para um método assíncrono retorna uma referência à operação na resposta. O snippet JSON abaixo mostra uma resposta típica depois de chamar updateMetadataAsync:

{
  "name": "operations/apibatchoperation/1234567890123476789"
}

Cada operação contém uma lista de tarefas individuais. Chame operations.get para descobrir informações sobre o status e os resultados das tarefas contidas na operação. O snippet abaixo mostra como você pode fazer isso. No seu próprio app, será necessário resolver todos os erros.

Java

// Build out the request body to apply the same order number to a customer's
// purchase of 2 devices.
UpdateMetadataArguments firstUpdate = new UpdateMetadataArguments();
firstUpdate.setDeviceMetadata(metadata);
firstUpdate.setDeviceId(firstTargetDeviceId);

UpdateMetadataArguments secondUpdate = new UpdateMetadataArguments();
secondUpdate.setDeviceMetadata(metadata);
secondUpdate.setDeviceId(firstTargetDeviceId);

// Start the device metadata update.
UpdateDeviceMetadataInBatchRequest body = new UpdateDeviceMetadataInBatchRequest();
body.setUpdates(Arrays.asList(firstUpdate, secondUpdate));
Operation response = service
    .partners()
    .devices()
    .updateMetadataAsync(PARTNER_ID, body)
    .execute();

// Assume the metadata update started, so get the Operation for the update.
Operation operation = service.operations().get(response.getName()).execute();

.NET

// Build out the request body to apply the same order number to a customer's
// purchase of 2 devices.
var updates = new List<UpdateMetadataArguments>
{
    new UpdateMetadataArguments
    {
        DeviceMetadata = metadata,
        DeviceId = firstTargetDeviceId
    },
    new UpdateMetadataArguments
    {
        DeviceMetadata = metadata,
        DeviceId = secondTargetDeviceId
    }
};

// Start the device metadata update.
UpdateDeviceMetadataInBatchRequest body = new UpdateDeviceMetadataInBatchRequest
{
    Updates = updates
};
var response = service.Partners.Devices.UpdateMetadataAsync(body, PartnerId).Execute();

// Assume the metadata update started, so get the Operation for the update.
Operation operation = service.Operations.Get(response.Name).Execute();

Python

# Build out the request body to apply the same order number to a customer's
# purchase of 2 devices.
updates = [{'deviceMetadata':metadata,'deviceId':first_target_device_id},
    {'deviceMetadata':metadata,'deviceId':second_target_device_id}]

# Start the device metadata update.
response = service.partners().devices().updateMetadataAsync(
    partnerId=PARTNER_ID, body={'updates':updates}).execute()

# Assume the metadata update started, so get the Operation for the update.
operation = service.operations().get(name=response['name']).execute()

Para descobrir se uma operação foi concluída, verifique se há um campo done com um valor de true na operação. Se done estiver ausente ou false, a operação ainda estará em execução.

Respostas

Após a conclusão de uma operação, a API a atualiza com o resultado, mesmo que todas ou nenhuma das tarefas individuais sejam bem-sucedidas. O campo response é um objeto DevicesLongRunningOperationResponse que detalha o processamento de cada dispositivo na operação.

Inspecione o campo successCount para descobrir de maneira eficiente se alguma tarefa falhou e evitar a iteração em grandes listas de resultados. O campo perDeviceStatus de DevicesLongRunningOperationResponse é uma lista de instâncias de OperationPerDevice que detalham cada dispositivo na operação. A ordem da lista corresponde às tarefas na solicitação original.

Cada tarefa OperationPerDevice contém um campo result e um resumo do lembrete da solicitação recebida pelo servidor. Use o campo result para verificar se a tarefa foi bem-sucedida ou falhou.

O snippet JSON abaixo mostra parte de uma resposta típica de uma operação após uma chamada para updateMetadataAsync:

"response": {
  "perDeviceStatus": [
    {
      "result": {
        "deviceId": "12345678901234567",
        "status": "SINGLE_DEVICE_STATUS_SUCCESS"
      },
      "updateMetadata": {
        "deviceId": "12345678901234567",
        "deviceMetadata": {
          "entries": {
            "phonenumber": "[phone]"
          }
        }
      }
    }
  ],
  "successCount": 1
}

Acompanhe o progresso.

Se o app precisar rastrear o progresso, busque novamente a operação periodicamente. O campo metadata contém uma instância DevicesLongRunningOperationMetadata para ajudar seu app a verificar o progresso mais recente de uma operação em execução. Use os campos de DevicesLongRunningOperationMetadata listados na tabela a seguir para acompanhar o progresso da operação:

Campo	Uso normal
processingStatus	Muda de BATCH_PROCESS_PENDING para BATCH_PROCESS_IN_PROGRESS e, em seguida, para BATCH_PROCESS_PROCESSED conforme a operação avança.
progress	É a porcentagem de atualizações processadas. Seu app pode usar isso para estimar o tempo de conclusão. Como o valor progress pode ser 100 enquanto a operação está terminando, verifique o campo done de uma operação para saber se ela foi concluída e tem um resultado.
devicesCount	Mostra o número de atualizações na operação. Esse número poderá ser diferente do número de atualizações da solicitação se a API não puder analisar algumas das atualizações.

O exemplo simplificado abaixo mostra como um app pode usar os metadados de progresso para definir intervalos de pesquisa. No seu app, talvez você precise de um executor de tarefas mais sofisticado para a pesquisa. Também é necessário adicionar tratamento de erros.

Java

// Milliseconds between polling the API.
private static long MIN_INTERVAL = 2000;
private static long MAX_INTERVAL = 10000;

// ...
// Start the device metadata update.
Operation response = service
    .partners()
    .devices()
    .updateMetadataAsync(PARTNER_ID, body)
    .execute();
String operationName = response.getName();

// Start polling for completion.
long startTime = new Date().getTime();
while (true) {

  // Get the latest update on the operation's progress using the API.
  Operation operation = service.operations().get(operationName).execute();

  if (operation.get("done") != null && operation.getDone()) {
    // The operation is finished. Print the status.
    System.out.format("Operation complete: %s of %s successful device updates\n",
        operation.getResponse().get("successCount"),
        operation.getMetadata().get("devicesCount"));
    break;

  } else {
    // Estimate how long the operation *should* take - within min and max value.
    BigDecimal opProgress = (BigDecimal) operation.getMetadata().get("progress");
    double progress = opProgress.longValue();
    long interval = MAX_INTERVAL;
    if (progress > 0) {
      interval = (long) ((new Date().getTime() - startTime) *
          ((100.0 - progress) / progress));
    }
    interval = Math.max(MIN_INTERVAL, Math.min(interval, MAX_INTERVAL));

    // Sleep until the operation should be complete.
    Thread.sleep(interval);
  }
}

.NET

// Milliseconds between polling the API.
private static double MinInterval = 2000;
private static double MaxInterval = 10000;

// ...
// Start the device metadata update.
var response = service.Partners.Devices.UpdateMetadataAsync(body, PartnerId).Execute();
var operationName = response.Name;

// Start polling for completion.
var startTime = DateTime.Now;
while (true)
{

    // Get the latest update on the operation's progress using the API.
    Operation operation = service.Operations.Get(operationName).Execute();

    if (operation.Done == true)
    {
        // The operation is finished. Print the status.
        Console.WriteLine("Operation complete: {0} of {1} successful device updates",
                          operation.Response["successCount"],
                          operation.Metadata["devicesCount"]);
        break;
    }
    else
    {
        // Estimate how long the operation *should* take - within min and max value.
        double progress = (double)(long)operation.Metadata["progress"];
        double interval = MaxInterval;
        if (progress > 0)
        {
            interval = DateTime.Now.Subtract(startTime).TotalMilliseconds *
                                     ((100.0 - progress) / progress);
        }
        interval = Math.Max(MinInterval, Math.Min(interval, MaxInterval));

        // Sleep until the operation should be complete.
        System.Threading.Thread.Sleep((int)interval);
    }
}

Python

# Seconds between polling the API.
MIN_INTERVAL = 2;
MAX_INTERVAL = 10;

# ...
# Start the device metadata update
response = service.partners().devices().updateMetadataAsync(
  partnerId=PARTNER_ID, body={'updates':updates}).execute()

op_name = response['name']
start_time = time.time()

# Start polling for completion
while True:
  # Get the latest update on the operation's progress using the API
  op = service.operations().get(name=op_name).execute()

  if 'done' in op and op['done']:
    # The operation is finished. Print the status.
    print('Operation complete: {0} of {1} successful device updates'.format(
      op['response']['successCount'], op['metadata']['devicesCount']
    ))
    break
  else:
    # Estimate how long the operation *should* take - within min and max.
    progress = op['metadata']['progress']
    interval = MIN_INTERVAL
    if progress > 0:
      interval = (time.time() - start_time) * ((100.0 - progress) / progress)
    interval = max(MIN_INTERVAL, min(interval, MAX_INTERVAL))

    # Sleep until the operation should be complete.
    time.sleep(interval)

Escolha uma abordagem de pesquisa que faça sentido para os usuários do seu app. Alguns usuários do app podem se beneficiar de atualizações regulares de progresso se estiverem aguardando a conclusão de um processo.

Resultados paginados

O método partners.devices.findByOwner da API pode retornar listas muito grandes de dispositivos. Para reduzir o tamanho da resposta, este e outros métodos de API (como partners.devices.findByIdentifier) são compatíveis com resultados paginados. Com os resultados paginados, seu aplicativo pode solicitar e processar listas grandes de maneira iterativa, uma página por vez.

Depois de chamar o método da API, verifique se a resposta inclui um valor para nextPageToken. Se nextPageToken não for null, o app poderá usá-lo para buscar outra página de dispositivos chamando o método novamente. É necessário definir um limite máximo para o número de dispositivos no parâmetro limit. Se nextPageToken for null, isso significa que o app solicitou a última página.

O método de exemplo abaixo mostra como seu app pode imprimir uma lista de dispositivos, uma página por vez:

Java

private static long MAX_PAGE_SIZE = 10;

// ...
/**
 * Demonstrates how to loop through paginated lists of devices.
 * @param pageToken       The token specifying which result page to return.
 * @throws IOException    If the zero-touch API call fails.
 */
private void printDevices(String pageToken) throws IOException {

  // Create the request body to find the customer's devices.
  FindDevicesByOwnerRequest body = new FindDevicesByOwnerRequest();
  body.setLimit(MAX_PAGE_SIZE);
  body.setSectionType("SECTION_TYPE_ZERO_TOUCH");
  body.setCustomerId(Collections.singletonList(targetCustomerId));

  // Call the API to get a page of Devices. Send a page token from the method
  // argument (might be None). If the page token is None, the API returns the first page.
  FindDevicesByOwnerResponse response =
      service.partners().devices().findByOwner(PARTNER_ID, body).execute();
  if (response.getDevices() == null) {
    return;
  }

  // Print the devices included in this page of results.
  for (Device device: response.getDevices()) {
    System.out.format("Device %s\n", device.getName());
  }
  System.out.println("---");

  // Check to see if another page of devices is available. If yes,
  // fetch and print the devices.
  if (response.getNextPageToken() != null) {
    this.printDevices(response.getNextPageToken());
  }
}

// ...
// Pass null to start printing the first page of devices.
printDevices(null);

.NET

private static int MaxPageSize = 10;

// ...
/// <summary>Demonstrates how to loop through paginated lists of devices.</summary>
/// <param name="pageToken">The token specifying which result page to return.</param>
private void PrintDevices(string pageToken)
{
    // Create the request body to find the customer's devices.
    FindDevicesByOwnerRequest body = new FindDevicesByOwnerRequest
    {
        PageToken = pageToken,
        Limit = MaxPageSize,
        SectionType = "SECTION_TYPE_ZERO_TOUCH",
        CustomerId = new List<long?>
        {
            targetCustomerId
        }
    };

    // Call the API to get a page of Devices. Send a page token from the method
    // argument (might be None). If the page token is None, the API returns the first page.
    var response = service.Partners.Devices.FindByOwner(body, PartnerId).Execute();
    if (response.Devices == null)
    {
        return;
    }

    // Print the devices included in this page of results.
    foreach (Device device in response.Devices)
    {
        Console.WriteLine("Device: {0}", device.Name);
    }
    Console.WriteLine("---");

    // Check to see if another page of devices is available. If yes,
    // fetch and print the devices.
    if (response.NextPageToken != null)
    {
        this.PrintDevices(response.NextPageToken);
    }
}

// ...
// Pass null to start printing the first page of devices.
PrintDevices(null);

Python

MAX_PAGE_SIZE = 10;

# ...
def print_devices(page_token):
  """Demonstrates how to loop through paginated lists of devices.

  Args:
    page_token: The token specifying which result page to return.
  """

   # Create the body to find the customer's devices.
  request_body = {'limit':MAX_PAGE_SIZE, \
    'pageToken':page_token, \
    'customerId':[target_customer_id], \
    'sectionType':'SECTION_TYPE_ZERO_TOUCH'}

  # Call the API to get a page of Devices. Send a page token from the method
  # argument (might be None). If the page token is None,
  # the API returns the first page.
  response = service.partners().devices().findByOwner(partnerId=PARTNER_ID,
    body=request_body).execute()

  # Print the devices included in this page of results.
  for device in response['devices']:
    print 'Device: {0}'.format(device['name'])
  print '---'

  # Check to see if another page of devices is available. If yes,
  # fetch and print the devices.
  if 'nextPageToken' in response:
    print_devices(response['nextPageToken'])

# ...
# Pass None to start printing the first page of devices.
print_devices(None);

Próximas etapas

Agora que você sabe como a API funciona, teste os exemplos com um guia de início rápido para Java, .NET ou Python.