Die Customer API ermöglicht die programmatische Steuerung von Geräten und Konfiguration für die Zero-Touch-Registrierung von Android. In diesem Dokument wird die APIs für EMM-Anbieter (Enterprise Mobility Management) und Unternehmens-IT zu entwickeln. Nachdem Sie dieses Dokument gelesen haben, sollten Sie die zentralen die in der API verwendeten Ressourcen und wie sie interagieren. Wenn Sie Zero-Touch zum ersten Mal verwenden zur Registrierung, lesen Sie die Kurzbeschreibung android.com .
Übersicht
Die Customer API unterstützt Organisationen, die Android-Geräte mit Zero-Touch-Registrierung erwerben. Ihre App oder Ihr Tool kann IT-Administratoren bei Folgendem unterstützen:
- Bereitstellungskonfigurationen erstellen, bearbeiten und löschen
- Wenden Sie eine Konfiguration auf ein Gerät an oder entfernen Sie sie.
- Wählen Sie eine Standardkonfiguration für Geräte aus, die zukünftig der Zero-Touch-Registrierung hinzugefügt werden.
Über die API können IT-Administratoren auch Geräte von Zero-Touch abmelden Registrierung. Um die Nutzer ihrer Organisation zu verwalten oder die Nutzungsbedingungen zu akzeptieren, IT-Administratoren können das Portal für die Zero-Touch-Registrierung nutzen.
Typische Nutzer dieser API sind:
- EMM-Anbieter, die die Zero-Touch-Registrierung in ihrer Konsole unterstützen
- IT-Entwickler in Unternehmen, die Tools zur Automatisierung der Zero-Touch-Registrierung erstellen Aufgaben.
Kernressourcen
Konfigurationen und Geräte sind die Hauptressourcen, die Sie in der API verwenden. Eine Unternehmen können auch Konfigurationen und Geräte mit der Registrierungsportal.
- Konfiguration
- IT-Administratoren legen die Bereitstellungsoptionen für Geräte über eine Konfiguration fest. Konfigurationen umfassen EMM-Richtlinien für Mobilgeräte und Kontaktdaten, die für Nutzer Nutzenden zu helfen. Konfigurationen sind zentral für die API und werden daher in vielen Methoden verwendet. Weitere Informationen finden Sie unten unter Konfigurationen.
- Gerät
- Ein Android-Gerät mit Zero-Touch-Registrierung, das eine Organisation bei ihrem Reseller gekauft hat. Konfiguration anwenden, um das Gerät in Zero-Touch aufzunehmen Registrierung. Geräte haben Hardware-IDs und angehängte Metadaten. Weitere Informationen finden Sie unten unter Geräte.
- DPC
- Eine schreibgeschützte Referenz zum DPC eines EMM (Geräterichtlinien)
Controller) DPC hinzufügen
zu einer Konfiguration, um die EMM-Lösung für Geräte auszuwählen. Alle aufgeführten DPCs
der API unterstützen die Zero-Touch-Registrierung und sind bei Google Play verfügbar. Bis
Weitere Informationen finden Sie unter
Dpc
.
Eine Liste aller API-Methoden und -Ressourcen, die Ihre Anwendung verwenden kann, finden Sie in der API-Referenz
Konfigurationen
Die API-Ressource Configuration
kombiniert die
Folgendes:
- Der DPC des EMM, der auf den Geräten installiert ist.
- Auf den Geräten erzwungene EMM-Richtlinien.
- Kontaktdaten, die auf dem Gerät angezeigt werden, um Nutzern bei der Einrichtung zu helfen.
Mit der API kann Ihre App Konfigurationen für IT-Administratoren verwalten. Rufen Sie die API auf, um Konfigurationen abrufen, erstellen, aktualisieren und löschen. Das folgende Beispiel zeigt, wie Sie erstellen Sie eine neue Konfiguration:
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()
Wenn Sie eine Konfiguration mit der Patch-API aktualisieren, denken Sie daran, den Parameter
field mask – oder eine
Wert für jedes Feld ein, das nicht null
sein soll. Unten finden Sie unter Standardkonfigurationen ein Beispiel dafür, wie Sie eine Konfiguration effizient aktualisieren.
Konfigurationen löschen
Sie können eine Konfiguration nicht löschen, wenn sie noch auf Geräte angewendet wird. Wenn Sie versuchen,
eine gerade verwendete Konfiguration löschen, gibt die API-Methode ein HTTP-400 Bad Request
zurück.
Statuscode und eine Meldung, die angibt, wie viele Geräte die Konfiguration verwenden.
Anruf
customers.devices.removeConfiguration
um die Konfiguration von den Geräten zu entfernen, bevor Sie es noch einmal versuchen.
Standardkonfigurationen
Die Zero-Touch-Registrierung funktioniert am besten, wenn eine Organisation
Konfiguration, die auf alle neuen Geräte angewendet wird, die die Organisation kauft.
Sie können die IT-Administratoren auffordern, eine Standardkonfiguration festzulegen, falls noch keine festgelegt wurde.
Das folgende Beispiel zeigt, wie Sie eine bestehende Konfiguration
isDefault
wird auf true
festgelegt:
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()
Es kann nur eine Standardkonfiguration geben. Wenn Sie eine neue Standardkonfiguration erstellen, wird das Feld isDefault
der vorherigen Konfiguration auf false
gesetzt. Möglicherweise müssen Sie
Aktualisieren Sie alle im Cache gespeicherten Instanzen von Configuration
, damit die korrekten Werte im
isDefault
-Feldern.
Anleitung für Gerätenutzer
Bei der Zero-Touch-Konfiguration wird eine benutzerdefinierte Anleitung bei der Geräteeinrichtung angezeigt
Assistent, der Nutzern hilft. Geben Sie eine Kontakttelefonnummer und eine E-Mail-Adresse an.
Adresse und dem Namen der Organisation, die das Gerät in einem
Konfiguration. Wir empfehlen außerdem, ein oder zwei Sätze in das
customMessage
ein, um weitere Informationen dazu bereitzustellen, was mit dem
.
Der Nutzer kann auf dem ausgewählten Gerät nicht anrufen oder E-Mails senden die Telefonnummer und die E-Mail-Adresse formatieren, damit Sie den zu den Informationen.
Geräte
Reseller erstellen Geräte, wenn ein Kunde sie für Zero-Touch kauft
Registrierung: IT-Administratoren können keine Geräte erstellen. Um mit Geräten zu arbeiten, rufen Sie Methoden auf
Die API-Ressource Device
Wenn Sie nach Geräten suchen möchten, listen Sie alle Geräte auf und filtern Sie jede Gruppe lokal in Ihrer App. Weitere Informationen finden Sie unten unter Seitenergebnisse.
Geräte konfigurieren
Durch das Anwenden einer Konfiguration auf ein Gerät wird es für Zero-Touch registriert
Registrierung. Rufen Sie zum Anwenden einer Konfiguration Folgendes auf:
customers.devices.applyConfiguration
Nach dem Anwenden einer Konfiguration wird das Gerät automatisch auf
oder beim nächsten Zurücksetzen auf die Werkseinstellungen. Das folgende Beispiel zeigt, wie Sie eine
für eine Gerätesammlung:
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()
Wenn Sie die Konfiguration von einem Gerät entfernen möchten, geben Sie customers.devices.removeConfiguration
ein.
Die Änderung wird wirksam, nachdem Sie das Gerät auf die Werkseinstellungen zurückgesetzt haben.
Anspruch auf Geräte aufheben
IT-Administratoren können die Inhaberschaft für ein Gerät zurückziehen, um es aus der Zero-Touch-Registrierung zu entfernen. Ein IT-
ein Gerät, das in ein anderes Konto migriert werden soll,
oder an den Reseller zurückgegeben werden. Methode aufrufen
customers.devices.unclaim
, um Anspruch auf ein Gerät zurückzuziehen
von einem Unternehmen.
Das folgende Beispiel zeigt, wie Sie die Inhaberschaft für ein Gerät über eine IMEI-Nummer zurückziehen und Herstellername:
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()
Gerätemetadaten
Ein IT-Administrator kann Metadaten sehen, die vom Reseller an das Gerät angehängt wurden. Anzeige diese Gerätemetadaten in Ihrer App, damit IT-Administratoren Geräte leichter erkennen können.
Weitere Informationen zu den Metadaten, die möglicherweise angezeigt werden, findest du in diesem Artikel zum Gerät Metadaten für Reseller.
Seitenergebnisse
Die API-Methode customers.devices.list
gibt möglicherweise
sehr umfangreiche Gerätelisten. Um die Antwortgröße zu reduzieren, unterstützen diese und andere API-Methoden (z. B. customers.list
) paginierte Ergebnisse. Mit
Seitenergebnisse enthält, kann Ihre Anwendung große Listen iterativ anfordern und verarbeiten.
auf einer Seite nach der anderen an.
Prüfe nach dem Aufruf der API-Methode, ob die Antwort einen Wert für nextPageToken
enthält. Wenn nextPageToken
nicht
null
, kann deine App damit eine andere Seite mit Geräten abrufen, indem die
noch einmal an. Sie müssen eine Obergrenze für die Anzahl der Geräte in der
pageSize
-Parameter. Wenn nextPageToken
den Wert null
hat, hat Ihre App den
auf der letzten Seite.
Die folgende Beispielmethode zeigt, wie Ihre App eine Liste von Geräten Seite für Seite drucken könnte:
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'])
Erste Schritte
Lesen Sie als Nächstes unter Autorisierung, wie API-Aufrufe autorisiert werden. Wenn Sie erhalten Sie in den Kurzanleitungen Java .NET und Python Sie können einen colab zum Ansehen Beispiele für API-Aufrufe und experimentieren Sie mit dem API-Aufruf.