Cách thức hoạt động

API khách hàng cung cấp quyền kiểm soát có lập trình đối với thiết bị và cấu hình để đăng ký Android không cần chạm. Tài liệu này giới thiệu API cho các nhà cung cấp giải pháp quản lý di động dành cho doanh nghiệp (EMM) và nhà phát triển công nghệ thông tin (IT) của doanh nghiệp. Sau khi đọc tài liệu này, chắc hẳn bạn đã nắm được những được dùng trong API và cách chúng tương tác. Nếu bạn mới sử dụng mô hình tự động đăng ký, hãy đọc android.com ngắn gọn giới thiệu.

Tổng quan

API khách hàng giúp các tổ chức mua quy trình thiết lập tự động của Android thiết bị. Ứng dụng hoặc công cụ của bạn có thể giúp quản trị viên CNTT làm những việc sau:

  • Tạo, chỉnh sửa và xoá cấu hình cấp phép.
  • Áp dụng hoặc xoá cấu hình cho thiết bị.
  • Chọn cấu hình mặc định cho mọi thiết bị được thêm vào quy trình thiết lập tự động từ nay về sau.

Thông qua API, quản trị viên CNTT cũng có thể huỷ đăng ký thiết bị khỏi tính năng thiết lập tự động. Để quản lý người dùng của tổ chức hoặc chấp nhận Điều khoản dịch vụ, quản trị viên CNTT sử dụng cổng đăng ký không cần tiếp xúc.

Người dùng điển hình của API này có thể là:

  • Các nhà cung cấp dịch vụ EMM (quản lý thiết bị di động doanh nghiệp) thêm tính năng hỗ trợ thiết lập tự động vào bảng điều khiển của họ.
  • Các nhà phát triển CNTT doanh nghiệp tạo ra các công cụ để tự động hoá quy trình thiết lập tự động công việc.

Tài nguyên cốt lõi

Cấu hình và thiết bị là các tài nguyên cốt lõi mà bạn sử dụng trong API. Một tổ chức cũng có thể tạo cấu hình và thiết bị bằng quy trình tự động đăng ký cổng đăng ký.

Mối quan hệ với thiết bị và tài nguyên khách hàng

Cấu hình
Quản trị viên CNTT đặt tuỳ chọn cấp phép cho thiết bị bằng cách sử dụng cấu hình. Cấu hình bao gồm các chính sách EMM (quản lý thiết bị di động doanh nghiệp) và thông tin liên hệ sẽ hiển thị với trợ giúp người dùng. Cấu hình là yếu tố trung tâm của API, vì vậy, bạn sẽ sử dụng cấu hình trong nhiều phương thức. Để tìm hiểu thêm, hãy xem phần Cấu hình ở bên dưới.
Thiết bị
Thiết bị Android có thể đăng ký không cần chạm mà một tổ chức đã mua từ đại lý của họ. Áp dụng cấu hình để thiết bị được thiết lập tự động đăng ký. Thiết bị có mã phần cứng và siêu dữ liệu đính kèm. Để tìm hiểu thêm, hãy xem phần Thiết bị bên dưới.
DPC
Tệp tham chiếu chỉ đọc đến DPC của EMM (chính sách thiết bị) tay điều khiển). Thêm DPC vào một cấu hình để chọn giải pháp EMM cho thiết bị. Tất cả DPC được liệt kê bởi API có hỗ trợ thiết lập tự động và có sẵn trên Google Play. Người nhận tìm hiểu thêm, xem Dpc.

Để liệt kê tất cả phương thức API và tài nguyên mà ứng dụng của bạn có thể dùng, hãy xem Tài liệu tham khảo API.

Cấu hình

Tài nguyên API Configuration kết hợp sau:

  • DPC của EMM đã được cài đặt trên các thiết bị.
  • Chính sách EMM được thực thi trên thiết bị.
  • Thông tin liên hệ xuất hiện trên thiết bị để giúp người dùng trong quá trình thiết lập.

Khi sử dụng API này, ứng dụng của bạn có thể quản lý cấu hình cho quản trị viên CNTT. Gọi API để tìm nạp, tạo, cập nhật và xoá cấu hình. Ví dụ bên dưới cho thấy cách tạo một cấu hình mới:

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

Khi bạn cập nhật cấu hình bằng API bản vá, hãy nhớ đưa vào mặt nạ trường – hoặc cho mọi trường bạn không muốn đặt là null. Xem phần Mặc định cấu hình (bên dưới) để xem ví dụ về cách cập nhật cấu hình một cách hiệu quả.

Xoá cấu hình

Bạn không thể xoá một cấu hình nếu cấu hình đó vẫn được áp dụng cho các thiết bị. Nếu bạn cố gắng xoá cấu hình đang sử dụng, thì phương thức API sẽ trả về một HTTP 400 Bad Request và một thông báo giải thích số lượng thiết bị sử dụng cấu hình này. Gọi điện customers.devices.removeConfiguration để xoá cấu hình khỏi thiết bị trước khi thử lại.

Cấu hình mặc định

