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 เพื่อดึงข้อมูล สร้าง อัปเดต และลบการกําหนดค่า ตัวอย่างด้านล่างแสดงวิธีสร้างการกำหนดค่าใหม่
// 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();
// 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();
# 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
:
// 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();
// 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();
# 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
หลังจากใช้การกำหนดค่า อุปกรณ์จะจัดสรรตัวเองโดยอัตโนมัติใน
เปิดเครื่องครั้งแรก หรือรีเซ็ตเป็นค่าเริ่มต้นครั้งถัดไป ตัวอย่างด้านล่างแสดงวิธีที่คุณอาจนำไปใช้
การกำหนดค่าให้กับคอลเล็กชันอุปกรณ์
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();
}
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();
}
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 และ ชื่อผู้ผลิต:
// 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();
// 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();
# 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
แสดงว่าแอปของคุณได้ขอหน้าสุดท้ายแล้ว
ตัวอย่างเมธอดด้านล่างแสดงวิธีที่แอปอาจพิมพ์รายการอุปกรณ์ทีละหน้า
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());
}
}
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);
}
}
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 ด้วยตัวเอง