使用參數標籤 - AWS Systems Manager

使用參數標籤

參數標籤是使用者定義的別名,可協助您管理不同版本的參數。當您修改參數時,AWS Systems Manager 會自動儲存新版本,並將版本號碼增加 1。如果參數有多個版本,標籤可協助您記住參數版本的目的。

例如,假設您有一個名為 /MyApp/DB/ConnectionString 的參數。此參數的值是測試環境中本機資料庫的 MySQL 伺服器連線字串。在您完成更新應用程式之後,您需要參數以使用生產資料庫的連線字串。變更 /MyApp/DB/ConnectionString 的值。Systems Manager 會使用新的連線字串來自動建立版本 2。為了協助您記住每個版本的目的,您為每個參數加上標籤。您為版本 1 加上標籤 Test,為版本 2 加上標籤 Production

您可以將標籤從參數的一個版本移動至另一個版本。例如,如果您以新生產資料庫的連線字串建立 /MyApp/DB/ConnectionString 參數的版本 3,則可以將 Production 標籤從參數的版本 2 移動至參數的版本 3。

參數標籤是參數標記的輕量型替代方案。您的組織對於必須套用至不同 AWS 資源的標記可能有嚴格的指導方針。反之,標籤只是特定參數版本的文字關聯。

與標記類似,您可以使用標記查詢參數。如本節先前所述,如果您使用 GetParametersByPath API 操作來查詢您的參數集,您將可檢視所有使用相同標籤的特定參數版本的清單。

標籤要求和限制

參數標籤有下列要求與限制:

  • 參數的版本最多可以有 10 個標籤。

  • 您無法將相同的標籤附加至相同參數的不同版本。例如,如果參數的版本 1 有標籤 Production,那麼您無法將 Production 連接至版本 2。

  • 您可以將標籤從參數的一個版本移動至另一個版本。

  • 您無法在建立參數時建立標籤。您必須將標籤附加至指定的參數版本。

  • 如果您不再使用某個參數標籤,則可以將其移至不同的參數版本或將其刪除。

  • 標籤最多可使用 100 個字元。

  • 標籤可包含字母 (區分大小寫)、數字、句點 (.)、連字號 (-) 及底線 (_)。

  • 標籤的開頭不可以是數字、「aws」或「ssm」(不區分大小寫)。如果標籤未符合上述要求,該標籤將不會附加至參數版本,系統會將它顯示在 InvalidLabels 清單中。

使用參數標籤 (主控台)

本節說明如何使用 Systems Manager 主控台執行以下工作:

建立參數標籤 (主控台)

下列程序說明如何使用 Systems Manager 主控台,將標籤連接至現有參數的一個特定版本。您無法在建立參數時附加標籤。

將標籤連接至參數版本

  1. 開啟位於 AWS Systems Managerhttps://console.aws.amazon.com/systems-manager/ 的 主控台。https://console.aws.amazon.com/systems-manager/

  2. 在導覽窗格中,選擇 Parameter Store

    -或-

    如果 AWS Systems Manager 首頁先開啟,選擇選單圖示 ( ) 以開啟導覽窗格,然後選擇 Parameter Store

  3. 選擇參數的名稱以開啟該參數的詳細資訊頁面。

  4. 選擇 History (歷程記錄) 索引標籤。

  5. 選擇您要附加標籤的參數版本。

  6. 選擇 Manage labels (管理標籤)。

  7. 選擇 Add new label (新增新標籤)。

  8. 在文字方塊中輸入標籤名稱。若要新增更多標籤,請選擇 Add new label (新增新標籤)。您最多可以附加十個標籤。

  9. 完成時,請選擇 Save changes (儲存變更)

檢視已附加至參數的標籤 (主控台)

一個參數版本最多可以有 10 個標籤。下列程序說明如何使用 Systems Manager 主控台,檢視已附加至參數版本的所有標籤。

檢視已附加至參數版本的標籤

  1. 開啟位於 AWS Systems Managerhttps://console.aws.amazon.com/systems-manager/ 的 主控台。https://console.aws.amazon.com/systems-manager/

  2. 在導覽窗格中,選擇 Parameter Store

    -或-

    如果 AWS Systems Manager 首頁先開啟,選擇選單圖示 ( ) 以開啟導覽窗格,然後選擇 Parameter Store

  3. 選擇參數的名稱以開啟該參數的詳細資訊頁面。

  4. 選擇 History (歷程記錄) 索引標籤。

  5. 找到您要檢視所有已附加標籤的參數版本。Labels (標籤) 欄位會顯示所有已附加至該參數版本的標籤。

移動參數標籤 (主控台)

