Utilisation de la validation du schéma JSON - Amazon DocumentDB
Création et utilisation de la validation du schéma JSONMots clés pris en chargebypassDocumentValidationLimites

Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.

Utilisation de la validation du schéma JSON

À l'aide de l'opérateur de requête d'$jsonSchemaévaluation, vous pouvez valider les documents insérés dans vos collections.

Création et utilisation de la validation du schéma JSON

Création d'une collection avec validation de schéma

Vous pouvez créer une collection avec des règles de createCollection fonctionnement et de validation. Ces règles de validation sont appliquées lors des insertions ou des mises à jour de documents Amazon DocumentDB. L'exemple de code suivant montre les règles de validation pour un ensemble d'employés :

db.createCollection("employees", {
   "validator": {
      "$jsonSchema": {
         "bsonType": "object",
         "title": "employee validation",
         "required": [ "name", "employeeId"],
         "properties": {
            "name": {
                  "bsonType": "object",
                  "properties": {
                     "firstName": {
                        "bsonType": ["string"]
                     },
                     "lastName": {
                        "bsonType": ["string"]
                     }
                  },
                  "additionalProperties" : false 
            },
            "employeeId": {
               "bsonType": "string",
               "description": "Unique Identifier for employee"
            },
             "salary": {
               "bsonType": "double"
            },
            "age": {
               "bsonType": "number"
            }
         },
         "additionalProperties" : true 
      }
   },
   "validationLevel": "strict", "validationAction": "error"
} )

Insérer un document valide

L'exemple suivant insère des documents conformes aux règles de validation du schéma ci-dessus :

db.employees.insert({"name" : { "firstName" : "Carol" , "lastName" : "Smith"}, "employeeId": "c720a" , "salary": 1000.0 })
db.employees.insert({ "name" : { "firstName" : "William", "lastName" : "Taylor" }, "employeeId" : "c721a", "age" : 24})

Insérer un document non valide

L'exemple suivant insère des documents qui ne sont pas conformes aux règles de validation du schéma ci-dessus. Dans cet exemple, la valeur EmployeeID n'est pas une chaîne :

db.employees.insert({
    "name" : { "firstName" : "Carol" , "lastName" : "Smith"}, 
    "employeeId": 720 , 
    "salary": 1000.0 
})

Cet exemple montre une syntaxe incorrecte dans le document.

Modifier une collection

La collMod commande est utilisée pour ajouter ou modifier les règles de validation d'une collection existante. L'exemple suivant ajoute un champ de salaire à la liste des champs obligatoires :

db.runCommand({"collMod" : "employees", 
   "validator": {
      "$jsonSchema": {
         "bsonType": "object",
         "title": "employee validation",
         "required": [ "name", "employeeId", "salary"],
         "properties": {
            "name": {
                  "bsonType": "object",
                  "properties": {
                     "firstName": {
                        "bsonType": ["string"]
                     },
                     "lastName": {
                        "bsonType": ["string"]
                     }
                  },
                  "additionalProperties" : false 
            },
            "employeeId": {
               "bsonType": "string",
               "description": "Unique Identifier for employee"
            },
             "salary": {
               "bsonType": "double"
            },
            "age": {
               "bsonType": "number"
            }
         },
         "additionalProperties" : true 
      }
   }
} )

Adressage des documents ajoutés avant la modification des règles de validation

Pour traiter les documents qui ont été ajoutés à votre collection avant que les règles de validation ne soient modifiées, utilisez les validationLevel modificateurs suivants :

  • strict : applique les règles de validation à toutes les insertions et mises à jour.

  • modéré : applique les règles de validation aux documents valides existants. Lors des mises à jour, les documents non valides existants ne sont pas vérifiés.

Dans l'exemple suivant, après avoir mis à jour les règles de validation sur la collection nommée « employés », le champ salaire est obligatoire. La mise à jour du document suivant échouera :

db.runCommand({ 
    update: "employees", 
    updates: [{ 
        q: { "employeeId": "c721a" }, 
        u: { age: 25 , salary : 1000}, 
        upsert: true }] 
})

Amazon DocumentDB renvoie le résultat suivant :

