Request Syntax Request Parameters Response Syntax Response Elements Errors Examples See Also

CreateAssociationBatch

Associates the specified Amazon Systems Manager document (SSM document) with the specified instances or targets.

When you associate a document with one or more instances using instance IDs or tags, Amazon Systems Manager Agent (SSM Agent) running 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 returns the AssociationAlreadyExists exception.

Request Syntax


{
   "Entries": [ 
      { 
         "ApplyOnlyAtCronInterval": boolean,
         "AssociationName": "string",
         "AutomationTargetParameterName": "string",
         "CalendarNames": [ "string" ],
         "ComplianceSeverity": "string",
         "DocumentVersion": "string",
         "InstanceId": "string",
         "MaxConcurrency": "string",
         "MaxErrors": "string",
         "Name": "string",
         "OutputLocation": { 
            "S3Location": { 
               "OutputS3BucketName": "string",
               "OutputS3KeyPrefix": "string",
               "OutputS3Region": "string"
            }
         },
         "Parameters": { 
            "string" : [ "string" ]
         },
         "ScheduleExpression": "string",
         "SyncCompliance": "string",
         "TargetLocations": [ 
            { 
               "Accounts": [ "string" ],
               "ExecutionRoleName": "string",
               "Regions": [ "string" ],
               "TargetLocationMaxConcurrency": "string",
               "TargetLocationMaxErrors": "string"
            }
         ],
         "Targets": [ 
            { 
               "Key": "string",
               "Values": [ "string" ]
            }
         ]
      }
   ]
}

Request Parameters

For information about the parameters that are common to all actions, see Common Parameters.

The request accepts the following data in JSON format.

Entries

One or more associations.

Type: Array of CreateAssociationBatchRequestEntry objects

Array Members: Minimum number of 1 item.

Required: Yes

Response Syntax


{
   "Failed": [ 
      { 
         "Entry": { 
            "ApplyOnlyAtCronInterval": boolean,
            "AssociationName": "string",
            "AutomationTargetParameterName": "string",
            "CalendarNames": [ "string" ],
            "ComplianceSeverity": "string",
            "DocumentVersion": "string",
            "InstanceId": "string",
            "MaxConcurrency": "string",
            "MaxErrors": "string",
            "Name": "string",
            "OutputLocation": { 
               "S3Location": { 
                  "OutputS3BucketName": "string",
                  "OutputS3KeyPrefix": "string",
                  "OutputS3Region": "string"
               }
            },
            "Parameters": { 
               "string" : [ "string" ]
            },
            "ScheduleExpression": "string",
            "SyncCompliance": "string",
            "TargetLocations": [ 
               { 
                  "Accounts": [ "string" ],
                  "ExecutionRoleName": "string",
                  "Regions": [ "string" ],
                  "TargetLocationMaxConcurrency": "string",
                  "TargetLocationMaxErrors": "string"
               }
            ],
            "Targets": [ 
               { 
                  "Key": "string",
                  "Values": [ "string" ]
               }
            ]
         },
         "Fault": "string",
         "Message": "string"
      }
   ],
   "Successful": [ 
      { 
         "ApplyOnlyAtCronInterval": boolean,
         "AssociationId": "string",
         "AssociationName": "string",
         "AssociationVersion": "string",
         "AutomationTargetParameterName": "string",
         "CalendarNames": [ "string" ],
         "ComplianceSeverity": "string",
         "Date": number,
         "DocumentVersion": "string",
         "InstanceId": "string",
         "LastExecutionDate": number,
         "LastSuccessfulExecutionDate": number,
         "LastUpdateAssociationDate": number,
         "MaxConcurrency": "string",
         "MaxErrors": "string",
         "Name": "string",
         "OutputLocation": { 
            "S3Location": { 
               "OutputS3BucketName": "string",
               "OutputS3KeyPrefix": "string",
               "OutputS3Region": "string"
            }
         },
         "Overview": { 
            "AssociationStatusAggregatedCount": { 
               "string" : number 
            },
            "DetailedStatus": "string",
            "Status": "string"
         },
         "Parameters": { 
            "string" : [ "string" ]
         },
         "ScheduleExpression": "string",
         "Status": { 
            "AdditionalInfo": "string",
            "Date": number,
            "Message": "string",
            "Name": "string"
         },
         "SyncCompliance": "string",
         "TargetLocations": [ 
            { 
               "Accounts": [ "string" ],
               "ExecutionRoleName": "string",
               "Regions": [ "string" ],
               "TargetLocationMaxConcurrency": "string",
               "TargetLocationMaxErrors": "string"
            }
         ],
         "Targets": [ 
            { 
               "Key": "string",
               "Values": [ "string" ]
            }
         ]
      }
   ]
}

Response Elements

If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in JSON format by the service.

Failed

Information about the associations that failed.

