Chrome Policy API のコードサンプル

API 機能の概要については、Chrome Policy API のページをご覧ください。

以下のリクエストでは、プリンタポリシーの例で Policy API によるポリシー管理について説明しています。以下に示すリクエストでは、次の変数を使用します。

$TOKEN - OAuth 2 トークン
$CUSTOMER - 顧客の ID またはリテラル my_customer

プリンタポリシーのスキーマ一覧を取得する

プリンタのポリシーにのみ関連するスキーマをリスティングするには、Schema Service リストリクエストに filter パラメータを適用します。 pageSize パラメータと pageToken パラメータを使用すると、結果のページ分けを制御できます。

リクエスト:

  curl -X GET \
  --header "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"
}

スキーマを検索する

Schema Service リストリクエストで filter= パラメータを使用すると、複雑な検索クエリを作成できます。たとえば、名前に「printer」という単語が含まれていて、かつ、説明に「devices」という単語を含むスキーマを検索する場合は、フィルタ name=printers AND description=devices に以下の値を適用します。フィルタ構文の詳細については、こちらをご覧ください。

リクエスト:

  curl -X GET \
  --header "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 フィールドがあります。スキーマ名がわかると、リクエスト URL のスキーマ名を参照して、特定のスキーマを直接読み取ることができます。 chrome.printers.AllowForUsers スキーマの例を見てみましょう。

リクエスト:

  curl -X GET \
  --header "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 フィールドに注目してください。このフィールドでは、このポリシーを扱うときに追加の Key-Value を指定する必要があることが示されています。特に、このポリシーの場合、プリンタの ID を常に指定する必要があります。

組織部門のポリシー値を読み取る

ここでは、特定の組織部門の特定プリンタに対するポリシー chrome.printers.AllowForUsers を読み取ります。リクエストでは、additionalTargetKeys フィールドを使用してプリンタ ID を指定しています。

レスポンスの sourceKey フィールドは、ポリシー値のソース組織部門を指定します。

ソース組織部門がリクエストで指定された組織部門と同じ場合、ポリシーはこの組織部門にローカルに適用されています。
ソース組織部門がリクエストで指定された組織部門と異なる場合、ポリシーはソース組織部門から継承されています。
sourceKey が存在しない場合、またはレスポンスが空の場合は、顧客にこのポリシーに設定されておらず、デフォルトのシステム値が設定されています。

リクエスト:

  curl -X POST \
  -H "Content-Type: application/json" \
  --header "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 を省略した場合、03ph8a2z1xdnme9 組織部門のすべてのプリンタが返されます。

組織部門の複数ポリシーを読み取る

* の入ったスキーマ名前空間（例: chrome.printers.*）を指定すると、特定の組織部門でこの名前空間の下にあるすべてのポリシーの値を読み取ることができます。スキーマの名前空間については、ポリシースキーマのページをご覧ください。

リクエスト:

  curl -X POST \
  -H "Content-Type: application/json" \
  --header "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 という名前のフィールドが 1 つあります。このフィールドはブール値型です。ポリシーの値の例は、{allowForUsers: false} または {allowForUsers: true} です。この例では 1 つのフィールドしかありませんが、他のポリシーには複数のフィールドが含まれる場合があります。

変更リクエストでは、updateMask を指定する必要があります。更新マスクには、変更するすべてのフィールドを列挙します。組織部門にすでにポリシーがローカルに適用されている場合、更新マスクに列挙されていないフィールドは変更されません。ポリシーが組織部門でまだローカルに適用されていない場合に、更新マスクに列挙されていないすべてのフィールドには、該当する場合、親組織部門から値がコピーされ、ポリシー全体がローカルに適用されます。

組織部門 04fatzly4jbjho9 のユーザーに対してプリンタ 0gjdgxs208tpef を禁止するには、次のリクエストを送信する必要があります。

リクエスト:

curl -X POST \
  -H "Content-Type: application/json" \
  --header "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"

レスポンス:

成功した場合のレスポンスは空（{}）です。

複数のポリシーを一度に変更する

BatchModify メソッドを使用すると、複数ポリシーの変更を同時に送信できます。ただし、どのポリシーでも一括処理できるわけではありません。一括処理に関するルールについては、Policy API のページをご覧ください。

この例では、同じリクエストで、同じプリンタと同じ組織部門に 2 つの異なるポリシー（chrome.printers.AllowForDevices と chrome.printers.AllowForUsers）を変更します。

リクエスト:

curl -X POST \
  -H "Content-Type: application/json" \
  --header "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 メソッドを使用すると、複数のポリシー継承リクエストを同時に送信できます。ただし、どのポリシーでも一括処理できるわけではありません。一括処理に関するルールについては、Policy API のページをご覧ください。

リクエスト:

curl -X POST \
  -H "Content-Type: application/json" \
  --header "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"

レスポンス:

成功した場合のレスポンスは空（{}）です。

確認が必要なポリシーの処理

一部のポリシースキーマは、確認を必要とする特定フィールドの特定値に「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 sse 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" \
  --header "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」と入力されているフィールドがあります。この場合、BatchModify リクエストで使用する URL を取得するために、これらのポリシーの値として設定するファイルを API サーバーにアップロードする必要があります。

この例では、jpeg ファイルをアップロードして chrome.users.Wallpaper を設定します。

ファイルをアップロードする

リクエスト:

curl -X POST \
  -H "Content-Type: image/jpeg" \
  --header "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"

成功した場合、レスポンスにはファイルにアクセスするための URL が含まれます。

{
  "downloadUri": "https://storage.googleapis.com/chromeos-mgmt/0gjdgxs370bkl6/ChromeOsWallpaper/32ac50ab-b5ae-4bba-afa8-b6b443912897"
}

ファイルポリシーを設定する

リクエスト:

curl -X POST \
  -H "Content-Type: application/json" \
  --header "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"

成功した場合のレスポンスは空です。

{}

Chrome Policy API のコードサンプル

プリンタ ポリシーのスキーマ一覧を取得する

リクエスト:

レスポンス:

スキーマを検索する

リクエスト:

レスポンス:

特定のスキーマを取得する

リクエスト:

レスポンス:

組織部門のポリシー値を読み取る

リクエスト:

レスポンス:

組織部門の複数ポリシーを読み取る

リクエスト:

レスポンス:

組織部門のポリシー値を変更する

リクエスト:

レスポンス:

複数のポリシーを一度に変更する

リクエスト:

レスポンス:

組織部門のポリシー値を継承する

リクエスト:

レスポンス:

確認が必要なポリシーの処理

ファイル ポリシーの設定

ファイルをアップロードする

ファイル ポリシーを設定する

プリンタポリシーのスキーマ一覧を取得する

ファイルポリシーの設定

ファイルポリシーを設定する