以下请求说明了如何使用 Policy API 进行政策管理。在开始之前,请务必查看 Chrome Policy API 概览,简要了解此 API 的功能。
下面显示的所有请求都使用以下变量:
$TOKEN
- OAuth 2 令牌$CUSTOMER
- 客户 ID 或文字my_customer
列出打印机政策的架构
如需列出仅涉及打印机政策的架构,我们会将 filter
参数应用于架构服务列表请求。您可以使用 pageSize
和 pageToken
参数控制结果的分页。
请求
curl -X GET \
-H "Authorization: Bearer $TOKEN" \
"https://chromepolicy.googleapis.com/v1/customers/$CUSTOMER/policySchemas?filter=chrome.printers&pageSize=2"
响应
{
"policySchemas": [
{
"name": "customers/C0202nabg/policySchemas/chrome.printers.AllowForUsers",
"policyDescription": "Allows a printer for users in a given organization.",
"additionalTargetKeyNames": [
{
"key": "printer_id",
"keyDescription": "Id of printer as visible in Admin SDK printers API."
}
],
"definition": {
"messageType": [
{
"name": "AllowForUsers",
"field": [
{
"name": "allowForUsers",
"number": 1,
"label": "LABEL_OPTIONAL",
"type": "TYPE_BOOL"
}
]
}
]
},
"fieldDescriptions": [
{
"field": "allowForUsers",
"description": "Controls whether a printer is allowed for users in a given organization."
}
],
"schemaName": "chrome.printers.AllowForUsers"
},
{
"name": "customers/C0202nabg/policySchemas/chrome.printers.AllowForDevices",
"policyDescription": "Allows a printer for devices in a given organization.",
"additionalTargetKeyNames": [
{
"key": "printer_id",
"keyDescription": "Id of printer as visible in Admin SDK printers API."
}
],
"definition": {
"messageType": [
{
"name": "AllowForDevices",
"field": [
{
"name": "allowForDevices",
"number": 1,
"label": "LABEL_OPTIONAL",
"type": "TYPE_BOOL"
}
]
}
]
},
"fieldDescriptions": [
{
"field": "allowForDevices",
"description": "Controls whether a printer is allowed for devices in a given organization."
}
],
"schemaName": "chrome.printers.AllowForDevices"
}
],
"nextPageToken": "AEbDN_obE8A98T8YhIeU9VCIZhEBylLBwZRQpGu_DUug-mU4bnzcDx30UnO2xMuuImvfVpmeuXRF6VhJ4OmZpZ4H6EaRvu2qMOPxVN_u"
}
搜索架构
您可以在架构服务列表请求中使用 filter=
参数创建复杂的搜索查询。例如,如果要搜索名称中具有“printer”一词且说明中具有“devices”一词的架构,您可以将以下值应用于过滤条件 name=printers AND description=devices
。
了解如何列出政策架构。
请求
curl -X GET \
-H "Authorization: Bearer $TOKEN" \
"https://chromepolicy.googleapis.com/v1/customers/$CUSTOMER/policySchemas?filter=name=printers%20AND%20description=devices"
响应
{
"policySchemas": [
{
"name": "customers/C0202nabg/policySchemas/chrome.printers.AllowForDevices",
"policyDescription": "Allows a printer for devices in a given organization.",
"additionalTargetKeyNames": [
{
"key": "printer_id",
"keyDescription": "Id of printer as visible in Admin SDK printers API."
}
],
"definition": {
"messageType": [
{
"name": "AllowForDevices",
"field": [
{
"name": "allowForDevices",
"number": 1,
"label": "LABEL_OPTIONAL",
"type": "TYPE_BOOL"
}
]
}
]
},
"fieldDescriptions": [
{
"field": "allowForDevices",
"description": "Controls whether a printer is allowed for devices in a given organization."
}
],
"schemaName": "chrome.printers.AllowForDevices"
}
]
}
获取特定架构
在上面的结果中,我们看到了一个受支持的政策架构列表。每个架构都有一个用于标识架构的 name
字段。将来,知道架构名称后,您可以通过引用请求网址中的架构名称直接读取特定架构。
我们来看一个 chrome.printers.AllowForUsers
架构的示例。
请求
curl -X GET \
-H "Authorization: Bearer $TOKEN" \
"https://chromepolicy.googleapis.com/v1/customers/$CUSTOMER/policySchemas/chrome.printers.AllowForUsers"
响应
{
"name": "customers/C0202nabg/policySchemas/chrome.printers.AllowForUsers",
"policyDescription": "Allows a printer for users in a given organization.",
"additionalTargetKeyNames": [
{
"key": "printer_id",
"keyDescription": "Id of printer as visible in Admin SDK printers API."
}
],
"definition": {
"messageType": [
{
"name": "AllowForUsers",
"field": [
{
"name": "allowForUsers",
"number": 1,
"label": "LABEL_OPTIONAL",
"type": "TYPE_BOOL"
}
]
}
]
},
"fieldDescriptions": [
{
"field": "allowForUsers",
"description": "Controls whether a printer is allowed for users in a given organization."
}
],
"schemaName": "chrome.printers.AllowForUsers"
}
上述政策架构响应描述了 chrome.printers.AllowForUsers
政策的架构。通知字段 additionalTargetKeyNames
。
此字段说明该政策要求在处理此政策时提供额外的键/值。特别是,对于此政策,我们始终需要提供打印机的标识符。
读取政策值
我们来读取特定打印机的政策 chrome.printers.AllowForUsers
。请注意,我们在请求中使用字段 additionalTargetKeys
指定打印机 ID。
您可以从组织部门或群组中读取政策。
在响应中,请注意 sourceKey
字段,该字段用于指定政策的值来自哪个组织部门或群组。对于组织部门,有以下可能性:
- 如果源组织部门与请求中提供的组织部门相同,则表示政策已在此组织部门中本地应用。
- 如果源组织部门与请求中提供的组织部门不同,则表示政策继承自源组织部门。
- 如果
sourceKey
不存在或响应为空,则表示没有为客户设置政策,但该政策具有默认的系统值。
对于群组,sourceKey 将始终与请求中指定的群组相同。
以下示例适用于组织部门。群组请求是一样的,但 targetResource 除外,其 ID 前带有“groups/”而不是“orgunits/”。
请求
curl -X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-d '{
policyTargetKey: {
targetResource: "orgunits/04fatzly4jbjho9",
additionalTargetKeys: {"printer_id":"0gjdgxs208tpef"}
},
policySchemaFilter: "chrome.printers.AllowForDevices"
}' \
"https://chromepolicy.googleapis.com/v1/customers/$CUSTOMER/policies:resolve"
响应
{
"resolvedPolicies": [
{
"targetKey": {
"targetResource": "orgunits/03ph8a2z1xdnme9"
"additionalTargetKeys": {"printer_id":"0gjdgxs208tpef"}
},
"value": {
"policySchema": "chrome.users.AllowForDevices",
"value": {
"allowForDevices": true
}
},
"sourceKey": {
"targetResource": "orgunits/03ph8a2z3qhz81k"
}
}
]
}
请注意,在请求中省略 additionalTargetKeys
即可提取目标资源中的所有实体。例如,如果上述请求中省略了 additionalTargetKeys
,则会返回指定目标资源中的所有打印机。
读取多项政策
提供带星号的架构命名空间(例如,chrome.printers.*
)时,您可以读取特定组织部门或群组中此命名空间下所有政策的值。详细了解政策架构。
以下示例适用于组织部门。群组请求是一样的,但 targetResource 除外,其 ID 前带有“groups/”而不是“orgunits/”。
请求
curl -X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-d '{
policyTargetKey: {
targetResource: "orgunits/04fatzly4jbjho9",
},
policySchemaFilter: "chrome.printers.*"
}' \
"https://chromepolicy.googleapis.com/v1/customers/$CUSTOMER/policies:resolve"
响应
{
"resolvedPolicies": [
{
"targetKey": {
"targetResource": "orgunits/04fatzly4jbjho9",
"additionalTargetKeys": {
"printer_id": "0gjdgxs0xd59y1"
}
},
"value": {
"policySchema": "chrome.printers.AllowForUsers",
"value": {
"allowForUsers": false
}
}
},
{
"targetKey": {
"targetResource": "orgunits/04fatzly4jbjho9",
"additionalTargetKeys": {
"printer_id": "0gjdgxs0xd59y1"
}
},
"value": {
"policySchema": "chrome.printers.AllowForDevices",
"value": {
"allowForDevices": false
}
}
},
//...
],
"nextPageToken": "AEbDN_pFvDeGSbQDkvMxr4UA0Ew7UEUw8aJyw95VPs2en6YxMmFcWQ9OQQEIeSkjnWFCQNyz5GGoOKQGEd50e2z6WqvM2w7sQz6TMxVOBD_4NmEHRWtIJCYymeYXWHIrNH29Ezl1wkeyYBAOKnE="
}
修改政策值
如政策架构响应中所示,政策 chrome.printers.AllowForUsers
有一个名为 allowForUsers
的字段。此字段是布尔值类型。政策的值可以是 {allowForUsers: false}
或 {allowForUsers: true}
。在此特定示例中,我们只有一个字段,但其他政策可能包含多个字段。
在修改请求中,我们需要指定 updateMask
。更新掩码会列出我们要修改的所有字段。如果政策已在组织部门中本地应用,则未通过更新掩码列出的字段将保持不变。如果政策尚未在组织部门本地应用,并且未通过更新掩码列出的所有字段,则会适时从父级组织部门复制其值,并且整个政策将在本地应用。
以下示例适用于组织部门。除了 targetResource 之外,群组请求都是相同的,后者的 ID 前带有“groups/”而不是“orgunits/”。在这里,我们将禁止组织部门 ID 04fatzly4jbjho9
中的用户使用打印机 0gjdgxs208tpef
:
请求
curl -X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-d '{
requests: [{
policyTargetKey: {
targetResource: "orgunits/04fatzly4jbjho9",
additionalTargetKeys: {"printer_id":"0gjdgxs208tpef"}
},
policyValue: {
policySchema: "chrome.printers.AllowForUsers",
value: {allowForUsers: false}
},
updateMask: {paths: "allowForUsers"}
}]
}' \
"https://chromepolicy.googleapis.com/v1/customers/$CUSTOMER/policies/orgunits:batchModify"
响应
成功的响应为空。
{}
列表或数组等多值字段带有“LABEL_REPEATED”标签。如需填充多值字段,请使用以下 JSON 数组格式:[value1, value2, value3, ...]
。
例如,如需将应用和扩展程序软件包的来源网址设置为“test1.com”“test2.com”和“test3.com”,我们需要发送以下请求:
请求
curl -X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-d "{
requests: [
{
policy_target_key: {
target_resource: 'orgunits/03ph8a2z28rz85a'
},
updateMask: {
paths: ['extensionInstallSources']
},
policy_value: {
policy_schema: 'chrome.users.appsconfig.AppExtensionInstallSources',
value: {
extensionInstallSources: ['test1.com', 'test2.com', 'test3.com']
}
}
}
]
}" \
"https://chromepolicy.googleapis.com/v1/customers/$CUSTOMER/policies/orgunits:batchModify"
响应
成功的响应为空。
{}
包含 NullableDuration 字段的所有政策有两个版本。原始版本仅接受字符串作为 NullableDuration 的输入,现已废弃。请使用 V2 版本,该版本会将时长类型替换为数字输入值。例如,要将用户会话时长上限设置为 10 分钟,我们需要发送以下请求:
请求
curl -X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-d "{
requests: [
{
policy_target_key: {
target_resource: 'orgunits/03ph8a2z28rz85a'
},
updateMask: {
paths: ['sessionDurationLimit']
},
policy_value: {
policy_schema: 'chrome.users.SessionLengthV2',
value: {
sessionDurationLimit: {
duration: 10
}
}
}
}
]
}" \
"https://chromepolicy.googleapis.com/v1/customers/$CUSTOMER/policies/orgunits:batchModify"
响应
成功的响应为空。
{}
一次修改多项政策
借助 batchModify
方法,您可以同时发送多项政策修改。但是,并非所有政策都可以批量进行。如需了解详情,请参阅批量更新政策。
在本示例中,我们将在同一请求中修改同一打印机的两个不同的政策(chrome.printers.AllowForDevices
和 chrome.printers.AllowForUsers
)。
以下示例适用于组织部门。群组请求是一样的,但 targetResource 除外,其 ID 前带有“groups/”而不是“orgunits/”。
请求
curl -X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-d '{
requests: [{
policyTargetKey: {
targetResource: "orgunits/04fatzly4jbjho9",
additionalTargetKeys: {"printer_id":"0gjdgxs208tpef"}
},
policyValue: {
policySchema: "chrome.printers.AllowForDevices",
value: {allowForDevices: true}
},
updateMask: {paths: "allowForDevices"}
},
{
policyTargetKey: {
targetResource: "orgunits/04fatzly4jbjho9",
additionalTargetKeys: {"printer_id":"0gjdgxs208tpef"}
},
policyValue: {
policySchema: "chrome.printers.AllowForUsers",
value: {allowForUsers: true}
},
updateMask: {paths: "allowForUsers"}
}]
}' \
"https://chromepolicy.googleapis.com/v1/customers/C0202nabg/policies/orgunits:batchModify"
响应
成功的响应为空。
{}
继承组织部门中的政策值
借助 batchInherit
方法,您可以将组织部门中政策的状态从“本地应用”修改为“继承”。本地值将被清除,并且在适用时,政策将沿用父级组织部门的值。
借助 batchInherit
方法,您还可以同时发送多个政策继承请求。但是,并非所有政策都可以批量进行。如需了解详情,请参阅批量更新政策。
请求
curl -X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-d '{
requests: [{
policyTargetKey: {
targetResource: "orgunits/04fatzly12wd3ox",
additionalTargetKeys: {"printer_id":"0gjdgxs208tpef"}
},
policySchema: "chrome.printers.AllowForUsers"
}]
}' \
"https://chromepolicy.googleapis.com/v1/customers/$CUSTOMER/policies/orgunits:batchInherit"
响应
成功的响应为空。
{}
删除组中的政策值
您可以使用 batchDelete
方法从组中删除政策。本地值将被清除。
借助 batchDelete
方法,您还可以同时发送多个政策删除请求。但是,并非所有政策都可以批量进行。如需了解详情,请参阅批量更新政策。
请求
curl -X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-d '{
requests: [{
policyTargetKey: {
targetResource: "groups/04fatzly12wd3ox",
additionalTargetKeys: {"printer_id":"0gjdgxs208tpef"}
},
policySchema: "chrome.printers.AllowForUsers"
}]
}' \
"https://chromepolicy.googleapis.com/v1/customers/$CUSTOMER/policies/groups:batchDelete"
响应
成功的响应为空。
{}
列出群组的优先级排序
您可以使用 listGroupPriorityOrdering
方法列出应用群组的优先级排序。
返回的群组 ID 的顺序表示将相应设置应用于应用的优先级;之后的 ID 的政策将被在列表中较早的 ID 所覆盖的政策中。
请注意,群组优先级高于组织部门优先级。
在此请求中,我们将返回“exampleapp”Chrome 用户应用的优先级排序。
请求
curl -X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-d '{
policyTargetKey: {
additionalTargetKeys: {"app_id":"chrome:exampleapp"}
},
policyNamespace: 'chrome.users.apps'
}' \
"https://chromepolicy.googleapis.com/v1/customers/$CUSTOMER/policies/groups:listGroupPriorityOrdering"
响应
{
"policyTargetKey": {
"additionalTargetKeys": {
"app_id": "chrome:exampleapp"
}
},
"policyNamespace": "chrome.users.apps",
"groupIds": [
"03ep43zb2k1nodu",
"01t3h5sf2k52kol",
"03q5sasy2ihwnlz"
]
}
更新群组的优先级排序
使用 updateGroupPriorityOrdering
方法,您可以更新应用群组的优先级排序。
请求中群组 ID 的顺序表示其设置将应用于应用的优先级;之后的 ID 的政策将被在列表中较早的 ID 所覆盖的政策中。请求必须包含当前应用于应用的每个群组 ID。
请注意,群组优先级高于组织部门优先级。
在此请求中,我们将为 Chrome 用户“exampleapp”应用设置优先级排序。
请求
curl -X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-d '{
policyTargetKey: {
additionalTargetKeys: {"app_id":"chrome:exampleapp"}
},
policyNamespace: 'chrome.users.apps',
groupIds: ['03ep43zb2k1nodu', '01t3h5sf2k52kol', '03q5sasy2ihwnlz']
}' \
"https://chromepolicy.googleapis.com/v1/customers/$CUSTOMER/policies/groups:updateGroupPriorityOrdering"
响应
成功的响应为空。
{}
处理需要确认的政策
一些政策架构会为需要确认的特定字段的某些值指定“通知”。
chrome.users.PluginVmAllowd
政策的示例:
{
"name": "customers/C0202nabg/policySchemas/chrome.users.PluginVmAllowed",
"policyDescription": "Parallels Desktop.",
# ...
"fieldDescriptions": [
{
"field": "pluginVmAllowed",
"description": "N/A",
"knownValueDescriptions": [
{
"value": "true",
"description": "Allow users to use Parallels Desktop."
},
{
"value": "false",
"description": "Do not allow users to use Parallels Desktop."
}
]
},
{
"field": "ackNoticeForPluginVmAllowedSetToTrue",
"description": "This field must be set to true to acknowledge the notice message associated with the field 'plugin_vm_allowed' set to value 'true'. Please see the notices listed with this policy for more information."
}
],
"notices": [
{
"field": "pluginVmAllowed",
"noticeValue": "true",
"noticeMessage": "By enabling Parallels Desktop, you agree to the Parallels End-User License Agreement specified at https://www.parallels.com/about/legal/eula/. Warning: Device identifiers may be shared with Parallels. Please see privacy policy for more details at https://www.parallels.com/about/legal/privacy/. The minimum recommended configuration includes an i5 processor, 16 GB RAM, and 128 GB storage: https://support.google.com/chrome/a/answer/10044480.",
"acknowledgementRequired": true
}
],
"supportUri": "...",
"schemaName": "chrome.users.PluginVmAllowed"
}
在上面的示例中,将字段 pluginVmAllowed
的值设置为 true
与包含 acknowledgementRequired
的通知相关联。如需将此字段值正确设置为 true
,您需要向 true
发送一个指定确认字段 ackNoticeForPluginVmAllowedSetToTrue
的请求,否则,您的请求将出现错误。
在此示例中,您需要发送以下批量修改请求。
curl -X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-d "{
'requests': [
{
'policyTargetKey': {
'targetResource': 'orgunits/03ph8a2z10ybbh2'
},
'policyValue': {
'policySchema': 'chrome.users.PluginVmAllowed',
'value': {
'pluginVmAllowed': true,
'ackNoticeForPluginVmAllowedSetToTrue': true
}
},
'updateMask': {
'paths': [
'pluginVmAllowed',
'ackNoticeForPluginVmAllowedSetToTrue'
]
}
}
]
}" \
"https://chromepolicy.googleapis.com/v1/customers/$CUSTOMER/policies/orgunits:batchModify"
设置文件政策
某些政策的字段类型为 UploadedFile
,您需要将要设为这些政策的值的文件上传到 API 服务器,以获取要在 BatchModify
请求中使用的网址。
在此示例中,我们将通过上传 JPEG 文件来设置 chrome.users.Wallpaper
。
上传文件
请求
curl -X POST \
-H "Content-Type: image/jpeg" \
-H "Authorization: Bearer $TOKEN" \
-T "/path/to/the/file" \
"https://chromepolicy.googleapis.com/upload/v1/customers/$CUSTOMER/policies/files:uploadPolicyFile?policy_field=chrome.users.Wallpaper.wallpaperImage"
响应
成功的响应应包含用于访问该文件的网址:
{
"downloadUri": "https://storage.googleapis.com/chromeos-mgmt/0gjdgxs370bkl6/ChromeOsWallpaper/32ac50ab-b5ae-4bba-afa8-b6b443912897"
}
设置文件政策
请求
curl -X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-d '{
requests: [{
policyTargetKey: {
targetResource: "orgunits/04fatzly4jbjho9",
},
policyValue: {
policySchema: "chrome.users.Wallpaper",
value: {
wallpaperImage: {downloadUri: "https://storage.googleapis.com/chromeos-mgmt/0gjdgxs370bkl6/ChromeOsWallpaper/32ac50ab-b5ae-4bba-afa8-b6b443912897"}
}
},
updateMask: {paths: "wallpaperImage"}
}]
}' \
"https://chromepolicy.googleapis.com/v1/customers/$CUSTOMER/policies/orgunits:batchModify"
响应
成功的响应应该为空。
{}