Questa pagina è stata tradotta dall'API Cloud Translation.

Guida all'integrazione EMM

Questa guida aiuta i fornitori di gestione della mobilità aziendale (EMM) a integrare la registrazione zero-touch nella loro console. Continua a leggere per scoprire di più sulla registrazione e visualizzare i consigli sulle best practice per aiutare il tuo DPC (controller dei criteri dei dispositivi) a eseguire il provisioning dei dispositivi. Se hai un DPC, scoprirai le best practice per il provisioning dei dispositivi e riceverai consigli per lo sviluppo e i test.

Funzionalità per gli amministratori IT

Utilizza l'API Customer per aiutare gli amministratori IT a configurare la registrazione zero-touch direttamente dalla tua console. Ecco alcune attività che un amministratore IT potrebbe completare nella tua console:

Crea, modifica ed elimina le configurazioni della registrazione zero-touch in base alle tue norme per il mobile.
Imposta una configurazione predefinita in modo che il DPC esegua il provisioning dei futuri dispositivi acquistati dall'organizzazione.
Applica configurazioni individuali ai dispositivi o rimuovili dalla registrazione zero-touch.

Per saperne di più sulla registrazione zero-touch, leggi la panoramica.

Prerequisiti

Prima di aggiungere la registrazione zero-touch alla console EMM, verifica che la tua soluzione supporti quanto segue:

La tua soluzione EMM deve eseguire il provisioning di un dispositivo Android 8.0+ (Pixel 7.1+) di proprietà dell'azienda in modalità completamente gestita. I dispositivi Android 10+ di proprietà aziendale possono essere provisionati come completamente gestiti o con un profilo di lavoro.
Poiché la registrazione zero-touch scarica e installa automaticamente un DPC, il tuo DPC deve essere disponibile su Google Play. Gestiamo un elenco di DPC compatibili che gli amministratori IT possono configurare utilizzando l'API cliente o il portale. Invia una richiesta di modifica del prodotto tramite la community dei provider EMM per aggiungere il tuo DPC all'elenco.
I tuoi clienti hanno bisogno di un account di registrazione zero-touch per chiamare l'API customer. Un rivenditore partner configura l'account per l'organizzazione di un amministratore IT quando l'organizzazione acquista i dispositivi.
Il dispositivo deve essere compatibile con Google Mobile Services (GMS) e Google Play Services deve essere sempre attivo affinché la registrazione zero-touch funzioni correttamente.

Chiama l'API

Gli utenti della tua console (utilizzando il proprio Account Google) autorizzano le tue richieste API all'API Customer. Questo flusso è diverso dall'autorizzazione che esegui per altre API EMM. Leggi Autorizzazione per scoprire come farlo nella tua app.

Termini di servizio degli handle

Prima di chiamare l'API, i tuoi utenti devono accettare i Termini di servizio (TdS) più recenti. Se la chiamata API restituisce un codice di stato HTTP 403 Forbidden e il corpo della risposta contiene un TosError, chiedi all'utente di accettare i Termini di servizio accedendo al portale di registrazione zero-touch. L'esempio riportato di seguito mostra uno dei modi in cui puoi farlo:

Java

// Authorize this method call as a user that hasn't yet accepted the ToS.
final String googleApiFormatHttpHeader = "X-GOOG-API-FORMAT-VERSION";
final String googleApiFormatVersion = "2";
final String tosErrorType =
      "type.googleapis.com/google.android.device.provisioning.v1.TosError";

try {
  // Send an API request to list all the DPCs available including the HTTP header
  // X-GOOG-API-FORMAT-VERSION with the value 2. Import the  exception:
  // from googleapiclient.errors import HttpError
  AndroidProvisioningPartner.Customers.Dpcs.List request =
        service.customers().dpcs().list(customerAccount);
  request.getRequestHeaders().put(googleApiFormatHttpHeader, googleApiFormatVersion);
  CustomerListDpcsResponse response = request.execute();
  return response.getDpcs();

} catch (GoogleJsonResponseException e) {
  // Get the error details. In your app, check details exists first.
  ArrayList<Map> details = (ArrayList<Map>) e.getDetails().get("details");
  for (Map detail : details) {
    if (detail.get("@type").equals(tosErrorType)
          && (boolean) detail.get("latestTosAccepted") != true) {
      // Ask the user to accept the ToS. If they agree, open the portal in a browser.
      // ...
    }
  }
  return null;
}

