L'API del cliente offre il controllo programmatico dei dispositivi e 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 basi risorse utilizzate nell'API e il modo in cui interagiscono. Se non hai esperienza con la registrazione zero-touch per la registrazione, leggi il breve android.com introduzione.
Panoramica
L'API del cliente aiuta le organizzazioni che acquistano la registrazione zero-touch di Android dispositivi mobili. 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 la registrazione zero-touch attività di machine learning.
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ù, consulta la sezione 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:
Java
// 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();
.NET
// 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();
Python
# 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
. Vedi Predefinita
configurazioni (di seguito) per un esempio che mostra come
aggiornare una configurazione in modo efficiente.
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.
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 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
:
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. 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 utente personalizzate nella configurazione del dispositivo
una procedura guidata per aiutare gli utenti. 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:
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 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:
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. 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
di pagina, la tua applicazione può richiedere ed elaborare iterativamente 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:
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
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.