طريقة العمل

مقدمة

تساعد واجهة برمجة التطبيقات لعملية "إعداد الأجهزة الجوّالة للمؤسّسات دفعةً واحدة" مورّدي الأجهزة على برمجة عمليات الدمج. يمكن لأدوات المبيعات في مؤسستك تضمين برنامج "إعداد الأجهزة الجوّالة للمؤسّسات دفعةً واحدة"، ما يجعل والمستخدمين، وعملائك، أكثر إنتاجية. استخدِم واجهة برمجة التطبيقات لمساعدة المستخدمين في ما يلي:

• تعيين الأجهزة التي تم شراؤها إلى حساب العميل المخصّص لعملية "إعداد الأجهزة الجوّالة للمؤسّسات دفعةً واحدة".
• إنشاء حساب عميلك على "إعداد الأجهزة الجوّالة للمؤسّسات دفعةً واحدة"
• يمكنك توصيل رقم هاتف مؤسستك وبيانات الطلب الوصفية بالأجهزة.
• إنشاء تقارير عن الأجهزة المخصّصة لعملائك

يقدم هذا المستند واجهة برمجة التطبيقات ويشرح الأنماط. إذا كنت ترغب في استكشاف واجهة برمجة التطبيقات بنفسك، وتجربة التشغيل السريع Java .NET أو Python

مفاهيم واجهة برمجة التطبيقات

يشكّل العملاء والأجهزة الموارد الأساسية التي تستخدمها في واجهة برمجة التطبيقات. لإنشاء العملاء، اتصل برقم create. يمكنك إنشاء أجهزة باستخدام طرق واجهة برمجة التطبيقات للمطالبة (انظر أدناه) يمكن لمؤسستك أيضًا إنشاء عملاء وأجهزة باستخدام بوابة برنامج "إعداد الأجهزة الجوّالة للمؤسسات دفعةً واحدة".

العميل

الشركات التي تبيع لها مؤسستك الأجهزة. لدى العملاء name. وID. استخدِم العميل عندما تريد المطالبة بأجهزته أو العثور عليها. إلى لمزيد من المعلومات، يُرجى الاطّلاع على Customer.

الجهاز

جهاز Android أو ChromeOS لمؤسستك يتيح إعداد الأجهزة الجوّالة للمؤسّسات دفعةً واحدة يبيعها للعميل. تشتمل الأجهزة على معرّفات الأجهزة وبيانات وصفية المطالبات. تشكّل الأجهزة عنصرًا أساسيًا في واجهة برمجة التطبيقات، وبالتالي يمكنك استخدامها في جميع الطرق. لمزيد من المعلومات، يُرجى الاطّلاع على Device.

معرّف الجهاز

يتضمن هذا الحقل معرّفات الأجهزة، مثل IMEI أو MEID، لتحديد الشركة المصنّعة. الخاص بك. استخدام DeviceIdentifier لاستهداف الجهاز التي تريد العثور عليها أو تعديلها أو المطالبة بها لمزيد من المعلومات، يُرجى قراءة المعرّفات:

DeviceMetadata

تخزين أزواج المفتاح/القيمة من البيانات الوصفية للجهاز استخدام DeviceMetadata لتخزين البيانات الوصفية لمؤسستك. إلى للتعرّف على مزيد من المعلومات، يُرجى الاطّلاع على البيانات الوصفية للجهاز.

للاطّلاع على جميع طرق واجهة برمجة التطبيقات والموارد التي يمكن لتطبيقك استخدامها، يُرجى الاطّلاع على مرجع واجهة برمجة التطبيقات.

إنشاء عملاء

بالنسبة إلى أجهزة Android، يتحمّل المورِّد مسؤولية إنشاء حساب بالنيابة عن العميل. سيستخدم العميل هذا الحساب من أجل الوصول إلى بوابة برنامج "إعداد الأجهزة الجوّالة للمؤسسات دفعةً واحدة" لضبط إعدادات توفير المتطلبات اللازمة الأجهزة. وهذا ليس ضروريًا لأجهزة ChromeOS التي تستخدم Google Workspace الذي سيتم استخدامه لضبط إعدادات توفير المتطلبات اللازمة