.NET

// Authorize this method call as a user that hasn't yet accepted the ToS.
try
{
    var request = service.Customers.Dpcs.List(customerAccount);
    CustomerListDpcsResponse response = request.Execute();
    return response.Dpcs;
}
catch (GoogleApiException e)
{
    foreach (SingleError error in e.Error?.Errors)
    {
        if (error.Message.StartsWith("The user must agree the terms of service"))
        {
            // Ask the user to accept the ToS. If they agree, open the portal in a browser.
            // ...
        }
    }
}

Python

# Authorize this method call as a user that hasn't yet accepted the ToS.
tos_error_type = ('type.googleapis.com/'
                  'google.android.device.provisioning.v1.TosError')
portal_url = 'https://enterprise.google.com/android/zero-touch/customers'

# Send an API request to list all the DPCs available including the HTTP
# header X-GOOG-API-FORMAT-VERSION with the value 2. Import the exception:
# from googleapiclient.errors import HttpError
try:
  request = service.customers().dpcs().list(parent=customer_account)
  request.headers['X-GOOG-API-FORMAT-VERSION'] = '2'
  response = request.execute()
  return response['dpcs']

except HttpError as err:
  # Parse the JSON content of the error. In your app, check ToS exists first.
  error = json.loads(err.content)
  tos_error = error['error']['details'][0]

  # Ask the user to accept the ToS (not shown here). If they agree, then open
  # the portal in a browser.
  if (tos_error['@type'] == tos_error_type
      and tos_error['latestTosAccepted'] is not True):
    if raw_input('Accept the ToS in the zero-touch portal? y|n ') == 'y':
      webbrowser.open(portal_url)

Se il tuo client API Google supporta errori dettagliati (richieste Java, Python o HTTP), includi l'intestazione HTTP X-GOOG-API-FORMAT-VERSION con il valore 2 nelle tue richieste. Se il tuo client non supporta gli errori dettagliati (.NET e altri), fai in modo che il messaggio di errore corrisponda.

Se in futuro aggiorneremo i TdS, se segui questo approccio, la tua app invita l'utente ad accettare nuovamente i nuovi TdS.

Link al portale

Gli amministratori IT utilizzano il portale di registrazione zero-touch per gestire gli utenti della loro organizzazione. Non puoi offrire questa funzionalità tramite l'API Customer. Gli amministratori IT possono anche gestire dispositivi e configurazioni utilizzando il portale. Se devi creare un link al portale dalla console o nella documentazione, utilizza questo URL:

https://enterprise.google.com/android/zero-touch/customers

Ti consigliamo di informare gli amministratori IT che viene chiesto loro di accedere con il proprio Account Google.

Registrazione dei dispositivi

La registrazione zero-touch è un meccanismo per registrare i dispositivi ed è simile alla registrazione NFC o con codice QR. La console deve supportare i dispositivi gestiti e il DPC deve essere in grado di essere eseguito in modalità dispositivo completamente gestito.

La registrazione zero-touch è disponibile sui dispositivi supportati con Android 8.0 o versioni successive. Gli amministratori IT devono acquistare dispositivi supportati da un rivenditore partner. La tua console può monitorare quali dispositivi dell'amministratore IT sono disponibili per la registrazione zero-touch chiamando customers.devices.list.

Ecco una panoramica di come funziona la registrazione:

Al primo avvio (o dopo un ripristino dei dati di fabbrica), un dispositivo esegue il check-in con un server Google per la registrazione zero-touch.
Se l'amministratore IT ha applicato una configurazione al dispositivo, la registrazione zero-touch esegue la procedura guidata di configurazione di Android per i dispositivi completamente gestiti e personalizza le schermate con i metadati della configurazione.
La registrazione zero-touch scarica e installa il DPC da Google Play.
Il tuo DPC riceve l'intent ACTION_PROVISION_MANAGED_DEVICE e provisiona il dispositivo.

