使用参数标签 - Amazon Systems Manager
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅中国的 Amazon Web Services 服务入门

使用参数标签

参数标签是用户定义的别名,帮助管理参数的不同版本。修改参数时,Amazon Systems Manager 将自动保存新版本并将版本号增加 1。标签可帮助您在存在多个版本时记住参数版本的用途。

例如,假设您有一个名为 /MyApp/DB/ConnectionString 的参数。参数值在测试环境中是本地数据库中 MySQL 服务器的连接字符串。更新完应用程序之后,您希望此参数使用生产数据库的连接字符串。您更改了 /MyApp/DB/ConnectionString 的值。Systems Manager 将自动使用新连接字符串创建版本 2。为帮助您记住每个版本的用途,您为每个参数附加了一个标签。为版本 1 附加 Test 标签,并为版本 2 附加 Production 标签。

您可以将一个参数版本的标签移至另一个版本。例如,如果您使用新生产数据库的连接字符串为 /MyApp/DB/ConnectionString 参数创建版本 3,则可将 Production 标签从参数的版本 2 移至参数的版本 3。

参数标签是参数标记的轻量级替代。您的组织可能对必须应用于不同 Amazon 资源的标记具有严格的准则。相比之下,标签只是参数特定版本的文本关联。

与标签类似,您可使用标签查询参数。如果使用 GetParametersByPath API 操作查询参数设置,则可查看使用相同标签的所有特定参数版本的列表,如本部分后文所述。

标签要求和限制

参数标签具有以下要求和限制:

  • 一个参数版本最多可以具有 10 个标签。

  • 您无法将同一标签附加到同一参数的不同版本。例如,如果参数的版本 1 具有标签 Production,则无法将 Production 附加到版本 2。

  • 您可以将一个参数版本的标签移至另一个参数版本。

  • 创建参数时,无法创建标签。必须将标签附加到参数的特定版本。

  • 如果您不再想使用参数标签,可将其移至参数的其他版本或将其删除。

  • 标签最多可包含 100 个字符。

  • 标签可以包含字母(区分大小写)、数字、句点 (.)、连字符 (-) 或下划线 (_)。

  • 标签不能以数字、“aws”或“ssm”(不区分大小写)开头。如果标签不满足这些要求,则不会将标签附加到参数版本,并且系统将在 InvalidLabels 的列表中显示它。

使用参数标签(控制台)

此部分介绍了如何使用 Systems Manager 控制台执行以下任务。

创建参数标签(控制台)

以下过程介绍了如何使用 Systems Manager 控制台将标签附加到现有 参数的特定版本。创建参数时,无法附加标签。

要将标签附加到某个参数版本,请执行以下步骤:

  1. 访问 https://console.aws.amazon.com/systems-manager/,打开 Amazon Systems Manager 控制台。

  2. 在导航窗格中,选择 Parameter Store

    -或者-

    如果首先打开 Amazon Systems Manager 主页,选择菜单图标 ( ) 以打开导航窗格,然后选择 Parameter Store

  3. 选择参数的名称以打开该参数的详细信息页面。

  4. 选择 History 选项卡。

  5. 选择要为其附加标签的参数版本。

  6. 选择 Manage labels (管理标签)

  7. 选择 Add new label (添加新标签)

  8. 在文本框中,输入标签名称。要添加更多标签,请选择 Add new label (添加新标签)。您最多可以附加 10 个标签。

  9. 完成后,选择 Save changes (保存更改)

查看附加到参数的标签(控制台)

一个参数版本最多可以具有 10 个标签。以下过程介绍了如何使用 Systems Manager 控制台查看附加到参数版本的所有标签。

要查看附加到参数版本的标签,请执行以下步骤:

  1. 访问 https://console.aws.amazon.com/systems-manager/,打开 Amazon Systems Manager 控制台。

  2. 在导航窗格中,选择 Parameter Store

    -或者-

    如果首先打开 Amazon Systems Manager 主页,选择菜单图标 ( ) 以打开导航窗格,然后选择 Parameter Store

  3. 选择参数的名称以打开该参数的详细信息页面。

  4. 选择 History 选项卡。

  5. 找到要查看其所有附加标签的参数版本。Labels (标签) 列显示附加到参数版本的所有标签。

移动参数标签(控制台)

以下过程介绍了如何使用 Systems Manager 控制台将参数标签移至同一参数的其他版本。

要将标签移至其他参数版本,请执行以下步骤:

  1. 访问 https://console.aws.amazon.com/systems-manager/,打开 Amazon Systems Manager 控制台。

  2. 在导航窗格中,选择 Parameter Store

    -或者-

    如果首先打开 Amazon Systems Manager 主页,选择菜单图标 ( ) 以打开导航窗格,然后选择 Parameter Store

  3. 选择参数的名称以打开该参数的详细信息页面。

  4. 选择 History 选项卡。

  5. 选择要移动其标签的参数版本。

  6. 选择 Manage labels (管理标签)

  7. 选择 Add new label (添加新标签)

  8. 在文本框中,输入标签名称。

  9. 完成后,选择 Save changes (保存更改)

删除参数标签(控制台)

以下过程介绍了如何使用 Systems Manager 控制台删除一个或多个参数标签。

要删除参数的标签,请执行以下步骤:

  1. 访问 https://console.aws.amazon.com/systems-manager/,打开 Amazon Systems Manager 控制台。

  2. 在导航窗格中,选择 Parameter Store

    -或者-

    如果首先打开 Amazon Systems Manager 主页,选择菜单图标 ( ) 以打开导航窗格,然后选择 Parameter Store

  3. 选择参数的名称以打开该参数的详细信息页面。

  4. 选择 History 选项卡。

  5. 选择要删除其标签的参数版本。

  6. 选择 Manage labels (管理标签)

  7. 选择要删除的每个标签旁边的 Remove (删除)

  8. 完成后,选择 Save changes (保存更改)

  9. 确认您的更改是正确的,在文本框中输入 Confirm,然后选择 Confirm (确认)

使用参数标签 (Amazon CLI)

此部分介绍了如何使用 Amazon Command Line Interface (Amazon CLI) 执行以下任务。

创建新的参数标签 (Amazon CLI)

以下过程介绍如何使用 将标签附加到现有Amazon CLI 参数的特定版本。创建参数时,无法附加标签。

要创建参数标签,请执行以下步骤:

  1. 安装并配置 Amazon Command Line Interface (Amazon CLI)(如果尚未执行该操作)。

    有关信息,请参阅安装或升级 Amazon 命令行工具

  2. 运行以下命令以查看您有权为其附加标签的参数的列表。

    注意

    参数只在创建它的 Amazon Web Services 区域 可用。如果看不到要为其附加标签的参数,请验证您的区域。

    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"
        }
    }
    注意

    输出中的 Selector 是您在 Name 输入字段中指定的版本号或标签。

查看参数的标签 (Amazon 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"
            }
        ]
    }

查看已分配有标签的参数的列表 (Amazon 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"
        }
    ]
}

移动参数标签 (Amazon 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

删除参数标签 (Amazon CLI)

以下过程介绍了如何使用 Amazon 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 parameter name \ --parameter-version version \ --labels label 1,label 2,label 3

    系统将返回类似于以下内容的信息。

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