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

บทนำ

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

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