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