MySQL :: X DevAPI 使用者指南 :: 4.6 JSON 綱要驗證

4.6 JSON 綱要驗證

可以設定集合，以根據 JSON 綱要驗證文件。這讓您能夠要求文件在插入或更新至集合之前必須具有特定結構。您可以使用 https://json-schema.dev.org.tw 中說明的 JSON 綱要。綱要驗證由伺服器執行，如果集合中的文件未根據指定的 JSON 綱要驗證，則伺服器會傳回錯誤訊息。如需 MySQL 中 JSON 綱要驗證的詳細資訊，請參閱JSON 綱要驗證函式。本節說明如何設定集合，以根據 JSON 綱要驗證文件。

注意

Connector/J 實作 JSON 綱要驗證的方式與本節所述模型非常不同。詳細資訊請參閱綱要驗證中的MySQL Connector/J 開發人員指南。

若要啟用或修改 JSON 綱要驗證，請提供集合一個如下的 validation JSON 物件

{
    validation: {
      level: "off|strict",
      schema: "json-schema"
    }
}

在此，validation 是一個 JSON 物件，其中包含您可以用來設定 JSON 綱要驗證的索引鍵。第一個索引鍵是 level，它可以採用 strict 或 off 值。第二個索引鍵 schema 是一個 JSON 綱要，如 https://json-schema.dev.org.tw 中所定義。如果 level 索引鍵設定為 strict，則在將文件新增至集合時，或如果文件已在集合中，則當文件透過某些作業更新時，系統會根據 json-schema 驗證文件。如果文件未驗證，伺服器會產生錯誤，且作業會失敗。如果 level 索引鍵設定為 off，則不會根據 json-schema 驗證文件。

建立已驗證的集合

若要在建立新集合時啟用 JSON 綱要驗證，請提供上述的 validation JSON 物件。例如，若要建立一個集合來保存經度和緯度值，並要求將這些值驗證為數字

MySQL Shell JavaScript 程式碼

var coll = schema.createCollection("longlang", {
  validation: {
    level: "strict",
    schema:   {
      "id": "https://json-schema.dev.org.tw/geo",
      "$schema": "https://json-schema.dev.org.tw/draft-06/schema#",
      "description": "A geographical coordinate",
      "type": "object",
      "properties": {
        "latitude": {
          "type": "number"
        },
        "longitude": {
          "type": "number"
        }
      },
      "required": ["latitude", "longitude"]
    }
  }
})

MySQL Shell Python 程式碼

coll = schema.create_collection("longlang", validation={
    "level": "strict",
    "schema":   {
        "id": "https://json-schema.dev.org.tw/geo",
        "$schema": "https://json-schema.dev.org.tw/draft-06/schema#",
        "description": "A geographical coordinate",
        "type": "object",
        "properties": {
            "latitude": {
                "type": "number"
            },
            "longitude": {
                "type": "number"
            }
        },
        "required": ["latitude", "longitude"]
    }
})

Node.js JavaScript 程式碼

var coll = schema.createCollection("longlang", {
  validation: {
    level: "strict",
    schema:   {
      "id": "https://json-schema.dev.org.tw/geo",
      "$schema": "https://json-schema.dev.org.tw/draft-06/schema#",
      "description": "A geographical coordinate",
      "type": "object",
      "properties": {
        "latitude": {
          "type": "number"
        },
        "longitude": {
          "type": "number"
        }
      },
      "required": ["latitude", "longitude"]
    }
  }
})

C# 程式碼

var collOptions = CreateCollectionOptions() {
  reuseExistingObject = false,
  validation = Validation() {
    level = ValidationLevel.Strict,
    schema = "{\"id\": \"https://json-schema.dev.org.tw/geo\","
             + "\"$schema\": \"https://json-schema.dev.org.tw/draft-06/schema#\","
             + "       \"description\": \"A geographical coordinate\","
             + "       \"type\": \"object\","
             + "       \"properties\": {"
             + "          \"latitude\": {"
             + "             \"type\": \"number\""
             + "          },"
             + "          \"longitude\": {"
             + "             \"type\": \"number\""
             + "          }"
             + "       },"
             + "       \"required\": [\"latitude\", \"longitude\"]"
             + "  }"
    }
};

var coll = schema.CreateCollection("longlang", collOptions);

Python 程式碼

coll = schema.create_collection("longlang", validation={
    "level": "strict",
    "schema":   {
        "id": "https://json-schema.dev.org.tw/geo",
        "$schema": "https://json-schema.dev.org.tw/draft-06/schema#",
        "description": "A geographical coordinate",
        "type": "object",
        "properties": {
            "latitude": {
                "type": "number"
            },
            "longitude": {
                "type": "number"
            }
        },
        "required": ["latitude", "longitude"]
    }
})

修改集合驗證

您可以修改集合，以控制文件的 JSON 綱要驗證。例如，您可以啟用或停用驗證，或變更要驗證文件的 JSON 綱要。

若要修改集合的 JSON 綱要驗證，請在呼叫 Collection.modify() 方法時提供 validation JSON 物件。例如，若要修改集合以停用 JSON 綱要驗證，validation 物件會是

{ 
   validation: {
       "level": "off"
   }
}

修改 JSON 綱要驗證時，您可以單獨提供 level 選項，僅變更綱要驗證的層級。例如，傳遞上面顯示的 JSON 物件以停用 JSON 綱要驗證。這不會變更先前指定的 JSON 綱要，也不會從集合中移除 JSON 綱要。或者，您可以僅傳遞新的 JSON 綱要物件來僅修改綱要。