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

Fonctionnement

Introduction

L'API d'enregistrement sans contact permet aux revendeurs d'appareils d'automatiser leur intégration. Les outils de vente de votre entreprise peuvent intégrer l'enregistrement sans contact, ce qui permet d'améliorer la productivité de vos utilisateurs et de vos clients. Utilisez l'API pour aider vos utilisateurs :

Attribuer les appareils achetés au compte d'enregistrement sans contact d'un client.
Créer votre propre compte d'enregistrement sans contact
Joindre le numéro de téléphone et les métadonnées de commande de votre organisation à des appareils
Créer des rapports à propos des appareils affectés à vos clients

Ce document présente l'API et décrit les différents modèles. Si vous souhaitez explorer l'API vous-même, essayez un guide de démarrage rapide pour Java, .NET ou Python.

Concepts de l'API

Les clients et les appareils sont les ressources principales que vous utilisez dans l'API. Pour créer clients, appelez create. Vous pouvez créer des appareils à l'aide des méthodes de l'API Claim (voir ci-dessous). Votre organisation peut également créer des clients et des appareils à l'aide du portail d'enregistrement sans contact ;

Relation entre l'appareil et les ressources client

Client: Entreprises auxquelles votre organisation vend des appareils. Les clients disposent d'un name et d'un ID. Utilisez un client lorsque vous souhaitez revendiquer ou retrouver ses appareils. Pour en savoir plus, consultez Customer.
Appareil: Un appareil Android ou ChromeOS compatible avec l'enregistrement sans contact pour votre organisation que vous vendez à un client. Les appareils disposent d'ID matériels, de métadonnées et de réclamations client. Les appareils sont au cœur de l'API. Vous les utilisez donc dans presque tous méthodes. Pour en savoir plus, consultez Device.
DeviceIdentifier: Encapsule les ID matériels, tels que l'IMEI ou le MEID, pour identifier un appareil fabriqué. Utilisez un DeviceIdentifier pour cibler l'appareil que vous souhaitez rechercher, mettre à jour ou revendiquer. Pour en savoir plus, consultez Identifiants
DeviceMetadata: Stocke les paires clé-valeur de métadonnées pour l'appareil. Utilisez DeviceMetadata pour stocker les métadonnées de votre organisation. À Pour en savoir plus, consultez Métadonnées de l'appareil.

Pour obtenir la liste de toutes les méthodes et ressources d'API que votre application peut utiliser, consultez la documentation de référence sur les API.

Créer des clients

Pour les appareils Android, le revendeur est responsable de la création du compte client au nom de son client. Le client utilisera ce compte pour accéder au portail d'enregistrement sans contact et configurer les paramètres de provisionnement de ses appareils. Cela n'est pas nécessaire pour les appareils ChromeOS, qui disposent déjà d'un Workspace qu'ils utiliseront pour configurer leurs paramètres de provisionnement.

Vous pouvez appeler la méthode API create pour créer des comptes clients pour l'enregistrement sans contact. Parce que vos clients voient nom de l'entreprise sur son portail d'enregistrement sans contact, l'utilisateur de votre application doit pour confirmer qu'elle est correcte. Une fois le client créé, vous ne pouvez plus modifier son nom.

Vous devez inclure au moins une adresse e-mail professionnelle, associée à un un compte Google, pour être le propriétaire. Vous ne pouvez pas utiliser de comptes Gmail personnels avec le API. Si le client a besoin d'aide pour associer le compte, envoyez-lui les instructions de la page Associer un compte Google.

Une fois que vous avez créé un client en appelant l'API, il gère l'accès de ses employés au portail. Vous ne pouvez pas modifier les utilisateurs de vos clients à l'aide de l'API. L'extrait de code ci-dessous montre comment créer un client :

Java

// Provide the customer data as a Company type.
// The API requires a name and owners.
Company customer = new Company();
customer.setCompanyName("XYZ Corp");
customer.setOwnerEmails(Arrays.asList("liz@example.com", "darcy@example.com"));
customer.setAdminEmails(Collections.singletonList("jane@example.com"));

// Use our reseller ID for the parent resource name.
String parentResource = String.format("partners/%d", PARTNER_ID);

// Call the API to create the customer using the values in the company object.
CreateCustomerRequest body = new CreateCustomerRequest();
body.setCustomer(customer);
Company response = service.partners().customers().create(parentResource, body).execute();

