Como funciona

A API do cliente oferece controle programático de dispositivos e configurações para o registro sem toque do Android. Este documento apresenta a API para provedores de gerenciamento de mobilidade empresarial (EMM) e desenvolvedores de TI empresariais. Depois de ler este documento, entenda os principais recursos usados na API e como eles interagem. Se você não tem experiência com o registro sem toque, leia esta breve introdução do android.com.

Visão geral

A API do cliente ajuda as organizações que compram dispositivos de registro sem toque do Android. Seu app ou ferramenta pode ajudar os administradores de TI a fazer o seguinte:

• Criar, editar e excluir configurações de provisionamento.
• Aplique ou remova uma configuração de um dispositivo.
• Selecione uma configuração padrão para todos os dispositivos adicionados ao registro sem toque a partir de agora.

Com a API, os administradores de TI também podem cancelar a inscrição de dispositivos no registro sem toque. Para gerenciar os usuários da organização ou aceitar os Termos de Serviço, os administradores de TI usam o portal de registro sem toque.

Os usuários típicos dessa API podem ser:

• Provedores de EMM que adicionam suporte ao registro sem toque ao console.
• Desenvolvedores de TI empresariais que criam ferramentas para automatizar tarefas de registro sem toque

Principais recursos

As configurações e os dispositivos são os principais recursos que você usa na API. Uma organização também pode criar configurações e dispositivos usando o portal de registro sem toque.

Configuração

Os administradores de TI usam uma configuração para definir opções de provisionamento para os dispositivos. As configurações incluem políticas de EMM para dispositivos móveis e dados de contato que são exibidos para ajudar os usuários. As configurações são essenciais para a API, e por isso podem ser usadas de vários métodos. Para saber mais, consulte a seção Configurações abaixo.

Dispositivo

Um dispositivo Android com registro sem toque que uma organização comprou de um revendedor. Aplique uma configuração para incluir o dispositivo no registro sem toque. Os dispositivos têm IDs de hardware e metadados anexados. Para saber mais, consulte Dispositivos abaixo.

DPC

Uma referência somente leitura ao DPC de um EMM (controlador de política de dispositivo). Adicione um DPC a uma configuração para selecionar a solução de EMM para dispositivos. Todos os DPCs listados pela API são compatíveis com o registro sem toque e estão disponíveis no Google Play. Para saber mais, consulte Dpc.

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

Configurações

O recurso da API Configuration combina o seguinte:

• O DPC do EMM instalado nos dispositivos.
• Políticas de EMM aplicadas aos dispositivos.
• Dados de contato exibidos no dispositivo para ajudar os usuários durante a configuração.

Com a API, o app pode gerenciar configurações para administradores de TI. Chame a API para buscar, criar, atualizar e excluir configurações. O exemplo abaixo mostra como criar uma nova configuração:

Java

// Add metadata to help the device user during provisioning.
Configuration configuration = new Configuration();
configuration.setConfigurationName("Sales team");
configuration.setCompanyName("XYZ Corp.");
configuration.setContactEmail("[e-mail]");
configuration.setContactPhone("[phone]");
configuration.setCustomMessage("We're setting up your phone. Call or email for help.");

// Set the DPC that zero-touch enrollment downloads and installs from Google Play.
configuration.setDpcResourcePath(dpc.getName());

// Set the JSON-formatted EMM provisioning extras that are passed to the DPC.
configuration.setDpcExtras("{"
      + "\"android.app.extra.PROVISIONING_LEAVE_ALL_SYSTEM_APPS_ENABLED\":true,"
      + "\"android.app.extra.PROVISIONING_ADMIN_EXTRAS_BUNDLE\":{"
      + "\"default_min_password_length\":6,"
      + "\"company_name\":\"XYZ Corp\","
      + "\"management_server\":\"emm.example.com\","
      + "\"terms_url\":\"https://www.example.com/policies/terms/\","
      + "\"allowed_user_domains\":\"[\\\"example.com\\\", \\\"example.org\\\"]\""
      + "}"
      + "}");

// Create the new configuration on the server.
AndroidProvisioningPartner.Customers.Configurations.Create request =
      service.customers().configurations().create(customerAccount, configuration);
Configuration response = request.execute();

.NET

// Add metadata to help the device user during provisioning.
Configuration configuration = new Configuration
{
    ConfigurationName = "Sales team",
    CompanyName = "XYZ Corp.",
    ContactEmail = "[e-mail]",
    ContactPhone = "[phone]",
    CustomMessage = "We're setting up your phone. Call or email for help."
};

