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("it-support@example.com"); configuration.setContactPhone("+1 (800) 555-0112"); 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 = "it-support@example.com", ContactPhone = "+1 (800) 555-0112", 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': 'it-support@example.com', 'contactPhone': '+1 (800) 555-0112', '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.
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.