API ของลูกค้าช่วยในการควบคุมอุปกรณ์และการกำหนดค่าสำหรับการตั้งค่าอุปกรณ์พร้อมใช้แบบรวมกลุ่มของ Android แบบเป็นโปรแกรม เอกสารนี้จะแนะนำ API ให้กับผู้ให้บริการ Enterprise Mobility Management (EMM) และนักพัฒนาซอฟต์แวร์ด้านไอทีขององค์กร หลังจากอ่านเอกสารนี้ คุณควรเข้าใจทรัพยากรหลักที่ใช้ใน API และวิธีการโต้ตอบ หากคุณเพิ่งเริ่มใช้การตั้งค่าอุปกรณ์พร้อมใช้แบบรวมกลุ่ม โปรดอ่านข้อมูลเบื้องต้นเกี่ยวกับ android.com สั้นๆ
ภาพรวม
Customer API จะช่วยองค์กรที่ซื้ออุปกรณ์การตั้งค่าอุปกรณ์พร้อมใช้แบบรวมกลุ่มของ Android แอปหรือเครื่องมือของคุณช่วยผู้ดูแลระบบไอทีทำสิ่งต่อไปนี้ได้
- สร้าง แก้ไข และลบการกำหนดค่าการจัดสรร
- ใช้หรือนำการกำหนดค่าออกจากอุปกรณ์
- เลือกการกำหนดค่าเริ่มต้นสำหรับอุปกรณ์ที่จะเพิ่มลงในการตั้งค่าอุปกรณ์พร้อมใช้แบบรวมกลุ่มในอนาคต
นอกจากนี้ยังสามารถยกเลิกการลงทะเบียนอุปกรณ์จากการลงทะเบียนอุปกรณ์พร้อมใช้แบบรวมกลุ่มผ่าน API ได้ด้วย หากต้องการจัดการผู้ใช้ขององค์กรหรือยอมรับข้อกำหนดในการให้บริการ ผู้ดูแลระบบไอทีจะใช้พอร์ทัลการตั้งค่าอุปกรณ์พร้อมใช้แบบรวมกลุ่ม
ผู้ใช้โดยทั่วไปของ API นี้อาจเป็น:
- ผู้ให้บริการ EMM เพิ่มการรองรับการตั้งค่าอุปกรณ์พร้อมใช้แบบรวมกลุ่มไปยังคอนโซลของตน
- นักพัฒนาไอทีขององค์กรสร้างเครื่องมือที่ช่วยให้งานการตั้งค่าอุปกรณ์พร้อมใช้แบบรวมกลุ่มทำงานโดยอัตโนมัติ
ทรัพยากรหลัก
การกำหนดค่าและอุปกรณ์เป็นทรัพยากรหลักที่คุณใช้ใน API นอกจากนี้ องค์กรยังสร้างการกำหนดค่าและอุปกรณ์โดยใช้พอร์ทัลการลงทะเบียนอุปกรณ์พร้อมใช้แบบรวมกลุ่มได้ด้วย
- การกำหนดค่า
- ผู้ดูแลระบบไอทีตั้งค่าตัวเลือกการจัดสรรให้กับอุปกรณ์ที่ใช้การกำหนดค่าเดียวกันได้ ซึ่งการกำหนดค่าจะมีนโยบายด้านอุปกรณ์เคลื่อนที่ของ EMM และข้อมูลติดต่อที่แสดงเพื่อช่วยเหลือผู้ใช้ การกำหนดค่าเป็นหัวใจสำคัญของ API คุณจึงนำไปใช้ได้หลายวิธี ดูข้อมูลเพิ่มเติมได้ที่การกำหนดค่าด้านล่าง
- อุปกรณ์
- อุปกรณ์ Android การตั้งค่าอุปกรณ์พร้อมใช้แบบรวมกลุ่มซึ่งองค์กรซื้อจากตัวแทนจำหน่าย ใช้การกำหนดค่าเพื่อรวมอุปกรณ์ไว้ในการลงทะเบียนอุปกรณ์พร้อมใช้แบบรวมกลุ่ม อุปกรณ์จะมีรหัสฮาร์ดแวร์และข้อมูลเมตาที่แนบมา ดูข้อมูลเพิ่มเติมได้ที่อุปกรณ์ด้านล่าง
- DPC
- ข้อมูลอ้างอิงแบบอ่านอย่างเดียวไปยัง DPC ของ EMM (เครื่องมือควบคุมนโยบายด้านอุปกรณ์) เพิ่ม DPC ในการกำหนดค่าเพื่อเลือกโซลูชัน EMM สำหรับอุปกรณ์ DPC ทั้งหมดที่ระบุไว้โดย API รองรับการตั้งค่าอุปกรณ์พร้อมใช้แบบรวมกลุ่มและพร้อมให้บริการใน Google Play ดูข้อมูลเพิ่มเติมได้ที่
Dpc
หากต้องการดูรายการเมธอด API และทรัพยากรทั้งหมดที่แอปใช้ได้ โปรดดูเอกสารอ้างอิง API
การกำหนดค่า
ทรัพยากร API ของ Configuration
ประกอบด้วยสิ่งต่างๆ ต่อไปนี้
- DPC ของ EMM ที่ติดตั้งในอุปกรณ์
- บังคับใช้นโยบาย EMM ในอุปกรณ์
- ข้อมูลติดต่อที่แสดงในอุปกรณ์เพื่อช่วยเหลือผู้ใช้ในระหว่างการตั้งค่า
เมื่อใช้ API แอปของคุณจะจัดการการกำหนดค่าสำหรับผู้ดูแลระบบไอทีได้ เรียก API เพื่อดึงข้อมูล สร้าง อัปเดต และลบการกำหนดค่า ตัวอย่างด้านล่างแสดงวิธีสร้างการกำหนดค่าใหม่
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()
เมื่อคุณอัปเดตการกำหนดค่าโดยใช้แพตช์ API อย่าลืมใส่มาสก์ของช่อง หรือค่าสำหรับทุกช่องที่คุณไม่ต้องการให้เป็น null
โปรดดูการกำหนดค่าเริ่มต้น (ด้านล่าง) สำหรับตัวอย่างที่แสดงวิธีอัปเดตการกำหนดค่าอย่างมีประสิทธิภาพ
ลบการกำหนดค่า
คุณลบการกำหนดค่าไม่ได้หากยังใช้การกำหนดค่าดังกล่าวกับอุปกรณ์อยู่ หากคุณพยายามลบการกำหนดค่าที่ใช้งานอยู่ เมธอด API จะแสดงรหัสสถานะ HTTP 400 Bad Request
และข้อความอธิบายจำนวนอุปกรณ์ที่ใช้การกำหนดค่า
โปรดโทร customers.devices.removeConfiguration
เพื่อนำการกำหนดค่าออกจากอุปกรณ์ก่อนลองอีกครั้ง
การกำหนดค่าเริ่มต้น
การตั้งค่าอุปกรณ์พร้อมใช้แบบรวมกลุ่มจะทำงานได้ดีที่สุดเมื่อองค์กรตั้งการกำหนดค่าเริ่มต้นที่จะนำไปใช้กับอุปกรณ์ใหม่ทั้งหมดที่องค์กรซื้อ
ลองแจ้งให้ผู้ดูแลระบบไอทีตั้งค่าการกำหนดค่าเริ่มต้นหากไม่ได้ตั้งค่าไว้
ตัวอย่างด้านล่างแสดงวิธีทำให้การกำหนดค่าที่มีอยู่เป็นค่าเริ่มต้นโดยตั้งค่า isDefault
เป็น 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()
มีการกำหนดค่าเริ่มต้นได้เพียงรายการเดียวเท่านั้น การสร้างการกำหนดค่าเริ่มต้นใหม่
จะตั้งค่าช่อง isDefault
ของการกำหนดค่าก่อนหน้าเป็น false
คุณอาจต้องรีเฟรชอินสแตนซ์ Configuration
ที่แคชไว้เพื่อดูค่าที่ถูกต้องในช่อง isDefault
แนะนำผู้ใช้อุปกรณ์
การกำหนดค่าอุปกรณ์พร้อมใช้แบบรวมกลุ่ม จะแสดงคำแนะนำที่ปรับแต่งสำหรับผู้ใช้ในวิซาร์ดการตั้งค่าอุปกรณ์เพื่อช่วยผู้ใช้ คุณต้องระบุหมายเลขโทรศัพท์และอีเมลสำหรับติดต่อ พร้อมด้วยชื่อองค์กรที่จัดการอุปกรณ์ในการกำหนดค่า นอกจากนี้เราขอแนะนำให้เพิ่มประโยค 1 หรือ 2 ประโยคในช่อง customMessage
เพื่อให้รายละเอียดเพิ่มเติมเกี่ยวกับสิ่งที่เกิดขึ้นกับอุปกรณ์ของผู้ใช้
เนื่องจากผู้ใช้จะไม่สามารถโทรหรืออีเมลได้จากอุปกรณ์ที่ตั้งค่าอยู่ โปรดจัดรูปแบบหมายเลขโทรศัพท์และอีเมลเพื่อให้ดูข้อมูลได้ง่ายขึ้น
อุปกรณ์
ตัวแทนจำหน่ายจะสร้างอุปกรณ์เมื่อลูกค้าซื้ออุปกรณ์สำหรับการลงทะเบียนอุปกรณ์พร้อมใช้แบบรวมกลุ่ม ผู้ดูแลระบบไอทีจะสร้างอุปกรณ์ไม่ได้ หากต้องการทำงานกับอุปกรณ์ ให้เรียกใช้เมธอดในทรัพยากร API ของ Device
หากคุณต้องการค้นหาอุปกรณ์ ให้แสดงอุปกรณ์ทั้งหมดและกรองแต่ละกลุ่มในแอปในเครื่อง ดูตัวอย่างได้ที่ผลการค้นหาที่แบ่งหน้าด้านล่าง
กำหนดค่าอุปกรณ์
การใช้การกำหนดค่ากับอุปกรณ์จะเป็นการลงทะเบียนอุปกรณ์สำหรับการตั้งค่าอุปกรณ์พร้อมใช้แบบรวมกลุ่ม หากต้องการใช้การกำหนดค่า โปรดเรียกใช้ customers.devices.applyConfiguration
หลังจากใช้การกำหนดค่า อุปกรณ์จะจัดสรรตัวเองโดยอัตโนมัติเมื่อเปิดเครื่องครั้งแรกหรือรีเซ็ตเป็นค่าเริ่มต้นในครั้งถัดไป ตัวอย่างด้านล่างแสดงวิธีนำการกำหนดค่าไปใช้กับคอลเล็กชันอุปกรณ์
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()
หากต้องการนำการกำหนดค่าออกจากอุปกรณ์ ให้โทรหา customers.devices.removeConfiguration
การเปลี่ยนแปลงจะมีผลหลังจากรีเซ็ตอุปกรณ์เป็นค่าเริ่มต้น
ถอนการอ้างสิทธิ์อุปกรณ์
ผู้ดูแลระบบไอทีสามารถถอนการอ้างสิทธิ์อุปกรณ์เพื่อนำอุปกรณ์ออกจากการตั้งค่าอุปกรณ์พร้อมใช้แบบรวมกลุ่มได้ ผู้ดูแลระบบไอทีอาจถอนการอ้างสิทธิ์อุปกรณ์ที่ต้องการย้ายข้อมูลไปยังบัญชีอื่น จำหน่าย หรือส่งคืนให้ตัวแทนจำหน่าย เรียกใช้เมธอด customers.devices.unclaim
เพื่อถอนการอ้างสิทธิ์อุปกรณ์จากองค์กร
ตัวอย่างด้านล่างแสดงวิธีถอนการอ้างสิทธิ์อุปกรณ์จากหมายเลข IMEI และชื่อผู้ผลิต
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()
ข้อมูลเมตาของอุปกรณ์
ผู้ดูแลระบบไอทีจะดูข้อมูลเมตาที่ตัวแทนจำหน่ายแนบมากับอุปกรณ์ได้ แสดงข้อมูลเมตาของอุปกรณ์นี้ในแอปของคุณเพื่อช่วยให้ผู้ดูแลระบบไอทีจดจำอุปกรณ์ได้
หากต้องการดูข้อมูลเพิ่มเติมเกี่ยวกับข้อมูลเมตาที่คุณอาจเห็น โปรดอ่านคู่มือข้อมูลเมตาของอุปกรณ์สำหรับตัวแทนจำหน่าย
ผลลัพธ์แบบแบ่งหน้า
เมธอด API ของ customers.devices.list
อาจแสดงรายการอุปกรณ์จำนวนมาก หากต้องการลดขนาดการตอบกลับ วิธีนี้และเมธอด API อื่นๆ (เช่น customers.list
) จะรองรับผลการค้นหาแบบแบ่งหน้า เมื่อใช้ผลการค้นหาที่แบ่งหน้า แอปพลิเคชันจะขอและประมวลผลรายการขนาดใหญ่ได้ครั้งละ 1 หน้าเสมอ
หลังจากเรียกเมธอด API แล้ว ให้ตรวจสอบว่าการตอบกลับมีค่าสำหรับ nextPageToken
หรือไม่ หาก nextPageToken
ไม่ใช่ null
แอปของคุณจะใช้หน้าเพื่อดึงข้อมูลหน้าอื่นของอุปกรณ์ได้โดยเรียกใช้เมธอดอีกครั้ง คุณต้องตั้งค่าขีดจำกัดสูงสุดสำหรับจำนวนอุปกรณ์ในพารามิเตอร์ pageSize
หาก nextPageToken
คือ null
แสดงว่าแอปขอหน้าสุดท้าย
วิธีการตัวอย่างด้านล่างแสดงวิธีที่แอปอาจพิมพ์รายการอุปกรณ์ทีละหน้า
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'])
เริ่มต้นใช้งาน
ถัดไป โปรดอ่านวิธีให้สิทธิ์การเรียก API ใน Authorization หากต้องการสำรวจ API ให้ดูคู่มือเริ่มใช้งานฉบับย่อสำหรับ Java, .NET และ Python คุณใช้ Colab เพื่อดูตัวอย่างการเรียก API และทดสอบการเรียก API ด้วยตนเองได้