איך זה עובד

ה-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 כדי לאחזר, ליצור, לעדכן ולמחוק הגדרות. הדוגמה הבאה מראה איך יוצרים הגדרה חדשה:

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

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

# 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. בקטע הגדרות ברירת מחדל (בהמשך) מופיעה דוגמה שמראה איך לעדכן הגדרה בצורה יעילה.

מחיקת הגדרות

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

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

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

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

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

# 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 לאחר החלת הגדרות אישיות, המכשיר מקצה את עצמו באופן אוטומטי בהפעלה הראשונה או באיפוס הבא להגדרות המקוריות. הדוגמה הבאה ממחישה איך אפשר להחיל במערך של מכשירים:

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

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

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 ושם היצרן:

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

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

# 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, האפליקציה יכולה להשתמש בו כדי לאחזר דף נוסף של מכשירים על ידי קריאה חוזרת ל-method. צריך להגדיר מגבלה עליונה למספר המכשירים הפרמטר pageSize. אם nextPageToken הוא null, האפליקציה שלך ביקשה הדף האחרון.

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

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

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);
    }
}

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 בעצמכם.