تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

طريقة العمل

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

نظرة عامة

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

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

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

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

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

الموارد الأساسية

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

العلاقة بمورد العميل والجهاز

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

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

الإعدادات

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

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

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

Java

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

NET.

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

Python

# 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()

عند تعديل إعدادات باستخدام واجهة برمجة تطبيقات التصحيح، لا تنسَ تضمين قناع الحقل، أو قيمة لكل حقل لا تريد إدراجه في null. راجِع عمليات الضبط التلقائية (أدناه) للاطّلاع على مثال يوضّح كيفية تعديل عملية ضبط بشكلٍ فعّال.

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

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

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

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

Java

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

NET.

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

Python

# 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. وبعد تطبيق الإعداد، سيُدير الجهاز نفسه تلقائيًا عند تشغيله للمرة الأولى أو عند إعادة الضبط على الإعدادات الأصلية. ويوضّح المثال أدناه كيفية تطبيق عملية ضبط على مجموعة من الأجهزة:

Java

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

NET.

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

Python

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 واسم الشركة المصنّعة:

Java

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

NET.

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

Python

# 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، يعني ذلك أنّ تطبيقك طلب الصفحة الأخيرة.

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

Java

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

NET.

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

Python

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 للاطّلاع على أمثلة على طلبات البيانات من واجهة برمجة التطبيقات وتجربة استدعاء واجهة برمجة التطبيقات بنفسك.