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.
- 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.