Cara kerja

Customer API memberikan kontrol terprogram atas perangkat dan konfigurasi untuk pendaftaran zero-touch Android. Dokumen ini memperkenalkan API kepada penyedia pengelolaan mobilitas perusahaan (EMM) dan developer IT perusahaan. Setelah membaca dokumen ini, Anda harus memahami resource inti yang digunakan di API dan cara interaksinya. Jika Anda baru mengenal pendaftaran zero-touch, baca pengantar android.com singkat.

Ringkasan

API pelanggan membantu organisasi yang membeli perangkat pendaftaran zero-touch Android. Aplikasi atau alat Anda dapat membantu admin IT melakukan hal berikut:

• Membuat, mengedit, dan menghapus konfigurasi penyediaan.
• Menerapkan atau menghapus konfigurasi pada perangkat.
• Pilih konfigurasi default untuk perangkat apa pun yang selanjutnya ditambahkan ke pendaftaran zero-touch.

Melalui API, admin IT juga dapat membatalkan pendaftaran perangkat dari pendaftaran zero-touch. Untuk mengelola pengguna organisasi atau menyetujui Persyaratan Layanan, admin IT menggunakan portal pendaftaran zero-touch.

Pengguna umum API ini mungkin:

• Penyedia EMM menambahkan dukungan untuk pendaftaran zero-touch ke konsol mereka.
• Developer IT perusahaan yang membuat alat untuk mengotomatiskan tugas pendaftaran zero-touch.

Resource inti

Konfigurasi dan perangkat adalah resource inti yang Anda gunakan di API. Organisasi juga dapat membuat konfigurasi dan perangkat menggunakan portal pendaftaran zero-touch.

Konfigurasi

Admin IT menetapkan opsi penyediaan untuk perangkat menggunakan konfigurasi. Konfigurasi mencakup kebijakan seluler EMM dan info kontak yang ditampilkan untuk membantu pengguna. Konfigurasi sangat penting bagi API, jadi Anda dapat menggunakannya dalam banyak metode. Untuk mempelajari lebih lanjut, lihat Konfigurasi di bawah.

Perangkat

Perangkat Android yang mendukung pendaftaran zero-touch yang dibeli organisasi dari resellernya. Terapkan konfigurasi untuk menyertakan perangkat dalam pendaftaran zero-touch. Perangkat memiliki ID hardware dan metadata yang terlampir. Untuk mempelajari lebih lanjut, lihat Perangkat di bawah.

DPC

Referensi hanya baca ke DPC EMM (pengontrol kebijakan perangkat). Tambahkan DPC ke konfigurasi untuk memilih solusi EMM untuk perangkat. Semua DPC yang dicantumkan oleh API mendukung pendaftaran zero-touch dan tersedia di Google Play. Untuk mempelajari lebih lanjut, lihat Dpc.

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

Konfigurasi

Resource Configuration API menggabungkan hal berikut:

• DPC EMM yang diinstal di perangkat.
• Kebijakan EMM diterapkan di perangkat.
• Informasi kontak yang ditampilkan di perangkat untuk membantu pengguna selama penyiapan.

Dengan menggunakan API, aplikasi Anda dapat mengelola konfigurasi untuk admin IT. Panggil API untuk mengambil, membuat, memperbarui, dan menghapus konfigurasi. Contoh di bawah ini menunjukkan cara membuat konfigurasi baru:

Java

// Add metadata to help the device user during provisioning.
Configuration configuration = new Configuration();
configuration.setConfigurationName("Sales team");
configuration.setCompanyName("XYZ Corp.");
configuration.setContactEmail("[e-mail]");
configuration.setContactPhone("[phone]");
configuration.setCustomMessage("We're setting up your phone. Call or email for help.");

// Set the DPC that zero-touch enrollment downloads and installs from Google Play.
configuration.setDpcResourcePath(dpc.getName());

