Jak to działa

Interfejs customer API zapewnia zautomatyzowaną kontrolę nad urządzeniami na potrzeby rejestracji typu zero-touch na Androidzie. W tym dokumencie przedstawiamy Dostawcy interfejsów API do zarządzania urządzeniami mobilnymi (EMM) i IT dla programistów. Zapoznanie się z treścią tego dokumentu powinno ułatwić i sposobach ich interakcji z zasobami w interfejsie API. Jeśli dopiero zaczynasz korzystać z rejestracji typu zero-touch rejestracji, przeczytaj krótki opis android.com .

Omówienie

Interfejs Customer API pomaga organizacjom, które kupują rejestrację typu zero-touch na Androidzie urządzenia. Twoja aplikacja lub narzędzie może pomóc administratorom IT w następujących czynnościach:

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

Za pomocą interfejsu API administratorzy IT mogą też wyrejestrować urządzenia z rejestracji typu zero-touch. rejestracji. Aby zarządzać użytkownikami w organizacji lub zaakceptować Warunki korzystania z usługi: Administratorzy IT mogą korzystać z portalu rejestracji typu zero-touch.

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

  • Dostawcy usług EMM, którzy dodają obsługę rejestracji typu zero-touch w konsoli.
  • Programiści IT dla firm tworzący narzędzia do automatyzacji rejestracji typu zero-touch zadania.

Podstawowe zasoby

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

Relacja między urządzeniem a zasobami klientów

Konfiguracja
Administratorzy IT ustawiają opcje obsługi administracyjnej urządzeń za pomocą konfiguracji. Konfiguracje obejmują zasady EMM dotyczące urządzeń mobilnych i informacje kontaktowe, które są wyświetlane pomaga użytkownikom. Konfiguracje są centralnym elementem interfejsu API, więc możesz ich używać . Więcej informacji znajdziesz w sekcji Konfiguracje poniżej.
Urządzenie
Urządzenie z Androidem z obsługą rejestracji typu zero-touch, które zostało kupione przez organizację jego sprzedawcę. Zastosuj konfigurację, aby uwzględnić urządzenie w ramach rejestracji typu zero-touch rejestracji. Urządzenia mają identyfikatory sprzętu i dołączone metadane. Więcej informacji: Urządzenia poniżej.
DPC
Odniesienie tylko do odczytu do DPC dostawcy usług EMM (zasady dotyczące urządzeń) kontroler). Dodaj DPC do konfiguracji, aby wybrać rozwiązanie EMM dla urządzeń. Wszystkie wymienione urządzenia DPC przez interfejs API obsługują rejestrację typu zero-touch i są dostępne w Google Play. Do więcej informacji: Dpc.

Aby wyświetlić listę wszystkich metod interfejsu API i zasobów, z których może korzystać aplikacja, zapoznaj się z Dokumentacja API.

Konfiguracje

Zasób interfejsu API Configuration łączy :

  • DPC dostawcy usług EMM zainstalowany na urządzeniach.
  • Zasady EMM egzekwowane na urządzeniach.
  • Informacje kontaktowe wyświetlane na urządzeniu, które ułatwiają użytkownikom konfigurację.

