Przewodnik po integracji EMM

Ten przewodnik ułatwia dostawcom usług zarządzania urządzeniami mobilnymi (EMM) integrację rejestracji typu zero-touch z ich konsolą. Czytaj dalej, aby dowiedzieć się więcej o rejestrowaniu i poznać sprawdzone metody, które pomogą Twojemu DPC (kontroler zasad dotyczących urządzeń) w udostępnianiu urządzeń. Jeśli masz DPC, poznasz sprawdzone metody udostępniania urządzeń oraz otrzymasz porady, które pomogą Ci w programowaniu i testowaniu.

Funkcje dla administratorów IT

Użyj interfejsu API klienta, aby pomóc administratorom IT skonfigurować rejestrację typu zero-touch bezpośrednio w konsoli. Oto niektóre czynności, które administrator IT może wykonywać w konsoli:

  • Twórz, edytuj i usuwaj konfiguracje rejestracji typu zero-touch na podstawie zasad dotyczących urządzeń mobilnych.
  • Ustaw domyślną konfigurację, aby DPC udostępniała w przyszłości urządzenia kupowane przez organizację.
  • Zastosuj poszczególne konfiguracje na urządzeniach lub usuń urządzenia z rejestracji typu zero-touch.

Więcej informacji o rejestracji typu zero-touch znajdziesz w omówieniu.

Wymagania wstępne

Zanim dodasz rejestrację typu zero-touch do konsoli EMM, sprawdź, czy Twoje rozwiązanie obsługuje te funkcje:

  • Twoje rozwiązanie EMM musi udostępnić należące do firmy urządzenie z Androidem 8.0 lub nowszym (Pixel 7.1 lub nowsze) w trybie pełnego zarządzania. Należące do firmy urządzenia z Androidem 10 lub nowszym mogą być udostępniane jako w pełni zarządzane lub z profilem służbowym.
  • Rejestracja typu zero-touch automatycznie pobiera i instaluje DPC, dlatego musi być dostępna w Google Play. Utrzymujemy listę zgodnych DPC, które administratorzy IT mogą konfigurować za pomocą interfejsu API klienta lub portalu. Aby dodać DPC do listy, prześlij prośbę o zmodyfikowanie usługi w społeczności dostawców usług EMM.
  • Aby móc wywoływać interfejs API klienta, Twoi klienci muszą mieć konto do rejestracji typu zero-touch. Sprzedawca partnerski konfiguruje konto dla organizacji administratora IT, gdy organizacja kupuje urządzenia.
  • Aby rejestracja typu zero-touch działała prawidłowo, urządzenie musi być zgodne z Usługami mobilnymi Google (GMS), a Usługi Google Play muszą być zawsze włączone.

Wywoływanie interfejsu API

Użytkownicy Twojej konsoli (korzystając ze swoich kont Google) autoryzują Twoje żądania do interfejsu API klienta. Różni się on od autoryzacji, którą przeprowadzasz dla innych interfejsów API EMM. Przeczytaj artykuł Autoryzacja, aby dowiedzieć się, jak to zrobić w swojej aplikacji.

Warunki korzystania z usługi

Przed wywołaniem interfejsu API użytkownicy muszą zaakceptować najnowsze Warunki korzystania z usługi. Jeśli wywołanie interfejsu API zwraca kod stanu HTTP 403 Forbidden, a treści odpowiedzi zawierają TosError, poproś użytkownika o zaakceptowanie Warunków korzystania z usługi przez zalogowanie się w portalu rejestracji typu zero-touch. Poniższy przykład pokazuje, jak można to zrobić:

Java

// Authorize this method call as a user that hasn't yet accepted the ToS.
final String googleApiFormatHttpHeader = "X-GOOG-API-FORMAT-VERSION";
final String googleApiFormatVersion = "2";
final String tosErrorType =
      "type.googleapis.com/google.android.device.provisioning.v1.TosError";

