如第 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