.NET

// Provide the customer data as a Company type.
// The API requires a name and owners.
var customer = new Company
{
    CompanyName = "XYZ Corp",
    OwnerEmails = new String[] { "liz@example.com", "darcy@example.com" },
    AdminEmails = new String[] { "jane@example.com" }
};

// Use our reseller ID for the parent resource name.
var parentResource = String.Format("partners/{0}", PartnerId);

// Call the API to create the customer using the values in the company object.
var body = new CreateCustomerRequest
{
    Customer = customer
};
var request = service.Partners.Customers.Create(body, parentResource);
var response = request.Execute();

Python

# Provide the customer data as a Company type. The API requires
# a name and at least one owner.
company = {'companyName':'XYZ Corp', \
  'ownerEmails':['liz@example.com', 'darcy@example.com'], \
  'adminEmails':['jane@example.com']}

# Use our reseller ID for the parent resource name.
parent_resource = 'partners/{0}'.format(PARTNER_ID)

# Call the API to create the customer using the values in the company object.
response = service.partners().customers().create(parent=parent_resource,
    body={'customer':company}).execute()

Pour en savoir plus sur les rôles de propriétaire et d'administrateur pour les employés de votre client, consultez Utilisateurs du portail.

Revendiquer les appareils des clients

Une fois que vos clients auront acheté des appareils, ils devront configurer les paramètres de provisionnement de ces appareils dans leur compte. La revendication d'un appareil l'ajoute à l'enregistrement sans contact et permet au client de configurer les paramètres de provisionnement.

L'enregistrement de provisionnement d'un appareil comporte une section pour l'enregistrement sans contact. Pour attribuer l'appareil, revendiquez la section d'enregistrement sans contact de l'enregistrement pour un client. Appelez la méthode partners.devices.claim ou partners.devices.claimAsync avec la le client comme argument. Fournissez toujours SECTION_TYPE_ZERO_TOUCH comme valeur pour sectionType

Vous devrez retirer la revendication (voir ci-dessous) de l'appareil d'un client avant de pouvoir revendiquer le même appareil pour un autre client. Méthodes de revendication valider les champs DeviceIdentifier ; (code IMEI ou MEID, ou numéro de série, par exemple), le nom et le modèle du fabricant, ainsi que les ID d'appareil certifié pour les appareils ChromeOS, lors de la création d'un appareil.

L'extrait de code ci-dessous montre comment revendiquer un appareil :

Java

// Identify the device to claim.
DeviceIdentifier identifier = new DeviceIdentifier();
// The manufacturer value is optional but recommended for cellular devices
identifier.setManufacturer("Google");
identifier.setImei("098765432109875");

// Create the body to connect the customer with the device.
ClaimDeviceRequest body = new ClaimDeviceRequest();
body.setDeviceIdentifier(identifier);
body.setCustomerId(customerId);
body.setSectionType("SECTION_TYPE_ZERO_TOUCH");

// Claim the device.
ClaimDeviceResponse response = service.partners().devices().claim(PARTNER_ID, body).execute();

.NET

// Identify the device to claim.
var deviceIdentifier = new DeviceIdentifier
{
    // The manufacturer value is optional but recommended for cellular devices
    Manufacturer = "Google",
    Imei = "098765432109875"
};

// Create the body to connect the customer with the device.
ClaimDeviceRequest body = new ClaimDeviceRequest
{
    DeviceIdentifier = deviceIdentifier,
    CustomerId = CustomerId,
    SectionType = "SECTION_TYPE_ZERO_TOUCH"
};

// Claim the device.
var response = service.Partners.Devices.Claim(body, PartnerId).Execute();

Python

# Identify the device to claim.
# The manufacturer value is optional but recommended for cellular devices
device_identifier = {'manufacturer':'Google', 'imei':'098765432109875'}

# Create the body to connect the customer with the device.
request_body = {'deviceIdentifier':device_identifier, \
    'customerId':customer_id, \
    'sectionType':'SECTION_TYPE_ZERO_TOUCH'}

# Claim the device.
response = service.partners().devices().claim(partnerId=PARTNER_ID,
    body=request_body).execute()

Rétracter la revendication d'appareils