يمكنك استدعاء طريقة واجهة برمجة التطبيقات create لإنشاء حسابات العملاء لبرنامج "إعداد الأجهزة الجوّالة للمؤسّسات دفعةً واحدة". نظرًا لأن العملاء يرون اسم الشركة في بوابة برنامج "إعداد الأجهزة الجوّالة للمؤسسات دفعةً واحدة"، يجب على مستخدم التطبيق فتأكد من صحتها. لا يمكنك تعديل اسم العميل بعد إنشاء العميل.

يجب تضمين عنوان بريد إلكتروني واحد على الأقل للشركة، يكون مرتبطًا حساب Google، كمالك. لا يمكنك استخدام حسابات Gmail الشخصية مع واجهة برمجة التطبيقات. إذا كان العميل بحاجة إلى المساعدة في ربط الحساب، أرسِل تعليمات من ربط حساب Google

ملاحظة: تعرض واجهة برمجة التطبيقات رسالة خطأ إذا كان هناك عنوان واحد أو أكثر من عناوين البريد الإلكتروني غير صحيح. المرتبطة بحساب Google. عند حدوث ذلك، اطلب من المستخدم التحقّق من توفّر حساب Google لكل عنوان بريد إلكتروني. لا توفّر Google واجهة برمجة تطبيقات للتحقّق من الرسالة الإلكترونية مرتبط بحساب Google.

بعد إنشاء عميل من خلال طلب بيانات من واجهة برمجة التطبيقات، سيدير المشرف حسابات موظفيه الوصول إلى البوابة - لا يمكنك تعديل حسابات عملائك مستخدمي واجهة برمجة التطبيقات. المقتطف في ما يلي كيفية إنشاء عميل:

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("[e-mail]", "[e-mail]"));
customer.setAdminEmails(Collections.singletonList("[e-mail]"));

// 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[] { "[e-mail]", "[e-mail]" },
    AdminEmails = new String[] { "[e-mail]" }
};

// 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':['[e-mail]', '[e-mail]'], \
  'adminEmails':['[e-mail]']}

# 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 لسحب المطالبة الجهاز من العميل.

تنبيه: ننصحك بأن تطلب من مستخدم التطبيق التأكّد من حصوله على تصحيح الجهاز قبل استدعاء واجهات برمجة التطبيقات لإلغاء المطالبة. تؤدي عملية إلغاء المطالبة بملكية جهاز إلى إزالة إعداد إدارة حسابات العميل ويصبح الجهاز غير مُدار بعد المصنع إعادة الضبط.

المورّدون

يمكنك الاستعانة بالمورّدين لتمثيل شركاء الموردين في شبكة وكالات البيع أو أي منطقة محلية المشغلين داخل شبكة موردين عالمية أو أي مؤسسة تبيع الأجهزة نيابةً عنك. يساعدك الموردون في الفصل بين المستخدمين والعملاء الأجهزة:

• لا يمكن للمورّدين الذين تنشئهم الاطّلاع على حسابك على برنامج "إعداد الأجهزة الجوّالة للمؤسسات دفعةً واحدة" أو كل حسابات الآخرين.
• يمكنك الاطّلاع على عملاء المورّدين وأجهزتهم، ويمكنك إلغاء التسجيل. أجهزة البائعين. ومع ذلك، لا يمكنك تعيين أجهزة لمورديك الدائمين.

نقطة رئيسية: المورِّد هو نوع خاص من المورّدين. ظهور المورّدين وسلوكهم (في البوابة وواجهات برمجة التطبيقات) تمامًا كما يفعل المورّد، باستثناء أنّه لا يمكن للمورّد والمورّدين الآخرين

يمكنك استخدام البوابة من أجل إنشاء مورّدين من أجل المؤسسة — لا يمكنك استخدام واجهة برمجة التطبيقات. يجب أن يكون دور حسابك كما يلي: المالك لإنشاء مورّد جديد. إذا كانت مؤسستك تمتلك مورّدين، يمكنك الاتصال بـ partners.vendors.list لإدراج البائعين وpartners.vendors.customers.list لجذب عملاء البائع. يستخدم المثال التالي كلتا الطريقتين لطباعة تقرير يوضح حالة بنود الخدمة للمورّدين العملاء:

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 في سجلّ المطالبات الخاص بالجهاز