Za pomocą interfejsu API aplikacja może zarządzać konfiguracjami administratorów IT. Wywołaj interfejs API, aby pobierania, tworzenia, aktualizowania i usuwania konfiguracji. Ten przykład pokazuje, jak utwórz 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("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()

Podczas aktualizowania konfiguracji za pomocą interfejsu patch API pamiętaj o dodaniu parametru maska pola – lub dla każdego pola, którego nie chcesz mieć null. Patrz sekcja Domyślne konfiguracji (poniżej) znajdziesz przykład, który pokazuje, jak skutecznie aktualizować konfigurację.

Usuń konfiguracje

Nie możesz usunąć konfiguracji, jeśli nadal jest ona stosowana na urządzeniach. Jeśli spróbujesz usuniesz konfigurację używaną, metoda interfejsu API zwróci wartość HTTP 400 Bad Request kodu stanu oraz komunikatu z wyjaśnieniem, ile urządzeń używa tej konfiguracji. Zadzwoń do nas customers.devices.removeConfiguration , aby usunąć konfigurację z urządzeń i spróbować ponownie.

Konfiguracje domyślne

Rejestracja typu zero-touch działa najlepiej, gdy organizacja określa domyślną wartość , która jest stosowana na wszystkich nowych urządzeniach kupionych przez organizację. Jeśli nie jest ona ustawiona, poproś administratorów IT o ustawienie domyślnej konfiguracji. Poniższy przykład pokazuje, jak ustawić istniejącą konfigurację jako domyślną Ustawianie wartości 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. Tworzę nową konfigurację domyślną, ustawia pole isDefault poprzedniej konfiguracji na false. Może być konieczne odśwież wszystkie instancje Configuration w pamięci podręcznej, aby zobaczyć prawidłowe wartości w isDefault pól.

Pomaganie użytkownikom urządzeń

Konfiguracja rejestracji typu zero-touch wyświetla spersonalizowane wskazówki w ustawieniach urządzenia Kreator pomagający użytkownikom. Musisz podać kontaktowy numer telefonu i adres e-mail wraz z nazwą organizacji zarządzającej urządzeniem w konfiguracji. Zalecamy również umieszczenie jednego lub dwóch zdań w polu customMessage, aby podać więcej informacji o tym, co dzieje się z kontem użytkownika urządzenia.

Ponieważ użytkownik nie będzie mógł dzwonić ani wysyłać e-maili ze swojego urządzenia sformatować numer telefonu i adres e-mail, by ułatwić przeglądanie informacje.

Urządzenia

Sprzedawcy tworzą urządzenia, gdy klient kupuje je na potrzeby rejestracji typu zero-touch Rejestracja – administratorzy IT nie mogą tworzyć urządzeń. Aby móc pracować z urządzeniami, włącz metody połączeń zasób interfejsu API Device. Jeśli chcesz wyszukać w przypadku urządzeń, wymień wszystkie urządzenia i przefiltruj każdą ich partię lokalnie w aplikacji. Dla: przykład: Wyniki z podziałem na strony poniżej.

Konfigurowanie urządzeń

Zastosowanie konfiguracji na urządzeniu powoduje zarejestrowanie na nim rejestracji typu zero-touch rejestracji. Aby zastosować konfigurację, wywołaj customers.devices.applyConfiguration Po zastosowaniu konfiguracji urządzenie automatycznie przełączy się na obsługę administracyjną pierwszego uruchomienia czy przywrócenia do ustawień fabrycznych. Poniższy przykład pokazuje, jak można zastosować 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 customers.devices.removeConfiguration Zmiana zostanie wprowadzona po przywróceniu urządzenia do ustawień fabrycznych.

Usuń rezerwację urządzeń

Administratorzy IT mogą usunąć zarezerwowanie urządzenia, aby usunąć je z rejestracji typu zero-touch. IT administrator może anulować rezerwację urządzenia, które chce przenieść na inne konto, lub wróciła do sprzedawcy. Wywołaj metodę customers.devices.unclaim, aby usunąć rezerwację urządzenia od organizacji.

Przykład poniżej pokazuje, jak usunąć zgłoszenie praw do urządzenia z numerem IMEI oraz nazwa 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ę. Displayowa, w aplikacji, aby ułatwić administratorom IT rozpoznawanie urządzeń.

Więcej informacji na temat możliwych metadanych znajdziesz w sekcji Urządzenie metadanych.

Wyniki z podziałem na strony

Metoda interfejsu API customers.devices.list może zwrócić bardzo dużych list urządzeń. Aby zmniejszyć rozmiar odpowiedzi, ten i inny interfejs API (takie jak customers.list) mogą obsługiwać wyniki na stronach. Na wyników na stronach, aplikacja może iterować żądania i przetwarzać duże listy tylko jedną stronę naraz.

Po wywołaniu metody interfejsu API sprawdź, czy odpowiedź zawiera wartość dla argumentu nextPageToken Jeśli nextPageToken nie jest null, aplikacja może jej użyć do pobrania kolejnej strony z urządzeniami, wywołując metodę . Musisz ustawić górny limit liczby urządzeń pageSize. Jeśli nextPageToken to null, Twoja aplikacja wysłała żądanie ostatniej stronie.

Przykładowa metoda poniżej pokazuje, jak aplikacja może wydrukować listę urządzeń. Pierwsza z nich tylko jedną stronę:

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, jak autoryzować wywołania interfejsu API w sekcji Autoryzacja. Jeśli chcesz poznaj interfejsy API, zapoznaj się z krótkimi przewodnikami Java .NET oraz Python. Za pomocą colab, aby wyświetlić przykładowych wywołań interfejsu API i poeksperymentować z samodzielnym wywoływaniem interfejsu API.