כיצד זה עובד

ה-API של הלקוח נותן שליטה פרוגרמטית במכשירים להרשמה דרך הארגון ל-Android. במסמך הזה נסביר על API לספקים לניהול ניידות ארגונית (EMM) ול-IT לארגונים למפתחים. המסמך הזה יעזור לכם להבין את העקרונות הבסיסיים את המשאבים שנמצאים בשימוש ב-API ואת אופן האינטראקציה ביניהם. אם עוד לא התחלתם להשתמש בממשק ללא מגע, הרשמה, קראו את המאמר הקצר android.com מבוא.

סקירה כללית

ה-API של הלקוח עוזר לארגונים שרוכשים הרשמה דרך הארגון ל-Android מכשירים. האפליקציה או הכלי שלכם יכולים לעזור לאדמינים ב-IT לבצע את הפעולות הבאות:

  • ליצור, לערוך ולמחוק הגדרות של ניהול הקצאות.
  • מחילים או מסירים תצורה במכשיר.
  • צריך לבחור הגדרות ברירת מחדל לכל המכשירים שיתווספו להרשמה דרך הארגון בעתיד.

מנהלי IT גם יכולים לבטל את הרישום של מכשירים דרך ה-API דרך ה-API. להרשמה לקראת השקת אפליקציה. כדי לנהל את המשתמשים בארגון או לאשר את התנאים וההגבלות, אדמינים ב-IT משתמשים בפורטל ההרשמה דרך הארגון.

משתמשים טיפוסיים ב-API הזה יכולים להיות:

  • ספקי EMM מוסיפים תמיכה בהרשמה דרך הארגון למסוף שלהם.
  • מפתחי IT בארגונים יוצרים כלים לאוטומציה של הרשמה דרך הארגון למשימות סיווג.

משאבי ליבה

הגדרות אישיות ומכשירים הם משאבי הליבה שבהם אתם משתמשים ב-API. הארגון יכול גם ליצור הגדרות אישיות ומכשירים באמצעות דרך הארגון או פורטל ההרשמה.

הקשר בין המכשיר למשאב הלקוח

תצורה
אדמינים ב-IT הגדירו אפשרויות להקצאת הרשאות ידנית במכשירים באמצעות הגדרות אישיות. ההגדרות כוללות מדיניות EMM לנייד ופרטים ליצירת קשר שמוצגים למשתמשים. ההגדרות האישיות הן חלק מרכזי ב-API, כך שאתם משתמשים בהן בהרבה שיטות. למידע נוסף, אפשר לעיין בקטע הגדרות בהמשך.
מכשיר
מכשיר Android עם יכולות הרשמה דרך הארגון שנרכש ממנו למפיץ שלו. החלת הגדרות אישיות כדי לכלול את המכשיר דרך הארגון להרשמה לקראת השקת אפליקציה. למכשירים יש מזהי חומרה ומטא-נתונים מצורפים. מידע נוסף זמין במאמר הבא: מכשירים למטה.
בקר DPC
חומר עזר לקריאה בלבד של בקר DPC של EMM (מדיניות מכשיר) ). הוספת בקר DPC להגדרות אישיות כדי לבחור את פתרון ה-EMM למכשירים. כל בקרי ה-DPC ברשימה של ה-API תומך בהרשמה דרך הארגון והן זמינות ב-Google Play. שפת תרגום מידע נוסף זמין בכתובת Dpc.

כדי להציג רשימה של כל השיטות והמשאבים של ה-API שהאפליקציה יכולה להשתמש בהם, אפשר לעיין ב הפניית API.

הגדרות אישיות

משאב ה-API של Configuration משלב הבאים:

  • בקר ה-DPC של ה-EMM המותקן במכשירים.
  • כללי מדיניות EMM שנאכפים במכשירים.
  • פרטים ליצירת קשר שמוצגים במכשיר כדי לעזור למשתמשים במהלך ההגדרה.

באמצעות ה-API, האפליקציה יכולה לנהל את ההגדרות של האדמינים ב-IT. קוראים ל-API אל אחזור, יצירה, עדכון ומחיקה של הגדרות אישיות. הדוגמה הבאה מראה איך יוצרים הגדרה חדשה:

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

כשמעדכנים הגדרה באמצעות API לתיקון, חשוב לכלול את הקוד field mask – או לכל שדה שלא רוצים להיות null. להצגת ברירת המחדל (בהמשך) דוגמה שמראה איך לעדכן תצורה ביעילות.

מחיקת הגדרות

לא ניתן למחוק הגדרה אישית אם היא עדיין מופעלת במכשירים. אם תנסה מוחקים הגדרה בשימוש, ה-method של ה-API מחזירה HTTP 400 Bad Request קוד סטטוס והודעה שמסבירה כמה מכשירים משתמשים בתצורה. שיחת טלפון customers.devices.removeConfiguration כדי להסיר את ההגדרות האישיות מהמכשירים לפני שמנסים שוב.

הגדרות ברירת המחדל

