บทนำ
API การตั้งค่าอุปกรณ์พร้อมใช้แบบรวมกลุ่มช่วยให้ตัวแทนจำหน่ายอุปกรณ์ผสานรวมโดยอัตโนมัติได้ เครื่องมือขายขององค์กรสามารถสร้างการลงทะเบียนแบบรวมศูนย์ได้ ซึ่งจะช่วยให้ผู้ใช้และลูกค้าของคุณทำงานได้อย่างมีประสิทธิภาพมากขึ้น ใช้ API เพื่อช่วยผู้ใช้ดำเนินการต่อไปนี้
- กำหนดอุปกรณ์ที่ซื้อให้กับบัญชีการตั้งค่าอุปกรณ์พร้อมใช้แบบรวมกลุ่มของลูกค้า
- สร้างบัญชีการตั้งค่าอุปกรณ์พร้อมใช้แบบรวมกลุ่มของลูกค้า
- แนบข้อมูลโทรศัพท์ขององค์กรและข้อมูลเมตาคำสั่งซื้อกับอุปกรณ์
- สร้างรายงานเกี่ยวกับอุปกรณ์ที่มอบหมายให้กับลูกค้า
เอกสารนี้จะแนะนำ API และอธิบายรูปแบบ หากต้องการสำรวจ API ด้วยตนเอง ให้ลองใช้การเริ่มต้นใช้งานฉบับย่อสำหรับ Java, .NET หรือ Python
แนวคิดเกี่ยวกับ API
ลูกค้าและอุปกรณ์คือทรัพยากรหลักที่คุณใช้ใน API หากต้องการสร้างลูกค้า ให้โทรไปที่ create
คุณสร้างอุปกรณ์ได้
โดยใช้เมธอด API การอ้างสิทธิ์ (ดูด้านล่าง) นอกจากนี้ องค์กรของคุณยังดำเนินการต่อไปนี้ได้
สร้างลูกค้าและอุปกรณ์โดยใช้พอร์ทัลการตั้งค่าอุปกรณ์พร้อมใช้แบบรวมกลุ่ม
- ลูกค้า
- บริษัทที่องค์กรของคุณขายอุปกรณ์ให้ ลูกค้ามี
name
และID
ใช้บริการของลูกค้าเมื่อคุณต้องการอ้างสิทธิ์หรือค้นหาอุปกรณ์ของพวกเขา ถึง ดูข้อมูลเพิ่มเติมได้ที่Customer
- อุปกรณ์
- อุปกรณ์ Android หรือ ChromeOS ขององค์กรที่รองรับการตั้งค่าอุปกรณ์พร้อมใช้แบบรวมกลุ่ม
ขายให้ลูกค้า อุปกรณ์มีรหัสฮาร์ดแวร์ ข้อมูลเมตา และการอ้างสิทธิ์ของลูกค้า อุปกรณ์เป็นหัวใจสำคัญของ API คุณจึงใช้อุปกรณ์เหล่านี้ได้ใน
ดูข้อมูลเพิ่มเติมได้ที่
Device
- DeviceIdentifier
- รวมรหัสฮาร์ดแวร์ เช่น IMEI หรือ MEID เพื่อระบุอุปกรณ์ที่ผลิต ใช้
DeviceIdentifier
เพื่อกําหนดเป้าหมายอุปกรณ์ที่ต้องการค้นหา อัปเดต หรืออ้างสิทธิ์ หากต้องการดูข้อมูลเพิ่มเติม โปรดอ่าน ตัวระบุ - DeviceMetadata
- จัดเก็บคู่คีย์-ค่าของข้อมูลเมตาสําหรับอุปกรณ์ ใช้
DeviceMetadata
เพื่อจัดเก็บข้อมูลเมตาขององค์กร ถึง ดูข้อมูลเพิ่มเติมได้ที่ข้อมูลเมตาของอุปกรณ์
หากต้องการดูรายการเมธอดและทรัพยากร API ทั้งหมดที่แอปของคุณใช้ได้ โปรดดูเอกสารอ้างอิง API
สร้างลูกค้า
สำหรับอุปกรณ์ Android ตัวแทนจำหน่ายมีหน้าที่รับผิดชอบในการสร้างบัญชีลูกค้าในนามของลูกค้า ลูกค้าจะใช้บัญชีนี้เพื่อ เข้าถึงพอร์ทัลการตั้งค่าอุปกรณ์พร้อมใช้แบบรวมกลุ่มเพื่อกำหนดการตั้งค่าการจัดสรรสำหรับ อุปกรณ์ ขั้นตอนนี้ไม่จำเป็นสำหรับอุปกรณ์ ChromeOS ที่มีบัญชี Google Workspace อยู่แล้ว ซึ่งผู้ใช้จะใช้เพื่อกำหนดการตั้งค่าการจัดสรร
คุณสามารถเรียกใช้เมธอด create
API เพื่อสร้างบัญชีลูกค้าสำหรับการตั้งค่าอุปกรณ์พร้อมใช้แบบรวมกลุ่ม เนื่องจากลูกค้าของคุณจะเห็น
ชื่อบริษัทในพอร์ทัลการตั้งค่าอุปกรณ์พร้อมใช้แบบรวมกลุ่ม ผู้ใช้แอปควร
เพื่อยืนยันว่าถูกต้อง คุณไม่สามารถแก้ไขชื่อลูกค้าหลังจากสร้าง
ลูกค้า
คุณต้องระบุอีเมลของบริษัทอย่างน้อย 1 รายการซึ่งเชื่อมโยงกับ บัญชี Google ที่จะเป็นเจ้าของ คุณใช้บัญชี Gmail ส่วนบุคคลกับ API ไม่ได้ หากลูกค้าต้องการความช่วยเหลือในการเชื่อมโยงบัญชี ให้ส่ง คำสั่งจาก เชื่อมโยงบัญชี Google
หลังจากที่คุณสร้างลูกค้าด้วยการเรียกใช้ API ลูกค้าจะจัดการพนักงานของตน สิทธิ์การเข้าถึงพอร์ทัล — คุณไม่สามารถแก้ไขลูกค้าของคุณได้ ผู้ใช้ที่ใช้ API ข้อมูลโค้ดด้านล่างแสดงวิธีที่คุณอาจสร้างลูกค้า
Java
// Provide the customer data as a Company type. // The API requires a name and owners. Company customer = new Company(); customer.setCompanyName("XYZ Corp"); customer.setOwnerEmails(Arrays.asList("liz@example.com", "darcy@example.com")); customer.setAdminEmails(Collections.singletonList("jane@example.com")); // Use our reseller ID for the parent resource name. String parentResource = String.format("partners/%d", PARTNER_ID); // Call the API to create the customer using the values in the company object. CreateCustomerRequest body = new CreateCustomerRequest(); body.setCustomer(customer); Company response = service.partners().customers().create(parentResource, body).execute();
.NET
// Provide the customer data as a Company type. // The API requires a name and owners. var customer = new Company { CompanyName = "XYZ Corp", OwnerEmails = new String[] { "liz@example.com", "darcy@example.com" }, AdminEmails = new String[] { "jane@example.com" } }; // Use our reseller ID for the parent resource name. var parentResource = String.Format("partners/{0}", PartnerId); // Call the API to create the customer using the values in the company object. var body = new CreateCustomerRequest { Customer = customer }; var request = service.Partners.Customers.Create(body, parentResource); var response = request.Execute();
Python
# Provide the customer data as a Company type. The API requires # a name and at least one owner. company = {'companyName':'XYZ Corp', \ 'ownerEmails':['liz@example.com', 'darcy@example.com'], \ 'adminEmails':['jane@example.com']} # Use our reseller ID for the parent resource name. parent_resource = 'partners/{0}'.format(PARTNER_ID) # Call the API to create the customer using the values in the company object. response = service.partners().customers().create(parent=parent_resource, body={'customer':company}).execute()
หากต้องการดูข้อมูลเพิ่มเติมเกี่ยวกับบทบาทของเจ้าของและผู้ดูแลระบบสำหรับพนักงานของลูกค้า โปรดอ่านผู้ใช้พอร์ทัล
อ้างสิทธิ์อุปกรณ์ให้กับลูกค้า
หลังจากที่ลูกค้าซื้ออุปกรณ์แล้ว ลูกค้าจะต้องกำหนดค่าการจัดสรร การตั้งค่าสำหรับอุปกรณ์เหล่านี้ในบัญชีของตน การอ้างสิทธิ์อุปกรณ์จะเพิ่มอุปกรณ์ การตั้งค่าอุปกรณ์พร้อมใช้แบบรวมกลุ่ม และช่วยให้ลูกค้ากำหนดค่า การตั้งค่าการจัดสรร
ระเบียนการจัดสรรของอุปกรณ์จะมีส่วนสําหรับการตั้งค่าอุปกรณ์พร้อมใช้แบบรวมกลุ่ม คุณ
กำหนดอุปกรณ์โดยอ้างสิทธิ์ในส่วนการตั้งค่าอุปกรณ์พร้อมใช้แบบรวมกลุ่มของระเบียนสำหรับ
ลูกค้า เรียกใช้เมธอด partners.devices.claim
หรือ partners.devices.claimAsync
โดยระบุ customer เป็นอาร์กิวเมนต์ ระบุ SECTION_TYPE_ZERO_TOUCH
เป็นค่าเสมอสำหรับ
sectionType
คุณจะต้องยกเลิกการอ้างสิทธิ์ (ดูด้านล่าง) อุปกรณ์ของลูกค้าก่อนจึงจะอ้างสิทธิ์อุปกรณ์เครื่องเดียวกันให้กับลูกค้ารายอื่นได้ วิธีการอ้างสิทธิ์
ตรวจสอบช่อง DeviceIdentifier
รวมถึง IMEI หรือ MEID หรือหมายเลขซีเรียล
ชื่อผู้ผลิตและรุ่น
รหัสอุปกรณ์ที่ผ่านการรับรองสำหรับอุปกรณ์ ChromeOS เมื่อสร้างอุปกรณ์ใหม่
ตัวอย่างข้อมูลด้านล่างแสดงวิธีอ้างสิทธิ์อุปกรณ์
Java
// Identify the device to claim. DeviceIdentifier identifier = new DeviceIdentifier(); // The manufacturer value is optional but recommended for cellular devices identifier.setManufacturer("Google"); identifier.setImei("098765432109875"); // Create the body to connect the customer with the device. ClaimDeviceRequest body = new ClaimDeviceRequest(); body.setDeviceIdentifier(identifier); body.setCustomerId(customerId); body.setSectionType("SECTION_TYPE_ZERO_TOUCH"); // Claim the device. ClaimDeviceResponse response = service.partners().devices().claim(PARTNER_ID, body).execute();
.NET
// Identify the device to claim. var deviceIdentifier = new DeviceIdentifier { // The manufacturer value is optional but recommended for cellular devices Manufacturer = "Google", Imei = "098765432109875" }; // Create the body to connect the customer with the device. ClaimDeviceRequest body = new ClaimDeviceRequest { DeviceIdentifier = deviceIdentifier, CustomerId = CustomerId, SectionType = "SECTION_TYPE_ZERO_TOUCH" }; // Claim the device. var response = service.Partners.Devices.Claim(body, PartnerId).Execute();
Python
# Identify the device to claim. # The manufacturer value is optional but recommended for cellular devices device_identifier = {'manufacturer':'Google', 'imei':'098765432109875'} # Create the body to connect the customer with the device. request_body = {'deviceIdentifier':device_identifier, \ 'customerId':customer_id, \ 'sectionType':'SECTION_TYPE_ZERO_TOUCH'} # Claim the device. response = service.partners().devices().claim(partnerId=PARTNER_ID, body=request_body).execute()
กำลังถอนการอ้างสิทธิ์อุปกรณ์
องค์กรสามารถยกเลิกการอ้างสิทธิ์อุปกรณ์จากลูกค้าได้ การถอนการอ้างสิทธิ์อุปกรณ์
นำออกจากการตั้งค่าอุปกรณ์พร้อมใช้แบบรวมกลุ่ม ตัวแทนจําหน่ายอาจยกเลิกการอ้างสิทธิ์ในอุปกรณ์ที่ต้องการย้ายข้อมูลไปยังบัญชีอื่น คืน หรือมีการอ้างสิทธิ์โดยไม่ได้ตั้งใจ
เรียกใช้เมธอด partners.devices.unclaim
หรือ partners.devices.unclaimAsync
เพื่อยกเลิกการอ้างสิทธิ์อุปกรณ์จากลูกค้า
ตัวแทนจำหน่ายรายย่อย
คุณสามารถใช้ผู้ให้บริการเพื่อแสดงตัวแทนพาร์ทเนอร์ตัวแทนจำหน่ายในเครือข่ายตัวแทนจำหน่าย ผู้ให้บริการในพื้นที่ภายในเครือข่ายตัวแทนจำหน่ายทั่วโลก หรือองค์กรใดก็ตามที่ขายอุปกรณ์ในนามของคุณ ผู้ให้บริการจะช่วยคุณแยกผู้ใช้ ลูกค้า และอุปกรณ์ ดังนี้
- ผู้ให้บริการที่คุณสร้างจะไม่เห็นบัญชีการตั้งค่าอุปกรณ์พร้อมใช้แบบรวมกลุ่มหรือบัญชีของกันและกัน
- คุณสามารถดูลูกค้าและอุปกรณ์ของผู้ให้บริการ รวมถึงยกเลิกการลงทะเบียนอุปกรณ์ของผู้ให้บริการได้ แต่คุณจะกําหนดอุปกรณ์ให้กับผู้ให้บริการไม่ได้ ลูกค้า
ใช้พอร์ทัลเพื่อสร้างผู้ให้บริการสำหรับ
องค์กร - คุณจะใช้ API ไม่ได้ บทบาทของบัญชีต้องเป็นเจ้าของจึงจะสร้างผู้ให้บริการรายใหม่ได้ หากองค์กรของคุณมีผู้ให้บริการ
คุณสามารถโทรหา partners.vendors.list
เพื่อแสดง
ผู้ให้บริการและ partners.vendors.customers.list
เพื่อให้ได้ลูกค้าของผู้ให้บริการ ตัวอย่างต่อไปนี้ใช้ทั้ง 2 วิธีนี้เพื่อพิมพ์รายงานที่แสดงสถานะข้อกำหนดในการให้บริการสำหรับลูกค้าของผู้ให้บริการ
Java
// First, get the organization's vendors. String parentResource = String.format("partners/%d", PARTNER_ID); ListVendorsResponse results = service.partners().vendors().list(parentResource).execute(); if (results.getVendors() == null) { return; } // For each vendor, report the company name and a maximum 5 customers. for (Company vendor: results.getVendors()) { System.out.format("\n%s customers\n", vendor.getCompanyName()); System.out.println("---"); // Use the vendor's API resource name as the parent resource. AndroidProvisioningPartner.Partners.Vendors.Customers.List customerRequest = service.partners().vendors().customers().list(vendor.getName()); customerRequest.setPageSize(5); ListVendorCustomersResponse customerResponse = customerRequest.execute(); List<Company> customers = customerResponse.getCustomers(); if (customers == null) { System.out.println("No customers"); break; } else { for (Company customer: customers) { System.out.format("%s: %s\n", customer.getCompanyName(), customer.getTermsStatus()); } } }
.NET
// First, get the organization's vendors. var parentResource = String.Format("partners/{0}", PartnerId); var results = service.Partners.Vendors.List(parentResource).Execute(); if (results.Vendors == null) { return; } // For each vendor, report the company name and a maximum 5 customers. foreach (Company vendor in results.Vendors) { Console.WriteLine("\n{0} customers", vendor); Console.WriteLine("---"); // Use the vendor's API resource name as the parent resource. PartnersResource.VendorsResource.CustomersResource.ListRequest customerRequest = service.Partners.Vendors.Customers.List(vendor.Name); customerRequest.PageSize = 5; var customerResponse = customerRequest.Execute(); IList<Company> customers = customerResponse.Customers; if (customers == null) { Console.WriteLine("No customers"); break; } else { foreach (Company customer in customers) { Console.WriteLine("{0}: {1}", customer.Name, customer.TermsStatus); } } }
Python
# First, get the organization's vendors. parent_resource = 'partners/{0}'.format(PARTNER_ID) vendor_response = service.partners().vendors().list( parent=parent_resource).execute() if 'vendors' not in vendor_response: return # For each vendor, report the company name and a maximum 5 customers. for vendor in vendor_response['vendors']: print '\n{0} customers'.format(vendor['companyName']) print '---' # Use the vendor's API resource name as the parent resource. customer_response = service.partners().vendors().customers().list( parent=vendor['name'], pageSize=5).execute() if 'customers' not in customer_response: print 'No customers' break for customer in customer_response['customers']: print ' {0}: {1}'.format(customer['name'], customer['termsStatus'])
หากมีอุปกรณ์หลายเครื่อง คุณอาจต้องทราบว่าตัวแทนจำหน่ายหรือผู้ให้บริการรายใดอ้างสิทธิ์ในอุปกรณ์ หากต้องการดูรหัสตัวแทนจำหน่ายที่เป็นตัวเลข ให้ตรวจสอบค่าของ
ช่อง resellerId
ในบันทึกการอ้างสิทธิ์ของอุปกรณ์
องค์กรสามารถยกเลิกการอ้างสิทธิ์ในอุปกรณ์ที่อ้างสิทธิ์โดยผู้ให้บริการได้ สําหรับการเรียก API อื่นๆ ที่แก้ไขอุปกรณ์ คุณควรตรวจสอบว่าองค์กรของคุณอ้างสิทธิ์ในอุปกรณ์แล้วก่อนที่จะเรียกใช้เมธอด API ตัวอย่างต่อไปนี้แสดงวิธีดำเนินการ
Java
// Get the devices claimed for two customers: one of our organization's // customers and one of our vendor's customers. FindDevicesByOwnerRequest body = new FindDevicesByOwnerRequest(); body.setSectionType("SECTION_TYPE_ZERO_TOUCH"); body.setCustomerId(Arrays.asList(resellerCustomerId, vendorCustomerId)); body.setLimit(MAX_PAGE_SIZE); FindDevicesByOwnerResponse response = service.partners().devices().findByOwner(PARTNER_ID, body).execute(); if (response.getDevices() == null) { return; } for (Device device: response.getDevices()) { // Confirm the device was claimed by our reseller and not a vendor before // updating metadata in another method. for (DeviceClaim claim: device.getClaims()) { if (claim.getResellerId() == PARTNER_ID) { updateDeviceMetadata(device.getDeviceId()); break; } } }
.NET
// Get the devices claimed for two customers: one of our organization's // customers and one of our vendor's customers. FindDevicesByOwnerRequest body = new FindDevicesByOwnerRequest { Limit = MaxPageSize, SectionType = "SECTION_TYPE_ZERO_TOUCH", CustomerId = new List<long?> { resellerCustomerId, vendorCustomerId } }; var response = service.Partners.Devices.FindByOwner(body, PartnerId).Execute(); if (response.Devices == null) { return; } foreach (Device device in response.Devices) { // Confirm the device was claimed by our reseller and not a vendor before // updating metadata in another method. foreach (DeviceClaim claim in device.Claims) { if (claim.ResellerId == PartnerId) { UpdateDeviceMetadata(device.DeviceId); break; } } }
Python
# Get the devices claimed for two customers: one of our organization's # customers and one of our vendor's customers. request_body = {'limit':MAX_PAGE_SIZE, \ 'pageToken':None, \ 'customerId':[reseller_customer_id, vendor_customer_id], \ 'sectionType':'SECTION_TYPE_ZERO_TOUCH'} response = service.partners().devices().findByOwner(partnerId=PARTNER_ID, body=request_body).execute() for device in response['devices']: # Confirm the device was claimed by our reseller and not a vendor before # updating metadata in another method. for claim in device['claims']: if claim['resellerId'] == PARTNER_ID: update_device_metadata(device['deviceId']) break
การดำเนินการแบบกลุ่มที่ใช้เวลานาน
API มีเมธอดของอุปกรณ์เวอร์ชันแบบไม่พร้อมกัน
วิธีการเหล่านี้ช่วยให้สามารถประมวลผลอุปกรณ์จำนวนมากได้พร้อมกัน ขณะที่การเชื่อมต่อแบบซิงโครนัส
จะดำเนินการกับ 1 อุปกรณ์สำหรับคำขอ API แต่ละรายการ ชื่อเมธอดแบบอะซิงโครนัสจะมีส่วนต่อท้าย Async เช่น claimAsync
เมธอด API แบบอะซิงโครนัสจะแสดงผลลัพธ์ก่อนที่การประมวลผลจะเสร็จสมบูรณ์ นอกจากนี้ วิธีการแบบไม่พร้อมกันยังช่วยให้แอป (หรือเครื่องมือ) ของคุณตอบสนองต่อผู้ใช้ได้อยู่เสมอขณะที่ผู้ใช้รอการดำเนินการที่ใช้เวลานานให้เสร็จสมบูรณ์ แอปของคุณควรตรวจสอบสถานะการดำเนินการเป็นระยะๆ
การดำเนินการ
คุณใช้ Operation
เพื่อติดตามการดำเนินการแบบกลุ่มที่ใช้เวลานาน ต
การเรียกเมธอดแบบไม่พร้อมกันสำเร็จจะส่งคืนการอ้างอิงไปยังการดำเนินการ
ในการตอบกลับ ข้อมูลโค้ด JSON ด้านล่างแสดงการตอบสนองทั่วไปหลังจากการเรียกใช้
updateMetadataAsync
:
{
"name": "operations/apibatchoperation/1234567890123476789"
}
การดำเนินการแต่ละรายการจะมีรายการงานแต่ละรายการ โทร
operations.get
เพื่อดูข้อมูลเกี่ยวกับสถานะและ
ผลของงานที่มีอยู่ในการดำเนินการนี้ ข้อมูลโค้ดด้านล่างแสดงวิธีดำเนินการ คุณจะต้องจัดการข้อผิดพลาดในแอปของคุณเอง
Java
// Build out the request body to apply the same order number to a customer's // purchase of 2 devices. UpdateMetadataArguments firstUpdate = new UpdateMetadataArguments(); firstUpdate.setDeviceMetadata(metadata); firstUpdate.setDeviceId(firstTargetDeviceId); UpdateMetadataArguments secondUpdate = new UpdateMetadataArguments(); secondUpdate.setDeviceMetadata(metadata); secondUpdate.setDeviceId(firstTargetDeviceId); // Start the device metadata update. UpdateDeviceMetadataInBatchRequest body = new UpdateDeviceMetadataInBatchRequest(); body.setUpdates(Arrays.asList(firstUpdate, secondUpdate)); Operation response = service .partners() .devices() .updateMetadataAsync(PARTNER_ID, body) .execute(); // Assume the metadata update started, so get the Operation for the update. Operation operation = service.operations().get(response.getName()).execute();
.NET
// Build out the request body to apply the same order number to a customer's // purchase of 2 devices. var updates = new List<UpdateMetadataArguments> { new UpdateMetadataArguments { DeviceMetadata = metadata, DeviceId = firstTargetDeviceId }, new UpdateMetadataArguments { DeviceMetadata = metadata, DeviceId = secondTargetDeviceId } }; // Start the device metadata update. UpdateDeviceMetadataInBatchRequest body = new UpdateDeviceMetadataInBatchRequest { Updates = updates }; var response = service.Partners.Devices.UpdateMetadataAsync(body, PartnerId).Execute(); // Assume the metadata update started, so get the Operation for the update. Operation operation = service.Operations.Get(response.Name).Execute();
Python
# Build out the request body to apply the same order number to a customer's # purchase of 2 devices. updates = [{'deviceMetadata':metadata,'deviceId':first_target_device_id}, {'deviceMetadata':metadata,'deviceId':second_target_device_id}] # Start the device metadata update. response = service.partners().devices().updateMetadataAsync( partnerId=PARTNER_ID, body={'updates':updates}).execute() # Assume the metadata update started, so get the Operation for the update. operation = service.operations().get(name=response['name']).execute()
หากต้องการทราบว่าการดำเนินการเสร็จสิ้นแล้วหรือไม่ ให้ตรวจสอบการดำเนินการสำหรับช่อง done
ด้วยค่า true
หากไม่มี done
หรือ false
แสดงว่าการดำเนินการยังดำเนินอยู่
การตอบกลับ
หลังจากการดำเนินการเสร็จสิ้น API จะอัปเดตการดำเนินการพร้อมผลลัพธ์ แม้ว่างานแต่ละรายการจะสำเร็จหรือไม่สำเร็จก็ตาม ฟิลด์ response
คือ
DevicesLongRunningOperationResponse
ที่มีรายละเอียดการประมวลผลของอุปกรณ์แต่ละเครื่องในการทำงาน
ตรวจสอบช่อง successCount
เพื่อดูว่ามีการดำเนินการใดที่ล้มเหลวหรือไม่อย่างมีประสิทธิภาพ
หลีกเลี่ยงการทำซ้ำผ่านรายการผลการค้นหาจำนวนมาก ฟิลด์ perDeviceStatus
ของ
DevicesLongRunningOperationResponse
เป็นรายการของ
อินสแตนซ์ OperationPerDevice
ที่แสดงรายละเอียดอุปกรณ์แต่ละเครื่องใน
การดำเนินการ ลําดับรายการตรงกับงานในคําขอต้นฉบับ
งาน OperationPerDevice
แต่ละรายการจะมีช่อง result
และสรุปการช่วยเตือนของคำขอที่ได้รับจากเซิร์ฟเวอร์ ตรวจสอบว่างานสำเร็จหรือล้มเหลว
โดยใช้ช่อง result
ข้อมูลโค้ด JSON ด้านล่างแสดงการตอบกลับทั่วไปบางส่วนจากการดำเนินการหลังจากการเรียก updateMetadataAsync
"response": {
"perDeviceStatus": [
{
"result": {
"deviceId": "12345678901234567",
"status": "SINGLE_DEVICE_STATUS_SUCCESS"
},
"updateMetadata": {
"deviceId": "12345678901234567",
"deviceMetadata": {
"entries": {
"phonenumber": "+1 (800) 555-0100"
}
}
}
}
],
"successCount": 1
}
ติดตามความคืบหน้า
หากแอปของคุณต้องการติดตามความคืบหน้า คุณควรดึงข้อมูล
การดำเนินการ ฟิลด์ metadata
มีตัวอย่าง DevicesLongRunningOperationMetadata
เพื่อช่วยแอปตรวจสอบความคืบหน้าล่าสุดของการดำเนินการที่ทำงานอยู่ ใช้
ช่องของ DevicesLongRunningOperationMetadata
ที่แสดงในรายการต่อไปนี้
สำหรับติดตามความคืบหน้าของการดำเนินการ
ช่อง | การใช้งานทั่วไป |
---|---|
processingStatus
|
การเปลี่ยนแปลงจาก BATCH_PROCESS_PENDING เป็น
BATCH_PROCESS_IN_PROGRESS จากนั้นไปยัง
BATCH_PROCESS_PROCESSED เมื่อการดำเนินการดำเนินอยู่ |
progress
|
เปอร์เซ็นต์ของการอัปเดตที่ประมวลผล แอปของคุณสามารถใช้ข้อมูลนี้เพื่อประมาณเวลาสิ้นสุด เนื่องจากprogress
ค่าเป็น 100 ได้ขณะดําเนินการเสร็จสิ้น
ตรวจสอบฟิลด์ done ของการดำเนินการเพื่อดูว่า
เสร็จสิ้นแล้วและมีผลลัพธ์ |
devicesCount
|
แสดงจํานวนการอัปเดตในการดำเนินการ ซึ่งอาจแตกต่างจากจํานวนการอัปเดตในคําขอหาก API ไม่สามารถแยกวิเคราะห์การอัปเดตบางอย่างได้ |
ตัวอย่างที่เข้าใจง่ายด้านล่างแสดงวิธีที่แอปอาจใช้ข้อมูลเมตาความคืบหน้าเพื่อกำหนดช่วงเวลาการโหวต คุณอาจต้องทำงานที่ซับซ้อนขึ้นในแอป สำหรับ แบบสำรวจความคิดเห็น คุณยังต้องเพิ่มการจัดการข้อผิดพลาดด้วย
Java
// Milliseconds between polling the API. private static long MIN_INTERVAL = 2000; private static long MAX_INTERVAL = 10000; // ... // Start the device metadata update. Operation response = service .partners() .devices() .updateMetadataAsync(PARTNER_ID, body) .execute(); String operationName = response.getName(); // Start polling for completion. long startTime = new Date().getTime(); while (true) { // Get the latest update on the operation's progress using the API. Operation operation = service.operations().get(operationName).execute(); if (operation.get("done") != null && operation.getDone()) { // The operation is finished. Print the status. System.out.format("Operation complete: %s of %s successful device updates\n", operation.getResponse().get("successCount"), operation.getMetadata().get("devicesCount")); break; } else { // Estimate how long the operation *should* take - within min and max value. BigDecimal opProgress = (BigDecimal) operation.getMetadata().get("progress"); double progress = opProgress.longValue(); long interval = MAX_INTERVAL; if (progress > 0) { interval = (long) ((new Date().getTime() - startTime) * ((100.0 - progress) / progress)); } interval = Math.max(MIN_INTERVAL, Math.min(interval, MAX_INTERVAL)); // Sleep until the operation should be complete. Thread.sleep(interval); } }
.NET
// Milliseconds between polling the API. private static double MinInterval = 2000; private static double MaxInterval = 10000; // ... // Start the device metadata update. var response = service.Partners.Devices.UpdateMetadataAsync(body, PartnerId).Execute(); var operationName = response.Name; // Start polling for completion. var startTime = DateTime.Now; while (true) { // Get the latest update on the operation's progress using the API. Operation operation = service.Operations.Get(operationName).Execute(); if (operation.Done == true) { // The operation is finished. Print the status. Console.WriteLine("Operation complete: {0} of {1} successful device updates", operation.Response["successCount"], operation.Metadata["devicesCount"]); break; } else { // Estimate how long the operation *should* take - within min and max value. double progress = (double)(long)operation.Metadata["progress"]; double interval = MaxInterval; if (progress > 0) { interval = DateTime.Now.Subtract(startTime).TotalMilliseconds * ((100.0 - progress) / progress); } interval = Math.Max(MinInterval, Math.Min(interval, MaxInterval)); // Sleep until the operation should be complete. System.Threading.Thread.Sleep((int)interval); } }
Python
# Seconds between polling the API. MIN_INTERVAL = 2; MAX_INTERVAL = 10; # ... # Start the device metadata update response = service.partners().devices().updateMetadataAsync( partnerId=PARTNER_ID, body={'updates':updates}).execute() op_name = response['name'] start_time = time.time() # Start polling for completion while True: # Get the latest update on the operation's progress using the API op = service.operations().get(name=op_name).execute() if 'done' in op and op['done']: # The operation is finished. Print the status. print('Operation complete: {0} of {1} successful device updates'.format( op['response']['successCount'], op['metadata']['devicesCount'] )) break else: # Estimate how long the operation *should* take - within min and max. progress = op['metadata']['progress'] interval = MIN_INTERVAL if progress > 0: interval = (time.time() - start_time) * ((100.0 - progress) / progress) interval = max(MIN_INTERVAL, min(interval, MAX_INTERVAL)) # Sleep until the operation should be complete. time.sleep(interval)
เลือกวิธีการสำรวจที่เหมาะกับผู้ใช้แอป ผู้ใช้แอปบางราย อาจได้ประโยชน์จากการอัปเดตความคืบหน้าเป็นประจำ หากพวกเขากำลังรอให้กระบวนการ เสร็จสมบูรณ์
ผลลัพธ์แบ่งหน้า
เมธอด partners.devices.findByOwner
API อาจแสดงรายการอุปกรณ์จํานวนมาก เพื่อลดขนาดการตอบกลับ เมธอดนี้และเมธอด API อื่นๆ (เช่น partners.devices.findByIdentifier
) รองรับผลการค้นหาแบบแบ่งหน้า เมื่อใช้ผลการค้นหาแบบแบ่งหน้า แอปพลิเคชันจะขอและประมวลผลรายการขนาดใหญ่ทีละหน้าได้ซ้ำๆ
หลังจากเรียกใช้เมธอด API แล้ว ให้ตรวจสอบว่าคำตอบมีค่าสำหรับ nextPageToken
หรือไม่ หาก nextPageToken
ไม่ใช่ null
แอปของคุณสามารถใช้คำสั่งเพื่อดึงข้อมูลหน้าอื่นของอุปกรณ์ด้วยการโทร
เมธอดอีกครั้ง คุณต้องกำหนดขีดจำกัดสูงสุดสำหรับจำนวนอุปกรณ์ใน
พารามิเตอร์ limit
หาก nextPageToken
คือ null
แสดงว่าแอปของคุณได้ขอ
หน้าสุดท้าย
ตัวอย่างเมธอดด้านล่างแสดงวิธีที่แอปอาจพิมพ์รายการอุปกรณ์ทีละหน้า
Java
private static long MAX_PAGE_SIZE = 10; // ... /** * Demonstrates how to loop through paginated lists of devices. * @param pageToken The token specifying which result page to return. * @throws IOException If the zero-touch API call fails. */ private void printDevices(String pageToken) throws IOException { // Create the request body to find the customer's devices. FindDevicesByOwnerRequest body = new FindDevicesByOwnerRequest(); body.setLimit(MAX_PAGE_SIZE); body.setSectionType("SECTION_TYPE_ZERO_TOUCH"); body.setCustomerId(Collections.singletonList(targetCustomerId)); // Call the API to get a page of Devices. Send a page token from the method // argument (might be None). If the page token is None, the API returns the first page. FindDevicesByOwnerResponse response = service.partners().devices().findByOwner(PARTNER_ID, body).execute(); if (response.getDevices() == null) { return; } // 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 and print the devices. if (response.getNextPageToken() != null) { this.printDevices(response.getNextPageToken()); } } // ... // Pass null to start printing the first page of devices. printDevices(null);
.NET
private static int MaxPageSize = 10; // ... /// <summary>Demonstrates how to loop through paginated lists of devices.</summary> /// <param name="pageToken">The token specifying which result page to return.</param> private void PrintDevices(string pageToken) { // Create the request body to find the customer's devices. FindDevicesByOwnerRequest body = new FindDevicesByOwnerRequest { PageToken = pageToken, Limit = MaxPageSize, SectionType = "SECTION_TYPE_ZERO_TOUCH", CustomerId = new List<long?> { targetCustomerId } }; // Call the API to get a page of Devices. Send a page token from the method // argument (might be None). If the page token is None, the API returns the first page. var response = service.Partners.Devices.FindByOwner(body, PartnerId).Execute(); if (response.Devices == null) { return; } // 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(response.NextPageToken); } } // ... // Pass null to start printing the first page of devices. PrintDevices(null);
Python
MAX_PAGE_SIZE = 10; # ... def print_devices(page_token): """Demonstrates how to loop through paginated lists of devices. Args: page_token: The token specifying which result page to return. """ # Create the body to find the customer's devices. request_body = {'limit':MAX_PAGE_SIZE, \ 'pageToken':page_token, \ 'customerId':[target_customer_id], \ 'sectionType':'SECTION_TYPE_ZERO_TOUCH'} # Call the API to get a page of Devices. Send a page token from the method # argument (might be None). If the page token is None, # the API returns the first page. response = service.partners().devices().findByOwner(partnerId=PARTNER_ID, body=request_body).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(response['nextPageToken']) # ... # Pass None to start printing the first page of devices. print_devices(None);
ขั้นตอนถัดไป
เมื่อทราบวิธีการทำงานของ API แล้ว ก็ให้ลองดูตัวอย่างด้วยการเริ่มต้นอย่างรวดเร็วสำหรับ Java .NET หรือ Python คุณสามารถใช้ Colab เพื่อดู ตัวอย่างการเรียก API และการทดสอบการเรียก API ด้วยตัวเอง