API pelanggan memberikan kontrol terprogram atas perangkat dan 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. Channel organisasi juga dapat membuat konfigurasi dan perangkat menggunakan zero-touch portal pendaftaran.
- 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 Configuration
API menggabungkan
berikut ini:
- 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("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, 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 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 optimal jika organisasi menetapkan setelan default
konfigurasi yang diterapkan ke perangkat
baru yang dibeli organisasi.
Pertimbangkan untuk meminta admin IT menetapkan konfigurasi default jika belum disetel.
Contoh di bawah menunjukkan cara menjadikan konfigurasi yang ada sebagai default oleh
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 perlu menyertakan nomor telepon dan email kontak
beserta nama organisasi yang mengelola perangkat dalam
konfigurasi Anda. 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 zero-touch
pendaftaran—admin IT tidak dapat membuat perangkat. Agar dapat digunakan dengan perangkat, panggil metode di
resource Device
API. Jika Anda perlu mencari
untuk perangkat, cantumkan semua perangkat dan filter setiap batch secara lokal di aplikasi Anda. Sebagai
contoh, lihat Hasil berhalaman 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.
Contoh di bawah 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. Layar 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 dalam halaman
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-page, aplikasi Anda dapat secara iteratif meminta dan memproses daftar yang 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
metode lagi. Anda perlu menyetel batas atas untuk jumlah perangkat di
Parameter pageSize
. Jika nextPageToken
adalah null
, aplikasi Anda telah meminta
halaman terakhir.
Contoh metode di bawah ini menunjukkan cara aplikasi 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.