L'API du client permet de contrôler les appareils de manière programmatique. pour l'enregistrement sans contact Android. Ce document présente API pour les fournisseurs de solutions de gestion de la mobilité en entreprise (EMM) et l'informatique d'entreprise développeurs. Après avoir lu ce document, vous devriez comprendre les principales les ressources utilisées dans l'API et la manière dont elles interagissent. Si vous débutez avec l'enregistrement sans contact d'inscription, consultez la courte android.com présentation.
Présentation
L'API du client aide les entreprises qui achètent l'enregistrement sans contact Android appareils. Votre application ou votre outil peuvent aider les administrateurs informatiques à effectuer les opérations suivantes:
- Créer, modifier et supprimer des configurations de provisionnement
- Appliquer ou supprimer une configuration sur un appareil
- Sélectionner une configuration par défaut pour tous les appareils ajoutés à l'enregistrement sans contact à l'avenir.
Via l'API, les administrateurs informatiques peuvent également annuler l'enregistrement des appareils pour l'enregistrement sans contact. de l'inscription. Pour gérer les utilisateurs de son organisation ou accepter les conditions d'utilisation, Les administrateurs informatiques utilisent le portail d'enregistrement sans contact.
Les utilisateurs types de cette API peuvent être:
- Les fournisseurs EMM prennent en charge l'enregistrement sans contact dans leur console.
- Des développeurs informatiques d'entreprise créent des outils pour automatiser l'enregistrement sans contact tâches.
Ressources principales
Les configurations et les appareils sont les principales ressources que vous utilisez dans l'API. Une les entreprises peuvent également créer des configurations et des appareils à l'aide du système d'inscription.
- Configuration
- Les administrateurs informatiques définissent les options de provisionnement des appareils à l'aide d'une configuration. Ces configurations incluent des règles de gestion des appareils mobiles EMM et des coordonnées accessibles aux aider les utilisateurs. Les configurations sont au cœur de l'API. Vous les utilisez donc dans de nombreuses méthodes. Pour en savoir plus, consultez la section Configurations ci-dessous.
- Appareil
- Appareil Android auprès duquel une organisation a acheté l'enregistrement sans contact leur revendeur. Appliquer une configuration pour inclure l'appareil dans l'enregistrement sans contact de l'inscription. Les appareils ont des ID matériel et des métadonnées associées. Pour en savoir plus, consultez Appareils ci-dessous.
- DPC
- Référence en lecture seule à un DPC d'un fournisseur EMM (règles relatives aux appareils
manette). Ajouter un DPC
à une configuration pour choisir la solution EMM pour les appareils. Tous les DPC répertoriés
sont compatibles avec l'enregistrement sans contact et sont disponibles sur Google Play. À
Pour en savoir plus, consultez
Dpc
.
Pour obtenir la liste de toutes les ressources et méthodes d'API que votre application peut utiliser, consultez la Documentation de référence de l'API
Configurations
La ressource d'API Configuration
combine les
suivantes:
- Le DPC de l'EMM est installé sur les appareils.
- Règles EMM appliquées aux appareils.
- Coordonnées affichées sur l'appareil pour aider les utilisateurs lors de la configuration.
L'API permet à votre application de gérer les configurations pour les administrateurs informatiques. Appelez l'API pour : récupérer, créer, mettre à jour et supprimer des configurations. L'exemple ci-dessous montre comment créez une configuration:
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()
Lorsque vous mettez à jour une configuration à l'aide de l'API patch, n'oubliez pas d'inclure le paramètre
masque de champ – ou
pour chaque champ que vous ne souhaitez pas attribuer à null
. Voir Paramètre par défaut
de configuration (ci-dessous), pour voir un exemple
mettre à jour efficacement une configuration.
Supprimer les configurations
Vous ne pouvez pas supprimer une configuration si elle est toujours appliquée aux appareils. Si vous essayez de
supprimer une configuration en cours d'utilisation, la méthode API renvoie une requête HTTP 400 Bad Request
code d'état et un message expliquant combien d'appareils utilisent la configuration.
Appeler
customers.devices.removeConfiguration
pour supprimer la configuration des appareils avant de réessayer.
Configurations par défaut
L'enregistrement sans contact fonctionne mieux lorsqu'une organisation définit une valeur par défaut
qui sera appliquée à tous les nouveaux appareils achetés par l'organisation.
Demandez aux administrateurs informatiques de définir une configuration par défaut si aucune configuration n'est définie.
L'exemple ci-dessous montre comment définir une configuration existante comme configuration par défaut
définir isDefault
sur 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()
Il ne peut y avoir qu'une seule configuration par défaut. Créer une nouvelle configuration par défaut
définit le champ isDefault
d'une configuration précédente sur false
. Vous devrez peut-être
Actualisez les instances Configuration
mises en cache pour afficher les valeurs correctes dans la
isDefault
.
Guider les utilisateurs des appareils
La configuration sans contact affiche des conseils personnalisés pour les utilisateurs dans la section de configuration de l'appareil.
Assistant pour aider les utilisateurs. Vous devez inclure un numéro de téléphone et une adresse e-mail de contact
associée, ainsi que le nom de l'organisation qui gère l'appareil
configuration. Nous vous recommandons également d'inclure une ou deux phrases dans
Champ customMessage
pour fournir plus de détails sur la situation de l'utilisateur
appareil.
Parce que l'utilisateur ne pourra pas appeler ni envoyer d'e-mails depuis l'appareil qu'il configure formatez le numéro de téléphone et l'adresse e-mail pour faciliter la lecture les informations.
Appareils
Les revendeurs créent des appareils lorsqu'un client les achète pour l'enregistrement sans contact.
enregistrement : les administrateurs informatiques ne peuvent pas créer d'appareils. Pour utiliser des appareils, appelez des méthodes sur
la ressource d'API Device
. Si vous devez effectuer une recherche
pour les appareils, répertoriez tous les appareils et filtrez chaque lot localement dans votre application. Pour
Pour obtenir un exemple, consultez la section Résultats paginés ci-dessous.
Configurez des appareils
L'application d'une configuration à un appareil enregistre celui-ci pour l'enregistrement sans contact.
de l'inscription. Pour appliquer une configuration, appelez
customers.devices.applyConfiguration
Après l'application d'une configuration, l'appareil est automatiquement provisionné
lors du premier démarrage ou
au prochain rétablissement de la configuration d'usine. L'exemple ci-dessous montre comment appliquer
à une collection d'appareils:
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()
Pour supprimer la configuration d'un appareil, appelez
customers.devices.removeConfiguration
Le changement prend effet après le rétablissement de la configuration d'usine de l'appareil.
Retirer la revendication d'appareils
Les administrateurs informatiques peuvent annuler la revendication d'un appareil pour le retirer de l'enregistrement sans contact. Un ingénieur informatique
l'administrateur peut retirer la revendication d'un appareil qu'il souhaite transférer
vers un autre compte, vendre,
ou retournées au revendeur. Appeler la méthode
customers.devices.unclaim
pour retirer la revendication d'un appareil
d'une entreprise.
L'exemple ci-dessous montre comment retirer la revendication d'un appareil associé à son code IMEI et nom du fabricant:
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()
Métadonnées de l'appareil
Un administrateur informatique peut voir les métadonnées associées à l'appareil par le revendeur. Campagne display ces métadonnées d'appareil dans votre application pour aider les administrateurs informatiques à reconnaître les appareils.
Pour en savoir plus sur les métadonnées susceptibles de s'afficher, consultez la documentation Appareil guide des métadonnées pour les revendeurs.
Résultats paginés
La méthode API customers.devices.list
peut renvoyer
de très grandes listes
d'appareils. Pour réduire la taille de la réponse, cette API et d'autres
(telles que customers.list
) sont compatibles avec les résultats paginés. Avec
paginés de résultats paginés, votre application peut demander et traiter de manière itérative de longues listes
une page à la fois.
Après avoir appelé la méthode API, vérifiez si la réponse inclut une valeur pour
nextPageToken
Si nextPageToken
n'est pas
null
, votre application peut l'utiliser pour extraire une autre page d'appareils en appelant la méthode
à nouveau. Vous devez définir une limite maximale pour le nombre d'appareils dans
Paramètre pageSize
. Si nextPageToken
est défini sur null
, votre application a demandé l'autorisation
dernière page.
L'exemple de méthode ci-dessous montre comment votre application peut imprimer une liste d'appareils, un page à la fois:
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'])
Commencer
Pour savoir comment autoriser les appels d'API, consultez la section Autorisation. Si vous souhaitez explorer les API, consultez les guides de démarrage rapide Java .NET Python : Vous pouvez utiliser un colab pour afficher exemples d'appels d'API et essayez d'appeler l'API vous-même.