// Set the DPC that zero-touch enrollment downloads and installs from Google Play.
configuration.DpcResourcePath = dpc.Name;

// Set the JSON-formatted EMM provisioning extras that are passed to the DPC.
configuration.DpcExtras = @"{
    ""android.app.extra.PROVISIONING_LEAVE_ALL_SYSTEM_APPS_ENABLED"":true,
    ""android.app.extra.PROVISIONING_ADMIN_EXTRAS_BUNDLE"":{
    ""default_min_password_length"":6,
    ""company_name"":""XYZ Corp"",
    ""management_server"":""emm.example.com"",
    ""terms_url"":""https://www.example.com/policies/terms/"",
    ""allowed_user_domains"":""[\""example.com\"", \""example.org\""]""
  }
}";

// Create the new configuration on the server.
var request = service.Customers.Configurations.Create(configuration, customerAccount);
var response = request.Execute();

Python

# Add metadata to help the device user during provisioning.
configuration = {
    'configurationName': 'Sales team',
    'companyName': 'XYZ Corp.',
    'contactEmail': '[e-mail]',
    'contactPhone': '[phone]',
    'customMessage': 'We\'re setting up your phone. Call or email for help.'}

# Set the DPC that zero-touch enrollment installs from Google Play.
configuration['dpcResourcePath'] = dpc['name']

# Set the JSON-formatted EMM provisioning extras that are passed to the DPC.
configuration['dpcExtras'] = '''{
    "android.app.extra.PROVISIONING_LEAVE_ALL_SYSTEM_APPS_ENABLED":true,
    "android.app.extra.PROVISIONING_ADMIN_EXTRAS_BUNDLE":{
      "default_min_password_length":6,
      "company_name":"XYZ Corp",
      "management_server":"emm.example.com",
      "terms_url":"https://www.example.com/policies/terms/",
      "allowed_user_domains":"[\\"example.com\\", \\"example.org\\"]"}
}'''

# Create the new configuration on the server.
response = service.customers().configurations().create(
    parent=customer_account, body=configuration).execute()

Ao atualizar uma configuração usando a API de patch, inclua a máscara de campo ou um valor para cada campo que você não quer que seja null. Consulte Configurações padrão (abaixo) para um exemplo que mostra como atualizar uma configuração com eficiência.

Excluir configurações

Não será possível excluir uma configuração se ela ainda estiver aplicada a dispositivos. Se você tentar excluir uma configuração em uso, o método da API retornará um código de status HTTP 400 Bad Request e uma mensagem explicando quantos dispositivos usam a configuração. Chame customers.devices.removeConfiguration para remover a configuração dos dispositivos antes de tentar novamente.

Configurações padrão

O registro sem toque funciona melhor quando uma organização define uma configuração padrão aplicada a todos os novos dispositivos comprados pela organização. Solicite que os administradores de TI definam uma configuração padrão, se não houver uma. O exemplo abaixo mostra como tornar uma configuração atual padrão, definindo isDefault como true:

Java

// Send minimal data with the request. Just the 2 required fields.
// targetConfiguration is an existing configuration that we want to make the default.
Configuration configuration = new Configuration();
configuration.setIsDefault(true);
configuration.setConfigurationId(targetConfiguration.getConfigurationId());

// Call the API, including the FieldMask to avoid setting other fields to null.
AndroidProvisioningPartner.Customers.Configurations.Patch request = service
      .customers()
      .configurations()
      .patch(targetConfiguration.getName(), configuration);
request.setUpdateMask("isDefault");
Configuration results = request.execute();

.NET

// Send minimal data with the request. Just the 2 required fields.
// targetConfiguration is an existing configuration that we want to make the default.
Configuration configuration = new Configuration
{
    IsDefault = true,
    ConfigurationId = targetConfiguration.ConfigurationId,
};

// Call the API, including the FieldMask to avoid setting other fields to null.
var request = service.Customers.Configurations.Patch(configuration,
                                                     targetConfiguration.Name);
request.UpdateMask = "IsDefault";
Configuration results = request.Execute();

Python

# Send minimal data with the request. Just the 2 required fields.
# target_configuration is an existing configuration we'll make the default.
configuration = {
    'isDefault': True,
    'configurationId': target_configuration['configurationId']}

