AWS Greengrass - API Reference

153 Pages·2017·0.74 MB·English

by  Amazon Web Services

AWS IoT Greengrass
API Reference, Version 1
AWS IoT Greengrass API Reference, Version 1
AWS IoT Greengrass: API Reference, Version 1
Copyright © 2022 Amazon Web Services, Inc. and/or its affiliates. All rights reserved.
Amazon's trademarks and trade dress may not be used in connection with any product or service that is not
Amazon's, in any manner that is likely to cause confusion among customers, or in any manner that disparages or
discredits Amazon. All other trademarks not owned by Amazon are the property of their respective owners, who may
or may not be affiliated with, connected to, or sponsored by Amazon.
AWS IoT Greengrass API Reference, Version 1
Table of Contents
....................................................................................................................................................... ix
Greengrass V1 API.............................................................................................................................. 1
Actions..................................................................................................................................... 1
AssociateRoleToGroup......................................................................................................... 3
AssociateServiceRoleToAccount............................................................................................ 6
CreateConnectorDefinition................................................................................................... 9
CreateConnectorDefinitionVersion...................................................................................... 13
CreateCoreDefinition......................................................................................................... 17
CreateCoreDefinitionVersion.............................................................................................. 21
CreateDeployment............................................................................................................ 24
CreateDeviceDefinition...................................................................................................... 27
CreateDeviceDefinitionVersion............................................................................................ 31
CreateFunctionDefinition................................................................................................... 34
CreateFunctionDefinitionVersion......................................................................................... 41
CreateGroup.................................................................................................................... 48
CreateGroupCertificateAuthority......................................................................................... 52
CreateGroupVersion.......................................................................................................... 55
CreateLoggerDefinition..................................................................................................... 58
CreateLoggerDefinitionVersion........................................................................................... 62
CreateResourceDefinition................................................................................................... 66
CreateResourceDefinitionVersion........................................................................................ 74
CreateSoftwareUpdateJob................................................................................................. 81
CreateSubscriptionDefinition.............................................................................................. 85
CreateSubscriptionDefinitionVersion................................................................................... 89
DeleteConnectorDefinition................................................................................................. 92
DeleteCoreDefinition......................................................................................................... 94
DeleteDeviceDefinition...................................................................................................... 96
DeleteFunctionDefinition................................................................................................... 98
DeleteGroup.................................................................................................................... 99
DeleteLoggerDefinition.................................................................................................... 101
DeleteResourceDefinition................................................................................................. 103
DeleteSubscriptionDefinition............................................................................................ 104
DisassociateRoleFromGroup............................................................................................. 106
DisassociateServiceRoleFromAccount................................................................................. 109
GetAssociatedRole.......................................................................................................... 110
GetBulkDeploymentStatus............................................................................................... 113
GetConnectivityInfo ........................................................................................................ 116
GetConnectorDefinition................................................................................................... 119
GetConnectorDefinitionVersion......................................................................................... 122
GetCoreDefinition........................................................................................................... 125
GetCoreDefinitionVersion................................................................................................. 128
GetDeploymentStatus..................................................................................................... 131
GetDeviceDefinition........................................................................................................ 134
GetDeviceDefinitionVersion.............................................................................................. 136
GetFunctionDefinition..................................................................................................... 140
GetFunctionDefinitionVersion........................................................................................... 142
GetGroup....................................................................................................................... 149
GetGroupCertificateAuthority........................................................................................... 151
GetGroupCertificateConfiguration..................................................................................... 154
GetGroupVersion............................................................................................................ 157
GetLoggerDefinition........................................................................................................ 160
GetLoggerDefinitionVersion............................................................................................. 163
GetResourceDefinition..................................................................................................... 166
GetResourceDefinitionVersion........................................................................................... 169
iii
AWS IoT Greengrass API Reference, Version 1
GetServiceRoleForAccount............................................................................................... 175
GetSubscriptionDefinition................................................................................................ 177
GetSubscriptionDefinitionVersion...................................................................................... 179
GetThingRuntimeConfiguration........................................................................................ 183
ListBulkDeploymentDetailedReports.................................................................................. 186
ListBulkDeployments....................................................................................................... 190
ListConnectorDefinitionVersions....................................................................................... 192
ListConnectorDefinitions.................................................................................................. 195
ListCoreDefinitionVersions............................................................................................... 197
ListCoreDefinitions.......................................................................................................... 200
ListDeployments............................................................................................................. 202
ListDeviceDefinitionVersions............................................................................................. 205
ListDeviceDefinitions....................................................................................................... 208
ListFunctionDefinitionVersions.......................................................................................... 210
ListFunctionDefinitions.................................................................................................... 213
ListGroupCertificateAuthorities......................................................................................... 215
ListGroupVersions........................................................................................................... 218
ListGroups..................................................................................................................... 221
ListLoggerDefinitionVersions............................................................................................ 223
ListLoggerDefinitions...................................................................................................... 226
ListResourceDefinitionVersions......................................................................................... 228
ListResourceDefinitions.................................................................................................... 231
ListSubscriptionDefinitionVersions.................................................................................... 233
ListSubscriptionDefinitions............................................................................................... 236
ListTagsForResource........................................................................................................ 238
ResetDeployments.......................................................................................................... 240
StartBulkDeployment...................................................................................................... 242
StopBulkDeployment...................................................................................................... 245
TagResource................................................................................................................... 247
UntagResource............................................................................................................... 249
UpdateConnectivityInfo ................................................................................................... 250
UpdateConnectorDefinition.............................................................................................. 254
UpdateCoreDefinition...................................................................................................... 256
UpdateDeviceDefinition................................................................................................... 258
UpdateFunctionDefinition................................................................................................ 260
UpdateGroup................................................................................................................. 262
UpdateGroupCertificateConfiguration................................................................................ 264
UpdateLoggerDefinition.................................................................................................. 268
UpdateResourceDefinition................................................................................................ 270
UpdateSubscriptionDefinition........................................................................................... 272
UpdateThingRuntimeConfiguration................................................................................... 274
Endpoints.............................................................................................................................. 277
/greengrass/bulk/deployments........................................................................................ 278
/greengrass/bulk/deployments/BulkDeploymentId/$stop.................................................... 284
/greengrass/bulk/deployments/BulkDeploymentId/detailed-reports..................................... 286
/greengrass/bulk/deployments/BulkDeploymentId/status................................................... 289
/greengrass/definition/connectors.................................................................................... 293
/greengrass/definition/connectors/ConnectorDefinitionId .................................................... 299
/greengrass/definition/connectors/ConnectorDefinitionId/versions....................................... 306
/greengrass/definition/connectors/ConnectorDefinitionId/versions/
ConnectorDefinitionVersionId ........................................................................................... 312
/greengrass/definition/cores............................................................................................ 316
/greengrass/definition/cores/CoreDefinitionId .................................................................... 322
/greengrass/definition/cores/CoreDefinitionId/versions....................................................... 329
/greengrass/definition/cores/CoreDefinitionId/versions/CoreDefinitionVersionId .................... 335
/greengrass/definition/devices......................................................................................... 338
/greengrass/definition/devices/DeviceDefinitionId.............................................................. 345
iv
AWS IoT Greengrass API Reference, Version 1
/greengrass/definition/devices/DeviceDefinitionId/versions................................................. 351
/greengrass/definition/devices/DeviceDefinitionId/versions/DeviceDefinitionVersionId ............ 358
/greengrass/definition/functions...................................................................................... 361
/greengrass/definition/functions/FunctionDefinitionId........................................................ 371
/greengrass/definition/functions/FunctionDefinitionId/versions........................................... 377
/greengrass/definition/functions/FunctionDefinitionId/versions/FunctionDefinitionVersionId ... 387
/greengrass/definition/loggers......................................................................................... 393
/greengrass/definition/loggers/LoggerDefinitionId............................................................. 400
/greengrass/definition/loggers/LoggerDefinitionId/versions................................................. 406
/greengrass/definition/loggers/LoggerDefinitionId/versions/LoggerDefinitionVersionId ........... 413
/greengrass/definition/resources...................................................................................... 416
/greengrass/definition/resources/ResourceDefinitionId ........................................................ 426
/greengrass/definition/resources/ResourceDefinitionId/versions........................................... 433
/greengrass/definition/resources/ResourceDefinitionId/versions/ResourceDefinitionVersionId .. 443
/greengrass/definition/subscriptions................................................................................. 450
/greengrass/definition/subscriptions/SubscriptionDefinitionId.............................................. 456
/greengrass/definition/subscriptions/SubscriptionDefinitionId/versions................................. 463
/greengrass/definition/subscriptions/SubscriptionDefinitionId/versions/
SubscriptionDefinitionVersionId........................................................................................ 469
/greengrass/groups......................................................................................................... 473
/greengrass/groups/GroupId ............................................................................................ 479
/greengrass/groups/GroupId/certificateauthorities............................................................. 486
/greengrass/groups/GroupId/certificateauthorities/configuration/expiry............................... 492
/greengrass/groups/GroupId/certificateauthorities/CertificateAuthorityId.............................. 498
/greengrass/groups/GroupId/deployments........................................................................ 501
/greengrass/groups/GroupId/deployments/$reset.............................................................. 507
/greengrass/groups/GroupId/deployments/DeploymentId/status......................................... 509
/greengrass/groups/GroupId/role..................................................................................... 512
/greengrass/groups/GroupId/versions............................................................................... 521
/greengrass/groups/GroupId/versions/GroupVersionId........................................................ 527
/greengrass/servicerole................................................................................................... 530
/greengrass/things/ThingName/connectivityInfo................................................................ 538
/greengrass/things/ThingName/runtimeconfig................................................................... 545
/greengrass/updates....................................................................................................... 550
/tags/resource-arn.......................................................................................................... 554
Parameters............................................................................................................................ 560
AssociateRoleToGroupRequestBody................................................................................... 561
AssociateServiceRoleToAccountRequestBody...................................................................... 562
BulkDeploymentId.......................................................................................................... 562
CertificateAuthorityId...................................................................................................... 562
ConnectorDefinitionId..................................................................................................... 563
ConnectorDefinitionVersionId ........................................................................................... 563
CoreDefinitionId ............................................................................................................. 563
CoreDefinitionVersionId................................................................................................... 564
CreateConnectorDefinitionRequestBody............................................................................. 564
CreateConnectorDefinitionVersionRequestBody.................................................................. 565
CreateCoreDefinitionRequestBody..................................................................................... 566
CreateCoreDefinitionVersionRequestBody.......................................................................... 566
CreateDeploymentRequestBody........................................................................................ 567
CreateDeviceDefinitionRequestBody.................................................................................. 568
CreateDeviceDefinitionVersionRequestBody........................................................................ 569
CreateFunctionDefinitionRequestBody............................................................................... 570
CreateFunctionDefinitionVersionRequestBody..................................................................... 571
CreateGroupRequestBody................................................................................................ 575
CreateGroupVersionRequestBody...................................................................................... 575
CreateLoggerDefinitionRequestBody................................................................................. 576
CreateLoggerDefinitionVersionRequestBody....................................................................... 577
v
AWS IoT Greengrass API Reference, Version 1
CreateResourceDefinitionRequestBody............................................................................... 578
CreateResourceDefinitionVersionRequestBody.................................................................... 579
CreateSoftwareUpdateJobRequestBody............................................................................. 584
CreateSubscriptionDefinitionRequestBody.......................................................................... 585
CreateSubscriptionDefinitionVersionRequestBody............................................................... 585
DeploymentId................................................................................................................ 587
DeviceDefinitionId........................................................................................................... 587
DeviceDefinitionVersionId................................................................................................ 587
FunctionDefinitionId........................................................................................................ 588
FunctionDefinitionVersionId ............................................................................................. 588
GroupId ......................................................................................................................... 588
GroupVersionId ............................................................................................................... 589
LoggerDefinitionId.......................................................................................................... 589
LoggerDefinitionVersionId................................................................................................ 589
MaxResults..................................................................................................................... 590
NextToken..................................................................................................................... 590
ResetDeploymentsRequestBody........................................................................................ 590
ResourceArn................................................................................................................... 591
ResourceDefinitionId ....................................................................................................... 591
ResourceDefinitionVersionId............................................................................................. 591
RuntimeConfigurationUpdateRequestBody......................................................................... 592
StartBulkDeploymentRequestBody.................................................................................... 592
SubscriptionDefinitionId.................................................................................................. 593
SubscriptionDefinitionVersionId........................................................................................ 594
tags.............................................................................................................................. 594
ThingName.................................................................................................................... 594
TagKeys......................................................................................................................... 595
UpdateConnectivityInfoRequestBody................................................................................. 595
UpdateDefinitionRequestBody.......................................................................................... 596
UpdateGroupCertificateConfigurationRequestBody.............................................................. 596
X-Amzn-Client-Token...................................................................................................... 597
Definitions............................................................................................................................. 597
AssociateRoleToGroupRequest.......................................................................................... 599
AssociateServiceRoleToAccountRequest............................................................................. 600
AssociateServiceRoleToAccountResponse........................................................................... 600
BulkDeployment............................................................................................................. 600
BulkDeploymentMetrics................................................................................................... 601
BulkDeploymentResult.................................................................................................... 601
BulkDeploymentResults................................................................................................... 603
BulkDeploymentStatus.................................................................................................... 604
BulkDeployments............................................................................................................ 605
ConnectivityInfo............................................................................................................. 605
Connector...................................................................................................................... 606
ConnectorDefinitionVersion.............................................................................................. 607
Core.............................................................................................................................. 608
CoreDefinitionVersion...................................................................................................... 608
CreateDeploymentRequest............................................................................................... 609
CreateDeploymentResponse............................................................................................. 610
CreateGroupCertificateAuthorityResponse.......................................................................... 610
CreateSoftwareUpdateJobRequest.................................................................................... 610
CreateSoftwareUpdateJobResponse.................................................................................. 611
DefinitionInformation...................................................................................................... 612
Deployment................................................................................................................... 613
DeploymentType............................................................................................................ 614
Deployments.................................................................................................................. 614
Device........................................................................................................................... 615
DeviceDefinitionVersion................................................................................................... 616
vi
AWS IoT Greengrass API Reference, Version 1
DisassociateRoleFromGroupResponse................................................................................ 617
DisassociateServiceRoleFromAccountResponse.................................................................... 617
Empty Schema............................................................................................................... 617
ErrorDetail..................................................................................................................... 617
ErrorDetails.................................................................................................................... 618
Function........................................................................................................................ 618
FunctionConfiguration..................................................................................................... 621
FunctionConfigurationEnvironment................................................................................... 624
FunctionDefaultConfig ..................................................................................................... 626
FunctionDefaultExecutionConfig....................................................................................... 626
FunctionDefinitionVersion................................................................................................ 627
FunctionExecutionConfig................................................................................................. 631
FunctionIsolationMode.................................................................................................... 632
FunctionRunAsConfig...................................................................................................... 632
GeneralError.................................................................................................................. 632
GetAssociatedRoleResponse............................................................................................. 633
GetBulkDeploymentStatusResponse.................................................................................. 634
GetConnectivityInfoResponse........................................................................................... 635
GetConnectorDefinitionVersionResponse............................................................................ 636
GetCoreDefinitionVersionResponse.................................................................................... 638
GetDeploymentStatusResponse........................................................................................ 639
GetDeviceDefinitionVersionResponse................................................................................. 641
GetFunctionDefinitionVersionResponse.............................................................................. 642
GetGroupCertificateAuthorityResponse.............................................................................. 646
GetGroupVersionResponse............................................................................................... 647
GetLoggerDefinitionVersionResponse................................................................................ 648
GetResourceDefinitionVersionResponse.............................................................................. 650
GetServiceRoleForAccountResponse.................................................................................. 655
GetSubscriptionDefinitionVersionResponse......................................................................... 655
GetThingRuntimeConfigurationResponse........................................................................... 657
Group............................................................................................................................ 657
Group Certificate Authority Properties .............................................................................. 658
GroupCertificateConfiguration.......................................................................................... 658
GroupInformation........................................................................................................... 659
GroupOwnerSetting ........................................................................................................ 660
GroupVersion................................................................................................................. 660
IDList............................................................................................................................ 661
ListBulkDeploymentDetailedReportsResponse.................................................................... 661
ListBulkDeploymentsResponse.......................................................................................... 663
ListDefinitionsResponse................................................................................................... 664
ListDeploymentsRequest.................................................................................................. 665
ListDeploymentsResponse................................................................................................ 666
ListGroupCertificateAuthoritiesResponse............................................................................ 667
ListGroupsResponse........................................................................................................ 668
ListVersionsResponse...................................................................................................... 669
LocalDeviceResourceData................................................................................................. 670
LocalVolumeResourceData............................................................................................... 671
Logger.......................................................................................................................... 671
LoggerComponent.......................................................................................................... 672
LoggerDefinitionVersion.................................................................................................. 672
LoggerLevel ................................................................................................................... 673
LoggerType.................................................................................................................... 674
Permission..................................................................................................................... 674
ResetDeploymentsRequest............................................................................................... 674
ResetDeploymentsResponse............................................................................................. 674
Resource........................................................................................................................ 675
ResourceAccessPolicy...................................................................................................... 679
vii
AWS IoT Greengrass API Reference, Version 1
ResourceDataContainer.................................................................................................... 679
ResourceDefinitionVersion................................................................................................ 683
ResourceDownloadOwnerSetting ...................................................................................... 687
RuntimeConfiguration..................................................................................................... 688
RuntimeConfigurationUpdate........................................................................................... 688
S3MachineLearningModelResourceData............................................................................. 689
S3UrlSignerRole............................................................................................................. 690
SageMakerMachineLearningModelResourceData................................................................. 690
SecretsManagerSecretResourceData.................................................................................. 691
SoftwareToUpdate.......................................................................................................... 691
StartBulkDeploymentRequest........................................................................................... 691
StartBulkDeploymentResponse......................................................................................... 692
Subscription................................................................................................................... 693
SubscriptionDefinitionVersion........................................................................................... 693
TelemetryConfiguration................................................................................................... 694
TelemetryConfigurationUpdate......................................................................................... 695
UpdateAgentLogLevel ..................................................................................................... 695
UpdateConnectivityInfoRequest........................................................................................ 696
UpdateConnectivityInfoResponse...................................................................................... 696
UpdateTargets................................................................................................................ 697
UpdateTargetsArchitecture............................................................................................... 697
UpdateTargetsOperatingSystem....................................................................................... 697
VersionInformation......................................................................................................... 697
Versions........................................................................................................................ 698
tags.............................................................................................................................. 699
updateGroupCertificateConfigurationRequest..................................................................... 699
viii
AWS IoT Greengrass API Reference, Version 1
AWS IoT Greengrass Version 1 no longer receives feature updates, and will receive only security patches
and bug fixes until June 30, 2023. For more information, see the AWS IoT Greengrass V1 maintenance
policy. We strongly recommend that you migrate to AWS IoT Greengrass Version 2, which adds
significant new features and support for additional platforms.
ix
AWS IoT Greengrass API Reference, Version 1
Actions
Greengrass V1 API
AWS IoT Greengrass provides a resource-based API that uses Hypertext Application Language (HAL). HAL
provides a standard way for expressing the resources and relationships of an API as hyperlinks. Using
HAL, you use HTTP methods (GET, PUT, POST, DELETE) to submit requests and receive information about
the API in the response. Applications can use the information returned to explore the functionality of the
API. For more information about HAL, see the JSON Hypertext Application Language draft.
To request a HAL response from AWS IoT Greengrass, specify application/hal+json for the accept request
header.
For more information about how AWS IoT Greengrass works, see the AWS IoT Greengrass Version 1
Developer Guide.
Contents
• Actions (p. 1)
• Endpoints (p. 277)
• Parameters (p. 560)
• Definitions (p. 597)
Actions
The following actions are supported:
• AssociateRoleToGroup (p. 3)
• AssociateServiceRoleToAccount (p. 6)
• CreateConnectorDefinition (p. 9)
• CreateConnectorDefinitionVersion (p. 13)
• CreateCoreDefinition (p. 17)
• CreateCoreDefinitionVersion (p. 21)
• CreateDeployment (p. 24)
• CreateDeviceDefinition (p. 27)
• CreateDeviceDefinitionVersion (p. 31)
• CreateFunctionDefinition (p. 34)
• CreateFunctionDefinitionVersion (p. 41)
• CreateGroup (p. 48)
• CreateGroupCertificateAuthority (p. 52)
• CreateGroupVersion (p. 55)
• CreateLoggerDefinition (p. 58)
• CreateLoggerDefinitionVersion (p. 62)
• CreateResourceDefinition (p. 66)
• CreateResourceDefinitionVersion (p. 74)
• CreateSoftwareUpdateJob (p. 81)
• CreateSubscriptionDefinition (p. 85)
• CreateSubscriptionDefinitionVersion (p. 89)
1