يمكن لمؤسستك إلغاء المطالبة بجهاز يطالب به المورّد. بالنسبة إلى طلبات البيانات من واجهة برمجة التطبيقات الأخرى التي تعديل الأجهزة، عليك التأكّد من أنّ مؤسستك طالبت بملكية الجهاز. قبل طلب طريقة واجهة برمجة التطبيقات. يوضّح المثال التالي كيفية إجراء ذلك:

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

عمليات مجمّعة طويلة الأمد

تتضمّن واجهة برمجة التطبيقات إصدارات غير متزامنة من طرق الأجهزة. وتسمح هذه الطرق بالمعالجة المجمّعة للعديد من الأجهزة بينما معالجة جهاز واحد لكل طلب بيانات من واجهة برمجة التطبيقات. أسماء الطرق غير المتزامنة اللاحقة غير متزامن، على سبيل المثال claimAsync.

تعرض طرق واجهة برمجة التطبيقات غير المتزامنة نتيجة قبل اكتمال المعالجة. كما تساعد الطرق غير المتزامنة أيضًا تطبيقك (أو الأداة) في الاستمرار في الاستجابة لطلبات مستخدمين أثناء انتظار اكتمال عملية طويلة الأمد. يجب أن التحقق من حالة العملية بشكل دوري.

العمليات

يمكنك استخدام 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، لا تزال العملية. الجري.

الردود

بعد انتهاء إحدى العمليات، تُحدِّث واجهة برمجة التطبيقات العملية بالنتيجة، حتى إذا كانت جميع المهام الفردية أو لم تكن أيًا من المهام الفردية ناجحة. الحقل 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": "[phone]"
          }
        }
      }
    }
  ],
  "successCount": 1
}

تتبُّع مستوى التقدّم

إذا احتاج تطبيقك إلى تتبع التقدم، يجب عليك إعادة جلب العملية. يحتوي الحقل metadata على DevicesLongRunningOperationMetadata لمساعدة التطبيق في التحقق من آخر تقدم في عملية جارية. استخدام حقول DevicesLongRunningOperationMetadata المدرجة في ما يلي لتتبع تقدم العملية:

الحقل	معدّل الاستخدام
processingStatus	التغييرات من BATCH_PROCESS_PENDING إلى BATCH_PROCESS_IN_PROGRESS، ثم إلى BATCH_PROCESS_PROCESSED أثناء تقدم العملية.
progress	النسبة المئوية للتحديثات التي تمت معالجتها. يمكن لتطبيقك استخدام لتقدير وقت الانتهاء. لأنّ progress يمكن أن تكون 100 أثناء انتهاء العملية، التحقّق من الحقل done في أي عملية لمعرفة ما إذا كانت الفريق ولديه نتيجة.
devicesCount	يعرض عدد التعديلات في العملية. هذا النمط عن عدد التحديثات في إذا لم تتمكّن واجهة برمجة التطبيقات من تحليل بعض التحديثات.

يوضح المثال المبسَّط أدناه كيف يمكن أن يستخدم أحد التطبيقات البيانات الوصفية الخاصة بالتقدم من أجل تعيين فواصل زمنية للاستقصاء. قد تحتاج إلى مهمة أكثر تعقيدًا في تطبيقك. ومتسابقًا للاقتراع. ستحتاج أيضًا إلى إضافة طريقة معالجة الأخطاء.

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 قوائم كبيرة جدًا من الأجهزة. لتقليل حجم الاستجابة، طرق واجهة برمجة التطبيقات الأخرى (مثل partners.devices.findByIdentifier) دعم النتائج المقسّمة إلى صفحات. وباستخدام النتائج المقسّمة إلى صفحات، يمكن لتطبيقك التكرار طلب ومعالجة القوائم الكبيرة لصفحة واحدة في كل مرة.

بعد استدعاء طريقة واجهة برمجة التطبيقات، تحقق مما إذا كان الرد يتضمن قيمة 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);

الخطوات التالية

والآن بعد أن عرفت كيفية عمل واجهة برمجة التطبيقات، جرّب الأمثلة مع أمثلة Java .NET أو Python