طريقة العمل

تمنح customer API إمكانية التحكّم الآلي في الأجهزة إعدادات برنامج "إعداد الأجهزة الجوّالة للمؤسّسات دفعةً واحدة" على Android يعرِض هذا المستند واجهة برمجة التطبيقات (API) لموفّري إدارة الخدمات الجوّالة للمؤسسات (EMM) ومطوّري تكنولوجيا المعلومات (IT) في المؤسسات. بعد قراءة هذا المستند، ينبغي أن تفهم المبادئ الموارد المستخدمة في واجهة برمجة التطبيقات وكيفية تفاعلها. إذا كنت مبتدئًا في برنامج "إعداد الأجهزة الجوّالة للمؤسسات دفعةً واحدة" التسجيل، فاقرأ android.com القصير المقدمة.

نظرة عامة

تساعد واجهة برمجة تطبيقات العميل المؤسسات التي تشتري برنامج "إعداد الأجهزة الجوّالة للمؤسّسات دفعةً واحدة" على Android الأجهزة. يمكن أن يساعد التطبيق أو الأداة مشرفي تكنولوجيا المعلومات في تنفيذ ما يلي:

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

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

في ما يلي المستخدمين العاديين لواجهة برمجة التطبيقات هذه:

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

المراجع الأساسية

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

الإعداد

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

الجهاز

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

DPC

إشارة للقراءة فقط إلى وحدة التحكّم بسياسة الجهاز لإدارة الخدمات الجوّالة للمؤسسات (سياسة الجهاز) وحدة التحكّم بالبيانات). إضافة وحدة التحكّم بسياسة الجهاز (DPC) إلى أحد الإعدادات لاختيار حلّ إدارة الخدمات الجوّالة للمؤسسات (EMM) للأجهزة. جميع وحدات التحكّم بسياسة الجهاز (DPC) المُدرَجة من خلال واجهة برمجة التطبيقات التي تتيح إعداد الأجهزة الجوّالة للمؤسّسات دفعةً واحدة وتتوفّر في Google Play إلى لمزيد من المعلومات، يُرجى الاطّلاع على Dpc.

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

الإعدادات

يجمع مورد واجهة برمجة التطبيقات Configuration بين التالي:

• تثبيت وحدة التحكّم بسياسة الجهاز لإدارة الخدمات الجوّالة للمؤسسات على الأجهزة
• يتم فرض سياسات إدارة الخدمات الجوّالة للمؤسسات (EMM) على الأجهزة.
• معلومات جهات الاتصال المعروضة على الجهاز لمساعدة المستخدمين أثناء الإعداد.

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

// Add metadata to help the device user during provisioning.
Configuration configuration = new Configuration();
configuration.setConfigurationName("Sales team");
configuration.setCompanyName("XYZ Corp.");
configuration.setContactEmail("it-support@example.com");
configuration.setContactPhone("+1 (800) 555-0112");
configuration.setCustomMessage("We're setting up your phone. Call or email for help.");

// Set the DPC that zero-touch enrollment downloads and installs from Google Play.
configuration.setDpcResourcePath(dpc.getName());

// Set the JSON-formatted EMM provisioning extras that are passed to the DPC.
configuration.setDpcExtras("{"
      + "\"android.app.extra.PROVISIONING_LEAVE_ALL_SYSTEM_APPS_ENABLED\":true,"
      + "\"android.app.extra.PROVISIONING_ADMIN_EXTRAS_BUNDLE\":{"
      + "\"default_min_password_length\":6,"
      + "\"company_name\":\"XYZ Corp\","
      + "\"management_server\":\"emm.example.com\","
      + "\"terms_url\":\"https://www.example.com/policies/terms/\","
      + "\"allowed_user_domains\":\"[\\\"example.com\\\", \\\"example.org\\\"]\""
      + "}"
      + "}");

// Create the new configuration on the server.
AndroidProvisioningPartner.Customers.Configurations.Create request =
      service.customers().configurations().create(customerAccount, configuration);
Configuration response = request.execute();

