Jak to działa

Interfejs API klienta zapewnia automatyczną kontrolę nad urządzeniami i konfiguracją rejestracji typu zero-touch na Androidzie. Ten dokument stanowi wprowadzenie do interfejsu API dla dostawców usług zarządzania urządzeniami mobilnymi (EMM) i programistów IT w przedsiębiorstwach. Zapoznasz się z podstawowymi zasobami API i zapoznasz się z nimi, Jeśli po raz pierwszy korzystasz z rejestracji typu zero-touch, przeczytaj krótkie wprowadzenie na android.com.

Przegląd

Interfejs API klienta pomaga organizacjom, które kupują urządzenia do rejestracji typu zero-touch z Androidem. Aplikacja lub narzędzie może pomóc administratorom IT w:

• Tworzenie, edytowanie i usuwanie konfiguracji obsługi administracyjnej.
• Zastosuj konfigurację na urządzeniu lub usuń ją.
• Wybierz domyślną konfigurację dla wszystkich urządzeń dodanych od tej pory do rejestracji typu zero-touch.

Za jego pomocą administratorzy IT mogą też wyrejestrowywać urządzenia z rejestracji typu zero-touch. Aby zarządzać użytkownikami w organizacji lub zaakceptować Warunki korzystania z usługi, administratorzy IT mogą skorzystać z portalu rejestracji typu zero-touch.

Typowi użytkownicy tego interfejsu API mogą obejmować:

• Dostawcy usług EMM dodają w swoich konsoli obsługę rejestracji typu zero-touch.
• Programiści IT z firmy tworzą narzędzia do automatyzacji zadań rejestracji typu zero-touch.

Zasoby podstawowe

Konfiguracje i urządzenia to podstawowe zasoby używane w interfejsie API. Organizacja może też tworzyć konfiguracje i urządzenia za pomocą portalu rejestracji typu zero-touch.

Konfiguracja

Administratorzy IT ustawiają opcje obsługi administracyjnej urządzeń przy użyciu konfiguracji. Konfiguracje obejmują zasady EMM dotyczące urządzeń mobilnych i informacje kontaktowe, które są wyświetlane użytkownikom. Konfiguracje są centralnym elementem interfejsu API, dlatego można ich używać w wielu metodach. Więcej informacji znajdziesz w sekcji Konfiguracje poniżej.

Urządzenie

urządzenie z Androidem obsługujące rejestrację typu zero-touch, które zostało kupione przez organizację od sprzedawcy. Zastosuj konfigurację, aby uwzględnić urządzenie w rejestracji typu zero-touch. Urządzenia mają identyfikatory sprzętu i dołączone metadane. Więcej informacji znajdziesz w sekcji Urządzenia poniżej.

kontroler DPC

Odniesienie tylko do odczytu do DPC (kontrolera zasad urządzeń) EMM. Dodaj DPC do konfiguracji, aby wybrać rozwiązanie EMM dla urządzeń. Wszystkie DPC wymienione przez interfejs API obsługują rejestrację typu zero-touch i są dostępne w Google Play. Więcej informacji: Dpc.

Listę wszystkich metod i zasobów interfejsu API, z których może korzystać Twoja aplikacja, znajdziesz w dokumentacji interfejsu API.

Konfiguracje

Zasób interfejsu API Configuration łączy te elementy:

• DPC dostawcy usług EMM zainstalowany na urządzeniach.
• Zasady EMM obowiązujące na urządzeniach.
• Informacje kontaktowe wyświetlane na urządzeniu, aby pomóc użytkownikom podczas konfiguracji.

Za jego pomocą aplikacja może zarządzać konfiguracjami dla administratorów IT. Wywołaj ten interfejs API, aby pobierać, tworzyć, aktualizować i usuwać konfiguracje. Z przykładu poniżej dowiesz się, jak utworzyć nową konfigurację:

Java

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

.NET

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

Python

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

Aktualizując konfigurację za pomocą interfejsu patch API, pamiętaj o dodaniu maski pola – lub wartości każdego pola, które nie ma mieć wartości null. Przykład, który pokazuje, jak skutecznie zaktualizować konfigurację, znajdziesz poniżej w sekcji Konfiguracje domyślne.

Usuń konfiguracje

Nie możesz usunąć konfiguracji, jeśli nadal jest ona stosowana na urządzeniach. Jeśli próbujesz usunąć nieużywaną konfigurację, metoda API zwraca kod stanu HTTP 400 Bad Request i komunikat wyjaśniający, ile urządzeń korzysta z tej konfiguracji. Wywołaj customers.devices.removeConfiguration, aby usunąć konfigurację z urządzeń, zanim spróbujesz ponownie.

Konfiguracje domyślne

Rejestracja typu zero-touch działa najlepiej, gdy organizacja ustawia domyślną konfigurację, która jest stosowana na wszystkich nowych urządzeniach zakupionych przez tę organizację. W razie potrzeby poproś administratorów IT o ustawienie domyślnej konfiguracji. Poniższy przykład pokazuje, jak ustawić istniejącą konfigurację jako domyślną przez ustawienie isDefault na 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()

