/ /

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.

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	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 esse 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. Esse formato prioriza a legibilidade humana e a interoperabilidade na perda de determinados tipos de informações. O driver Java Reactive Streams usa o modo Relaxed por padrão. Para saber mais sobre esse formato, consulte JsonMode.RELAXED na documentação da API.
Shell	Um formato de string que corresponda à sintaxe usada no MongoDB shell. Esse formato prioriza a compatibilidade com o shell do MongoDB , 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 Java Streams analisa o $uuid tipo de JSON estendido de uma string para um BsonBinary objeto de subtipo 4 binário. Para obter mais informações sobre a $uuid análise do campo, 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

Esta seção mostra como ler valores de JSON estendido em objetos Java das seguintes maneiras:

Use as classes de documentos
Usar a classe JsonReader

Use as classes de documentos

Para ler uma string JSON estendida em um objeto de documento Java, chame o método estático parse() da classe Document ou BsonDocument. Este método analisa a string JSON estendida e armazena seus dados em uma instância da classe de documento especificada.

O exemplo seguinte utiliza o método parse() para ler uma string de Extended JSON em um objeto Document :

String ejsonStr = "{ \"_id\": { \"$oid\": \"507f1f77bcf86cd799439011\" },"
        + " \"myNumber\": { \"$numberLong\": \"4794261\" } }";
Document doc = Document.parse(ejsonStr);
System.out.println(doc);

Document{{_id=507f1f77bcf86cd799439011, myNumber=4794261}}

Usar a classe JsonReader

Para ler uma string de Extended JSON em objetos Java sem usar as classes de documentos, use a classe JsonReader da biblioteca BSON. Essa classe contém métodos para analisar sequencialmente os campos e valores da string de Extended JSON e retorná-los como objetos Java. As classes de documentos do driver também usam essa classe para analisar Extended JSON.

O código a seguir usa métodos fornecidos pela classe JsonReader para converter uma string de Extended JSON em objetos Java:

String string = "{ \"_id\": { \"$oid\": \"507f1f77bcf86cd799439011\" },"
        + " \"myNumber\": { \"$numberLong\": \"4794261\" } }";
JsonReader jsonReader = new JsonReader(string);
jsonReader.readStartDocument();
// Reads the "_id" field value
jsonReader.readName("_id");
ObjectId id = jsonReader.readObjectId();
// Reads the "myNumber" field value
jsonReader.readName("myNumber");
long myNumber = jsonReader.readInt64();
jsonReader.readEndDocument();
System.out.println(id + " is type: " + id.getClass().getName());
System.out.println(myNumber + " is type: " + Long.class.getName());
jsonReader.close();

507f1f77bcf86cd799439011 is type: org.bson.types.ObjectId
4794261 is type: java.lang.Long

Aviso

Validar entrada não confiável antes de converter JSON em BSON

Se você converter uma string JSON em BSON e utilizar o BSON resultante em uma query, atualização ou comando, um invasor poderá 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, de uma solicitação de API ou de outra fonte não confiável.

Para saber mais sobre como validar a entrada antes da conversão, consulte Validar entrada não confiável antes de converter JSON em BSON.

Escrever JSON estendido

Esta seção mostra como gravar valores de JSON estendido a partir de objetos Java das seguintes maneiras:

Use as classes de documentos
Usar a classe JsonWriter

Use as classes de documentos

Para gravar uma string de JSON estendida a partir de um objeto Document ou BsonDocument, chame o método toJson(). Você pode passar a esse método um parâmetro de objeto JsonWriterSettings para especificar o formato de JSON estendido.

O exemplo a seguir grava dados Document como JSON estendido do modo relaxado:

Document doc = new Document()
        .append("_id", new ObjectId("507f1f77bcf86cd799439012"))
        .append("createdAt", Date.from(Instant.ofEpochMilli(1601499609000L)))
        .append("myNumber", 4794261);
JsonWriterSettings settings = JsonWriterSettings.builder()
        .outputMode(JsonMode.RELAXED)
        .build();
System.out.println(doc.toJson(settings));

{"_id": {"$oid": "507f1f77bcf86cd799439012"}, "createdAt": {"$date": "2020-09-30T21:00:09Z"}, "myNumber": 4794261}

Usar a classe JsonWriter

Para gerar uma string de Extended JSON a partir de dados armazenados em objetos Java, você pode usar a classe JsonWriter da biblioteca BSON. Para construir um objeto JsonWriter, passe uma subclasse de um Writer Java para especificar como você deseja gerar a saída do Extended JSON. Opcionalmente, você 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 BSON também usam esta classe para converter BSON para Extended JSON.

O exemplo a seguir usa um objeto JsonWriter para criar valores de string JSON estendido do modo canônico e enviá-los para System.out:

JsonWriterSettings settings = JsonWriterSettings.builder()
        .outputMode(JsonMode.EXTENDED)
        .build();
JsonWriter jsonWriter = new JsonWriter(
        new BufferedWriter(new OutputStreamWriter(System.out)), settings);
jsonWriter.writeStartDocument();
jsonWriter.writeName("_id");
jsonWriter.writeObjectId(new ObjectId("507f1f77bcf86cd799439012"));
jsonWriter.writeName("myNumber");
jsonWriter.writeInt64(11223344L);
jsonWriter.writeEndDocument();
jsonWriter.flush();

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

Conversão personalizada de tipo de BSON

Além de especificar o formato de saída JSON estendido, você pode personalizar ainda mais a saída adicionando conversores ao seu objeto JsonWriterSettings. Esses métodos de conversor especificam a lógica para lidar com diferentes tipos de dados durante o processo de conversão.

O exemplo a seguir converte o mesmo documento que o exemplo Usar classes de documentos. No entanto, este exemplo define os objectIdConverter() dateTimeConverter() métodos conversores e em um JsonWriterSettings objeto para simplificar a saída de Extended JSON do modo Relaxed:

JsonWriterSettings settings = JsonWriterSettings.builder()
        .outputMode(JsonMode.RELAXED)
        .objectIdConverter((value, writer) -> writer.writeString(value.toHexString()))
        .dateTimeConverter((value, writer) -> {
            ZonedDateTime zonedDateTime = Instant.ofEpochMilli(value).atZone(ZoneOffset.UTC);
            writer.writeString(DateTimeFormatter.ISO_DATE_TIME.format(zonedDateTime));
        })
        .build();
Document doc = new Document()
        .append("_id", new ObjectId("507f1f77bcf86cd799439012"))
        .append("createdAt", Date.from(Instant.ofEpochMilli(1601499609000L)))
        .append("myNumber", 4794261);
System.out.println(doc.toJson(settings));

{"_id": "507f1f77bcf86cd799439012", "createdAt": "2020-09-30T21:00:09Z", "myNumber": 4794261}

Documentação da API

Para saber mais sobre qualquer um dos métodos ou tipos discutidos neste guia, consulte a seguinte documentação da API:

Voltar

Codecs

Indexes