/ /

Extended JSON

Visão geral

Neste guia, você verá como usar o formato de dados JSON estendido ao interagir com documentos do MongoDB.

JSON é um formato de dados legível por humanos que representa os valores de objetos, arrays, números, strings, booleans e nulos. Este formato suporta apenas um subconjunto de tipos de dados BSON, que é o formato que o MongoDB utiliza para armazenar dados. O formato Extended JSON aceita mais tipos de BSON, definindo um conjunto reservado de chaves prefixadas com "$" para representar informações de tipos de campo que correspondem diretamente a cada tipo em BSON.

Para saber mais sobre JSON, BSON e Extended JSON, consulte o recurso JSON e BSON e a entrada de manual do Extended JSON MongoDB Server.

Formatos Extended JSON

O MongoDB Extended JSON fornece formatos de string para representar dados BSON. Cada formato está em conformidade com o JSON RFC e atende a casos de uso específicos.

A tabela abaixo descreve cada formato de Extended JSON:

Nome	Descrição
Estendido ou Canônico	A string format that avoids loss of BSON type information during data conversions. This format prioritizes type preservation at the loss of human-readability and interoperability with older formats. The Ruby driver uses this mode by default.
Descontraído	A string format that describes BSON documents with some type information loss. This format prioritizes human-readability and interoperability at the loss of certain type information. To specify this mode, pass `:relaxed` as the `mode` option.
Shell	A string format that matches the syntax used in the MongoDB shell. This format prioritizes compatibility with the MongoDB shell, which often uses JavaScript functions to represent types. To specify this mode, pass `:legacy` as the `mode` option.

Observação

O driver Ruby analisa o tipo de JSON estendido $uuid de uma string para um objeto BSON::Binary de subtipo binário 4. Para obter mais informações sobre a análise do campo $uuid, consulte a seção regras especiais para analisar campos $uuid na especificação de JSON estendida.

Exemplos de JSON estendido

Os exemplos abaixo mostram um documento contendo um campo de ObjectId, data e número longo representado em cada formato Extended JSON. Clique na aba correspondente ao formato do exemplo que deseja ver:

{
  "_id": { "$oid": "573a1391f29313caabcd9637" },
  "createdAt": { "$date": { "$numberLong": "1601499609" }},
  "numViews": { "$numberLong": "36520312" }
}

{
  "_id": { "$oid": "573a1391f29313caabcd9637" },
  "createdAt": { "$date": "2020-09-30T18:22:51.648Z" },
  "numViews": 36520312
}

{
  "_id": ObjectId("573a1391f29313caabcd9637"),
  "createdAt": ISODate("2020-09-30T18:22:51.648Z"),
  "numViews": NumberLong("36520312")
}

Ler Extended JSON

Você pode ler uma string de Extended JSON em uma array Ruby chamando o método BSON::ExtJSON.parse. Este método analisa uma string de JSON estendida e retorna uma array contendo os dados.

O exemplo abaixo mostra como ler uma string de Extended JSON em uma array de hashes usando o método parse:

require 'bson'
ex_json = '''[
    {"foo": [1, 2]},
    {"bar": {"hello": "world"}},
    {"code": {
    "$scope": {},
    "$code": "function x() { return 1; }"
    }},
    {"bin": {
    "$type": "80",
    "$binary": "AQIDBA=="
    }}
    ]'''
doc = BSON::ExtJSON.parse(ex_json)
puts doc.class
puts doc

{"foo" => [1, 2]}
{"bar" => {"hello" => "world"}}
{"code" => #<BSON::CodeWithScope:0x0000000123f398e0 @javascript="function x() { return 1; }", @scope={}>}
{"bin" => <BSON::Binary:0x7144 type=user data=0x01020304...>}

Escrever JSON estendido

Você pode gravar uma string de JSON estendida usando o método as_extended_json. Por padrão, este método retorna a string de JSON estendida no formato canônico, mas você pode especificar formatos relaxados ou legado passando um argumento mode.

Observação

Versão legada

A opção de formato legado diz ao driver Ruby para serializar os tipos BSON com o formato MongoDB Extended JSON v1, que é anterior aos formatos relaxados e canônicos atuais.

Para obter mais informações, consulte a página MongoDB Extended JSON v1 no manual do servidor.

O método as_extended_json está disponível para vários tipos de bibliotecas principais e padrão, incluindo Array e Hash. O exemplo a seguir cria strings de JSON estendida nos formatos canônico, relaxado e legado a partir de uma array de hashes:

require 'bson'
hash_array = [
    { "foo" => [1, 2] },
    { "bin" => BSON::Binary.new("\x01\x02\x03\x04", :user) },
    { "number" => BSON::Int64.new(42) }
]
json_string_canonical = hash_array.as_extended_json
json_string_relaxed = hash_array.as_extended_json(mode: :relaxed)
json_string_legacy = hash_array.as_extended_json(mode: :legacy)
puts "canonical:\t #{json_string_canonical}"
puts "relaxed:\t #{json_string_relaxed}"
puts "legacy:\t\t #{json_string_legacy}"

canonical: [{"foo":[{"$numberInt":"1"},{"$numberInt":"2"}]},{"bin":{"$binary":{"base64":"AQIDBA==","subType":"80"}}},{"number":{"$numberLong":"42"}}]
relaxed:   [{"foo":[1,2]},{"bin":{"$binary":{"base64":"AQIDBA==","subType":"80"}}},{"number":42}]
legacy:    [{"foo":[1,2]},{"bin":{"$binary":"AQIDBA==","$type":"80"}},{"number":42}]

Informações adicionais

Para obter mais informações, consulte os seguintes recursos:

Documentação da API

Páginas manuais do servidor

MongoDB Extended JSON (v2)

Voltar

BSON

Dados de Time Series