Diese Seite wurde von der Cloud Translation API übersetzt.

Ablauf

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.

Beziehung zwischen Gerät und Kundenressource

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.