try {
  // Send an API request to list all the DPCs available including the HTTP header
  // X-GOOG-API-FORMAT-VERSION with the value 2. Import the  exception:
  // from googleapiclient.errors import HttpError
  AndroidProvisioningPartner.Customers.Dpcs.List request =
        service.customers().dpcs().list(customerAccount);
  request.getRequestHeaders().put(googleApiFormatHttpHeader, googleApiFormatVersion);
  CustomerListDpcsResponse response = request.execute();
  return response.getDpcs();

} catch (GoogleJsonResponseException e) {
  // Get the error details. In your app, check details exists first.
  ArrayList<Map> details = (ArrayList<Map>) e.getDetails().get("details");
  for (Map detail : details) {
    if (detail.get("@type").equals(tosErrorType)
          && (boolean) detail.get("latestTosAccepted") != true) {
      // Ask the user to accept the ToS. If they agree, open the portal in a browser.
      // ...
    }
  }
  return null;
}

.NET

// Authorize this method call as a user that hasn't yet accepted the ToS.
try
{
    var request = service.Customers.Dpcs.List(customerAccount);
    CustomerListDpcsResponse response = request.Execute();
    return response.Dpcs;
}
catch (GoogleApiException e)
{
    foreach (SingleError error in e.Error?.Errors)
    {
        if (error.Message.StartsWith("The user must agree the terms of service"))
        {
            // Ask the user to accept the ToS. If they agree, open the portal in a browser.
            // ...
        }
    }
}

Python

# Authorize this method call as a user that hasn't yet accepted the ToS.
tos_error_type = ('type.googleapis.com/'
                  'google.android.device.provisioning.v1.TosError')
portal_url = 'https://partner.android.com/zerotouch'

# Send an API request to list all the DPCs available including the HTTP
# header X-GOOG-API-FORMAT-VERSION with the value 2. Import the exception:
# from googleapiclient.errors import HttpError
try:
  request = service.customers().dpcs().list(parent=customer_account)
  request.headers['X-GOOG-API-FORMAT-VERSION'] = '2'
  response = request.execute()
  return response['dpcs']

except HttpError as err:
  # Parse the JSON content of the error. In your app, check ToS exists first.
  error = json.loads(err.content)
  tos_error = error['error']['details'][0]

  # Ask the user to accept the ToS (not shown here). If they agree, then open
  # the portal in a browser.
  if (tos_error['@type'] == tos_error_type
      and tos_error['latestTosAccepted'] is not True):
    if raw_input('Accept the ToS in the zero-touch portal? y|n ') == 'y':
      webbrowser.open(portal_url)

Jeśli Twój klient interfejsu API Google obsługuje szczegółowe błędy (żądania w języku Java, Python lub HTTP), dołącz w żądaniach nagłówek HTTP X-GOOG-API-FORMAT-VERSION z wartością 2. Jeśli klient nie obsługuje szczegółowych błędów (.NET i inne), podaj treść komunikatu o błędzie.

Jeśli w przyszłości zaktualizujemy Warunki korzystania z usługi, a Ty skorzystasz z tego sposobu, aplikacja skieruje użytkownika do ponownego zaakceptowania nowych Warunków korzystania z usługi.

Administratorzy IT używają portalu rejestracji typu zero-touch do zarządzania użytkownikami w organizacji – nie można tego zaoferować za pomocą interfejsu API klienta. Administratorzy IT mogą też zarządzać urządzeniami i konfiguracjami za pomocą portalu. Jeśli musisz podać link do portalu w konsoli lub w dokumentacji, użyj tego adresu:

https://partner.android.com/zerotouch

Warto powiadomić administratorów IT, że zostaną poproszeni o zalogowanie się na konto Google.

Rejestrowanie urządzenia

Rejestracja typu zero-touch to mechanizm rejestrowania urządzeń, który działa podobnie do rejestracji NFC lub rejestracji za pomocą kodu QR. Twoja konsola musi obsługiwać urządzenia zarządzane, a DPC musi działać w trybie w pełni zarządzanym.

Rejestracja typu zero-touch jest dostępna na obsługiwanych urządzeniach z Androidem 8.0 lub nowszym. Administratorzy IT muszą kupić obsługiwane urządzenia od partnera sprzedawcy. Konsola może śledzić, które z urządzeń administratora IT są dostępne do rejestracji typu zero-touch, wywołując metodę customers.devices.list.

