Cómo funciona

La API de cliente ofrece control programático de los dispositivos y para la inscripción automática de Android. En este documento, se presenta la API a los proveedores de administración de movilidad empresarial (EMM) y a los desarrolladores de TI de las empresas. Después de leer este documento, deberías comprender los recursos principales que se usan en la API y cómo interactúan. Si es la primera vez que utilizas la inscripción automática inscripción, lee el breve android.com introducción.

 Descripción general

La API del cliente ayuda a las organizaciones que compran la inscripción automática de Android dispositivos. La app o herramienta puede ayudar a los administradores de TI a hacer lo siguiente:

• Crear, editar y borrar parámetros de configuración de aprovisionamiento
• Aplicar o quitar una configuración de un dispositivo
• Selecciona una configuración predeterminada para los dispositivos agregados a la inscripción automática en el futuro.

A través de la API, los administradores de TI también pueden cancelar el registro de dispositivos de la inscripción automática. la inscripción. Para administrar los usuarios de su organización o aceptar las Condiciones del Servicio, sigue estos pasos: Los administradores de TI usan el portal de inscripción automática.

Estos son los usuarios típicos de esta API:

• Proveedores de EMM que agregan compatibilidad con la inscripción automática a su consola.
• Desarrolladores de TI empresariales que crean herramientas para automatizar la inscripción automática tareas.

Recursos principales

Las configuraciones y los dispositivos son los recursos principales que usas en la API. Los organización también puede crear configuraciones y dispositivos con la inscripción automática portal de inscripción.

Configuración

Los administradores de TI establecen opciones de aprovisionamiento para los dispositivos que usan una configuración. Los parámetros de configuración incluyen políticas para dispositivos móviles de EMM y la información de contacto que se muestra a ayudan a los usuarios. Las configuraciones son fundamentales para la API, por lo que se usan en muchos . Para obtener más información, consulta Configuraciones a continuación.

Dispositivo

Un dispositivo Android compatible con la inscripción automática que una organización compró en un entonces su revendedor. Aplica una configuración para incluir el dispositivo en la inscripción automática. Los dispositivos tienen IDs de hardware y metadatos adjuntos. Para obtener más información, consulta Dispositivos a continuación.

DPC

Una referencia de solo lectura al DPC de una EMM (política de dispositivo) responsable del tratamiento de datos). Agregar un DPC a una configuración para seleccionar la solución de EMM para los dispositivos. Todos los DPC enumerados que ofrece la API admiten la inscripción automática y están disponibles en Google Play. Para obtener más información, consulta Dpc.

Para ver una lista de todos los métodos y recursos de la API que puede usar tu app, consulta la Referencia de la API.

Configuraciones

El recurso de API de Configuration combina lo siguiente:

• El DPC de EMM instalado en los dispositivos.
• Políticas de EMM aplicadas en los dispositivos
• Información de contacto que se muestra en el dispositivo para ayudar a los usuarios durante la configuración.

Con la API, tu app puede administrar las configuraciones de los administradores de TI. Llama a la API para recuperar, crear, actualizar y borrar parámetros de configuración. En el siguiente ejemplo, se muestra cómo crea una configuración nueva:

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

Cuando actualices una configuración con la API de parche, recuerda incluir el máscara de campo o una valor para cada campo que no deseas que sea null. Consulta Configuración predeterminada de configuración (más abajo) para ver un ejemplo que muestra cómo actualizar una configuración de forma eficiente.

Borrar parámetros de configuración

No puedes borrar una configuración si todavía se aplica a los dispositivos. Si intentas si borras una configuración en uso, el método de la API devuelve un 400 Bad Request código de estado y un mensaje que explica cuántos dispositivos usan la configuración. Llamada customers.devices.removeConfiguration para quitar la configuración de los dispositivos antes de volver a intentarlo.

Configuración predeterminada.

La inscripción automática funciona mejor cuando una organización establece una configuración predeterminada que se aplica a los dispositivos nuevos que compra la organización. Considera pedirles a los administradores de TI que establezcan una configuración predeterminada si no hay una establecida. En el siguiente ejemplo, se muestra cómo hacer que una configuración existente sea la predeterminada Configurando 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()

