As solicitações abaixo ilustram o gerenciamento de políticas com a API Policy. Antes de começar, leia a Visão geral da API Chrome Policy para um resumo detalhado dos recursos dessa API.
Todas as solicitações apresentadas abaixo usam as seguintes variáveis:
$TOKEN
: token OAuth 2$CUSTOMER
: ID do cliente ou literalmy_customer
Listar esquemas para políticas de impressora
Para listar os esquemas que dizem respeito apenas às políticas de impressoras, aplicaremos o parâmetro filter
à solicitação da lista de serviços de esquema. É possível controlar a paginação do
resultado usando os parâmetros pageSize
e pageToken
.
Solicitação
curl -X GET \
-H "Authorization: Bearer $TOKEN" \
"https://chromepolicy.googleapis.com/v1/customers/$CUSTOMER/policySchemas?filter=chrome.printers&pageSize=2"
Resposta
{
"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"
}
Pesquisar esquemas
Você pode criar consultas de pesquisa complexas usando o parâmetro filter=
na solicitação da lista do serviço de esquema. Por exemplo, se você quer pesquisar esquemas que tenham a palavra "impressora" no nome e a palavra "dispositivos" na descrição, aplique o valor a seguir ao filtro name=printers AND description=devices
.
Saiba como listar esquemas de política.
Solicitação
curl -X GET \
-H "Authorization: Bearer $TOKEN" \
"https://chromepolicy.googleapis.com/v1/customers/$CUSTOMER/policySchemas?filter=name=printers%20AND%20description=devices"
Resposta
{
"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"
}
]
}
Acessar um esquema específico
No resultado acima, há uma lista de esquemas de políticas compatíveis. Cada esquema tem um campo name
que o identifica. No futuro, depois de descobrir o nome dele, você poderá ler o esquema específico diretamente consultando o nome dele no URL da solicitação.
Vamos conferir um exemplo de esquema chrome.printers.AllowForUsers
.
Solicitação
curl -X GET \
-H "Authorization: Bearer $TOKEN" \
"https://chromepolicy.googleapis.com/v1/customers/$CUSTOMER/policySchemas/chrome.printers.AllowForUsers"
Resposta
{
"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"
}
A resposta do esquema da política acima descreve o esquema da política chrome.printers.AllowForUsers
. Campo de aviso additionalTargetKeyNames
.
Esse campo explica que a política exige o fornecimento de chaves/valores extras
ao lidar com ela. Especificamente, para essa política, sempre precisamos
fornecer o identificador de uma impressora.
Ler um valor de política
Vamos ler uma política chrome.printers.AllowForUsers
para uma impressora específica.
Observe o uso do campo additionalTargetKeys
para especificar o ID da impressora na solicitação.
Você pode ler uma política em uma unidade organizacional ou em um grupo.
Na resposta, observe o campo sourceKey
, que especifica de qual
unidade organizacional ou grupo o valor da política vem. Para
unidades organizacionais, há estas possibilidades:
- Se a unidade organizacional de origem for igual à da unidade organizacional fornecida em uma solicitação, significa que a política é aplicada localmente nessa unidade organizacional.
- Se a unidade organizacional de origem for diferente da unidade organizacional fornecida em uma solicitação, isso significa que a política é herdada da unidade organizacional de origem.
- Se não houver nenhum
sourceKey
ou a resposta estiver vazia, isso significa que a política não está definida para o cliente e tem um valor padrão do sistema.
Para Grupos, a sourceKey sempre será a mesma que o grupo que foi especificado na solicitação.
O exemplo a seguir é para uma unidade organizacional. Uma solicitação de grupo seria a mesma, exceto pelo targetResource, que teria "groups/" em vez de "orgunits/" antes do ID.
Solicitação
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"
Resposta
{
"resolvedPolicies": [
{
"targetKey": {
"targetResource": "orgunits/03ph8a2z1xdnme9"
"additionalTargetKeys": {"printer_id":"0gjdgxs208tpef"}
},
"value": {
"policySchema": "chrome.users.AllowForDevices",
"value": {
"allowForDevices": true
}
},
"sourceKey": {
"targetResource": "orgunits/03ph8a2z3qhz81k"
}
}
]
}
Todas as entidades nos recursos de destino podem ser buscadas, basta omitir
additionalTargetKeys
da solicitação. Por exemplo, se additionalTargetKeys
fosse omitido da solicitação acima, todas as impressoras no
recurso de destino especificado eram retornadas.
Ler várias políticas
Fornecer um namespace de esquema com um asterisco (por exemplo, chrome.printers.*
) permite que você leia os valores de todas as políticas nesse namespace em uma determinada unidade organizacional ou grupo. Saiba mais sobre esquemas de políticas.
O exemplo a seguir é para uma unidade organizacional. Uma solicitação de grupo seria a mesma, exceto pelo targetResource, que teria "groups/" em vez de "orgunits/" antes do ID.
Solicitação
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"
Resposta
{
"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="
}
Modificar valor da política
Conforme visto na resposta do esquema da política, a política chrome.printers.AllowForUsers
tem um campo chamado allowForUsers
. Esse campo é de um tipo booleano. O valor de exemplo da política pode ser {allowForUsers: false}
ou {allowForUsers: true}
. Nesse caso específico, temos apenas um campo.
No entanto, outras políticas podem conter vários campos.
Nas solicitações de modificação, é necessário especificar um updateMask
. A máscara de atualização lista todos
os campos que queremos modificar. Se a política já tiver sido aplicada localmente na
unidade organizacional, os campos não listados pela máscara de atualização
permanecerão intactos. Se a política ainda não tiver sido aplicada localmente na
unidade organizacional, e todos os campos não listados pela máscara de atualização
copiarem os valores da unidade organizacional mãe quando apropriado, a política será aplicada localmente.
Os exemplos a seguir são para uma unidade organizacional. As solicitações de grupo são as
mesmas, exceto pelo targetResource, que teria "groups/" em vez de
"orgunits/" antes do ID. Aqui, não permitiremos uma impressora 0gjdgxs208tpef
para
usuários no ID da unidade organizacional 04fatzly4jbjho9
:
Solicitação
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"
Resposta
Uma resposta bem-sucedida está vazia.
{}
Campos com vários valores, como listas ou matrizes, são marcados com um rótulo "LABEL_REPEATED". Para preencher campos de vários valores, use o seguinte formato de matriz JSON: [value1, value2, value3, ...]
.
Por exemplo, para definir URLs de origem para pacotes de apps e extensões como "test1.com", "test2.com" e "test3.com", precisamos enviar a seguinte solicitação:
Solicitação
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"
Resposta
Uma resposta bem-sucedida está vazia.
{}
Há duas versões para todas as políticas que contêm campos NullableDuration. A versão original só aceita string como entrada para NullableDuration e foi descontinuada. Use a versão V2, que substitui o tipo de duração por uma entrada numérica. Por exemplo, para definir a duração máxima da sessão do usuário como 10 minutos, precisamos enviar a seguinte solicitação:
Solicitação
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"
Resposta
Uma resposta bem-sucedida está vazia.
{}
Modificar várias políticas de uma vez
O método batchModify
permite enviar várias modificações de política ao mesmo tempo.
No entanto, nem todas as políticas podem ser agrupadas. Para mais detalhes,
consulte Políticas de atualização em lote.
Neste exemplo, modificaremos na mesma solicitação duas políticas
diferentes (chrome.printers.AllowForDevices
e chrome.printers.AllowForUsers
)
para a mesma impressora.
O exemplo a seguir é para uma unidade organizacional. Uma solicitação de grupo seria a mesma, exceto pelo targetResource, que teria "groups/" em vez de "orgunits/" antes do ID.
Solicitação
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"
Resposta
Uma resposta bem-sucedida está vazia.
{}
Herdar um valor de política em uma unidade organizacional
O método batchInherit
permite que você modifique o status da política em uma unidade organizacional de
"aplicada localmente" para "herdada". Os valores locais serão apagados e a política vai herdar os valores de uma unidade organizacional mãe quando aplicável.
O método batchInherit
também permite que você envie várias solicitações de herança de política ao mesmo tempo. No entanto, nem todas as políticas podem ser agrupadas.
Para mais detalhes,
consulte Políticas de atualização em lote.
Solicitação
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"
Resposta
Uma resposta bem-sucedida está vazia.
{}
Excluir um valor de política em um grupo
O método batchDelete
permite excluir uma política de um grupo. Os valores locais vão ser apagados.
O método batchDelete
também permite que você envie várias solicitações de exclusão de política ao mesmo tempo. No entanto, nem todas as políticas podem ser agrupadas.
Para mais detalhes, consulte
Políticas de atualização em lote.
Solicitação
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"
Resposta
Uma resposta bem-sucedida está vazia.
{}
Listar a ordem de prioridade de um grupo
O método listGroupPriorityOrdering
permite listar a ordem de prioridade dos grupos para um app.
A ordem dos IDs de grupo retornados indica a prioridade em que as configurações serão aplicadas ao app. As políticas dos IDs posteriores serão substituídas por aquelas que tiverem IDs anteriores na lista.
As prioridades do grupo são maiores que as da unidade organizacional.
Nesta solicitação, estamos retornando a ordem de prioridade para o app do usuário do Chrome "exampleapp".
Solicitação
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"
Resposta
{
"policyTargetKey": {
"additionalTargetKeys": {
"app_id": "chrome:exampleapp"
}
},
"policyNamespace": "chrome.users.apps",
"groupIds": [
"03ep43zb2k1nodu",
"01t3h5sf2k52kol",
"03q5sasy2ihwnlz"
]
}
Atualizar a ordem de prioridade de um grupo
O método updateGroupPriorityOrdering
permite atualizar a ordem de prioridade dos grupos em um app.
A ordem dos IDs de grupos na solicitação indica a prioridade em que as configurações serão aplicadas ao app. As políticas dos IDs posteriores serão substituídas por aquelas que tiverem IDs anteriores na lista. A solicitação precisa incluir todos os IDs de grupo aplicados no app no momento.
As prioridades do grupo são maiores que as da unidade organizacional.
Nesta solicitação, estamos definindo a ordem de prioridade para o aplicativo do usuário do Chrome "exampleapp".
Solicitação
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"
Resposta
Uma resposta bem-sucedida está vazia.
{}
Como lidar com políticas que exigem confirmação
Alguns esquemas de política especificam "avisos" para determinados valores de um determinado campo que exigem confirmação.
Exemplo para a política 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"
}
No exemplo acima, a definição do valor do campo pluginVmAllowed
como true
está
associada a um aviso que tem acknowledgementRequired
. Para definir corretamente
o valor desse campo como true
, envie uma solicitação que especifique
o campo de confirmação ackNoticeForPluginVmAllowedSetToTrue
para true
.
Caso contrário, haverá um erro na solicitação.
Neste exemplo, você precisaria enviar a seguinte solicitação de modificação em lote.
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"
Como configurar políticas de arquivos
Algumas políticas têm campos com o tipo UploadedFile
. É necessário fazer upload do arquivo que você quer definir como o valor dessas políticas para o servidor da API a fim de receber um URL a ser usado nas solicitações BatchModify
.
Neste exemplo, vamos configurar chrome.users.Wallpaper
fazendo upload de um
arquivo JPEG.
Fazer upload do arquivo
Solicitação
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"
Resposta
Uma resposta bem-sucedida deve conter o URL para acessar o arquivo:
{
"downloadUri": "https://storage.googleapis.com/chromeos-mgmt/0gjdgxs370bkl6/ChromeOsWallpaper/32ac50ab-b5ae-4bba-afa8-b6b443912897"
}
Definir a política do arquivo
Solicitação
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"
Resposta
Uma resposta bem-sucedida deve estar vazia.
{}