Come funziona

L'API Customer fornisce il controllo programmatico dei dispositivi e della configurazione per la registrazione zero-touch di Android. Questo documento presenta l'API per i provider di gestione della mobilità aziendale (EMM) e gli sviluppatori IT aziendali. Dopo aver letto questo documento, dovresti comprendere le risorse principali utilizzate nell'API e come interagiscono. Se non hai mai utilizzato la registrazione zero-touch, leggi la breve introduzione ad android.com.

Panoramica

L'API del cliente aiuta le organizzazioni che acquistano dispositivi di registrazione zero-touch di Android. L'app o lo strumento può aiutare gli amministratori IT a:

• Creare, modificare ed eliminare le configurazioni di provisioning.
• Applica o rimuovi una configurazione da un dispositivo.
• Seleziona una configurazione predefinita per tutti i dispositivi aggiunti alla registrazione zero-touch in futuro.

Tramite l'API, gli amministratori IT possono anche annullare la registrazione zero-touch dei dispositivi. Per gestire gli utenti della propria organizzazione o accettare i Termini di servizio, gli amministratori IT utilizzano il portale della registrazione zero-touch.

Gli utenti tipici di questa API potrebbero essere:

• I provider EMM aggiungono il supporto della registrazione zero-touch alla propria console.
• Sviluppatori IT aziendali che creano strumenti per automatizzare le attività di registrazione zero-touch.

Risorse principali

Le configurazioni e i dispositivi sono le risorse principali che utilizzi nell'API. Un'organizzazione può anche creare configurazioni e dispositivi utilizzando il portale della registrazione zero-touch.

Configurazione

Gli amministratori IT impostano le opzioni di provisioning per i dispositivi utilizzando una configurazione. Le configurazioni includono i criteri per dispositivi mobili EMM e i dati di contatto che vengono visualizzati per aiutare gli utenti. Le configurazioni sono centrali per l'API, perciò puoi utilizzarle in molti metodi. Per saperne di più, consulta la sezione Configurazioni di seguito.

Dispositivo

Un dispositivo Android compatibile con la registrazione zero-touch che un'organizzazione ha acquistato presso il proprio rivenditore. Applica una configurazione per includere il dispositivo nella registrazione zero-touch. I dispositivi hanno ID hardware e metadati allegati. Per scoprire di più, vedi Dispositivi di seguito.

DPC (controller criteri dispositivi)

Un riferimento di sola lettura al DPC (controller dei criteri dei dispositivi) di un EMM. Aggiungi un DPC a una configurazione per selezionare la soluzione EMM per i dispositivi. Tutti i DPC elencati dall'API supportano la registrazione zero-touch e sono disponibili su Google Play. Per scoprire di più, consulta Dpc.

Per elencare tutti i metodi e le risorse API che la tua app può utilizzare, consulta la documentazione di riferimento API.

Configurazioni

La risorsa API Configuration combina quanto segue:

• Il DPC del provider EMM installato sui dispositivi.
• Criteri EMM applicati ai dispositivi.
• Dati di contatto visualizzati sul dispositivo per aiutare gli utenti durante la configurazione.

Utilizzando l'API, l'app può gestire le configurazioni per gli amministratori IT. Chiama l'API per recuperare, creare, aggiornare ed eliminare le configurazioni. L'esempio seguente mostra come creare una nuova configurazione:

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

Quando aggiorni una configurazione utilizzando l'API Patch, ricordati di includere la maschera di campo o un valore per ogni campo che non vuoi che sia null. Consulta la sezione Configurazioni predefinite (di seguito) per un esempio che mostra come aggiornare in modo efficiente una configurazione.

Elimina configurazioni

Non puoi eliminare una configurazione se è ancora applicata ai dispositivi. Se provi a eliminare una configurazione in uso, il metodo API restituisce un codice di stato HTTP 400 Bad Request e un messaggio che spiega quanti dispositivi utilizzano la configurazione. Chiama customers.devices.removeConfiguration per rimuovere la configurazione dai dispositivi prima di riprovare.

Configurazioni predefinite

La registrazione zero-touch funziona al meglio quando un'organizzazione imposta una configurazione predefinita che viene applicata a tutti i nuovi dispositivi acquistati dall'organizzazione. Potresti chiedere agli amministratori IT di impostare una configurazione predefinita, se non ne è impostata una. L'esempio seguente mostra come rendere predefinita una configurazione esistente impostando isDefault su 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()