Proces rejestracji przebiega w ten sposób:

  1. Urządzenie sprawdza się na serwerze Google przy pierwszym uruchomieniu (lub po przywróceniu do ustawień fabrycznych) pod kątem rejestracji typu zero-touch.
  2. Jeśli administrator IT zastosował konfigurację na urządzeniu, rejestracja typu zero-touch uruchomi kreator konfiguracji w pełni zarządzanym urządzenia z Androidem i dostosowuje ekrany, korzystając z metadanych z konfiguracji.
  3. Rejestracja typu zero-touch umożliwia pobranie i zainstalowanie DPC z Google Play.
  4. DPC otrzymuje intencję ACTION_PROVISION_MANAGED_DEVICE i udostępnia urządzenie.

Jeśli nie masz połączenia z internetem, sprawdzenie nastąpi, gdy będzie dostępne. Więcej informacji o obsłudze administracyjnej urządzeń w ramach rejestracji typu zero-touch znajdziesz w sekcji Obsługa administracyjna poniżej.

Konfiguracje domyślne

Rejestracja typu zero-touch jest najbardziej przydatna dla administratorów IT, gdy ustawiają domyślną konfigurację, która jest stosowana do wszystkich nowych urządzeń kupionych przez organizację. Zmień ustawienie domyślnej konfiguracji w konsoli. Możesz sprawdzić wartość customers.configurations.isDefault, aby dowiedzieć się, czy organizacja ustawiła konfigurację domyślną.

Poniższy przykład pokazuje, jak możesz ustawić istniejącą konfigurację jako domyślną:

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

Odniesienia do DPC

Zalecamy użycie nazwy zasobu interfejsu API customers.dpcs.name do identyfikacji DPC i używania jej w konfiguracjach. Nazwa zasobu zawiera unikalny i niezmienny identyfikator DPC. Zadzwoń pod numer customers.dpcs.list, aby uzyskać listę wszystkich obsługiwanych DPC. Nazwa zasobu zawiera też identyfikator klienta, dlatego przefiltruj listę za pomocą ostatniego komponentu ścieżki, aby znaleźć pasującą instancję Dpc. Z przykładu poniżej dowiesz się, jak dopasować jednostkę DPC i utrzymać ją później w konfiguracji:

Java

// Return a customer Dpc instance for the specified DPC ID.
String myDpcIdentifier = "AH6Gbe4aiS459wlz58L30cqbbXbUa_JR9...xMSWCiYiuHRWeBbu86Yjq";
final int dpcIdIndex = 3;
final String dpcComponentSeparator = "/";
// ...
for (Dpc dpcApp : dpcs) {
    // Because the DPC name is in the format customers/{CUST_ID}/dpcs/{DPC_ID}, check the
    // fourth component matches the DPC ID.
    String dpcId = dpcApp.getName().split(dpcComponentSeparator)[dpcIdIndex];
    if (dpcId.equals(myDpcIdentifier)) {
        System.out.format("My DPC is: %s\n", dpcApp.getDpcName());
        return dpcApp;
    }
}
// Handle the case when the DPC isn't found...

.NET

// Return a customer Dpc instance for the specified DPC ID.
var myDpcIdentifer = "AH6Gbe4aiS459wlz58L30cqbbXbUa_JR9...fE9WdHcxMSWCiYiuHRWeBbu86Yjq";
const int dpcIdIndex = 3;
const String dpcComponentSeparator = "/";
// ...
foreach (Dpc dpcApp in dpcs)
{
    // Because the DPC name is in the format customers/{CUST_ID}/dpcs/{DPC_ID}, check the
    // fourth component matches the DPC ID.
    String dpcId = dpcApp.Name.Split(dpcComponentSeparator)[dpcIdIndex];
    if (dpcId.Equals(myDpcIdentifer))
    {
        Console.WriteLine("Matched DPC is: {0}", dpcApp.DpcName);
        return dpcApp;
    }
}
// Handle the case when the DPC isn't found...

Python

