AWS IoT Things Graph
Welcome (API Version 2018-09-06)

The AWS Documentation website is getting a new look!
Try it now and let us know what you think. Switch to the new look >>

You can return to the original look by selecting English in the language selector above.

CreateSystemInstance

Creates a system instance.

This action validates the system instance, prepares the deployment-related resources. For Greengrass deployments, it updates the Greengrass group that is specified by the greengrassGroupName parameter. It also adds a file to the S3 bucket specified by the s3BucketName parameter. You need to call DeploySystemInstance after running this action.

For Greengrass deployments, since this action modifies and adds resources to a Greengrass group and an S3 bucket on the caller's behalf, the calling identity must have write permissions to both the specified Greengrass group and S3 bucket. Otherwise, the call will fail with an authorization error.

For cloud deployments, this action requires a flowActionsRoleArn value. This is an IAM role that has permissions to access AWS services, such as AWS Lambda and AWS IoT, that the flow uses when it executes.

If the definition document doesn't specify a version of the user's namespace, the latest version will be used by default.

Request Syntax

{ "definition": { "language": "string", "text": "string" }, "flowActionsRoleArn": "string", "greengrassGroupName": "string", "metricsConfiguration": { "cloudMetricEnabled": boolean, "metricRuleRoleArn": "string" }, "s3BucketName": "string", "tags": [ { "key": "string", "value": "string" } ], "target": "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.

definition

A document that defines an entity.

Type: DefinitionDocument object

Required: Yes

flowActionsRoleArn

The ARN of the IAM role that AWS IoT Things Graph will assume when it executes the flow. This role must have read and write access to AWS Lambda and AWS IoT and any other AWS services that the flow uses when it executes. This value is required if the value of the target parameter is CLOUD.

Type: String

Length Constraints: Minimum length of 20. Maximum length of 2048.

Required: No

greengrassGroupName

The name of the Greengrass group where the system instance will be deployed. This value is required if the value of the target parameter is GREENGRASS.

Type: String

Required: No

metricsConfiguration

An object that specifies whether cloud metrics are collected in a deployment and, if so, what role is used to collect metrics.

Type: MetricsConfiguration object

Required: No

s3BucketName

The name of the Amazon Simple Storage Service bucket that will be used to store and deploy the system instance's resource file. This value is required if the value of the target parameter is GREENGRASS.

Type: String

Required: No

tags

Metadata, consisting of key-value pairs, that can be used to categorize your system instances.

Type: Array of Tag objects

Array Members: Minimum number of 0 items. Maximum number of 50 items.

Required: No

target

The target type of the deployment. Valid values are GREENGRASS and CLOUD.

Type: String

Valid Values: GREENGRASS | CLOUD

Required: Yes

Response Syntax

{ "summary": { "arn": "string", "createdAt": number, "greengrassGroupId": "string", "greengrassGroupName": "string", "greengrassGroupVersionId": "string", "id": "string", "status": "string", "target": "string", "updatedAt": number } }

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.

summary

The summary object that describes the new system instance.

Type: SystemInstanceSummary object

Errors

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

InternalFailureException

HTTP Status Code: 500

InvalidRequestException

HTTP Status Code: 400

LimitExceededException

HTTP Status Code: 400

ResourceAlreadyExistsException

HTTP Status Code: 400

ThrottlingException

HTTP Status Code: 400

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the following: