Trabalhe com dados JSON estendidos

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.

To learn more about JSON, BSON, and Extended JSON, see the JSON and BSON resource and Extended JSON MongoDB Server manual entry.

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	Um formato de string que evita a perda de informações do tipo BSON durante conversões de dados. Esse formato prioriza a preservação do tipo na perda de legibilidade humana e interoperabilidade com formatos mais antigos. Para saber mais sobre este formato, consulte JsonMode.EXTENDED na documentação da API.
Descontraído	Um formato de string que descreve documentos BSON com alguma perda de informação de tipo. Este formato prioriza a legibilidade humana e a interoperabilidade na perda de determinadas informações de tipos. O driver Scala usa o modo relaxado por padrão. Para saber mais sobre este formato, consulte JsonMode.RELAXED na documentação da API.
Shell	Um formato de string que corresponde à sintaxe usada no MongoDB shell. Esse formato prioriza a compatibilidade com o MongoDB shell, que frequentemente usa funções JavaScript para representar tipos. Para saber mais sobre esse formato, consulte JsonMode.SHELL na documentação da API.

Observação

O driver Scala analisa o tipo $uuid Extended JSON de uma string para um objeto 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 JSON estendida em objetos Scala usando as classes de documento do driver Scala ou usando a biblioteca BSON diretamente. As seções a seguir mostram como usar cada abordagem.

Classe de documento

Você pode ler uma string JSON estendida em um objeto de documento Scala chamando o método estático parse() em BsonDocument e, em seguida, envolvendo o resultado em uma instância Scala Document. Essa abordagem analisa a string JSON estendida em qualquer um dos formatos e retorna um Document contendo os dados.

O exemplo a seguir mostra como você pode ler uma string JSON estendida em um objeto Document chamando BsonDocument.parse() e passando o resultado para a fábrica Document:

val ejsonStr = """{"_id": {"$oid": "507f1f77bcf86cd799439011"}, "myNumber": {"$numberLong": "4794261"}}"""
val document = Document(BsonDocument.parse(ejsonStr))
println(document)

Iterable((_id,BsonObjectId{value=507f1f77bcf86cd799439011}), (myNumber,BsonInt64{value=4794261}))

To learn more about documents in MongoDB, see Documents in the MongoDB Server manual.

Biblioteca BSON

Você também pode ler uma string de Extended JSON em objetos Scala sem usar as classes de documentos do driver Scala do MongoDB, basta usar a classe JsonReader. Essa classe contém métodos para analisar sequencialmente os campos e valores em qualquer formato de string de Extended JSON, sendo gerado objetos Scala. As classes de documentos driver também usam esta classe para analisar Extended JSON.

O seguinte exemplo de código mostra como usar a classe JsonReader para converter uma string de Extended JSON em objetos Scala:

val ejsonStr = """{"_id": {"$oid": "507f1f77bcf86cd799439011"}, "myNumber": {"$numberLong": "4794261"}}"""
val reader = new JsonReader(ejsonStr)
reader.readStartDocument()
val id = reader.readObjectId("_id")
val myNumber = reader.readInt64("myNumber")
reader.readEndDocument()
println(s"$id is type: ${id.getClass.getName}")
println(s"$myNumber is type: ${myNumber.getClass.getName}")

507f1f77bcf86cd799439011 is type: org.bson.types.ObjectId
4794261 is type: long

Para obter mais informações, consulte a documentação da API do JsonReader.

Aviso

Valide entradas não confiáveis antes de converter JSON em BSON

Se você converter uma string JSON para BSON e usar o BSON resultante em uma query, atualizar ou comando, um invasor pode injetar operadores ou valores de campo inesperados que alteram o significado da operação. Esse risco é maior quando o JSON se origina de um usuário, uma solicitação de API ou outra fonte não confiável.

To learn more about validating input before conversion, see Validate Untrusted Input Before Converting JSON to BSON.

Escrever JSON estendido

Você pode gravar uma string JSON estendida a partir de seus dados usando as classes de documento do driver Scala ou usando a biblioteca BSON diretamente. As seções a seguir mostram como usar cada abordagem.

Classe de documento

Você pode gravar uma string de JSON estendida a partir de uma instância de Document ou BsonDocument chamando o método toJson(). Por padrão, o método toJson() gera a string no formato de modo relaxado. Para usar um formato diferente, passe uma instância da classe JsonWriterSettings para o método toJson().

O exemplo a seguir chama o método toJson() sem argumentos para gerar o JSON estendido no formato de modo relaxado padrão:

val document = Document(
  "_id" -> BsonObjectId(new ObjectId("507f1f77bcf86cd799439012")),
  "myNumber" -> BsonInt64(11223344L)
)
val ejsonStr = document.toJson()
println(ejsonStr)

{"_id": {"$oid": "507f1f77bcf86cd799439012"}, "myNumber": 11223344}

Biblioteca BSON

Você também pode gerar uma string de Extended JSON a partir de dados em objetos Scala usando a biblioteca BSON com a classe JsonWriter . Para construir uma instância de JsonWriter, passe uma subclasse de um Writer Java para especificar como você deseja gerar a saída do Extended JSON. Você também pode passar uma instância do JsonWriterSettings para especificar opções como o formato do Extended JSON. Por padrão, o JsonWriter usa o formato de modo relaxado. As classes de documentos de driver Scala também usam esta classe para converter BSON para Extended JSON.

O exemplo de código abaixo mostra como usar o JsonWriter para criar uma string de Extended JSON e fazer sua saída para System.out. O exemplo especifica o formato passando o método construtor outputMode() para a constante JsonMode.EXTENDED:

val writer = new StringWriter()
val jsonWriter = new JsonWriter(writer,
    JsonWriterSettings.builder().outputMode(JsonMode.EXTENDED).build())
jsonWriter.writeStartDocument()
jsonWriter.writeObjectId("_id", new ObjectId("507f1f77bcf86cd799439012"))
jsonWriter.writeInt64("myNumber", 11223344L)
jsonWriter.writeEndDocument()
println(writer.toString())

{"_id": {"$oid": "507f1f77bcf86cd799439012"}, "myNumber": {"$numberLong": "11223344"}}

Para obter mais informações sobre os métodos e as classes mencionadas nesta seção, consulte a seguinte documentação da API:

Conversão personalizada de tipo de BSON

Além de especificar o outputMode() para formatar a saída JSON, você pode personalizar ainda mais a saída adicionando conversores à sua instância JsonWriterSettings.Builder. Esses métodos de conversores detectam BSON types específicos e executam a lógica definida pelo Converter passado para eles.

O código de amostra a seguir exibe como anexar conversores, definidos como expressões Lambda, para simplificar a saída JSON no modo relaxado:

val settings = JsonWriterSettings.builder()
  .outputMode(JsonMode.RELAXED)
  .objectIdConverter((value, writer) => writer.writeString(value.toHexString))
  .timestampConverter((value, writer) => {
    val instant = Instant.ofEpochSecond(value.getTime.toLong)
    writer.writeString(
      DateTimeFormatter.ISO_LOCAL_DATE_TIME.withZone(ZoneOffset.UTC).format(instant))
  })
  .build()
val document = Document(
  "_id" -> BsonObjectId(new ObjectId("507f1f77bcf86cd799439012")),
  "createdAt" -> new BsonTimestamp(1601516589, 1),
  "myNumber" -> BsonInt64(4794261L)
)
println(document.toJson(settings))

{"_id": "507f1f77bcf86cd799439012", "createdAt": "2020-10-01T01:43:09", "myNumber": 4794261}
// Without specifying the converters, the Relaxed mode JSON output
// would look something like this:
{"_id": {"$oid": "507f1f77bcf86cd799439012"}, "createdAt": {"$timestamp": {"t": 1601516589, "i": 1}}, "myNumber": 4794261}

Para obter mais informações sobre os métodos e as classes mencionadas nesta seção, consulte a seguinte documentação da API:

Voltar

Codecs

Séries temporais