程式碼範例

以下要求會說明透過 Policy API 管理政策。使用前 開始，請務必詳閱 Chrome Policy API 總覽 ，瞭解此 API 功能的高階摘要。

下方顯示的所有要求都使用下列變數：

  • $TOKEN - OAuth 2 權杖
  • $CUSTOMER - 客戶 ID 或常值 my_customer

列出印表機政策的結構定義

如要列出僅涉及印表機政策的結構定義，我們會套用 filter 」參數加入「Schema Service list」要求中。您可以控制 使用 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 含有「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 含有「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 含有「groups/」而不是 「orgunits/」。這裡將禁止使用印表機「0gjdgxs208tpef」 機構單位 ID「04fatzly4jbjho9」中的使用者：

要求

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 含有「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 如果政策在清單中較舊，就會遭到覆寫。

請注意，群組優先順序高於機構單位優先順序。

在這個要求中，我們會傳回「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。

請注意，群組優先順序高於機構單位優先順序。

在這項要求中，我們要設定「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"

回應

成功的回應空白。

{}

處理需要確認的政策

部分政策結構定義會指定「notices」將特定欄位的某些值納入計算 需要確認

政策 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 要求中使用的網址。

在這個範例中，我們會上傳 chrome.users.Wallpaper JPEG 檔案。

上傳檔案

要求

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"

回應

成功的回應不得留空。

{}