選項說明

客戶 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 參數。如果 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'])

開始使用

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