Può esistere una sola configurazione predefinita. Se si crea una nuova configurazione predefinita, il campo isDefault di una configurazione precedente viene impostata su false. Potrebbe essere necessario aggiornare le istanze Configuration memorizzate nella cache per visualizzare i valori corretti nei campi isDefault.

Guida gli utenti dei dispositivi

La configurazione zero-touch mostra indicazioni per l'utente personalizzate nella configurazione guidata del dispositivo per aiutare gli utenti. Devi includere un numero di telefono e un indirizzo email di contatto insieme al nome dell'organizzazione che gestisce il dispositivo in una configurazione. Consigliamo inoltre di includere una o due frasi nel campo customMessage per fornire ulteriori dettagli su ciò che sta accadendo al dispositivo di un utente.

Poiché l'utente non sarà in grado di chiamare o inviare email dal dispositivo che sta configurando, formatta il numero di telefono e l'indirizzo email per semplificare la consultazione delle informazioni.

Dispositivi

I rivenditori creano i dispositivi quando un cliente li acquista per la registrazione zero-touch. Gli amministratori IT non possono creare dispositivi. Per lavorare con i dispositivi, chiama i metodi nella risorsa API Device. Se devi cercare dispositivi, elenca tutti i dispositivi e filtra ogni gruppo localmente nella tua app. Per un esempio, vedi Risultati impaginati di seguito.

Configura dispositivi

L'applicazione di una configurazione a un dispositivo lo registra per la registrazione zero-touch. Per applicare una configurazione, chiama customers.devices.applyConfiguration. Dopo aver applicato una configurazione, il dispositivo esegue automaticamente il provisioning automatico al primo avvio o al ripristino dei dati di fabbrica successivo. L'esempio seguente mostra come applicare una configurazione a una raccolta di dispositivi:

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

Per rimuovere la configurazione da un dispositivo, chiama customers.devices.removeConfiguration. La modifica avrà effetto dopo il ripristino dei dati di fabbrica del dispositivo.

Annulla rivendicazione dispositivi

Gli amministratori IT possono annullare la rivendicazione di un dispositivo per rimuoverlo dalla registrazione zero-touch. Un amministratore IT potrebbe annullare la rivendicazione di un dispositivo di cui vuole eseguire la migrazione a un altro account, venduto o restituito al rivenditore. Chiama il metodo customers.devices.unclaim per annullare la rivendicazione di un dispositivo da un'organizzazione.

Attenzione: valuta la possibilità di chiedere all'utente dell'app di confermare di disporre del dispositivo corretto prima di chiamare le API di annullamento delle rivendicazioni. L'annullamento della rivendicazione di un dispositivo comporta la rimozione della configurazione del provisioning dell'organizzazione e il dispositivo diventa non gestito dopo il ripristino dei dati di fabbrica. L'amministratore IT deve contattare il rivenditore se vuole registrare di nuovo il dispositivo per la registrazione zero-touch.

L'esempio seguente mostra come annullare la rivendicazione di un dispositivo da un numero IMEI e dal nome del produttore:

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

Metadati del dispositivo

Un amministratore IT può visualizzare i metadati allegati al dispositivo dal rivenditore. Mostra i metadati di questo dispositivo nella tua app per aiutare gli amministratori IT a riconoscere i dispositivi.

Per ulteriori informazioni sui metadati che potrebbero essere visualizzati, leggi la guida ai metadati dei dispositivi per i rivenditori.

Risultati con pagine

Il metodo API customers.devices.list potrebbe restituire elenchi di dispositivi molto grandi. Per ridurre le dimensioni della risposta, questo e altri metodi API (come customers.list) supportano i risultati impaginati. Con i risultati di pagine, l'applicazione può richiedere ed elaborare in modo iterativo grandi elenchi una pagina alla volta.

Dopo aver chiamato il metodo API, verifica se la risposta include un valore per nextPageToken. Se nextPageToken non è null, la tua app può utilizzarlo per recuperare un'altra pagina di dispositivi richiamando di nuovo il metodo. Devi impostare un limite massimo per il numero di dispositivi nel parametro pageSize. Se nextPageToken è null, la tua app ha richiesto l'ultima pagina.

Il metodo di esempio riportato di seguito mostra in che modo la tua app potrebbe stampare un elenco di dispositivi, una pagina alla volta:

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'])

Inizia

Quindi, leggi come autorizzare le chiamate API in Autorizzazione. Se vuoi esplorare le API, consulta le guide rapide per Java, .NET e Python. Puoi utilizzare colab per visualizzare esempi di chiamate API e provare a chiamare personalmente l'API.