Cara kerja

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

Ringkasan

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

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

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

Pengguna umum API ini adalah:

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

Referensi 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 kepada membantu pengguna. Konfigurasi merupakan inti dari API, jadi Anda akan menggunakannya di berbagai metode. Untuk mempelajari lebih lanjut, lihat Konfigurasi di bawah.

Perangkat

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

DPC

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

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

Konfigurasi

Resource API Configuration menggabungkan hal berikut:

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

Dengan menggunakan API, aplikasi Anda dapat mengelola konfigurasi untuk admin IT. Memanggil API ke mengambil, membuat, memperbarui, dan menghapus konfigurasi. Contoh di bawah ini menunjukkan cara buat 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, ingatlah untuk menyertakan field mask—atau untuk setiap kolom yang tidak Anda inginkan berupa null. Lihat Default konfigurasi (di bawah) untuk contoh yang menunjukkan cara memperbarui konfigurasi secara efisien.

Hapus konfigurasi

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

Konfigurasi default

Pendaftaran zero-touch berfungsi paling optimal jika organisasi menetapkan konfigurasi default yang diterapkan ke semua perangkat baru yang dibeli organisasi. Pertimbangkan untuk meminta admin IT menetapkan konfigurasi default jika belum disetel. Contoh di bawah ini menunjukkan cara menjadikan 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. Membuat konfigurasi {i>default<i} baru, menyetel kolom isDefault konfigurasi sebelumnya ke false. Anda mungkin perlu muat ulang instance Configuration yang di-cache untuk melihat nilai yang benar dalam isDefault kolom.

Memandu pengguna perangkat

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

Karena pengguna tidak akan dapat menelepon atau mengirim email dari perangkat yang mereka setel format nomor telepon dan alamat email agar lebih mudah melihat sekilas informasi.

Perangkat

Reseller membuat perangkat saat pelanggan membelinya untuk pendaftaran zero-touch—admin IT tidak dapat membuat perangkat. Agar dapat digunakan dengan perangkat, panggil metode di resource Device API. Jika Anda perlu menelusuri perangkat, cantumkan semua perangkat dan filter setiap batch secara lokal di aplikasi Anda. Sebagai contoh, lihat Hasil yang di-paging di bawah.

Mengonfigurasi perangkat

Menerapkan konfigurasi ke perangkat akan mendaftarkan perangkat untuk zero-touch pendaftaran. Untuk menerapkan konfigurasi, panggil customers.devices.applyConfiguration. Setelah menerapkan konfigurasi, perangkat secara otomatis melakukan penyediaan sendiri {i>booting<i} pertama, atau {i>factory reset<i} berikutnya. Contoh di bawah ini menunjukkan cara menerapkan konfigurasi ke sekumpulan 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 ini berlaku setelah mereset perangkat ke setelan pabrik.

Batalkan klaim perangkat

Admin IT dapat membatalkan klaim perangkat untuk menghapusnya dari pendaftaran zero-touch. Seorang IT admin mungkin membatalkan klaim perangkat yang ingin mereka migrasikan ke akun lain, dijual, atau dikembalikan ke reseller. Memanggil metode customers.devices.unclaim untuk membatalkan klaim perangkat dari suatu organisasi.

Perhatian: Pertimbangkan untuk meminta pengguna aplikasi mengonfirmasi bahwa mereka memiliki perangkat yang benar sebelum memanggil API pembatalan klaim. Membatalkan klaim perangkat akan menghapus penyiapan penyediaan organisasi dan perangkat menjadi tidak terkelola setelah reset ke setelan pabrik. Admin IT harus menghubungi reseller jika ingin mendaftar 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 tentang metadata yang mungkin Anda lihat, baca Perangkat panduan metadata untuk reseller.

Hasil yang di-page

Metode customers.devices.list API mungkin menampilkan daftar perangkat yang sangat banyak. Untuk mengurangi ukuran respons, API ini dan API lainnya (seperti customers.list) mendukung hasil yang dibagi-bagi. Dengan hasil yang di-paging, aplikasi Anda dapat secara iteratif meminta dan memproses daftar besar satu halaman pada satu waktu.

Setelah memanggil metode API, periksa apakah respons mencakup nilai untuk nextPageToken Jika nextPageToken bukan null, aplikasi Anda dapat menggunakannya untuk mengambil halaman perangkat lain dengan memanggil metode 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 menunjukkan cara aplikasi Anda mencetak daftar perangkat, satu halaman pada 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 memberikan otorisasi panggilan API di bagian Otorisasi. 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.