Se non è presente una connessione a internet, il controllo viene eseguito quando una connessione diventa disponibile. Per scoprire di più sul provisioning dei dispositivi con la registrazione zero-touch, consulta la sezione Provisioning di seguito.

Configurazioni predefinite

La registrazione zero-touch è più utile per gli amministratori IT quando impostano una configurazione predefinita da applicare a tutti i nuovi dispositivi acquistati dalla loro organizzazione. Promuovi l'impostazione di una configurazione predefinita dalla console se non ne è impostata una. Puoi controllare il valore di customers.configurations.isDefault per scoprire se un'organizzazione ha impostato una configurazione predefinita.

L'esempio seguente mostra come impostare una configurazione esistente come predefinita:

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

Fare riferimento al DPC

Ti consigliamo di utilizzare il nome della risorsa API customers.dpcs.name per identificare il tuo DPC e utilizzarlo nelle configurazioni. Il nome della risorsa contiene un identificatore univoco e immutabile per il DPC. Chiama customers.dpcs.list per ottenere l'elenco di tutti i DPC supportati. Poiché il nome della risorsa include anche l'ID cliente, filtra l'elenco utilizzando l'ultimo componente del percorso per trovare un'istanza Dpc corrispondente. L'esempio di seguito mostra come abbinare il DPC e conservarlo per un utilizzo successivo in una configurazione:

Java

// Return a customer Dpc instance for the specified DPC ID.
String myDpcIdentifier = "AH6Gbe4aiS459wlz58L30cqbbXbUa_JR9...xMSWCiYiuHRWeBbu86Yjq";
final int dpcIdIndex = 3;
final String dpcComponentSeparator = "/";
// ...
for (Dpc dpcApp : dpcs) {
    // Because the DPC name is in the format customers/{CUST_ID}/dpcs/{DPC_ID}, check the
    // fourth component matches the DPC ID.
    String dpcId = dpcApp.getName().split(dpcComponentSeparator)[dpcIdIndex];
    if (dpcId.equals(myDpcIdentifier)) {
        System.out.format("My DPC is: %s\n", dpcApp.getDpcName());
        return dpcApp;
    }
}
// Handle the case when the DPC isn't found...

.NET

// Return a customer Dpc instance for the specified DPC ID.
var myDpcIdentifer = "AH6Gbe4aiS459wlz58L30cqbbXbUa_JR9...fE9WdHcxMSWCiYiuHRWeBbu86Yjq";
const int dpcIdIndex = 3;
const String dpcComponentSeparator = "/";
// ...
foreach (Dpc dpcApp in dpcs)
{
    // Because the DPC name is in the format customers/{CUST_ID}/dpcs/{DPC_ID}, check the
    // fourth component matches the DPC ID.
    String dpcId = dpcApp.Name.Split(dpcComponentSeparator)[dpcIdIndex];
    if (dpcId.Equals(myDpcIdentifer))
    {
        Console.WriteLine("Matched DPC is: {0}", dpcApp.DpcName);
        return dpcApp;
    }
}
// Handle the case when the DPC isn't found...

Python

# Return a customer Dpc instance for the specified DPC ID.
my_dpc_id = 'AH6Gbe4aiS459wlz58L30cqb...fE9WdHcxMSWCiYiuHRWeBbu86Yjq'
# ...
for dpc_app in dpcs:
  # Because the DPC name is in the format customers/{CUST_ID}/dpcs/{DPC_ID},
  # check the fourth component matches the DPC ID.
  dpc_id = dpc_app['name'].split('/')[3]
  if dpc_id == my_dpc_id:
    return dpc_app

# Handle the case when the DPC isn't found...

Se devi mostrare il nome di un DPC nell'interfaccia utente della console, visualizza il valore restituito da customers.dpcs.dpcName.

