Overview
En esta guía, aprenderás a crear documentos BSON, a guardar documentos BSON en un archivo y a leer datos BSON de un archivo usando el driver C.
BSON, o JSON binario, es el formato de datos que utiliza MongoDB para organizar y almacenar datos. Este formato de datos incluye todos los tipos de estructura de datos JSON y añade soporte para tipos como fechas, enteros de diferentes tamaños, ObjectIds y datos binarios. Para obtener una lista completa de los tipos admitidos, consulta la página del manual del servidor Tipos BSON.
Puedes usar documentos BSON en tu aplicación en C incluyendo el paquete libbson.
Los ejemplos de código en esta guía usan el siguiente documento BSON como ejemplo:
{ "address" : { "street" : "Pizza St", "zipcode" : "10003" }, "coord" : [-73.982419, 41.579505] "cuisine" : "Pizza", "name" : "Mongo's Pizza"}Crear un Documento BSON
Los documentos BSON están representados por el tipo bson_t en el controlador C. Puedes utilizar la función BCON_NEW() para crear una instancia bson_t. El siguiente ejemplo crea una representación bson_t del documento BSON de muestra:
bson_t *doc = BCON_NEW( "address", "{", "street", BCON_UTF8("Pizza St"), "zipcode", BCON_UTF8("10003"), "}", "coord", "[", BCON_DOUBLE(-73.982419), BCON_DOUBLE(41.579505), "]", "cuisine", BCON_UTF8("Pizza"), "name", BCON_UTF8("Mongo's Pizza"));Nota
Valores de campo BSON
Al crear o agregar campos a un documento BSON, asegúrate de usar la función BCON_* adecuada para representar correctamente los valores de los campos. Para obtener una lista completa de funciones BCON_*, consulta el archivo bson-bcon.h en el repositorio de GitHub del driver C.
Añadir a un documento BSON
Puedes agregar pares de campo-valor a una instancia de bson_t existente usando la función BCON_APPEND(). El siguiente ejemplo anexa un nuevo campo yearEstablished y valor al documento BSON de ejemplo:
BCON_APPEND(doc, "yearEstablished", BCON_INT32(1996));También se puede usar la función bson_append_* que corresponde al tipo de datos del valor que debe añadirse. El siguiente ejemplo añade el mismo par campo-valor que el ejemplo anterior utilizando la función bson_append_int32():
bson_append_int32(doc, "yearEstablished", -1, 1996);Para obtener una lista completa de las funciones de bson_append_*, consulte bson_t en la documentación API de libbson.
Guardar BSON en un archivo
Puedes usar la función bson_get_data() con la librería estándar de entrada/salida de archivos de C para guardar datos BSON en un archivo. El siguiente ejemplo escribe el documento BSON de muestra en un archivo llamado output.bson:
FILE *fp;
if ((fp = fopen("output.bson", "wb"))) { fwrite(bson_get_data(doc), 1, doc->len, fp); fclose(fp);} else { fprintf(stderr, "Failed to open file for writing.\n"); return EXIT_FAILURE;}Leyendo BSON desde un archivo
Puedes usar el tipo bson_reader_t para leer una secuencia de documentos BSON desde un archivo, una región de memoria o una función de retorno personalizada. El siguiente ejemplo lee documentos BSON de un archivo llamado example.bson e imprime la representación JSON de cada documento:
bson_reader_t *reader;bson_error_t error;const bson_t *b;char *str;
if (!((reader = bson_reader_new_from_file("example.json", &error)))) { fprintf(stderr, "Failed to open file: %s\n", error.message); return EXIT_FAILURE;}
while ((b = bson_reader_read(reader, NULL))) { str = bson_as_canonical_extended_json(b, NULL); fprintf(stdout, "%s\n", str); bson_free(str);}
bson_reader_destroy(reader);Leyendo JSON de un archivo
Puedes usar el tipo bson_json_reader_t para leer una secuencia de documentos JSON y convertirlos en documentos bson_t. El siguiente ejemplo lee documentos JSON de un archivo denominado example.json, convierte cada documento a formato BSON e imprime los documentos:
bson_json_reader_t *reader;int b;bson_error_t error;bson_t doc = BSON_INITIALIZER;
if (!((reader = bson_json_reader_new_from_file("example.json", &error)))) { fprintf(stderr, "Failed to open file: %s\n", error.message); return EXIT_FAILURE;}
while ((b = bson_json_reader_read(reader, &doc, &error))) { if (b < 0) { fprintf(stderr, "Failed to parse JSON: %s\n", error.message); abort(); }
if (fwrite(bson_get_data(&doc), 1, doc.len, stdout) != doc.len) { fprintf(stderr, "Failed to write BSON to stdout, exiting.\n"); exit(1); } bson_reinit(&doc);}
bson_json_reader_destroy(reader);bson_destroy(&doc);Advertencia
Validar la entrada no confiable antes de convertir JSON a BSON
Si convierte una string JSON a BSON y utiliza el BSON resultante en una query, una actualización o un comando, un atacante puede inyectar operadores o valores de campo inesperados que cambian el significado de la operación. Este riesgo es mayor cuando el JSON procede de un usuario, una solicitud de API o de otra fuente que no sea de confianza.
Para aprender más sobre la validación de la entrada antes de la conversión, consulte Validar la entrada no confiable antes de convertir JSON a BSON.
Optimización
Puedes liberar la memoria asignada para un documento BSON utilizando la función bson_destroy(), como se muestra en el siguiente ejemplo:
bson_t *doc = BCON_NEW("test", BCON_UTF8("example"));
// Operations using doc
bson_destroy(doc);Importante
Siempre llama a bson_destroy() en una instancia de bson_t cuando hayas terminado de usarla para evitar fugas de memoria en tu aplicación.
Documentación de la API
Para aprender más sobre cualquiera de los métodos o tipos analizados en esta guía, consulta la siguiente documentación de API: