Ablauf

Einführung

Mit der Zero-Touch-Registrierungs-API können Geräte-Reseller ihre Integration automatisieren. Die Vertriebstools Ihrer Organisation können die Zero-Touch-Registrierung integrieren, sodass Ihre Ihre Nutzenden und Ihre Kundschaft produktiver sein können. Mit der API können Sie Ihren Nutzern folgende Vorteile bieten:

• Weisen Sie gekaufte Geräte dem Konto eines Kunden mit Zero-Touch-Registrierung zu.
• Erstellen von Kundenkonten mit Zero-Touch-Registrierung
• Fügen Sie den Geräten die Telefonnummer Ihrer Organisation und Bestellmetadaten hinzu.
• Erstellen von Berichten über Geräte, die Ihren Kunden zugewiesen sind

In diesem Dokument werden die API und die zugehörigen Muster vorgestellt. Wenn Sie die API selbst ausprobieren möchten, sehen Sie sich die Kurzanleitungen für Java, .NET oder Python an.

API-Konzepte

Kunden und Geräte sind die Kernressourcen, die Sie in der API verwenden. Zum Erstellen Kunden, rufen Sie unter create an. Sie können Geräte erstellen mithilfe der Claim API-Methoden (siehe unten). Ihre Organisation kann auch Kunden und Geräte über das Portal für die Zero-Touch-Registrierung erstellen

Kunde

Unternehmen, an die Ihre Organisation Geräte verkauft. Kunden haben eine name und eine ID. Verwende einen Kunden, wenn du seine Geräte freischalten oder finden möchtest. Weitere Informationen finden Sie unter Customer.

Gerät

Ein Android- oder ChromeOS-Gerät mit Zero-Touch-Registrierung, das Ihre Organisation an einen Kunden verkauft. Geräte haben Hardware-IDs, Metadaten und Ansprüche Geräte sind zentral für die API und werden daher in fast allen . Weitere Informationen finden Sie unter Device.

DeviceIdentifier (Geräte-ID)

Verkapselt Hardware-IDs wie IMEI oder MEID zur Identifizierung eines hergestellten . Verwenden Sie einen DeviceIdentifier für die Ausrichtung auf das Gerät. die Sie suchen, aktualisieren oder beanspruchen möchten. Weitere Informationen finden Sie unter Kennungen.

DeviceMetadata

Speichert Schlüssel/Wert-Paare von Metadaten für das Gerät. Verwenden Sie DeviceMetadata, um die Metadaten Ihrer Organisation zu speichern. Bis Weitere Informationen finden Sie unter Gerätemetadaten.

Eine Liste aller API-Methoden und ‑Ressourcen, die Ihre App verwenden kann, finden Sie in der API-Referenz.

Kunden erstellen

Bei Android-Geräten ist der Reseller für die Erstellung des Kunden im Auftrag eines Kunden. Der Kunde verwendet dieses Konto, um auf das Zero-Touch-Portal zuzugreifen und die Bereitstellungseinstellungen für seine Geräte zu konfigurieren. Für ChromeOS-Geräte ist dies nicht erforderlich, da diese Workspace-Konto, mit dem er die Einstellungen für die Bereitstellung konfiguriert.

Sie können die API-Methode create aufrufen, um Kundenkonten für die Zero-Touch-Registrierung zu erstellen. Da Ihre Kunden den Unternehmensnamen in ihrem Zero-Touch-Registrierungsportal sehen, sollte der Nutzer Ihrer App bestätigen, dass er korrekt ist. Sie können den Namen eines Kunden nicht mehr bearbeiten, nachdem Sie die Kunden.

Sie müssen mindestens eine geschäftliche E-Mail-Adresse angeben, die mit einem Google-Konto, um der Inhaber zu sein. Sie können keine privaten Gmail-Konten mit dem der API erstellen. Wenn der Kunde Hilfe beim Verknüpfen des Kontos benötigt, sende den Anweisungen von Ein Google-Konto verknüpfen