Provisioning

Cogli l'opportunità di offrire un'esperienza utente ottimale per il provisioning dei dispositivi. Per eseguire il provisioning del dispositivo sono necessari solo un nome utente e una password. Ricorda che i rivenditori potrebbero spedire i dispositivi direttamente agli utenti remoti. Includi tutte le altre impostazioni, come il server EMM o l'unità organizzativa, in customers.configuration.dpcExtras.

Lo snippet JSON riportato di seguito mostra parte di una configurazione di esempio:

{
  "android.app.extra.PROVISIONING_LOCALE": "en_GB",
  "android.app.extra.PROVISIONING_TIME_ZONE": "Europe/London",
  "android.app.extra.PROVISIONING_LEAVE_ALL_SYSTEM_APPS_ENABLED": true,
  "android.app.extra.PROVISIONING_ADMIN_EXTRAS_BUNDLE": {
    "workflow_type": 3,
    "default_password_quality": 327680,
    "default_min_password_length": 6,
    "company_name": "XYZ Corp",
    "organizational_unit": "sales-uk",
    "management_server": "emm.example.com",
    "detail_tos_url": "https://www.example.com/policies/terms/",
    "allowed_user_domains": "[\"example.com\", \"example.org\", \"example.net\"]"
    }
}

La registrazione zero-touch installa e avvia il DPC utilizzando un intent Android. Il sistema invia i valori nella proprietà JSON android.app.extra.PROVISIONING_ADMIN_EXTRAS_BUNDLE al tuo DPC come extra nell'intent. Il controller DPC può leggere le impostazioni di provisioning da PersistableBundle utilizzando le stesse chiavi.

Consigliato: utilizza i seguenti extra intent per configurare il DPC:

Sconsigliato: non includere i seguenti componenti aggiuntivi che potresti utilizzare in altri metodi di registrazione:

Per scoprire come estrarre e utilizzare queste impostazioni nel tuo controller DPC, leggi Provisioning dei dispositivi dei clienti.

Sviluppo e test

Per sviluppare e testare le funzionalità di registrazione zero-touch della console, ti serviranno:

un dispositivo supportato
un account di registrazione zero-touch per clienti

Sviluppa e testa con dispositivi che supportano la registrazione zero-touch, come Google Pixel. Non devi acquistare i tuoi dispositivi di sviluppo da un rivenditore partner.

Contattaci per ottenere un account cliente di prova e l'accesso al portale di registrazione zero-touch. Inviaci un'email dal tuo indirizzo email aziendale associato a un Account Google. Comunicaci il produttore e il numero IMEI di uno o due dispositivi e li aggiungeremo al tuo account sviluppatore.

Ricorda che, poiché la registrazione zero-touch scarica e installa automaticamente un DPC, quest'ultimo deve essere disponibile su Google Play prima di poter testare il provisioning. Non puoi eseguire test con una versione di sviluppo del tuo DPC.

Assistenza per gli amministratori IT

Se devi aiutare gli amministratori IT nell'interfaccia della console o nella documentazione, consulta la pagina Registrazione zero-touch per gli amministratori IT per indicazioni. Puoi anche indirizzare gli utenti della console a questo articolo del Centro assistenza.

Per approfondire

Leggi questi documenti per integrare la registrazione zero-touch nella tua console:

Registrazione zero-touch per gli amministratori IT nella Guida di Android Enterprise.
Esegui il provisioning dei dispositivi dei clienti dal sito per sviluppatori Android EMM.

Guida all'integrazione EMM Mantieni tutto organizzato con le raccolte Salva e classifica i contenuti in base alle tue preferenze.

Funzionalità per gli amministratori IT

Prerequisiti

Chiama l'API

Termini di servizio degli handle

Java

.NET

Python

Link al portale

Registrazione dei dispositivi

Configurazioni predefinite

Java

.NET

Python

Fare riferimento al DPC

Java

.NET

Python

Provisioning

Sviluppo e test

Assistenza per gli amministratori IT

Per approfondire

Guida all'integrazione EMM