lib/aws-sdk-secretsmanager/client.rb in aws-sdk-secretsmanager-1.0.0 vs lib/aws-sdk-secretsmanager/client.rb in aws-sdk-secretsmanager-1.1.0

- old
+ new

@@ -214,10 +214,27 @@ # # * {Types::CancelRotateSecretResponse#arn #arn} => String # * {Types::CancelRotateSecretResponse#name #name} => String # * {Types::CancelRotateSecretResponse#version_id #version_id} => String # + # + # @example Example: To cancel scheduled rotation for a secret + # + # # The following example shows how to cancel rotation for a secret. The operation sets the RotationEnabled field to false + # # and cancels all scheduled rotations. To resume scheduled rotations, you must re-enable rotation by calling the + # # rotate-secret operation. + # + # resp = client.cancel_rotate_secret({ + # secret_id: "MyTestDatabaseSecret", + # }) + # + # resp.to_h outputs the following: + # { + # arn: "arn:aws:secretsmanager:us-west-2:123456789012:secret:MyTestDatabaseSecret-a1b2c3", + # name: "Name", + # } + # # @example Request syntax with placeholder values # # resp = client.cancel_rotate_secret({ # secret_id: "SecretIdType", # required # }) @@ -235,13 +252,13 @@ def cancel_rotate_secret(params = {}, options = {}) req = build_request(:cancel_rotate_secret, params) req.send_request(options) end - # Creates a new secret. A secret in AWS Secrets Manager consists of both - # the protected secret data and the important information needed to - # manage the secret. + # Creates a new secret. A secret in Secrets Manager consists of both the + # protected secret data and the important information needed to manage + # the secret. # # Secrets Manager stores the encrypted secret data in one of a # collection of "versions" associated with the secret. Each version # contains a copy of the encrypted secret data. Each version is # associated with one or more "staging labels" that identify where the @@ -255,21 +272,21 @@ # parameter. If you include `SecretString` or `SecretBinary` then # Secrets Manager also creates an initial secret version and, if you # don't supply a staging label, automatically maps the new version's # ID to the staging label `AWSCURRENT`. # - # * If you call an operation that needs to encrypt or decrypt the + # <note markdown="1"> * If you call an operation that needs to encrypt or decrypt the # `SecretString` and `SecretBinary` for a secret in the same account # as the calling user and that secret doesn't specify a KMS - # encryption key, AWS Secrets Manager uses the account's default AWS + # encryption key, Secrets Manager uses the account's default AWS # managed customer master key (CMK) with the alias # `aws/secretsmanager`. If this key doesn't already exist in your - # account then AWS Secrets Manager creates it for you automatically. - # All users in the same AWS account automatically have access to use - # the default CMK. Note that if an AWS Secrets Manager API call - # results in AWS having to create the account's AWS-managed CMK, it - # can result in a one-time significant delay in returning the result. + # account then Secrets Manager creates it for you automatically. All + # users in the same AWS account automatically have access to use the + # default CMK. Note that if an Secrets Manager API call results in AWS + # having to create the account's AWS-managed CMK, it can result in a + # one-time significant delay in returning the result. # # * If the secret is in a different AWS account from the credentials # calling an API that requires encryption or decryption of the secret # value then you must create and use a custom KMS CMK because you # can't access the default CMK for the account using credentials from @@ -278,10 +295,14 @@ # `KMSKeyId`. If you call an API that must encrypt or decrypt # `SecretString` or `SecretBinary` using credentials from a different # account then the KMS key policy must grant cross-account access to # that other account's user or role. # + # </note> + # + # + # # **Minimum permissions** # # To run this command, you must have the following permissions: # # * secretsmanager:CreateSecret @@ -312,24 +333,22 @@ # * To retrieve the list of secret versions associated with the current # secret, use DescribeSecret and examine the `SecretVersionsToStages` # response value. # # @option params [required, String] :name - # Specifies the friendly name of the new secret. The secret name can - # consist of uppercase letters, lowercase letters, digits, and any of - # the following characters: /\_+=.@-    Spaces are not permitted. + # Specifies the friendly name of the new secret. # # @option params [String] :client_request_token # (Optional) If you include `SecretString` or `SecretBinary`, then an # initial version is created as part of the secret, and this parameter # specifies a unique identifier for the new version. # # <note markdown="1"> If you use the AWS CLI or one of the AWS SDK to call this operation, # then you can leave this parameter empty. The CLI or SDK generates a # random UUID for you and includes as the value for this parameter in # the request. If you don't use the SDK and instead generate a raw HTTP - # request to the AWS Secrets Manager service endpoint, then you must + # request to the Secrets Manager service endpoint, then you must # generate a `ClientRequestToken` yourself for the new version and # include that value in the request. # # </note> # @@ -371,12 +390,12 @@ # values in the versions stored in this secret. # # If you don't specify this value, then Secrets Manager defaults to # using the AWS account's default CMK (the one named # `aws/secretsmanager`). If a KMS CMK with that name doesn't yet exist, - # then AWS Secrets Manager creates it for you automatically the first - # time it needs to encrypt a version's `SecretString` or `SecretBinary` + # then Secrets Manager creates it for you automatically the first time + # it needs to encrypt a version's `SecretString` or `SecretBinary` # fields. # # You can use the account's default CMK to encrypt and decrypt only if # you call this operation using credentials from the same account that # owns the secret. If the secret is in a different account, then you @@ -435,12 +454,12 @@ # (Optional) Specifies a list of user-defined tags that are attached to # the secret. Each tag is a "Key" and "Value" pair of strings. This # operation only appends tags to the existing list of tags. To remove # tags, you must use UntagResource. # - # * AWS Secrets Manager tag key names are case sensitive. A tag with the - # key "ABC" is a different tag from one with key "abc". + # * Secrets Manager tag key names are case sensitive. A tag with the key + # "ABC" is a different tag from one with key "abc". # # * If you check tags in IAM policy `Condition` elements as part of your # security strategy, then adding or removing a tag can change # permissions. If the successful completion of this operation would # result in you losing your permissions for this secret, then this @@ -486,10 +505,30 @@ # # * {Types::CreateSecretResponse#arn #arn} => String # * {Types::CreateSecretResponse#name #name} => String # * {Types::CreateSecretResponse#version_id #version_id} => String # + # + # @example Example: To create a basic secret + # + # # The following example shows how to create a secret. The credentials stored in the encrypted secret value are retrieved + # # from a file on disk named mycreds.json. + # + # resp = client.create_secret({ + # client_request_token: "EXAMPLE1-90ab-cdef-fedc-ba987SECRET1", + # description: "My test database secret created with the CLI", + # name: "MyTestDatabaseSecret", + # secret_string: "{\"username\":\"david\",\"password\":\"BnQw!XDWgaEeT9XGTT29\"}", + # }) + # + # resp.to_h outputs the following: + # { + # arn: "arn:aws:secretsmanager:us-west-2:123456789012:secret:MyTestDatabaseSecret-a1b2c3", + # name: "MyTestDatabaseSecret", + # version_id: "EXAMPLE1-90ab-cdef-fedc-ba987SECRET1", + # } + # # @example Request syntax with placeholder values # # resp = client.create_secret({ # name: "NameType", # required # client_request_token: "ClientRequestTokenType", @@ -520,28 +559,28 @@ req.send_request(options) end # Deletes an entire secret and all of its versions. You can optionally # include a recovery window during which you can restore the secret. If - # you don't provide a recovery window value, the operation defaults to + # you don't specify a recovery window value, the operation defaults to # 30 days. Secrets Manager attaches a `DeletionDate` stamp to the secret # that specifies the end of the recovery window. At the end of the # recovery window, Secrets Manager deletes the secret permanently. # - # At any time before recovery period ends, you can use RestoreSecret to + # At any time before recovery window ends, you can use RestoreSecret to # remove the `DeletionDate` and cancel the deletion of the secret. # # You cannot access the encrypted secret information in any secret that # is scheduled for deletion. If you need to access that information, you - # can cancel the deletion with RestoreSecret and then retrieve the + # must cancel the deletion with RestoreSecret and then retrieve the # information. # # <note markdown="1"> * There is no explicit operation to delete a version of a secret. # Instead, remove all staging labels from the `VersionStage` field of - # a version. That marks the version as deprecated and allows AWS - # Secrets Manager to delete it as needed. Versions that do not have - # any staging labels do not show up in ListSecretVersionIds unless you + # a version. That marks the version as deprecated and allows Secrets + # Manager to delete it as needed. Versions that do not have any + # staging labels do not show up in ListSecretVersionIds unless you # specify `IncludeDeprecated`. # # * The permanent secret deletion at the end of the waiting period is # performed as a background task with low priority. There is no # guarantee of a specific time after the recovery window for the @@ -560,28 +599,47 @@ # **Related operations** # # * To create a secret, use CreateSecret. # # * To cancel deletion of a version of a secret before the recovery - # period has expired, use RestoreSecret. + # window has expired, use RestoreSecret. # # @option params [required, String] :secret_id # Specifies the secret that you want to delete. You can specify either # the Amazon Resource Name (ARN) or the friendly name of the secret. # # @option params [Integer] :recovery_window_in_days - # (Optional) Specifies the number of days that AWS Secrets Manager waits + # (Optional) Specifies the number of days that Secrets Manager waits # before it can delete the secret. # # This value can range from 7 to 30 days. The default value is 30. # # @return [Types::DeleteSecretResponse] Returns a {Seahorse::Client::Response response} object which responds to the following methods: # # * {Types::DeleteSecretResponse#arn #arn} => String # * {Types::DeleteSecretResponse#name #name} => String # * {Types::DeleteSecretResponse#deletion_date #deletion_date} => Time # + # + # @example Example: To delete a secret + # + # # The following example shows how to delete a secret. The secret stays in your account in a deprecated and inaccessible + # # state until the recovery window ends. After the date and time in the DeletionDate response field has passed, you can no + # # longer recover this secret with restore-secret. + # + # resp = client.delete_secret({ + # recovery_window_in_days: 7, + # secret_id: "MyTestDatabaseSecret1", + # }) + # + # resp.to_h outputs the following: + # { + # arn: "arn:aws:secretsmanager:us-west-2:123456789012:secret:MyTestDatabaseSecret-a1b2c3", + # deletion_date: Time.parse("1524085349.095"), + # name: "MyTestDatabaseSecret", + # } + # # @example Request syntax with placeholder values # # resp = client.delete_secret({ # secret_id: "SecretIdType", # required # recovery_window_in_days: 1, @@ -644,10 +702,53 @@ # * {Types::DescribeSecretResponse#last_accessed_date #last_accessed_date} => Time # * {Types::DescribeSecretResponse#deleted_date #deleted_date} => Time # * {Types::DescribeSecretResponse#tags #tags} => Array&lt;Types::Tag&gt; # * {Types::DescribeSecretResponse#version_ids_to_stages #version_ids_to_stages} => Hash&lt;String,Array&lt;String&gt;&gt; # + # + # @example Example: To retrieve the details of a secret + # + # # The following example shows how to get the details about a secret. + # + # resp = client.describe_secret({ + # secret_id: "MyTestDatabaseSecret", + # }) + # + # resp.to_h outputs the following: + # { + # arn: "arn:aws:secretsmanager:us-west-2:123456789012:secret:MyTestDatabaseSecret-a1b2c3", + # description: "My test database secret", + # kms_key_id: "arn:aws:kms:us-west-2:123456789012:key/EXAMPLE1-90ab-cdef-fedc-ba987KMSKEY1", + # last_accessed_date: Time.parse("1523923200"), + # last_changed_date: Time.parse(1523477145.729), + # last_rotated_date: Time.parse(1525747253.72), + # name: "MyTestDatabaseSecret", + # rotation_enabled: true, + # rotation_lambda_arn: "arn:aws:lambda:us-west-2:123456789012:function:MyTestRotationLambda", + # rotation_rules: { + # automatically_after_days: 30, + # }, + # tags: [ + # { + # key: "SecondTag", + # value: "AnotherValue", + # }, + # { + # key: "FirstTag", + # value: "SomeValue", + # }, + # ], + # version_ids_to_stages: { + # "EXAMPLE1-90ab-cdef-fedc-ba987EXAMPLE" => [ + # "AWSPREVIOUS", + # ], + # "EXAMPLE2-90ab-cdef-fedc-ba987EXAMPLE" => [ + # "AWSCURRENT", + # ], + # }, + # } + # # @example Request syntax with placeholder values # # resp = client.describe_secret({ # secret_id: "SecretIdType", # required # }) @@ -737,10 +838,27 @@ # # @return [Types::GetRandomPasswordResponse] Returns a {Seahorse::Client::Response response} object which responds to the following methods: # # * {Types::GetRandomPasswordResponse#random_password #random_password} => String # + # + # @example Example: To generate a random password + # + # # The following example shows how to request a randomly generated password. This example includes the optional flags to + # # require spaces and at least one character of each included type. It specifies a length of 20 characters. + # + # resp = client.get_random_password({ + # include_space: true, + # password_length: 20, + # require_each_included_type: true, + # }) + # + # resp.to_h outputs the following: + # { + # random_password: "N+Z43a,>vx7j O8^*<8i3", + # } + # # @example Request syntax with placeholder values # # resp = client.get_random_password({ # password_length: 1, # exclude_characters: "ExcludeCharactersType", @@ -823,10 +941,34 @@ # * {Types::GetSecretValueResponse#secret_binary #secret_binary} => String # * {Types::GetSecretValueResponse#secret_string #secret_string} => String # * {Types::GetSecretValueResponse#version_stages #version_stages} => Array&lt;String&gt; # * {Types::GetSecretValueResponse#created_date #created_date} => Time # + # + # @example Example: To retrieve the encrypted secret value of a secret + # + # # The following example shows how to retrieve the secret string value from the version of the secret that has the + # # AWSPREVIOUS staging label attached. If you want to retrieve the AWSCURRENT version of the secret, then you can omit the + # # VersionStage parameter because it defaults to AWSCURRENT. + # + # resp = client.get_secret_value({ + # secret_id: "MyTestDatabaseSecret", + # version_stage: "AWSPREVIOUS", + # }) + # + # resp.to_h outputs the following: + # { + # arn: "arn:aws:secretsmanager:us-west-2:123456789012:secret:MyTestDatabaseSecret-a1b2c3", + # created_date: Time.parse(1523477145.713), + # name: "MyTestDatabaseSecret", + # secret_string: "{\n \"username\":\"david\",\n \"password\":\"BnQw&XDWgaEeT9XGTT29\"\n}\n", + # version_id: "EXAMPLE1-90ab-cdef-fedc-ba987SECRET1", + # version_stages: [ + # "AWSPREVIOUS", + # ], + # } + # # @example Request syntax with placeholder values # # resp = client.get_secret_value({ # secret_id: "SecretIdType", # required # version_id: "SecretVersionIdType", @@ -891,12 +1033,12 @@ # the response. If you don't include this parameter, it defaults to a # value that's specific to the operation. If additional items exist # beyond the maximum you specify, the `NextToken` response element is # present and has a value (isn't null). Include that value as the # `NextToken` request parameter in the next call to the operation to get - # the next part of the results. Note that AWS Secrets Manager might - # return fewer results than the maximum even when there are more results + # the next part of the results. Note that Secrets Manager might return + # fewer results than the maximum even when there are more results # available. You should check `NextToken` after every operation to # ensure that you receive all of the results. # # @option params [String] :next_token # (Optional) Use this parameter in a request if you receive a @@ -916,10 +1058,47 @@ # * {Types::ListSecretVersionIdsResponse#versions #versions} => Array&lt;Types::SecretVersionsListEntry&gt; # * {Types::ListSecretVersionIdsResponse#next_token #next_token} => String # * {Types::ListSecretVersionIdsResponse#arn #arn} => String # * {Types::ListSecretVersionIdsResponse#name #name} => String # + # + # @example Example: To list all of the secret versions associated with a secret + # + # # The following example shows how to retrieve a list of all of the versions of a secret, including those without any + # # staging labels. + # + # resp = client.list_secret_version_ids({ + # include_deprecated: true, + # secret_id: "MyTestDatabaseSecret", + # }) + # + # resp.to_h outputs the following: + # { + # arn: "arn:aws:secretsmanager:us-west-2:123456789012:secret:MyTestDatabaseSecret-a1b2c3", + # name: "MyTestDatabaseSecret", + # versions: [ + # { + # created_date: Time.parse(1523477145.713), + # version_id: "EXAMPLE1-90ab-cdef-fedc-ba987EXAMPLE", + # version_stages: [ + # "AWSPREVIOUS", + # ], + # }, + # { + # created_date: Time.parse(1523486221.391), + # version_id: "EXAMPLE2-90ab-cdef-fedc-ba987EXAMPLE", + # version_stages: [ + # "AWSCURRENT", + # ], + # }, + # { + # created_date: Time.parse(1511974462.36), + # version_id: "EXAMPLE3-90ab-cdef-fedc-ba987EXAMPLE;", + # }, + # ], + # } + # # @example Request syntax with placeholder values # # resp = client.list_secret_version_ids({ # secret_id: "SecretIdType", # required # max_results: 1, @@ -946,14 +1125,14 @@ def list_secret_version_ids(params = {}, options = {}) req = build_request(:list_secret_version_ids, params) req.send_request(options) end - # Lists all of the secrets that are stored by AWS Secrets Manager in the - # AWS account. To list the versions currently stored for a specific - # secret, use ListSecretVersionIds. The encrypted fields `SecretString` - # and `SecretBinary` are not included in the output. To get that + # Lists all of the secrets that are stored by Secrets Manager in the AWS + # account. To list the versions currently stored for a specific secret, + # use ListSecretVersionIds. The encrypted fields `SecretString` and + # `SecretBinary` are not included in the output. To get that # information, call the GetSecretValue operation. # # <note markdown="1"> Always check the `NextToken` response parameter when calling any of # the `List*` operations. These operations can occasionally return an # empty or shorter than expected list of results even when there are @@ -982,12 +1161,12 @@ # the response. If you don't include this parameter, it defaults to a # value that's specific to the operation. If additional items exist # beyond the maximum you specify, the `NextToken` response element is # present and has a value (isn't null). Include that value as the # `NextToken` request parameter in the next call to the operation to get - # the next part of the results. Note that AWS Secrets Manager might - # return fewer results than the maximum even when there are more results + # the next part of the results. Note that Secrets Manager might return + # fewer results than the maximum even when there are more results # available. You should check `NextToken` after every operation to # ensure that you receive all of the results. # # @option params [String] :next_token # (Optional) Use this parameter in a request if you receive a @@ -999,10 +1178,46 @@ # @return [Types::ListSecretsResponse] Returns a {Seahorse::Client::Response response} object which responds to the following methods: # # * {Types::ListSecretsResponse#secret_list #secret_list} => Array&lt;Types::SecretListEntry&gt; # * {Types::ListSecretsResponse#next_token #next_token} => String # + # + # @example Example: To list the secrets in your account + # + # # The following example shows how to list all of the secrets in your account. + # + # resp = client.list_secrets({ + # }) + # + # resp.to_h outputs the following: + # { + # secret_list: [ + # { + # arn: "arn:aws:secretsmanager:us-west-2:123456789012:secret:MyTestDatabaseSecret-a1b2c3", + # description: "My test database secret", + # last_changed_date: Time.parse(1523477145.729), + # name: "MyTestDatabaseSecret", + # secret_versions_to_stages: { + # "EXAMPLE1-90ab-cdef-fedc-ba987EXAMPLE" => [ + # "AWSCURRENT", + # ], + # }, + # }, + # { + # arn: "arn:aws:secretsmanager:us-west-2:123456789012:secret:MyTestDatabaseSecret1-d4e5f6", + # description: "Another secret created for a different database", + # last_changed_date: Time.parse(1523482025.685), + # name: "MyTestDatabaseSecret1", + # secret_versions_to_stages: { + # "EXAMPLE2-90ab-cdef-fedc-ba987EXAMPLE" => [ + # "AWSCURRENT", + # ], + # }, + # }, + # ], + # } + # # @example Request syntax with placeholder values # # resp = client.list_secrets({ # max_results: 1, # next_token: "NextTokenType", @@ -1042,13 +1257,13 @@ # Stores a new encrypted secret value in the specified secret. To do # this, the operation creates a new version and attaches it to the # secret. The version can contain a new `SecretString` value or a new # `SecretBinary` value. # - # <note markdown="1"> The AWS Secrets Manager console uses only the `SecretString` field. To - # add binary data to a secret with the `SecretBinary` field you must use - # the AWS CLI or one of the AWS SDKs. + # <note markdown="1"> The Secrets Manager console uses only the `SecretString` field. To add + # binary data to a secret with the `SecretBinary` field you must use the + # AWS CLI or one of the AWS SDKs. # # </note> # # * If this operation creates the first version for the secret then # Secrets Manager automatically attaches the staging label @@ -1068,21 +1283,21 @@ # * If this operation moves the staging label `AWSCURRENT` to this # version (because you included it in the `StagingLabels` parameter) # then Secrets Manager also automatically moves the staging label # `AWSPREVIOUS` to the version that `AWSCURRENT` was removed from. # - # * If you call an operation that needs to encrypt or decrypt the + # <note markdown="1"> * If you call an operation that needs to encrypt or decrypt the # `SecretString` and `SecretBinary` for a secret in the same account # as the calling user and that secret doesn't specify a KMS - # encryption key, AWS Secrets Manager uses the account's default AWS + # encryption key, Secrets Manager uses the account's default AWS # managed customer master key (CMK) with the alias # `aws/secretsmanager`. If this key doesn't already exist in your - # account then AWS Secrets Manager creates it for you automatically. - # All users in the same AWS account automatically have access to use - # the default CMK. Note that if an AWS Secrets Manager API call - # results in AWS having to create the account's AWS-managed CMK, it - # can result in a one-time significant delay in returning the result. + # account then Secrets Manager creates it for you automatically. All + # users in the same AWS account automatically have access to use the + # default CMK. Note that if an Secrets Manager API call results in AWS + # having to create the account's AWS-managed CMK, it can result in a + # one-time significant delay in returning the result. # # * If the secret is in a different AWS account from the credentials # calling an API that requires encryption or decryption of the secret # value then you must create and use a custom KMS CMK because you # can't access the default CMK for the account using credentials from @@ -1091,10 +1306,12 @@ # `KMSKeyId`. If you call an API that must encrypt or decrypt # `SecretString` or `SecretBinary` using credentials from a different # account then the KMS key policy must grant cross-account access to # that other account's user or role. # + # </note> + # # **Minimum permissions** # # To run this command, you must have the following permissions: # # * secretsmanager:PutSecretValue @@ -1121,22 +1338,18 @@ # @option params [required, String] :secret_id # Specifies the secret to which you want to add a new version. You can # specify either the Amazon Resource Name (ARN) or the friendly name of # the secret. The secret must already exist. # - # The secret name can consist of uppercase letters, lowercase letters, - # digits, and any of the following characters: /\_+=.@-    Spaces are - # not permitted. - # # @option params [String] :client_request_token # (Optional) Specifies a unique identifier for the new version of the # secret. # # <note markdown="1"> If you use the AWS CLI or one of the AWS SDK to call this operation, # then you can leave this parameter empty. The CLI or SDK generates a # random UUID for you and includes that in the request. If you don't - # use the SDK and instead generate a raw HTTP request to the AWS Secrets + # use the SDK and instead generate a raw HTTP request to the Secrets # Manager service endpoint, then you must generate a # `ClientRequestToken` yourself for new versions and include that value # in the request. # # </note> @@ -1210,21 +1423,43 @@ # you specify a staging label that's already associated with a # different version of the same secret then that staging label is # automatically removed from the other version and attached to this # version. # - # If you do not specify a value for `VersionStages` then AWS Secrets - # Manager automatically moves the staging label `AWSCURRENT` to this new + # If you do not specify a value for `VersionStages` then Secrets Manager + # automatically moves the staging label `AWSCURRENT` to this new # version. # # @return [Types::PutSecretValueResponse] Returns a {Seahorse::Client::Response response} object which responds to the following methods: # # * {Types::PutSecretValueResponse#arn #arn} => String # * {Types::PutSecretValueResponse#name #name} => String # * {Types::PutSecretValueResponse#version_id #version_id} => String # * {Types::PutSecretValueResponse#version_stages #version_stages} => Array&lt;String&gt; # + # + # @example Example: To store a secret value in a new version of a secret + # + # # The following example shows how to create a new version of the secret. Alternatively, you can use the update-secret + # # command. + # + # resp = client.put_secret_value({ + # client_request_token: "EXAMPLE2-90ab-cdef-fedc-ba987EXAMPLE", + # secret_id: "MyTestDatabaseSecret", + # secret_string: "{\"username\":\"david\",\"password\":\"BnQw!XDWgaEeT9XGTT29\"}", + # }) + # + # resp.to_h outputs the following: + # { + # arn: "arn:aws:secretsmanager:us-west-2:123456789012:secret:MyTestDatabaseSecret-a1b2c3", + # name: "MyTestDatabaseSecret", + # version_id: "EXAMPLE2-90ab-cdef-fedc-ba987EXAMPLE", + # version_stages: [ + # "AWSCURRENT", + # ], + # } + # # @example Request syntax with placeholder values # # resp = client.put_secret_value({ # secret_id: "SecretIdType", # required # client_request_token: "ClientRequestTokenType", @@ -1276,10 +1511,25 @@ # @return [Types::RestoreSecretResponse] Returns a {Seahorse::Client::Response response} object which responds to the following methods: # # * {Types::RestoreSecretResponse#arn #arn} => String # * {Types::RestoreSecretResponse#name #name} => String # + # + # @example Example: To restore a previously deleted secret + # + # # The following example shows how to restore a secret that you previously scheduled for deletion. + # + # resp = client.restore_secret({ + # secret_id: "MyTestDatabaseSecret", + # }) + # + # resp.to_h outputs the following: + # { + # arn: "arn:aws:secretsmanager:us-west-2:123456789012:secret:MyTestDatabaseSecret-a1b2c3", + # name: "MyTestDatabaseSecret", + # } + # # @example Request syntax with placeholder values # # resp = client.restore_secret({ # secret_id: "SecretIdType", # required # }) @@ -1351,11 +1601,11 @@ # * To attach staging labels to or remove staging labels from a version # of a secret, use UpdateSecretVersionStage. # # # - # [1]: http://docs.aws.amazon.com/http:/docs.aws.amazon.com/;asm-service-name;/latest/userguide/rotating-secrets.html + # [1]: http://docs.aws.amazon.com/secretsmanager/latest/userguide/rotating-secrets.html # # @option params [required, String] :secret_id # Specifies the secret that you want to rotate. You can specify either # the Amazon Resource Name (ARN) or the friendly name of the secret. # @@ -1365,11 +1615,11 @@ # # If you use the AWS CLI or one of the AWS SDK to call this operation, # then you can leave this parameter empty. The CLI or SDK generates a # random UUID for you and includes that in the request for this # parameter. If you don't use the SDK and instead generate a raw HTTP - # request to the AWS Secrets Manager service endpoint, then you must + # request to the Secrets Manager service endpoint, then you must # generate a `ClientRequestToken` yourself for new versions and include # that value in the request. # # You only need to specify your own value if you are implementing your # own retry logic and want to ensure that a given secret is not created @@ -1506,10 +1756,30 @@ # # [1]: http://docs.aws.amazon.com/cli/latest/userguide/cli-using-param.html#cli-using-param-json # # @return [Struct] Returns an empty {Seahorse::Client::Response response}. # + # + # @example Example: To add tags to a secret + # + # # The following example shows how to attach two tags each with a Key and Value to a secret. There is no output from this + # # API. To see the result, use the DescribeSecret operation. + # + # resp = client.tag_resource({ + # secret_id: "MyExampleSecret", + # tags: [ + # { + # key: "FirstTag", + # value: "SomeValue", + # }, + # { + # key: "SecondTag", + # value: "AnotherValue", + # }, + # ], + # }) + # # @example Request syntax with placeholder values # # resp = client.tag_resource({ # secret_id: "SecretIdType", # required # tags: [ # required @@ -1572,10 +1842,24 @@ # # [1]: http://docs.aws.amazon.com/cli/latest/userguide/cli-using-param.html#cli-using-param-json # # @return [Struct] Returns an empty {Seahorse::Client::Response response}. # + # + # @example Example: To remove tags from a secret + # + # # The following example shows how to remove two tags from a secret's metadata. For each, both the tag and the associated + # # value are removed. There is no output from this API. To see the result, use the DescribeSecret operation. + # + # resp = client.untag_resource({ + # secret_id: "MyTestDatabaseSecret", + # tag_keys: [ + # "FirstTag", + # "SecondTag", + # ], + # }) + # # @example Request syntax with placeholder values # # resp = client.untag_resource({ # secret_id: "SecretIdType", # required # tag_keys: ["TagKeyType"], # required @@ -1595,14 +1879,14 @@ # it also creates a new version attached to the secret. # # To modify the rotation configuration of a secret, use RotateSecret # instead. # - # <note markdown="1"> The AWS Secrets Manager console uses only the `SecretString` parameter - # and therefore limits you to encrypting and storing only a text string. - # To encrypt and store binary data as part of the version of a secret, - # you must use either the AWS CLI or one of the AWS SDKs. + # <note markdown="1"> The Secrets Manager console uses only the `SecretString` parameter and + # therefore limits you to encrypting and storing only a text string. To + # encrypt and store binary data as part of the version of a secret, you + # must use either the AWS CLI or one of the AWS SDKs. # # </note> # # * If this update creates the first version of the secret or if you did # not include the `VersionStages` parameter then Secrets Manager @@ -1614,21 +1898,21 @@ # * If a version with a `SecretVersionId` with the same value as the # `ClientRequestToken` parameter already exists, the operation # generates an error. You cannot modify an existing version, you can # only create new ones. # - # * If you call an operation that needs to encrypt or decrypt the + # <note markdown="1"> * If you call an operation that needs to encrypt or decrypt the # `SecretString` and `SecretBinary` for a secret in the same account # as the calling user and that secret doesn't specify a KMS - # encryption key, AWS Secrets Manager uses the account's default AWS + # encryption key, Secrets Manager uses the account's default AWS # managed customer master key (CMK) with the alias # `aws/secretsmanager`. If this key doesn't already exist in your - # account then AWS Secrets Manager creates it for you automatically. - # All users in the same AWS account automatically have access to use - # the default CMK. Note that if an AWS Secrets Manager API call - # results in AWS having to create the account's AWS-managed CMK, it - # can result in a one-time significant delay in returning the result. + # account then Secrets Manager creates it for you automatically. All + # users in the same AWS account automatically have access to use the + # default CMK. Note that if an Secrets Manager API call results in AWS + # having to create the account's AWS-managed CMK, it can result in a + # one-time significant delay in returning the result. # # * If the secret is in a different AWS account from the credentials # calling an API that requires encryption or decryption of the secret # value then you must create and use a custom KMS CMK because you # can't access the default CMK for the account using credentials from @@ -1637,10 +1921,12 @@ # `KMSKeyId`. If you call an API that must encrypt or decrypt # `SecretString` or `SecretBinary` using credentials from a different # account then the KMS key policy must grant cross-account access to # that other account's user or role. # + # </note> + # # **Minimum permissions** # # To run this command, you must have the following permissions: # # * secretsmanager:UpdateSecret @@ -1675,11 +1961,11 @@ # ensure idempotency. # # If you use the AWS CLI or one of the AWS SDK to call this operation, # then you can leave this parameter empty. The CLI or SDK generates a # random UUID for you and includes that in the request. If you don't - # use the SDK and instead generate a raw HTTP request to the AWS Secrets + # use the SDK and instead generate a raw HTTP request to the Secrets # Manager service endpoint, then you must generate a # `ClientRequestToken` yourself for new versions and include that value # in the request. # # You typically only need to interact with this value if you implement @@ -1722,12 +2008,12 @@ # secret. # # If you don't specify this value, then Secrets Manager defaults to # using the default CMK in the account (the one named # `aws/secretsmanager`). If a KMS CMK with that name doesn't exist, - # then AWS Secrets Manager creates it for you automatically the first - # time it needs to encrypt a version's `Plaintext` or `PlaintextString` + # then Secrets Manager creates it for you automatically the first time + # it needs to encrypt a version's `Plaintext` or `PlaintextString` # fields. # # You can only use the account's default CMK to encrypt and decrypt if # you call this operation using credentials from the same account that # owns the secret. If the secret is in a different account, then you @@ -1768,10 +2054,60 @@ # # * {Types::UpdateSecretResponse#arn #arn} => String # * {Types::UpdateSecretResponse#name #name} => String # * {Types::UpdateSecretResponse#version_id #version_id} => String # + # + # @example Example: To update the description of a secret + # + # # The following example shows how to modify the description of a secret. + # + # resp = client.update_secret({ + # client_request_token: "EXAMPLE1-90ab-cdef-fedc-ba987EXAMPLE", + # description: "This is a new description for the secret.", + # secret_id: "MyTestDatabaseSecret", + # }) + # + # resp.to_h outputs the following: + # { + # arn: "arn:aws:secretsmanager:us-west-2:123456789012:secret:MyTestDatabaseSecret-a1b2c3", + # name: "MyTestDatabaseSecret", + # } + # + # @example Example: To update the KMS key associated with a secret + # + # # This example shows how to update the KMS customer managed key (CMK) used to encrypt the secret value. The KMS CMK must + # # be in the same region as the secret. + # + # resp = client.update_secret({ + # kms_key_id: "arn:aws:kms:us-west-2:123456789012:key/EXAMPLE2-90ab-cdef-fedc-ba987EXAMPLE", + # secret_id: "MyTestDatabaseSecret", + # }) + # + # resp.to_h outputs the following: + # { + # arn: "arn:aws:secretsmanager:us-west-2:123456789012:secret:MyTestDatabaseSecret-a1b2c3", + # name: "MyTestDatabaseSecret", + # } + # + # @example Example: To create a new version of the encrypted secret value + # + # # The following example shows how to create a new version of the secret by updating the SecretString field. Alternatively, + # # you can use the put-secret-value operation. + # + # resp = client.update_secret({ + # secret_id: "MyTestDatabaseSecret", + # secret_string: "{JSON STRING WITH CREDENTIALS}", + # }) + # + # resp.to_h outputs the following: + # { + # arn: "aws:arn:secretsmanager:us-west-2:123456789012:secret:MyTestDatabaseSecret-a1b2c3", + # name: "MyTestDatabaseSecret", + # version_id: "EXAMPLE1-90ab-cdef-fedc-ba987EXAMPLE", + # } + # # @example Request syntax with placeholder values # # resp = client.update_secret({ # secret_id: "SecretIdType", # required # client_request_token: "ClientRequestTokenType", @@ -1838,11 +2174,11 @@ # # ^ # # # - # [1]: http://docs.aws.amazon.com/http:/docs.aws.amazon.com/;asm-service-name;/latest/userguide/terms-concepts.html#term_label + # [1]: http://docs.aws.amazon.com/secretsmanager/latest/userguide/terms-concepts.html#term_staging-label # # @option params [required, String] :secret_id # Specifies the secret with the version whose list of staging labels you # want to modify. You can specify either the Amazon Resource Name (ARN) # or the friendly name of the secret. @@ -1874,10 +2210,65 @@ # @return [Types::UpdateSecretVersionStageResponse] Returns a {Seahorse::Client::Response response} object which responds to the following methods: # # * {Types::UpdateSecretVersionStageResponse#arn #arn} => String # * {Types::UpdateSecretVersionStageResponse#name #name} => String # + # + # @example Example: To add a staging label attached to a version of a secret + # + # # The following example shows you how to add a staging label to a version of a secret. You can review the results by + # # running the operation ListSecretVersionIds and viewing the VersionStages response field for the affected version. + # + # resp = client.update_secret_version_stage({ + # move_to_version_id: "EXAMPLE1-90ab-cdef-fedc-ba987SECRET1", + # secret_id: "MyTestDatabaseSecret", + # version_stage: "STAGINGLABEL1", + # }) + # + # resp.to_h outputs the following: + # { + # arn: "arn:aws:secretsmanager:us-west-2:123456789012:secret:MyTestDatabaseSecret-a1b2c3", + # name: "MyTestDatabaseSecret", + # } + # + # @example Example: To delete a staging label attached to a version of a secret + # + # # The following example shows you how to delete a staging label that is attached to a version of a secret. You can review + # # the results by running the operation ListSecretVersionIds and viewing the VersionStages response field for the affected + # # version. + # + # resp = client.update_secret_version_stage({ + # remove_from_version_id: "EXAMPLE1-90ab-cdef-fedc-ba987SECRET1", + # secret_id: "MyTestDatabaseSecret", + # version_stage: "STAGINGLABEL1", + # }) + # + # resp.to_h outputs the following: + # { + # arn: "arn:aws:secretsmanager:us-west-2:123456789012:secret:MyTestDatabaseSecret-a1b2c3", + # name: "MyTestDatabaseSecret", + # } + # + # @example Example: To move a staging label from one version of a secret to another + # + # # The following example shows you how to move a staging label that is attached to one version of a secret to a different + # # version. You can review the results by running the operation ListSecretVersionIds and viewing the VersionStages response + # # field for the affected version. + # + # resp = client.update_secret_version_stage({ + # move_to_version_id: "EXAMPLE2-90ab-cdef-fedc-ba987SECRET2", + # remove_from_version_id: "EXAMPLE1-90ab-cdef-fedc-ba987SECRET1", + # secret_id: "MyTestDatabaseSecret", + # version_stage: "AWSCURRENT", + # }) + # + # resp.to_h outputs the following: + # { + # arn: "arn:aws:secretsmanager:us-west-2:123456789012:secret:MyTestDatabaseSecret-a1b2c3", + # name: "MyTestDatabaseSecret", + # } + # # @example Request syntax with placeholder values # # resp = client.update_secret_version_stage({ # secret_id: "SecretIdType", # required # version_stage: "SecretVersionStageType", # required @@ -1910,10 +2301,10 @@ operation: config.api.operation(operation_name), client: self, params: params, config: config) context[:gem_name] = 'aws-sdk-secretsmanager' - context[:gem_version] = '1.0.0' + context[:gem_version] = '1.1.0' Seahorse::Client::Request.new(handlers, context) end # @api private # @deprecated