Hinweis: Die API gibt einen Fehler zurück, wenn mindestens eine der E-Mail-Adressen nicht mit einem Google-Konto verknüpft ist. Bitten Sie den Nutzer in diesem Fall, zu prüfen, ob für jede E-Mail-Adresse ein Google-Konto vorhanden ist. Google stellt keine API zur Verfügung, um zu prüfen, ob eine E-Mail Adresse mit einem Google-Konto verknüpft ist.

Nachdem Sie über die API einen Kunden erstellt haben, verwaltet er die Daten Portalzugriff – Sie können die Einstellungen Ihrer Kunden nicht bearbeiten die die API verwenden. Im folgenden Snippet wird gezeigt, wie Sie einen Kunden erstellen können:

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("[e-mail]", "[e-mail]"));
customer.setAdminEmails(Collections.singletonList("[e-mail]"));

// 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[] { "[e-mail]", "[e-mail]" },
    AdminEmails = new String[] { "[e-mail]" }
};

// 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':['[e-mail]', '[e-mail]'], \
  'adminEmails':['[e-mail]']}

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

Weitere Informationen zu den Inhaber- und Administratorrollen für Mitarbeiter Ihres Kunden finden Sie unter Portalnutzer.

Geräte für Kunden freischalten

Nachdem Ihre Kunden Geräte gekauft haben, möchten sie die Nutzerverwaltung konfigurieren Einstellungen für diese Geräte in ihrem Konto an. Wenn du ein Gerät anforderst, wird es hinzugefügt bis hin zur Zero-Touch-Registrierung. Einstellungen für die Nutzerverwaltung.

Der Bereitstellungseintrag eines Geräts enthält einen Abschnitt für die Zero-Touch-Registrierung. Ich das Gerät zuzuweisen, indem Sie den Abschnitt für die Zero-Touch-Registrierung Kunden. Rufen Sie die partners.devices.claim oder partners.devices.claimAsync-Methoden mit dem Kundschaft als Argument angeben. Geben Sie immer SECTION_TYPE_ZERO_TOUCH als Wert für sectionType an.

Du musst den Anspruch auf das Gerät eines Kunden aufheben (siehe unten), bevor du das Gerät für einen anderen Kunden beanspruchen kannst. Die Anspruchsmethoden DeviceIdentifier-Felder validieren, einschließlich IMEI, MEID oder Seriennummer, Herstellername und Modell sowie Attestierte Geräte-ID für ChromeOS-Geräte beim Erstellen eines neuen Geräts.

Im folgenden Snippet wird gezeigt, wie Sie Anspruch auf ein Gerät erheben:

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

Anspruch auf Geräte aufheben

Ihre Organisation kann die Inhaberschaft für ein Gerät eines Kunden zurückziehen. Anspruch auf ein Gerät aufheben wird es aus der Zero-Touch-Registrierung entfernt. Ein Reseller kann die Inhaberschaft für ein Gerät zurückziehen, das zu einem anderen Konto migriert, zurückgegeben oder auf das fälschlicherweise Anspruch erhoben wurde. Rufen Sie die Methode partners.devices.unclaim auf oder partners.devices.unclaimAsync, um den Anspruch zurückzuziehen für Gerät eines Kunden.

Achtung :Bitten Sie den Nutzer Ihrer App, zu bestätigen, dass er die das richtige Gerät zu beheben, bevor Sie APIs ohne Anspruch aufrufen. Wenn du die Beanspruchung eines Geräts zurückziehst, wird Folgendes entfernt: Einrichtung der Nutzerverwaltung einrichten und das Gerät wird nach der Werkseinstellungen nicht mehr verwaltet. zurücksetzen.

Anbieter

Sie können Anbieter verwenden, um Reseller-Partner in Ihrem Händlernetzwerk, lokal in einem globalen Reseller-Netzwerk oder einer Organisation, die in Ihrem Namen zu verwalten. Mit Anbietern lassen sich Nutzer, Kunden und Geräte:

• Von Ihnen erstellte Anbieter können weder Ihr Konto für die Zero-Touch-Registrierung noch die Konten anderer Anbieter sehen.
• Sie können sich die Kunden und Geräte Ihrer Anbieter ansehen und die Registrierung der Geräte Ihrer Anbieter aufheben. Sie können jedoch keine Geräte den Kunden Ihrer Anbieter zuweisen.

