2015/10/26 - Amazon Simple Systems Management Service - 5 new 7 updated api methods
Executes commands on one or more remote instances.
Request Syntax
client.send_command(
InstanceIds=[
'string',
],
DocumentName='string',
TimeoutSeconds=123,
Comment='string',
Parameters={
'string': [
'string',
]
},
OutputS3BucketName='string',
OutputS3KeyPrefix='string'
)
list
[REQUIRED] Required. The instance IDs where the command should execute.
(string) --
string
[REQUIRED] Required. The name of the SSM document to execute. This can be an SSM public document or a custom document.
integer
If this time is reached and the command has not already started executing, it will not execute.
string
User-specified information about the command, such as a brief description of what the command should do.
dict
The required and optional parameters specified in the SSM document being executed.
(string) --
(list) --
(string) --
string
The name of the S3 bucket where command execution responses should be stored.
string
The directory structure within the S3 bucket where the responses should be stored.
dict
Response Syntax
{
'Command': {
'CommandId': 'string',
'DocumentName': 'string',
'Comment': 'string',
'ExpiresAfter': datetime(2015, 1, 1),
'Parameters': {
'string': [
'string',
]
},
'InstanceIds': [
'string',
],
'RequestedDateTime': datetime(2015, 1, 1),
'Status': 'Pending'|'InProgress'|'Cancelling'|'Success'|'TimedOut'|'Cancelled'|'Failed',
'OutputS3BucketName': 'string',
'OutputS3KeyPrefix': 'string'
}
}
Response Structure
(dict) --
Command (dict) -- The request as it was received by SSM. Also provides the command ID which can be used future references to this request.
CommandId (string) -- A unique identifier for this command.
DocumentName (string) -- The name of the SSM document requested for execution.
Comment (string) -- User-specified information about the command, such as a brief description of what the command should do.
ExpiresAfter (datetime) -- If this time is reached and the command has not already started executing, it will not execute. Calculated based on the ExpiresAfter user input provided as part of the SendCommand API.
Parameters (dict) -- The parameter values to be inserted in the SSM document when executing the command.
(string) --
(list) --
(string) --
InstanceIds (list) -- The instance IDs against which this command was requested.
(string) --
RequestedDateTime (datetime) -- The date and time the command was requested.
Status (string) -- The status of the command.
OutputS3BucketName (string) -- The S3 bucket where the responses to the command executions should be stored. This was requested when issuing the command.
OutputS3KeyPrefix (string) -- The S3 directory path inside the bucket where the responses to the command executions should be stored. This was requested when issuing the command.
Lists the commands requested by users of the AWS account.
Request Syntax
client.list_commands(
CommandId='string',
InstanceId='string',
MaxResults=123,
NextToken='string',
Filters=[
{
'key': 'InvokedAfter'|'InvokedBefore'|'Status',
'value': 'string'
},
]
)
string
(Optional) If provided, lists only the specified command.
string
(Optional) Lists commands issued against this instance ID.
integer
(Optional) The maximum number of items to return for this call. The call also returns a token that you can specify in a subsequent call to get the next set of results.
string
(Optional) The token for the next set of items to return. (You received this token from a previous call.)
list
(Optional) One or more filters. Use a filter to return a more specific list of results.
(dict) -- Describes a command filter.
key (string) -- [REQUIRED] The name of the filter. For example, requested date and time.
value (string) -- [REQUIRED] The filter value. For example: June 30, 2015.
dict
Response Syntax
{
'Commands': [
{
'CommandId': 'string',
'DocumentName': 'string',
'Comment': 'string',
'ExpiresAfter': datetime(2015, 1, 1),
'Parameters': {
'string': [
'string',
]
},
'InstanceIds': [
'string',
],
'RequestedDateTime': datetime(2015, 1, 1),
'Status': 'Pending'|'InProgress'|'Cancelling'|'Success'|'TimedOut'|'Cancelled'|'Failed',
'OutputS3BucketName': 'string',
'OutputS3KeyPrefix': 'string'
},
],
'NextToken': 'string'
}
Response Structure
(dict) --
Commands (list) -- (Optional) The list of commands requested by the user.
(dict) -- Describes a command request.
CommandId (string) -- A unique identifier for this command.
DocumentName (string) -- The name of the SSM document requested for execution.
Comment (string) -- User-specified information about the command, such as a brief description of what the command should do.
ExpiresAfter (datetime) -- If this time is reached and the command has not already started executing, it will not execute. Calculated based on the ExpiresAfter user input provided as part of the SendCommand API.
Parameters (dict) -- The parameter values to be inserted in the SSM document when executing the command.
(string) --
(list) --
(string) --
InstanceIds (list) -- The instance IDs against which this command was requested.
(string) --
RequestedDateTime (datetime) -- The date and time the command was requested.
Status (string) -- The status of the command.
OutputS3BucketName (string) -- The S3 bucket where the responses to the command executions should be stored. This was requested when issuing the command.
OutputS3KeyPrefix (string) -- The S3 directory path inside the bucket where the responses to the command executions should be stored. This was requested when issuing the command.
NextToken (string) -- (Optional) The token for the next set of items to return. (You received this token from a previous call.)
Describes one or more of your instances. You can use this to get information about instances like the operating system platform, the SSM agent version, status etc. If you specify one or more instance IDs, it returns information for those instances. If you do not specify instance IDs, it returns information for all your instances. If you specify an instance ID that is not valid or an instance that you do not own, you receive an error.
Request Syntax
client.describe_instance_information(
InstanceInformationFilterList=[
{
'key': 'InstanceIds'|'AgentVersion'|'PingStatus'|'PlatformTypes',
'valueSet': [
'string',
]
},
],
MaxResults=123,
NextToken='string'
)
list
One or more filters. Use a filter to return a more specific list of instances.
(dict) -- Describes a filter for a specific list of instances.
key (string) -- [REQUIRED] The name of the filter.
valueSet (list) -- [REQUIRED] The filter values.
(string) --
integer
The maximum number of items to return for this call. The call also returns a token that you can specify in a subsequent call to get the next set of results.
string
The token for the next set of items to return. (You received this token from a previous call.)
dict
Response Syntax
{
'InstanceInformationList': [
{
'InstanceId': 'string',
'PingStatus': 'Online'|'ConnectionLost'|'Inactive',
'LastPingDateTime': datetime(2015, 1, 1),
'AgentVersion': 'string',
'IsLatestVersion': True|False,
'PlatformType': 'Windows'|'Linux',
'PlatformName': 'string',
'PlatformVersion': 'string'
},
],
'NextToken': 'string'
}
Response Structure
(dict) --
InstanceInformationList (list) -- The instance information list.
(dict) -- Describes a filter for a specific list of instances.
InstanceId (string) -- The instance ID.
PingStatus (string) -- Connection status of the SSM agent.
LastPingDateTime (datetime) -- The date and time when agent last pinged SSM service.
AgentVersion (string) -- The version of the SSM agent running on your instance.
IsLatestVersion (boolean) -- Indicates whether latest version of the SSM agent is running on your instance.
PlatformType (string) -- The operating system platform type.
PlatformName (string) -- The name of the operating system platform running on your instance.
PlatformVersion (string) -- The version of the OS platform running on your instance.
NextToken (string) -- The token to use when requesting the next set of items. If there are no additional items to return, the string is empty.
Attempts to cancel the command specified by the Command ID. There is no guarantee that the command will be terminated and the underlying process stopped.
Request Syntax
client.cancel_command(
CommandId='string',
InstanceIds=[
'string',
]
)
string
[REQUIRED] The ID of the command you want to cancel.
list
(Optional) A list of instance IDs on which you want to cancel the command. If not provided, the command is canceled on every instance on which it was requested.
(string) --
dict
Response Syntax
{}
Response Structure
(dict) --
Whether or not the command was successfully canceled. There is no guarantee that a request can be canceled.
An invocation is copy of a command sent to a specific instance. A command can apply to one or more instances. A command invocation applies to one instance. For example, if a user executes SendCommand against three instances, then a command invocation is created for each requested instance ID. ListCommandInvocations provide status about command execution.
Request Syntax
client.list_command_invocations(
CommandId='string',
InstanceId='string',
MaxResults=123,
NextToken='string',
Filters=[
{
'key': 'InvokedAfter'|'InvokedBefore'|'Status',
'value': 'string'
},
],
Details=True|False
)
string
(Optional) The invocations for a specific command ID.
string
(Optional) The command execution details for a specific instance ID.
integer
(Optional) The maximum number of items to return for this call. The call also returns a token that you can specify in a subsequent call to get the next set of results.
string
(Optional) The token for the next set of items to return. (You received this token from a previous call.)
list
(Optional) One or more filters. Use a filter to return a more specific list of results.
(dict) -- Describes a command filter.
key (string) -- [REQUIRED] The name of the filter. For example, requested date and time.
value (string) -- [REQUIRED] The filter value. For example: June 30, 2015.
boolean
(Optional) If set this returns the response of the command executions. By default this is set to False.
dict
Response Syntax
{
'CommandInvocations': [
{
'CommandId': 'string',
'InstanceId': 'string',
'Comment': 'string',
'DocumentName': 'string',
'RequestedDateTime': datetime(2015, 1, 1),
'Status': 'Pending'|'InProgress'|'Cancelling'|'Success'|'TimedOut'|'Cancelled'|'Failed',
'TraceOutput': 'string',
'CommandPlugins': [
{
'Name': 'string',
'Status': 'Pending'|'InProgress'|'Success'|'TimedOut'|'Cancelled'|'Failed',
'ResponseCode': 123,
'ResponseStartDateTime': datetime(2015, 1, 1),
'ResponseFinishDateTime': datetime(2015, 1, 1),
'Output': 'string',
'OutputS3BucketName': 'string',
'OutputS3KeyPrefix': 'string'
},
]
},
],
'NextToken': 'string'
}
Response Structure
(dict) --
CommandInvocations (list) -- (Optional) A list of all invocations.
(dict) -- An invocation is copy of a command sent to a specific instance. A command can apply to one or more instances. A command invocation applies to one instance. For example, if a user executes SendCommand against three instances, then a command invocation is created for each requested instance ID. A command invocation returns status and detail information about a command you executed.
CommandId (string) -- The command against which this invocation was requested.
InstanceId (string) -- The instance ID in which this invocation was requested.
Comment (string) -- User-specified information about the command, such as a brief description of what the command should do.
DocumentName (string) -- The document name that was requested for execution.
RequestedDateTime (datetime) -- The time and date the request was sent to this instance.
Status (string) -- Whether or not the invocation succeeded, failed, or is pending.
TraceOutput (string) -- Gets the trace output sent by the agent.
CommandPlugins (list) --
(dict) -- Describes plugin details.
Name (string) -- The name of the plugin. Must be one of the following: AWS-JoinDirectoryServiceDomain, AWS-InstallApplication, AWS-RunPowerShellScript, AWS-InstallPowerShellModule, AWS-ConfigureCloudWatch.
Status (string) -- The status of this plugin. You can execute a document with multiple plugins.
ResponseCode (integer) -- A numeric response code generated after executing the plugin.
ResponseStartDateTime (datetime) -- The time the plugin started executing.
ResponseFinishDateTime (datetime) -- The time the plugin stopped executing. Could stop prematurely if, for example, a cancel command was sent.
Output (string) -- Output of the plugin execution.
OutputS3BucketName (string) -- The S3 bucket where the responses to the command executions should be stored. This was requested when issuing the command.
OutputS3KeyPrefix (string) -- The S3 directory path inside the bucket where the responses to the command executions should be stored. This was requested when issuing the command.
NextToken (string) -- (Optional) The token for the next set of items to return. (You received this token from a previous call.)
{'Parameters': {'string': ['string']}}
Response {'AssociationDescription': {'Parameters': {'string': ['string']}}}
Associates the specified SSM document with the specified instance.
When you associate an SSM document with an instance, the configuration agent on the instance processes the document and configures the instance as specified.
If you associate a document with an instance that already has an associated document, the system throws the AssociationAlreadyExists exception.
Request Syntax
client.create_association(
Name='string',
InstanceId='string',
Parameters={
'string': [
'string',
]
}
)
string
[REQUIRED]
The name of the SSM document.
string
[REQUIRED]
The instance ID.
dict
The parameters for the document’s runtime configuration.
(string) --
(list) --
(string) --
dict
Response Syntax
{
'AssociationDescription': {
'Name': 'string',
'InstanceId': 'string',
'Date': datetime(2015, 1, 1),
'Status': {
'Date': datetime(2015, 1, 1),
'Name': 'Pending'|'Success'|'Failed',
'Message': 'string',
'AdditionalInfo': 'string'
},
'Parameters': {
'string': [
'string',
]
}
}
}
Response Structure
(dict) --
AssociationDescription (dict) --
Information about the association.
Name (string) --
The name of the SSM document.
InstanceId (string) --
The ID of the instance.
Date (datetime) --
The date when the association was made.
Status (dict) --
The association status.
Date (datetime) --
The date when the status changed.
Name (string) --
The status.
Message (string) --
The reason for the status.
AdditionalInfo (string) --
A user-defined string.
Parameters (dict) -- A description of the parameters for a document.
(string) --
(list) --
(string) --
{'Entries': {'Parameters': {'string': ['string']}}}
Response {'Failed': {'Entry': {'Parameters': {'string': ['string']}}},
'Successful': {'Parameters': {'string': ['string']}}}
Associates the specified SSM document with the specified instances.
When you associate an SSM document with an instance, the configuration agent on the instance processes the document and configures the instance as specified.
If you associate a document with an instance that already has an associated document, the system throws the AssociationAlreadyExists exception.
Request Syntax
client.create_association_batch(
Entries=[
{
'Name': 'string',
'InstanceId': 'string',
'Parameters': {
'string': [
'string',
]
}
},
]
)
list
[REQUIRED]
One or more associations.
(dict) -- Describes the association of an SSM document and an instance.
Name (string) -- The name of the configuration document.
InstanceId (string) -- The ID of the instance.
Parameters (dict) -- A description of the parameters for a document.
(string) --
(list) --
(string) --
dict
Response Syntax
{
'Successful': [
{
'Name': 'string',
'InstanceId': 'string',
'Date': datetime(2015, 1, 1),
'Status': {
'Date': datetime(2015, 1, 1),
'Name': 'Pending'|'Success'|'Failed',
'Message': 'string',
'AdditionalInfo': 'string'
},
'Parameters': {
'string': [
'string',
]
}
},
],
'Failed': [
{
'Entry': {
'Name': 'string',
'InstanceId': 'string',
'Parameters': {
'string': [
'string',
]
}
},
'Message': 'string',
'Fault': 'Client'|'Server'|'Unknown'
},
]
}
Response Structure
(dict) --
Successful (list) --
Information about the associations that succeeded.
(dict) --
Describes the parameters for a document.
Name (string) --
The name of the SSM document.
InstanceId (string) --
The ID of the instance.
Date (datetime) --
The date when the association was made.
Status (dict) --
The association status.
Date (datetime) --
The date when the status changed.
Name (string) --
The status.
Message (string) --
The reason for the status.
AdditionalInfo (string) --
A user-defined string.
Parameters (dict) -- A description of the parameters for a document.
(string) --
(list) --
(string) --
Failed (list) --
Information about the associations that failed.
(dict) --
Describes a failed association.
Entry (dict) --
The association.
Name (string) -- The name of the configuration document.
InstanceId (string) -- The ID of the instance.
Parameters (dict) -- A description of the parameters for a document.
(string) --
(list) --
(string) --
Message (string) --
A description of the failure.
Fault (string) --
The source of the failure.
{'DocumentDescription': {'Description': 'string',
'Parameters': [{'DefaultValue': 'string',
'Description': 'string',
'Name': 'string',
'Type': 'String | StringList'}],
'PlatformTypes': ['Windows | Linux']}}
Creates an SSM document.
After you create an SSM document, you can use CreateAssociation to associate it with one or more running instances.
Request Syntax
client.create_document(
Content='string',
Name='string'
)
string
[REQUIRED]
A valid JSON string. For more information about the contents of this string, see SSM Document.
string
[REQUIRED]
A name for the SSM document.
dict
Response Syntax
{
'DocumentDescription': {
'Sha1': 'string',
'Name': 'string',
'CreatedDate': datetime(2015, 1, 1),
'Status': 'Creating'|'Active'|'Deleting',
'Description': 'string',
'Parameters': [
{
'Name': 'string',
'Type': 'String'|'StringList',
'Description': 'string',
'DefaultValue': 'string'
},
],
'PlatformTypes': [
'Windows'|'Linux',
]
}
}
Response Structure
(dict) --
DocumentDescription (dict) --
Information about the SSM document.
Sha1 (string) --
The SHA1 hash of the document, which you can use for verification purposes.
Name (string) --
The name of the SSM document.
CreatedDate (datetime) -- The date when the SSM document was created.
Status (string) --
The status of the SSM document.
Description (string) -- A description of the document.
Parameters (list) --
A description of the parameters for a document.
(dict) --
Name (string) --
The name of the parameter.
Type (string) --
The type of parameter. The type can be either “String” or “StringList”.
Description (string) --
A description of what the parameter does, how to use it, the default value, and whether or not the parameter is optional.
DefaultValue (string) --
If specified, the default values for the parameters. Parameters without a default value are required. Parameters with a default value are optional.
PlatformTypes (list) -- The list of OS platforms compatible with this SSM document.
(string) --
{'AssociationDescription': {'Parameters': {'string': ['string']}}}
Describes the associations for the specified SSM document or instance.
Request Syntax
client.describe_association(
Name='string',
InstanceId='string'
)
string
[REQUIRED]
The name of the SSM document.
string
[REQUIRED]
The ID of the instance.
dict
Response Syntax
{
'AssociationDescription': {
'Name': 'string',
'InstanceId': 'string',
'Date': datetime(2015, 1, 1),
'Status': {
'Date': datetime(2015, 1, 1),
'Name': 'Pending'|'Success'|'Failed',
'Message': 'string',
'AdditionalInfo': 'string'
},
'Parameters': {
'string': [
'string',
]
}
}
}
Response Structure
(dict) --
AssociationDescription (dict) --
Information about the association.
Name (string) --
The name of the SSM document.
InstanceId (string) --
The ID of the instance.
Date (datetime) --
The date when the association was made.
Status (dict) --
The association status.
Date (datetime) --
The date when the status changed.
Name (string) --
The status.
Message (string) --
The reason for the status.
AdditionalInfo (string) --
A user-defined string.
Parameters (dict) -- A description of the parameters for a document.
(string) --
(list) --
(string) --
{'Document': {'Description': 'string',
'Parameters': [{'DefaultValue': 'string',
'Description': 'string',
'Name': 'string',
'Type': 'String | StringList'}],
'PlatformTypes': ['Windows | Linux']}}
Describes the specified SSM document.
Request Syntax
client.describe_document(
Name='string'
)
string
[REQUIRED]
The name of the SSM document.
dict
Response Syntax
{
'Document': {
'Sha1': 'string',
'Name': 'string',
'CreatedDate': datetime(2015, 1, 1),
'Status': 'Creating'|'Active'|'Deleting',
'Description': 'string',
'Parameters': [
{
'Name': 'string',
'Type': 'String'|'StringList',
'Description': 'string',
'DefaultValue': 'string'
},
],
'PlatformTypes': [
'Windows'|'Linux',
]
}
}
Response Structure
(dict) --
Document (dict) --
Information about the SSM document.
Sha1 (string) --
The SHA1 hash of the document, which you can use for verification purposes.
Name (string) --
The name of the SSM document.
CreatedDate (datetime) -- The date when the SSM document was created.
Status (string) --
The status of the SSM document.
Description (string) -- A description of the document.
Parameters (list) --
A description of the parameters for a document.
(dict) --
Name (string) --
The name of the parameter.
Type (string) --
The type of parameter. The type can be either “String” or “StringList”.
Description (string) --
A description of what the parameter does, how to use it, the default value, and whether or not the parameter is optional.
DefaultValue (string) --
If specified, the default values for the parameters. Parameters without a default value are required. Parameters with a default value are optional.
PlatformTypes (list) -- The list of OS platforms compatible with this SSM document.
(string) --
{'DocumentFilterList': {'key': {'PlatformTypes', 'Owner'}}}
Response {'DocumentIdentifiers': {'PlatformTypes': ['Windows | Linux']}}
Describes one or more of your SSM documents.
Request Syntax
client.list_documents(
DocumentFilterList=[
{
'key': 'Name'|'Owner'|'PlatformTypes',
'value': 'string'
},
],
MaxResults=123,
NextToken='string'
)
list
One or more filters. Use a filter to return a more specific list of results.
(dict) --
Describes a filter.
key (string) -- [REQUIRED]
The name of the filter.
value (string) -- [REQUIRED]
The value of the filter.
integer
The maximum number of items to return for this call. The call also returns a token that you can specify in a subsequent call to get the next set of results.
string
The token for the next set of items to return. (You received this token from a previous call.)
dict
Response Syntax
{
'DocumentIdentifiers': [
{
'Name': 'string',
'PlatformTypes': [
'Windows'|'Linux',
]
},
],
'NextToken': 'string'
}
Response Structure
(dict) --
DocumentIdentifiers (list) --
The names of the SSM documents.
(dict) --
Describes the name of an SSM document.
Name (string) --
The name of the SSM document.
PlatformTypes (list) -- The operating system platform.
(string) --
NextToken (string) --
The token to use when requesting the next set of items. If there are no additional items to return, the string is empty.
{'AssociationDescription': {'Parameters': {'string': ['string']}}}
Updates the status of the SSM document associated with the specified instance.
Request Syntax
client.update_association_status(
Name='string',
InstanceId='string',
AssociationStatus={
'Date': datetime(2015, 1, 1),
'Name': 'Pending'|'Success'|'Failed',
'Message': 'string',
'AdditionalInfo': 'string'
}
)
string
[REQUIRED]
The name of the SSM document.
string
[REQUIRED]
The ID of the instance.
dict
[REQUIRED]
The association status.
Date (datetime) -- [REQUIRED]
The date when the status changed.
Name (string) -- [REQUIRED]
The status.
Message (string) -- [REQUIRED]
The reason for the status.
AdditionalInfo (string) --
A user-defined string.
dict
Response Syntax
{
'AssociationDescription': {
'Name': 'string',
'InstanceId': 'string',
'Date': datetime(2015, 1, 1),
'Status': {
'Date': datetime(2015, 1, 1),
'Name': 'Pending'|'Success'|'Failed',
'Message': 'string',
'AdditionalInfo': 'string'
},
'Parameters': {
'string': [
'string',
]
}
}
}
Response Structure
(dict) --
AssociationDescription (dict) --
Information about the association.
Name (string) --
The name of the SSM document.
InstanceId (string) --
The ID of the instance.
Date (datetime) --
The date when the association was made.
Status (dict) --
The association status.
Date (datetime) --
The date when the status changed.
Name (string) --
The status.
Message (string) --
The reason for the status.
AdditionalInfo (string) --
A user-defined string.
Parameters (dict) -- A description of the parameters for a document.
(string) --
(list) --
(string) --