下列要求會說明如何使用 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
。這個欄位說明政策需要在處理這項政策時提供額外的鍵/值。具體來說,我們一律會針對這項政策提供印表機的 ID。
讀取政策值
以下介紹特定印表機的 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 列在清單中較早者,將會覆寫其 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 政策。要求必須包含應用程式目前套用的每個群組 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',
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
,您必須傳送指定確認欄位 ackNoticeForPluginVmAllowedSetToTrue
的要求給 true
,否則您會在要求中收到錯誤訊息。
在此範例中,您需要傳送下列批次修改要求。
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"
回應
成功的回應應為空白。
{}