Votre organisation peut retirer la revendication d'un appareil à un client. Retirer la revendication d'un appareil et le supprime de l'enregistrement sans contact. Un revendeur peut annuler la revendication d'un appareil qu'il souhaite migrer vers un autre compte, retourner ou qui a été revendiqué par erreur. Appelez la méthode partners.devices.unclaim ou partners.devices.unclaimAsync pour retirer une revendication appareil d'un client.

Fournisseurs

Vous pouvez faire appel à des fournisseurs pour représenter les revendeurs partenaires de votre réseau de concessionnaires, au sein d'un réseau mondial de revendeurs ou dans toute entreprise appareils en votre nom. Les fournisseurs vous aident à distinguer vos utilisateurs, vos clients appareils:

Les fournisseurs que vous créez ne peuvent pas voir votre compte d'enregistrement sans contact ni chaque d'autres utilisateurs.
Vous pouvez consulter les clients et les appareils de vos fournisseurs, et annuler l'enregistrement de leurs appareils. Toutefois, vous ne pouvez pas attribuer d'appareils clients.

Utilisez le portail pour créer des fournisseurs pour votre organisation. Vous ne pouvez pas utiliser l'API. Votre rôle au niveau du compte doit être : Owner pour créer un fournisseur Si votre organisation a des fournisseurs, vous pouvez appeler partners.vendors.list pour lister vos fournisseurs et partners.vendors.customers.list pour trouver les clients de votre fournisseur. L'exemple suivant utilise ces deux méthodes pour imprimer un rapport indiquant l'état des conditions d'utilisation pour les clients des fournisseurs :

Java

// First, get the organization's vendors.
String parentResource = String.format("partners/%d", PARTNER_ID);
ListVendorsResponse results = service.partners().vendors().list(parentResource).execute();
if (results.getVendors() == null) {
  return;
}

// For each vendor, report the company name and a maximum 5 customers.
for (Company vendor: results.getVendors()) {
  System.out.format("\n%s customers\n", vendor.getCompanyName());
  System.out.println("---");
  // Use the vendor's API resource name as the parent resource.
  AndroidProvisioningPartner.Partners.Vendors.Customers.List customerRequest =
      service.partners().vendors().customers().list(vendor.getName());
  customerRequest.setPageSize(5);
  ListVendorCustomersResponse customerResponse = customerRequest.execute();

  List<Company> customers = customerResponse.getCustomers();
  if (customers == null) {
    System.out.println("No customers");
    break;
  } else {
    for (Company customer: customers) {
      System.out.format("%s: %s\n",
          customer.getCompanyName(),
          customer.getTermsStatus());
    }
  }
}

.NET

// First, get the organization's vendors.
var parentResource = String.Format("partners/{0}", PartnerId);
var results = service.Partners.Vendors.List(parentResource).Execute();
if (results.Vendors == null)
{
    return;
}

// For each vendor, report the company name and a maximum 5 customers.
foreach (Company vendor in results.Vendors)
{
    Console.WriteLine("\n{0} customers", vendor);
    Console.WriteLine("---");
    // Use the vendor's API resource name as the parent resource.
    PartnersResource.VendorsResource.CustomersResource.ListRequest customerRequest =
        service.Partners.Vendors.Customers.List(vendor.Name);
    customerRequest.PageSize = 5;
    var customerResponse = customerRequest.Execute();

    IList<Company> customers = customerResponse.Customers;
    if (customers == null)
    {
        Console.WriteLine("No customers");
        break;
    }
    else
    {
        foreach (Company customer in customers)
        {
            Console.WriteLine("{0}: {1}", customer.Name, customer.TermsStatus);
        }
    }
}

Python

# First, get the organization's vendors.
parent_resource = 'partners/{0}'.format(PARTNER_ID)
vendor_response = service.partners().vendors().list(
    parent=parent_resource).execute()
if 'vendors' not in vendor_response:
  return

# For each vendor, report the company name and a maximum 5 customers.
for vendor in vendor_response['vendors']:
  print '\n{0} customers'.format(vendor['companyName'])
  print '---'
  # Use the vendor's API resource name as the parent resource.
  customer_response = service.partners().vendors().customers().list(
      parent=vendor['name'], pageSize=5).execute()
  if 'customers' not in customer_response:
    print 'No customers'
    break
  for customer in customer_response['customers']:
    print '  {0}: {1}'.format(customer['name'], customer['termsStatus'])