# Call the API, including the FieldMask to avoid setting other fields to null.
response = service.customers().configurations().patch(
    name=target_configuration['name'],
    body=configuration, updateMask='isDefault').execute()

Pode haver apenas uma configuração padrão. Ao fazer uma nova configuração padrão, o campo isDefault da configuração anterior é definido como false. Talvez seja necessário atualizar as instâncias Configuration em cache para conferir os valores corretos nos campos isDefault.

Guiar usuários do dispositivo

A configuração sem toque mostra orientações personalizadas para o usuário no assistente de configuração do dispositivo para ajudar os usuários. É necessário incluir um número de telefone e um endereço de e-mail de contato com o nome da organização que gerencia o dispositivo em uma configuração. Também recomendamos incluir uma ou duas frases no campo customMessage para dar mais detalhes sobre o que está acontecendo com o dispositivo do usuário.

Como o usuário não poderá ligar ou enviar e-mail usando o dispositivo que está configurando, formate o número de telefone e o endereço de e-mail para facilitar a visualização das informações.

Dispositivo

Os revendedores criam dispositivos quando um cliente faz a compra para registro sem toque. Os administradores de TI não podem criar dispositivos. Para trabalhar com dispositivos, chame métodos no recurso da API Device. Se você precisar pesquisar dispositivos, liste todos os dispositivos e filtre cada lote localmente no app. Confira um exemplo na seção Resultados paginados abaixo.

Configurar dispositivos

A aplicação de uma configuração a um dispositivo registra o dispositivo no registro sem toque. Para aplicar uma configuração, chame customers.devices.applyConfiguration. Após a aplicação de uma configuração, o dispositivo se provisiona automaticamente na primeira inicialização ou na próxima redefinição para a configuração original. O exemplo abaixo mostra como aplicar uma configuração a uma coleção de dispositivos:

Java

List<Device> devices = getDevicesToConfigure(service);
Configuration configurationToApply = getConfigurationToApply(service);

// Loop through the collection and apply the configuration to each device. This might
// take some time if the collection contains many devices.
for (Device device : devices) {
    System.out.println(device.getDeviceIdentifier().getImei());

    // Wrap the device ID in a DeviceReference.
    DeviceReference deviceRef = new DeviceReference();
    deviceRef.setDeviceId(device.getDeviceId());

    // Build and send the request to the API.
    CustomerApplyConfigurationRequest body = new CustomerApplyConfigurationRequest();
    body.setConfiguration(configurationToApply.getName());
    body.setDevice(deviceRef);

    AndroidProvisioningPartner.Customers.Devices.ApplyConfiguration request = service
          .customers()
          .devices()
          .applyConfiguration(customerAccount, body);
    request.execute();
}

.NET

IList<Device> devices = GetDevicesToConfigure(service);
Configuration configurationToApply = GetConfigurationToApply(service);

// Loop through the collection and apply the configuration to each device. This might
// take some time if the collection contains many devices.
foreach (Device device in devices)
{
    Console.WriteLine(device.DeviceIdentifier.Imei);

    // Wrap the device ID in a DeviceReference.
    var deviceRef = new DeviceReference
    {
        DeviceId = device.DeviceId
    };

    // Build and send the request to the API.
    CustomerApplyConfigurationRequest body = new CustomerApplyConfigurationRequest
    {
        Configuration = configurationToApply.Name,
        Device = deviceRef
    };
    var request = service.Customers.Devices.ApplyConfiguration(body,
                                                               customerAccount);
    request.Execute();
}

Python

devices = get_devices_to_configure(service)
configuration = get_configuration_to_apply(service)

# Loop through the collection and apply the configuration to each device.
# This might take some time if the collection contains many devices.
for device in devices:
  print(device['deviceIdentifier']['imei'])

  # Wrap the device ID in a DeviceReference.
  device_ref = {'deviceId': device['deviceId']}

  # Build and send the request to the API.
  body = {'configuration': configuration['name'], 'device': device_ref}
  service.customers().devices().applyConfiguration(
      parent=customer_account, body=body).execute()

Para remover a configuração de um dispositivo, chame customers.devices.removeConfiguration. A mudança entra em vigor depois que o dispositivo é redefinido para a configuração original.

Cancelar reivindicação de dispositivos

