چگونه کار می کند

API مشتری کنترل برنامه‌ای دستگاه‌ها و پیکربندی را برای ثبت‌نام بدون لمس Android ارائه می‌دهد. این سند API را به ارائه دهندگان مدیریت تحرک سازمانی (EMM) و توسعه دهندگان فناوری اطلاعات سازمانی معرفی می کند. پس از خواندن این سند، باید منابع اصلی مورد استفاده در API و نحوه تعامل آنها را درک کنید. اگر در ثبت نام با لمس صفر تازه وارد هستید، مقدمه کوتاه android.com را بخوانید.

بررسی اجمالی

API مشتری به سازمان‌هایی که دستگاه‌های ثبت نام بدون لمس Android را خریداری می‌کنند کمک می‌کند. برنامه یا ابزار شما می‌تواند به سرپرستان فناوری اطلاعات در انجام کارهای زیر کمک کند:

• ایجاد، ویرایش و حذف تنظیمات تامین.
• یک پیکربندی را روی یک دستگاه اعمال یا حذف کنید.
• یک پیکربندی پیش‌فرض برای هر دستگاهی که در آینده به ثبت نام بدون لمس اضافه می‌شود، انتخاب کنید.

از طریق API، مدیران فناوری اطلاعات همچنین می‌توانند دستگاه‌ها را از ثبت‌نام بدون لمس لغو ثبت کنند. برای مدیریت کاربران سازمان خود یا پذیرش شرایط خدمات، سرپرستان فناوری اطلاعات از پورتال ثبت نام بدون لمس استفاده می کنند.

کاربران معمولی این API ممکن است:

• ارائه دهندگان EMM پشتیبانی از ثبت نام بدون لمس را به کنسول خود اضافه می کنند.
• توسعه دهندگان IT سازمانی ابزارهایی را برای خودکارسازی وظایف ثبت نام بدون لمس ایجاد می کنند.

منابع اصلی

پیکربندی ها و دستگاه ها منابع اصلی هستند که در API استفاده می کنید. یک سازمان همچنین می‌تواند پیکربندی‌ها و دستگاه‌هایی را با استفاده از پورتال ثبت‌نام بدون لمس ایجاد کند.

پیکربندی

سرپرستان فناوری اطلاعات گزینه‌های تأمین را برای دستگاه‌هایی با استفاده از پیکربندی تنظیم می‌کنند. تنظیمات شامل خط‌مشی‌های تلفن همراه EMM و اطلاعات تماس است که برای کمک به کاربران نمایش داده می‌شود. پیکربندی ها برای API مرکزی هستند، بنابراین شما از آنها در بسیاری از روش ها استفاده می کنید. برای کسب اطلاعات بیشتر، تنظیمات زیر را ببینید.

دستگاه

یک دستگاه Android با قابلیت ثبت نام بدون لمس که یک سازمان از فروشنده خود خریداری کرده است. پیکربندی را برای گنجاندن دستگاه در ثبت نام بدون لمس اعمال کنید. دستگاه‌ها دارای شناسه‌های سخت‌افزاری و فراداده پیوست هستند. برای اطلاعات بیشتر، دستگاه‌های زیر را ببینید.

DPC

یک مرجع فقط خواندنی به DPC یک EMM ( کنترل کننده خط مشی دستگاه ). برای انتخاب راه حل EMM برای دستگاه ها، یک DPC به پیکربندی اضافه کنید. همه DPC های فهرست شده توسط API از ثبت نام بدون لمس پشتیبانی می کنند و در Google Play در دسترس هستند. برای کسب اطلاعات بیشتر، Dpc ببینید.

برای فهرست کردن همه روش‌ها و منابع API که برنامه شما می‌تواند استفاده کند، به مرجع API مراجعه کنید.

پیکربندی

منبع Configuration API موارد زیر را ترکیب می کند:

• DPC EMM روی دستگاه ها نصب شده است.
• خط‌مشی‌های EMM اعمال شده در دستگاه‌ها.
• اطلاعات تماس برای کمک به کاربران در هنگام راه‌اندازی روی دستگاه نمایش داده می‌شود.

با استفاده از API، برنامه شما می‌تواند پیکربندی‌های سرپرستان فناوری اطلاعات را مدیریت کند. برای واکشی، ایجاد، به‌روزرسانی و حذف تنظیمات، با API تماس بگیرید. مثال زیر نحوه ایجاد یک پیکربندی جدید را نشان می دهد:

جاوا

// Add metadata to help the device user during provisioning.
Configuration configuration = new Configuration();
configuration.setConfigurationName("Sales team");
configuration.setCompanyName("XYZ Corp.");
configuration.setContactEmail("[e-mail]");
configuration.setContactPhone("[phone]");
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 = "[e-mail]",
    ContactPhone = "[phone]",
    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': '[e-mail]',
    'contactPhone': '[phone]',
    '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 باشد. برای مثالی که نشان می دهد چگونه پیکربندی را به طور موثر به روز کنید ، تنظیمات پیش فرض (در زیر) را ببینید.

