Cara kerja

Pengantar

API pendaftaran zero-touch membantu reseller perangkat mengotomatiskan integrasi mereka. Alat penjualan organisasi Anda dapat digunakan untuk pendaftaran zero-touch, sehingga pengguna dan pelanggan Anda menjadi lebih produktif. Gunakan API ini untuk membantu pengguna Anda:

• Tetapkan perangkat yang dibeli ke akun pendaftaran zero-touch pelanggan.
• Membuat akun pendaftaran zero-touch pelanggan Anda.
• Lampirkan metadata nomor telepon dan pesanan organisasi Anda ke perangkat.
• Membuat laporan tentang perangkat yang ditetapkan ke pelanggan Anda.

Dokumen ini memperkenalkan API dan menjelaskan polanya. Jika Anda ingin mempelajari sendiri API ini, coba panduan memulai untuk Java, .NET, atau Python.

Konsep API

Pelanggan dan perangkat adalah resource inti yang Anda gunakan di API. Untuk membuat pelanggan, panggil create. Anda dapat membuat perangkat menggunakan metode API klaim (lihat di bawah). Organisasi Anda juga dapat membuat pelanggan dan perangkat menggunakan portal pendaftaran zero-touch.

Pelanggan

Perusahaan tempat organisasi Anda menjual perangkat. Pelanggan memiliki name dan ID. Gunakan pelanggan saat Anda ingin mengklaim atau menemukan perangkat mereka. Untuk mempelajari lebih lanjut, lihat Customer.

Perangkat

Perangkat Android atau ChromeOS yang mendukung pendaftaran zero-touch yang dijual organisasi Anda kepada pelanggan. Perangkat memiliki ID hardware, metadata, dan klaim pelanggan. Perangkat merupakan pusat API, jadi Anda menggunakannya di hampir semua metode. Untuk mempelajari lebih lanjut, lihat Device.

DeviceIdentifier

Mengenkapsulasi ID hardware, seperti IMEI atau MEID, untuk mengidentifikasi perangkat yang diproduksi. Gunakan DeviceIdentifier untuk menargetkan perangkat yang ingin Anda temukan, perbarui, atau klaim. Untuk mempelajari lebih lanjut, baca ID.

DeviceMetadata

Menyimpan key-value pair metadata untuk perangkat. Gunakan DeviceMetadata untuk menyimpan metadata organisasi Anda. Untuk mempelajari lebih lanjut, baca Metadata perangkat.

Untuk menampilkan daftar semua metode dan resource API yang dapat digunakan aplikasi Anda, lihat Referensi API.

Membuat pelanggan

Untuk perangkat Android, reseller bertanggung jawab untuk membuat akun pelanggan atas nama pelanggan mereka. Pelanggan akan menggunakan akun ini untuk mengakses portal zero-touch guna mengonfigurasi setelan penyediaan untuk perangkat mereka. Tindakan ini tidak diperlukan untuk perangkat ChromeOS, yang sudah memiliki akun Google Workspace yang akan digunakan untuk mengonfigurasi setelan penyediaan mereka.

Anda dapat memanggil metode API create guna membuat akun pelanggan untuk pendaftaran zero-touch. Karena pelanggan Anda melihat nama perusahaan di portal pendaftaran zero-touch mereka, pengguna aplikasi harus mengonfirmasi bahwa nama tersebut sudah benar. Anda tidak dapat mengedit nama pelanggan setelah membuat pelanggan.

Anda harus menyertakan minimal satu alamat email perusahaan, yang terkait dengan Akun Google, untuk menjadi pemilik. Anda tidak dapat menggunakan akun Gmail pribadi dengan API. Jika pelanggan memerlukan bantuan untuk mengaitkan akun, kirim petunjuk dari Mengaitkan Akun Google.

Catatan: API akan menampilkan error jika satu atau beberapa alamat email tidak dikaitkan dengan Akun Google. Jika hal ini terjadi, minta pengguna Anda untuk memeriksa apakah ada Akun Google untuk setiap alamat email. Google tidak menyediakan API untuk memeriksa apakah alamat email dikaitkan dengan Akun Google.

Setelah Anda membuat pelanggan dengan memanggil API, mereka mengelola akses portal karyawannya — Anda tidak dapat mengedit pengguna di sisi pelanggan yang menggunakan API tersebut. Cuplikan di bawah menunjukkan cara membuat pelanggan:

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

Untuk mempelajari lebih lanjut peran pemilik dan admin untuk karyawan pelanggan Anda, baca Pengguna Portal.

Klaim perangkat untuk pelanggan