Solo puede haber una configuración predeterminada. Establecer una nueva configuración predeterminada Establece el campo isDefault de una configuración anterior en false. Es posible que debas actualiza las instancias de Configuration almacenadas en caché para ver los valores correctos en el isDefault campos.

Guía a los usuarios del dispositivo

La configuración de la inscripción automática muestra una guía del usuario personalizada en la configuración del dispositivo Asistente para ayudar a los usuarios. Debes incluir un número de teléfono y un correo electrónico de contacto. dirección junto con el nombre de la organización que administra el dispositivo en una configuración. También recomendamos incluir una o dos oraciones en el El campo customMessage para brindar más detalles sobre lo que le sucede al usuario dispositivo.

Porque el usuario no podrá llamar ni enviar correos electrónicos desde el dispositivo que esté configurando dar formato al número de teléfono y a la dirección de correo electrónico para que sea más fácil consultarlos la información.

Dispositivos

Los revendedores crean dispositivos cuando un cliente los compra para la inscripción automática inscripción: los administradores de TI no pueden crear dispositivos. Para trabajar con dispositivos, llama a los métodos activados el recurso de API Device. Si necesitas buscar dispositivos, haz una lista de todos ellos y filtra cada lote de forma local en tu app. Para ver un ejemplo, consulta Resultados paginados a continuación.

Cómo configurar dispositivos

Cuando se aplica una configuración a un dispositivo, se registra la inscripción automática en este. la inscripción. Para aplicar una configuración, llama a customers.devices.applyConfiguration Después de aplicar una configuración, el dispositivo se aprovisiona automáticamente en el primer inicio o el siguiente restablecimiento de la configuración de fábrica. En el siguiente ejemplo, se muestra cómo aplicar un existente en un conjunto 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 quitar la configuración de un dispositivo, llama customers.devices.removeConfiguration El cambio se aplica después de restablecer la configuración de fábrica del dispositivo.

Cómo rechazar dispositivos

Los administradores de TI pueden anular la propiedad de un dispositivo para quitarlo de la inscripción sin intervención manual. Un equipo de TI puede cancelar el reclamo de un dispositivo que quiere migrar a otra cuenta, vendido o devolverse al revendedor. Llama al método customers.devices.unclaim para anular el reclamo de un dispositivo de una organización.

Precaución: Considera pedirle al usuario de la app que confirme si cuenta con el el dispositivo correcto antes de llamar a las APIs sin reclamar. Si revocas un dispositivo, se quitará la de aprovisionamiento de tu organización y el dispositivo deja de ser administrado después de que restablecer la configuración de fábrica. El administrador de TI debe comunicarse con su revendedor si quiere registrarse volver a usar la inscripción automática en el dispositivo.

En el siguiente ejemplo, se muestra cómo retirar un dispositivo a un número IMEI y nombre del 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()

Metadatos del dispositivo

Un administrador de TI puede ver los metadatos que el revendedor conectó al dispositivo. Muestra estos metadatos del dispositivo en tu app para ayudar a los administradores de TI a reconocer los dispositivos.

Para obtener más información sobre los metadatos que puedes ver, lee el artículo Dispositivo metadatos para revendedores.

Resultados paginados

Es posible que el método de la API customers.devices.list muestre listas muy extensas de dispositivos. Para reducir el tamaño de las respuestas, esta y otras APIs (como customers.list) admiten resultados paginados, Con los resultados paginados, tu aplicación puede solicitar y procesar de forma iterativa listas grandes, una página a la vez.

Después de llamar al método de la API, verifica si la respuesta incluye un valor para nextPageToken. Si nextPageToken no es null, tu app puede usarla para recuperar otra página de dispositivos llamando al de nuevo. Debes establecer un límite superior para la cantidad de dispositivos en el parámetro pageSize. Si nextPageToken es null, tu app solicitó la última página.

En el método de ejemplo que aparece a continuación, se muestra cómo tu app podría imprimir una lista de dispositivos, una página a la 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'])

Comenzar

A continuación, lee cómo autorizar llamadas a la API en Autorización. Si quieres explorar las APIs, consulta las guías de inicio rápido para Java, .NET y Python. Puedes usar un colab para ver de llamadas a la API y prueba llamar a la API tú mismo.