Si vous possédez plusieurs appareils, vous devrez peut-être savoir quel revendeur ou fournisseur les a revendiqués. Pour obtenir l'ID numérique du revendeur, inspectez la valeur du champ resellerId dans l'enregistrement de réclamation d'un appareil.

Votre organisation peut retirer la revendication d'un appareil revendiqué par le fournisseur. Pour les autres appels d'API qui modifient les appareils, vous devez vérifier que votre organisation a revendiqué l'appareil avant d'appeler la méthode de l'API. L'exemple suivant montre comment procéder :

Java

// Get the devices claimed for two customers: one of our organization's
// customers and one of our vendor's customers.
FindDevicesByOwnerRequest body = new FindDevicesByOwnerRequest();
body.setSectionType("SECTION_TYPE_ZERO_TOUCH");
body.setCustomerId(Arrays.asList(resellerCustomerId, vendorCustomerId));
body.setLimit(MAX_PAGE_SIZE);
FindDevicesByOwnerResponse response =
    service.partners().devices().findByOwner(PARTNER_ID, body).execute();
if (response.getDevices() == null) {
  return;
}

for (Device device: response.getDevices()) {
  // Confirm the device was claimed by our reseller and not a vendor before
  // updating metadata in another method.
  for (DeviceClaim claim: device.getClaims()) {
    if (claim.getResellerId() == PARTNER_ID) {
      updateDeviceMetadata(device.getDeviceId());
      break;
    }
  }
}

.NET

// Get the devices claimed for two customers: one of our organization's
// customers and one of our vendor's customers.
FindDevicesByOwnerRequest body = new FindDevicesByOwnerRequest
{
    Limit = MaxPageSize,
    SectionType = "SECTION_TYPE_ZERO_TOUCH",
    CustomerId = new List<long?>
    {
        resellerCustomerId,
        vendorCustomerId
    }
};
var response = service.Partners.Devices.FindByOwner(body, PartnerId).Execute();
if (response.Devices == null)
{
    return;
}

foreach (Device device in response.Devices)
{
    // Confirm the device was claimed by our reseller and not a vendor before
    // updating metadata in another method.
    foreach (DeviceClaim claim in device.Claims)
    {
        if (claim.ResellerId == PartnerId)
        {
            UpdateDeviceMetadata(device.DeviceId);
            break;
        }
    }
}

Python

# Get the devices claimed for two customers: one of our organization's
# customers and one of our vendor's customers.
request_body = {'limit':MAX_PAGE_SIZE, \
  'pageToken':None, \
  'customerId':[reseller_customer_id, vendor_customer_id], \
  'sectionType':'SECTION_TYPE_ZERO_TOUCH'}
response = service.partners().devices().findByOwner(partnerId=PARTNER_ID,
    body=request_body).execute()

for device in response['devices']:
  # Confirm the device was claimed by our reseller and not a vendor before
  # updating metadata in another method.
  for claim in device['claims']:
    if claim['resellerId'] == PARTNER_ID:
      update_device_metadata(device['deviceId'])
      break

Opérations par lot de longue durée

L'API inclut des versions asynchrones des méthodes de l'appareil. Ces méthodes permettent de traiter par lot de nombreux appareils, tandis que les méthodes synchrones traitent un appareil pour chaque requête d'API. Les noms de méthodes asynchrones comportent un suffixe Async, par exemple claimAsync.

Les méthodes d'API asynchrones renvoient un résultat avant la fin du traitement. Les méthodes asynchrones permettent également à votre application (ou outil) de rester réactive pour vos des utilisateurs pendant qu'ils attendent la fin d'une opération de longue durée. Votre application doit vérifier régulièrement l'état de l'opération.

Opérations

Vous utilisez un Operation pour suivre une opération par lots de longue durée. A un appel réussi à une méthode asynchrone renvoie une référence à l'opération dans la réponse. L'extrait JSON ci-dessous présente une réponse typique après l'appel de updateMetadataAsync :

{
  "name": "operations/apibatchoperation/1234567890123476789"
}

Chaque opération contient une liste de tâches individuelles. Appelez operations.get pour obtenir des informations sur l'état et les résultats des tâches contenues dans l'opération. L'extrait de code ci-dessous vous montre comment procéder. Dans votre propre application, vous devrez gérer les erreurs.