下列程序說明如何使用 Systems Manager 主控台,將參數標籤移動至相同參數的不同版本。

將標籤移動至不同的參數版本

  1. 開啟位於 AWS Systems Managerhttps://console.aws.amazon.com/systems-manager/ 的 主控台。https://console.aws.amazon.com/systems-manager/

  2. 在導覽窗格中,選擇 Parameter Store

    -或-

    如果 AWS Systems Manager 首頁先開啟,選擇選單圖示 ( ) 以開啟導覽窗格,然後選擇 Parameter Store

  3. 選擇參數的名稱以開啟該參數的詳細資訊頁面。

  4. 選擇 History (歷程記錄) 索引標籤。

  5. 選擇您要移動標籤的參數版本。

  6. 選擇 Manage labels (管理標籤)。

  7. 選擇 Add new label (新增新標籤)。

  8. 在文字方塊中輸入標籤名稱。

  9. 完成時,請選擇 Save changes (儲存變更)

刪除參數標籤 (主控台)

下列程序說明如何使用 Systems Manager 主控台來刪除一個或多個參數標籤。

若要從參數中刪除標籤

  1. 開啟位於 AWS Systems Managerhttps://console.aws.amazon.com/systems-manager/ 的 主控台。https://console.aws.amazon.com/systems-manager/

  2. 在導覽窗格中,選擇 Parameter Store

    -或-

    如果 AWS Systems Manager 首頁先開啟,選擇選單圖示 ( ) 以開啟導覽窗格,然後選擇 Parameter Store

  3. 選擇參數的名稱以開啟該參數的詳細資訊頁面。

  4. 選擇 History (歷程記錄) 索引標籤。

  5. 選擇您要刪除標籤的參數版本。

  6. 選擇 Manage labels (管理標籤)。

  7. 在您要刪除的每個標籤旁選擇 Remove (移除)。

  8. 完成時,請選擇 Save changes (儲存變更)

  9. 確認您的變更正確,在文字方塊中輸入 Confirm,然後選擇 Confirm (確認)。

使用參數標籤 (AWS CLI)

本節說明如何使用 AWS Command Line Interface (AWS CLI) 執行以下工作。

建立新的參數標籤 (AWS CLI)

下列程序說明如何使用 AWS CLI 主控台,將標籤連接至現有參數的一個特定版本。您無法在建立參數時附加標籤。

建立參數標籤

  1. 如果您尚未安裝並設定 AWS Command Line Interface (AWS CLI),請進行相應的作業。

    如需相關資訊,請參閱安裝或升級 AWS 命令列工具

  2. 執行以下命令,以檢視您具有連接標籤許可的參數清單。

    注意

    參數只能在建立該參數的 AWS 區域 中使用。如果沒有看到您要附加標籤的參數,請確認您的區域。

    aws ssm describe-parameters

    記下您要附加標籤的參數名稱。

  3. 執行以下命令,以檢視參數的所有版本。

    aws ssm get-parameter-history --name "parameter-name"

    記下您要附加標籤的參數版本。

  4. 執行以下命令,依照版本號碼擷取有關參數的資訊。

    aws ssm get-parameters --names "parameter-name:version-number"

    請見此處範例。

    aws ssm get-parameters --names "/Production/SQLConnectionString:3"
  5. 執行以下命令其中之一,將標籤附加至參數版本。如果您要連接多個標籤,以空格分隔標籤名稱。

    將標籤附加至參數的最新版本

    aws ssm label-parameter-version --name parameter-name --labels label-name

    將標籤附加至指定的參數版本

    aws ssm label-parameter-version --name parameter-name --parameter-version version-number --labels label-name

    請見下方範例。

    aws ssm label-parameter-version --name /config/endpoint --labels production east-region finance
    aws ssm label-parameter-version --name /config/endpoint --parameter-version 3 --labels MySQL-test
    注意

    如果輸出顯示您在 InvalidLabels 清單中建立的標籤,表示該標籤不符合本主題中前述的要求。請檢閱需求,然後再試一次。如果 InvalidLabels 清單是空的,表示您的標籤已成功附加至參數的版本。

  6. 您可以使用版本號碼或標籤名稱檢視參數的詳細資訊。執行以下命令,並指定您在上一步驟建立的標籤。

    aws ssm get-parameter --name parameter-name:label-name --with-decryption

    該命令會傳回相關資訊,如以下所示。

    {
        "Parameter": {
            "Version": version-number, 
            "Type": "parameter-type", 
            "Name": "parameter-name", 
            "Value": "parameter-value", 
            "Selector": ":label-name"
        }
    }
    注意

    輸出中選擇器是您在 Name 輸入欄位中指定的版本號碼或標籤。

