Jak to działa

Interfejs API klienta zapewnia programową kontrolę nad urządzeniami i konfiguracją w przypadku 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. Po przeczytaniu tego dokumentu powinieneś rozumieć podstawowe zasoby używane w interfejsie API oraz ich wzajemne oddziaływanie. 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 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 dodają obsługę rejestracji typu zero-touch do swoich konsol;
• deweloperzy IT w firmach, którzy tworzą narzędzia do automatyzacji zadań związanych z rejestracją typu zero-touch;

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.

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 :

• kontroler zasad dotyczących urządzeń 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("[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()

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 usunąć konfigurację, której używają inne urządzenia, metoda interfejsu API zwróci kod stanu HTTP 400 Bad Requestoraz wiadomość z informacją, ile urządzeń korzysta z 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. W kontakcie musisz podać numer telefonu i adres e-mail oraz nazwę organizacji, która zarządza urządzeniem w ramach konfiguracji. Zalecamy też umieszczenie w polu customMessage 1–2 zdań, aby podać więcej informacji o tym, co dzieje się z urządzeniem użytkownika.

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 kupi je do rejestracji typu zero-touch. 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 jego rejestrację do rejestracji typu zero-touch. Aby zastosować konfigurację, wywołaj customers.devices.applyConfiguration Gdy zastosujesz konfigurację na urządzeniu, automatycznie przejdzie ono w tryb obsługi administracyjnej przy pierwszym uruchomieniu lub przy następnym przywróceniu ustawień fabrycznych. Przykład poniżej pokazuje, jak 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 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.

Uwaga: poproś użytkownika aplikacji o potwierdzenie, że posiada poprawić urządzenie przed wywołaniem interfejsów API, które nie mają zgłoszonych praw. Anulowanie rezerwacji urządzenia powoduje usunięcie konfiguracji obsługi administracyjnej organizacji, a urządzenie stanie się niezarządzane do ustawień fabrycznych. Jeśli administrator IT chce ponownie zarejestrować urządzenie w ramach rejestracji typu zero-touch, musi skontaktować się ze sprzedawcą.

Przykład poniżej pokazuje, jak zrezygnować z uprawnienia na urządzeniu na podstawie 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 te metadane urządzenia 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 zwracać bardzo długie listy urządzeń. Aby zmniejszyć rozmiar odpowiedzi, ten i inny interfejs API (takie jak customers.list) mogą obsługiwać wyniki na stronach. Dzięki podziałowi wyników na strony aplikacja może stopniowo pobierać i przetwarzać duże listy po jednej stronie 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.