{
"n" : 0,
    "nModified" : 0,
    "writeErrors" : [
        {
"index" : 0,
            "code" : 121,
            "errmsg" : "Document failed validation"
        }
    ],
    "ok" : 1,
    "operationTime" : Timestamp(1234567890, 1)
}

La mise à jour du niveau de validation moderate permettra au document ci-dessus d'être correctement mis à jour :

db.runCommand({
    "collMod" : "employees", 
    validationLevel : "moderate"
})

db.runCommand({ 
    update: "employees", 
    updates: [{ 
        q: { "employeeId": "c721a" }, 
        u: { age: 25 , salary : 1000}, 
        upsert: true }]
})

Amazon DocumentDB renvoie le résultat suivant :

{
"n" : 1,
    "nModified" : 1,
    "ok" : 1,
    "operationTime" : Timestamp(1234567890, 1)
}

Récupération de documents avec le $JSONSchema

L'$jsonSchemaopérateur peut être utilisé comme filtre pour interroger les documents qui correspondent au schéma JSON. Il s'agit d'un opérateur de niveau supérieur qui peut être présent dans les documents filtrés sous forme de champ de niveau supérieur ou utilisé avec des opérateurs de requête tels que $and$or, et$nor. Les exemples suivants montrent l'utilisation de $JSONSchema en tant que filtre individuel et avec d'autres opérateurs de filtre :

Document inséré dans une collection « d'employés » :

{ "name" : { "firstName" : "Carol", "lastName" : "Smith" }, "employeeId" : "c720a", "salary" : 1000 }
{ "name" : { "firstName" : "Emily", "lastName" : "Brown" }, "employeeId" : "c720b", "age" : 25, "salary" : 1050.2 }
{ "name" : { "firstName" : "William", "lastName" : "Taylor" }, "employeeId" : "c721a", "age" : 24, "salary" : 1400.5 }
{ "name" : { "firstName" : "Jane", "lastName" : "Doe" }, "employeeId" : "c721a", "salary" : 1300 }

Collection filtrée avec l'$jsonSchemaopérateur uniquement :

db.employees.find({ 
       $jsonSchema: { required: ["age"] } })

Amazon DocumentDB renvoie le résultat suivant :

{ "_id" : ObjectId("64e5f91c6218c620cf0e8f8b"), "name" : { "firstName" : "Emily", "lastName" : "Brown" }, "employeeId" : "c720b", "age" : 25, "salary" : 1050.2 }
{ "_id" : ObjectId("64e5f94e6218c620cf0e8f8c"), "name" : { "firstName" : "William", "lastName" : "Taylor" }, "employeeId" : "c721a", "age" : 24, "salary" : 1400.5 }

Collection filtrée avec l'$jsonSchemaopérateur et un autre opérateur :

db.employees.find({ 
       $or: [{ $jsonSchema: { required: ["age", "name"]}}, 
            { salary: { $lte:1000}}]});

Amazon DocumentDB renvoie le résultat suivant :

{ "_id" : ObjectId("64e5f8886218c620cf0e8f8a"), "name" : { "firstName" : "Carol", "lastName" : "Smith" }, "employeeId" : "c720a", "salary" : 1000 }
{ "_id" : ObjectId("64e5f91c6218c620cf0e8f8b"), "name" : { "firstName" : "Emily", "lastName" : "Brown" }, "employeeId" : "c720b", "age" : 25, "salary" : 1050.2 }
{ "_id" : ObjectId("64e5f94e6218c620cf0e8f8c"), "name" : { "firstName" : "William", "lastName" : "Taylor" }, "employeeId" : "c721a", "age" : 24, "salary" : 1400.5 }

Collection filtrée avec l'$jsonSchemaopérateur et avec $match dans le filtre agrégé :

db.employees.aggregate(
    [{ $match: { 
        $jsonSchema: { 
            required: ["name", "employeeId"],  
            properties: {"salary" :{"bsonType": "double"}}
        }
       }
    }]
)

Amazon DocumentDB renvoie le résultat suivant :