檢視參數的標籤 (AWS CLI)

您可以使用 GetParameterHistory API 操作來檢視完整的歷程記錄,以及已連接至指定參數的所有標籤。或者,您可以使用 GetParametersByPath API 操作來檢視已被指派特定標籤的所有參數清單。

使用 GetParameterHistory API 操作檢視參數的標籤

  1. 執行以下命令,以檢視您可以檢視標籤的參數清單。

    注意

    參數只能在建立該參數的區域中使用。如果沒有看到您要移動標籤的參數,請確認您的區域。

    aws ssm describe-parameters

    記下您要檢視其標籤的參數名稱。

  2. 執行以下命令,以檢視參數的所有版本。

    aws ssm get-parameter-history --name parameter-name --with-decryption

    系統會傳回相關資訊,如下所示。

    {
        "Parameters": [
            {
                "Name": "/Config/endpoint", 
                "LastModifiedDate": 1528932105.382, 
                "Labels": [
                    "Deprecated"
                ], 
                "Value": "MyTestService-June-Release.example.com", 
                "Version": 1, 
                "LastModifiedUser": "arn:aws:iam::123456789012:user/test", 
                "Type": "String"
            }, 
            {
                "Name": "/Config/endpoint", 
                "LastModifiedDate": 1528932111.222, 
                "Labels": [
                    "Current"
                ], 
                "Value": "MyTestService-July-Release.example.com", 
                "Version": 2, 
                "LastModifiedUser": "arn:aws:iam::123456789012:user/test", 
                "Type": "String"
            }
        ]
    }

檢視已指派標籤的參數清單 (AWS CLI)

您可以使用 GetParametersByPath API 操作來檢視某路徑中已被指派特定標籤的所有參數的清單。

執行以下命令,以檢視在某路徑中已被指派特定標籤的參數清單。

aws ssm get-parameters-by-path --path parameter-path --parameter-filters Key=Label,Values=label-name,Option=Equals --max-results a-number --with-decryption --recursive

系統會傳回相關資訊,如下所示。在此範例中,使用者在 /Config 路徑之下進行搜尋。

{
    "Parameters": [
        {
            "Version": 3, 
            "Type": "SecureString", 
            "Name": "/Config/DBpwd", 
            "Value": "MyS@perGr&pass33"
        }, 
        {
            "Version": 2, 
            "Type": "String", 
            "Name": "/Config/DBusername", 
            "Value": "TestUserDB"
        }, 
        {
            "Version": 2, 
            "Type": "String", 
            "Name": "/Config/endpoint", 
            "Value": "MyTestService-July-Release.example.com"
        }
    ]
}

移動參數標籤 (AWS CLI)

下列程序說明如何將參數標籤移動至相同參數的不同版本。

若要移動參數標籤

  1. 執行以下命令,以檢視參數的所有版本。

    aws ssm get-parameter-history --name "parameter-name"

    記下您要在其中移動標籤的參數版本。

  2. 執行以下命令,將現有標籤指派到參數的不同版本。

    aws ssm label-parameter-version --name parameter-name --parameter-version version-number --labels name-of-existing-label
    注意

    如果您要將現有標籤移動至參數的最新版本,請從命令中將 --parameter-version 移除。

刪除參數標籤 (AWS CLI)

以下程序說明如何使用 AWS CLI 來刪除參數標籤。

刪除參數標籤

  1. 執行以下命令,以檢視參數的所有版本。

    aws ssm get-parameter-history --name "parameter-name"

    系統會傳回相關資訊,如下所示。

    {
        "Parameters": [
            {
                "Name": "foo",
                "DataType": "text",
                "LastModifiedDate": 1607380761.11,
                "Labels": [
                    "l3",
                    "l2"
                ],
                "Value": "test",
                "Version": 1,
                "LastModifiedUser": "arn:aws:iam::123456789012:user/test",
                "Policies": [],
                "Tier": "Standard",
                "Type": "String"
            },
            {
                "Name": "foo",
                "DataType": "text",
                "LastModifiedDate": 1607380763.11,
                "Labels": [
                    "l1"
                ],
                "Value": "test",
                "Version": 2,
                "LastModifiedUser": "arn:aws:iam::123456789012:user/test",
                "Policies": [],
                "Tier": "Standard",
                "Type": "String"
            }
        ]
    }

    記下您要刪除標籤的參數版本。

  2. 執行以下命令,以刪除您從該參數中選擇的標籤。

    aws ssm unlabel-parameter-version --name parameterName --parameter-version version --labels label1,label2,label3

    系統會傳回相關資訊,如下所示。

    {
        "InvalidLabels": ["invalid"], 
        "DeletedLabels" : ["Prod"]
     }