Funktionsweise

Die Kunden-API ermöglicht die programmatische Kontrolle über Geräte und die Konfiguration für die Zero-Touch-Registrierung von Android. In diesem Dokument wird die API für EMM-Anbieter (Enterprise Mobility Management) und IT-Entwickler in Unternehmen vorgestellt. Nachdem Sie dieses Dokument gelesen haben, sollten Sie mit den in der API verwendeten Kernressourcen und ihrer Interaktion vertraut sein. Wenn Sie die Zero-Touch-Registrierung noch nicht kennen, lesen Sie die kurze Einführung unter android.com.

Übersicht

Die Kunden-API unterstützt Organisationen, die Android-Geräte mit Zero-Touch-Registrierung kaufen. Mit Ihrer App oder Ihrem Tool können IT-Administratoren Folgendes tun:

• Nutzerverwaltungskonfigurationen erstellen, bearbeiten und löschen.
• Konfiguration auf ein Gerät anwenden oder daraus entfernen
• Wählen Sie eine Standardkonfiguration für alle Geräte aus, die zukünftig der Zero-Touch-Registrierung hinzugefügt werden.

Über die API können IT-Administratoren auch Geräte von der Zero-Touch-Registrierung abmelden. IT-Administratoren können das Portal zur Zero-Touch-Registrierung verwenden, um die Nutzer ihrer Organisation zu verwalten oder die Nutzungsbedingungen zu akzeptieren.

Typische Nutzer dieser API:

• EMM-Anbieter, die ihrer Konsole Unterstützung für die Zero-Touch-Registrierung hinzufügen
• IT-Entwickler in Unternehmen, die Tools zur Automatisierung von Zero-Touch-Registrierungsaufgaben erstellen

Wichtige Ressourcen

Konfigurationen und Geräte sind die Hauptressourcen, die Sie in der API verwenden. Eine Organisation kann Konfigurationen und Geräte auch über das Portal für die Zero-Touch-Registrierung erstellen.

Konfiguration

IT-Administratoren legen mithilfe einer Konfiguration Bereitstellungsoptionen für Geräte fest. Konfigurationen umfassen EMM-Richtlinien für Mobilgeräte und Kontaktdaten, die Nutzern angezeigt werden. Konfigurationen sind von zentraler Bedeutung für die API und werden daher in vielen Methoden verwendet. Weitere Informationen finden Sie unten im Abschnitt Konfigurationen.

Gerät

Ein Android-Gerät mit Zero-Touch-Registrierung, das eine Organisation bei ihrem Reseller gekauft hat. Wenden Sie eine Konfiguration an, um das Gerät in die Zero-Touch-Registrierung aufzunehmen. Geräte haben Hardware-IDs und angehängte Metadaten. Weitere Informationen finden Sie unten unter Geräte.

DPC

Eine schreibgeschützte Referenz auf den DPC (Device Policy Controller) eines EMM-Anbieters. Fügen Sie einer Konfiguration einen DPC hinzu, um die EMM-Lösung für Geräte auszuwählen. Alle in der API aufgeführten DPCs unterstützen die Zero-Touch-Registrierung und sind bei Google Play verfügbar. Weitere Informationen finden Sie unter Dpc.

Eine Liste aller API-Methoden und -Ressourcen, die die Anwendung verwenden kann, finden Sie in der API-Referenz.

Konfigurationen

Die API-Ressource Configuration umfasst Folgendes:

• Der DPC des EMM, der auf den Geräten installiert ist.
• EMM-Richtlinien, die auf den Geräten erzwungen werden
• Auf dem Gerät angezeigte Kontaktdaten, die Nutzern bei der Einrichtung helfen.

Mithilfe der API kann Ihre App Konfigurationen für IT-Administratoren verwalten. Rufen Sie die API auf, um Konfigurationen abzurufen, zu erstellen, zu aktualisieren und zu löschen. Das folgende Beispiel zeigt, wie Sie eine neue Konfiguration erstellen:

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

Wenn Sie eine Konfiguration mit der Patch API aktualisieren, müssen Sie die Feldmaske oder einen Wert für jedes Feld angeben, das nicht null sein soll. Unter Standardkonfigurationen (unten) finden Sie ein Beispiel, das zeigt, 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 verwendete Konfiguration zu löschen, gibt die API-Methode den HTTP-Statuscode 400 Bad Request und eine Meldung zurück, in der angegeben ist, wie viele Geräte die Konfiguration verwenden. Rufen Sie customers.devices.removeConfiguration auf, 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 eine Standardkonfiguration festlegt, die auf alle neuen Geräte angewendet wird, die die Organisation kauft. Sie können IT-Administratoren auffordern, eine Standardkonfiguration festzulegen, falls dies nicht der Fall ist. Das folgende Beispiel zeigt, wie Sie eine vorhandene Konfiguration als Standard festlegen, indem Sie isDefault auf true setzen:

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 einer vorherigen Konfiguration auf false gesetzt. Unter Umständen müssen Sie im Cache gespeicherte Configuration-Instanzen aktualisieren, um die korrekten Werte in den isDefault-Feldern zu sehen.