// Add metadata to help the device user during provisioning.
Configuration configuration = new Configuration
{
    ConfigurationName = "Sales team",
    CompanyName = "XYZ Corp.",
    ContactEmail = "it-support@example.com",
    ContactPhone = "+1 (800) 555-0112",
    CustomMessage = "We're setting up your phone. Call or email for help."
};

// Set the DPC that zero-touch enrollment downloads and installs from Google Play.
configuration.DpcResourcePath = dpc.Name;

// Set the JSON-formatted EMM provisioning extras that are passed to the DPC.
configuration.DpcExtras = @"{
    ""android.app.extra.PROVISIONING_LEAVE_ALL_SYSTEM_APPS_ENABLED"":true,
    ""android.app.extra.PROVISIONING_ADMIN_EXTRAS_BUNDLE"":{
    ""default_min_password_length"":6,
    ""company_name"":""XYZ Corp"",
    ""management_server"":""emm.example.com"",
    ""terms_url"":""https://www.example.com/policies/terms/"",
    ""allowed_user_domains"":""[\""example.com\"", \""example.org\""]""
  }
}";

// Create the new configuration on the server.
var request = service.Customers.Configurations.Create(configuration, customerAccount);
var response = request.Execute();

# Add metadata to help the device user during provisioning.
configuration = {
    'configurationName': 'Sales team',
    'companyName': 'XYZ Corp.',
    'contactEmail': 'it-support@example.com',
    'contactPhone': '+1 (800) 555-0112',
    'customMessage': 'We\'re setting up your phone. Call or email for help.'}

# Set the DPC that zero-touch enrollment installs from Google Play.
configuration['dpcResourcePath'] = dpc['name']

# Set the JSON-formatted EMM provisioning extras that are passed to the DPC.
configuration['dpcExtras'] = '''{
    "android.app.extra.PROVISIONING_LEAVE_ALL_SYSTEM_APPS_ENABLED":true,
    "android.app.extra.PROVISIONING_ADMIN_EXTRAS_BUNDLE":{
      "default_min_password_length":6,
      "company_name":"XYZ Corp",
      "management_server":"emm.example.com",
      "terms_url":"https://www.example.com/policies/terms/",
      "allowed_user_domains":"[\\"example.com\\", \\"example.org\\"]"}
}'''

# Create the new configuration on the server.
response = service.customers().configurations().create(
    parent=customer_account, body=configuration).execute()

عند تعديل أحد الإعدادات باستخدام واجهة برمجة التطبيقات patch API، تذكَّر تضمين قناع الحقل أو قيمة لكل حقل لا تريد أن يكون null. انظر تلقائي الإعدادات (أدناه) للاطّلاع على مثال يوضح كيفية لتحديث أحد التكوينات بكفاءة.

حذف الإعدادات

لا يمكنك حذف إعداد إذا كان لا يزال مطبّقًا على الأجهزة. إذا حاولت حذف إعدادات قيد الاستخدام، ستعرض طريقة واجهة برمجة التطبيقات رمز 400 Bad Request HTTP رمز الحالة ورسالة توضح عدد الأجهزة التي تستخدم التهيئة. اتصل customers.devices.removeConfiguration إزالة الإعدادات من الأجهزة قبل إعادة المحاولة.

الإعدادات التلقائية

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

// Send minimal data with the request. Just the 2 required fields.
// targetConfiguration is an existing configuration that we want to make the default.
Configuration configuration = new Configuration();
configuration.setIsDefault(true);
configuration.setConfigurationId(targetConfiguration.getConfigurationId());

// Call the API, including the FieldMask to avoid setting other fields to null.
AndroidProvisioningPartner.Customers.Configurations.Patch request = service
      .customers()
      .configurations()
      .patch(targetConfiguration.getName(), configuration);
request.setUpdateMask("isDefault");
Configuration results = request.execute();

// Send minimal data with the request. Just the 2 required fields.
// targetConfiguration is an existing configuration that we want to make the default.
Configuration configuration = new Configuration
{
    IsDefault = true,
    ConfigurationId = targetConfiguration.ConfigurationId,
};

// Call the API, including the FieldMask to avoid setting other fields to null.
var request = service.Customers.Configurations.Patch(configuration,
                                                     targetConfiguration.Name);
request.UpdateMask = "IsDefault";
Configuration results = request.Execute();

