如第 5.8.2.1 節「MySQL Shell API 函數的命令列整合」所述,MySQL Shell 中可用的大多數 API 都期望提供的引數具有特定的資料類型。命令列引數中的值可以使用 JSON 規格提供,並考慮以下事項。某些終端機會對資料進行自己的預處理,這可能會影響資料提供給 MySQL Shell 的方式,並且這會根據所使用的終端機而有所不同。例如:
如果找到空格,某些終端機會分割引數。
連續的空格可能會被分割邏輯忽略。
引號可能會被移除。
MySQL Shell 會將值解釋為它所運行的終端機所提供的,因此您必須以正確格式的方式將資料提供給終端機。例如:
- 重要
某些終端機需要逸出引號
-
字串引數在以下情況下應該要加上引號
它們包含空格
引數是清單參數,且包含逗號
它們包含逸出字元
API 參數可以接受不同的資料類型,而該值(根據 JSON 規格)可能是錯誤的資料類型。
使用 JSON 定義參數時,請為字串值和字串鍵加上引號。避免在引號項目之外使用空格。
以下範例說明一些參數的處理方式。
-
若要傳入多個參數,每個參數都是單一字串,則不需要加上引號
$ mysqlsh -- object function simple string
在這種情況下,MySQL Shell 會取得兩個引數 - 引數 1 為
simple
,而引數 2 為string
。 -
如果您希望將這兩個字串視為單一參數,則必須用引號括住它們,如下所示:
$ mysqlsh -- object function "simple string"
在這種情況下,MySQL Shell 會取得一個引數 - 引數 1 為
simple string
。 -
若要使用包含反斜線等字元的引數,則必須將字串加上引號。否則,該字元會被忽略。例如:
$ mysqlsh -- object function simple\tstring
在這種情況下,MySQL Shell 會取得一個引數 -
simpletstring
,反斜線字元 (\
) 已被忽略。若要確保將反斜線字元傳遞至 MySQL Shell,請用引號括住字串
$ mysqlsh -- object function "simple\tstring"
在這種情況下,MySQL Shell 會取得一個引數 -
simple\tstring
。
使用命令列整合時,定義 JSON 陣列有其自身的注意事項。例如,在 MySQL Shell 互動模式中,您將 JSON 陣列定義為
["simple",123]
若要在命令列整合中使用相同的陣列,則需要特定的引號。以下範例說明如何正確引用 JSON 陣列
-
嘗試以與互動模式相同的方式傳遞 JSON 陣列是行不通的
$ mysqlsh -- object function ["simple", 123]
在這種情況下,MySQL Shell 會取得兩個引數 - 引數 1 為
[simple,
,而引數 2 為123]
。 -
在陣列中使用空格雖然有幫助,但它仍然是無效的 JSON 陣列
$ mysqlsh -- object function ["simple",123]
在這種情況下,MySQL Shell 會取得一個引數 -
[simple,123]
。 -
若要建立有效的 JSON 陣列,請在已加上引號的字串元素內新增逸出的引號,例如:
$ mysqlsh -- object function ["\"simple\"",123]
在這種情況下,MySQL Shell 會取得一個引數 -
["simple",123]
。
若要使用包含 JSON 物件的 JSON 陣列,則需要以類似的方式加上引號。例如,在 MySQL Shell 互動模式中,您將包含 JSON 物件的 JSON 陣列定義為
{"firstName":"John","lastName":"Smith"}
以下範例說明如何在命令列整合中正確引用相同的陣列
-
嘗試以與互動模式相同的方式傳遞 JSON 陣列是行不通的
$ mysqlsh -- object function {"firstName":"John","lastName":"Smith"}
在這種情況下,MySQL Shell 會取得兩個引數 - 引數 1 為
firstName:John
,而引數 2 為lastName:Smith
。 -
對字串資料使用逸出的引號會導致
$ mysqlsh -- object function {"\"firstName\"":"\"John\"","\"lastName\"":"\"Smith\""}
在這種情況下,MySQL Shell 會取得兩個引數 - 引數 1 為
"firstName":"John"
,而引數 2 為"lastName":"Smith"
。 -
若要修正此問題,您需要另外引用整個 JSON 物件,才能取得
$ mysqlsh -- object function "{"\"firstName\"":"\"John\"","\"lastName\"":"\"Smith\""}"
在這種情況下,MySQL Shell 會取得一個引數 -
{"firstName":"John","lastName":"Smith"}
。
由於顯示的困難以及不同平台中的終端機行為可能不同,因此支援以下格式。
字串僅在以下情況下需要加上引號
該值包含空格
值本身包含逗號,且用於清單參數(以避免分割)
該值包含逸出字元
該值是數字、
null
、true
、false
,但它本應是字串。在這些情況下,該值應該加上引號,並包含內部逸出的引號。換句話說,如果字串值為 "true",則應該在 CLI 呼叫中定義為 ""true""。
除了 JSON 陣列之外,清單參數的引數還可以提供為
逗號分隔的值清單
個別的匿名引數
當正在處理清單參數時(依位置順序),所有剩餘的匿名引數都是清單的一部分。以下 MySQL Shell CLI 呼叫是相等的
-
使用逗號分隔的值清單
$ mysqlsh root@localhost -- util dump-schemas sakila,employees
-
使用連續的匿名引數
$ mysqlsh root@localhost -- util dump-schemas sakila employees
-
使用 JSON 陣列
$ mysqlsh root@localhost -- util dump-schemas ["\"sakila\"","\"employees\""]
字典是使用鍵值組建立的,字典引數中鍵的值也可以使用具名引數指定
--key=value
以下 MySQL Shell CLI 呼叫說明如何在 util.dumpInstance()
函數的 options 參數中定義 threads
和 osBucketName
鍵
$ mysqlsh -- util dump-instance my-dump --threads=8 --osBucketName=my-bucket
清單鍵
您可以使用以下方式在字典中定義清單鍵的值
將值定義為 JSON 陣列。
將值定義為逗號分隔的值清單。
重複定義鍵的值。
例如,在以下呼叫中,傳遞至 util.dumpInstance()
作業的 excludeSchemas
鍵的定義是相等的
-
使用逗號分隔的值清單
$ mysqlsh root@localhost -- util dump-instance --outputUrl="my-dump" --excludeSchemas=sakila,employees
-
使用 JSON 陣列
$ mysqlsh root@localhost -- util dump-instance --outputUrl="my-dump" --excludeSchemas=["\"sakila\"","\"employees\""]
-
定義
--excludeSchemas
鍵的多個值$ mysqlsh root@localhost -- util dump-instance --outputUrl="my-dump" --excludeSchemas=sakila --excludeSchemas=employees
字典鍵
支援巢狀字典,但具有以下限制
僅支援一層巢狀。
不支援內部預定義鍵的驗證。
不支援內部預期資料類型的驗證。
在巢狀字典中定義鍵的值的語法如下
--key=innerKey=value
例如,若要定義 decodeColumns
鍵並將其傳遞至 util.importTable()
作業
$ mysqlsh -- util import-table --decodeColumns=myColumn=1
如上一節所示,字典參數可透過使用 --key=value
語法的具名引數來支援。還有另一種情況是,引數必須指定為具名引數:在清單參數之後定義的參數。提供屬於清單參數的引數的最方便方法是使用匿名引數,例如在清單引數中的範例所示
$ mysqlsh root@localhost -- util dump-schemas sakila employees
但是,此範例缺少 outputUrl
參數的引數,該引數對於 util.dumpSchemas()
作業是必要的。因為所有剩餘的匿名引數都包含在 schemas 清單中作為項目,所以無法將 outputUrl
指定為匿名引數。例如,以下將不會起作用
$ mysqlsh root@localhost -- util dump-schemas sakila employees path/to/dump
在此呼叫中,路徑 path/to/dump
會被解釋為 schemas 清單中的另一個項目。因此,從命令列呼叫函數時,在清單參數之後定義的任何參數都必須指定為具名引數。例如:
$ mysqlsh root@localhost -- util dump-schemas sakila employees --outputUrl=path/to/dump