Wichtiger Hinweis: Ein Anbieter ist eine spezielle Art von Reseller. Anbieter erscheinen und verhalten sich wie ein Reseller (im Portal und in APIs), mit der Ausnahme, dass ein Anbieter keine anderen Anbietern.

Verwenden Sie das Portal, um Anbieter für Ihre Organisation zu erstellen. Die API kann nicht verwendet werden. Ihre Kontorolle muss Inhaber, um einen neuen Anbieter zu erstellen. Wenn Ihr Unternehmen Zulieferunternehmen hat, können Sie partners.vendors.list anrufen, um eine Liste Ihrer Anbieter und partners.vendors.customers.list um die Kunden Ihres Anbieters zu gewinnen. Im folgenden Beispiel werden beide Methoden verwendet, um einen Bericht mit dem Status der Nutzungsbedingungen für die Kunden der Anbieter zu drucken:

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'])

Wenn Sie mehrere Geräte haben, müssen Sie möglicherweise wissen, welcher Reseller oder Anbieter hat das Gerät beansprucht. Um die numerische Reseller-ID zu erhalten, prüfen Sie den Wert der Feld resellerId im Anspruchsdatensatz eines Geräts

Ihre Organisation kann die Anspruchserhebung für ein Gerät, das von einem Anbieter beansprucht wurde, zurückziehen. Bei anderen API-Aufrufen, die Geräte ändern, sollten Sie prüfen, ob Ihre Organisation das Gerät beansprucht hat, bevor Sie die API-Methode aufrufen. Das folgende Beispiel zeigt, wie das geht:

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

Lang andauernde Batchvorgänge

Die API enthält asynchrone Versionen der Gerätemethoden. Diese Methoden ermöglichen die Batchverarbeitung vieler Geräte, während die synchrone -Methoden verarbeiten ein Gerät pro API-Anfrage. Die Namen der asynchronen Methoden haben das Suffix Async, z. B. claimAsync.

Asynchrone API-Methoden geben ein Ergebnis zurück, bevor die Verarbeitung abgeschlossen ist. Asynchrone Methoden sorgen außerdem dafür, dass Ihre App oder Ihr Tool für Ihre während sie auf den Abschluss eines lang andauernden Vorgangs warten. Ihre App sollte den Status des Vorgangs regelmäßig zu überprüfen.

Vorgänge

Sie verwenden ein Operation, um einen Batchvorgang mit langer Ausführungszeit zu verfolgen. Ein erfolgreicher Aufruf einer asynchronen Methode gibt in der Antwort einen Verweis auf den Vorgang zurück. Das folgende JSON-Snippet zeigt eine typische Antwort nach dem Aufruf von updateMetadataAsync:

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

Jeder Vorgang enthält eine Liste einzelner Aufgaben. Anruf operations.get, um Informationen zum Status und Ergebnisse der im Vorgang enthaltenen Aufgaben. Das folgende Snippet zeigt, wie das geht. In Ihrer eigenen App müssen Sie alle Fehler behandeln.

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

Wenn Sie herausfinden möchten, ob ein Vorgang abgeschlossen ist, suchen Sie im Vorgang nach einem done-Feld mit dem Wert true. Wenn done fehlt oder false ist, ist der Vorgang immer noch ausgeführt wird.

Antworten

Nach Abschluss eines Vorgangs aktualisiert die API den Vorgang mit dem Ergebnis – auch wenn alle oder keine der einzelnen Aufgaben erfolgreich waren. Das Feld response ist ein DevicesLongRunningOperationResponse-Objekt, das die Verarbeitung jedes Geräts im Vorgang beschreibt.

Prüfen Sie das Feld successCount, um schnell herauszufinden, ob Aufgaben fehlgeschlagen sind, und um zu vermeiden, dass Sie große Ergebnislisten durchgehen müssen. Das Feld perDeviceStatus von DevicesLongRunningOperationResponse ist eine Liste von OperationPerDevice-Instanzen mit Details zu jedem Gerät im Vorgang. Die Reihenfolge der Liste stimmt mit den Aufgaben in der ursprünglichen Anfrage überein.