Type: Array of FailedCreateAssociation objects

Successful

Information about the associations that succeeded.

Type: Array of AssociationDescription objects

Errors

For information about the errors that are common to all actions, see Common Errors.

AssociationLimitExceeded

You can have at most 2,000 active associations.

HTTP Status Code: 400

DuplicateInstanceId

You can't specify an instance ID in more than one association.

HTTP Status Code: 400

InternalServerError

An error occurred on the server side.

HTTP Status Code: 500

InvalidDocument

The specified SSM document doesn't exist.

HTTP Status Code: 400

InvalidDocumentVersion

The document version isn't valid or doesn't exist.

HTTP Status Code: 400

InvalidInstanceId

The following problems can cause this exception:

You don't have permission to access the instance.
Amazon Systems Manager Agent(SSM Agent) isn't running. Verify that SSM Agent is running.
SSM Agent isn't registered with the SSM endpoint. Try reinstalling SSM Agent.
The instance isn't in valid state. Valid states are: Running, Pending, Stopped, and Stopping. Invalid states are: Shutting-down and Terminated.

HTTP Status Code: 400

InvalidOutputLocation

The output location isn't valid or doesn't exist.

HTTP Status Code: 400

InvalidParameters

You must specify values for all required parameters in the Amazon Systems Manager document (SSM document). You can only supply values to parameters defined in the SSM document.

HTTP Status Code: 400

InvalidSchedule

The schedule is invalid. Verify your cron or rate expression and try again.

HTTP Status Code: 400

InvalidTarget

The target isn't valid or doesn't exist. It might not be configured for Systems Manager or you might not have permission to perform the operation.

HTTP Status Code: 400

UnsupportedPlatformType

The document doesn't support the platform type of the given instance ID(s). For example, you sent an document for a Windows instance to a Linux instance.

HTTP Status Code: 400

Examples

Example

This example illustrates one usage of CreateAssociationBatch.

Sample Request


POST / HTTP/1.1
Host: ssm.us-east-2.amazonaws.com
Accept-Encoding: identity
X-Amz-Target: AmazonSSM.CreateAssociationBatch
Content-Type: application/x-amz-json-1.1
User-Agent: aws-cli/1.17.12 Python/3.6.8 Darwin/18.7.0 botocore/1.14.12
X-Amz-Date: 20200324T142446Z
Authorization: AWS4-HMAC-SHA256 Credential=AKIAIOSFODNN7EXAMPLE/20200324/us-east-2/ssm/aws4_request,
SignedHeaders=content-type;host;x-amz-date;x-amz-target, Signature=39c3b3042cd2aEXAMPLE
Content-Length: 151

{
    "Entries": [
        {
            "InstanceId": "i-0471e04240EXAMPLE",
            "Name": "AWS-UpdateSSMAgent"
        },
        {
            "InstanceId": "i-07782c72faEXAMPLE",
            "Name": "AWS-UpdateSSMAgent"
        }
    ]
}

Sample Response


{
    "Failed": [],
    "Successful": [
        {
            "ApplyOnlyAtCronInterval": false,
            "AssociationId": "33858bec-0c55-4547-a054-eb5fcEXAMPLE",
            "AssociationVersion": "1",
            "Date": 1585059887.692,
            "DocumentVersion": "$DEFAULT",
            "InstanceId": "i-0471e04240EXAMPLE",
            "LastUpdateAssociationDate": 1585059887.692,
            "Name": "AWS-UpdateSSMAgent",
            "Overview": {
                "DetailedStatus": "Creating",
                "Status": "Pending"
            },
            "Status": {
                "Date": 1585059887.692,
                "Message": "Associated with AWS-UpdateSSMAgent",
                "Name": "Associated"
            },
            "Targets": [
                {
                    "Key": "InstanceIds",
                    "Values": [
                        "i-0471e04240EXAMPLE"
                    ]
                }
            ]
        },
        {
            "ApplyOnlyAtCronInterval": false,
            "AssociationId": "e0e0a062-3dcb-4b3e-bb2b-d01b4EXAMPLE",
            "AssociationVersion": "1",
            "Date": 1585059887.726,
            "DocumentVersion": "$DEFAULT",
            "InstanceId": "i-07782c72faEXAMPLE",
            "LastUpdateAssociationDate": 1585059887.726,
            "Name": "AWS-UpdateSSMAgent",
            "Overview": {
                "DetailedStatus": "Creating",
                "Status": "Pending"
            },
            "Status": {
                "Date": 1585059887.726,
                "Message": "Associated with AWS-UpdateSSMAgent",
                "Name": "Associated"
            },
            "Targets": [
                {
                    "Key": "InstanceIds",
                    "Values": [
                        "i-07782c72faEXAMPLE"
                    ]
                }
            ]
        }
    ]
}