İşleyiş şekli

customer API, Android el değmeden kayıt için cihazların ve yapılandırmanın programatik kontrolünü sağlar. Bu belgede, kurumsal mobilite yönetimi (EMM) sağlayıcıları ve kurumsal BT geliştiricileri ile ilgili API tanıtılmaktadır. Bu belgeyi okuduktan sonra, API'de kullanılan temel kaynakları ve bunların birbiriyle nasıl etkileşime girdiğini anlamanız gerekir. El değmeden kayıt konusunda yeniyseniz kısa android.com tanıtımını okuyun.

Genel bakış

Müşteri API'si, Android el değmeden kayıt özellikli cihazlar satın alan kuruluşlara yardımcı olur. 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şturma, düzenleme ve silme
• Yapılandırmayı bir cihaza uygulayın veya kaldırın.
• Bundan sonra el değmeden kayıt sürecine eklenecek tüm cihazlar için varsayılan bir yapılandırma seçin.

BT yöneticileri, API aracılığıyla cihazların el değmeden kayıt kaydını iptal edebilir. BT yöneticileri el değmeden kayıt portalını kullanarak kuruluşlarının kullanıcılarını yönetebilir veya Hizmet Şartları'nı kabul edebilirler.

Bu API'nin tipik kullanıcıları arasında şunlar olabilir:

• EMM sağlayıcıları konsollarına el değmeden kayıt desteği 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. Ayrıca kuruluşlar, el değmeden kayıt portalını kullanarak yapılandırmalar ve cihazlar oluşturabilir.

Yapılandırma

BT yöneticileri, cihazlar için temel hazırlık seçeneklerini bir yapılandırma kullanarak ayarladı. Yapılandırmalar, EMM mobil politikalarını ve kullanıcılara yardımcı olmak için gösterilen iletişim bilgilerini içerir. Yapılandırmalar API'nin merkezinde yer aldığı için bunları birçok yöntemde kullanabilirsiniz. Daha fazla bilgi edinmek için aşağıdaki Yapılandırmalar bölümüne bakın.

Cihaz

Bir kuruluşun bayisinden satın aldığı, el değmeden kayıt özellikli bir Android cihaz. Cihazı el değmeden kayıt sürecine dahil etmek için bir yapılandırma uygulayın. Cihazlarda donanım kimlikleri ve ekli meta veriler bulunur. Daha fazla bilgi edinmek için aşağıdaki Cihazlar bölümüne bakın.

DPC

Bir EMM'nin DPC'sine (cihaz politikası denetleyici) salt okunur referans. Cihazlar için EMM çözümünü seçmek üzere bir yapılandırmaya DPC ekleyin. API tarafından listelenen tüm DPC'ler el değmeden kaydı destekler ve Google Play'de kullanılabilir. Daha fazla bilgi için Dpc sayfasını inceleyin.

Uygulamanızın kullanabileceği tüm API yöntemlerini ve kaynakları listelemek için API Referansı'nı inceleyin.

Yapılandırmalar

Configuration API kaynağında şu bilgiler yer alır:

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

Uygulamanız, API'yi kullanarak BT yöneticilerinin yapılandırmalarını yönetebilir. Yapılandırmaları getirmek, oluşturmak, güncellemek ve silmek için API'yi çağırın. 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()

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

Yapılandırmaları sil

Hâlâ cihazlara uygulanmış olan yapılandırmayı silemezsiniz. Kullanımdaki bir yapılandırmayı silmeye çalışırsanız API yöntemi, HTTP 400 Bad Request durum kodu ve yapılandırmayı kaç cihazın kullandığını açıklayan bir mesaj döndürür. Tekrar denemeden önce cihazlardan yapılandırmayı kaldırmak için customers.devices.removeConfiguration numaralı telefonu arayın.

Varsayılan yapılandırmalar

El değmeden kayıt, bir kuruluşun satın aldığı tüm yeni cihazlara uygulanan varsayılan bir yapılandırma ayarladığında en iyi sonucu verir. Ayarlanmamışsa BT yöneticilerinden varsayılan bir yapılandırma belirlemelerini isteyebilirsiniz. Aşağıdaki örnekte, isDefault ayarını true yaparak mevcut bir yapılandırmanın nasıl varsayılan ayarlanacağı gösterilmektedir:

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 tane varsayılan yapılandırma olabilir. Yeni bir varsayılan yapılandırma oluşturduğunuzda, önceki yapılandırmanın isDefault alanını false olarak ayarlar. isDefault alanlarında doğru değerleri görmek için önbelleğe alınan Configuration örneklerini yenilemeniz gerekebilir.

Cihaz kullanıcılarına rehberlik et

El değmeden yapılandırma, kullanıcılara yardımcı olmak için cihaz Kurulum Sihirbazı'nda özelleştirilmiş kullanıcı rehberliği görüntüler. Yapılandırmada, cihazı yöneten kuruluşun adıyla birlikte iletişim telefon numarası ve e-posta adresi belirtmeniz gerekir. Ayrıca, bir kullanıcının cihazına ne olduğu hakkında daha ayrıntılı bilgi vermek için customMessage alanına bir veya iki cümle eklemenizi öneririz.

Kullanıcı, kurulumunu yaptığı cihazdan arayamayacağı veya e-posta gönderemeyeceği için telefon numarasını ve e-posta adresini, bilgilere göz atmayı kolaylaştıracak şekilde biçimlendirin.

Cihazlar

Bayiler, bir müşteri el değmeden kayıt için satın aldığı cihazları oluşturur. BT yöneticileri cihaz oluşturamaz. Cihazlarla çalışmak için Device API kaynağındaki yöntemleri çağırın. Cihazları aramanız gerekiyorsa tüm cihazları listeleyin ve her bir grubu uygulamanızda yerel olarak filtreleyin. Örnek için aşağıdaki Sayfalandırılmış sonuçlar bölümüne bakın.

Cihazları yapılandırın

Yapılandırma uygulanan cihazlar, el değmeden kayıt için kaydedilir. Bir yapılandırma uygulamak için customers.devices.applyConfiguration numaralı telefonu arayın. Bir yapılandırma uygulandıktan sonra, cihaz ilk başlatmada veya daha sonra fabrika ayarlarına sıfırlandığında, temel hazırlığını otomatik olarak kendisi yapar. Aşağıdaki örnekte, bir yapılandırmayı bir cihaz grubuna nasıl uygulayabileceğiniz gösterilmektedir:

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 customers.devices.removeConfiguration numaralı telefonu arayın. Değişiklik, cihaz fabrika ayarlarına sıfırlandıktan sonra geçerli olur.

Cihazların talebini iptal et

BT yöneticileri, el değmeden kayıt sürecindeki bir cihazı kaldırmak için hak talebini iptal edebilir. BT yöneticisi; başka bir hesaba taşınmasını, satılmasını veya bayiye iade edilmesini istediği bir cihazın talebini iptal edebilir. Bir cihazın kuruluşla ilgili hak talebini iptal etmek için customers.devices.unclaim yöntemini çağırın.

Dikkat: API'lerin hak talebini iptal etmeden önce uygulamanızın kullanıcısından, doğru cihaza sahip olduğunu onaylamasını isteyebilirsiniz. Bir cihazın hak talebi iptal edildiğinde, kuruluşun temel hazırlık kurulumu kaldırılır ve cihaz, fabrika ayarlarına sıfırlandıktan sonra yönetilmiyor hale gelir. Cihazı el değmeden kayıt için tekrar kaydetmek isterse BT yöneticisi, bayisiyle iletişime geçmelidir.

Aşağıdaki örnekte, bir cihazın IMEI numarası ve üretici adıyla ilgili hak talebi iptalinin nasıl iptal edileceği gösterilmektedir:

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. BT yöneticilerinin cihazları tanımasına yardımcı olmak için uygulamanızda bu cihaz meta verilerini görüntüleyin.

Görebileceğiniz meta veriler hakkında daha fazla bilgi edinmek için bayiler için Cihaz meta verileri kılavuzunu okuyun.

Sayfalara ayrılmış sonuçlar

customers.devices.list API yöntemi çok büyük cihaz listeleri döndürebilir. Yanıt boyutunu azaltmak için bu ve diğer API yöntemleri (ör. customers.list) sayfalık sonuçları destekler. Sayfalandırılmış sonuçlar sayesinde uygulamanız, büyük listeleri her seferinde tek bir sayfa için tekrar tekrar isteyebilir ve işleyebilir.

API yöntemini çağırdıktan sonra, yanıtın nextPageToken için bir değer içerip içermediğini kontrol edin. nextPageToken, null değilse uygulamanız bu yöntemi tekrar çağırarak başka bir cihaz sayfası getirmek için kullanabilir. pageSize parametresinde cihaz sayısı için üst sınır ayarlamanız gerekir. nextPageToken değeri null ise uygulamanız son sayfayı istemiştir.

Aşağıdaki örnek yöntemde, uygulamanızın cihaz listesini nasıl yazdırabileceği gösterilmektedir.

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

Daha sonra Yetkilendirme bölümünde API çağrılarını nasıl yetkilendireceğinizi okuyun. API'leri keşfetmek istiyorsanız Java, .NET ve Python hızlı başlangıç kılavuzlarına göz atın. API çağrısı örneklerini görüntülemek ve API'yi kendiniz çağırmak için denemeler yapmak için colab kullanabilirsiniz.