Może być tylko 1 konfiguracja domyślna. Utworzenie nowej konfiguracji domyślnej powoduje ustawienie w polu isDefault poprzedniej konfiguracji wartości false. Aby zobaczyć prawidłowe wartości w polach isDefault, może być konieczne odświeżenie pamięci podręcznej instancji Configuration.

Prowokowanie użytkowników urządzeń

Konfiguracja rejestracji typu zero-touch wyświetla użytkownikom dostosowane wskazówki w Kreatorze konfiguracji urządzenia, Musisz podać kontaktowy numer telefonu i adres e-mail wraz z nazwą organizacji zarządzającej urządzeniem w konfiguracji. Zalecamy też wpisanie 1 lub 2 zdań w polu customMessage, aby podać więcej informacji o tym, co dzieje się z urządzeniem użytkownika.

Użytkownik nie będzie mógł zadzwonić ani wysłać e-maila z konfigurowanego urządzenia, dlatego format numeru telefonu i adresu e-mail ułatwia przegląd informacji.

Urządzenia

Sprzedawcy tworzą urządzenia, gdy klient kupuje je do rejestracji typu zero-touch. Administratorzy IT nie mogą tworzyć urządzeń. Aby pracować z urządzeniami, wywołaj metody w zasobie interfejsu API Device. Jeśli chcesz wyszukać urządzenia, wymień wszystkie urządzenia i przefiltruj każdą grupę lokalnie w aplikacji. Przykład znajdziesz w sekcji Wyniki z podziałem na strony poniżej.

Konfigurowanie urządzeń

Zastosowanie konfiguracji na urządzeniu spowoduje zarejestrowanie go w rejestracji typu zero-touch. Aby zastosować konfigurację, wywołaj metodę customers.devices.applyConfiguration. Po zastosowaniu konfiguracji urządzenie automatycznie się konfiguruje przy pierwszym uruchomieniu lub przy następnym przywróceniu do ustawień fabrycznych. Ten przykład pokazuje, jak możesz zastosować konfigurację do zbioru urządzeń:

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

Aby usunąć konfigurację z urządzenia, wywołaj metodę customers.devices.removeConfiguration. Zmiana zostanie wprowadzona po przywróceniu ustawień fabrycznych na urządzeniu.

Usuń rezerwację urządzeń

Administratorzy IT mogą usunąć rezerwację urządzenia z rejestracji typu zero-touch. Administrator IT może wycofać rezerwację urządzenia, które chce przenieść na inne konto, sprzedać lub zwrócić sprzedawcy. Wywołaj metodę customers.devices.unclaim, aby wycofać rezerwację urządzenia w organizacji.

Uwaga: zanim wywołasz interfejsy API anulowania rezerwacji, możesz poprosić użytkownika o potwierdzenie, że korzysta z właściwego urządzenia. Anulowanie rezerwacji urządzenia spowoduje usunięcie konfiguracji obsługi administracyjnej organizacji, a po przywróceniu ustawień fabrycznych urządzenie przestanie być zarządzane. Jeśli będzie chciał ponownie zarejestrować urządzenie w rejestracji typu zero-touch, administrator IT musi skontaktować się ze sprzedawcą.

Poniższy przykład pokazuje, jak usunąć zgłoszenie prawa własności do urządzenia, korzystając z numeru IMEI i nazwy producenta:

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

Metadane urządzenia

Administrator IT może zobaczyć metadane dołączone do urządzenia przez sprzedawcę. Wyświetlaj metadane urządzenia w aplikacji, aby pomóc administratorom IT rozpoznawać urządzenia.

Aby dowiedzieć się więcej o metadanych, które możesz zobaczyć, przeczytaj przewodnik dla sprzedawców dotyczący metadanych urządzeń.

Wyniki podzielone na strony

Metoda interfejsu API customers.devices.list może zwracać bardzo duże listy urządzeń. Aby zmniejszyć rozmiar odpowiedzi, ta i inne metody interfejsu API (np. customers.list) obsługują wyniki z podziałem na strony. Dzięki wynikom z podziałem na strony aplikacja może iteracyjnie wysyłać żądania i przetwarzać duże listy po jednej stronie.

Po wywołaniu metody interfejsu API sprawdź, czy odpowiedź zawiera wartość nextPageToken. Jeśli nextPageToken nie jest null, aplikacja może użyć jej do pobrania innej strony urządzeń, ponownie wywołując metodę. Musisz ustawić górny limit liczby urządzeń w parametrze pageSize. Jeśli nextPageToken to null, aplikacja zażądała ostatniej strony.

W przykładowej metodzie poniżej pokazujemy, jak aplikacja może drukować listę urządzeń (po jednej stronie):

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

Rozpocznij

Następnie przeczytaj o autoryzowaniu wywołań interfejsu API w artykule Autoryzacja. Jeśli chcesz poznać interfejsy API, zapoznaj się z krótkimi przewodnikami po językach Java, .NET i Pythona. Możesz użyć colab, aby zobaczyć przykłady wywołań interfejsu API i poeksperymentować z samodzielnym wywoływaniem interfejsu API.