5.8.2.2 定義引數

第 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"}

由於顯示的困難以及不同平台中的終端機行為可能不同,因此支援以下格式。

字串引數

字串在以下情況下需要加上引號

  • 該值包含空格

  • 值本身包含逗號,且用於清單參數(以避免分割)

  • 該值包含逸出字元

  • 該值是數字、nulltruefalse,但它本應是字串。在這些情況下,該值應該加上引號,並包含內部逸出的引號。換句話說,如果字串值為 "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 參數中定義 threadsosBucketName

$ 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