Java

// Build out the request body to apply the same order number to a customer's
// purchase of 2 devices.
UpdateMetadataArguments firstUpdate = new UpdateMetadataArguments();
firstUpdate.setDeviceMetadata(metadata);
firstUpdate.setDeviceId(firstTargetDeviceId);

UpdateMetadataArguments secondUpdate = new UpdateMetadataArguments();
secondUpdate.setDeviceMetadata(metadata);
secondUpdate.setDeviceId(firstTargetDeviceId);

// Start the device metadata update.
UpdateDeviceMetadataInBatchRequest body = new UpdateDeviceMetadataInBatchRequest();
body.setUpdates(Arrays.asList(firstUpdate, secondUpdate));
Operation response = service
    .partners()
    .devices()
    .updateMetadataAsync(PARTNER_ID, body)
    .execute();

// Assume the metadata update started, so get the Operation for the update.
Operation operation = service.operations().get(response.getName()).execute();

.NET

// Build out the request body to apply the same order number to a customer's
// purchase of 2 devices.
var updates = new List<UpdateMetadataArguments>
{
    new UpdateMetadataArguments
    {
        DeviceMetadata = metadata,
        DeviceId = firstTargetDeviceId
    },
    new UpdateMetadataArguments
    {
        DeviceMetadata = metadata,
        DeviceId = secondTargetDeviceId
    }
};

// Start the device metadata update.
UpdateDeviceMetadataInBatchRequest body = new UpdateDeviceMetadataInBatchRequest
{
    Updates = updates
};
var response = service.Partners.Devices.UpdateMetadataAsync(body, PartnerId).Execute();

// Assume the metadata update started, so get the Operation for the update.
Operation operation = service.Operations.Get(response.Name).Execute();

Python

# Build out the request body to apply the same order number to a customer's
# purchase of 2 devices.
updates = [{'deviceMetadata':metadata,'deviceId':first_target_device_id},
    {'deviceMetadata':metadata,'deviceId':second_target_device_id}]

# Start the device metadata update.
response = service.partners().devices().updateMetadataAsync(
    partnerId=PARTNER_ID, body={'updates':updates}).execute()

# Assume the metadata update started, so get the Operation for the update.
operation = service.operations().get(name=response['name']).execute()

Pour savoir si une opération s'est terminée, consultez l'opération pour un champ done. dont la valeur est true. Si done est manquant ou false, l'opération est toujours en cours d'exécution.

Réponses

Une fois une opération terminée, l'API met à jour l'opération avec le résultat, même si toutes les tâches individuelles aboutissent ou non. Le champ response est un objet DevicesLongRunningOperationResponse qui détaille le traitement de chaque appareil dans l'opération.

Inspectez le champ successCount pour déterminer efficacement si des tâches ont échoué et éviter d'itérer sur de grandes listes de résultats. Le champ perDeviceStatus de DevicesLongRunningOperationResponse est une liste de Instances OperationPerDevice détaillant chaque appareil dans l'opération. L'ordre de la liste correspond aux tâches de la requête d'origine.

Chaque tâche OperationPerDevice contient un champ result et un résumé de rappel de la requête reçue par le serveur. Vérifiez si la tâche a réussi ou échoué à l'aide du champ result.

L'extrait JSON ci-dessous montre une partie d'une réponse typique d'une opération après un appel à updateMetadataAsync :

"response": {
  "perDeviceStatus": [
    {
      "result": {
        "deviceId": "12345678901234567",
        "status": "SINGLE_DEVICE_STATUS_SUCCESS"
      },
      "updateMetadata": {
        "deviceId": "12345678901234567",
        "deviceMetadata": {
          "entries": {
            "phonenumber": "+1 (800) 555-0100"
          }
        }
      }
    }
  ],
  "successCount": 1
}

Suivre la progression

Si votre application doit suivre la progression, vous devez régulièrement réextraire le opération. Le champ metadata contient une instance DevicesLongRunningOperationMetadata pour aider votre application à vérifier la dernière progression d'une opération en cours d'exécution. Utilisez les champs de DevicesLongRunningOperationMetadata listés dans le tableau suivant pour suivre la progression de l'opération :