Jede OperationPerDevice-Aufgabe enthält ein result-Feld und eine Erinnerungsübersicht der vom Server empfangenen Anfrage. Prüfen, ob die Aufgabe erfolgreich war oder fehlgeschlagen ist result verwenden.

Das folgende JSON-Snippet zeigt einen Teil einer typischen Antwort eines Vorgangs nach einen Anruf an updateMetadataAsync:

"response": {
  "perDeviceStatus": [
    {
      "result": {
        "deviceId": "12345678901234567",
        "status": "SINGLE_DEVICE_STATUS_SUCCESS"
      },
      "updateMetadata": {
        "deviceId": "12345678901234567",
        "deviceMetadata": {
          "entries": {
            "phonenumber": "[phone]"
          }
        }
      }
    }
  ],
  "successCount": 1
}

Fortschritt verfolgen

Wenn Ihre App den Fortschritt verfolgen muss, sollten Sie den . Das Feld metadata enthält eine DevicesLongRunningOperationMetadata-Instanz, mit der Ihre App den aktuellen Fortschritt eines laufenden Vorgangs prüfen kann. Verwenden Sie die im Folgenden aufgeführten Felder von DevicesLongRunningOperationMetadata , um den Fortschritt des Vorgangs zu verfolgen:

Feld	Typischer Einsatzzweck
processingStatus	Ändert sich von BATCH_PROCESS_PENDING zu BATCH_PROCESS_IN_PROGRESS und dann für BATCH_PROCESS_PROCESSED während des Vorgangs.
progress	Der Prozentsatz der verarbeiteten Aktualisierungen. Deine App kann Folgendes verwenden: um eine Endzeit zu schätzen. Da die progress 100 sein, während der Vorgang abgeschlossen ist, prüfen Sie im Feld done eines Vorgangs, und hat ein Ergebnis.
devicesCount	Zeigt die Anzahl der Aktualisierungen im Vorgang an. Dieser Wert kann von der Anzahl der Updates in Ihrer Anfrage abweichen, wenn die API einige der Updates nicht parsen kann.

Das vereinfachte Beispiel unten zeigt, wie eine App die Fortschrittsmetadaten verwenden könnte, um Abfrageintervalle festlegen. In Ihrer App benötigen Sie möglicherweise eine komplexere Aufgabe, Runner zum Abfragen. Sie müssen auch eine Fehlerbehandlung hinzufügen.

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)

Wählen Sie einen Umfrageansatz aus, der für die Nutzer Ihrer App sinnvoll ist. Einige App-Nutzer können von regelmäßigen Updates zum Fortschritt profitieren, wenn sie auf einen Prozess warten, abgeschlossen ist.

Paginierte Ergebnisse

Die API-Methode partners.devices.findByOwner kann es sehr umfangreiche Listen mit Geräten geben. Um die Antwortgröße zu reduzieren, unterstützen diese und andere API-Methoden (z. B. partners.devices.findByIdentifier) die Paginierung von Ergebnissen. Mit Paged-Ergebnissen kann Ihre Anwendung iterativ große Listen seitenweise anfordern und verarbeiten können.

Prüfe nach dem Aufruf der API-Methode, ob die Antwort einen Wert für nextPageToken enthält. Wenn nextPageToken nicht null ist, kann Ihre App damit eine weitere Seite mit Geräten abrufen, indem sie die Methode noch einmal aufruft. Sie müssen im Parameter limit eine Obergrenze für die Anzahl der Geräte festlegen. Wenn nextPageToken den Wert null hat, hat Ihre App den auf der letzten Seite.

Die folgende Beispielmethode zeigt, wie Ihre App eine Liste von Geräten Seite für Seite drucken könnte:

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

Nächste Schritte

Nachdem Sie nun wissen, wie die API funktioniert, können Sie die Beispiele mit einer Kurzanleitung für Java .NET oder Python In einem Colab können Sie sich Beispiele für API-Aufrufe ansehen und selbst mit dem Aufruf der API experimentieren.