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

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

คุณต้องระบุอีเมลของบริษัทอย่างน้อย 1 รายการซึ่งเชื่อมโยงกับ บัญชี Google ที่จะเป็นเจ้าของ คุณใช้บัญชี Gmail ส่วนบุคคลกับ API ไม่ได้ หากลูกค้าต้องการความช่วยเหลือในการเชื่อมโยงบัญชี ให้ส่ง คำสั่งจาก เชื่อมโยงบัญชี Google

หลังจากที่คุณสร้างลูกค้าด้วยการเรียกใช้ API ลูกค้าจะจัดการพนักงานของตน สิทธิ์การเข้าถึงพอร์ทัล — คุณไม่สามารถแก้ไขลูกค้าของคุณได้ ผู้ใช้ที่ใช้ API ข้อมูลโค้ดด้านล่างแสดงวิธีที่คุณอาจสร้างลูกค้า

Java.NETPython

// 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();

// 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();

# 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.NETPython

// 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();

// 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();

# 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.NETPython

// 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());
    }
  }
}

// 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);
        }
    }
}

# 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.NETPython

// 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;
    }
  }
}

// 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;
        }
    }
}

# 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.NETPython

// 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();

// 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();

# 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.NETPython

// 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);
  }
}

// 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);
    }
}

# 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.NETPython

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);

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);

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 ด้วยตัวเอง