Os administradores de TI podem cancelar a reivindicação de um dispositivo para que ele seja removido do registro sem toque. Um administrador de TI pode cancelar a reivindicação de um dispositivo que ele quer migrar para outra conta, vendido ou devolvido ao revendedor. Chame o método customers.devices.unclaim para cancelar a reivindicação de um dispositivo de uma organização.

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 da organização e o dispositivo deixa de ser gerenciado após uma redefinição para a configuração original. O administrador de TI precisa entrar em contato com o revendedor se quiser registrar o dispositivo no registro sem toque novamente.

O exemplo abaixo mostra como cancelar a reivindicação de um dispositivo de um número IMEI e nome de fabricante:

Java

// Wrap the hardware ID and manufacturer values in a DeviceIdentifier.
// Then wrap the DeviceIdentifier in a DeviceReference.
DeviceIdentifier identifier = new DeviceIdentifier();
identifier.setImei("123456789012347");
identifier.setManufacturer("Google");
DeviceReference reference = new DeviceReference();
reference.setDeviceIdentifier(identifier);

// Create the body of the request.
CustomerUnclaimDeviceRequest body = new CustomerUnclaimDeviceRequest();
body.setDevice(reference);

// Call the API method to unclaim the device from the organization.
service.customers().devices().unclaim(customerAccount, body).execute();

.NET

// Wrap the hardware ID and manufacturer values in a DeviceIdentifier.
// Then wrap the DeviceIdentifier in a DeviceReference.
DeviceIdentifier identifier = new DeviceIdentifier
{
    Imei = "123456789012347",
    Manufacturer = "Google"
};
DeviceReference reference = new DeviceReference();
reference.DeviceIdentifier = identifier;

// Create the body of the request.
CustomerUnclaimDeviceRequest body = new CustomerUnclaimDeviceRequest();
body.Device = reference;

// Call the API method to unclaim the device from the organization.
service.Customers.Devices.Unclaim(body, customerAccount).Execute();

Python

# Wrap the hardware ID and manufacturer values in a DeviceIdentifier.
# Then wrap the DeviceIdentifier in a DeviceReference.
identifier = {'imei': '123456789012347', 'manufacturer': 'Google'}
reference = {'deviceIdentifier': identifier}

# Create the body of the request.
body = {'device': reference}

# Call the API method to unclaim the device from the organization.
service.customers().devices().unclaim(
    parent=customer_account, body=body).execute()

Metadados do dispositivo

Um administrador de TI pode ver os metadados anexados ao dispositivo pelo revendedor. Mostre os metadados desse dispositivo no seu app para ajudar os administradores de TI a reconhecer os dispositivos.

Para saber mais sobre os metadados que você pode encontrar, leia o guia Metadados de dispositivos para revendedores.

Resultados paginados

O método customers.devices.list da API pode retornar listas muito grandes de dispositivos. Para reduzir o tamanho da resposta, esse e outros métodos de API (como customers.list) oferecem suporte a resultados paginados. Com os resultados paginados, seu aplicativo pode solicitar e processar iterativamente listas grandes, 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 pageSize. 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 void printDevices(AndroidProvisioningPartner service, String customerAccount,
      String pageToken) throws IOException {

    // Call the API to get a page of Devices. Send a page token from the method argument.
    // If the page token is null, the API returns the first page.
    AndroidProvisioningPartner.Customers.Devices.List request =
          service.customers().devices().list(customerAccount);
    request.setPageSize(50L);
    request.setPageToken(pageToken);
    CustomerListDevicesResponse response = request.execute();

    // 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 & print the devices.
    if (response.getNextPageToken() != null) {
        this.printDevices(service, customerAccount, response.getNextPageToken());
    }
}

.NET

private void PrintDevices(AndroidProvisioningPartnerService service, String customerAccount,
                          String pageToken)
{
    // Call the API to get a page of Devices. Send a page token from the method argument.
    // If the page token is null, the API returns the first page.
    var request = service.Customers.Devices.List(customerAccount);
    request.PageSize = 50;
    request.PageToken = pageToken;
    var response = request.Execute();

    // 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(service, customerAccount, response.NextPageToken);
    }
}

Python

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

  # Call the API to get a page of Devices. Send a page token from the method
  # argument. If the page token is None, the API returns the first page.
  response = service.customers().devices().list(
      parent=customer_account, pageSize=50, pageToken=page_token).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(service, customer_account, response['nextPageToken'])

Primeiros passos

A seguir, leia como autorizar chamadas de API em Autorização. Se você quiser explorar as APIs, confira os guias de início rápido para Java, .NET e Python. Use o Colab para conferir exemplos de chamadas de API e testar como chamar a API por conta própria.