# Send minimal data with the request. Just the 2 required fields.
# target_configuration is an existing configuration we'll make the default.
configuration = {
    'isDefault': True,
    'configurationId': target_configuration['configurationId']}

# Call the API, including the FieldMask to avoid setting other fields to null.
response = service.customers().configurations().patch(
    name=target_configuration['name'],
    body=configuration, updateMask='isDefault').execute()

يمكن أن يكون هناك ضبط تلقائي واحد فقط. إن إجراء تهيئة افتراضية جديدة، تضبط الحقل isDefault في الإعدادات السابقة على false. قد تحتاج إلى إعادة تحميل أي مثيلات Configuration مخزّنة مؤقتًا للاطّلاع على القيم الصحيحة في حقلان (isDefault)

توجيه مستخدمي الأجهزة

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

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

الأجهزة

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

إعداد الأجهزة

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

List<Device> devices = getDevicesToConfigure(service);
Configuration configurationToApply = getConfigurationToApply(service);

// Loop through the collection and apply the configuration to each device. This might
// take some time if the collection contains many devices.
for (Device device : devices) {
    System.out.println(device.getDeviceIdentifier().getImei());

    // Wrap the device ID in a DeviceReference.
    DeviceReference deviceRef = new DeviceReference();
    deviceRef.setDeviceId(device.getDeviceId());

    // Build and send the request to the API.
    CustomerApplyConfigurationRequest body = new CustomerApplyConfigurationRequest();
    body.setConfiguration(configurationToApply.getName());
    body.setDevice(deviceRef);

    AndroidProvisioningPartner.Customers.Devices.ApplyConfiguration request = service
          .customers()
          .devices()
          .applyConfiguration(customerAccount, body);
    request.execute();
}

IList<Device> devices = GetDevicesToConfigure(service);
Configuration configurationToApply = GetConfigurationToApply(service);

// Loop through the collection and apply the configuration to each device. This might
// take some time if the collection contains many devices.
foreach (Device device in devices)
{
    Console.WriteLine(device.DeviceIdentifier.Imei);

    // Wrap the device ID in a DeviceReference.
    var deviceRef = new DeviceReference
    {
        DeviceId = device.DeviceId
    };

    // Build and send the request to the API.
    CustomerApplyConfigurationRequest body = new CustomerApplyConfigurationRequest
    {
        Configuration = configurationToApply.Name,
        Device = deviceRef
    };
    var request = service.Customers.Devices.ApplyConfiguration(body,
                                                               customerAccount);
    request.Execute();
}

devices = get_devices_to_configure(service)
configuration = get_configuration_to_apply(service)

# Loop through the collection and apply the configuration to each device.
# This might take some time if the collection contains many devices.
for device in devices:
  print(device['deviceIdentifier']['imei'])

  # Wrap the device ID in a DeviceReference.
  device_ref = {'deviceId': device['deviceId']}

  # Build and send the request to the API.
  body = {'configuration': configuration['name'], 'device': device_ref}
  service.customers().devices().applyConfiguration(
      parent=customer_account, body=body).execute()

لإزالة الإعدادات من جهاز، اتصِل customers.devices.removeConfiguration يتم تطبيق هذا التغيير بعد إعادة ضبط الجهاز على الإعدادات الأصلية.

إلغاء طلب الأجهزة

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

يوضح المثال أدناه كيفية إلغاء المطالبة بجهاز من رقم IMEI اسم الشركة المصنعة:

// Wrap the hardware ID and manufacturer values in a DeviceIdentifier.
// Then wrap the DeviceIdentifier in a DeviceReference.
DeviceIdentifier identifier = new DeviceIdentifier();
identifier.setImei("123456789012347");
identifier.setManufacturer("Google");
DeviceReference reference = new DeviceReference();
reference.setDeviceIdentifier(identifier);

// Create the body of the request.
CustomerUnclaimDeviceRequest body = new CustomerUnclaimDeviceRequest();
body.setDevice(reference);

// Call the API method to unclaim the device from the organization.
service.customers().devices().unclaim(customerAccount, body).execute();

