Cette page a été traduite par l'API Cloud Translation.

Fonctionnement

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, consultez la courte introduction sur android.com.

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.

Relation entre l'appareil et les ressources client

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 disposent d'ID matériels et de métadonnées associées. Pour en savoir plus, consultez Appareils ci-dessous.
DPC: Référence en lecture seule à l'outil de contrôle des règles relatives aux appareils (DPC) d'un EMM. Ajoutez un DPC à une configuration pour sélectionner 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 répertorier 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 de l'API renvoie un code d'état HTTP 400 Bad Request et un message expliquant le nombre d'appareils qui 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. Envisagez d'inviter les administrateurs informatiques à définir une configuration par défaut si aucune 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.

Étant donné que l'utilisateur ne pourra pas appeler ni envoyer d'e-mails depuis l'appareil qu'il configure, mettez en forme le numéro de téléphone et l'adresse e-mail pour faciliter la consultation des informations.

Appareils

Les revendeurs créent des appareils lorsqu'un client les achète pour l'enregistrement sans contact. 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 rechercher des appareils, listez-les tous et filtrez chaque lot localement dans votre application. Pour en savoir plus, consultez la section Résultats paginés ci-dessous.

Configurez des appareils

L'application d'une configuration à un appareil l'enregistre pour l'inscription sans contact. 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.

Réclâmer des appareils

Les administrateurs informatiques peuvent retirer 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 page 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 de l'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'])

Premiers pas

Découvrez ensuite comment autoriser les appels d'API dans 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.