{ 
"_id" : ObjectId("64e5f8886218c620cf0e8f8a"),
 "name" : { "firstName" : "Carol", "lastName" : "Smith" },
"employeeId" : "c720a",
"salary" : 1000 
}
{
"_id" : ObjectId("64e5f91c6218c620cf0e8f8b"),
"name" : { "firstName" : "Emily", "lastName" : "Brown" },
"employeeId" : "c720b",
"age" : 25,
"salary" : 1050.2
}
{
"_id" : ObjectId("64e5f94e6218c620cf0e8f8c"),
"name" : { "firstName" : "William", "lastName" : "Taylor" },
"employeeId" : "c721a",
"age" : 24,
"salary" : 1400.5
}
{
"_id" : ObjectId("64e5f9786218c620cf0e8f8d"),
"name" : { "firstName" : "Jane", "lastName" : "Doe" },
"employeeId" : "c721a",
"salary" : 1300
}

Afficher les règles de validation existantes

Pour consulter les règles de validation existantes sur une collection, utilisez :

db.runCommand({
    listCollections: 1, 
    filter: { name: 'employees' }
})

Amazon DocumentDB renvoie le résultat suivant :

{
    "waitedMS" : NumberLong(0),
    "cursor" : {
        "firstBatch" : [
            {
                "name" : "employees",
                "type" : "collection",
                "options" : {
                    "autoIndexId" : true,
                    "capped" : false,
                    "validator" : {
                        "$jsonSchema" : {
                            "bsonType" : "object",
                            "title" : "employee validation",
                            "required" : [
                                "name",
                                "employeeId",
                                "salary"
                            ],
                            "properties" : {
                                "name" : {
                                    "bsonType" : "object",
                                    "properties" : {
                                        "firstName" : {
                                            "bsonType" : [
                                                "string"
                                            ]
                                        },
                                        "lastName" : {
                                            "bsonType" : [
                                                "string"
                                            ]
                                        }
                                    },
                                    "additionalProperties" : false
                                },
                                "employeeId" : {
                                    "bsonType" : "string",
                                    "description" : "Unique Identifier for employee"
                                },
                                "salary" : {
                                    "bsonType" : "double"
                                },
                                "age" : {
                                    "bsonType" : "number"
                                }
                            },
                            "additionalProperties" : true
                        }
                    },
                    "validationLevel" : "moderate",
                    "validationAction" : "error"
                },
                "info" : {
                    "readOnly" : false
                },
                "idIndex" : {
                    "v" : 2,
                    "key" : {
                        "_id" : 1
                    },
                    "name" : "_id_",
                    "ns" : "test.employees"
                }
            }
        ],
        "id" : NumberLong(0),
        "ns" : "test.$cmd.listCollections"
    },
    "ok" : 1,
    "operationTime" : Timestamp(1692788937, 1)
}

Amazon DocumentDB conserve également les règles de validation lors de la phase d'$outagrégation.

Mots clés pris en charge

Les champs suivants sont pris en charge dans les collMod commandes create et :

  • Validator— Supporte $jsonSchem l'opérateur a.

  • ValidationLevel— Supports off et moderate valeurs. strict

  • ValidationAction— Supporte la error valeur.

L'opérateur $JSONSchema prend en charge les mots clés suivants :

  • additionalItems

  • additionalProperties

  • allOf

  • anyOf

  • bsonType

  • dependencies

  • description

  • enum

  • exclusiveMaximum

  • exclusiveMinimum

  • items

  • maximum

  • minimum

  • maxItems

  • minItems

  • maxLength

  • minLength

  • maxProperties

  • minProperties

  • multipleOf

  • not

  • oneOf

  • pattern

  • patternProperties

  • properties

  • required

  • title

  • type

  • uniqueItems

bypassDocumentValidation

Amazon DocumentDB prend en charge bypassDocumentValidation les commandes et méthodes suivantes :

  • insert

  • update

  • findAndModify

  • $outétape dans le aggregate commandement et dans la db.collection.aggregate() méthode

Amazon DocumentDB ne prend pas en charge les commandes suivantes pour : bypassDocumentValidation

  • $mergedans la aggregate commande et dans la db.collection.aggregate() méthode

  • mapReducecommande et db.collection.mapReduce() méthode

  • applyOps commande

Limites

Les limites suivantes s'appliquent à la $jsonSchema validation :

  • Amazon DocumentDB renvoie l'erreur « Échec de la validation du document » lorsqu'une opération ne respecte pas la règle de validation.

  • Les clusters élastiques Amazon DocumentDB ne sont pas pris en charge. $jsonSchema