// Set the JSON-formatted EMM provisioning extras that are passed to the DPC.
configuration.setDpcExtras("{"
      + "\"android.app.extra.PROVISIONING_LEAVE_ALL_SYSTEM_APPS_ENABLED\":true,"
      + "\"android.app.extra.PROVISIONING_ADMIN_EXTRAS_BUNDLE\":{"
      + "\"default_min_password_length\":6,"
      + "\"company_name\":\"XYZ Corp\","
      + "\"management_server\":\"emm.example.com\","
      + "\"terms_url\":\"https://www.example.com/policies/terms/\","
      + "\"allowed_user_domains\":\"[\\\"example.com\\\", \\\"example.org\\\"]\""
      + "}"
      + "}");

// Create the new configuration on the server.
AndroidProvisioningPartner.Customers.Configurations.Create request =
      service.customers().configurations().create(customerAccount, configuration);
Configuration response = request.execute();

.NET

// Add metadata to help the device user during provisioning.
Configuration configuration = new Configuration
{
    ConfigurationName = "Sales team",
    CompanyName = "XYZ Corp.",
    ContactEmail = "[e-mail]",
    ContactPhone = "[phone]",
    CustomMessage = "We're setting up your phone. Call or email for help."
};

// Set the DPC that zero-touch enrollment downloads and installs from Google Play.
configuration.DpcResourcePath = dpc.Name;

// Set the JSON-formatted EMM provisioning extras that are passed to the DPC.
configuration.DpcExtras = @"{
    ""android.app.extra.PROVISIONING_LEAVE_ALL_SYSTEM_APPS_ENABLED"":true,
    ""android.app.extra.PROVISIONING_ADMIN_EXTRAS_BUNDLE"":{
    ""default_min_password_length"":6,
    ""company_name"":""XYZ Corp"",
    ""management_server"":""emm.example.com"",
    ""terms_url"":""https://www.example.com/policies/terms/"",
    ""allowed_user_domains"":""[\""example.com\"", \""example.org\""]""
  }
}";

// Create the new configuration on the server.
var request = service.Customers.Configurations.Create(configuration, customerAccount);
var response = request.Execute();

Python

# Add metadata to help the device user during provisioning.
configuration = {
    'configurationName': 'Sales team',
    'companyName': 'XYZ Corp.',
    'contactEmail': '[e-mail]',
    'contactPhone': '[phone]',
    'customMessage': 'We\'re setting up your phone. Call or email for help.'}

# Set the DPC that zero-touch enrollment installs from Google Play.
configuration['dpcResourcePath'] = dpc['name']

# Set the JSON-formatted EMM provisioning extras that are passed to the DPC.
configuration['dpcExtras'] = '''{
    "android.app.extra.PROVISIONING_LEAVE_ALL_SYSTEM_APPS_ENABLED":true,
    "android.app.extra.PROVISIONING_ADMIN_EXTRAS_BUNDLE":{
      "default_min_password_length":6,
      "company_name":"XYZ Corp",
      "management_server":"emm.example.com",
      "terms_url":"https://www.example.com/policies/terms/",
      "allowed_user_domains":"[\\"example.com\\", \\"example.org\\"]"}
}'''

# Create the new configuration on the server.
response = service.customers().configurations().create(
    parent=customer_account, body=configuration).execute()

Saat Anda mengupdate konfigurasi menggunakan patch API, jangan lupa untuk menyertakan mask kolom—atau nilai untuk setiap kolom yang tidak ingin Anda jadikan null. Lihat Konfigurasi default (di bawah) untuk mengetahui contoh yang menunjukkan cara mengupdate konfigurasi secara efisien.

Menghapus konfigurasi

Anda tidak dapat menghapus konfigurasi jika masih diterapkan ke perangkat. Jika Anda mencoba menghapus konfigurasi yang sedang digunakan, metode API akan menampilkan kode status 400 Bad Request HTTP dan pesan yang menjelaskan jumlah perangkat yang menggunakan konfigurasi tersebut. Panggil customers.devices.removeConfiguration untuk menghapus konfigurasi dari perangkat sebelum mencoba lagi.

Konfigurasi default

Pendaftaran zero-touch berfungsi optimal jika organisasi menetapkan konfigurasi default yang diterapkan ke perangkat baru apa pun yang dibeli organisasi. Pertimbangkan untuk meminta admin IT menetapkan konfigurasi default jika belum ditetapkan. Contoh di bawah menunjukkan cara menetapkan konfigurasi yang ada sebagai default dengan menetapkan isDefault ke true:

Java

// Send minimal data with the request. Just the 2 required fields.
// targetConfiguration is an existing configuration that we want to make the default.
Configuration configuration = new Configuration();
configuration.setIsDefault(true);
configuration.setConfigurationId(targetConfiguration.getConfigurationId());

// Call the API, including the FieldMask to avoid setting other fields to null.
AndroidProvisioningPartner.Customers.Configurations.Patch request = service
      .customers()
      .configurations()
      .patch(targetConfiguration.getName(), configuration);
request.setUpdateMask("isDefault");
Configuration results = request.execute();

.NET

// Send minimal data with the request. Just the 2 required fields.
// targetConfiguration is an existing configuration that we want to make the default.
Configuration configuration = new Configuration
{
    IsDefault = true,
    ConfigurationId = targetConfiguration.ConfigurationId,
};

// Call the API, including the FieldMask to avoid setting other fields to null.
var request = service.Customers.Configurations.Patch(configuration,
                                                     targetConfiguration.Name);
request.UpdateMask = "IsDefault";
Configuration results = request.Execute();

Python

# Send minimal data with the request. Just the 2 required fields.
# target_configuration is an existing configuration we'll make the default.
configuration = {
    'isDefault': True,
    'configurationId': target_configuration['configurationId']}

# Call the API, including the FieldMask to avoid setting other fields to null.
response = service.customers().configurations().patch(
    name=target_configuration['name'],
    body=configuration, updateMask='isDefault').execute()

Hanya boleh ada satu konfigurasi default. Dengan membuat konfigurasi default baru, tetapkan kolom isDefault pada konfigurasi sebelumnya ke false. Anda mungkin perlu memuat ulang instance Configuration yang di-cache untuk melihat nilai yang benar di kolom isDefault.

Memandu pengguna perangkat

Konfigurasi zero-touch menampilkan panduan pengguna yang disesuaikan di Wizard Penyiapan perangkat untuk membantu pengguna. Anda harus menyertakan nomor telepon kontak dan alamat email beserta nama organisasi yang mengelola perangkat dalam konfigurasi. Sebaiknya sertakan satu atau dua kalimat di kolom customMessage untuk memberikan detail selengkapnya tentang apa yang terjadi pada perangkat pengguna.

Karena pengguna tidak akan dapat melakukan panggilan atau mengirim email dari perangkat yang mereka siapkan, format nomor telepon dan alamat email agar lebih mudah melihat informasi tersebut.

Perangkat

Reseller membuat perangkat saat pelanggan membelinya untuk pendaftaran zero-touch—Admin IT tidak dapat membuat perangkat. Untuk bekerja dengan perangkat, panggil metode pada resource API Device. Jika Anda perlu menelusuri perangkat, cantumkan semua perangkat dan filter setiap batch secara lokal di aplikasi Anda. Untuk contohnya, lihat Paged results di bawah.

Mengonfigurasi perangkat

Menerapkan konfigurasi ke perangkat akan mendaftarkan perangkat ke pendaftaran zero-touch. Untuk menerapkan konfigurasi, panggil customers.devices.applyConfiguration. Setelah menerapkan konfigurasi, perangkat akan otomatis menyediakan dirinya sendiri saat booting pertama, atau reset ke setelan pabrik berikutnya. Contoh di bawah ini menunjukkan cara menerapkan konfigurasi ke kumpulan perangkat:

Java

List<Device> devices = getDevicesToConfigure(service);
Configuration configurationToApply = getConfigurationToApply(service);

