API ของลูกค้าทำให้ควบคุมอุปกรณ์และ การกำหนดค่าอุปกรณ์พร้อมใช้แบบรวมกลุ่มของ Android เอกสารนี้จะแนะนำ API ให้แก่ผู้ให้บริการ Enterprise Mobility Management (EMM) และนักพัฒนาซอฟต์แวร์ไอทีขององค์กร หลังจากอ่านเอกสารนี้ คุณควรทำความเข้าใจเกี่ยวกับ ทรัพยากรที่ใช้ใน API และโต้ตอบอย่างไร หากคุณเพิ่งเริ่มใช้การตั้งค่าอุปกรณ์พร้อมใช้แบบรวมกลุ่ม การลงทะเบียน ให้อ่านสั้นๆ ที่ android.com ข้อมูลเบื้องต้น
ภาพรวม
Customer API ช่วยให้องค์กรที่ซื้อการตั้งค่าอุปกรณ์พร้อมใช้แบบรวมกลุ่มของ Android ได้ อุปกรณ์ แอปหรือเครื่องมือช่วยให้ผู้ดูแลระบบไอทีทำสิ่งต่อไปนี้ได้
- สร้าง แก้ไข และลบการกำหนดค่าการจัดสรร
- ใช้หรือนำการกำหนดค่าออกจากอุปกรณ์
- เลือกการกำหนดค่าเริ่มต้นสำหรับอุปกรณ์ที่จะเพิ่มลงในการตั้งค่าอุปกรณ์พร้อมใช้แบบรวมกลุ่มในอนาคต
นอกจากนี้ ผู้ดูแลระบบไอทียังยกเลิกการลงทะเบียนอุปกรณ์จากการตั้งค่าอุปกรณ์พร้อมใช้แบบรวมกลุ่มผ่าน API ได้อีกด้วย การลงทะเบียนเข้าร่วม หากต้องการจัดการผู้ใช้ในองค์กรหรือยอมรับข้อกำหนดในการให้บริการ ผู้ดูแลระบบไอทีใช้พอร์ทัลการตั้งค่าอุปกรณ์พร้อมใช้แบบรวมกลุ่ม
ผู้ใช้ทั่วไปของ API นี้อาจได้แก่
- ผู้ให้บริการ EMM ที่เพิ่มการรองรับการตั้งค่าอุปกรณ์พร้อมใช้แบบรวมกลุ่มลงในคอนโซล
- นักพัฒนาซอฟต์แวร์ด้านไอทีระดับองค์กรที่สร้างเครื่องมือเพื่อช่วยให้การตั้งค่าอุปกรณ์พร้อมใช้แบบรวมกลุ่มเป็นแบบอัตโนมัติ งาน
แหล่งข้อมูลหลัก
การกำหนดค่าและอุปกรณ์เป็นทรัพยากรหลักที่คุณใช้ใน API CANNOT TRANSLATE องค์กรยังสร้างการกำหนดค่าและอุปกรณ์โดยใช้การตั้งค่าอุปกรณ์พร้อมใช้แบบรวมกลุ่มได้ด้วย ด้วยพอร์ทัลการลงทะเบียน
- การกำหนดค่า
- ผู้ดูแลระบบไอทีตั้งค่าตัวเลือกการจัดสรรสำหรับอุปกรณ์โดยใช้การกำหนดค่า การกำหนดค่ารวมถึงนโยบายอุปกรณ์เคลื่อนที่ของ 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()
เมื่ออัปเดตการกําหนดค่าโดยใช้ Patch 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 นี้และ API อื่นๆ
(เช่น customers.list
) รองรับผลลัพธ์แบบแบ่งหน้า ด้วย
ผลลัพธ์แบ่งเป็นหน้า แอปพลิเคชันของคุณจะขอและดำเนินการกับรายการจำนวนมากซ้ำๆ
ทีละหน้า
หลังจากเรียกใช้เมธอด 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 ในการให้สิทธิ์ หากคุณต้องการ สำรวจ API โปรดดูคู่มือเริ่มใช้งานฉบับย่อสำหรับ Java .NET และ Python คุณสามารถใช้ Colab เพื่อดู ตัวอย่างการเรียก API และการทดสอบการเรียก API ด้วยตัวเอง