Come funziona

L'API per i clienti offre il controllo programmatico dei dispositivi e della configurazione per la registrazione zero-touch di Android. Questo documento introduce API per i provider di gestione della mobilità aziendale (EMM) e IT aziendale sviluppatori. Dopo aver letto questo documento, dovresti comprendere le risorse di base utilizzate nell'API e come interagiscono. Se non hai mai utilizzato la registrazione zero-touch, consulta la breve introduzione di android.com.

Panoramica

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

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

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

Gli utenti tipici di questa API potrebbero essere:

• I provider EMM aggiungono il supporto per la registrazione zero-touch alla loro 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 un'organizzazione può anche creare configurazioni e dispositivi usando la funzionalità portale di registrazione.

Configurazione

Gli amministratori IT impostano le opzioni di provisioning per i dispositivi utilizzando una configurazione. Le configurazioni includono criteri EMM per dispositivi mobili e dati di contatto mostrati a e aiutare gli utenti. Le configurazioni sono fondamentali per l'API, quindi puoi usarle in molte di machine learning. Per saperne di più, vedi Configurazioni di seguito.

Dispositivo

Un dispositivo Android con funzionalità di registrazione zero-touch da cui è stata acquistata un'organizzazione rivenditore. Applica una configurazione per includere il dispositivo nella registrazione zero-touch della registrazione. I dispositivi hanno ID hardware e metadati collegati. Per saperne di più, vedi Dispositivi qui sotto.

DPC (controller criteri dispositivi)

Un riferimento di sola lettura al DPC (criteri relativi ai dispositivi) di un EMM controller). Aggiungi un DPC (controller criteri dispositivi) 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 in Google Play. A per saperne di più, consulta Dpc.

Per elencare tutti i metodi e le risorse dell'API che l'app può utilizzare, consulta le Riferimento API.

Configurazioni

La risorsa API Configuration combina seguenti:

• Il DPC dell'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, la tua app può gestire le configurazioni per gli amministratori IT. Chiama l'API per recuperare, creare, aggiornare ed eliminare le configurazioni. L'esempio di seguito mostra come crea una nuova configurazione:

// Add metadata to help the device user during provisioning.
Configuration configuration = new Configuration();
configuration.setConfigurationName("Sales team");
configuration.setCompanyName("XYZ Corp.");
configuration.setContactEmail("it-support@example.com");
configuration.setContactPhone("+1 (800) 555-0112");
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();

// Add metadata to help the device user during provisioning.
Configuration configuration = new Configuration
{
    ConfigurationName = "Sales team",
    CompanyName = "XYZ Corp.",
    ContactEmail = "it-support@example.com",
    ContactPhone = "+1 (800) 555-0112",
    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();

# Add metadata to help the device user during provisioning.
configuration = {
    'configurationName': 'Sales team',
    'companyName': 'XYZ Corp.',
    'contactEmail': 'it-support@example.com',
    'contactPhone': '+1 (800) 555-0112',
    '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 il parametro maschera di campo: per ogni campo che non vuoi che sia null. Consulta Configurazioni predefinite (di seguito) per un esempio che mostra come aggiornare efficacemente una configurazione.

Elimina configurazioni

Non puoi eliminare una configurazione se è ancora applicata ai dispositivi. Se provi a elimini una configurazione in uso, il metodo API restituisce un URL HTTP 400 Bad Request codice di stato e un messaggio che spiega quanti dispositivi utilizzano la configurazione. Chiamare 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 un valore predefinito configurazione applicata a tutti i nuovi dispositivi acquistati dall'organizzazione. Valuta la possibilità di chiedere agli amministratori IT di impostare una configurazione predefinita se non ne esiste una. L'esempio seguente mostra come rendere predefinita una configurazione esistente impostazione di isDefault su true:

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

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

# 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. Creiamo una nuova configurazione predefinita, Il campo isDefault di una configurazione precedente viene impostato su false. Potresti dover aggiorna tutte le istanze Configuration memorizzate nella cache per visualizzare i valori corretti nella isDefault campi.

Guida gli utenti dei dispositivi

La configurazione zero-touch mostra indicazioni personalizzate per gli utenti nella configurazione guidata del dispositivo per aiutarli. Devi includere un numero di telefono e un indirizzo email di contatto indirizzo insieme al nome dell'organizzazione che gestisce il dispositivo in un configurazione. Ti consigliamo inoltre di includere una o due frasi nella customMessage per fornire ulteriori dettagli su cosa sta succedendo a un utente dispositivo.

Perché l'utente non potrà effettuare chiamate o inviare email dal dispositivo che ha impostato formatta il numero di telefono e l'indirizzo email in modo che sia più facile le informazioni.

Dispositivi

I rivenditori creano i dispositivi quando un cliente li acquista per la registrazione zero-touch Registrazione: gli amministratori IT non possono creare dispositivi. Per usare i dispositivi, attiva i metodi di chiamata la risorsa API Device. Se hai bisogno di cercare per i dispositivi, elenca tutti i dispositivi e filtra ogni batch localmente nella tua app. Per un esempio, consulta la sezione Risultati impaginati di seguito.

Configura dispositivi

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

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

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

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 viene applicata 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 servizio IT un amministratore potrebbe annullare la rivendicazione di un dispositivo di cui vuole eseguire la migrazione a un altro account, o restituirlo al rivenditore. Chiama il metodo customers.devices.unclaim per annullare la rivendicazione di un dispositivo di un'organizzazione.

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

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

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

# 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ò vedere i metadati associati al dispositivo dal rivenditore. Rete Display Questi metadati del dispositivo nella tua app per aiutare gli amministratori IT a riconoscere i dispositivi.

Per ulteriori informazioni sui metadati che potrebbero essere visualizzati, leggi l'articolo sul sui metadati per i rivenditori.

Risultati per pagine

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

Dopo aver chiamato il metodo API, controlla se la risposta include un valore per nextPageToken Se nextPageToken non è null, la tua app può utilizzarla per recuperare un'altra pagina di dispositivi chiamando il metodo . Devi impostare un limite superiore per il numero di dispositivi nella Parametro pageSize. Se nextPageToken è null, la tua app ha richiesto il l'ultima pagina.

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

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

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

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

Successivamente, scopri come autorizzare le chiamate API in Autorizzazione. Se vuoi esplora le API, dai un'occhiata alle guide rapide Java .NET e Python. Puoi utilizzare uno dei seguenti colab per visualizzare esempi di chiamate API e esperimenti con le chiamate all'API autonomamente.