此页面由 Cloud Translation API 翻译。

代码示例

以下请求说明了如何使用 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"

响应

成功的响应应该为空。

{}