İşleyiş şekli

Müşteri API'si, Android el değmeden kayıt özelliği için cihazlar ve yapılandırma üzerinde programatik kontrol sağlar. Bu belgede, API'den kurumsal mobilite yönetimi (EMM) sağlayıcıları ve kurumsal BT için birlikte çalışır. Bu belgeyi okuduktan sonra temel kavram, API'da kullanılan kaynaklar ve bunların etkileşim kurma biçimleri. El değmeden kayıt özelliğini kullanmaya yeni başladıysanız hakkında daha fazla bilgi edinmek için android.com giriş bölümüne bakın.

Genel Bakış

Müşteri API'si, Android el değmeden kayıt özelliğini satın alan kuruluşlara yardımcı olur. cihazlar. Uygulamanız veya aracınız, BT yöneticilerinin aşağıdakileri yapmasına yardımcı olabilir:

• Temel hazırlık yapılandırmaları oluşturun, düzenleyin ve silin.
• Bir cihaza yapılandırma uygulayabilir veya kaldırabilirsiniz.
• El değmeden kayıt özelliğine eklenen tüm cihazlar için varsayılan yapılandırma seçin devam edebilir.

BT yöneticileri, API aracılığıyla cihazların el değmeden kayıt kaydını da iptal edebilir. kayıt. BT yöneticileri, kuruluşlarının kullanıcılarını yönetmek veya Hizmet Şartları'nı kabul etmek için el değmeden kayıt portalını kullanır.

Bu API'nin genel kullanıcıları şunlar olabilir:

• EMM sağlayıcıları, konsollarına el değmeden kayıt için destek ekliyor.
• El değmeden kayıt görevlerini otomatikleştirmek için araçlar oluşturan kurumsal BT geliştiricileri.

Temel kaynaklar

Yapılandırmalar ve cihazlar, API'de kullandığınız temel kaynaklardır. el değmeden kayıt özelliğini kullanarak konfigürasyonlar ve cihazlar da oluşturabilir. kayıt portalına gidin.

Yapılandırma

BT yöneticileri, yapılandırma kullanarak cihazlar için temel hazırlık seçeneklerini belirler. Yapılandırmalar, EMM mobil politikalarını ve kullanıcılara yardımcı olabilir. Yapılandırmalar API'nin merkezindedir; bu nedenle bunları birçok yöntemlerine göz atın. Daha fazla bilgi edinmek için aşağıdaki Yapılandırmalar bölümüne bakın.

Cihaz

Kuruluşun satın aldığı, el değmeden kayıt özellikli Android cihaz bayisi olabilir. Cihazı el değmeden kayıt moduna dahil etmek için bir yapılandırma uygulayın. kayıt. Cihazların donanım kimlikleri ve ekli meta verileri vardır. Daha fazla bilgi edinmek için bkz. Cihazlar bölümünü inceleyin.

DPC

Bir EMM'nin DPC'sine (cihaz politikası) salt okunur referans denetleyici) ekleyebilirsiniz. Cihazlar için EMM çözümünü seçmek üzere bir yapılandırmaya DPC ekleyin. Listelenen tüm DPC'ler Google Play'de kullanıma sunulmaktadır. Alıcı: Daha fazla bilgi için bkz. Dpc.

Uygulamanızın kullanabileceği tüm API yöntemlerini ve kaynaklarını listelemek için şu sayfaya bakın: API Referansı.

Yapılandırmalar

Configuration API kaynağı, takip etmek için:

• Cihazlara yüklenen EMM'nin DPC'si.
• Cihazlarda EMM politikaları zorunlu kılındı.
• Kurulum sırasında kullanıcılara yardımcı olmak için cihazda görüntülenen iletişim bilgileri.

Uygulamanız, API'yi kullanarak BT yöneticilerinin yapılandırmaları yönetebilir. API'yi yapılandırma, getirme, güncelleme ve silme işlemlerini yapabilir. Aşağıdaki örnekte yeni bir yapılandırmanın nasıl oluşturulacağı gösterilmektedir:

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

Bir yapılandırmayı, yama API'sini kullanarak güncellerken alan maskesini veya null olmasını istemediğiniz her alan için bir değer eklemeyi unutmayın. Bir yapılandırmanın nasıl verimli bir şekilde güncelleneceğini gösteren bir örnek için Varsayılan yapılandırmalar'a (aşağıda) bakın.

Yapılandırmaları silin

Hâlâ cihazlara uygulanmış olan bir yapılandırmayı silemezsiniz. Örneğin kullanımdaki bir yapılandırmayı silerseniz API yöntemi bir HTTP 400 Bad Request döndürür durum kodu ve yapılandırmayı kullanan cihaz sayısını açıklayan bir mesaj gösterilir. Telefonla arama customers.devices.removeConfiguration kullanarak tekrar denemeden önce yapılandırmayı cihazlardan kaldırın.

Varsayılan yapılandırmalar

El değmeden kayıt özelliği, kuruluş varsayılan olarak ayarladığında en iyi sonucu verir kuruluşun satın aldığı yeni cihazlara uygulanan yapılandırma. Ayarlanmamışsa BT yöneticilerinden varsayılan bir yapılandırma belirlemelerini isteyebilirsiniz. Aşağıdaki örnekte, mevcut bir yapılandırmanın isDefault, true olarak ayarlanıyor:

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

