หน้านี้ได้รับการแปลโดย Cloud Translation API

วิธีการทำงาน

เกริ่นนำ

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 อยู่แล้ว ซึ่งจะใช้เพื่อกำหนดการตั้งค่าการจัดสรร

คุณสามารถเรียกใช้เมธอด API ของ create เพื่อสร้างบัญชีลูกค้าสำหรับการตั้งค่าอุปกรณ์พร้อมใช้แบบรวมกลุ่ม เนื่องจากลูกค้าจะเห็นชื่อบริษัทในพอร์ทัลการตั้งค่าอุปกรณ์พร้อมใช้แบบรวมกลุ่ม ผู้ใช้แอปจึงควรยืนยันว่าถูกต้อง หลังจากสร้างลูกค้าแล้ว คุณจะแก้ไขชื่อลูกค้าไม่ได้

คุณต้องใส่อีเมลของบริษัทอย่างน้อย 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 โดยมีลูกค้าเป็นอาร์กิวเมนต์ โปรดระบุ SECTION_TYPE_ZERO_TOUCH เป็นค่าสำหรับ sectionType เสมอ

คุณจะต้องถอนการอ้างสิทธิ์อุปกรณ์ของลูกค้า (ดูด้านล่าง) ก่อนจึงจะอ้างสิทธิ์อุปกรณ์เดียวกันนั้นให้กับลูกค้ารายอื่นได้ วิธีการอ้างสิทธิ์จะvalidateช่องต่างๆ ของ 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)

เลือกวิธีแบบสำรวจที่เหมาะกับผู้ใช้แอป ผู้ใช้แอปบางรายอาจได้ประโยชน์จากการอัปเดตความคืบหน้าอย่างสม่ำเสมอหากกำลังรอกระบวนการเสร็จสมบูรณ์

ผลลัพธ์แบบแบ่งหน้า

เมธอด API ของ partners.devices.findByOwner อาจแสดงรายการอุปกรณ์ขนาดใหญ่มาก หากต้องการลดขนาดการตอบกลับ วิธีนี้และเมธอด API อื่นๆ (เช่น partners.devices.findByIdentifier) จะรองรับผลการค้นหาแบบแบ่งหน้า เมื่อใช้ผลลัพธ์ที่แบ่งหน้า แอปพลิเคชันจะส่งคำขอและประมวลผลรายการขนาดใหญ่ได้ครั้งละ 1 หน้าเสมอ

หลังจากเรียกเมธอด 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