تنظیمات را حذف کنید

اگر پیکربندی همچنان در دستگاه‌ها اعمال شود، نمی‌توانید آن را حذف کنید. اگر بخواهید یک پیکربندی در حال استفاده را حذف کنید، روش API یک کد وضعیت HTTP 400 Bad Request و پیامی را برمی‌گرداند که توضیح می‌دهد چند دستگاه از پیکربندی استفاده می‌کنند. قبل از تلاش مجدد، با 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 تنظیم می‌کند. برای مشاهده مقادیر صحیح در فیلدهای isDefault ، ممکن است لازم باشد هر نمونه Configuration کش شده را بازخوانی کنید.

راهنمای کاربران دستگاه

پیکربندی Zero-touch راهنمای کاربر سفارشی شده را در جادوگر راه اندازی دستگاه نمایش می دهد تا به کاربران کمک کند. باید یک شماره تلفن تماس و آدرس ایمیل همراه با نام سازمانی که دستگاه را در یک پیکربندی مدیریت می‌کند، وارد کنید. همچنین توصیه می‌کنیم یک یا دو جمله را در قسمت customMessage اضافه کنید تا جزئیات بیشتری در مورد آنچه برای دستگاه کاربر اتفاق می‌افتد ارائه دهید.

از آنجایی که کاربر نمی‌تواند از دستگاهی که تنظیم می‌کند تماس یا ایمیل بزند، شماره تلفن و آدرس ایمیل را فرمت کنید تا نگاه کردن به اطلاعات آسان‌تر شود.

دستگاه ها

هنگامی که مشتری برای ثبت نام بدون لمس آنها را خریداری می کند، نمایندگان فروش دستگاه ها را ایجاد می کنند — سرپرستان فناوری اطلاعات نمی توانند دستگاه ایجاد کنند. برای کار با دستگاه‌ها، روش‌های موجود در منبع Device API را فراخوانی کنید. اگر می‌خواهید دستگاه‌ها را جستجو کنید، همه دستگاه‌ها را فهرست کنید و هر دسته را به صورت محلی در برنامه خود فیلتر کنید. برای مثال، نتایج Paged را در زیر ببینید.

پیکربندی دستگاه ها

اعمال پیکربندی روی دستگاه، دستگاه را برای ثبت نام بدون لمس ثبت می‌کند. برای اعمال یک پیکربندی، با 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 را صدا بزنید.

احتیاط: قبل از فراخوانی APIهای بدون ادعا، از کاربر برنامه خود بخواهید تا تأیید کند که دستگاه درستی دارد. عدم ادعای دستگاه، راه‌اندازی تأمین سازمان را حذف می‌کند و دستگاه پس از بازنشانی کارخانه‌ای مدیریت نمی‌شود. اگر می‌خواهد دوباره دستگاه را در ثبت نام بدون لمس ثبت کند، سرپرست فناوری اطلاعات باید با فروشنده خود تماس بگیرد.

مثال زیر نحوه لغو ادعای دستگاه را از شماره 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()

فراداده دستگاه

یک سرپرست فناوری اطلاعات می‌تواند ابرداده‌های پیوست شده توسط فروشنده را به دستگاه ببیند. این فراداده دستگاه را در برنامه خود نمایش دهید تا به مدیران فناوری اطلاعات کمک کنید دستگاه ها را تشخیص دهند.

برای کسب اطلاعات بیشتر درباره ابرداده‌هایی که ممکن است ببینید، راهنمای فراداده دستگاه برای فروشندگان را بخوانید.

نتایج صفحه شده

ممکن است روش API customers.devices.list لیست های بسیار بزرگی از دستگاه ها را برگرداند. برای کاهش اندازه پاسخ، این و سایر روش‌های API (مانند customers.list ) از نتایج صفحه‌شده پشتیبانی می‌کنند. با نتایج صفحه‌بندی شده، برنامه شما می‌تواند به طور مکرر لیست‌های بزرگ را یک صفحه در یک زمان درخواست و پردازش کند.

پس از فراخوانی متد API، بررسی کنید که آیا پاسخ دارای مقداری برای 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'])

شروع کنید

در مرحله بعد، نحوه مجاز کردن تماس‌های API را در Authorization بخوانید. اگر می خواهید API ها را کاوش کنید، به راهنمای شروع سریع برای جاوا ، دات نت و پایتون نگاهی بیندازید. می‌توانید از یک colab برای مشاهده نمونه‌هایی از تماس‌های API استفاده کنید و خودتان با API تماس بگیرید.