Champ	Utilisation type
`processingStatus`	La valeur passe de `BATCH_PROCESS_PENDING` à `BATCH_PROCESS_IN_PROGRESS`, puis à `BATCH_PROCESS_PROCESSED` au fur et à mesure de l'opération.
`progress`	Pourcentage de mises à jour traitées. Votre application peut utiliser afin d’estimer une date de fin. Étant donné que la valeur `progress` peut être 100 pendant la fin de l'opération, vérifiez le champ `done` d'une opération pour savoir si elle est terminée et si elle a un résultat.
`devicesCount`	Indique le nombre de mises à jour dans l'opération. Ce peuvent différer du nombre de mises à jour si l'API ne parvient pas à analyser certaines mises à jour.

L'exemple simplifié ci-dessous montre comment une application peut utiliser les métadonnées de progression pour définir des intervalles de sondage. Dans votre application, vous aurez peut-être besoin d'une tâche plus complexe d'exécution pour l'interrogation. Vous devez également ajouter la gestion des erreurs.

Java

// Milliseconds between polling the API.
private static long MIN_INTERVAL = 2000;
private static long MAX_INTERVAL = 10000;

// ...
// Start the device metadata update.
Operation response = service
    .partners()
    .devices()
    .updateMetadataAsync(PARTNER_ID, body)
    .execute();
String operationName = response.getName();

// Start polling for completion.
long startTime = new Date().getTime();
while (true) {

  // Get the latest update on the operation's progress using the API.
  Operation operation = service.operations().get(operationName).execute();

  if (operation.get("done") != null && operation.getDone()) {
    // The operation is finished. Print the status.
    System.out.format("Operation complete: %s of %s successful device updates\n",
        operation.getResponse().get("successCount"),
        operation.getMetadata().get("devicesCount"));
    break;

  } else {
    // Estimate how long the operation *should* take - within min and max value.
    BigDecimal opProgress = (BigDecimal) operation.getMetadata().get("progress");
    double progress = opProgress.longValue();
    long interval = MAX_INTERVAL;
    if (progress > 0) {
      interval = (long) ((new Date().getTime() - startTime) *
          ((100.0 - progress) / progress));
    }
    interval = Math.max(MIN_INTERVAL, Math.min(interval, MAX_INTERVAL));

    // Sleep until the operation should be complete.
    Thread.sleep(interval);
  }
}

.NET

// Milliseconds between polling the API.
private static double MinInterval = 2000;
private static double MaxInterval = 10000;

// ...
// Start the device metadata update.
var response = service.Partners.Devices.UpdateMetadataAsync(body, PartnerId).Execute();
var operationName = response.Name;

// Start polling for completion.
var startTime = DateTime.Now;
while (true)
{

    // Get the latest update on the operation's progress using the API.
    Operation operation = service.Operations.Get(operationName).Execute();

    if (operation.Done == true)
    {
        // The operation is finished. Print the status.
        Console.WriteLine("Operation complete: {0} of {1} successful device updates",
                          operation.Response["successCount"],
                          operation.Metadata["devicesCount"]);
        break;
    }
    else
    {
        // Estimate how long the operation *should* take - within min and max value.
        double progress = (double)(long)operation.Metadata["progress"];
        double interval = MaxInterval;
        if (progress > 0)
        {
            interval = DateTime.Now.Subtract(startTime).TotalMilliseconds *
                                     ((100.0 - progress) / progress);
        }
        interval = Math.Max(MinInterval, Math.Min(interval, MaxInterval));

        // Sleep until the operation should be complete.
        System.Threading.Thread.Sleep((int)interval);
    }
}

Python

# Seconds between polling the API.
MIN_INTERVAL = 2;
MAX_INTERVAL = 10;

# ...
# Start the device metadata update
response = service.partners().devices().updateMetadataAsync(
  partnerId=PARTNER_ID, body={'updates':updates}).execute()

op_name = response['name']
start_time = time.time()

# Start polling for completion
while True:
  # Get the latest update on the operation's progress using the API
  op = service.operations().get(name=op_name).execute()

  if 'done' in op and op['done']:
    # The operation is finished. Print the status.
    print('Operation complete: {0} of {1} successful device updates'.format(
      op['response']['successCount'], op['metadata']['devicesCount']
    ))
    break
  else:
    # Estimate how long the operation *should* take - within min and max.
    progress = op['metadata']['progress']
    interval = MIN_INTERVAL
    if progress > 0:
      interval = (time.time() - start_time) * ((100.0 - progress) / progress)
    interval = max(MIN_INTERVAL, min(interval, MAX_INTERVAL))

    # Sleep until the operation should be complete.
    time.sleep(interval)