Setelah pelanggan membeli perangkat, mereka ingin mengonfigurasi setelan penyediaan untuk perangkat tersebut di akun mereka. Mengklaim perangkat akan menambahkan perangkat ke pendaftaran zero-touch dan memberi pelanggan kemampuan untuk mengonfigurasi setelan penyediaan.

Data penyediaan perangkat memiliki bagian untuk pendaftaran zero-touch. Anda menetapkan perangkat dengan mengklaim bagian pendaftaran zero-touch data untuk pelanggan. Panggil metode partners.devices.claim atau partners.devices.claimAsync dengan pelanggan sebagai argumen. Selalu berikan SECTION_TYPE_ZERO_TOUCH sebagai nilai untuk sectionType.

Anda harus membatalkan klaim (lihat di bawah) perangkat pelanggan sebelum dapat mengklaim perangkat yang sama untuk pelanggan yang berbeda. Metode klaim validate kolom DeviceIdentifier, termasuk IMEI atau MEID, atau nomor seri, nama produsen dan model, serta ID perangkat yang disahkan untuk perangkat ChromeOS, saat membuat perangkat baru.

Cuplikan di bawah ini menunjukkan cara mengklaim perangkat:

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

Membatalkan klaim perangkat

Organisasi Anda dapat membatalkan klaim perangkat dari pelanggan. Membatalkan klaim perangkat akan menghapusnya dari pendaftaran zero-touch. Reseller mungkin membatalkan klaim perangkat yang ingin dimigrasikan ke akun lain, dikembalikan, atau yang diklaim secara keliru. Panggil metode partners.devices.unclaim atau partners.devices.unclaimAsync untuk membatalkan klaim perangkat dari pelanggan.

Perhatian: Pertimbangkan untuk meminta pengguna aplikasi Anda mengonfirmasi bahwa mereka memiliki perangkat yang benar sebelum memanggil API pembatalan klaim. Membatalkan klaim perangkat akan menghapus penyiapan penyediaan pelanggan dan perangkat menjadi tidak dikelola setelah direset ke setelan pabrik.

Vendor

Anda dapat menggunakan vendor untuk mewakili partner reseller di jaringan dealer Anda, operator lokal dalam jaringan reseller global, atau organisasi apa pun yang menjual perangkat atas nama Anda. Vendor membantu Anda memisahkan pengguna, pelanggan, dan perangkat:

• Vendor yang Anda buat tidak dapat melihat akun pendaftaran zero-touch Anda atau akun satu sama lain.
• Anda dapat melihat pelanggan dan perangkat vendor serta membatalkan pendaftaran perangkat vendor. Namun, Anda tidak dapat menetapkan perangkat ke pelanggan vendor.

Poin Penting: Vendor adalah jenis reseller khusus. Vendor akan muncul dan berperilaku (di portal dan API) sama seperti yang dilakukan reseller—kecuali vendor tidak dapat memiliki vendor lain.

Gunakan portal untuk membuat vendor untuk organisasi — Anda tidak dapat menggunakan API. Anda harus memiliki peran Pemilik untuk membuat vendor baru. Jika organisasi Anda memiliki vendor, Anda dapat memanggil partners.vendors.list untuk menampilkan daftar vendor dan partners.vendors.customers.list untuk mendapatkan pelanggan vendor Anda. Contoh berikut menggunakan kedua metode ini untuk mencetak laporan yang menampilkan status Persyaratan Layanan untuk pelanggan vendor:

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

Jika memiliki sekumpulan perangkat, Anda mungkin perlu mengetahui reseller atau vendor mana yang mengklaim perangkat tersebut. Untuk mendapatkan ID reseller numerik, periksa nilai kolom resellerId di catatan klaim perangkat.

Organisasi Anda dapat membatalkan klaim perangkat yang diklaim vendor. Untuk panggilan API lainnya yang mengubah perangkat, Anda harus memeriksa apakah organisasi Anda telah mengklaim perangkat sebelum memanggil metode API. Contoh berikut menunjukkan cara melakukannya:

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

Operasi batch yang berjalan lama

API ini menyertakan versi asinkron dari metode perangkat. Metode ini memungkinkan batch processing terhadap banyak perangkat, sementara metode sinkron memproses satu perangkat untuk setiap permintaan API. Nama metode asinkron memiliki akhiran Async, misalnya claimAsync.

Metode API asinkron menampilkan hasil sebelum pemrosesan selesai. Metode asinkron juga membantu aplikasi (atau alat) Anda tetap responsif bagi pengguna saat mereka menunggu operasi yang berjalan lama selesai. Aplikasi Anda harus memeriksa status operasi secara berkala.

Operasi