// Wrap the hardware ID and manufacturer values in a DeviceIdentifier.
// Then wrap the DeviceIdentifier in a DeviceReference.
DeviceIdentifier identifier = new DeviceIdentifier
{
    Imei = "123456789012347",
    Manufacturer = "Google"
};
DeviceReference reference = new DeviceReference();
reference.DeviceIdentifier = identifier;

// Create the body of the request.
CustomerUnclaimDeviceRequest body = new CustomerUnclaimDeviceRequest();
body.Device = reference;

// Call the API method to unclaim the device from the organization.
service.Customers.Devices.Unclaim(body, customerAccount).Execute();

# Wrap the hardware ID and manufacturer values in a DeviceIdentifier.
# Then wrap the DeviceIdentifier in a DeviceReference.
identifier = {'imei': '123456789012347', 'manufacturer': 'Google'}
reference = {'deviceIdentifier': identifier}

# Create the body of the request.
body = {'device': reference}

# Call the API method to unclaim the device from the organization.
service.customers().devices().unclaim(
    parent=customer_account, body=body).execute()

البيانات الوصفية للجهاز

يمكن لمشرف تكنولوجيا المعلومات الاطّلاع على البيانات الوصفية التي أرفقها المورِّد بالجهاز. الشبكة الإعلانية البيانات الوصفية لهذا الجهاز في تطبيقك لمساعدة مشرفي تكنولوجيا المعلومات في التعرّف على الأجهزة.

لمعرفة المزيد من المعلومات حول البيانات الوصفية التي قد تظهر لك، يمكنك قراءة مقالة الجهاز دليل البيانات الوصفية للمورّدين.

النتائج المقسّمة إلى صفحات

قد يتم عرض طريقة واجهة برمجة التطبيقات customers.devices.list قوائم كبيرة جدًا من الأجهزة. لتقليل حجم الاستجابة، يمكن لواجهة برمجة التطبيقات هذه (مثل customers.list) تتوافق مع النتائج المقسّمة إلى صفحات. مع نتائج مُقسَّمة إلى صفحات، يمكن لتطبيقك طلب قوائم كبيرة ومعالجتها بشكل متكرر صفحة واحدة في كل مرة.

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

يوضّح مثال الطريقة أدناه كيفية طباعة تطبيقك لقائمة بالأجهزة، صفحة واحدة في كل مرة:

private void printDevices(AndroidProvisioningPartner service, String customerAccount,
      String pageToken) throws IOException {

    // Call the API to get a page of Devices. Send a page token from the method argument.
    // If the page token is null, the API returns the first page.
    AndroidProvisioningPartner.Customers.Devices.List request =
          service.customers().devices().list(customerAccount);
    request.setPageSize(50L);
    request.setPageToken(pageToken);
    CustomerListDevicesResponse response = request.execute();

    // 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 & print the devices.
    if (response.getNextPageToken() != null) {
        this.printDevices(service, customerAccount, response.getNextPageToken());
    }
}

private void PrintDevices(AndroidProvisioningPartnerService service, String customerAccount,
                          String pageToken)
{
    // Call the API to get a page of Devices. Send a page token from the method argument.
    // If the page token is null, the API returns the first page.
    var request = service.Customers.Devices.List(customerAccount);
    request.PageSize = 50;
    request.PageToken = pageToken;
    var response = request.Execute();

    // 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(service, customerAccount, response.NextPageToken);
    }
}

def print_devices(service, customer_account, page_token):
  """Demonstrates how to loop through paginated lists of devices."""

  # Call the API to get a page of Devices. Send a page token from the method
  # argument. If the page token is None, the API returns the first page.
  response = service.customers().devices().list(
      parent=customer_account, pageSize=50, pageToken=page_token).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(service, customer_account, response['nextPageToken'])

البدء

بعد ذلك، يمكنك الاطِّلاع على كيفية تفويض طلبات بيانات من واجهة برمجة التطبيقات في التفويض. إذا كنت ترغب في واستكشاف واجهات برمجة التطبيقات، ألقِ نظرة على أدلة البدء السريع Java .NET Python يمكنك استخدام colab لعرض أمثلة على طلبات بيانات من واجهة برمجة التطبيقات وتجربة طلب واجهة برمجة التطبيقات بنفسك.