Choisissez une méthode de sondage pertinente pour les utilisateurs de votre application. Certains utilisateurs d'applications peuvent bénéficier de mises à jour régulières de la progression s'ils attendent la fin d'un processus.

Résultats paginés

La méthode de l'API partners.devices.findByOwner peut renvoyer de très longues listes d'appareils. Pour réduire la taille de la réponse, cette fonction d'autres méthodes d'API (comme partners.devices.findByIdentifier) pour prendre en charge les résultats paginés. Avec des résultats paginés, votre application peut procéder de manière itérative de demander et de traiter de grandes 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 à nouveau la méthode. Vous devez définir une limite supérieure pour le nombre d'appareils dans le paramètre limit. Si nextPageToken est null, votre application a demandé la dernière page.

L'exemple de méthode ci-dessous montre comment votre application peut imprimer une liste d'appareils, une page à la fois :

Java

private static long MAX_PAGE_SIZE = 10;

// ...
/**
 * Demonstrates how to loop through paginated lists of devices.
 * @param pageToken       The token specifying which result page to return.
 * @throws IOException    If the zero-touch API call fails.
 */
private void printDevices(String pageToken) throws IOException {

  // Create the request body to find the customer's devices.
  FindDevicesByOwnerRequest body = new FindDevicesByOwnerRequest();
  body.setLimit(MAX_PAGE_SIZE);
  body.setSectionType("SECTION_TYPE_ZERO_TOUCH");
  body.setCustomerId(Collections.singletonList(targetCustomerId));

  // Call the API to get a page of Devices. Send a page token from the method
  // argument (might be None). If the page token is None, the API returns the first page.
  FindDevicesByOwnerResponse response =
      service.partners().devices().findByOwner(PARTNER_ID, body).execute();
  if (response.getDevices() == null) {
    return;
  }

  // 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 and print the devices.
  if (response.getNextPageToken() != null) {
    this.printDevices(response.getNextPageToken());
  }
}

// ...
// Pass null to start printing the first page of devices.
printDevices(null);

.NET

private static int MaxPageSize = 10;

// ...
/// <summary>Demonstrates how to loop through paginated lists of devices.</summary>
/// <param name="pageToken">The token specifying which result page to return.</param>
private void PrintDevices(string pageToken)
{
    // Create the request body to find the customer's devices.
    FindDevicesByOwnerRequest body = new FindDevicesByOwnerRequest
    {
        PageToken = pageToken,
        Limit = MaxPageSize,
        SectionType = "SECTION_TYPE_ZERO_TOUCH",
        CustomerId = new List<long?>
        {
            targetCustomerId
        }
    };

    // Call the API to get a page of Devices. Send a page token from the method
    // argument (might be None). If the page token is None, the API returns the first page.
    var response = service.Partners.Devices.FindByOwner(body, PartnerId).Execute();
    if (response.Devices == null)
    {
        return;
    }

    // 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(response.NextPageToken);
    }
}

// ...
// Pass null to start printing the first page of devices.
PrintDevices(null);

Python

MAX_PAGE_SIZE = 10;

# ...
def print_devices(page_token):
  """Demonstrates how to loop through paginated lists of devices.

  Args:
    page_token: The token specifying which result page to return.
  """

   # Create the body to find the customer's devices.
  request_body = {'limit':MAX_PAGE_SIZE, \
    'pageToken':page_token, \
    'customerId':[target_customer_id], \
    'sectionType':'SECTION_TYPE_ZERO_TOUCH'}

  # Call the API to get a page of Devices. Send a page token from the method
  # argument (might be None). If the page token is None,
  # the API returns the first page.
  response = service.partners().devices().findByOwner(partnerId=PARTNER_ID,
    body=request_body).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(response['nextPageToken'])

# ...
# Pass None to start printing the first page of devices.
print_devices(None);

Étapes suivantes

Maintenant que vous savez comment fonctionne l'API, essayez les exemples avec un guide de démarrage rapide pour Java .NET ou Python : Vous pouvez utiliser un colab pour afficher exemples d'appels d'API et essayez d'appeler l'API vous-même.