Quy trình thiết lập tự động hoạt động hiệu quả nhất khi tổ chức đặt chế độ mặc định được áp dụng cho mọi thiết bị mới mà tổ chức mua. Hãy cân nhắc việc nhắc quản trị viên CNTT đặt cấu hình mặc định nếu bạn chưa thiết lập cấu hình này. Ví dụ bên dưới trình bày cách đặt một cấu hình hiện có làm mặc định theo đặt isDefault thành 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()

Chỉ được có một cấu hình mặc định. Tạo một cấu hình mặc định mới, đặt trường isDefault của cấu hình trước thành false. Bạn có thể cần làm mới mọi phiên bản Configuration đã lưu vào bộ nhớ đệm để xem các giá trị chính xác trong isDefault trường.

Hướng dẫn người dùng thiết bị

Cấu hình không tiếp xúc hiển thị hướng dẫn tuỳ chỉnh cho người dùng trong Trình hướng dẫn thiết lập thiết bị để giúp người dùng. Bạn cần cung cấp số điện thoại liên hệ và địa chỉ email cùng với tên của tổ chức quản lý thiết bị trong . Bạn cũng nên thêm một hoặc hai câu vào trường customMessage để cung cấp thêm thông tin chi tiết về những gì đang xảy ra với thiết bị của người dùng.

Vì người dùng sẽ không thể gọi điện hoặc gửi email từ thiết bị mà họ đang cài đặt định dạng số điện thoại và địa chỉ email để người dùng có thể dễ dàng xem nhanh thông tin đó.

Thiết bị

Đại lý tạo thiết bị khi khách hàng mua thiết bị cho quy trình tự động đăng ký đăng ký—quản trị viên CNTT không thể tạo thiết bị. Để hoạt động với các thiết bị, hãy bật các phương thức gọi trên tài nguyên API Device. Nếu bạn cần tìm kiếm đối với thiết bị, hãy liệt kê tất cả thiết bị và lọc cục bộ từng lô trong ứng dụng của bạn. Để ví dụ, hãy xem phần Kết quả phân trang bên dưới.

Định cấu hình thiết bị

Việc áp dụng cấu hình cho một thiết bị sẽ đăng ký thiết bị đó cho tính năng tự động đăng ký đăng ký. Để áp dụng một cấu hình, hãy gọi customers.devices.applyConfiguration. Sau khi áp dụng một cấu hình, thiết bị sẽ tự động cấp phép cho chính nó trong lần khởi động đầu tiên hoặc lần đặt lại về trạng thái ban đầu tiếp theo. Ví dụ bên dưới cho thấy cách bạn có thể áp dụng cấu hình cho một tập hợp thiết bị:

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

Để xoá cấu hình khỏi một thiết bị, hãy gọi customers.devices.removeConfiguration. Thay đổi sẽ có hiệu lực sau khi thiết bị được đặt lại về trạng thái ban đầu.

Huỷ xác nhận thiết bị

Quản trị viên CNTT có thể huỷ xác nhận quyền sở hữu một thiết bị để xoá thiết bị đó khỏi quy trình thiết lập tự động. CNTT quản trị viên có thể huỷ xác nhận quyền sở hữu một thiết bị mà họ muốn di chuyển sang một tài khoản khác, đã bán, hoặc trả lại cho người bán lại. Gọi phương thức customers.devices.unclaim để huỷ xác nhận thiết bị của một tổ chức.

Ví dụ bên dưới minh hoạ cách huỷ xác nhận quyền sở hữu thiết bị bằng số IMEI và tên nhà sản xuất:

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

Siêu dữ liệu thiết bị

Quản trị viên CNTT có thể xem siêu dữ liệu mà đại lý đính kèm với thiết bị. Chiến dịch Hiển thị siêu dữ liệu thiết bị này trong ứng dụng của bạn để giúp quản trị viên CNTT nhận ra thiết bị.

Để tìm hiểu thêm về siêu dữ liệu mà bạn có thể thấy, hãy đọc phần Thiết bị siêu dữ liệu dành cho đại lý.

Kết quả được phân trang

Phương thức API customers.devices.list có thể trả về danh sách rất lớn gồm các thiết bị. Để giảm kích thước phản hồi, phương thức này và các phương thức API khác (chẳng hạn như customers.list) hỗ trợ kết quả được phân trang. Bằng kết quả được phân trang, ứng dụng của bạn có thể yêu cầu lặp lại và xử lý các danh sách lớn từng trang một.

Sau khi gọi phương thức API, hãy kiểm tra xem phản hồi có chứa giá trị cho nextPageToken. Nếu nextPageToken không phải là null, ứng dụng của bạn có thể sử dụng thông tin này để tìm nạp một trang thiết bị khác bằng cách gọi hàm . Bạn cần đặt giới hạn trên cho số lượng thiết bị trong Tham số pageSize. Nếu nextPageToken là null, tức là ứng dụng của bạn đã yêu cầu trang cuối.

Phương thức mẫu bên dưới cho biết cách ứng dụng của bạn có thể in danh sách thiết bị, mỗi lần một trang:

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'])

Bắt đầu

Tiếp theo, hãy đọc cách uỷ quyền lệnh gọi API trong phần Uỷ quyền. Nếu bạn muốn khám phá các API, hãy xem hướng dẫn nhanh về Java, .NET và Python. Bạn có thể sử dụng colab để xem ví dụ về lệnh gọi API và thử tự gọi API.