customer API מאפשר לשלוט באופן פרוגרמטי במכשירים ובהגדרות אישיות להרשמה דרך הארגון. במסמך הזה מתוארים ה-API לספקים של ניהול ניידות ארגונית (EMM) ולמפתחי IT בארגונים. אחרי שתקראו את המסמך הזה, תבינו את המשאבים העיקריים שבהם נעשה שימוש ב-API ואת האינטראקציה שלהם. אם עדיין לא השתמשתם בהרשמה דרך הארגון, כדאי לקרוא את המבוא הקצר של android.com.
סקירה כללית
ממשק ה-API של הלקוח עוזר לארגונים שרוכשים מכשירי Android להרשמה דרך הארגון. האפליקציה או הכלי שלך יכולים לעזור למנהלי IT לבצע את הפעולות הבאות:
- יצירה, עריכה ומחיקה של הגדרות של ניהול תצורה.
- החלה או הסרה של הגדרה במכשיר.
- צריך לבחור הגדרת ברירת מחדל לכל מכשיר שיתווספו בהמשך להרשמה דרך הארגון.
באמצעות ה-API, אדמינים ב-IT יכולים גם לבטל רישום של מכשירים באמצעות הרשמה דרך הארגון. כדי לנהל את המשתמשים בארגון או לאשר את התנאים וההגבלות, האדמינים ב-IT משתמשים בפורטל ההרשמה דרך הארגון.
משתמשים אופייניים ב-API הזה יכולים להיות:
- ספקי EMM מוסיפים תמיכה בהרשמה דרך הארגון למסוף שלהם.
- מפתחי IT ארגוניים יוצרים כלים לאוטומציה של משימות הרשמה דרך הארגון.
מקורות מידע עיקריים
תצורות ומכשירים הם המשאבים המרכזיים שבהם אתם משתמשים ב-API. הארגון יכול גם ליצור הגדרות ומכשירים באמצעות פורטל ההרשמה דרך הארגון.
- הגדרות אישיות
- אדמינים ב-IT הגדירו אפשרויות לניהול תצורה במכשירים באמצעות הגדרה. ההגדרות כוללות את מדיניות EMM לנייד ואת הפרטים ליצירת קשר שמוצגים כדי לעזור למשתמשים. ההגדרות האישיות הן חלק מרכזי ב-API, ולכן משתמשים בהן בשיטות רבות. מידע נוסף זמין בקטע הגדרות אישיות בהמשך.
- מכשיר
- מכשיר Android עם יכולות הרשמה דרך הארגון, שנרכש מהמפיץ שלו. מגדירים הגדרות כדי לכלול את המכשיר בהרשמה דרך הארגון. למכשירים יש מזהי חומרה ומטא-נתונים מצורפים. מידע נוסף מופיע בקטע מכשירים בהמשך.
- בקר DPC
- הפניה לקריאה בלבד לבקר DPC של EMM (בקרת מדיניות המכשיר). כדי לבחור פתרון EMM למכשירים, צריך להוסיף בקר DPC לתצורה כל מרכזי ה-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 לתיקון, חשוב לכלול את
מסכת השדות – או
ערך לכל שדה שלא רוצים להיות null. בקטע הגדרות ברירת מחדל (בהמשך) תוכלו לראות איך מעדכנים הגדרות אישיות בצורה יעילה.
מחיקת ההגדרות האישיות
אי אפשר למחוק הגדרות אישיות אם הן עדיין חלות על מכשירים. כשמנסים למחוק הגדרה שנמצאת בשימוש, שיטת ה-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 לזהות מכשירים.
מידע נוסף על המטא-נתונים שעשויים להופיע מופיע במדריך מטא-נתונים של מכשירים למפיצים.
תוצאות בדפים
שיטת ה-API customers.devices.list עשויה להחזיר רשימות ארוכות מאוד של מכשירים. כדי להקטין את גודל התשובה, השיטה הזו ושיטות API אחרות (כמו customers.list) תומכות בתוצאות מחולקות לדפים. בעזרת תוצאות הדפים, האפליקציה יכולה לבקש ולעבד רשימות גדולות באופן חזרתי, על בסיס דף אחר.
אחרי שמפעילים את שיטת ה-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.