הרשמה דרך הארגון פועלת בצורה הטובה ביותר כשארגון מגדיר ברירת מחדל שתחול על כל מכשיר חדש שהארגון רוכש. מומלץ לבקש מאדמינים ב-IT לקבוע הגדרות ברירת מחדל אם הן לא מוגדרות. הדוגמה הבאה מראה איך להגדיר הגדרה קיימת כברירת המחדל באמצעות הגדרה של isDefault ל-true:

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

אפשר להגדיר רק הגדרה אחת כברירת מחדל. יוצרים הגדרות ברירת מחדל חדשות מגדירה את השדה isDefault של הגדרה קודמת כ-false. יכול להיות שתצטרכו צריך לרענן את כל המופעים של Configuration שנשמרו במטמון כדי לראות את הערכים הנכונים isDefault שדות.

הדרכת המשתמשים במכשיר

תצורה דרך הארגון מציגה הנחיות מותאמות אישית למשתמש בהגדרת המכשיר אשף שעוזר למשתמשים. צריך לציין מספר טלפון וכתובת אימייל ליצירת קשר ואת שם הארגון שמנהל את המכשיר הגדרה אישית. מומלץ גם לכלול משפט אחד או שניים את השדה customMessage, כדי לספק פרטים נוספים על מה שקורה במכשיר של משתמש במכשיר.

כי המשתמש לא יוכל להתקשר או לשלוח אימייל מהמכשיר שאותו הוא מגדיר לעצב את מספר הטלפון ואת כתובת האימייל כדי שיהיה קל יותר לעיין את המידע.

מכשירים

מפיצים יוצרים מכשירים כשלקוח רוכש אותם דרך הארגון רישום — אדמינים ב-IT לא יכולים ליצור מכשירים. כדי לעבוד עם מכשירים, שיטות השיחה פועלות משאב ה-API Device. אם צריך לחפש להצגת רשימה של כל המכשירים ולסנן כל קבוצת קבצים באופן מקומי באפליקציה. עבור דוגמה, ראו תוצאות בדפים שבהמשך.

הגדרת מכשירים

כשמחילים הגדרות אישיות על מכשיר, המערכת רושמת את המכשיר דרך הארגון להרשמה לקראת השקת אפליקציה. כדי להחיל מערך הגדרות אישיות, קוראים לפונקציה customers.devices.applyConfiguration לאחר החלת הגדרות אישיות, המכשיר מקצה את עצמו באופן אוטומטי בהפעלה הראשונה או באיפוס הבא להגדרות המקוריות. הדוגמה הבאה ממחישה איך אפשר להחיל באוסף של מכשירים:

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

כדי להסיר את התצורה ממכשיר, צריך להתקשר customers.devices.removeConfiguration השינוי ייכנס לתוקף לאחר איפוס המכשיר להגדרות המקוריות.

הסרת הבעלות על מכשירים

אדמינים ב-IT יכולים לבטל את הבעלות על מכשיר כדי להסיר אותו מהרשמה דרך הארגון. צוות IT יכול לבטל בעלות על מכשיר שהוא רוצה להעביר לחשבון אחר, למכור, או הוחזרו למפיץ. קריאה ל-method customers.devices.unclaim כדי לבטל תביעת בעלות על מכשיר מארגון.

הדוגמה הבאה מראה איך לבטל את הבעלות על מכשיר ממספר IMEI, שם היצרן:

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

מטא-נתונים של המכשיר

אדמין ב-IT יכול לראות את המטא-נתונים שהמפיץ צירף למכשיר. קמפיינים לרשת המדיה המטא-נתונים של המכשיר הזה באפליקציה שלך כדי לעזור לאדמינים ב-IT לזהות מכשירים.

לקבלת מידע נוסף על המטא-נתונים שעשויים להופיע, אפשר לקרוא את המאמר מכשיר מטא נתונים מדריך למפיצים.

תוצאות בדף

ה-method customers.devices.list של ה-API עשויה להחזיר רשימות גדולות מאוד של מכשירים. כדי להקטין את גודל התשובה, ממשק ה-API הזה ואחרים שיטות (כמו customers.list) שתומכות בתוצאות בדפים. ב- תוצאות לדפים, האפליקציה יכולה לבקש ולעבד רשימות גדולות באופן חזרתי דף אחד בכל פעם.

אחרי קריאה ל-method של ה-API, צריך לבדוק אם התשובה כוללת ערך עבור nextPageToken אם nextPageToken לא null, האפליקציה שלך יכולה להשתמש בו כדי לאחזר דף אחר של מכשירים על ידי קריאה שוב. צריך להגדיר מגבלה עליונה למספר המכשירים הפרמטר pageSize. אם nextPageToken הוא null, האפליקציה שלך ביקשה הדף האחרון.

השיטה לדוגמה הבאה מראה איך האפליקציה עשויה להדפיס רשימה של מכשירים, דף אחד בכל פעם:

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

שנתחיל?

בשלב הבא קוראים איך מאשרים קריאות ל-API בקטע הרשאה. אם רוצים את ממשקי ה-API, תוכלו לעיין במדריכים למתחילים Java, .NET, וגם Python. אפשר להשתמש colab להצגה דוגמאות לקריאות ל-API ותנסו להפעיל את ה-API בעצמכם.