# Return a customer Dpc instance for the specified DPC ID.
my_dpc_id = 'AH6Gbe4aiS459wlz58L30cqb...fE9WdHcxMSWCiYiuHRWeBbu86Yjq'
# ...
for dpc_app in dpcs:
  # Because the DPC name is in the format customers/{CUST_ID}/dpcs/{DPC_ID},
  # check the fourth component matches the DPC ID.
  dpc_id = dpc_app['name'].split('/')[3]
  if dpc_id == my_dpc_id:
    return dpc_app

# Handle the case when the DPC isn't found...

Jeśli musisz pokazać nazwę DPC w interfejsie konsoli, wyświetl wartość zwrócona z customers.dpcs.dpcName.

Udostępniam

Skorzystaj z okazji, aby zapewnić użytkownikom wygodę podczas obsługi administracyjnej urządzeń. Nazwa użytkownika i hasło powinny być potrzebne do obsługi administracyjnej urządzenia. Pamiętaj, że sprzedawcy mogą wysyłać urządzenia bezpośrednio do użytkowników zdalnych. Uwzględnij wszystkie inne ustawienia, takie jak serwer EMM czy jednostka organizacyjna, w customers.configuration.dpcExtras.

Poniższy fragment kodu JSON przedstawia część przykładowej konfiguracji:

{
  "android.app.extra.PROVISIONING_LOCALE": "en_GB",
  "android.app.extra.PROVISIONING_TIME_ZONE": "Europe/London",
  "android.app.extra.PROVISIONING_LEAVE_ALL_SYSTEM_APPS_ENABLED": true,
  "android.app.extra.PROVISIONING_ADMIN_EXTRAS_BUNDLE": {
    "workflow_type": 3,
    "default_password_quality": 327680,
    "default_min_password_length": 6,
    "company_name": "XYZ Corp",
    "organizational_unit": "sales-uk",
    "management_server": "emm.example.com",
    "detail_tos_url": "https://www.example.com/policies/terms/",
    "allowed_user_domains": "[\"example.com\", \"example.org\", \"example.net\"]"
    }
}

Rejestracja typu zero-touch instaluje i uruchamia DPC za pomocą intencji Androida. System wysyła wartości z właściwości JSON android.app.extra.PROVISIONING_ADMIN_EXTRAS_BUNDLE do DPC jako dodatki w intencji. DPC może za pomocą tych samych kluczy odczytać ustawienia obsługi administracyjnej z jednostki PersistableBundle.

Zalecane – do skonfigurowania DPC użyj tych dodatków:

Niezalecane – nie dodawaj tych dodatków, których możesz używać w innych metodach rejestracji:

Aby dowiedzieć się, jak wyodrębnić i wykorzystać te ustawienia w DPC, przeczytaj artykuł Obsługa administracyjna urządzeń klientów.

Programowanie i testowanie

Aby utworzyć i przetestować funkcje rejestracji typu zero-touch w konsoli, potrzebujesz:

  • obsługiwane urządzenie
  • konto klienta do rejestracji typu zero-touch.

Twórz i testuj aplikacje z wykorzystaniem urządzeń obsługujących rejestrację typu zero-touch, takich jak Google Pixel. Nie musisz kupować urządzeń dla programistów od sprzedawcy.

Skontaktuj się z nami, aby uzyskać konto klienta testowego i uzyskać dostęp do portalu rejestracji typu zero-touch. Wyślij do nas e-maila z firmowego adresu e-mail powiązanego z kontem Google. Podaj producenta i numer IMEI jednego lub dwóch urządzeń, a dodamy je do Twojego konta programowania.

Pamiętaj, że rejestracja typu zero-touch automatycznie pobiera i instaluje DPC, dlatego zanim przetestujesz obsługę administracyjną, ta wersja DPC musi być dostępna w Google Play. Nie możesz przeprowadzać testów na rozwojowej wersji DPC.

Pomoc dla administratorów IT

Jeśli potrzebujesz pomocy dla administratorów IT związanych z interfejsem konsoli lub z dokumentacją, zapoznaj się ze wskazówkami w artykule Rejestracja typu zero-touch dla administratorów IT. Możesz też skierować użytkowników konsoli do tego artykułu w Centrum pomocy.

Więcej informacji

Przeczytaj te dokumenty, które pomogą Ci zintegrować rejestrację typu zero-touch w konsoli: