通过

Test-Json

  • 参考
模块:
Microsoft.PowerShell.Utility

测试某个字符串是否为有效的 JSON 文档

语法

Test-Json
    [-Json] <String>
    [<CommonParameters>]
Test-Json
    [-Json] <string>
    [-Schema] <string>
    [<CommonParameters>]
Test-Json
    [-Json] <string>
    [-SchemaFile] <string>
    [<CommonParameters>]
Test-Json
    [-Path] <string>
    [<CommonParameters>]
Test-Json
    [-Path] <string>
    [-Schema] <string>
    [<CommonParameters>]
Test-Json
    [-Path] <string>
    [-SchemaFile] <string>
    [<CommonParameters>]
Test-Json
    [-LiteralPath] <string>
    [<CommonParameters>]
Test-Json
    [-LiteralPath] <string>
    [-Schema] <string>
    [<CommonParameters>]
Test-Json
    [-LiteralPath] <string>
    [-SchemaFile] <string>
    [<CommonParameters>]

说明

Test-Json cmdlet 可测试字符串是否为有效的 JavaScript 对象表示法 (JSON) 文档，并且还可选择性地根据提供的架构验证该 JSON 文档。

然后，可将已验证的字符串与 ConvertFrom-Json cmdlet 配合使用，将 JSON 格式的字符串转换为 JSON 对象，从而在 PowerShell 中轻松管理该对象，或者将其发送到访问 JSON 输入的其他程序或 Web 服务。

许多网站使用 JSON（而不是 XML）来序列化用于在服务器和基于 Web 的应用之间进行通信的数据。

此 cmdlet 是在 PowerShell 6.1 中引入的

示例

示例 1：测试某个对象是否为有效的 JSON

此示例测试输入字符串是否为有效的 JSON 文档。

'{"name": "Ashley", "age": 25}' | Test-Json

True

示例 2：依据提供的架构测试某个对象

此示例采用包含 JSON 架构的字符串，并将其与输入字符串进行比较。

$schema = @'
{
  "definitions": {},
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "http://example.com/root.json",
  "type": "object",
  "title": "The Root Schema",
  "required": [
    "name",
    "age"
  ],
  "properties": {
    "name": {
      "$id": "#/properties/name",
      "type": "string",
      "title": "The Name Schema",
      "default": "",
      "examples": [
        "Ashley"
      ],
      "pattern": "^(.*)$"
    },
    "age": {
      "$id": "#/properties/age",
      "type": "integer",
      "title": "The Age Schema",
      "default": 0,
      "examples": [
        25
      ]
    }
  }
}
'@
'{"name": "Ashley", "age": "25"}' | Test-Json -Schema $schema

Test-Json:
Line |
  35 |  '{"name": "Ashley", "age": "25"}' | Test-Json -Schema $schema
     |                                      ~~~~~~~~~~~~~~~~~~~~~~~~~
     | The JSON is not valid with the schema: Value is "string" but should be "integer" at '/age'
False

在此示例中，我们收到一个错误，因为架构希望 age 为整数，但我们测试的 JSON 输入却使用了字符串值。

有关详细信息，请参阅 JSON 架构。

示例 3：依据文件中的架构测试某个对象

JSON 架构可以使用 $ref 关键字来引用定义。 $ref 可以解析为引用另一个文件的 URI。 SchemaFile 参数接受 JSON 架构文件的文本路径，并允许依据此类架构来验证 JSON 文件。

在此示例中，schema.json 文件引用了 definitions.json。

Get-Content schema.json

{
  "description":"A person",
  "type":"object",
  "properties":{
    "name":{
      "$ref":"definitions.json#/definitions/name"
    },
    "hobbies":{
      "$ref":"definitions.json#/definitions/hobbies"
    }
  }
}

Get-Content definitions.json

{
  "definitions":{
    "name":{
      "type":"string"
    },
    "hobbies":{
      "type":"array",
      "items":{
        "type":"string"
      }
    }
  }
}

'{"name": "James", "hobbies": [".NET", "Blogging"]}' | Test-Json -SchemaFile 'schema.json'

True

有关详细信息，请参阅构建复杂架构。

参数

-Json

指定要测试有效性的 JSON 字符串。 输入一个包含字符串的变量，或键入可获取字符串的命令或表达式。 还可以通过管道将字符串传递给 Test-Json。

Json 参数是必需的。

类型:String
Position:0
默认值:None
必需:True
接受管道输入:True
接受通配符:False

-LiteralPath

指定 JSON 文件的路径。 LiteralPath 的值严格按照所键入的形式使用。 不会将任何字符解释为通配符。 如果路径包括转义符，请将其括在单引号中。 单引号告知 PowerShell 不要将任何字符解释为转义序列。

此参数已在 PowerShell 7.4 中添加。

类型:String
别名:PSPath, LP
Position:0
默认值:None
必需:True
接受管道输入:True
接受通配符:False

-Path

指定 JSON 文件的路径。 此 cmdlet 获取位于指定位置的项。 允许使用通配符，但模式必须解析为单个文件。

此参数已在 PowerShell 7.4 中添加。

类型:String
Position:0
默认值:None
必需:True
接受管道输入:True
接受通配符:True

-Schema

指定验证 JSON 输入时要依据的架构。 如果传递了此参数，则 Test-Json 将验证 JSON 输入是否符合 Schema 参数指定的规范，并且仅当输入符合提供的架构时才返回 $true。

有关详细信息，请参阅 JSON 架构。

类型:String
Position:1
默认值:None
必需:True
接受管道输入:False
接受通配符:False

-SchemaFile

指定用来验证 JSON 输入的架构文件。 如果使用了此参数，则只有当 JSON 输入符合 SchemaFile 参数指定的文件中定义的架构时，Test-Json 才会返回 $true。

有关详细信息，请参阅 JSON 架构。

类型:String
Position:1
默认值:None
必需:True
接受管道输入:False
接受通配符:False

输入

String

可以通过管道将 JSON 字符串传递给此 cmdlet。

输出

Boolean

如果 JSON 有效，则此 cmdlet 返回 $true，否则返回 $false。

备注

从 PowerShell 6 开始，PowerShell 对 JSON 函数使用 Newtonsoft.Json 程序集。 Newtonsoft 的实现提供了对 JSON 标准的多项扩展，例如，支持使用注释和单引号。 有关完整的功能列表，请参阅 https://www.newtonsoft.com/json 中的 Newtonsoft 文档。

从 PowerShell 7.4 开始， Test-Json 使用 System.Text.Json 进行 JSON 分析和 JsonSchema.NET 进行架构验证。 通过这些更改， Test-Json：

  • 不再支持 Draft 4 架构
  • 仅支持严格符合 JSON

有关 Newtonsoft.Json 和 System.Text.Json 之间的差异的完整列表，请参阅从 Newtonsoft.Json 迁移到 System.Text.Json 中的差异表。

有关 JSON 架构规范的详细信息，请参阅 JSON-Schema.org 中的文档。