Anda menggunakan Operation untuk melacak operasi batch yang berjalan lama. Panggilan yang berhasil ke metode asinkron akan menampilkan referensi ke operasi dalam respons. Cuplikan JSON di bawah ini menunjukkan respons umum setelah memanggil updateMetadataAsync:

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

Setiap operasi berisi daftar tugas individual. Panggil operations.get untuk mengetahui informasi tentang status dan hasil tugas yang berada dalam operasi. Cuplikan di bawah menunjukkan cara melakukannya. Di aplikasi Anda sendiri, Anda harus menangani error yang ada.

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

Untuk mengetahui apakah operasi selesai, periksa operasi tersebut untuk kolom done dengan nilai true. Jika done tidak ada atau false, operasi masih berjalan.

Respons

Setelah operasi selesai, API akan memperbarui operasi tersebut dengan hasilnya, meskipun semua atau tidak satu pun tugas berhasil. Kolom response adalah objek DevicesLongRunningOperationResponse yang memerinci pemrosesan setiap perangkat dalam operasi.

Periksa kolom successCount untuk mengetahui secara efisien apakah ada tugas yang gagal dan menghindari iterasi melalui daftar hasil yang besar. Kolom perDeviceStatus pada DevicesLongRunningOperationResponse adalah daftar instance OperationPerDevice yang memerinci setiap perangkat dalam operasi. Urutan daftar sesuai dengan tugas dalam permintaan asli.

Setiap tugas OperationPerDevice berisi kolom result dan ringkasan pengingat permintaan yang diterima oleh server. Periksa apakah tugas berhasil atau gagal menggunakan kolom result.

Cuplikan JSON di bawah ini menunjukkan bagian dari respons standar dari suatu operasi setelah panggilan ke updateMetadataAsync:

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

Progres jalur

Jika aplikasi Anda perlu melacak progres, Anda harus mengambil kembali operasi tersebut secara berkala. Kolom metadata berisi instance DevicesLongRunningOperationMetadata untuk membantu aplikasi Anda memeriksa progres terbaru dari operasi yang sedang berjalan. Gunakan kolom DevicesLongRunningOperationMetadata yang tercantum dalam tabel berikut untuk melacak progres operasi:

Kolom	Penggunaan umum
processingStatus	Perubahan dari BATCH_PROCESS_PENDING menjadi BATCH_PROCESS_IN_PROGRESS, lalu ke BATCH_PROCESS_PROCESSED saat operasi berlangsung.
progress	Persentase update yang diproses. Aplikasi Anda dapat menggunakannya untuk memperkirakan waktu penyelesaian. Karena nilai progress dapat berupa 100 selagi operasi selesai, periksa kolom done operasi untuk mengetahui apakah operasi tersebut selesai dan memberikan hasil.
devicesCount	Menampilkan jumlah update dalam operasi. Jumlah ini mungkin berbeda dari jumlah update dalam permintaan Anda jika API tidak dapat mengurai beberapa update.

Contoh sederhana di bawah ini menunjukkan cara aplikasi dapat menggunakan metadata progres untuk menetapkan interval polling. Di aplikasi, Anda mungkin memerlukan runner tugas yang lebih canggih untuk polling. Anda juga perlu menambahkan penanganan error.

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)

Pilih pendekatan polling yang paling sesuai bagi pengguna aplikasi Anda. Beberapa pengguna aplikasi mungkin mendapatkan manfaat dari update progres rutin jika mereka sedang menunggu proses selesai.

Hasil halaman

Metode partners.devices.findByOwner API mungkin menampilkan daftar perangkat yang sangat besar. Untuk mengurangi ukuran respons, metode API ini dan metode API lainnya (seperti partners.devices.findByIdentifier) mendukung hasil yang di-page. Dengan hasil yang dibagi-bagi, aplikasi Anda dapat secara berulang meminta dan memproses daftar besar satu halaman dalam satu waktu.

Setelah memanggil metode API, periksa apakah respons tersebut menyertakan nilai untuk nextPageToken. Jika nextPageToken bukan null, aplikasi Anda dapat menggunakannya untuk mengambil halaman perangkat lain dengan memanggil metode itu lagi. Anda perlu menetapkan batas atas untuk jumlah perangkat dalam parameter limit. Jika nextPageToken adalah null, aplikasi Anda telah meminta halaman terakhir.

Contoh metode di bawah ini menunjukkan cara aplikasi Anda dapat mencetak daftar perangkat, satu halaman dalam satu waktu:

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

Langkah berikutnya

Setelah Anda mengetahui cara kerja API, coba contoh dengan panduan memulai untuk Java, .NET, atau Python.