Gerätenutzer anleiten

Die Zero-Touch-Konfiguration zeigt eine benutzerdefinierte Nutzerführung im Einrichtungsassistenten an, um Nutzern zu helfen. Sie müssen eine Kontakttelefonnummer und eine E-Mail-Adresse sowie den Namen der Organisation angeben, die das Gerät in einer Konfiguration verwaltet. Wir empfehlen außerdem, ein oder zwei Sätze in das Feld customMessage aufzunehmen, um genauer zu erklären, was mit dem Gerät eines Nutzers geschieht.

Da der Nutzer von dem Gerät, das er einrichtet, weder anrufen noch E-Mails senden kann, sollten Sie die Telefonnummer und E-Mail-Adresse formatieren, damit Sie die Informationen leichter auf einen Blick sehen können.

Geräte

Reseller erstellen Geräte, wenn ein Kunde sie für die Zero-Touch-Registrierung erwirbt. IT-Administratoren können keine Geräte erstellen. Wenn Sie mit Geräten arbeiten möchten, rufen Sie Methoden für die API-Ressource Device auf. Wenn Sie nach Geräten suchen müssen, listen Sie alle Geräte auf und filtern Sie jeden Batch lokal in Ihrer App. Ein Beispiel finden Sie unten unter Ausgewählte Ergebnisse.

Geräte konfigurieren

Wenn Sie eine Konfiguration auf ein Gerät anwenden, wird es für die Zero-Touch-Registrierung registriert. Rufen Sie zum Anwenden einer Konfiguration customers.devices.applyConfiguration auf. Nach dem Anwenden einer Konfiguration stellt sich das Gerät beim ersten Start oder beim nächsten Zurücksetzen auf die Werkseinstellungen automatisch bereit. Das folgende Beispiel zeigt, wie Sie eine Konfiguration auf eine Sammlung von Geräten anwenden können:

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

Rufen Sie customers.devices.removeConfiguration auf, um die Konfiguration von einem Gerät zu entfernen. Die Änderung wird nach dem Zurücksetzen des Geräts auf die Werkseinstellungen wirksam.

Anspruch auf Geräte aufheben

IT-Administratoren können den Anspruch auf ein Gerät zurückziehen, um es aus der Zero-Touch-Registrierung zu entfernen. Ein IT-Administrator kann den Anspruch auf ein Gerät zurückziehen, das zu einem anderen Konto migriert, verkauft oder an den Reseller zurückgegeben werden soll. Rufen Sie die Methode customers.devices.unclaim auf, um den Anspruch auf ein Gerät in einer Organisation aufzuheben.

Achtung :Sie sollten den Nutzer Ihrer App auffordern, zu bestätigen, dass er das richtige Gerät hat, bevor Sie APIs zum Aufheben der Inhaberschaft aufrufen. Wenn Sie den Anspruch auf ein Gerät aufheben, wird die Bereitstellungseinrichtung der Organisation entfernt und das Gerät wird nach dem Zurücksetzen auf die Werkseinstellungen nicht mehr verwaltet. Der IT-Administrator muss sich an seinen Reseller wenden, wenn er das Gerät noch einmal für die Zero-Touch-Registrierung registrieren möchte.

Das folgende Beispiel zeigt, wie Sie die Verknüpfung eines Geräts mit einer IMEI-Nummer und einem Herstellernamen aufheben:

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 die vom Reseller an das Gerät angehängten Metadaten sehen. Zeigen Sie diese Gerätemetadaten in Ihrer App an, damit IT-Administratoren Geräte leichter erkennen können.

Weitere Informationen zu den Metadaten, die möglicherweise angezeigt werden, finden Sie im Leitfaden zu Gerätemetadaten für Reseller.

Seitenbezogene Ergebnisse

Die API-Methode customers.devices.list gibt möglicherweise sehr große Listen von Geräten zurück. Diese und andere API-Methoden wie customers.list unterstützen ausgelagerte Ergebnisse, um die Antwortgröße zu reduzieren. Mit ausgelagerten Ergebnissen kann Ihre Anwendung iterativ große Listen seitenweise anfordern und verarbeiten.

Prüfen Sie nach dem Aufrufen der API-Methode, ob die Antwort einen Wert für nextPageToken enthält. Wenn nextPageToken nicht null ist, kann deine App damit eine weitere Seite mit Geräten abrufen, indem die Methode noch einmal aufgerufen wird. Sie müssen im Parameter pageSize eine Obergrenze für die Anzahl der Geräte festlegen. Wenn nextPageToken den Wert null hat, hat Ihre Anwendung die letzte Seite angefordert.

Die folgende Beispielmethode zeigt, wie Ihre App eine Seite für eine Liste von Geräten ausgeben 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. Weitere Informationen zu den APIs finden Sie in den Kurzanleitungen für Java, .NET und Python. In Collab können Sie sich Beispiele für API-Aufrufe ansehen und die API testen.