選項說明

客戶 API 提供裝置程式輔助管理功能 。本文件將介紹 向企業行動管理服務 (EMM) 供應商和企業 IT 人員提供的 API 開發人員。閱讀這份文件後,您應該瞭解 以及這些資源的互動方式如果你不熟悉零接觸機制 請先閱讀簡短的 android.com 簡介

總覽

客戶 API 可協助購買 Android 零接觸註冊裝置的機構。您的應用程式或工具可協助 IT 管理員執行以下操作:

  • 建立、編輯及刪除佈建設定。
  • 為裝置套用或移除設定。
  • 為日後加入零接觸註冊機制的任何裝置選取預設設定。

透過 API,IT 管理員也可以為裝置取消註冊零接觸註冊機制。如要管理機構的使用者或接受《服務條款》, IT 管理員使用零接觸註冊機制入口網站

下列是這個 API 的常見使用者:

  • EMM 供應商在主控台中新增零接觸註冊機制支援功能。
  • 企業 IT 開發人員需要建立可自動執行零接觸註冊機制的工具 機器學習程式庫提供一系列預先編寫的程式碼 可用來執行機器學習工作

核心資源

設定和裝置是指您在 API 中使用的核心資源。機構也可以使用零接觸註冊機制入口網站建立設定和裝置。

裝置和顧客資源關係

設定
IT 管理員必須為使用設定的裝置指定佈建選項。 設定包括 EMM 行動裝置政策,以及系統向 協助使用者。設定是 API 的核心,因此在許多 方法。詳情請參閱下方的設定
裝置
機構向經銷商購買的支援零接觸註冊機制的 Android 裝置。套用設定,將裝置納入零接觸機制 。裝置會有硬體 ID 和附加中繼資料。詳情請參閱: 裝置
DPC
EMM DPC (裝置政策) 的唯讀參照 控制器)。在設定中新增 DPC,為裝置選取 EMM 解決方案。列出所有裝置政策控制器 (DPC) 的 API 支援零接觸註冊機制,可透過 Google Play 下載。目的地: 詳情請參閱 Dpc

如要列出應用程式可使用的所有 API 方法和資源,請參閱 API 參考資料

設定

Configuration API 資源結合了 包括:

  • 裝置上安裝的 EMM DPC。
  • 已對裝置強制執行 EMM 政策。
  • 裝置上顯示的聯絡資訊,用於協助使用者設定裝置。

您的應用程式可透過 API 管理 IT 管理員的設定。呼叫 API, 擷取、建立、更新及刪除設定。以下範例說明如何 建立新的設定:

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

使用修補程式 API 更新設定時,請記得將 欄位遮罩,或 您不想為 null 的每個欄位輸入值。請參閱預設 設定 (詳見下文),示範如何使用 能有效率地更新設定

刪除設定

如果設定仍套用至裝置,則無法刪除。如果您嘗試 刪除使用中的設定,API 方法會傳回 HTTP 400 Bad Request 狀態碼,以及說明有多少裝置使用該設定的訊息。 致電 customers.devices.removeConfiguration敬上 ,請先從裝置移除設定,然後再試一次。

預設設定

如果機構已設定預設值,零接觸註冊機制能帶來最佳效益 會套用至機構購買的任何新裝置。 如果未設定,建議 IT 管理員設定預設設定。 以下範例說明如何將現有設定設為預設 將 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 欄位。

引導裝置使用者

零接觸設定會在裝置設定中顯示自訂的使用者指引 協助使用者的精靈。您需要提供聯絡電話號碼和電子郵件地址 以及管理此裝置的機構名稱 此外還會從 0 自動調整資源配置 您完全不必調整資源調度設定我們也建議您在 customMessage 欄位,針對使用者所發生的情況提供更詳細的說明 裝置。

使用者無法透過原先設定的裝置撥打電話或傳送電子郵件 設定、設定電話號碼和電子郵件地址的格式, 這些資訊

裝置

客戶購買的零接觸機制是由經銷商建立裝置 註冊:IT 管理員無法建立裝置。如要使用裝置,請在以下裝置上呼叫方法: Device API 資源。如果需要搜尋 列出所有裝置,並在本機篩選及篩選每批裝置。適用對象 範例請見下方的「分頁結果」

設定裝置

為裝置套用設定後,系統就會為裝置註冊零接觸機制 。如要套用設定,請呼叫 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。 變更會在裝置恢復原廠設定後生效。

取消認領裝置

IT 管理員可以取消認領裝置,將其從零接觸註冊機制中移除。IT 團隊 管理員可能會取消認領要遷移到其他帳戶 (售出) 的裝置, 或是退回給經銷商呼叫下列方法 按 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()

裝置中繼資料

IT 管理員可以查看經銷商附加至裝置的中繼資料。螢幕 應用程式中的這項裝置中繼資料,可協助 IT 管理員辨識裝置。

如要進一步瞭解系統可能會顯示的中繼資料,請參閱裝置說明 經銷商的中繼資料指南。

分頁結果

customers.devices.list API 方法可能會傳回非常大的裝置清單。為了縮減回應大小,這個 API 和其他 API 方法 (例如 customers.list) 支援分頁結果。取代為 分頁結果,您的應用程式可以反覆要求並處理大型清單 一次只能處理 1 個頁面

呼叫 API 方法後,請檢查回應是否包含 nextPageToken。如果 nextPageToken 不是 null,應用程式可以藉由呼叫 方法。您必須設定 pageSize 參數。如果 nextPageTokennull,您的應用程式要求 最後一頁。

以下範例方法說明應用程式如何一次列印一頁的裝置清單:

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

開始使用

接下來,請參閱授權一文,瞭解如何授權 API 呼叫。如果您想 探索 API,請參閱 Java.NETPython。您可以使用 前往 colab 即可查看 API 呼叫的範例,以及自行呼叫 API 的實驗。