Yalnızca bir varsayılan yapılandırma olabilir. Yeni bir varsayılan yapılandırma oluşturduğunuzda, önceki bir yapılandırmanın isDefault alanını false olarak ayarlar. Şunları yapmanız gerekebilir: doğru değerleri görmek için önbelleğe alınan tüm Configuration örneklerini yenileyin isDefault alanları.

Cihaz kullanıcılarına rehberlik et

El değmeden kayıt yapılandırması, cihazın kurulumunda özelleştirilmiş kullanıcı rehberliği gösterir Kullanıcılara yardım eden sihirbaz. İletişim telefon numarası ve e-posta adresi eklemeniz gerekiyor adresini ve cihazı yöneten kuruluşun adını yapılandırma. Ayrıca, customMessage alanında kullanıcının olanak tanır.

Kullanıcı, ayarlama yaptığı cihazdan telefon veya e-posta gönderemeyeceği için bilgilere göz atmayı kolaylaştırmak amacıyla telefon numarasını ve e-posta adresini biçimlendirin.

Cihazlar

Müşteriler el değmeden kayıt için cihaz satın aldığında bayiler cihaz oluşturur. BT yöneticileri cihaz oluşturamaz. Cihazlarla çalışmak için Device API kaynağındaki yöntemleri çağırın. Arama yapmanız gerekirse cihazlar için tüm cihazları listeleyin ve her grubu uygulamanızda yerel olarak filtreleyin. Örneğin, Aşağıdaki Sayfalandırılmış sonuçlar bölümünü inceleyin.

Cihazları yapılandırma

Bir cihaza yapılandırma uygulandığında cihaz el değmeden kayıt için kaydedilir kayıt. Yapılandırma uygulamak için şu çağrıyı yapın: customers.devices.applyConfiguration. Bir yapılandırma uygulandıktan sonra cihaz şurada kendi temel hazırlığını otomatik olarak yapar: yoksa sonraki fabrika ayarlarına sıfırlama işlemi de olabilir. Aşağıdaki örnekte, bir yapılandırma:

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

Yapılandırmayı bir cihazdan kaldırmak için şu numarayı arayın: customers.devices.removeConfiguration. Değişiklik, cihaz fabrika ayarlarına sıfırlandıktan sonra geçerli olur.

Cihazların talebini iptal et

BT yöneticileri, bir cihazın el değmeden kayıttan kaldırılması için cihazın sahipliğini iptal edebilir. BT Yönetici, başka bir hesaba taşınmasını, satılmasını veya satılmasını istediği bir cihazın hak talebini iptal edebilir. veya bayiye iade edildi. Yöntemi çağırın Bir cihaz hak talebini iptal etmek için customers.devices.unclaim bir kurumdan bahsetmek istiyorum.

Dikkat: Uygulamanızın kullanıcısından hak talebi iptali API'lerini çağırmadan önce doğru cihazı kullanın. Bir cihazın sahipliğini iptal ettiğinizde kuruluşun temel hazırlık kurulumu kaldırılır ve cihaz fabrika ayarlarına sıfırlandıktan sonra yönetilme durumuna geçer. BT yöneticisi, cihazı el değmeden kayıt için tekrar kaydetmek istiyorsa bayiyle iletişime geçmelidir.

Aşağıdaki örnekte, IMEI numarasından bir cihaz için hak talebinin nasıl iptal edileceği ve üreticinin adı:

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

Cihaz meta verileri

BT yöneticisi, bayi tarafından cihaza eklenen meta verileri görebilir. Görüntülü Reklam Ağı BT yöneticilerinin cihazları tanımasına yardımcı olmak için uygulamanızda bu cihaz meta verilerini kullanabilirsiniz.

Görebileceğiniz meta veriler hakkında daha fazla bilgi edinmek için Cihaz meta veriler kılavuzundan yararlanabilirsiniz.

Sayfalandırılmış sonuçlar

customers.devices.list API yöntemi dönebilir çok sayıda cihaz bulunur. Yanıt boyutunu küçültmek için bu API ve diğer API yöntemleri (ör. customers.list), sayfalandırılmış sonuçları destekler. Entegre sayfalandırılmış sonuçlar, uygulamanız yinelenen şekilde büyük listeleri isteyebilir ve işleyebilir tek seferde bir sayfaya gelecektir.

API yöntemini çağırdıktan sonra yanıtta nextPageToken için bir değer olup olmadığını kontrol edin. nextPageToken sizin için uygun değilse null, uygulamanız yöntemini tekrar deneyin. Şuradaki cihaz sayısı için bir üst sınır belirlemeniz gerekir: pageSize parametresinden yararlanın. nextPageToken null ise uygulamanız son sayfa.

Aşağıdaki örnek yöntem, uygulamanızın bir cihaz listesini nasıl yazdırabileceğini gösterir. bir sayfa görüntüleme:

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'])

Başlayın

Ardından Yetkilendirme bölümünde API çağrılarının nasıl yetkilendirileceğini okuyun. API'leri keşfetmek istiyorsanız Java, .NET ve Python için hızlı başlangıç kılavuzlarına göz atın. URL parametrelerinin Google tarafından nasıl ele alınmasını istediğinizi belirtmek için görüntülemek için colab örneklerine göz atın ve API'yi kendi başınıza çağırmayı deneyin.