// Loop through the collection and apply the configuration to each device. This might
// take some time if the collection contains many devices.
for (Device device : devices) {
    System.out.println(device.getDeviceIdentifier().getImei());

    // Wrap the device ID in a DeviceReference.
    DeviceReference deviceRef = new DeviceReference();
    deviceRef.setDeviceId(device.getDeviceId());

    // Build and send the request to the API.
    CustomerApplyConfigurationRequest body = new CustomerApplyConfigurationRequest();
    body.setConfiguration(configurationToApply.getName());
    body.setDevice(deviceRef);

    AndroidProvisioningPartner.Customers.Devices.ApplyConfiguration request = service
          .customers()
          .devices()
          .applyConfiguration(customerAccount, body);
    request.execute();
}

.NET

IList<Device> devices = GetDevicesToConfigure(service);
Configuration configurationToApply = GetConfigurationToApply(service);

// Loop through the collection and apply the configuration to each device. This might
// take some time if the collection contains many devices.
foreach (Device device in devices)
{
    Console.WriteLine(device.DeviceIdentifier.Imei);

    // Wrap the device ID in a DeviceReference.
    var deviceRef = new DeviceReference
    {
        DeviceId = device.DeviceId
    };

    // Build and send the request to the API.
    CustomerApplyConfigurationRequest body = new CustomerApplyConfigurationRequest
    {
        Configuration = configurationToApply.Name,
        Device = deviceRef
    };
    var request = service.Customers.Devices.ApplyConfiguration(body,
                                                               customerAccount);
    request.Execute();
}

Python

devices = get_devices_to_configure(service)
configuration = get_configuration_to_apply(service)

# Loop through the collection and apply the configuration to each device.
# This might take some time if the collection contains many devices.
for device in devices:
  print(device['deviceIdentifier']['imei'])

  # Wrap the device ID in a DeviceReference.
  device_ref = {'deviceId': device['deviceId']}

  # Build and send the request to the API.
  body = {'configuration': configuration['name'], 'device': device_ref}
  service.customers().devices().applyConfiguration(
      parent=customer_account, body=body).execute()

Untuk menghapus konfigurasi dari perangkat, panggil customers.devices.removeConfiguration. Perubahan akan diterapkan setelah mereset perangkat ke setelan pabrik.

Batalkan klaim perangkat

Admin IT dapat membatalkan klaim perangkat untuk menghapusnya dari pendaftaran zero-touch. Admin IT mungkin membatalkan klaim perangkat yang ingin dimigrasikan ke akun lain, dijual, atau dikembalikan kepada reseller. Panggil metode customers.devices.unclaim untuk membatalkan klaim perangkat dari organisasi.

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 organisasi dan perangkat menjadi tidak dikelola setelah direset ke setelan pabrik. Admin IT harus menghubungi reseller jika ingin mendaftarkan perangkat ke pendaftaran zero-touch lagi.

Contoh di bawah ini menunjukkan cara membatalkan klaim perangkat dari nomor IMEI dan nama produsen:

Java

// Wrap the hardware ID and manufacturer values in a DeviceIdentifier.
// Then wrap the DeviceIdentifier in a DeviceReference.
DeviceIdentifier identifier = new DeviceIdentifier();
identifier.setImei("123456789012347");
identifier.setManufacturer("Google");
DeviceReference reference = new DeviceReference();
reference.setDeviceIdentifier(identifier);

// Create the body of the request.
CustomerUnclaimDeviceRequest body = new CustomerUnclaimDeviceRequest();
body.setDevice(reference);

// Call the API method to unclaim the device from the organization.
service.customers().devices().unclaim(customerAccount, body).execute();

.NET

// Wrap the hardware ID and manufacturer values in a DeviceIdentifier.
// Then wrap the DeviceIdentifier in a DeviceReference.
DeviceIdentifier identifier = new DeviceIdentifier
{
    Imei = "123456789012347",
    Manufacturer = "Google"
};
DeviceReference reference = new DeviceReference();
reference.DeviceIdentifier = identifier;

