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 ont un name et 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é. Utiliser 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 des métadonnées pour l'appareil. Utilisez DeviceMetadata pour stocker les métadonnées de votre organisation. Pour en savoir plus, consultez la section 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 d'API create pour créer des comptes client pour l'enregistrement sans contact. Étant donné que vos clients voient le nom de l'entreprise dans leur portail d'enregistrement sans contact, l'utilisateur de votre application doit confirmer qu'il est correct. Une fois le nom du client créé, vous ne pouvez plus modifier son nom. client.

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'activité de ses employés l'accès au portail : vous ne pouvez pas modifier les paramètres aux utilisateurs 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 des employés de votre client, consultez la page 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. Le fait de revendiquer un appareil entraîne l'ajout de celui-ci à 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. Toi attribuer l'appareil en revendiquant la section d'enregistrement sans contact de l'enregistrement client. Appelez les méthodes partners.devices.claim ou partners.devices.claimAsync avec le client comme argument. Fournissez toujours SECTION_TYPE_ZERO_TOUCH comme valeur pour sectionType.

Vous devez annuler la revendication (voir ci-dessous) de l'appareil d'un client avant de pouvoir le revendiquer 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()

Retrait d'appareils

Votre organisation peut annuler la revendication d'un appareil par un client. Si vous ne revendiquez plus un appareil, il est supprimé de l'enregistrement sans contact. Un revendeur peut retirer la revendication d'un appareil qu'il souhaite migrer vers un autre compte, être renvoyé ou qui a été revendiqué par erreur. Appelez la méthode partners.devices.unclaim ou partners.devices.unclaimAsync pour annuler la revendication d'un appareil par un client.

Fournisseurs

Vous pouvez utiliser des fournisseurs pour représenter des partenaires revendeurs dans votre réseau de concessionnaires, des opérateurs locaux dans un réseau de revendeurs mondial ou toute organisation qui vend des 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 aux clients de vos fournisseurs.

Utilisez le portail afin de créer des sous-revendeurs pour votre vous ne pouvez pas utiliser l'API. Pour créer un fournisseur, vous devez disposer du rôle Propriétaire dans votre compte. Si votre organisation dispose de fournisseurs, vous pouvez appeler partners.vendors.list pour les lister et partners.vendors.customers.list pour obtenir les clients de vos fournisseurs. L'exemple suivant utilise ces deux méthodes pour imprimer un rapport indiquant l'état des conditions d'utilisation pour les fournisseurs clients:

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 modifier des appareils, vérifiez que votre organisation les a revendiqués avant d'appeler la méthode 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. Noms des méthodes asynchrones comporter 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 lot 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 de code JSON ci-dessous montre une réponse type après l'appel 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 ci-dessous montre comment pourrait le faire. 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 que 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 DevicesLongRunningOperationResponse détaillant 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 actualiser périodiquement l'opération. Le champ metadata contient un DevicesLongRunningOperationMetadata pour permettre à votre application de 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 l'utiliser pour estimer une heure de fin. Étant donné que `progress` peut prendre la valeur 100 pendant que l'opération se termine, vérifiez le champ `done` d'une opération pour savoir est terminée et a un résultat.
`devicesCount`	Indique le nombre de mises à jour dans l'opération. Ce nombre peut être différent du nombre de mises à jour de votre requête si l'API ne parvient pas à analyser certaines d'entre elles.

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 approche de sondage adaptée aux 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 API partners.devices.findByOwner peut renvoyer de très grandes listes d'appareils. Pour réduire la taille de la réponse, cette méthode et d'autres méthodes d'API (telles que partners.devices.findByIdentifier) acceptent les résultats paginés. Avec les résultats paginés, votre application peut demander et traiter de manière itérée de grandes 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 récupérer une autre page d'appareils en appelant à nouveau la méthode. Vous devez définir une limite maximale pour le nombre d'appareils dans le paramètre limit. 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 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.

Fonctionnement Restez organisé à l'aide des collections Enregistrez et classez les contenus selon vos préférences.

Introduction

Concepts de l'API

Créer des clients

Java

.NET

Python

Revendiquer les appareils des clients

Java

.NET

Python

Retrait d'appareils

Fournisseurs

Java

.NET

Python

Java

.NET

Python

Opérations par lot de longue durée

Opérations

Java

.NET

Python

Réponses

Suivre la progression

Java

.NET

Python

Résultats paginés

Java

.NET

Python

Étapes suivantes

Fonctionnement