// Create the body of the request.
CustomerUnclaimDeviceRequest body = new CustomerUnclaimDeviceRequest();
body.Device = reference;

// Call the API method to unclaim the device from the organization.
service.Customers.Devices.Unclaim(body, customerAccount).Execute();

Python

# Wrap the hardware ID and manufacturer values in a DeviceIdentifier.
# Then wrap the DeviceIdentifier in a DeviceReference.
identifier = {'imei': '123456789012347', 'manufacturer': 'Google'}
reference = {'deviceIdentifier': identifier}

# Create the body of the request.
body = {'device': reference}

# Call the API method to unclaim the device from the organization.
service.customers().devices().unclaim(
    parent=customer_account, body=body).execute()

Metadata perangkat

Admin IT dapat melihat metadata yang dilampirkan ke perangkat oleh reseller. Tampilkan metadata perangkat ini di aplikasi Anda untuk membantu admin IT mengenali perangkat.

Untuk mempelajari lebih lanjut metadata yang mungkin Anda lihat, baca panduan Metadata perangkat untuk reseller.

Hasil halaman

Metode API customers.devices.list mungkin menampilkan daftar perangkat yang sangat besar. Untuk mengurangi ukuran respons, metode API ini dan metode API lainnya (seperti customers.list) mendukung hasil yang di-page. Dengan hasil yang dibagi-bagi, aplikasi Anda dapat secara iteratif 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 lain dari perangkat dengan memanggil metode itu lagi. Anda perlu menetapkan batas atas untuk jumlah perangkat dalam parameter pageSize. 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 void printDevices(AndroidProvisioningPartner service, String customerAccount,
      String pageToken) throws IOException {

    // Call the API to get a page of Devices. Send a page token from the method argument.
    // If the page token is null, the API returns the first page.
    AndroidProvisioningPartner.Customers.Devices.List request =
          service.customers().devices().list(customerAccount);
    request.setPageSize(50L);
    request.setPageToken(pageToken);
    CustomerListDevicesResponse response = request.execute();

    // Print the devices included in this page of results.
    for (Device device : response.getDevices()) {
        System.out.format("Device: %s\n", device.getName());
    }
    System.out.println("---");

    // Check to see if another page of devices is available. If yes, fetch & print the devices.
    if (response.getNextPageToken() != null) {
        this.printDevices(service, customerAccount, response.getNextPageToken());
    }
}

.NET

private void PrintDevices(AndroidProvisioningPartnerService service, String customerAccount,
                          String pageToken)
{
    // Call the API to get a page of Devices. Send a page token from the method argument.
    // If the page token is null, the API returns the first page.
    var request = service.Customers.Devices.List(customerAccount);
    request.PageSize = 50;
    request.PageToken = pageToken;
    var response = request.Execute();

    // Print the devices included in this page of results.
    foreach (Device device in response.Devices)
    {
        Console.WriteLine("Device: {0}", device.Name);
    }
    Console.WriteLine("---");

    // Check to see if another page of devices is available. If yes, fetch and print the devices.
    if (response.NextPageToken != null)
    {
        this.PrintDevices(service, customerAccount, response.NextPageToken);
    }
}

Python

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

  # Call the API to get a page of Devices. Send a page token from the method
  # argument. If the page token is None, the API returns the first page.
  response = service.customers().devices().list(
      parent=customer_account, pageSize=50, pageToken=page_token).execute()

  # Print the devices included in this page of results.
  for device in response['devices']:
    print('Device: {0}'.format(device['name']))
  print('---')

  # Check to see if another page of devices is available. If yes,
  # fetch and print the devices.
  if 'nextPageToken' in response:
    print_devices(service, customer_account, response['nextPageToken'])

Mulai

Selanjutnya, baca cara melakukan otorisasi panggilan API di Authorization. Jika Anda ingin mempelajari API, lihat panduan memulai untuk Java, .NET, dan Python. Anda dapat menggunakan colab untuk melihat contoh panggilan API dan bereksperimen dengan memanggil API sendiri.