aws iot - 开发人员指南 · pdf fileaws iot 开发人员指南创建 aws iot 规则

AWS IoT开发人员指南

AWS IoT 开发人员指南

AWS IoT: 开发人员指南Copyright © 2018 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 mannerthat is likely to cause confusion among customers, or in any manner that disparages or discredits Amazon. All other trademarks notowned by Amazon are the property of their respective owners, who may or may not be affiliated with, connected to, or sponsored byAmazon.


Table of Contents什么是 AWS IoT？ .............................................................................................................................. 1

AWS IoT 的组件 ......................................................................................................................... 1如何开始使用 AWS IoT ................................................................................................................ 2访问 AWS IoT ............................................................................................................................ 2相关服务 .................................................................................................................................... 2AWS IoT 的工作原理 ................................................................................................................... 3

AWS IoT 入门 .................................................................................................................................... 4登录 AWS IoT 控制台 ................................................................................................................. 4在 Registry 中注册设备 ................................................................................................................ 5创建并激活设备证书 .................................................................................................................... 7创建 AWS IoT 策略 ..................................................................................................................... 9将 AWS IoT 策略附加到设备证书 ................................................................................................. 11将证书附加到事物 ...................................................................................................................... 13配置您的设备 ............................................................................................................................ 16

配置 AWS IoT 按钮。 ........................................................................................................ 16配置不同的设备 ................................................................................................................. 17

使用 AWS IoT MQTT 客户端查看设备 MQTT 消息 ......................................................................... 17配置并测试规则 ......................................................................................................................... 20

创建一个 SNS 主题 ........................................................................................................... 20订阅 Amazon SNS 主题 ..................................................................................................... 22创建规则 .......................................................................................................................... 22测试 Amazon SNS 规则 ..................................................................................................... 28后续步骤 .......................................................................................................................... 29

AWS IoT 按钮快速入门 ...................................................................................................................... 30AWS IoT 按钮向导快速入门 ........................................................................................................ 30AWS IoT 按钮 AWS CloudFormation 快速入门 .............................................................................. 39后续步骤 .................................................................................................................................. 44

AWS IoT 规则教程 ............................................................................................................................ 45创建 DynamoDB 规则 ................................................................................................................ 45创建 Lambda 规则 .................................................................................................................... 53

创建 Lambda 函数 ............................................................................................................ 53测试您的 Lambda 函数 ...................................................................................................... 61创建 Lambda 规则 ............................................................................................................ 63测试您的 Lambda 规则 ...................................................................................................... 66

创建 Amazon SNS 规则 ............................................................................................................. 68AWS IoT 软件开发工具包教程 ............................................................................................................. 76

连接您的 Raspberry Pi ............................................................................................................... 76先决条件 .......................................................................................................................... 76登录 AWS IoT 控制台 ........................................................................................................ 76创建并附加事物（设备） .................................................................................................... 78

使用 AWS IoT 嵌入式 C 软件开发工具包 ...................................................................................... 85设置适用于 AWS IoT 嵌入式 C 软件开发工具包的运行时环境 ................................................... 85示例应用程序配置 .............................................................................................................. 85运行示例应用程序 .............................................................................................................. 86

使用适用于 JavaScript 的 AWS IoT 设备软件开发工具包 ................................................................. 87设置适用于 JavaScript 的 AWS IoT 设备软件开发工具包的运行时环境 ....................................... 88安装适用于 JavaScript 的 AWS IoT 设备软件开发工具包 ......................................................... 89准备运行示例应用程序 ....................................................................................................... 89运行示例应用程序 .............................................................................................................. 89

使用 AWS IoT 管理设备 ..................................................................................................................... 91如何使用注册表管理事物 ............................................................................................................ 91

创建事物 .......................................................................................................................... 91列出事物 .......................................................................................................................... 92搜索事物 .......................................................................................................................... 92

iii


更新事物 .......................................................................................................................... 93删除事物 .......................................................................................................................... 94将委托人附加到事物 .......................................................................................................... 94将委托人与事物分离 .......................................................................................................... 94

事物类型 .................................................................................................................................. 94创建事物类型 .................................................................................................................... 95列出事物类型 .................................................................................................................... 95描述事物类型 .................................................................................................................... 95将事物类型与事物相关联 .................................................................................................... 96弃用事物类型 .................................................................................................................... 96删除事物类型 .................................................................................................................... 97

事物组 ..................................................................................................................................... 97创建事物组 ....................................................................................................................... 98描述事物组 ....................................................................................................................... 99将事物添加到事物组 .......................................................................................................... 99从事物组中删除此事物 ....................................................................................................... 99列出事物组中的事物 ......................................................................................................... 100列出事物组 ..................................................................................................................... 100列出事物的组 .................................................................................................................. 102更新事物组 ..................................................................................................................... 102删除事物组 ..................................................................................................................... 102将策略附加到事物组 ......................................................................................................... 103从事物组分离策略 ............................................................................................................ 103列出附加到事物组的策略 ................................................................................................... 103列出策略的组 .................................................................................................................. 104获取事物的有效策略 ......................................................................................................... 104测试 MQTT 操作的授权 .................................................................................................... 104

安全和身份 ..................................................................................................................................... 106AWS IoT 身份验证 .................................................................................................................. 106

X.509 证书 ..................................................................................................................... 106IAM 用户、组和角色 ........................................................................................................ 112Amazon Cognito 身份 ...................................................................................................... 113

自定义身份验证 ....................................................................................................................... 113自定义授权方 .................................................................................................................. 113配置自定义授权方 ............................................................................................................ 115自定义授权方工作流 ......................................................................................................... 116

授权 ...................................................................................................................................... 117AWS IoT 策略 ................................................................................................................ 118IAM IoT 策略 .................................................................................................................. 137

授予直接调用 AWS 服务的权限 ................................................................................................. 144跨账户访问 ............................................................................................................................. 145传输安全 ................................................................................................................................ 145

TLS 密码包支持 .............................................................................................................. 146消息代理 ........................................................................................................................................ 147

协议 ...................................................................................................................................... 147协议/端口映射 ................................................................................................................. 147MQTT ............................................................................................................................ 147HTTP ............................................................................................................................ 148基于 WebSocket 的 MQTT 协议 ........................................................................................ 149

主题： ................................................................................................................................... 152预留的主题 ..................................................................................................................... 152

生命周期事件 .......................................................................................................................... 154连接/断开连接事件 ........................................................................................................... 155订阅/取消订阅事件 ........................................................................................................... 155

规则 .............................................................................................................................................. 157授予 AWS IoT 所需的访问权限 .................................................................................................. 157传递角色权限 .......................................................................................................................... 159

iv


创建 AWS IoT 规则 ................................................................................................................. 159查看您的规则 .......................................................................................................................... 162SQL 版本 ............................................................................................................................... 163

2016-03-23 SQL 规则引擎版本中的新增功能 ........................................................................ 163排查规则问题 .......................................................................................................................... 164规则错误处理 .......................................................................................................................... 164

错误操作消息格式 ............................................................................................................ 165错误操作示例 .................................................................................................................. 166

删除规则 ................................................................................................................................ 166AWS IoT 规则操作 .................................................................................................................. 166

CloudWatch 警报操作 ...................................................................................................... 167CloudWatch 指标操作 ...................................................................................................... 168DynamoDB 操作 ............................................................................................................. 168DynamoDBv2 操作 .......................................................................................................... 170Amazon ES 操作 ............................................................................................................. 170Firehose 操作 ................................................................................................................. 171Kinesis 操作 ................................................................................................................... 172Lambda 操作 .................................................................................................................. 172Republish 操作 ............................................................................................................... 173S3 操作 ......................................................................................................................... 174SNS 操作 ....................................................................................................................... 175SQS 操作 ....................................................................................................................... 175Salesforce 操作 ............................................................................................................... 176

AWS IoT SQL 参考 ................................................................................................................. 177数据类型 ........................................................................................................................ 177运算符 ........................................................................................................................... 180函数 .............................................................................................................................. 185SELECT 语句 ................................................................................................................. 215FROM 子句 .................................................................................................................... 216WHERE 子句 .................................................................................................................. 217文本 .............................................................................................................................. 218Case 语句 ...................................................................................................................... 218JSON 扩展 ..................................................................................................................... 218替换模板 ........................................................................................................................ 219

Device Shadow 服务 ....................................................................................................................... 221Device Shadow 服务数据流 ...................................................................................................... 221

检测事物是否已连接 ......................................................................................................... 227Device Shadow 服务文档 ......................................................................................................... 228

文档属性 ........................................................................................................................ 228Device Shadow 的版本控制 .............................................................................................. 229客户端令牌 ..................................................................................................................... 229示例文档 ........................................................................................................................ 229空白部分 ........................................................................................................................ 230数组 .............................................................................................................................. 230

使用影子 ................................................................................................................................ 231协议支持 ........................................................................................................................ 231更新影子 ........................................................................................................................ 231检索影子文档 .................................................................................................................. 232删除数据 ........................................................................................................................ 235删除影子 ........................................................................................................................ 236增量状态 ........................................................................................................................ 236观察状态更改 .................................................................................................................. 238消息顺序 ........................................................................................................................ 238修剪影子消息 .................................................................................................................. 239

RESTful API ........................................................................................................................... 239GetThingShadow ............................................................................................................. 240UpdateThingShadow ........................................................................................................ 240

v


DeleteThingShadow ......................................................................................................... 241MQTT 发布/订阅主题 ............................................................................................................... 242

/更新 ............................................................................................................................. 242/update/accepted ............................................................................................................. 243/update/documents .......................................................................................................... 243/update/rejected .............................................................................................................. 244/update/delta ................................................................................................................... 244/get ............................................................................................................................... 245/get/accepted .................................................................................................................. 245/get/rejected .................................................................................................................... 246/delete ........................................................................................................................... 246/delete/accepted .............................................................................................................. 247/delete/rejected ............................................................................................................... 247

文档语法 ................................................................................................................................ 248请求状态文档 .................................................................................................................. 248响应状态文档 .................................................................................................................. 248错误响应文档 .................................................................................................................. 249

错误消息 ................................................................................................................................ 250工作 .............................................................................................................................................. 251

Jobs 关键概念 ........................................................................................................................ 251管理任务 ................................................................................................................................ 252

创建任务 ........................................................................................................................ 252取消任务 ........................................................................................................................ 253获取任务文档 .................................................................................................................. 253列出任务 ........................................................................................................................ 254描述任务 ........................................................................................................................ 255列出任务的执行 ............................................................................................................... 255列出事物的任务执行 ......................................................................................................... 256描述任务执行 .................................................................................................................. 257任务事件 ........................................................................................................................ 257

设备和任务 ............................................................................................................................. 260对设备进行编程以使用 Jobs .............................................................................................. 262

使用 AWS IoT Jobs API ........................................................................................................... 265任务管理和控制 API ......................................................................................................... 266Jobs 设备 MQTT 和 HTTPS API ....................................................................................... 297

任务限制 ................................................................................................................................ 318设备预配置 ..................................................................................................................................... 319

预配置模板 ............................................................................................................................. 319参数部分 ........................................................................................................................ 319资源部分 ........................................................................................................................ 319模板示例 ........................................................................................................................ 322

以编程方式预配置 .................................................................................................................... 323即时预配置 ............................................................................................................................. 323批量配置 ................................................................................................................................ 324

机群索引服务 .................................................................................................................................. 325管理索引 ................................................................................................................................ 325

启用索引 ........................................................................................................................ 325描述索引 ........................................................................................................................ 326什么是编制索引 ............................................................................................................... 326查询索引 ........................................................................................................................ 327查询语法 ........................................................................................................................ 328示例查询 ........................................................................................................................ 329授权 .............................................................................................................................. 330

AWS IoT 事件 ................................................................................................................................ 331注册表事件 ............................................................................................................................. 331任务事件 ................................................................................................................................ 337

AWS IoT 软件开发工具包 ................................................................................................................. 340

vi


适用于 Android 的 AWS 移动软件开发工具包 ............................................................................... 340Arduino Yún 软件开发工具包 ..................................................................................................... 340适用于嵌入式 C 的 AWS IoT 设备软件开发工具包 ........................................................................ 340AWS IoT C++ 设备开发工具包 .................................................................................................. 341适用于 iOS 的 AWS 移动软件开发工具包 .................................................................................... 341适用于 Java 的 AWS IoT 设备软件开发工具包 ............................................................................. 341适用于 JavaScript 的 AWS IoT 设备软件开发工具包 ...................................................................... 341适用于 Python 的 AWS IoT 设备软件开发工具包 .......................................................................... 341

监控 .............................................................................................................................................. 342监控工具 ................................................................................................................................ 342

自动化工具 ..................................................................................................................... 342手动工具 ........................................................................................................................ 343

使用 Amazon CloudWatch 进行监控 ........................................................................................... 343指标与维度 ..................................................................................................................... 344使用 AWS IoT 指标 ......................................................................................................... 349创建 CloudWatch 警报 ..................................................................................................... 349

使用 AWS CloudTrail 记录 AWS IoT API 调用 ............................................................................. 351CloudTrail 中的 AWS IoT 信息 .......................................................................................... 351了解 AWS IoT 日志文件条目 ............................................................................................. 352

故障排除 ........................................................................................................................................ 354诊断连接问题 .......................................................................................................................... 354

身份验证 ........................................................................................................................ 354授权 .............................................................................................................................. 354

使用 AWS IoT 设置 CloudWatch Logs ........................................................................................ 354创建日志记录角色 ............................................................................................................ 355日志级别 ........................................................................................................................ 355配置 AWS IoT 日志记录 ................................................................................................... 356CloudWatch 日志条目格式 ................................................................................................ 357查看日志 ........................................................................................................................ 370诊断规则问题 .................................................................................................................. 370

诊断 Shadows 问题 ................................................................................................................. 371诊断 Salesforce 操作问题 ......................................................................................................... 372

执行跟踪 ........................................................................................................................ 372操作成功和失败 ............................................................................................................... 372

AWS IoT 错误 ........................................................................................................................ 373IoT 命令 ....................................................................................................................................... 374

AcceptCertificateTransfer ......................................................................................................... 377CLI .............................................................................................................................. 378

AddThingToThingGroup .......................................................................................................... 378CLI .............................................................................................................................. 379

AssociateTargetsWithJob ........................................................................................................ 380CLI .............................................................................................................................. 382

AttachPolicy .......................................................................................................................... 383CLI .............................................................................................................................. 384

AttachPrincipalPolicy ............................................................................................................... 385CLI .............................................................................................................................. 386

AttachThingPrincipal ............................................................................................................... 386CLI .............................................................................................................................. 387

CancelCertificateTransfer ........................................................................................................ 388CLI .............................................................................................................................. 389

CancelJob ............................................................................................................................. 389CLI .............................................................................................................................. 391

ClearDefaultAuthorizer ............................................................................................................ 392CLI .............................................................................................................................. 392

CreateAuthorizer .................................................................................................................... 393CLI .............................................................................................................................. 394

CreateCertificateFromCsr ........................................................................................................ 396

vii


CLI .............................................................................................................................. 398CreateJob ............................................................................................................................. 399

CLI .............................................................................................................................. 401CreateKeysAndCertificate ........................................................................................................ 403

CLI .............................................................................................................................. 405CreateOTAUpdate .................................................................................................................. 406

CLI .............................................................................................................................. 409CreatePolicy .......................................................................................................................... 412

CLI .............................................................................................................................. 414CreatePolicyVersion ............................................................................................................... 415

CLI .............................................................................................................................. 417CreateRoleAlias ..................................................................................................................... 418

CLI .............................................................................................................................. 420CreateStream ........................................................................................................................ 421

CLI .............................................................................................................................. 423CreateThing .......................................................................................................................... 424

CLI .............................................................................................................................. 426CreateThingGroup .................................................................................................................. 428

CLI .............................................................................................................................. 429CreateThingType ................................................................................................................... 431

CLI .............................................................................................................................. 433CreateTopicRule .................................................................................................................... 434

CLI .............................................................................................................................. 438DeleteAuthorizer .................................................................................................................... 448

CLI .............................................................................................................................. 449DeleteCACertificate ................................................................................................................ 450

CLI .............................................................................................................................. 451DeleteCertificate ..................................................................................................................... 452

CLI .............................................................................................................................. 453DeleteOTAUpdate .................................................................................................................. 453

CLI .............................................................................................................................. 454DeletePolicy .......................................................................................................................... 455

CLI .............................................................................................................................. 456DeletePolicyVersion ................................................................................................................ 456

CLI .............................................................................................................................. 457DeleteRegistrationCode ........................................................................................................... 458

CLI .............................................................................................................................. 459DeleteRoleAlias ..................................................................................................................... 459

CLI .............................................................................................................................. 460DeleteStream ........................................................................................................................ 461

CLI .............................................................................................................................. 462DeleteThing ........................................................................................................................... 462

CLI .............................................................................................................................. 463DeleteThingGroup .................................................................................................................. 464

CLI .............................................................................................................................. 465DeleteThingShadow ................................................................................................................ 465

CLI .............................................................................................................................. 467DeleteThingType .................................................................................................................... 467

CLI .............................................................................................................................. 468DeleteTopicRule ..................................................................................................................... 469

CLI .............................................................................................................................. 470DeleteV2LoggingLevel ............................................................................................................ 470

CLI .............................................................................................................................. 471DeprecateThingType ............................................................................................................... 472

CLI .............................................................................................................................. 473DescribeAuthorizer ................................................................................................................. 473

CLI .............................................................................................................................. 475

viii


DescribeCACertificate ............................................................................................................. 476CLI .............................................................................................................................. 478

DescribeCertificate ................................................................................................................. 479CLI .............................................................................................................................. 481

DescribeDefaultAuthorizer ....................................................................................................... 483CLI .............................................................................................................................. 484

DescribeEndpoint ................................................................................................................... 485CLI .............................................................................................................................. 486

DescribeEventConfigurations .................................................................................................... 487CLI .............................................................................................................................. 488

DescribeIndex ........................................................................................................................ 489CLI .............................................................................................................................. 490

DescribeJob .......................................................................................................................... 491CLI .............................................................................................................................. 493

DescribeJobExecution ............................................................................................................. 496CLI .............................................................................................................................. 498

DescribeJobExecution ............................................................................................................. 500CLI .............................................................................................................................. 501

DescribeRoleAlias .................................................................................................................. 503CLI .............................................................................................................................. 505

DescribeStream ..................................................................................................................... 506CLI .............................................................................................................................. 507

DescribeThing ....................................................................................................................... 509CLI .............................................................................................................................. 511

DescribeThingGroup ............................................................................................................... 512CLI .............................................................................................................................. 514

DescribeThingRegistrationTask ................................................................................................ 516CLI .............................................................................................................................. 518

DescribeThingType ................................................................................................................. 519CLI .............................................................................................................................. 521

DetachPolicy ......................................................................................................................... 522CLI .............................................................................................................................. 523

DetachPrincipalPolicy .............................................................................................................. 524CLI .............................................................................................................................. 525

DetachThingPrincipal .............................................................................................................. 526CLI .............................................................................................................................. 527

DisableTopicRule ................................................................................................................... 527CLI .............................................................................................................................. 528

EnableTopicRule .................................................................................................................... 529CLI .............................................................................................................................. 529

GetEffectivePolicies ................................................................................................................ 530CLI .............................................................................................................................. 531

GetIndexingConfiguration ........................................................................................................ 533CLI .............................................................................................................................. 534

GetJobDocument ................................................................................................................... 534CLI .............................................................................................................................. 535

GetLoggingOptions ................................................................................................................. 536CLI .............................................................................................................................. 537

GetOTAUpdate ...................................................................................................................... 537CLI .............................................................................................................................. 539

GetPendingJobExecutions ....................................................................................................... 544CLI .............................................................................................................................. 545

GetPolicy .............................................................................................................................. 547CLI .............................................................................................................................. 548

GetPolicyVersion .................................................................................................................... 549CLI .............................................................................................................................. 551

GetRegistrationCode ............................................................................................................... 552

ix


CLI .............................................................................................................................. 553GetThingShadow ................................................................................................................... 553

CLI .............................................................................................................................. 554GetTopicRule ........................................................................................................................ 555

CLI .............................................................................................................................. 559GetV2LoggingOptions ............................................................................................................. 569

CLI .............................................................................................................................. 570ListAttachedPolicies ................................................................................................................ 571

CLI .............................................................................................................................. 573ListAuthorizers ....................................................................................................................... 574

CLI .............................................................................................................................. 575ListCACertificates ................................................................................................................... 577

CLI .............................................................................................................................. 578ListCertificates ....................................................................................................................... 579

CLI .............................................................................................................................. 581ListCertificatesByCA ............................................................................................................... 582

CLI .............................................................................................................................. 584ListIndices ............................................................................................................................. 585

CLI .............................................................................................................................. 587ListJobExecutionsForJob ......................................................................................................... 588

CLI .............................................................................................................................. 589ListJobExecutionsForThing ...................................................................................................... 591

CLI .............................................................................................................................. 592ListJobs ................................................................................................................................ 594

CLI .............................................................................................................................. 596ListOTAUpdates ..................................................................................................................... 599

CLI .............................................................................................................................. 600ListOutgoingCertificates ........................................................................................................... 601

CLI .............................................................................................................................. 602ListPolicies ............................................................................................................................ 604

CLI .............................................................................................................................. 605ListPolicyPrincipals ................................................................................................................. 606

CLI .............................................................................................................................. 608ListPolicyVersions .................................................................................................................. 609

CLI .............................................................................................................................. 610ListPrincipalPolicies ................................................................................................................ 611

CLI .............................................................................................................................. 613ListPrincipalThings ................................................................................................................. 614

CLI .............................................................................................................................. 615ListRoleAliases ...................................................................................................................... 616

CLI .............................................................................................................................. 618ListStreams ........................................................................................................................... 619

CLI .............................................................................................................................. 620ListTargetsForPolicy ............................................................................................................... 622

CLI .............................................................................................................................. 623ListThingGroups ..................................................................................................................... 624

CLI .............................................................................................................................. 626ListThingGroupsForThing ........................................................................................................ 627

CLI .............................................................................................................................. 628ListThingPrincipals ................................................................................................................. 629

CLI .............................................................................................................................. 631ListThingRegistrationTaskReports ............................................................................................. 631

CLI .............................................................................................................................. 633ListThingRegistrationTasks ...................................................................................................... 634

CLI .............................................................................................................................. 635ListThingTypes ...................................................................................................................... 636

CLI .............................................................................................................................. 638

x


ListThings ............................................................................................................................. 640CLI .............................................................................................................................. 641

ListThingsInThingGroup ........................................................................................................... 643CLI .............................................................................................................................. 645

ListTopicRules ....................................................................................................................... 646CLI .............................................................................................................................. 647

ListV2LoggingLevels ............................................................................................................... 648CLI .............................................................................................................................. 650

发布 ..................................................................................................................................... 651CLI .............................................................................................................................. 652

RegisterCACertificate .............................................................................................................. 653CLI .............................................................................................................................. 655

RegisterCertificate .................................................................................................................. 656CLI .............................................................................................................................. 658

RegisterThing ........................................................................................................................ 659CLI .............................................................................................................................. 661

RejectCertificateTransfer ......................................................................................................... 662CLI .............................................................................................................................. 663

RemoveThingFromThingGroup ................................................................................................. 664CLI .............................................................................................................................. 665

ReplaceTopicRule .................................................................................................................. 665CLI .............................................................................................................................. 669

SearchIndex .......................................................................................................................... 679CLI .............................................................................................................................. 681

SetDefaultAuthorizer ............................................................................................................... 683CLI .............................................................................................................................. 685

SetDefaultPolicyVersion .......................................................................................................... 686CLI .............................................................................................................................. 686

SetLoggingOptions ................................................................................................................. 687CLI .............................................................................................................................. 688

SetV2LoggingLevel ................................................................................................................. 689CLI .............................................................................................................................. 689

SetV2LoggingOptions ............................................................................................................. 690CLI .............................................................................................................................. 691

StartNextPendingJobExecution ................................................................................................. 692CLI .............................................................................................................................. 693

StartThingRegistrationTask ...................................................................................................... 696CLI .............................................................................................................................. 697

StopThingRegistrationTask ...................................................................................................... 698CLI .............................................................................................................................. 699

TestAuthorization ................................................................................................................... 699CLI .............................................................................................................................. 702

TestInvokeAuthorizer .............................................................................................................. 706CLI .............................................................................................................................. 708

TransferCertificate .................................................................................................................. 709CLI .............................................................................................................................. 711

UpdateAuthorizer ................................................................................................................... 712CLI .............................................................................................................................. 713

UpdateCACertificate ............................................................................................................... 715CLI .............................................................................................................................. 716

UpdateCertificate .................................................................................................................... 717CLI .............................................................................................................................. 718

UpdateEventConfigurations ...................................................................................................... 719CLI .............................................................................................................................. 720

UpdateIndexingConfiguration .................................................................................................... 721CLI .............................................................................................................................. 722

UpdateJobExecution ............................................................................................................... 722

xi


CLI .............................................................................................................................. 725UpdateRoleAlias .................................................................................................................... 727

CLI .............................................................................................................................. 729UpdateStream ....................................................................................................................... 730

CLI .............................................................................................................................. 731UpdateThing .......................................................................................................................... 733

CLI .............................................................................................................................. 735UpdateThingGroup ................................................................................................................. 737

CLI .............................................................................................................................. 738UpdateThingGroupsForThing ................................................................................................... 740

CLI .............................................................................................................................. 741UpdateThingShadow ............................................................................................................... 742

CLI .............................................................................................................................. 744

xii

AWS IoT 开发人员指南AWS IoT 的组件

什么是 AWS IoT？AWS IoT 可在连接了 Internet 的设备 (如传感器、致动器、嵌入式微控制器或智能设备) 与 AWS 云之间提供安全的双向通信。这样，您变能从多台设备收集遥测数据，然后存储和分析数据。您也可以创建令用户能够通过手机或平板电脑控制这些设备的应用程序。

AWS IoT 的组件AWS IoT 包括以下组件：

设备网关

使设备能够安全高效地与 AWS IoT 进行通信。消息代理

提供安全机制以供设备和 AWS IoT 应用程序用于相互发布和接收消息。进行发布和订阅时，您可以直接使用 MQTT 协议，也可以通过 WebSocket 使用 MQTT 协议。您可以使用 HTTP REST 接口进行发布。

规则引擎

提供消息处理及与其他 AWS 服务进行集成的功能。您可以使用基于 SQL 的语言选择消息负载中的数据，然后处理数据并将数据发送到其他服务，如 Amazon S3、Amazon DynamoDB 和 AWS Lambda。您还可以使用消息代理面向其他订阅者重新发布消息。

安全和身份服务

在 AWS 云中共担安全责任。为了安全地将数据发送到消息代理，您的设备必须确保自身凭证的安全。消息代理和规则引擎使用 AWS 安全功能将数据安全发送到设备或其他 AWS 服务。

注册表

整理与 AWS 云中的每台设备关联的资源。您可以注册自己的设备并将每台设备与最多三个自定义属性关联。您还可以将每台设备与相应的证书和 MQTT 客户端 ID 关联，以提高对设备进行管理和故障排除的能力。

组注册表

通过将设备按类别分成不同的组，可以使用组来同时管理多台设备。组中还可以包含组，您可以构建组的层次结构。您在父组上执行的任何操作都将应用于其子组以及该组及其子组中的所有设备。分配到某个组的权限将应用于该组及其子组中的所有设备。

Device Shadow

一种 JSON 文档，用于存储和检索设备的当前状态信息。Device Shadow 服务

在 AWS 云中提供您的设备的永久性表示形式。您可以向设备的影子发布更新后的状态信息，您的设备可在建立连接时实现状态同步。您的设备还可以将有关其当前状态的信息发布到影子，以供应用程序或其他设备使用。

设备预配置服务

让您可使用描述设备所需资源的模板来预置设备：事物、证书以及一个或多个策略。事物是注册表中的一个条目，其中包含描述设备的属性。设备使用证书针对 AWS IoT 进行身份验证。策略确定设备在AWS IoT 中可执行的操作。

模板包含可用字典中的值替换的变量 (映射)。您可以使用同一个模板来预配置多个设备，只需在字典中为模板变量传递不同的值。

1

AWS IoT 开发人员指南如何开始使用 AWS IoT

自定义身份验证服务

您可以定义自定义授权方，从而通过自定义的身份验证服务和 Lambda 函数来管理自己的身份验证和授权策略。自定义授权方使得 AWS IoT 可以使用持有者令牌身份验证和授权策略，对您的设备进行身份验证和授权操作。

自定义授权方可以实施各种身份验证策略 (例如：JWT 验证、OAuth 提供程序调用等等)，并且必须返回由设备网关授权 MQTT 操作所使用的策略文档。

任务服务

允许您定义一组远程操作，这些操作发送到一个或多个连接到 AWS IoT 的设备并在这些设备上执行。例如，您可以定义一个任务，该任务指示一组设备下载并安装应用程序或固件更新、重启、轮换证书或执行远程故障排除操作。

要创建任务，您需要指定要执行的远程操作的说明，以及应该执行这些操作的目标列表。目标可以是单个设备和/或设备组。

有关 AWS IoT 限制的信息，请参阅 AWS IoT 限制。

如何开始使用 AWS IoT• 要了解有关 AWS IoT 的更多信息，请参阅 AWS IoT 的工作原理 (p. 3)。• 要了解如何将设备连接到 AWS IoT，请参阅 AWS IoT 入门 (p. 4)。

访问 AWS IoTAWS IoT 提供以下接口以创建设备并与之交互：

• AWS Command Line Interface (AWS CLI) – 在 Windows、macOS 和 Linux 上运行 AWS IoT 的命令。您可以使用这些命令创建并管理事物、证书、规则和策略。要开始使用，请参阅 AWS Command LineInterface 用户指南。有关适用于 AWS IoT 的命令的更多信息，请参阅 AWS CLI Command Reference 中的 iot。

• AWS IoT API – 使用 HTTP 或 HTTPS 请求构建您的 IoT 应用程序。您可以使用这些 API 操作以编程方式创建和管理事物、证书、规则及策略。有关适用于 AWS IoT 的 API 操作的更多信息，请参阅 AWS IoTAPI 参考中的操作。

• AWS SDK – 使用语言特定 API 构建您的 IoT 应用程序。这些软件开发工具包中封装了 HTTP/HTTPSAPI，并且您可以用任何受支持的语言进行编程。有关更多信息，请参阅 AWS SDKs and Tools。

• AWS IoT 设备开发工具包 – 构建在设备上运行的应用程序，以便与 AWS IoT 收发消息。有关更多信息，请参阅 AWS IoT 开发工具包。

相关服务AWS IoT 可直接与以下 AWS 服务集成：

• Amazon Simple Storage Service – 在 AWS 云中提供可扩展存储。有关更多信息，请参阅 Amazon S3。• Amazon DynamoDB – 提供托管型 NoSQL 数据库。有关更多信息，请参阅 Amazon DynamoDB。• Amazon Kinesis – 可实时进行大规模的流数据处理。有关更多信息，请参阅 Amazon Kinesis。• AWS Lambda – 在 Amazon EC2 的虚拟服务器上运行代码以响应事件。有关更多信息，请参阅 AWS

Lambda。

2

http://docs.aws.amazon.com/general/latest/gr/aws_service_limits.html#limits_iot

http://docs.aws.amazon.com/cli/latest/userguide/

http://docs.aws.amazon.com/cli/latest/userguide/

http://docs.aws.amazon.com/cli/latest/reference/iot/index.html

http://docs.aws.amazon.com/iot/latest/apireference/API_Operations.html

http://aws.amazon.com/tools/#sdk

http://docs.aws.amazon.com/iot/latest/developerguide/iot-sdks.html

https://aws.amazon.com/s3/

https://aws.amazon.com/dynamodb/

https://aws.amazon.com/kinesis/

https://aws.amazon.com/lambda/

https://aws.amazon.com/lambda/

AWS IoT 开发人员指南AWS IoT 的工作原理

• Amazon Simple Notification Service – 发送或接收通知。有关更多信息，请参阅 Amazon SNS。• Amazon Simple Queue Service – 将数据存储在队列中以供应用程序检索。有关更多信息，请参阅

Amazon SQS。

AWS IoT 的工作原理AWS IoT 使连接了 Internet 的设备能够连接到 AWS 云，并使云中的应用程序能够与连接了 Internet 的设备进行交互。常见的 IoT 应用程序可从设备收集和处理遥测数据，或者令用户能够远程控制设备。

设备通过在 MQTT 主题下以 JSON 格式发布消息来报告自身的状态。每个 MQTT 主题都有一个分层名称，可识别状态正在更新的设备。在 MQTT 主题上发布消息时，该消息将发送至 AWS IoT MQTT 消息代理，后者负责将在该 MQTT 主题上发布的所有消息发送给已订阅该主题的所有客户端。

通过使用 X.509 证书保护设备与 AWS IoT 之间的通信。AWS IoT 可为您生成一个证书，您也可以使用自己的证书。无论哪种情况，都必须通过 AWS IoT 注册并激活证书，然后再复制到您的设备上。当您的设备与AWS IoT 进行通信时，它会将证书作为凭证提供给 AWS IoT。

我们建议在注册表中为连接到 AWS IoT 的所有设备都创建一个条目。注册表存储设备的相关信息以及设备用于确保与 AWS IoT 安全地通信的证书。

您可以制定相关规则，确定要基于消息内数据执行的一项或多项操作。例如，您可以插入、更新或查询DynamoDB 表，或者调用 Lambda 功能。规则使用表达式来筛选消息。当规则与一条消息匹配时，规则引擎会使用所选属性调用该操作。规则还包含 IAM 角色，该角色可授予 AWS IoT 对用于执行操作的 AWS 资源的权限。

每台设备都有一个可存储和检索状态信息的影子。状态信息中的每一项都含两个条目：设备报告的最新状态，以及应用程序请求的预期状态。应用程序可以请求设备的当前状态信息。影子通过提供包含状态信息（报告状态和预期状态）、元数据和版本号的 JSON 文档来响应请求。应用程序可以通过请求更改状态来控制设备。影子将接受状态更改请求、更新其状态信息，然后发送消息来指明状态信息已更新。设备会接收消息、更改状态，然后报告其新状态。

3

https://aws.amazon.com/sns/

https://aws.amazon.com/sqs/

AWS IoT 开发人员指南登录 AWS IoT 控制台

AWS IoT 入门本教程向您展示如何创建从使用 AWS IoT 的设备发送、接收和处理 MQTT 消息所需的资源。

完成本教程需要做好以下准备：

• 一台能够访问 Wi-Fi 的计算机。• 如果您已经有 AWS IoT 按钮 (如图所示)，则可以使用此按钮来完成本教程。• 如果您没有按钮，则可以在此处购买一个或在 AWS IoT 控制台中使用 MQTT 客户端来模拟一个设备。

有关 AWS IoT 的更多信息，请参阅什么是 AWS IoT (p. 1)。

登录 AWS IoT 控制台如果您没有 AWS 账户，请创建一个。

创建 AWS 账户:

1. 打开 AWS 主页，然后选择 Create an AWS Account。2. 按照在线说明操作。在注册过程中，您会接到来电并且需要使用手机键盘输入 PIN 码。3. 登录 AWS 管理控制台，然后打开 AWS IoT 控制台。4. 在 Welcome 页面上，选择 Get started。

4

https://www.amazon.com/All-New-AWS-IoT-Button-Generation/dp/B01KW6YCIM/ref=dp_ob_title_def

https://aws.amazon.com/

https://console.aws.amazon.com/iot/home

AWS IoT 开发人员指南在 Registry 中注册设备

如果这是您第一次使用 AWS IoT 控制台，您会看到欢迎使用 AWS IoT 控制台页面。

在 Registry 中注册设备连接到 AWS IoT 的设备在注册表中由事物表示。借助 Registry，您可以将连接到您的 AWS IoT 账户的所有设备的记录保留下来。

开始使用 AWS IoT 按钮的最快方法是下载适用于 iOS 或 Android 的移动应用程序。此移动应用程序会为您创建必要的 AWS IoT 资源，然后向您的按钮添加一个事件源，使用 Lambda 蓝图调用您选择的新 AWSLambda 函数。蓝图是预配置的 Lambda 函数，您可以通过它将按钮单击操作快速连接到最适合您的函数，如发送自动电子邮件、短信或部署其他 AWS 服务。您可以从以下位置下载移动应用程序：Apple AppStore或 Google Play。

如果您无法使用移动应用程序，请按照以下说明操作。

在 Registry 中注册您的设备：

1. 在欢迎使用 AWS IoT 控制台页面上，在左侧导航窗格中选择管理以展开选项，然后选择事物。

5

https://itunes.apple.com/us/app/aws-iot-button/id1178216626?mt=8

https://itunes.apple.com/us/app/aws-iot-button/id1178216626?mt=8

https://play.google.com/store/apps/details?id=com.amazonaws.iotbutton

AWS IoT 开发人员指南在 Registry 中注册设备

2. 在提示 You don't have any things yet 的页面上，选择 Register a thing。

3. 在创建 AWS IoT 事物页面上，选择创建单个事物。

6

AWS IoT 开发人员指南创建并激活设备证书

4. 在创建事物页面上的名称字段中键入设备的名称，例如 MyIoTButton。选择下一步以将您的设备添加到注册表。

创建并激活设备证书通过使用 X.509 证书保护您的设备与 AWS IoT 之间的通信。AWS IoT 可为您生成证书，或者您也可以使用自己的 X.509 证书。在本教程中，AWS IoT 会为您生成 X.509 证书。必须先激活证书，然后才能使用它们。

1. 选择 Create certificate。

7

AWS IoT 开发人员指南创建并激活设备证书

2. 在 Certificate created! 页面上，为证书、私有密钥和 AWS IoT 的根 CA 选择 Download (无需下载公有密钥)。将其中每一项都保存到您的计算机上，然后选择 Activate 以继续。

请注意，已下载的文件名可能不同于Certificate created! 页. 例如：

• 2a540e2346-certificate.pem.crt.txt• 2a540e2346-private.pem.key• 2a540e2346-public.pem.key

Note

根 CA 证书可能会过期和/或被吊销，但发生这种情况的可能性不大。如果发生这种情况，您必须将新的根 CA 证书复制到您的设备上。

3. 选择后退箭头，直至您返回到主 AWS IoT 控制台屏幕。

8

AWS IoT 开发人员指南创建 AWS IoT 策略

创建 AWS IoT 策略X.509 证书用于对您的 AWS IoT 设备进行身份验证。AWS IoT 策略用于授予您的设备执行 AWS IoT 操作的权限，比如订阅 MQTT 主题或向 MQTT 主题发布消息。您的设备将在向 AWS IoT 发送消息时呈现其证书。要允许您的设备执行 AWS IoT 操作，您必须创建 AWS IoT 策略并将其附加您的设备证书中。

创建 AWS IoT 策略：

1. 在左侧导航窗格中选择 Secure，然后选择 Policies。在 You don't have a policy yet 页面上，选择Create a policy。

2. 在 Create a policy 页面上的 Name 字段中键入策略的名称 (例如，MyIoTButtonPolicy)。在 Action字段中键入 iot:Connect。在 Resource ARN 字段中键入 *。选中 Allow 复选框。这样一来，所有客户端均能连接至 AWS IoT。

9

AWS IoT 开发人员指南创建 AWS IoT 策略

Note

您可以将客户端 ARN 指定为资源，从而限定哪些客户端（设备）能够连接。客户端 ARN 应采用以下格式：arn:aws:iot:your-region:your-aws-account:client/<my-client-id>

选择 Add Statement 按钮添加另一个策略语句。在 Action 字段键入 iot:Publish。在 Resource ARN 字段中，键入设备要在其下发布消息的主题的相应 ARN。

Note

主题 ARN 遵循以下格式：arn:aws:iot:your-region:your-aws-account:topic/iotbutton/your-button-serial-number例如：arn:aws:iot:us-east-1:123456789012:topic/iotbutton/G030JF055364XVRB在按钮底部，可以找到序列号。如果您当前未使用 AWS IoT 按钮，请在 ARN 中的 topic/ 之后放置设备将发布到的主题。例如：arn:aws:iot:us-east-1:123456789012:topic/my/topic/here

最后，选中 Allow 复选框。这样一来，您的设备便可以在指定主题下发布消息。3. 在输入策略的信息后，选择 Create。

10

AWS IoT 开发人员指南将 AWS IoT 策略附加到设备证书

有关详细信息，请参阅管理 AWS IoT 策略。

将 AWS IoT 策略附加到设备证书现在，您已经创建了策略，您必须将它附加到您的设备证书中。通过将 AWS IoT 策略附加到证书中，可授予设备在策略中指定的权限。

1. 在左侧导航窗格中选择 Secure，然后选择 Certificates。

11

http://docs.aws.amazon.com/iot/latest/developerguide/authorization.html

AWS IoT 开发人员指南将 AWS IoT 策略附加到设备证书

2. 在您创建的证书栏，选择 ... 打开下拉菜单，然后选择 Attach policy。

3. 在 Attach policies to certificate(s) 对话框中，选中您在上一步中创建的策略旁边的复选框，然后选择Attach。

12

AWS IoT 开发人员指南将证书附加到事物

将证书附加到事物设备必须拥有证书、私有密钥和根 CA 证书才能在 AWS IoT 中进行身份验证。我们建议您将设备证书附加到在 AWS IoT 中代表您的设备的事物。这让您能够基于附加到事物的证书来创建授予权限的 AWS IoT 策略。有关. 请参阅事物策略变量 (p. 124)

将证书附加到在 Registry 中代表您的设备的事物：

1. 在您创建的证书栏，选择 ... 打开下拉菜单，然后选择 Attach thing。

13


2. 在 Attach things to certificate(s) 对话框中，选中您已经注册的事物旁边的复选框，然后选择 Attach。

3. 要验证事物已附加，请选中代表证书的栏。

14


4. 在证书的 Details 页面上，在左侧导航窗格中选择 Things。

5. 要验证策略已附加，请在证书的 Details 页面上，在左侧导航窗格中选择 Policies。

15

AWS IoT 开发人员指南配置您的设备

配置您的设备配置您的设备，使其能够连接到您的 Wi-Fi 网络。您的设备必须连接至 Wi-Fi 网络才能安装需要的文件和向AWS IoT 发送消息。为了与 AWS IoT 通信，所有设备必须安装设备证书、私有密钥和根 CA 证书。

Note

按 AWS IoT 按钮 15 秒将重置该设备，此时您需要重新配置 Wi-Fi 和设备证书。

配置 AWS IoT 按钮。配置您的 AWS IoT 按钮的最简单方法是使用 AWS IoT 按钮智能手机应用程序。您可以从 Apple 应用商店或Google Play 商店下载该应用程序。如果您无法使用该智能手机应用程序，请按照以下说明操作来配置您的按钮。

打开您的设备1. 拆除 AWS IoT 按钮的包装，然后按住按钮，直到显示蓝色闪光信号灯。(该时间不应超过 15 秒。)2. 此按钮可充当 Wi-Fi 接入点，因此，当您的计算机搜索 Wi-Fi 网络时，它将发现一个名为 Button

ConfigureMe - XXX 的接入点，其中 XXX 是按钮生成的字符串 (含三个字符)。使用您的计算机连接到按钮的 Wi-Fi 接入点。

Note

当蓝光停止闪烁时，按钮会停止将自身作为 Wi-Fi 接入点。因此，如果您无法足够快地完成以下过程，可能需要多次打开闪烁蓝光的指示灯才能完成以下过程。配置后，设备不需要将自身作为 Wi-Fi 接入点，并像任何其他计算机一样，使用本地 Wi-Fi 网络与 Internet 进行通信。

3. 当您第一次连接到按钮的 Wi-Fi 接入点时，系统将提示您输入 WPA2-PSK 密码。请键入设备序列号(DSN) 的后 8 个字符。在设备背面可以找到 DSN，如下所示：

将您的设备证书和私有密钥复制到 AWS IoT 按钮要连接到 AWS IoT，您必须将您的设备证书和私有密钥复制到 AWS IoT 按钮上。

1. 在浏览器中，导航到 http://192.168.0.1/index.html。2. 填写配置表单：

• 键入您的 Wi-Fi SSID 和密码。• 浏览找到并选择您的证书和私有密钥。例如，分别为 2a540e2346-certificate.pem.crt.txt

和 2a540e2346-private.pem.key。• 在 AWS IoT 控制台中查找您的自定义终端节点。(在控制面板的左侧导航窗格中，选择 Manage，然

后选择 Things。选中代表您的按钮的栏可显示其详细信息页面。在详细信息页面上的左侧导航窗格中选择 Interact 并查找顶部附近的 HTTPS 部分。)您的终端节点看起来如下所示：

ABCDEFG1234567.iot.us-east-2.amazonaws.com

其中 ABCDEFG1234567 是子域，us-east-2 是区域。

16

https://itunes.apple.com/us/app/aws-iot-button/id1178216626

https://play.google.com/store/apps/details?id=com.amazonaws.iotbutton

http://192.168.0.1/index.html

https://console.aws.amazon.com/iot/home?region=us-east-1#/dashboard/help

AWS IoT 开发人员指南配置不同的设备

• 在 Button ConfigureMe 页面上，键入子域，然后选择与您的 AWS IoT 终端节点中的区域相匹配的区域。

• 选中 Terms and Conditions 复选框。现在，您的设置看起来应如下所示：

• 选择 Configure。您的按钮现在应连接到您的 Wi-Fi 网络。

配置不同的设备请按照设备文档的说明连接设备，并将设备证书、私有密钥和根 CA 证书复制到设备上。

使用 AWS IoT MQTT 客户端查看设备 MQTT 消息您可以使用 AWS IoT MQTT 客户端来更好地了解设备发送的 MQTT 消息。

设备会在主题下发布 MQTT 消息。您可以使用 AWS IoT MQTT 客户端订阅这些主题，以查看这些消息。

查看 MQTT 消息：

1. 在 AWS IoT 控制台中，在左侧导航窗格中选择 Test。

2. 订阅您的事物发布的主题。如果是 AWS IoT 按钮，您可以订阅 iotbutton/+ (请注意，+ 是通配符)。在 Subscribe to topic 中，在 Subscription topic 字段键入 iotbutton/+，然后选择 Subscribe totopic。

17


AWS IoT 开发人员指南使用 AWS IoT MQTT 客户端查看设备 MQTT 消息

选择上面的 Subscribe to topic 会导致主题 iotbutton/+ 显示在 Subscriptions 列中。

3. 按您的 AWS IoT 按钮，然后查看 AWS IoT MQTT 客户端中生成的消息。如果您没有按钮，则下一步需要模拟按钮按压。

18

AWS IoT 开发人员指南使用 AWS IoT MQTT 客户端查看设备 MQTT 消息

Note

AWS IoT 按钮常见问题包含有用的按钮 LED 颜色模式信息。4. 要使用 AWS IoT 控制台发布消息，请执行以下操作：

在 MQTT 客户端页面上，在发布部分的指定要发布的主题和消息… 字段中，键入 iotbutton/ABCDEFG12345。在消息负载部分，键入以下 JSON：

{ "serialNumber": "ABCDEFG12345", "clickType": "SINGLE", "batteryVoltage": "2000 mV"}

选择 Publish to topic。您应该在 AWS IoT MQTT 客户端中看到消息 (选择 Subscription 列中的iotbutton/+ 来查看消息)。

19

https://aws.amazon.com/iotbutton/faq

AWS IoT 开发人员指南配置并测试规则

配置并测试规则AWS IoT 规则引擎侦听与规则匹配的传入 MQTT 消息。当收到匹配的消息时，规则会对 MQTT 消息中的数据执行某种操作（例如，将数据写入 Amazon S3 存储桶中、调用 Lambda 函数或向 Amazon SNS 主题发送消息）。在此步骤中，您将创建和配置规则，以将从设备接收的数据发送到 Amazon SNS 主题。具体来说，您将要：

• 创建一个 Amazon SNS 主题。• 使用手机号码订阅 Amazon SNS 主题。• 创建规则，以便将从您的设备接收的消息发送到 Amazon SNS 主题。• 使用您的 AWS IoT 按钮或 MQTT 客户端测试规则。

在此页面的右上角，有一个 Filter View 下拉列表。有关使用 AWS IoT 按钮测试规则的说明，请选择 AWSIoT Button。有关使用 AWS IoT MQTT 客户端测试规则的说明，请选择 MQTT Client。

创建一个 SNS 主题使用 Amazon SNS 控制台可创建 Amazon SNS 主题。

Note

Amazon SNS 并未在所有 AWS 区域提供。

1. 打开 Amazon SNS 控制台。2. 在左侧窗格选择 Topics。

3. 选择 Create new topic。

20

https://console.aws.amazon.com/sns/v2/home

AWS IoT 开发人员指南创建一个 SNS 主题

4. 键入主题名称和显示名称，然后选择 Create topic。

5. 请记下您刚刚创建的主题的 ARN。

21

AWS IoT 开发人员指南订阅 Amazon SNS 主题

订阅 Amazon SNS 主题要在您的手机上接收 SMS 消息，请订阅 Amazon SNS 主题。

1. 在 Amazon SNS 控制台中，选中您刚创建的主题旁边的复选框。从 Actions 菜单中，选择 Subscribe totopic。

2. 在 Create subscription 上，从 Protocol 下拉列表中选择 SMS。

在 Endpoint 字段中，键入启用 SMS 的手机号码，然后选择 Create subscription。

Note

仅使用数字和短划线输入电话号码。

创建规则AWS IoT 规则包含主题筛选条件和规则操作，在大多数情况下还包括 IAM 角色。如果在与主题筛选条件相匹配的主题下发布消息，则会触发规则。规则操作定义了规则触发时应执行的操作。IAM 角色包含一项或多项IAM 策略，这些策略确定规则可以访问哪些 AWS 服务。您可以创建多项规则来侦听一个主题。同样，您也可以创建一个可由多个主题触发的规则。AWS IoT 规则引擎会持续处理在与规则中定义的主题筛选条件相匹配的主题下发布的消息。

在此示例中，您将创建一条规则，以便使用 Amazon SNS 向手机号码发送 SMS 通知。

1. 在 AWS IoT 控制台的左侧导航窗格中选择 Act (操作)。

22

AWS IoT 开发人员指南创建规则

2. 在 Act 页面上，选择 Create a rule。

3. 在 Create a rule 页面上，在 Name 字段中键入规则名称。在 Description 字段键入规则的说明。

23


4. 向下滚动至消息源。从 Using SQL version 下拉列表中选择最新版本。在 Attribute 字段键入 *。这将指定您要发送触发了规则的完整 MQTT 消息。

5. 规则引擎使用主题筛选条件来确定收到 MQTT 消息时将触发哪些规则。在 Topic filter 字段键入iotbutton/your-button-DSN。如果您当前未使用 AWS IoT 按钮，请键入 my/topic 或规则中使用的主题。

Note

您可以在按钮底部找到 DSN。

将 Condition 留空。

24


6. 在 Set one or more actions 中，选择 Add action。

7. 在 Select an action 页面上，选择 Send a message as an SNS push notification，然后选择 Configureaction。

25


8. 在 Configure action 页面上，从 SNS target 下拉列表中选择您之前创建的 Amazon SNS 主题。

26


9. 现在，授予 AWS IoT 在触发规则时代表您发布到 Amazon SNS 主题的权限。选择 Create a new role。在 IAM role name 字段输入新角色的名称。在输入名称后，再次选择 Create a new role。从 IAM rolename 下拉列表中选择新创建的角色。

10. 选择 Update role 将权限应用到新创建的角色，然后选择 Add action。

27

AWS IoT 开发人员指南测试 Amazon SNS 规则

11. 在 Create a Rule 页面，选择 Create rule。

有关如何创建规则的更多信息，请参阅 AWS IoT 规则。

测试 Amazon SNS 规则您可以使用 AWS IoT 按钮或 AWS IoT MQTT 客户端来测试规则。

AWS IoT 按钮按您的按钮。您应该会收到短信，显示您的设备的当前电池电量水平 (以及其他信息)。尝试长按 (大约 2 秒)和快速双按，然后注意生成的消息。

28

http://docs.aws.amazon.com/iot/latest/developerguide/iot-rules.html

AWS IoT 开发人员指南后续步骤

AWS IoT MQTT 客户端使用 AWS IoT MQTT 客户端测试您的规则：

1. 在 AWS IoT 控制台中，在左侧导航窗格中选择 Test。2. 在 MQTT 客户端页面上，在发布部分的指定要发布的主题和消息… 字段中，键入 my/topic 或规则中

使用的主题。在消息负载部分，键入以下 JSON：

{ "message": "Hello, from AWS IoT console"}

Note

如果您正在使用按钮，请在指定要发布的主题和消息… 字段中键入 iotbutton/您您您您您DSN，而不是 my/topic。

3. 选择 Publish to topic。您的手机上应该会收到 Amazon SNS 消息。

恭喜您！您已成功创建并配置了一个规则，它会将从设备收到的数据发送到 Amazon SNS 主题。

后续步骤有关 AWS IoT 规则的更多信息，请参阅和 AWS IoT 规则教程 (p. 45)和 AWS IoT 规则 (p. 157)。

29


AWS IoT 开发人员指南AWS IoT 按钮向导快速入门

AWS IoT 按钮快速入门本部分的两个快速入门为您展示了如何配置和使用 AWS IoT 按钮。您可以使用 AWS Lambda 控制台中的 AWS IoT 按钮向导快速轻松地配置 AWS IoT 按钮。AWS Lambda 控制台中包含一个蓝图，该蓝图可将AWS IoT 按钮的设置流程自动化，具体操作如下：

• 创建并激活 X.509 证书和私有密钥，以用于在 AWS IoT 中执行身份验证。• 指导您完成对 AWS IoT 按钮的配置，以便连接到 Wi-Fi 网络。• 指导您将证书和私有密钥复制到 AWS IoT 按钮。• 创建 AWS IoT 策略并将其附加到证书，以授予按钮调用 AWS IoT 的权限。• 创建 AWS IoT 规则，以在您按 AWS IoT 按钮时调用 Lambda 函数。• 创建 IAM 角色和策略，以允许 Lambda 函数通过 Amazon SNS 发送电子邮件。• 创建 Lambda 函数，以向 Lambda 函数代码中指定的地址发送电子邮件。

第二个快速入门向您展示如何使用 AWS CloudFormation 模板配置处理 MQTT 消息所需的 AWS IoT 资源，这些消息会在按下 AWS IoT 按钮时发送。

如果您没有按钮，可在此处购买一个。有关 AWS IoT 的更多信息，请参阅什么是 AWS IoT (p. 1)。

主题• AWS IoT 按钮向导快速入门 (p. 30)• AWS IoT 按钮 AWS CloudFormation 快速入门 (p. 39)• 后续步骤 (p. 44)

AWS IoT 按钮向导快速入门AWS IoT 按钮向导是一个 Lambda 蓝图，因此，您必须登录 AWS Lambda 控制台才能使用它。如果您没有AWS 账户，则可以按照以下步骤创建一个。

创建 AWS 账户

1. 打开 AWS 主页，然后选择 Create an AWS Account。2. 按照在线说明操作。在注册过程中，您会接到来电并且需要使用手机键盘输入 PIN 码。

30

https://www.amazon.com/All-New-AWS-IoT-Button-Generation/dp/B01KW6YCIM/ref=dp_ob_title_def

https://aws.amazon.com/


配置 AWS IoT 按钮

1. 登录 AWS 管理控制台，然后打开 AWS Lambda 控制台。2. 如果这是您首次登录 AWS Lambda 控制台，那么您将看到以下页面。选择 Get Started Now 按钮。

如果您使用过 AWS Lambda 控制台，那么您将看到以下页面。选择 Create a Lambda function 按钮。

3. 在 Select blueprint 页面上，从 Runtime 下拉菜单中选择 Node.js 4.3。在“Filter”文本框中，键入button。要选择 iot-button-email 蓝图，请双击它或选择 Next 按钮。

31

https://console.aws.amazon.com/lambda/home


4. 在 Configure triggers 页面上，从 IoT Type 下拉菜单中选择 IoT Button。

键入设备的序列号。设备序列号 (DSN) 显示在按钮背面。

选择 Generate certificate and keys。

Note

您只需生成一次证书和私有密钥。然后，您可以在浏览器中导航到 http://192.168.0.1/index.html 以开始配置您的按钮。

32




使用页面上的这些链接下载设备证书和私有密钥。

33


页面上还提供了关于如何配置 AWS IoT 按钮的说明。在步骤 3 中，您需要选择链接以打开一个网页，您可以在该网页中将 AWS IoT 按钮连接到网络。在 Wi-Fi Configuration 下，键入所在 Wi-Fi 网络的网络ID (SSID) 和网络密码。在 AWS IoT Configuration 下，选择之前下载的证书和私有密钥。这会将您的证书和私有密钥复制到 AWS IoT 按钮。选择相应的复选框以表示同意遵守 AWS IoT 按钮条款和条件，然后选择 Configure 按钮。

34


此时将显示配置确认页面。

5. 关闭 Configure 选项卡并返回到 AWS Lambda 控制台页面。选择 Enable trigger，然后选择 Next。

在 Configure function 页面上，键入函数名称。此时，系统将为您输入相应的描述、运行时间和 Lambda函数代码。

35


在 Lambda 函数代码中，将示例电子邮件地址替换为您自己的电子邮件地址。

36


在 Lambda function handler and role 部分，从 Role 下拉菜单中选择 Create new role fromtemplate(s)。为角色键入唯一名称。

在页面底部，选择 Next。

查看 Lambda 函数的设置，然后选择 Create function。

37


此时您应看到一个确认已创建 Lambda 函数的页面：

38

AWS IoT 开发人员指南AWS IoT 按钮 AWS CloudFormation 快速入门

6. 要测试 Lambda 函数，请选择 Test 按钮。大约一分钟后，您会收到一封主题行内容为 AWSNotification - Subscription Confirmation 的电子邮件。选择电子邮件中的链接，以确认Lambda 函数已创建 SNS 主题订阅。当 AWS IoT 收到来自您的按钮的消息后，它会向 Amazon SNS 发送一条消息。Lambda 函数创建 Amazon SNS 主题订阅时使用的是您在代码中添加的电子邮件地址。当Amazon SNS 在该 Amazon SNS 主题上收到消息后，它会将消息转发到您的订阅电子邮件地址。

按您的按钮以向 AWS IoT 发送消息。该消息将导致触发 Lambda 规则，进而调用 Lambda 函数。Lambda函数会检查您的 SNS 主题是否存在。接下来，Lambda 函数将消息内容发送至 Amazon SNS 主题。然后，Amazon SNS 将消息转发到您在 Lambda 函数代码中指定的电子邮件地址。

AWS IoT 按钮 AWS CloudFormation 快速入门在按下 AWS IoT 按钮时，它会将与按钮有关的基本信息发送至 Amazon SNS 主题。随后主题会将该信息以邮件消息的方式转发给您。本快速入门向您说明如何使用 AWS CloudFormation 模板配置 AWS IoT 按钮。

您需要 AWS 账户和 AWS IoT 按钮才能完成本快速入门中的步骤。

1. 使用 AWS IoT 控制台创建 AWS IoT 证书：

a. 打开 AWS IoT 控制台。b. 出现 Welcome 页面时，请选择 Get started。c. 在 AWS 区域选择器中，选择您要创建 AWS IoT 证书的 AWS 区域 (例如，美国东部 (弗吉尼亚北

部))。您将在同一 AWS 区域创建所有支持的 AWS 资源 (其他 AWS IoT 资源和 Amazon SNS 资源)。

d. 在控制面板上，在左侧导航窗格中选择安全，然后选择证书。

39



e. 在 Certificates 窗格中选择 Create。f. 选择 One-click certificate creation - Create certificate。g. 在证书已创建页面上，为证书、私有密钥和 AWS IoT 的根 CA 选择下载，将它们保存到您的计算机

中，然后选择激活。h. 选择完成。i. 在 Certificates 页面上，选择您刚创建的证书。j. 在 Details 信息中，记下证书 ARN 值 (例如，arn:aws:iot:region-ID:account-ID:cert/

random-ID)。您需要在本过程的后面部分中使用它。2. 在 https://console.aws.amazon.com/cloudformation/ 使用 AWS CloudFormation 控制台创建 AWS IoT

资源、Amazon SNS 资源和 IAM 角色：

a. 将 AWS CloudFormation 模板文件命名为 AWSIoTButtonQuickStart.template 并保存到您的计算机。

Note

检查您按钮的 DSN。确保“AllowedPattern”字符串的开头与您的 DSN 匹配。

{ "AWSTemplateFormatVersion": "2010-09-09", "Description": "Creates required AWS resources to allow an AWS IoT button to send information through an Amazon Simple Notification Service (Amazon SNS) topic to an email address.", "Parameters": { "IoTButtonDSN": { "Type": "String", "AllowedPattern": "G030[A-Z][A-Z][0=9][0-9][0-9][0-5][0-9][1-7][0-9A-HJ-NP-X][0-9A-HJ-NP-X][0-9A-HJ-NP-X][0-9A-HJ-NP-X]", "Description": "The device serial number (DSN) of the AWS IoT Button. This can be found on the back of the button. The DSN must match the pattern of 'G030[A-Z][A-Z][0=9][0-9][0-9][0-5][0-9][1-7][0-9A-HJ-NP-X][0-9A-HJ-NP-X][0-9A-HJ-NP-X][0-9A-HJ-NP-X]'." }, "CertificateARN": { "Type": "String", "Description": "The Amazon Resource Name (ARN) of the existing AWS IoT certificate." }, "SNSTopicName": { "Type": "String", "Default": "aws-iot-button-sns-topic", "Description": "The name of the Amazon SNS topic for AWS CloudFormation to create." }, "SNSTopicRoleName": { "Type": "String", "Default": "aws-iot-button-sns-topic-role", "Description": "The name of the IAM role for AWS CloudFormation to create. This IAM role allows AWS IoT to send notifications to the Amazon SNS topic." }, "EmailAddress": { "Type": "String", "Description": "The email address for the Amazon SNS topic to send information to." } }, "Resources": { "IoTThing": { "Type": "AWS::IoT::Thing", "Properties": { "ThingName": {

40

https://console.aws.amazon.com/cloudformation/


"Fn::Join" : [ "", [ "iotbutton_", { "Ref": "IoTButtonDSN" } ] ] } } }, "IoTPolicy": { "Type" : "AWS::IoT::Policy", "Properties": { "PolicyDocument": { "Version": "2012-10-17", "Statement": [ { "Action": "iot:Publish", "Effect": "Allow", "Resource": { "Fn::Join": [ "", [ "arn:aws:iot:", { "Ref": "AWS::Region" }, ":", { "Ref": "AWS::AccountId" }, ":topic/iotbutton/", { "Ref": "IoTButtonDSN" } ] ] } } ] } } }, "IoTPolicyPrincipalAttachment": { "Type": "AWS::IoT::PolicyPrincipalAttachment", "Properties": { "PolicyName": { "Ref": "IoTPolicy" }, "Principal": { "Ref": "CertificateARN" } } }, "IoTThingPrincipalAttachment": { "Type" : "AWS::IoT::ThingPrincipalAttachment", "Properties": { "Principal": { "Ref": "CertificateARN" }, "ThingName": { "Ref": "IoTThing" } } }, "SNSTopic": { "Type": "AWS::SNS::Topic", "Properties": { "DisplayName": "AWS IoT Button Press Notification", "Subscription": [ { "Endpoint": { "Ref": "EmailAddress" },

41


"Protocol": "email" } ], "TopicName": { "Ref": "SNSTopicName" } } }, "SNSTopicRole": { "Type": "AWS::IAM::Role", "Properties": { "AssumeRolePolicyDocument": { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "Service": "iot.amazonaws.com" }, "Action": "sts:AssumeRole" } ] }, "Path": "/", "Policies": [ { "PolicyDocument": { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": "sns:Publish", "Resource": { "Fn::Join": [ "", [ "arn:aws:sns:", { "Ref": "AWS::Region" }, ":", { "Ref": "AWS::AccountId" }, ":", { "Ref": "SNSTopicName" } ] ] } } ] }, "PolicyName": { "Ref": "SNSTopicRoleName" } } ] } }, "IoTTopicRule": { "Type": "AWS::IoT::TopicRule", "Properties": { "RuleName": { "Fn::Join": [ "", [ "iotbutton_", { "Ref": "IoTButtonDSN" } ] ] }, "TopicRulePayload": {

42


"Actions": [ { "Sns": { "RoleArn": { "Fn::GetAtt": [ "SNSTopicRole", "Arn" ] }, "TargetArn": { "Ref": "SNSTopic" } } } ], "AwsIotSqlVersion": "2015-10-08", "RuleDisabled": false, "Sql": { "Fn::Join": [ "", [ "SELECT * FROM 'iotbutton/", { "Ref": "IoTButtonDSN" }, "'" ] ] } } } } }}

b. 通过以下网址打开 AWS CloudFormation 控制台：https://console.aws.amazon.com/cloudformation/。

c. 请确保 AWS 区域选择器显示您创建 AWS IoT 证书的区域 (例如，美国东部 (弗吉尼亚北部))。d. 选择 Create Stack。e. 在 Select Template 页面上，选择 Upload a template to Amazon S3，然后选择 Browse。f. 选中您之前保存的 AWSIoTButtonQuickStart.template 文件，选择 Open，然后选择 Next。g. 在 Specify Details 页面上，在 Stack name 中键入该 AWS CloudFormation 堆栈的名称 (例如

MyAWSIoTButtonStack)。h. 对于 CertificateARN，键入您之前记下的 AWS IoT 证书的 Amazon 资源名称 (ARN) (证书 ARN

值)。i. 在 EmailAddress 中键入您的电子邮件地址。j. 在 IoTButtonDSN 中键入设备序列号 (DSN)。它显示在 AWS IoT 按钮的背面 (例

如，G030JF051234A5BC)。k. SNSTopicName 和 SNSTopicRoleName 可以保留默认值，您也可指定不同的 Amazon SNS 主题

名称和相关联的 IAM 角色名称。例如，如果您计划设置更多 AWS IoT 按钮，您可能需要更改这些值。选择 Next。

l. Options 页面中不需要进行执行操作。选择 Next。m. 在 Review 页面上，选择 I acknowledge that AWS CloudFormation might create IAM resources，

然后选择 Create。n. 如果 MyAWSIoTButtonStack 显示 CREATE_COMPLETE，请在您的电子邮件收件箱中查找主题

为“AWS IoT Button Press Notification”的消息。选择邮件消息正文中的 Confirm subscription 链接。3. 使用您之前创建的私有密钥和证书，按照 Configure Your Device 中的步骤设置您的 AWS IoT 按钮。4. 在设置之后，请按一次按钮。白灯闪烁几下，然后绿灯会亮起一段时间。不久后，您应收到主题行中包

含“AWS IoT Button Press Notification”的邮件消息。它包含由按钮在电子邮件正文中发送的信息。5. 在完成试用后，您可以进行清理 AWS CloudFormation 模板创建的 AWS 资源。为此，请返回 AWS

CloudFormation 控制台并删除 MyAWSIoTButtonStack。在删除 MyAWSIoTButtonStack 后，按照以下步骤删除 AWS IoT 证书：

43



http://docs.aws.amazon.com/iot/latest/developerguide/configure-iot.html

AWS IoT 开发人员指南后续步骤

a. 返回 AWS IoT 控制台。b. 在资源列表中，在代表 AWS IoT 证书的栏中 (带有握手图标的栏) 选中复选框。c. 对于 Actions，选择 Deactivate，然后确认。d. 保持选中代表 AWS IoT 证书的栏，为 Actions 选择 Delete，然后确认。e. 您之前下载的私有密钥和证书不再有效，您现在可以将它们从计算机中删除。

后续步骤要了解有关用于设置按钮的 Lambda 蓝图的更多信息，请参阅 Getting Started with AWS IoT。要学习如何通过 AWS IoT 按钮使用 AWS CloudFormation，请参阅 http://docs.aws.amazon.com/iot/latest/developerguide/iot-button-cloud-formation.html.

44

http://docs.aws.amazon.com/iot/latest/developerguide/iot-gs.html

http://docs.aws.amazon.com/iot/latest/developerguide/iot-button-cloud-formation.html

http://docs.aws.amazon.com/iot/latest/developerguide/iot-button-cloud-formation.html

AWS IoT 开发人员指南创建 DynamoDB 规则

AWS IoT 规则教程本指南中的教程将向您介绍如何创建和测试 AWS IoT 规则。如果您尚未完成 AWS IoT 入门教程 (p. 4)，建议您先学习该教程。它将向您展示如何创建 AWS 账户以及如何将您的设备连接到 AWS IoT。

AWS IoT 规则由 SQL SELECT 语句、主题筛选条件和规则操作组成。设备通过将消息发布到 MQTT 主题来向 AWS IoT 发送信息。利用 SQL SELECT 语句，您可以从传入的 MQTT 消息提取数据。AWS IoT 规则的主题筛选条件用于指定一个或多个 MQTT 主题。当与主题筛选条件匹配的主题收到 MQTT 消息时，规则将被触发。借助规则操作，您可以获取从 MQTT 消息提取的信息并将其发送到其他 AWS 服务。规则操作是针对 Amazon DynamoDB、AWS Lambda、Amazon SNS 和 Amazon S3 等 AWS 服务定义的。使用 Lambda规则，您可以调用其他 AWS 服务或第三方 Web 服务。有关规则操作的完整列表，请参阅 AWS IoT 规则操作 (p. 166)。

这些教程假定您正在使用 AWS IoT 按钮，并将使用 iotbutton/+ 作为规则中的主题筛选条件。如果您没有 AWS IoT 按钮，可在此处购买一个。

或者，您可以通过使用 MQTT 客户端来模拟 AWS IoT 按钮，例如 AWS IoT 控制台中的 AWS IoT MQTT 客户端。要模拟 AWS IoT 按钮，请在 iotbutton/ABCDEFG12345 主题下发布一条类似的消息。“/”后面的数字是随机的。它用作该按钮的序列号。

您也可以使用自己的设备，但必须了解您的设备会将消息发布到哪个 MQTT 主题，以便您可以将其指定为规则中的主题筛选条件。有关更多信息，请参阅 AWS IoT 规则 (p. 157)。

AWS IoT 按钮会发送一个类似于以下示例的 JSON 有效负载：

{ "serialNumber" : "ABCDEFG12345", "batteryVoltage" : "2000mV", "clickType" : "SINGLE"}

创建 DynamoDB 规则借助 DynamoDB 规则，您可以从传入的 MQTT 消息提取信息，并将其写入 DynamoDB 表。

创建 DynamoDB 规则：


45

https://www.amazon.com/All-New-AWS-IoT-Button-Generation/dp/B01KW6YCIM




2. 在 Rules 页面，选择 Create。

3. 在 Create a rule 页面上，在 Name 字段中键入规则名称。在 Description 字段键入规则的说明。

4. 向下滚动至消息源。从 Using SQL version 下拉列表中选择最新版本。在 Attribute 字段键入 *。这将指定您要发送触发了规则的完整 MQTT 消息。

46


5. 规则引擎使用主题筛选条件来确定收到 MQTT 消息时将触发哪些规则。在 Topic filter 字段键入iotbutton/your-button-DSN。如果您当前未使用 AWS IoT 按钮，请键入 my/topic 或规则中使用的主题。

Note

您可以在按钮底部找到 DSN。

将 Condition 留空。


47


7. 在 Select an action 页面，选择 Insert a message into a DynamoDB table，然后选择 Configureaction。

8. 在 Configure action 页面，选择 Create a new resource。

48


9. 在 Amazon DynamoDB 页面，选择 Create table。

10. 在 Create DynamoDB table 页面，在 Table name 字段键入名称。在 Partition key 中键入SerialNumber。选中 Add sort key 复选框，然后在 Sort key 字段键入 ClickType。为分区键和排序键选择 String。

49


11. 选择 Create。创建 DynamoDB 表需要几秒钟时间。关闭打开 Amazon DynamoDB 控制台的浏览器标签。如果您未关闭该标签页，您的 DynamoDB 表将不会显示在 AWS IoT Configure action 页面的 Tablename 下拉列表中。

12. 在 Configure action 页面，从 Table name 下拉列表中选择新表。In Hash Key Value 中，键入${serialNumber}。此操作将指示规则从 MQTT 消息中获取 serialNumber 属性的值，并将其写入 DynamoDB 表中的 SerialNumber 列。In Range Key Value 中，键入 ${clickType}。此操作会将clickType 属性的值写入 ClickType 列。将 Write message data to this column 留空。默认情况下，整条消息都将写入表中名为“Payload”的列。选择 Create a new role。

50


13. 在 IAM role name 中键入唯一的名称，然后再次选择 Create a new role 按钮。选择您刚刚创建的角色，选择 Update role，然后选择 Add action。

14. 选择 Create rule 来创建规则。

51


15. 确认消息将显示规则已创建。选择左箭头返回 Rules 页面。

16. 按一下完成配置的 AWS IoT 按钮，或者使用 MQTT 客户端向与您的规则主题筛选条件匹配的主题发布消息，以测试规则。最后，返回 DynamoDB 控制台并选择您创建的表来查看按钮按压或消息条目。

52

AWS IoT 开发人员指南创建 Lambda 规则

创建 Lambda 规则您可以定义一个规则来调用 Lambda 函数，该函数可传入已触发规则的 MQTT 消息中的数据。如此一来，您可以处理传入的消息，然后调用其他 AWS 服务或第三方服务。

本教程假定您已经完成了 AWS IoT 入门教程 (p. 4)，且您已使用您的手机号码创建并订阅了一个 AmazonSNS 主题。您将创建一个 Lambda 函数，用于向您在 AWS IoT 入门教程 (p. 4)中创建的 Amazon SNS 主题发布消息。此外，您还将创建一个用于调用 Lambda 函数的 Lambda 规则，该函数可以传入已触发规则的MQTT 消息中的一些数据。

本教程还假定您正在使用 AWS IoT 按钮来触发 Lambda 规则。如果您没有 AWS IoT 按钮，您可以在此处购买一个，也可以使用 MQTT 客户端发送触发规则的 MQTT 消息。

创建 Lambda 函数创建 Lambda 函数：

1. 在 AWS Lambda 控制台中，选择 Get Started Now，如果您之前创建过 Lambda 函数，请选择 Createa Lambda function。

53

https://www.amazon.com/dp/B01C7WE5WM


https://console.aws.amazon.com/lambda/home

AWS IoT 开发人员指南创建 Lambda 函数

2. 在 Select blueprint 页面，在 Filter 字段键入 hello-world，然后选择 hello-world 蓝图。

3. 在 Configure triggers 页面，选择 Lambda 图标左侧的框，然后从下拉菜单中选择 AWS IoT。

54


4. 在 Device Serial Number 字段，键入您的按钮的设备序列号 (DSN)。此 DSN 印在 AWS IoT 按钮的背面。如果您尚未给 AWS IoT 按钮生成证书和私有密钥，请选择 Generate certificate and keys。否则，请跳至步骤 6。

55


5. 选择用于下载证书 PEM 和私有密钥的链接。将这些文件保存在计算机中的安全位置。

按照在线说明操作来配置您的 AWS IoT 按钮。6. 确保选中 Enable trigger 复选框，然后选择 Next。

56


7. 在 Configure function 页面上，键入 Lambda 函数的名称和描述。在 Runtime 中，选择 Node.js 6.10。

8. 向下滚动至页面的 Lambda function code 部分。使用以下代码替换现有代码：

console.log('Loading function'); // Load the AWS SDK var AWS = require("aws-sdk"); // Set up the code to call when the Lambda function is invoked exports.handler = (event, context, callback) => { // Load the message passed into the Lambda function into a JSON object var eventText = JSON.stringify(event, null, 2); // Log a message to the console, you can view this text in the Monitoring tab in the Lambda console or in the CloudWatch Logs console console.log("Received event:", eventText); // Create a string extracting the click type and serial number from the message sent by the AWS IoT button var messageText = "Received " + event.clickType + " message from button ID: " + event.serialNumber; // Write the string to the console console.log("Message to send: " + messageText); // Create an SNS object var sns = new AWS.SNS(); // Populate the parameters for the publish operation // - Message : the text of the message to send // - TopicArn : the ARN of the Amazon SNS topic to which you want to publish var params = { Message: messageText, TopicArn: "arn:aws:sns:us-east-1:123456789012:MyIoTButtonSNSTopic" }; sns.publish(params, context.done); };

57


Note

使用您先前创建的 Amazon SNS 主题的 ARN 替换 TopicArn 的值。9. 向下滚动至页面的 Lambda function handler and role 部分。对于 Role，请选择 Create a custom role。

此时 IAM 控制台将打开，您可以创建一个 Lambda 在执行 Lambda 函数时可代入的 IAM 角色。

编辑角色策略以授予该角色向您的 Amazon SNS 主题发布消息的权限：

a. 选择 View Policy Document。

b. 选择 Edit 以编辑角色的策略。

c. 使用以下文档替换当前策略文档：

58


{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "logs:CreateLogGroup", "logs:CreateLogStream", "logs:PutLogEvents" ], "Resource": "arn:aws:logs:*:*:*" }, { "Effect": "Allow", "Action": [ "sns:Publish" ], "Resource": "arn:aws:sns:us-east-1:123456789012:MyIoTButtonSNSTopic" } ]}

该策略文档添加了向您的 Amazon SNS 主题发布消息的权限。

Note

使用您先前创建 Amazon SNS 主题的 ARN 替换第二个 Resource 的值。10. 选择 Allow。

11. 将 Advanced settings 页面中的各项设置保留为默认设置，然后选择 Next。

59


12. 在 Review 页面上，选择 Create function。

60

AWS IoT 开发人员指南测试您的 Lambda 函数

测试您的 Lambda 函数测试 Lambda 函数:

1. 在 Actions 菜单上，选择 Configure test event。

2. 复制以下 JSON 并将其粘贴到 Input test event 页面上，然后选择 Save and test。

{ "serialNumber": "ABCDEFG12345", "clickType": "SINGLE", "batteryVoltage": "2000 mV"}

61

AWS IoT 开发人员指南测试您的 Lambda 函数

3. 在 AWS Lambda 控制台中，滚动至页面底部。Log output 部分将显示 Lambda 函数已写入控制台的输出。

62


创建 Lambda 规则您已经创建了 Lambda 函数，接下来您可以创建用于调用 Lambda 函数的规则。



63



3. 键入规则的名称和描述。

4. 输入以下规则设置：

64



6. 在 Select an action 页面，选择 Invoke a Lambda function passing the message data，然后选择Configure action。

65

AWS IoT 开发人员指南测试您的 Lambda 规则

7. 从 Function name 下拉列表中选择 Lambda 函数名称，然后选择 Add action。

8. 选择 Create rule 来创建您的 Lambda 函数。

测试您的 Lambda 规则本教程假定您已经完成了 AWS IoT 入门教程 (p. 4)，其中包括：

• 配置 AWS IoT 按钮。

66

AWS IoT 开发人员指南测试您的 Lambda 规则

• 使用手机号码创建和订阅 Amazon SNS 主题。

您的按钮已完成配置并连接到 Wi-Fi，且您已经配置了 Amazon SNS 主题，现在您可以按一下按钮来测试您的 Lambda 规则。您的手机应该会收到一条 SMS 文本消息，其中包含：

• 您的按钮的序列号。• 按钮按压类型 (按一下或按两下)。• 电池电压。

该消息的内容应与以下内容类似：

IOT BUTTON> { "serialNumber" : "ABCDEFG12345", "clickType" : "SINGLE", "batteryVoltage" : "2000 mV"}

如果您没有按钮，您可以在此处购买一个，也可以使用 AWS IoT MQTT 客户端作为替代。

1. 在 AWS IoT 控制台中，选择 Test。

2. 在 MQTT client 页面上，在 Publish 部分的 Specify a topic 中键入 iotbutton/ABCDEFG12345。

在 Payload 中，键入以下 JSON，然后选择 Publish to topic。

{ "serialNumber" : "ABCDEFG12345", "clickType" : "SINGLE", "batteryVoltage" : "2000 mV"}

67



AWS IoT 开发人员指南创建 Amazon SNS 规则

3. 您的手机会收到一条消息。

创建 Amazon SNS 规则您可以定义将消息数据发送到 Amazon SNS 主题的规则。在本教程中，您将创建一条规则来将触发该规则的AWS IoT 事物的名称发送到 Amazon SNS 主题的所有订阅者。

使用 SNS 操作创建规则：



68



3. 为您的规则键入名称。

4. 在 Message source 下，为 Attribute 键入 *, topic(3)。对于 Topic filter，请键入 $aws/things/+/shadow/update/accepted。主题筛选条件指定在向其发布消息时触发规则的操作的主题。主题筛选条件中使用的 + 是匹配任何事物名的通配符。此属性将事物名称附加到消息内容中。

69


5. 在 Set one or more actions 选项中，选择 Add action。

6. 在 Select an action 下，选择 Send a message as an SNS push notification，然后选择 Configureaction。(此按钮未显示在屏幕截图中)。

70


7. 选择 Create new topic。

8. 在您的浏览器中打开一个新的选项卡。键入 SNS 主题的名称和描述，然后选择 Create topic。

71


9. 切换到从中打开 AWS IoT 控制台的浏览器选项卡。对于 SNS target，选择您刚刚创建的 SNS 主题。对于 Message format，请选择 JSON。

10. 对于 IAM role name，请选择 Create a new role。

72


11. 键入角色的名称，然后选择 Create a new role。

73


12. 选择您刚刚创建的角色，然后选择 Add action。

74


13. 选择 Create rule。

您现在已创建规则。要测试规则，请将订阅添加到您创建的 SNS 主题，然后更新任何 AWS IoT 事物的影子。您可以使用 AWS IoT 控制台查找事物、打开其详细信息页面和更改设备的影子。Device Shadow 服务在收到变更通知后将在 $aws/things/MySNSThing/shadow/update/accepted 上发布消息。将触发您的规则，并且您的 SNS 主题的所有订阅者都将收到一条包含您的事物的名称的消息。

75

AWS IoT 开发人员指南连接您的 Raspberry Pi

AWS IoT 软件开发工具包教程AWS IoT 设备软件开发工具包帮助您快速轻松地将设备连接至 AWS IoT。AWS IoT 设备软件开发工具包包括开源库、开发人员指南 (含示例) 和移植指南，便于您在自己选择的硬件平台上构建富有创新精神的 IoT 产品或解决方案。

本指南提供分步指导，以帮助您将 Raspberry Pi 连接到 AWS IoT 平台并对其进行设置，以与 AWS IoT 嵌入式 C 软件开发工具包和适用于 Javascript 的设备软件开发工具包配合使用。按照本指南中的步骤执行操作后，您便可以连接到 AWS IoT 平台并运行随这些 AWS IoT 开发工具包附带的示例应用程序。

内容• 连接您的 Raspberry Pi (p. 76)• 使用 AWS IoT 嵌入式 C 软件开发工具包 (p. 85)• 使用适用于 JavaScript 的 AWS IoT 设备软件开发工具包 (p. 87)

连接您的 Raspberry Pi遵循以下步骤将 Raspberry Pi 连接到 AWS IoT 平台。

先决条件• 完全设置的 Raspberry Pi 面板及 Internet 访问

有关设置 Raspberry Pi 的更多信息，请参阅 Raspberry Pi 快速入门指南。• Chrome 或 Firefox (Iceweasel) 浏览器

有关安装 Iceweasel 的更多信息，请参阅有关嵌入式 Linux wiki 的说明。

在本指南中，使用了下列硬件和软件：

• Raspberry Pi 2 Model B• Raspbian Wheezy• Raspbian Jessie• Iceweasel 浏览器

登录 AWS IoT 控制台1. 打开您的 Raspberry Pi 并确认您已连接到 Internet。2. 登录 AWS 管理控制台，并在 https://aws.amazon.com/iot 上打开 AWS IoT 控制台。在 Welcome 页面

上，选择 Get started。

76

https://www.raspberrypi.org/help/quick-start-guide/

http://elinux.org/RPi_IceWeasel#Installing_the_software

https://www.raspberrypi.org/

https://www.raspberrypi.org/downloads/

https://www.raspberrypi.org/downloads/raspbian/

http://elinux.org/RPi_IceWeasel#Installing_the_software

https://aws.amazon.com/iot

AWS IoT 开发人员指南登录 AWS IoT 控制台

3. 如果这是您第一次使用 AWS IoT 控制台，您会看到欢迎使用 AWS IoT 控制台页面。在左侧导航窗格，选择管理来展开选项，然后选择事物。

4. 在提示 You don't have any things yet 的页面上，选择 Register a thing。(如果您之前创建过事物，请选择 Create。)

77

AWS IoT 开发人员指南创建并附加事物（设备）

创建并附加事物（设备）事物代表其状态或数据存储在 AWS 云中的设备。此存储状态或数据称为设备的影子。Device Shadow 服务可以让每台设备的影子保持连接到 AWS IoT。

1. 输入事物的名称，然后选择 Create thing。

2. 在 Details 页面上，选择 Interact。

78


3. 记录 REST API 终端节点。您稍后会需要此值。选择 Security。

4. 选择 Create certificate。这将生成 X.509 证书和密钥对。

79


5. 创建一个名为 deviceSDK 的工作目录，以便在其中存储您的文件。选择相应链接以下载公有和私有密钥、证书以及根 CA，并将其保存在 deviceSDK 目录中。选择 Activate 来激活 X.509 证书，然后选择Attach a policy。

6. 选择 Create new policy。

80


7. 在 Create a policy 页面上，在 Name 字段键入策略的名称。在 Action 字段键入 iot:*。在 ResourceARN 字段中键入 *。选中 Allow 复选框。这样，您的 Raspberry Pi 便可以将向 AWS IoT 发布消息。

8. 选择 Create。

81


9. 选择左箭头返回 Policies 页面。

10. 在左侧导航窗格中，在 Security 下选择 Certificates。

82


11. 在您创建的证书栏，选择 ... 打开下拉菜单，然后选择 Attach policy。

12. 在 Attach policies to certificate(s) 对话框中，选中您已经创建的策略旁边的复选框，然后选择 Attach。

83


13. 在您创建的证书栏，选择 ... 打开下拉菜单，然后选择 Attach thing。

14. 在 Attach things to certificate(s) 对话框，选中您为代表 Raspberry Pi 而创建的事物旁边的复选框，然后选择 Attach。

84

AWS IoT 开发人员指南使用 AWS IoT 嵌入式 C 软件开发工具包

使用 AWS IoT 嵌入式 C 软件开发工具包设置适用于 AWS IoT 嵌入式 C 软件开发工具包的运行时环境1. 从以下 GitHub 存储库下载适用于 C 的 AWS IoT 设备开发工具包：

git clone https://github.com/aws/aws-iot-device-sdk-embedded-C.git -brelease

2. 您必须先从 GitHub 下载所有必需的第三方库，然后才能使用 AWS IoT 嵌入式 C 开发工具包。您可以在deviceSDK/external_libs 文件夹中找到执行该操作的说明。

示例应用程序配置AWS IoT 嵌入式 C 软件开发工具包包括示例应用程序以供您试用。为简便起见，我们将运行subscribe_publish_sample。

1. 将您的证书、私有密钥和根 CA 证书复制到 deviceSDK/certs 目录。

如果您未得到根 CA 证书的副本，您可以在此处下载。从浏览器复制根 CA 文本，将其粘贴到文件中，然后将其复制到 deviceSDK/certs 目录中。

Note

设备和根 CA 证书可能会过期或被吊销。如果出现这种情况，您必须将新的 CA 证书或私有密钥和设备证书复制到您的设备上。

2. 导航到 deviceSDK/sample_apps/subscribe_publish_sample 目录。您必须配置个人终端节点、私有密钥和证书。私有终端节点是您之前记下的 REST API 终端节点。如果忘记了终端节点，并且您有权访问安装有 AWS CLI 的设备，您可以使用 aws iot describe-endpoint 命令查找您的私有终端节点 URL。转至 AWS IoT 控制台。选择 Registry，选择 Things，然后选择代表 Raspberry Pi 的事物。在事物的 Details 页面上，在左侧导航窗格中，选择 Interact。复制所有内容，包括 REST API 终端节点中的“.com”。

85

https://www.symantec.com/content/en/us/enterprise/verisign/roots/VeriSign-Class%203-Public-Primary-Certification-Authority-G5.pem

AWS IoT 开发人员指南运行示例应用程序

3. 打开 aws_iot_config.h 文件并在 //Get from console 部分更新以下各项的值：

AWS_IOT_MQTT_HOST

您的私有终端节点。AWS_IOT_MY_THING_NAME

您的事物名称。AWS_IOT_ROOT_CA_FILENAME

您的根 CA 证书。AWS_IOT_CERTIFICATE_FILENAME

您的证书。AWS_IOT_PRIVATE_KEY_FILENAME

您的私有密钥。

例如：

// Get from console// =================================================#define AWS_IOT_MQTT_HOST "a22j5sm6o3yzc5.iot.us-east-1.amazonaws.com"#define AWS_IOT_MQTT_PORT 8883#define AWS_IOT_MQTT_CLIENT_ID "MyRaspberryPi"#define AWS_IOT_MY_THING_NAME "MyRaspberryPi"#define AWS_IOT_ROOT_CA_FILENAME "root-CA.crt"#define AWS_IOT_CERTIFICATE_FILENAME "4bbdc778b9-certificate.pem.crt"#define AWS_IOT_PRIVATE_KEY_FILENAME "4bbdc778b9-private.pem.key"// =================================================

运行示例应用程序1. 使用包含的生成文件编译 subscribe_publish_sample_app。

make -f Makefile

86

AWS IoT 开发人员指南使用适用于 JavaScript 的 AWS IoT 设备软件开发工具包

此操作将生成可执行的文件。

2. 现在运行 subscribe_publish_sample_app。您应该可以看到类似于如下所示的输出内容：

您的 Raspberry Pi 现已通过适用于 C 的 AWS IoT 设备软件开发工具包连接到 AWS IoT。

使用适用于 JavaScript 的 AWS IoT 设备软件开发工具包

安装适用于 Node.js 的 AWS IoT 设备软件开发工具包最简单的方式是使用 npm。在本部分我们将介绍如何安装 Node 和 npm。

87

AWS IoT 开发人员指南设置适用于 JavaScript 的 AWS IoT设备软件开发工具包的运行时环境

设置适用于 JavaScript 的 AWS IoT 设备软件开发工具包的运行时环境要使用适用于 JavaScript 的 AWS IoT 设备开发工具包，请在 Raspberry Pi 上安装 Node 和 npm 开发工具。默认情况下，未安装这些软件包。

Note

在继续下一步之前，您可能希望为您的 Raspberry Pi 配置键盘映射。有关更多信息，请参阅配置Raspberry Pi 键盘映射。

1. 要添加 Node 存储库，请打开一个终端并运行以下命令：

curl -sL https://deb.nodesource.com/setup_8.x | sudo -E bash -

2. 要安装 Node，请运行

sudo apt-get install nodejs

3. 运行 npm -v 以确定是否安装了 npm。如果未返回任何版本信息，则按照以下说明安装 npm：

sudo apt-get install npm

您应该可以看到类似于如下所示的输出内容：

4. 要验证 Node 和 npm 的安装情况，请运行以下命令：

node -v

和

npm -v

您应该可以看到类似于如下所示的输出内容：

88

https://www.raspberrypi.org/documentation/configuration/localisation.md

https://www.raspberrypi.org/documentation/configuration/localisation.md

AWS IoT 开发人员指南安装适用于 JavaScript 的 AWS IoT 设备软件开发工具包

安装适用于 JavaScript 的 AWS IoT 设备软件开发工具包要在您的 Raspberry Pi 中安装适用于 JavaScript/Node.js 的 AWS IoT 设备软件开发工具包，请打开控制台窗口，并从 ~/deviceSDK 目录中使用 npm 来安装软件开发工具包：

npm install aws-iot-device-sdk

在安装完成后，~/deviceSDK 目录下应该有一个 node_modules 目录。

准备运行示例应用程序适用于 JavaScript 的 AWS IoT 设备软件开发工具包包括示例应用程序以供您试用。要运行它们，您必须配置证书和私有密钥。

编辑文件 ~/deviceSDK/node_modules/aws-iot-device-sdk/examples/lib/cmdline.js 可更改各示例中私有密钥(privateKey)、证书 (clientCert) 和 CA 根证书 (caCert) 的默认名称。例如：

default: { region: 'us-east-1', clientId: clientIdDefault, privateKey: '4bbdc778b9-private.pem.key', clientCert: '4bbdc778b9-certificate.pem.crt', caCert: 'root-CA.crt, testMode: 1, reconnectPeriod: 3 * 1000, /* milliseconds */ delay: 4 * 1000 /* milliseconds */ };

运行示例应用程序使用以下命令运行示例

89

AWS IoT 开发人员指南运行示例应用程序

node examples/<YourDesiredExample>.js -f <certs location> -H <PREFIX>.iot.<REGION>.amazonaws.com

假定您在 ~/deviceSDK/node_modules/aws-iot-device-sdk/ 目录中，则证书位置为 ~/deviceSDK/certs/。使用 Raspberry Pi 的 ARN 作为 -H 参数的值。

要查看每个示例的所有可用命令行参数，请运行该程序并指定“h”参数：

node examples/<YourDesiredExample>.js -h

有关如何使用命令行选项指定证书位置和您自己的主机地址的更多信息，请参阅 GitHub 上的“适用于JavaScript 的 AWS IoT 设备软件开发工具包”自述文件的证书部分。自述文件中的此部分后面的示例说明显示了每个示例所需的附加命令行参数。

如果您想创建与命令行选项 --configuration-file (-F) 配合使用的配置文件，请创建包含以下属性的文件 (JSON 格式)。例如：

{ "host": "a22j5sm6o3yzc5.iot.us-east-1.amazonaws.com", "port": 8883, "clientId": "MyRaspberryPi", "thingName": "MyRaspberryPi", "caCert": "root-CA.crt", "clientCert": "4bbdc778b9-certificate.pem.crt", "privateKey": "4bbdc778b9-private.pem.key"}

您的 Raspberry Pi 现已通过适用于 JavaScript 的 AWS IoT 设备软件开发工具包连接到 AWS IoT。

90

https://github.com/aws/aws-iot-device-sdk-js#certificates

AWS IoT 开发人员指南如何使用注册表管理事物

使用 AWS IoT 管理设备AWS IoT 提供了注册表来帮助您管理事物。事物是特定设备或逻辑实体的表示形式。它可以是物理设备或传感器（例如，灯泡或墙壁上的开关）。此外，它也可以是逻辑实体（如应用程序实例），或没有连接到但与其他连接到 AWS IoT 的设备相关的物理实体（例如，装有发动机传感器的汽车或控制面板）。

事物的相关信息均以 JSON 数据形式存储在 Registry 中。以下是一个事物示例：

{ "version": 3, "thingName": "MyLightBulb", "defaultClientId": "MyLightBulb", "thingTypeName": "LightBulb", "attributes": { "model": "123", "wattage": "75" }}

事物由名称进行标识。此外，事物还可以具有名称-值对形式的属性，您可以利用这些属性存储事物的相关信息，如事物的序列号或制造商。

典型的设备使用案例使用事物名称作为默认的 MQTT 客户端 ID。虽然我们没有强制在事物的注册表名称和它使用的 MQTT 客户端 ID、证书或影子状态之间进行映射，但建议您选择一个事物名称，并将其同时用作注册表和 Device Shadow 服务的 MQTT 客户端 ID。这不仅为您的 IoT 队列带来了有序性和便利性，还保留了基础设备证书模型或影子的灵活性。

您无需在注册表中创建事物便能将设备连接到 AWS IoT。将事物添加到注册表可让您更轻松地管理和搜索设备。

如何使用注册表管理事物您可以使用 AWS IoT 控制台或 AWS CLI 与 Thing Registry 进行交互。以下各部分展示了如何使用 CLI 与Registry 进行交互。

创建事物以下命令说明了如何使用 AWS IoT CreateThing 命令从 CLI 创建事物：

$ aws iot create-thing --thing-name "MyLightBulb" --attribute-payload "{\"attributes\": {\"wattage\":\"75\", \"model\":\"123\"}}"

CreateThing 命令会显示新事物的名称和 ARN：

{ "thingArn": "arn:aws:iot:us-east-1:123456789012:thing/MyLightBulb", "thingName": "MyLightBulb" "thingId": "12345678abcdefgh12345678ijklmnop12345678"}

91

AWS IoT 开发人员指南列出事物

列出事物您可以使用 ListThings 命令列出您的账户中的所有事物：

$ aws iot list-things{ "things": [ { "attributes": { "model": "123", "wattage": "75" }, "version": 1, "thingName": "MyLightBulb" }, { "attributes": { "numOfStates":"3" }, "version": 11, "thingName": "MyWallSwitch" } ]}

搜索事物您可以使用 DescribeThing 命令列出某个事物的相关信息：

$ aws iot describe-thing --thing-name "MyLightBulb"{ "version": 3, "thingName": "MyLightBulb", "thingArn": "arn:aws:iot:us-east-1:123456789012:thing/MyLightBulb", "thingId": "12345678abcdefgh12345678ijklmnop12345678" "defaultClientId": "MyLightBulb", "thingTypeName": "StopLight", "attributes": { "model": "123", "wattage": "75" }}

您可以使用 ListThings 命令搜索与某个事物类型名称相关联的所有事物：

$ aws iot list-things --thing-type-name "LightBulb"

{ "things": [ { "thingTypeName": "LightBulb", "attributes": { "model": "123", "wattage": "75" }, "version": 1, "thingName": "MyRGBLight" },

92

AWS IoT 开发人员指南更新事物

{ "thingTypeName": "LightBulb", "attributes": { "model": "123", "wattage": "75" }, "version": 1, "thingName": "MySecondLightBulb" } ]}

您可以使用 ListThings 命令搜索某个属性为特定值的所有事物：

$ aws iot list-things --attribute-name "wattage" --attribute-value "75"

{ "things": [ { "thingTypeName": "StopLight", "attributes": { "model": "123", "wattage": "75" }, "version": 3, "thingName": "MyLightBulb" }, { "thingTypeName": "LightBulb", "attributes": { "model": "123", "wattage": "75" }, "version": 1, "thingName": "MyRGBLight" }, { "thingTypeName": "LightBulb", "attributes": { "model": "123", "wattage": "75" }, "version": 1, "thingName": "MySecondLightBulb" } ]}

更新事物您可以使用 UpdateThing 命令更新事物：

$ aws iot update-thing --thing-name "MyLightBulb" --attribute-payload "{\"attributes\": {\"wattage\":\"150\", \"model\":\"456\"}}"

UpdateThing 命令不会生成任何输出。您可以使用 DescribeThing 命令查看结果：

$ aws iot describe-thing --thing-name "MyLightBulb"

93

AWS IoT 开发人员指南删除事物

{ "attributes": { "model": "456", "wattage": "150" }, "version": 2, "thingName": "MyLightBulb"}

删除事物您可以使用 DeleteThing 命令删除事物：

$ aws iot delete-thing --thing-name "MyThing"

将委托人附加到事物物理设备必须具有 X.509 证书才能与 AWS IoT 通信。您可以将设备上的证书与 Registry 中代表该设备的事物关联。要将证书附加到您的事物，请使用 AttachThingPrincipal 命令：

$ aws iot attach-thing-principal --thing-name "MyLightBulb" --principal "arn:aws:iot:us-east-1:123456789012:cert/a0c01f5835079de0a7514643d68ef8414ab739a1e94ee4162977b02b12842847"

AttachThingPrincipal 命令不会生成任何输出。

将委托人与事物分离您可以使用 DetachThingPrincipal 命令将证书与事物分离：

$ aws iot detach-thing-principal --thing-name "MyLightBulb" --principal "arn:aws:iot:us-east-1:123456789012:cert/a0c01f5835079de0a7514643d68ef8414ab739a1e94ee4162977b02b12842847"

DetachThingPrincipal 命令不会生成任何输出。

事物类型通过定义事物类型，您可以存储与同一事物类型相关联的所有事物共有的描述和配置信息，这将简化Registry 中的事物管理。例如，您可以定义 LightBulb 事物类型。所有与 LightBulb 事物类型相关联的事物均具有一组共同的属性：序列号、制造商和功率。创建 LightBulb 类型的事物（或将现有事物的类型更改为LightBulb）时，您可以指定在 LightBulb 事物类型中定义的每个属性的值。

虽然事物类型是可选项，但使用它们可以更容易地搜索事物。

• 具有事物类型的事物最多可以具有 50 个属性。• 未设置事物类型的事物最多可以具有三个属性。• 一个事物只能与一种事物类型相关联。• 在账户中可以创建的事物类型数量不限。

事物类型是不可变的。事物类型名称一旦创建，便不可更改。您随时可以弃用某事物类型，以防止新事物与之关联。您也可以删除没有与任何事物关联的事物类型。

94

AWS IoT 开发人员指南创建事物类型

创建事物类型您可以使用 CreateThingType 命令创建事物类型：

$ aws iot create-thing-type

--thing-type-name "LightBulb" --thing-type-properties "thingTypeDescription=light bulb type, searchableAttributes=wattage,model"

CreateThingType 命令会返回一个含有事物类型及其 ARN 的响应：

{ "thingTypeName": "LightBulb", "thingTypeArn": "arn:aws:iot:us-west-2:123456789012:thingtype/LightBulb"}

列出事物类型您可以使用 ListThingTypes 命令列出事物类型：

$ aws iot list-thing-types

ListThingTypes 命令会返回一个列有您的 AWS 账户中定义的事物类型的列表：

{ "thingTypes": [ { "thingTypeName": "LightBulb", "thingTypeProperties": { "searchableAttributes": [ "wattage", "model" ], "thingTypeDescription": "light bulb type" }, "thingTypeMetadata": { "deprecated": false, "creationDate": 1468423800950 } } ]}

描述事物类型您可以使用 DescribeThingType 命令获取某事物类型的相关信息：

$ aws iot describe-thing-type --thing-type-name "LightBulb"

DescribeThingType 命令会使用指定类型的相关信息做出响应：

{ "thingTypeName": "LightBulb", "thingTypeProperties": { "searchableAttributes": [ "wattage",

95

AWS IoT 开发人员指南将事物类型与事物相关联

"model" ], "thingTypeDescription": "light bulb type" }, "thingTypeMetadata": { "deprecated": false, "creationDate": 1468423800950, }}

将事物类型与事物相关联创建事物时，可以使用 CreateThing 命令指定事物类型：

$ aws iot create-thing --thing-name "MySecondLightBulb" --thing-type-name "LightBulb" --attribute-payload "{\"attributes\": {\"wattage\":\"75\", \"model\":\"123\"}}"

您随时可以使用 UpdateThing 命令更改与某个事物关联的事物类型：

$ aws iot update-thing --thing-name "MyLightBulb" --thing-type-name "StopLight" --attribute-payload "{\"attributes\": {\"wattage\":\"75\", \"model\":\"123\"}}"

您还可以使用 UpdateThing 命令取消事物与事物类型之间的关联。

弃用事物类型事物类型是不可变的。一旦定义了事务类型，便不可更改。然而，您可以通过弃用某种事物类型来防止用户将新事物与之关联。所有与该事物类型相关联的现有事物将保持不变。

要弃用某事物类型，请使用 DeprecateThingType 命令：

$ aws iot deprecate-thing-type --thing-type-name "myThingType"

您可以使用 DescribeThingType 命令查看结果：

$ aws iot describe-thing-type --thing-type-name "StopLight":

{ "thingTypeName": "StopLight", "thingTypeProperties": { "searchableAttributes": [ "wattage", "numOfLights", "model" ], "thingTypeDescription": "traffic light type", }, "thingTypeMetadata": { "deprecated": true, "creationDate": 1468425854308, "deprecationDate": 1468446026349 }}

弃用事物类型是可逆操作。您可以通过在 DeprecateThingType CLI 命令中使用 --undo-deprecate 标志来撤消弃用：

96

AWS IoT 开发人员指南删除事物类型

$ aws iot deprecate-thing-type --thing-type-name "myThingType" --undo-deprecate

您可以使用 DescribeThingType CLI 命令查看结果：

$ aws iot describe-thing-type --thing-type-name "StopLight":

{ "thingTypeName": "StopLight", "thingTypeArn": "arn:aws:iot:us-east-1:123456789012:thingtype/StopLight", "thingTypeId": "12345678abcdefgh12345678ijklmnop12345678" "thingTypeProperties": { "searchableAttributes": [ "wattage", "numOfLights", "model" ], "thingTypeDescription": "traffic light type" }, "thingTypeMetadata": { "deprecated": false, "creationDate": 1468425854308, }}

删除事物类型只有在弃用事物类型后，才能将其删除。要删除某事物类型，请使用 DeleteThingType 命令：

$ aws iot delete-thing-type --thing-type-name "StopLight"

Note

弃用某事物类型后，必须等待 5 分钟，然后才能将其删除。

事物组通过将事物分类形成组，能够使用事物组同时管理几个事物。组中还可以包含组 - 您可以构建组的层次结构。您可以将策略附加到某个父组，该策略将由其所有子组和该组及其子组中的所有事物继承。这使得控制大量事物的权限非常简单。

下面是您可以对事物组执行的操作：

• 创建、描述或删除组。• 将事物添加到一个或多个组。• 从组中删除事物。• 列出您已创建的组。• 列出组的所有子组 (其直接和间接后代)。• 列出组中的事物，包括其子组中的所有事物。• 列出组的所有原级组 (其直接和间接父级)。• 添加、删除或更新组的属性。(属性是您可用于存储与组相关的信息的名称/值对。)• 从组中附加或分离策略。

97

AWS IoT 开发人员指南创建事物组

• 列出附加到组的策略。• 列出由某个事物继承的策略 (借助附加到其组或其父组之一的策略)。• 为组中的事物配置日志记录选项 (请参阅配置 AWS IoT 日志记录 (p. 356))。• 创建将发送到某个组及其子组中的所有事物并在这些事物上执行的任务 (请参阅工作 (p. 251)。

下面是事物组的一些限制：

• 如果一个组将是另一个组的子组，则必须在创建该子组时指定这一关系。• 您不能在之后更改组的父组。(因此，务必先规划组的层次结构并创建父组，然后再创建父组中将包含的任

何子组。)• 您无法将一个事物添加到超过 10 个组中。• 您无法将事物添加到相同层次结构的多个组中。(换而言之，您无法将事物添加到共享相同父级的两个组

中。)• 您无法重命名组。

在组上附加和分离策略能够以多种非常有效的方式增强 AWS IoT 操作的安全性。针对各个设备将策略附加到证书、然后附加到事物的方法非常费时，并且难于在整个设备机群中快速更新或更改策略。在需要轮换某个事物上的证书时，将策略附加到事物的组可以节省步骤。并且，在更改组成员资格时，策略会动态应用到事物，因此您无需在每次组中设备成员资格更改时重新创建复杂的权限集。

创建事物组您可以使用 CreateThingGroup 命令创建事物组：

$ aws iot create-thing-group --thing-group-name LightBulbs

CreateThingGroup 命令会返回一个包含事物组、其 ID 及其 ARN 的响应：

{ "thingGroupName": "LightBulbs", "thingGroupId": "abcdefgh12345678ijklmnop12345678qrstuvwx", "thingGroupArn": "arn:aws:iot:us-west-2:123456789012:thinggroup/LightBulbs"}

以下示例在创建事物组时指定其父级：

$ aws iot create-thing-group --thing-group-name RedLights --parent-group-name LightBulbs

如前，CreateThingGroup 命令会返回一个包含事物组及其 ID 和 ARN 的响应：

{ "thingGroupName": "RedLights", "thingGroupId": "abcdefgh12345678ijklmnop12345678qrstuvwx", "thingGroupArn": "arn:aws:iot:us-west-2:123456789012:thinggroup/RedLights",}

Important

创建组层次结构时，请注意以下限制：

• 一个组最多可以有一个直接父级。• 一个组不能有超过 100 个直接子组。

98

AWS IoT 开发人员指南描述事物组

• 组层次结构的最大深度为 7。• 一个组最多可以具有 50 个属性。(属性是您可用于存储与组相关的信息的名称/值对。) 每个属性

名称最多可包含 128 个字符，每个值最多可以包含 800 个字符。

描述事物组您可以使用 DescribeThingGroup 命令获取某事物组的相关信息：

$ aws iot describe-thing-group --thing-group-name RedLights

DescribeThingGroup 命令会使用指定组的相关信息做出响应：

{ "thingGroupName": "RedLights", "thingGroupArn": "arn:aws:iot:us-west-2:123456789012:thinggroup/RedLights", "thingGroupId": "12345678abcdefgh12345678ijklmnop12345678", "version": 1, "thingGroupMetadata": { "creationDate": 1478299948.882 "parentGroupName": "Lights", "rootToParentThingGroups": [ { "groupArn": "arn:aws:iot:us-west-2:123456789012:thinggroup/ShinyObjects", "groupName": "ShinyObjects" }, { "groupArn": "arn:aws:iot:us-west-2:123456789012:thinggroup/LightBulbs", "groupName": "LightBulbs" } ] }, "thingGroupProperties": { "attributePayload": { "attributes": { "brightness": "3400 lumens" }, }, "thingGroupDescription": "string" },}

将事物添加到事物组您可以使用 AddThingToThingGroup 命令将事物添加到事物组：

$ aws iot add-thing-to-thing-group --thing-name MyLightBulb --thing-group-name RedLights

AddThingToThingGroup 命令不会生成任何输出。Important

您可以将事物添加到最多 10 个组。但是，您无法将事物添加到相同层次结构的多个组中。(换而言之，您无法将事物添加到共享相同父级的两个组中。)

从事物组中删除此事物您可以使用 RemoveThingFromThingGroup 命令从组中删除事物：

99

AWS IoT 开发人员指南列出事物组中的事物

$ aws iot remove-thing-from-thing-group --thing-name MyLightBulb --thing-group-name RedLights

RemoveThingFromThingGroup 命令不会生成任何输出。

列出事物组中的事物您可以使用 ListThingsInThingGroup 命令列出属于某个组的事物：

$ aws iot list-things-in-thing-group --thing-group-name LightBulbs

ListThingsInThingGroup 命令返回指定组中的事物列表：

{ "things":[ "TestThingA" ]}

使用 --recursive 参数，您可以列出属于某个组及其所有子组中的事物：

$ aws iot list-things-in-thing-group --thing-group-name LightBulbs --recursive

{ "things":[ "TestThingA", "MyLightBulb" ]}

Note

此操作具有最终一致性，也就是说对事物组的更改可能不会立即体现。

列出事物组您可以使用 ListThingGroups 命令列出已创建的组：

$ aws iot list-thing-groups

ListThingGroups 命令会返回在您的 AWS 账户中定义的组的列表：

{ "thingGroups": [ { "groupName": "LightBulbs", "groupArn": "arn:aws:iot:us-west-2:123456789012:thinggroup/LightBulbs" }, { "groupName": "RedLights", "groupArn": "arn:aws:iot:us-west-2:123456789012:thinggroup/RedLights" }, { "groupName": "RedLEDLights",

100

https://web.stanford.edu/class/cs345d-01/rl/eventually-consistent.pdf

AWS IoT 开发人员指南列出事物组

"groupArn": "arn:aws:iot:us-west-2:123456789012:thinggroup/RedLEDLights" }, { "groupName": "RedIncandescentLights", "groupArn": "arn:aws:iot:us-west-2:123456789012:thinggroup/RedIncandescentLights" } { "groupName": "ReplaceableObjects", "groupArn": "arn:aws:iot:us-west-2:123456789012:thinggroup/ReplaceableObjects" } ]}

使用可选的筛选条件列出具有指定组作为父级 (--parent-group) 的组，或者名称以指定前缀 (--name-prefix-filter) 开头的组。使用 --recursive 参数还可以列出所有子组，而不仅仅是事物组的直接子组：

$ aws iot list-thing-groups --parent-group LightBulbs

在这种情况下，ListThingGroups 命令返回在您的 AWS 账户中定义的事物组的直接子组列表：

{ "childGroups":[ { "groupName": "RedLights", "groupArn": "arn:aws:iot:us-west-2:123456789012:thinggroup/RedLights" } ]}

将 --recursive 参数与 ListThingGroups 命令结合使用可以列出事物组的所有子组，而不仅仅是直接子组：

$ aws iot list-thing-groups --parent-group LightBulbs --recursive

ListThingGroups 命令返回事物组的所有子组的列表：

{ "childGroups":[ { "groupName": "RedLights", "groupArn": "arn:aws:iot:us-west-2:123456789012:thinggroup/RedLights" }, { "groupName": "RedLEDLights", "groupArn": "arn:aws:iot:us-west-2:123456789012:thinggroup/RedLEDLights" }, { "groupName": "RedIncandescentLights", "groupArn": "arn:aws:iot:us-west-2:123456789012:thinggroup/RedIncandescentLights" } ]}

Note

此操作具有最终一致性，也就是说对事物组的更改可能不会立即体现。

101

https://web.stanford.edu/class/cs345d-01/rl/eventually-consistent.pdf

AWS IoT 开发人员指南列出事物的组

列出事物的组您可以使用 ListThingGroupsForThing 命令列出某个事物所属的组，包括任何父组：

$ aws iot list-thing-groups-for-thing --thing-name MyLightBulb

ListThingGroupsForThing 命令返回此事物所属的事物组列表，包括任何父组：

{ "thingGroups":[ { "groupName": "LightBulbs", "groupArn": "arn:aws:iot:us-west-2:123456789012:thinggroup/LightBulbs" }, { "groupName": "RedLights", "groupArn": "arn:aws:iot:us-west-2:123456789012:thinggroup/RedLights" }, { "groupName": "ReplaceableObjects", "groupArn": "arn:aws:iot:us-west-2:123456789012:thinggroup/ReplaceableObjects" } ]}

更新事物组您可以使用 UpdateThingGroup 命令更新事物组的属性：

$ aws iot update-thing-group --thing-group-name "LightBulbs" --thing-group-properties "thingGroupDescription=\"this is a test group\", attributePayload=\"{\"attributes\"={\"Owner\"=\"150\",\"modelNames\"=\"456\"}}"

UpdateThingGroup 命令返回一个响应，其中包含该组更新后的版本号：

{ "version": 4}

Note

一个组最多可以具有 50 个属性。

删除事物组要删除事物组，请使用 DeleteThingGroup 命令：

$ aws iot delete-thing-group --thing-group-name "RedLights"

DeleteThingGroup 命令不会生成任何输出。

Important

如果您尝试删除具有子事物组的事物组，这将生成错误：

102

AWS IoT 开发人员指南将策略附加到事物组

A client error (InvalidRequestException) occurred when calling the DeleteThingGroup operation: Cannot delete thing group : RedLights when there are still child groups attached to it.

您必须先删除所有子组，然后再删除该组。

您可以删除具有子事物的组，但由组中的成员资格授予该事物的任何权限将不再适用。删除附加了策略的组之前，请认真检查，确保移除这些权限不会导致组中的事物无法正常运行。此外请注意，在更新云中的记录时，显示事物所属的组的命令 (例如，ListGroupsForThing) 可能会继续显示该组。

将策略附加到事物组您可以使用 AttachPolicy 命令将策略附加到事物组，这样可以扩展到该组中的所有事物及其所有子组中的事物：

$ aws iot attach-policy \ --target "arn:aws:iot:us-west-2:123456789012:thinggroup/LightBulbs" \ --policy-name "myLightBulbPolicy"

AttachPolicy 命令不会生成任何输出Important

可以附加到单个组上的最大策略数为 2。

--target 参数可以是事物组 ARN (如上所示)、证书 ARN 或 Amazon Cognito 身份。有关策略、证书和身份验证的更多信息，请参阅 AWS IoT 的安全和身份 (p. 106)。

从事物组分离策略您可以使用 DetachPolicy 命令从组中分离策略，这样会更进一步地从该组中的所有事物及其所有子组中的事物分离：

$ aws iot detach-policy --target "arn:aws:iot:us-west-2:123456789012:thinggroup/LightBulbs" --policy-name "myLightBulbPolicy"

DetachPolicy 命令不会生成任何输出。

列出附加到事物组的策略您可以使用 ListAttachedPolicies 命令列出附加到组的策略：

$ aws iot list-attached-policies --target "arn:aws:iot:us-west-2:123456789012:thinggroup/RedLights"

--target 参数可以是事物组 ARN (如上所示)、证书 ARN 或 Amazon Cognito 身份。

添加可选的 --recursive 参数还可以包括附加到组的父组的所有策略。

ListAttachedPolicies 命令返回策略列表：

{ "policies": [ "MyLightBulbPolicy" ...

103

AWS IoT 开发人员指南列出策略的组

]}

列出策略的组您可以使用 ListTargetsForPolicy 命令列出策略附加到的目标，包括任何组：

$ aws iot list-targets-for-policy --policy-name "MyLightBulbPolicy"

添加可选的 --page-size number 参数以指定为每个查询返回的最大结果数，并在后续调用上添加 --marker string 参数以检索下一组结果 (如果有)。

ListTargetsForPolicy 命令返回目标的列表以及用于检索更多结果的令牌：

{ "nextMarker": "string", "targets": [ "string" ... ]}

获取事物的有效策略您可以使用 GetEffectivePolicies 命令列出对事物生效的策略，包括附加到事物所属任意组的策略 (不论该组是直接父组还是间接原级)：

$ aws iot get-effective-policies \ --thing-name "MyLightBulb" \ --principal "arn:aws:iot:us-east-1:123456789012:cert/a0c01f5835079de0a7514643d68ef8414ab739a1e94ee4162977b02b12842847"

使用 --principal 参数指定附加到事物的证书的 ARN。如果您使用的是 Amazon Cognito 身份验证，请使用 --cognito-identity-pool-id 参数，并 (可选) 添加 --principal 参数来指定特定 Cognito 身份。如果您仅指定 --cognito-identity-pool-id，则返回未经身份验证用户的与该身份池角色关联的策略。如果同时使用两个参数，则返回经过身份验证用户的与该身份池角色关联的策略。

--thing-name 参数是可选的，可用于替代 --principal 参数。在使用时，将返回附加到事物所属任意组的策略以及附加到这些组的任意父组 (向上直至层次结构中的根组) 的策略。

GetEffectivePolicies 命令返回策略列表：

{ "effectivePolicies": [ { "policyArn": "string", "policyDocument": "string", "policyName": "string" } ... ]}

测试 MQTT 操作的授权您可以使用 TestAuthorization 命令测试某个事物是否允许 MQTT 操作：

$ aws iot test-authorization \

104

AWS IoT 开发人员指南测试 MQTT 操作的授权

--principal "arn:aws:iot:us-east-1:123456789012:cert/a0c01f5835079de0a7514643d68ef8414ab739a1e94ee4162977b02b12842847" \ --auth-infos "[ \"actionType": \"PUBLISH\", \"resources\": [ \"arn:aws:iot:us-east-1:123456789012:topic/iotButton/G030JF053216F1BS\" ] ]"

使用 --principal 参数指定附加到事物的证书的 ARN。如果使用 Amazon Cognito 身份验证，请指定Cognito 身份作为 --principal 并且/或者使用 --cognito-identity-pool-id 参数。如果您仅指定--cognito-identity-pool-id，则考虑未经身份验证用户的与该身份池角色关联的策略。如果同时使用两个参数，则考虑经过身份验证用户的与该身份池角色关联的策略。

通过列出资源和操作类型的组，并且后跟 --auth-infos 参数，来指定一个或多个要测试的 MQTT 操作。actionType 字段应包含“PUBLISH”、“SUBSCRIBE”、“RECEIVE”或“CONNECT”。resources 字段应包含资源 ARN 的列表。参阅 AWS IoT 策略 (p. 118) 了解更多信息。

您可以通过将这些参数与 --policy-names-to-add 参数一起指定，测试添加策略的效果。或者，您可以通过 --policy-names-to-skip 参数来测试移除这些策略的效果。

您可以使用可选的 --client-id 参数来进一步优化结果。

TestAuthorization 命令返回您指定的每组 --auth-infos 查询允许或拒绝的操作的详细信息：

{ "authResults": [ { "allowed": { "policies": [ { "policyArn": "string", "policyName": "string" } ] }, "authDecision": "string", "authInfo": { "actionType": "string", "resources": [ "string" ] }, "denied": { "explicitDeny": { "policies": [ { "policyArn": "string", "policyName": "string" } ] }, "implicitDeny": { "policies": [ { "policyArn": "string", "policyName": "string" } ] } }, "missingContextValues": [ "string" ] } ]}

105

AWS IoT 开发人员指南AWS IoT 身份验证

AWS IoT 的安全和身份每台连接的设备都必须拥有凭证才能访问消息代理或 Device Shadow 服务。对于往返 AWS IoT 的所有流量，都必须通过传输层安全性 (TLS) 进行加密。必须保证设备凭证的安全，以便安全地将数据发送到消息代理。数据在 AWS IoT 和其他设备或 AWS 服务之间移动时，AWS 云安全机制可为数据提供保护。

• 您负责管理设备上的设备凭证（X.509 凭证、AWS 凭证）及 AWS IoT 中的策略。您负责将唯一身份分配给每台设备并管理设备或设备组的权限。

• 设备将根据 AWS IoT 连接模式，使用您选择的身份 (X.509 证书、IAM 用户和组、Amazon Cognito 身份或自定义身份验证令牌) 通过安全连接来建立连接。

• 在使用 AWS IoT 身份验证时，消息代理针对账户内的所有操作执行身份验证和授权。消息代理负责对设备执行身份验证、安全地接收设备数据，以及支持您通过策略授予设备的访问权限。

• 在使用自定义身份验证时，自定义授权方负责对您的设备执行身份验证，并提供 AWS IoT/IAM 策略以对您账户中的操作进行授权。

• AWS IoT 规则引擎根据您定义的规则将设备数据转发到其他设备和其他 AWS 服务。它使用 AWS 访问管理系统将数据安全地传输到最终目的地。

AWS IoT 身份验证AWS IoT 支持使用四种身份委托人进行身份验证：

• X.509 证书• IAM 用户、组和角色• Amazon Cognito 身份• 联合身份

这些身份可用于移动应用程序、Web 应用程序或桌面应用程序。它们甚至可由键入 AWS IoT CLI 命令的用户使用。通常，AWS IoT 设备使用 X.509 证书，移动应用程序使用 Amazon Cognito 身份。Web 和桌面应用程序使用 IAM 或联合身份。CLI 命令使用 IAM。

X.509 证书X.509 证书属于数字证书，它按照 X.509 公有密钥基础设施标准将公有密钥与证书所含的身份相关联。X.509 证书由一家名为证书颁发机构 (CA) 的可信实体颁发。CA 持有一个或多个名为 CA 证书的特殊证书，它使用这种证书来颁发 X.509 证书。只有证书颁发机构才有权访问 CA 证书。

106

AWS IoT 开发人员指南X.509 证书

Note

我们建议为每个设备提供一个唯一的证书，以便进行精细的管理，包括证书吊销。设备必须支持轮换和更换证书，以确保证书过期时仍能顺畅运行。

AWS IoT 支持以下证书签名算法：

• SHA256WITHRSA• SHA384WITHRSA• SHA384WITHRSA• SHA512WITHRSA• RSASSAPSS• DSA_WITH_SHA256• ECDSA-WITH-SHA256• ECDSA-WITH-SHA384• ECDSA-WITH-SHA512

与其他身份和身份验证机制相比，证书具有多项优势。证书可将非对称密钥用于设备。这意味着您可以将私有密钥融入到设备上的安全存储中。这样，敏感的加密材料就永远不会离开设备。证书可以通过用户名和密码或持有者令牌等其他方案提供更可靠的客户端身份验证，因为密钥永远不会离开设备。

AWS IoT 身份验证证书采用 TLS 协议的客户端身份验证模式。TLS 适用于多种编程语言和操作系统并且通常用于为数据加密。在 TLS 客户端身份验证中，AWS IoT 请求客户端 X.509 证书并依照证书注册表验证证书的状态和 AWS 账户。随后，将要求客户端提供与证书所含公有密钥相对应的私有密钥的所有权证明。

要使用 AWS IoT 证书，客户端必须支持在 TLS 实施中使用所有以下各项：

• TLS 1.2.• SHA-256 RSA 证书签名验证。• 来自 TLS 密码包支持部门的密码包之一。

X.509 证书和 AWS IoTAWS IoT 可以使用 AWS IoT 生成的证书或 CA 证书签发的证书执行设备身份验证。由 AWS IoT 生成的证书是长期有效的 (但将在 2049-12-31T23:59:59Z 到期，即格林威治标准时间 2049 年 12 月 31 日午夜。)对于CA 证书签发的证书的过期日期和时间，将在创建 CA 证书时设置。

Note

我们建议为每个设备提供一个唯一的证书，以便进行精细的管理，包括证书吊销。设备必须支持轮换和更换证书，以确保证书过期时仍能顺畅运行。

要使用并非由 AWS IoT 创建的证书，您必须注册一个 CA 证书。所有设备证书都必须由您注册的 CA 证书签发。

您可以使用 AWS IoT 控制台或 CLI 执行以下操作：

• 创建并注册 AWS IoT 证书。• 注册 CA 证书。• 注册设备证书。• 激活或停用设备证书。• 撤销设备证书。• 将设备证书转移到其他 AWS 账户。

107


• 列出注册到您的 AWS 账户的所有 CA 证书。• 列出注册到您的 AWS 账户的所有设备证书。

有关用于执行这些操作的 CLI 命令的详细信息，请参阅 AWS IoT CLI 参考.

有关使用 AWS IoT 控制台创建证书的更多信息，请参阅创建和激活设备证书。

服务器身份验证服务器证书可让您的设备验证其是否正在与 AWS IoT 而非其他假冒 AWS IoT 的服务器进行通信。AWS IoT服务器证书由下列 CA 证书之一签署：

• RSA 2048 位密钥：VeriSign Class 3 Public Primary G5 根 CA 证书• RSA 2048 位密钥：Amazon Root CA 1• RSA 4096 位密钥：Amazon Root CA 2• ECC 256 位密钥：Amazon Root CA 3• ECC 384 位密钥：Amazon Root CA 4

要使您的设备能够验证 AWS IoT 服务器证书，我们建议在您的设备上安装上面列出的所有 CA 证书。

在您的设备上存储所有这些证书会占用宝贵的内存空间。如果您的设备实施基于 RSA 的验证，则可以省略Amazon Root CA 3 和 Amazon Root CA 4 ECC 证书。如果您的设备实施基于 ECC 的证书验证，则可以省略 Amazon Root CA 1 和 Amazon Root CA 2 RSA 证书。

无论您的设备使用的证书验证的类型如何，均需要包括 VeriSign Class 3 Public Primary G5 根 CA 证书。Note

CA 证书具有一个过期日期，在该日期后，这些证书将无法用于验证服务器的证书。可能需要在 CA证书的过期日期前替换这些证书。您应该确保可以更新所有设备上的根 CA 证书，以确保持续的连接并保持最新的安全最佳实践。

在连接到 AWS IoT 时，请参考您的设备代码中的 CA 根证书。有关更多信息，请参阅 AWS IoT 设备软件开发工具包 (p. 340)。

创建并注册 AWS IoT 设备证书您可以使用 AWS IoT 控制台或 AWS IoT CLI 来创建 AWS IoT 证书。

创建证书（控制台）

1. 登录 AWS 管理控制台并打开 AWS IoT 控制台，网址为：https://console.aws.amazon.com/iot。2. 在左侧导航窗格中，选择安全性以展开选项，然后选择证书。选择 Create。3. 选择 One-click certificate creation - Create certificate。或者，要使用证书签名请求 (CSR) 生成证书，请

选择 Create with CSR。4. 使用指向公有密钥、私有密钥和证书的链接将每一个密钥和证书都下载到一个安全位置。5. 选择 Activate。

创建证书 (CLI)

AWS IoT CLI 提供了两个命令来创建证书：

• create-keys-and-certificate

CreateKeysAndCertificate API 可创建私有密钥、公有密钥和 X.509 证书。

108


http://docs.aws.amazon.com/iot/latest/developerguide/create-device-certificate.html

https://www.symantec.com/content/en/us/enterprise/verisign/roots/VeriSign-Class 3-Public-Primary-Certification-Authority-G5.pem

https://www.amazontrust.com/repository/AmazonRootCA1.pem








https://www.symantec.com/content/en/us/enterprise/verisign/roots/VeriSign-Class 3-Public-Primary-Certification-Authority-G5.pem


https://console.aws.amazon.com/codedeploy

http://docs.aws.amazon.com/cli/latest/reference/iot/create-keys-and-certificate.html

http://docs.aws.amazon.com/iot/latest/apireference/API_CreateKeysAndCertificate.html


• create-certificate-from-csr

CreateCertificateFromCSR API 利用 CSR 创建证书。

使用您自己的证书

要使用您自己的 X.509 证书，必须在 AWS IoT 中注册 CA 证书。之后，CA 证书可用于签发设备证书。您可以使用相同的使用者字段为每个区域的每个 AWS 账户最多注册 10 个 CA 证书。这样，您便可以拥有多个能够签发设备证书的 CA。

Note

设备证书必须由已注册的 CA 证书签发。CA 证书通常用于创建中间 CA 证书。如果使用中间证书签发设备证书，则您必须注册中间 CA 证书。在连接到 AWS IoT 时应使用 AWS IoT 根 CA 证书，即使您注册了自己的根 CA 证书也是如此。设备使用 AWS IoT 根 CA 证书验证 AWS IoT 服务器的身份。

内容• 注册您的 CA 证书 (p. 109)• 使用您的 CA 证书创建设备证书 (p. 110)• 注册设备证书 (p. 111)• 手动注册设备证书 (p. 111)• 使用自动/即时注册功能来注册设备证书 (p. 111)• 停用 CA 证书 (p. 112)• 吊销设备证书 (p. 112)

如果没有 CA 证书，则可以使用 OpenSSL 工具创建一个。

创建 CA 证书

1. 生成密钥对。

openssl genrsa -out rootCA.key 2048

2. 使用密钥对中的私有密钥生成 CA 证书。

openssl req -x509 -new -nodes -key rootCA.key -sha256 -days 1024 -out rootCA.pem

注册您的 CA 证书

要注册您的 CA 证书，您必须：

• 从 AWS IoT 获取注册代码。• 使用您的 CA 证书来签署私有密钥验证证书。• 将您的 CA 证书和私有密钥验证证书传递给 register-ca-certificate CLI 命令。

必须将私有密钥验证证书中的 Common Name 字段设置为 get-registration-code CLI 命令生成的注册代码。命令会为每个 AWS 账户生成一个注册代码。您可以使用 register-ca-certificate 命令或AWS IoT 控制台注册 CA 证书。

注册 CA 证书

1. 从 AWS IoT 获取注册代码。此代码将用作私有密钥验证证书的 Common Name。

109

http://docs.aws.amazon.com/cli/latest/reference/iot/create-certificate-from-csr.html

http://docs.aws.amazon.com/iot/latest/apireference/API_CreateCertificateFromCsr.html

https://www.openssl.org/


aws iot get-registration-code

2. 为私有密钥验证证书生成密钥对。

openssl genrsa -out verificationCert.key 2048

3. 为私有密钥验证证书创建 CSR。将证书的 Common Name 字段设置为您的注册代码。

openssl req -new -key verificationCert.key -out verificationCert.csr

系统将提示您输入一些信息，其中包括证书的 Common Name。

Country Name (2 letter code) [AU]:State or Province Name (full name) []:Locality Name (for example, city) []:Organization Name (for example, company) []:Organizational Unit Name (for example, section) []:Common Name (e.g. server FQDN or YOUR name) []:XXXXXXXXXXXXMYREGISTRATIONCODEXXXXXX Email Address []:

4. 使用 CSR 创建私有密钥验证证书。

openssl x509 -req -in verificationCert.csr -CA rootCA.pem -CAkey rootCA.key -CAcreateserial -out verificationCert.pem -days 500 -sha256

5. 向 AWS IoT 注册 CA 证书。将 CA 证书和私有密钥验证证书传递给 register-ca-certificate CLI命令。

aws iot register-ca-certificate --ca-certificate file://rootCA.pem --verification-cert file://verificationCert.pem

6. 使用 update-certificate CLI 命令激活 CA 证书。

aws iot update-ca-certificate --certificate-id xxxxxxxxxxx --new-status ACTIVE

使用您的 CA 证书创建设备证书

您可以使用在 AWS IoT 中注册的 CA 证书创建设备证书。必须先在 AWS IoT 中注册设备证书，然后才能使用它。

创建设备证书

1. 生成密钥对。

openssl genrsa -out deviceCert.key 2048

2. 为设备证书创建 CSR。

openssl req -new -key deviceCert.key -out deviceCert.csr

系统将提示您输入一些信息，如下所示。

Country Name (2 letter code) [AU]:State or Province Name (full name) []:Locality Name (for example, city) []:

110


Organization Name (for example, company) []:Organizational Unit Name (for example, section) []:Common Name (e.g. server FQDN or YOUR name) []:Email Address []:

3. 使用 CSR 创建设备证书。

openssl x509 -req -in deviceCert.csr -CA rootCA.pem -CAkey rootCA.key -CAcreateserial -out deviceCert.pem -days 500 -sha256

Note

您必须使用在 AWS IoT 中注册的 CA 证书创建设备证书。如果您在自己的 AWS 账户中注册了多个 CA 证书 (具有相同的使用者字段和公有密钥)，则必须在注册设备证书时指定用于创建设备证书的 CA 证书。

4. 注册设备证书。

aws iot register-certificate --certificate-pem file://deviceCert.pem --ca-certificate-pem file://rootCA.pem

5. 使用 update-certificate CLI 命令激活设备证书。

aws iot update-certificate --certificate-id xxxxxxxxxxx --new-status ACTIVE

注册设备证书

您必须使用在 AWS IoT 中注册的 CA 证书签发设备证书。如果您在自己的 AWS 账户中注册了多个 CA 证书(具有相同的使用者字段和公有密钥)，则必须在注册设备证书时指定用于签发设备证书的 CA 证书。您可以手动注册每个设备证书，也可以使用自动注册功能，利用该功能，设备可以在首次连接到 AWS IoT 时注册自己的证书。

手动注册设备证书

使用以下 CLI 命令注册设备证书：

aws iot register-certificate --certificate-pem file://deviceCert.crt --ca-certificate-pem file://caCert.crt

使用自动/即时注册功能来注册设备证书

要在设备首次连接到 AWS IoT 时自动注册设备证书，您必须启用 CA 证书的自动注册。这将在设备连接到AWS IoT 时注册由您的 CA 证书签发的任何设备证书。

启用自动注册

使用 update-ca-certificate API 将 CA 证书的 auto-registration-status 设置为 ENABLE：

$ aws iot update-ca-certificate --cert-id caCertificateId --new-auto-registration-status ENABLE

使用 register-ca-certificate API 注册 CA 证书时，还可以将 auto-registration-status 设置为 ENABLE：

aws iot register-ca-certificate --ca-certificate file://rootCA.pem --verification-cert file://privateKeyVerificationCert.crt --allow-auto-registration

111

AWS IoT 开发人员指南IAM 用户、组和角色

当设备首次尝试连接到 AWS IoT 时，作为 TLS 握手流程的一部分，它必须提供已注册的 CA 证书和设备证书。AWS IoT 会将 CA 证书识别为已注册的 CA 证书，自动注册设备证书并将其状态设置为PENDING_ACTIVATION。这意味着，已自动注册设备证书，该证书正在等待激活。证书必须处于 ACTIVE状态才能用来连接到 AWS IoT。当 AWS IoT 自动注册证书时或者当处于 PENDING_ACTIVATION 状态的证书建立连接时，AWS IoT 将向以下 MQTT 主题发布消息：

$aws/events/certificates/registered/caCertificateID

其中 caCertificateID 是颁发设备证书的 CA 证书的 ID。

发布到该主题的消息具有以下结构：

{ "certificateId": "certificateID", "caCertificateId": "caCertificateId", "timestamp": timestamp, "certificateStatus": "PENDING_ACTIVATION", "awsAccountId": "awsAccountId", "certificateRegistrationTimestamp": "certificateRegistrationTimestamp"}

您可以创建一项规则，以侦听此主题并执行一些操作。我们建议您创建一项 Lambda 规则，以验证设备证书是否位于证书吊销列表 (CRL) 中，激活证书，创建策略并将其附加到证书中。该策略可确定设备能够访问的资源。有关如何创建可侦听 $aws/events/certificates/registered/caCertificateID 主题并执行这些操作的 Lambda 规则的更多信息，请参阅即时注册。

停用 CA 证书

当您注册设备证书时，AWS 将检查相关的 CA 证书是否处于 ACTIVE 状态。如果 CA 证书的状态是INACTIVE，AWS IoT 将禁止注册设备证书。通过将 CA 证书标记为 INACTIVE，可以防止在账户中注册由受损的 CA 颁发的任何新设备证书。您可以使用 update-ca-certificate API 停用 CA 证书：

$ aws iot update-ca-certificate --cert-id certificateId --new-status INACTIVE

Note

除非您明确吊销由受损的 CA 证书签发的已注册设备证书，否则所有此类证书均将继续工作。

使用 ListCertificatesByCA API 获取由受损的 CA 签发的所有已注册设备证书的列表。对于由受损的CA 证书签发的每个设备证书，请使用 UpdateCertificate API 吊销该设备证书以避免使用它。

吊销设备证书

如果您在已注册的设备证书上检测到可疑活动，可使用 update-certificate API 吊销该证书：

$ aws iot update-certificate --cert-id certificateId --new-status REVOKED

如果在自动注册设备证书期间发生任何错误或异常，AWS IoT 将向您的 CloudWatch Logs 日志发送相关事件或消息。有关如何为您的账户设置日志的更多信息，请参阅 Amazon CloudWatch 文档。

IAM 用户、组和角色IAM 用户、组和角色是用于在 AWS 中管理身份和身份验证的标准机制。您可以使用它们通过 AWS 软件开发工具包和 CLI 连接到 AWS IoT HTTP 界面。

IAM 角色还允许 AWS IoT 代表您访问您账户中的其他 AWS 资源。例如，如果您希望设备将自身状态发布到 DynamoDB 表，则 IAM 角色允许 AWS IoT 与 Amazon DynamoDB 交互。有关更多信息，请参阅 IAM 角色。

112

https://aws.amazon.com/blogs/iot/just-in-time-registration-of-device-certificates-on-aws-iot/

http://docs.aws.amazon.com/AmazonCloudWatch/latest/DeveloperGuide/

http://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use.html

http://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use.html

AWS IoT 开发人员指南Amazon Cognito 身份

对于通过 HTTP 的消息代理连接，AWS IoT 可以使用签名版本 4 签名流程对 IAM 用户、组和角色执行身份验证。有关信息，请参阅签署 AWS API 请求。

将 AWS Signature 版本 4 与 AWS IoT 配合使用时，客户端必须支持在 TLS 实施中使用以下各项：

• TLS 1.2、TLS 1.1、TLS 1.0。• SHA-256 RSA 证书签名验证。• 来自 TLS 密码包支持部门的密码包之一。

有关更多信息，请参阅 IAM 用户指南。

Amazon Cognito 身份借助 Amazon Cognito 身份，您可以使用自己的身份提供商或其他常见的身份提供商，例如，Login withAmazon、Facebook 或 Google。您需要用身份提供商提供的令牌来换取 AW 安全凭证。这些凭证代表 IAM角色，可与 AWS IoT 配合使用。

AWS IoT 可扩展 Amazon Cognito 并允许将策略附加到 Amazon Cognito 身份。您可以将策略附加到Amazon Cognito 身份并为 AWS IoT 应用程序的单个用户提供精细权限。这样，您就可以在特定客户和他们的设备之间分配权限。有关更多信息，请参阅 Amazon Cognito 身份。

自定义身份验证AWS IoT 可让您定义自定义授权方，从而通过自定义的身份验证服务和 Lambda 函数管理自己的身份验证和授权策略。自定义授权方使得 AWS IoT 可以使用持有者令牌身份验证和授权策略，对您的设备进行身份验证和授权操作。

在建立 HTTP 连接 (可以选择升级到 WebSocket 连接) 且 SigV4 标头不存在时，AWS IoT 设备网关将检查是否为终端节点配置了自定义授权方，如果是这样，它将用于对连接进行身份验证并向设备授权。自定义授权方可以实施各种身份验证策略 (例如：JWT 验证、OAuth 提供程序调用等等)，并且必须返回由设备网关授权MQTT 操作所使用的策略文档。

自定义授权方自定义授权方包含：

名称

一个标识授权方的唯一的任意字符串。

113

http://docs.aws.amazon.com/general/latest/gr/signing_aws_api_requests.html

http://docs.aws.amazon.com/IAM/latest/UserGuide/introduction.html

http://docs.aws.amazon.com/cognito/latest/developerguide/cognito-identity.html

AWS IoT 开发人员指南自定义授权方

Lambda 函数 ARN

实施身份验证逻辑并返回授权策略的 Lambda 函数的 ARN。公有密钥

来自密钥对的公有密钥，用于防止在未经授权的情况下调用授权方的 Lambda 函数。

使用以下命令可生成密钥对：openssl genrsa -out myKeyPair.pem 2048。使用以下命令可从密钥对中提取公有密钥：openssl rsa -in myKeyPair.pem -pubout > mykey.pub

令牌密钥名称

用于从 WebSocket 连接标头提取令牌的密钥名称。

在 Lambda 函数中实施执行身份验证的逻辑。Note

使用 AWS Lambda 是需要付费的。有关 Lambda 的更多信息，请参阅 AWS Lambda DeveloperGuide。

此函数接受设备所提供的令牌、对设备进行身份验证并返回以下信息：

isAuthenticated

一个布尔值，指示是否已对令牌进行身份验证。如果该值为 false，则忽略响应字段的其余部分。principalId

正在获取此权限的委托人。policyDocuments

一个策略列表，指定令牌持有者可执行的操作。DisconnectAfterInSecs

WebSocket 连接保持打开状态的时间长度 (以秒为单位)。RefreshAfterInSecs

时间长度 (以秒为单位)，经过该时间段后将调用 Lambda 函数以刷新策略。关联

验证令牌后派生的其他信息。可在 AWS IoT 规则引擎 SQL 语句和 IAM/AWS IoT 策略变量中提供此信息。

您必须向 AWS IoT 服务委托人授予调用 Lambda 函数 (该函数实施自定义身份验证/授权逻辑) 的权限。可使用以下 CLI 命令执行此操作：

aws lambda add-permission --function-name <authorizer-function-name> --statement-id <unique_identifier_string> --action 'lambda:*' --principal iot.amazonaws.com --source-arn arn:aws:iot:<your-aws-region>:<account_id>:authorizer/<authorizer-function-name> --region <your-aws-region>

有关授予调用 Lambda 函数的权限的更多信息，请参阅 AWS Lambda 权限

您可以设置在连接请求中未包含授权方信息时使用的默认授权方：

aws iot set-default-authorizer --authorizer-name <my-authorizer>

114

https://aws.amazon.com/lambda/pricing/

http://docs.aws.amazon.com/lambda/latest/dg/


http://docs.aws.amazon.com/iot/latest/developerguide/iot-substitution-templates.html

http://docs.aws.amazon.com/iot/latest/developerguide/policy-variables.html

http://docs.aws.amazon.com/lambda/latest/dg/intro-permission-model.html#intro-permission-model-access-policy

AWS IoT 开发人员指南配置自定义授权方

--region <your-aws-region> --endpoint <your-iot-endpoint

--source-arn 参数可确保您的 Lambda 函数只能由计划中的自定义授权方调用。

配置自定义授权方1. 创建一个实现身份验证/授权逻辑的 Lambda 函数 (即以下步骤中的 MyAuthorizerFunction)。以下

是自定义授权 Lambda 功能可能返回的结果的示例：

{ "isAuthenticated": true, "principalId": "xxxxxxxx", "disconnectAfterInSeconds": 86400, "refreshAfterInSeconds": 300, "policyDocuments": [ "{\"Version\":\"2012-10-17\",\"Statement\":[{\"Action\":\"...\",\"Effect\":\"Allow|Deny\",\"Resource\":\"...\"}]}" ], "context": { "username": "johnDoe123", "city": "Seattle", "country": "USA" }}

Lambda 函数的返回值应类似于上述内容，并且可以是 JSON 序列化或非序列化对象。2. 使用 create-authorizer API 将自定义授权方注册到 AWS IoT。

aws iot create-authorizer --authorizer-name MyAuthorizer --authorizer-function-arn arn:aws:lambda:us-west-2:<account_id>:function:MyAuthorizerFunction // Lambda ARN --token-key-name MyAuthorizerToken // Key use to extract token from headers --token-signing-public-keys FIRST_KEY= // Public key used to verify token signature"-----BEGIN PUBLIC KEY-----[...insert your public key here...]-----END PUBLIC KEY-----" --status ACTIVE // Authorizer status - must be ACTIVE --region us-west-2 // AWS region --endpoint https://us-west-2.iot.amazonaws.com // IoT endpoint

test-invoke-authorizer API 可用于测试是否已正确配置自定义授权方 Lambda 函数，如下所示：

aws iot test-invoke-authorizer --authorizer-name <NAME_OF_AUTHORIZER> --token <TOKEN_VALUE> --token-signature <TOKEN_SIGNATURE>

Note

<TOKEN_SIGNITURE> 必须使用上传至在 create-authorizer 调用中使用的公有钥/私有密钥对的私有密钥签名。在本地从类似 UNIX 的命令行创建 <TOKEN_SIGNITURE> 的一种方法如下所示：

echo -n <TOKEN_VALUE> | openssl dgst -sha256 -sign <PRIVATE_KEY> | openssl base64

115

AWS IoT 开发人员指南自定义授权方工作流

在将 <TOKEN_SIGNATURE> 值传递给 test-invoke-authorizer API 之前，必须从前面命令的结果中微调所有换行符。

自定义授权方工作流对于要使用自定义授权方针对 AWS IoT 设备网关进行身份验证的设备，在调用授权方之前，需要通过由AWS 使用的令牌和签名来验证令牌。

当设备尝试连接到 AWS IoT 时，它会在 HTTP 标头中发送以下信息：

• 身份验证服务所生成的令牌。• 身份验证服务所生成的签名。• 用于对令牌进行身份验证的授权方。如果忽略，则将使用默认授权方。

以下是通过 WebSocket 协议连接到 AWS IoT 的示例 HTTP 请求。

GET /mqtt HTTP/1.1 Host: <your-iot-endpoint>Upgrade: WebSocketConnection: Upgradex-amz-customauthorizer-name: <authorizer-name>x-amz-customauthorizer-signature: <token-signature><token-key-name>: <some-token>sec-WebSocket-Key: <any random base64 value>sec-websocket-protocol: mqttsec-WebSocket-Version: <websocket version>

在此示例中，x-amz-customauthorizer-name 标头指定要使用的自定义授权方，x-amz-customauthorizer-signature 标头包含用于验证令牌的数字签名，token-key-name 是由传递给create-authorizer API 的 --token-key-name 指定的令牌密钥名称。

AWS IoT 设备网关将验证数字签名，如果签名有效，将调用指定的授权方。以下是 AWS IoT 发送到自定义授权方的 Lambda 函数的示例负载。

{ "type":"TOKEN", "authorizationToken":"<caller-supplied-token>", "authorizerId":<authorizer-id>, "endpoint":"<your-iot-endpoint>"}

授权方验证令牌并返回委托人 ID、其关联的 AWS IoT/IAM 策略、连接的生存时间 (TTL) 信息以及授权方所生成的任何其他上下文。

以下是来自自定义授权方的响应的示例。

{ "isAuthenticated":true, "principalId": "xxxxxxxx", "disconnectAfterInSeconds": 86400, "refreshAfterInSeconds", 300, "policyDocuments": [ "{ \"Version\": \"2012-10-17\", \"Statement\": [ { \"Action\": \"...\", \"Effect\": \"Allow|Deny\", \"Resource\": \"...\" } ] }" ], "context": {

116

AWS IoT 开发人员指南授权

"username" : "johnDoe123", "city" : "Seattle", "country" : "USA" }}

Lambda 函数的返回值应类似于上述内容，并且可以是 JSON 序列化或非序列化对象。

随后，AWS IoT 设备网关将建立 WebSocket 连接。AWS IoT 将缓存与委托人关联的策略，以便无需重新对设备进行身份验证即可对后续调用进行授权。自定义身份验证期间发生的任何失败都会导致身份验证失败和连接终止。

授权策略确定经身份验证的身份可执行的操作。经身份验证的身份由设备、移动应用程序、Web 应用程序和桌面应用程序使用。经身份验证的身份甚至可以是键入 AWS IoT CLI 命令的用户。仅当身份具有向其授予权限的策略时，才能执行 AWS IoT 操作。

AWS IoT 策略和 IAM 策略均可用于 AWS IoT，以控制身份 (也称为委托人) 可以执行的操作。您使用的策略类型取决于向 AWS IoT 进行身份验证时使用的身份类型。下表显示了身份类型、它们使用的协议和可用于授权的策略类型。

AWS IoT 操作分为两组：

• 控制层面 API 允许您执行诸如创建或更新证书、事物、规则等管理任务。• 数据层面 API 允许您向 AWS IoT 发送数据以及从其接收数据。

您使用的策略类型取决于您使用的是控制层面 API 还是数据层面 API。

AWS IoT 数据层面 API 和策略类型

协议和身份验证机制

开发工具包身份类型策略类型

基于双向身份验证的 MQTT(端口 8883 或443† (p. 147))

AWS IoT 设备软件开发工具包

X.509 证书 AWS IoT 策略

基于WebSocket 的MQTT (端口443)

AWS 移动软件开发工具包

AmazonCognito、IAM或联合身份

用于 AmazonCognito 身份的AWS IoT 策略

用于其他身份的IAM 策略

基于服务器身份验证的 HTTP(端口 443)

AWS CLI AmazonCognito、IAM或联合身份



基于双向身份验证的 HTTP (端口 8443)

不支持软件开发工具包

X.509 证书 AWS IoT 策略

117

AWS IoT 开发人员指南AWS IoT 策略

AWS IoT 控制层面 API 和策略类型

协议和身份验证机制

开发工具包身份类型策略类型

基于服务器身份验证的 HTTP(端口 443)

AWS CLI AmazonCognito、IAM或联合身份



AWS IoT 策略附加到 X.509 证书或 Amazon Cognito 身份。IAM 策略附加到 IAM 用户、组或角色。如果您使用 AWS IoT 控制台或 AWS IoT CLI 附加策略 (附加到证书或 Amazon Cognito 身份)，则应使用 AWS IoT策略。否则，应使用 IAM 策略。

基于策略的授权是一种功能强大的工具。它让您能够完全控制设备、用户或应用程序在 AWS IoT 中可以执行的操作。例如，以使用证书连接到 AWS IoT 的设备为例。您可以允许设备访问所有 MQTT 主题，也可以限制它的访问权限，只允许它访问一个主题。在另一个示例中，假设用户在命令行中键入 CLI 命令。通过使用策略，您可以允许或拒绝用户访问任何命令或 AWS IoT 资源。还可以控制应用程序对 AWS IoT 资源的访问。

AWS IoT 策略AWS IoT 策略是 JSON 文档。它们与 IAM策略遵循相同的约定。AWS IoT 支持命名策略，因此，许多身份都可以参考相同的策略文档。命名策略采用版本化，以便可以轻松回滚。

AWS IoT 定义一组策略操作，这些操作描述可以授予或拒绝对它们的访问权限的操作和资源。例如：

• iot:Connect 代表连接到 AWS IoT 代理消息的权限。• iot:Subscribe 代表订阅 MQTT 主题或主题筛选条件的权限。• iot:GetThingShadow 表示获取设备的影子的权限。

AWS IoT 策略允许您控制对 AWS IoT 数据层面的访问。AWS IoT 数据层面由允许您连接到 AWS IoT 消息代理，发送和接收 MQTT 消息以及获取或更新设备的影子的操作组成。有关更多信息，请参阅 AWS IoT 策略操作 (p. 119)。

AWS IoT 策略是包含一个或多个策略语句的 JSON 文档。每个语句都包含一个 Effect、一个 Action和一个 Resource。Effect 指定是允许还是拒绝该操作。Action 指定策略允许或拒绝的操作。Resource 指定允许或拒绝对其执行操作的资源。以下策略向所有设备授予连接到 AWS IoT 消息代理的权限，但限制设备只能在特定 MQTT 主题上发布：

{ "Version": "2012-10-17", "Statement": [{ "Effect": "Allow", "Action":["iot:Publish"], "Resource": ["arn:aws:iot:us-east-1:123456789012:topic/foo/bar"] }, { "Effect": "Allow", "Action": ["iot:Connect"], "Resource": ["*"] }]}

118


AWS IoT 策略操作AWS IoT 定义了以下策略操作：

MQTT 策略操作

iot:Connect

代表连接到 AWS IoT 消息代理的权限。每次向代理发送 CONNECT 请求时，均检查 iot:Connect 权限。消息代理禁止两个具有相同 ID 的客户端同时保持连接状态。在第二个客户端建立连接后，代理将检测此案例并断开其中一个客户端的连接。iot:Connect 权限可用来确保只有经授权的客户端才能使用特定的客户端 ID 进行连接。

iot:Publish

代表向 MQTT 主题发布内容的权限。每次向代理发送 PUBLISH 请求时，均检查该权限。这可用于允许客户端发布到特定主题模式。

Note

还必须授予 iot:Connect 权限才能授予 iot:Publish 权限。iot:Receive

表示从 AWS IoT 接收消息的权限。每次向客户端交付消息时，均检查 iot:Receive 权限。由于每次交付时都会检查此权限，因此，可以使用它来撤销当前已订阅某个主题的客户端的权限。

iot:Subscribe

代表订阅主题筛选条件的权限。每次向代理发送 SUBSCRIBE 请求时，均检查该权限。这可用于允许客户端订阅与特定主题模式相符的主题。

Note

还必须授予 iot:Connect 权限才能授予 iot:Subscribe 权限。

影子策略操作

iot:DeleteThingShadow

表示删除设备的影子的权限。每次请求删除影子的内容时，都会检查 iot:DeleteThingShadow 权限。

iot:GetThingShadow

表示检索设备的影子的权限。每次请求检索影子的内容时，都会检查 iot:GetThingShadow 权限。iot:UpdateThingShadow

表示更新设备的影子的权限。每次请求更新影子的内容时，都会检查 iot:UpdateThingShadow 权限。

Note

任务执行策略操作仅适用于 HTTP TLS 终端节点。如果您使用了 MQTT 终端节点，则需要使用上面定义的 MQTT 策略操作。

任务执行策略操作

iot:DescribeJobExecution

表示为给定事物检索任务执行的权限。每次请求获取任务执行时，都会检查iot:DescribeJobExecution 权限。

119


iot:GetPendingJobExecutions

表示一个权限，用于为事物检索未处于最终状态的任务的列表。每次请求检索该列表时，都会检查iot:GetPendingJobExecutions 权限。

iot:UpdateJobExecution

表示更新任务执行的权限。每次请求更新任务执行的状态时，都会检查 iot:UpdateJobExecution权限。

iot:StartNextPendingJobExecution

表示一个权限，用于为事物获取和启动下一个待处理任务执行。(即，将状态为 QUEUED 或IN_PROGRESS 的任务执行更新为状态 IN_PROGRESS。)每次请求启动下一个待处理任务执行，都会检查 iot:StartNextPendingJobExecution 权限。

操作资源要为 AWS IoT 策略操作指定资源，必须使用资源的 ARN。所有资源 ARN 均采用以下形式：

arn:aws:iot:region:AWS account ID:resource type/resource name

下表列出了要为每种类型的操作指定的操作：

操作资源

iot:DeleteThingShadow 事物 ARN - arn:aws:iot:us-east-1:123456789012:thing/thingOne

iot:Connect 客户端 ID ARN - arn:aws:iot:us-east1:123456789012:client/myClientId

iot:Publish 主题 ARN - arn:aws:iot:us-east-1:123456789012:topic/myTopicName

iot:Subscribe 主题筛选条件 ARN - arn:aws:iot:us-east-1:123456789012:topicfilter/myTopicFilter

iot:Receive 主题 ARN - arn:aws:iot:us-east-1:123456789012:topic/myTopicName

iot:UpdateThingShadow 事物 ARN - arn:aws:iot:us-east-1:123456789012:thing/thingOne

iot:GetThingShadow 事物 ARN - arn:aws:iot:us-east-1:123456789012:thing/thingOne

iot:DescribeJobExecution 事物 ARN - arn:aws:iot:us-east-1:123456789012:thing/thingOne

iot:GetPendingJobExecutions 事物 ARN - arn:aws:iot:us-east-1:123456789012:thing/thingOne

iot:UpdateJobExecution 事物 ARN - arn:aws:iot:us-east-1:123456789012:thing/thingOne

iot:StartNextPendingJobExecution 事物 ARN - arn:aws:iot:us-east-1:123456789012:thing/thingOne

120


AWS IoT 策略变量AWS IoT 定义可在资源或条件块内的 AWS IoT 策略中使用的策略变量。评估策略时，将使用实际值替换策略变量。例如，如果设备使用客户端 ID“100-234-3456”连接到 AWS IoT 消息代理，iot:ClientId 策略变量将在策略文档中替换为“100-234-3456”。有关策略变量的更多信息，请参阅 IAM 策略变量和多值条件。

基本策略变量

AWS IoT 定义了以下基本策略变量：

• iot:ClientId：用于连接到 AWS IoT 消息代理的客户端 ID。• aws:SourceIp：连接到 AWS IoT 消息代理的客户端的 IP 地址。

以下 AWS IoT 策略显示了策略变量的用法：

{ "Version": "2012-10-17", "Statement": [{ "Effect": "Allow", "Action": ["iot:Connect"], "Resource": [ "arn:aws:iot:us-east-1:123451234510:client/${iot:ClientId}" ] }, { "Effect": "Allow", "Action": ["iot:Publish"], "Resource": [ "arn:aws:iot:us-east-1:123451234510:topic/foo/bar/${iot:ClientId}" ] }]}

在这些示例中，${iot:ClientId} 将替换为评估策略时连接到 AWS IoT 消息代理的客户端的 ID。使用${iot:ClientId} 等策略变量时，您可能会无意中开放对意外主题的访问权限。例如，如果您使用借助${iot:ClientId} 来指定主题筛选条件的策略：

{ "Effect": "Allow", "Action": ["iot:Subscribe"], "Resource": [ "arn:aws:iot:us-east-1:123456789012:topicfilter/foo/${iot:ClientId}/bar" ]}

客户端可使用 + 作为客户端 ID 来进行连接。这样，用户便可以订阅与主题筛选条件 foo/+/bar 匹配的任何主题。要防范此类安全漏洞，请使用 iot:Connect 策略操作来控制哪些客户端 ID 能够建立连接。例如，此策略仅允许客户端 ID 为 clientid1 的客户端建立连接：

{ "Version": "2012-10-17", "Statement": [{ "Effect": "Allow", "Action": ["iot:Connect"], "Resource": [ "arn:aws:iot:us-east-1:123456789012:client/clientid1" ]

121

http://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_variables.html

http://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_multi-value-conditions.html


}]}

X.509 证书策略变量

X.509 证书策略变量允许您根据 X.509 证书属性编写授予权限的 AWS IoT 策略。以下部分介绍如何使用这些证书策略变量。

发布者属性

以下 AWS IoT 策略变量允许您根据由证书发布者设置的证书属性来授予或拒绝权限。

• iot:Certificate.Issuer.DistinguishedNameQualifier

• iot:Certificate.Issuer.Country

• iot:Certificate.Issuer.Organization

• iot:Certificate.Issuer.OrganizationalUnit

• iot:Certificate.Issuer.State

• iot:Certificate.Issuer.CommonName

• iot:Certificate.Issuer.SerialNumber

• iot:Certificate.Issuer.Title

• iot:Certificate.Issuer.Surname

• iot:Certificate.Issuer.GivenName

• iot:Certificate.Issuer.Initials

• iot:Certificate.Issuer.Pseudonym

• iot:Certificate.Issuer.GenerationQualifier

主题属性

以下 AWS IoT 策略变量允许您根据由证书发布者设置的证书使用者属性来授予或拒绝权限。

• iot:Certificate.Subject.DistinguishedNameQualifier

• iot:Certificate.Subject.Country

• iot:Certificate.Subject.Organization

• iot:Certificate.Subject.OrganizationalUnit

• iot:Certificate.Subject.State

• iot:Certificate.Subject.CommonName

• iot:Certificate.Subject.SerialNumber

• iot:Certificate.Subject.Title

• iot:Certificate.Subject.Surname

• iot:Certificate.Subject.GivenName

• iot:Certificate.Subject.Initials

• iot:Certificate.Subject.Pseudonym

• iot:Certificate.Subject.GenerationQualifier

X.509 证书允许这些属性包含一个或多个值。默认情况下，每个多值属性的策略变量会返回第一个值。例如，Certificate.Subject.Country 属性可能包含国家/地区名称列表。在策略中进行评估时，iot:Certificate.Subject.Country 由第一个国家/地区名称替换。您可以

122


使用从零开始的索引请求特定的属性值。例如，iot:Certificate.Subject.Country#1 由Certificate.Subject.Country 属性中第二个国家/地区名称替换。如果您指定不存在的属性值 (例如，如果您在只有两个值分配到属性时请求第三个值)，则不会执行替换功能，并且授权将失败。您可以在策略变量名称中使用 .List 后缀指定属性的所有值。以下示例策略允许任何客户端连接至 AWS IoT，但是，对于证书的 Certificate.Subject.Organization 属性设为 "Example Corp" 或 "AnyCompany" 的客户端，会限制发布权限。这可以通过使用为前面的操作指定条件的 "Condition" 属性来完成。本例中的条件是证书的 Certificate.Subject.Organization 属性必须包括一个列出的值。

{ "Version":"2012-10-17", "Statement":[ { "Effect":"Allow", "Action":[ "iot:Connect" ], "Resource":[ "*" ] }, { "Effect":"Allow", "Action":[ "iot:Publish" ], "Resource":[ "*" ], "Condition":{ "ForAllValues:StringEquals":{ "iot:Certificate.Subject.Organization.List":[ "Example Corp", "AnyCompany" ] } } } ]}

发布者备用名称属性

以下 AWS IoT 策略变量允许您根据由证书发布者设置的发布者备用名称属性来授予或拒绝权限。

• iot:Certificate.Issuer.AlternativeName.RFC822Name

• iot:Certificate.Issuer.AlternativeName.DNSName

• iot:Certificate.Issuer.AlternativeName.DirectoryName

• iot:Certificate.Issuer.AlternativeName.UniformResourceIdentifier

• iot:Certificate.Issuer.AlternativeName.IPAddress

主题备用名称属性

以下 AWS IoT 策略变量允许您根据由证书发布者设置的使用者备用名称属性来授予或拒绝权限。

• iot:Certificate.Subject.AlternativeName.RFC822Name

• iot:Certificate.Subject.AlternativeName.DNSName

• iot:Certificate.Subject.AlternativeName.DirectoryName

• iot:Certificate.Subject.AlternativeName.UniformResourceIdentifier

123


• iot:Certificate.Subject.AlternativeName.IPAddress

其他属性

您可以根据证书的序列号使用 iot:Certificate.SerialNumber 允许或拒绝访问 AWS IoT 资源。iot:Certificate.AvailableKeys 策略变量包含具有值的所有证书策略变量的名称。

X.509 证书策略变量限制

以下限制适用于 X.509 证书策略变量：

通配符

如果证书属性中有通配符，则策略变量不会由证书属性值替换，并在策略文档中保留 ${policy-variable} 文本。这可能会导致授权失败。

数组字段

包含数组的证书属性限制为五项。其他的项将被忽略。字符串长度

所有字符串值的长度限制为 1024 个字符。如果证书属性包含超过 1024 个字符的字符串，则策略变量不会由证书属性值替换，并在策略文档中保留 ${policy-variable}。这可能会导致授权失败。

事物策略变量

事物策略变量允许您根据事物名称、事物类型和事物属性值等事物属性来编写授予或拒绝权限的 AWS IoT策略。事物名称从事物连接至 AWS IoT 时发送的 MQTT Connect 消息中的客户端 ID 获取。当事物通过使用 TLS 双向身份验证的 MQTT 连接至 AWS IoT 时，或通过使用经过身份验证的 Amazon Cognito 身份的WebSocket 协议 MQTT 连接至 AWS IoT 时，事物策略变量将被替换。当证书或经过身份验证的 AmazonCognito 身份附加到事物时，事物策略变量也将被替换。可以使用 AttachThingPrincipal API 将证书和经过身份验证的 Amazon Cognito 身份附加到事物。

可用的事物策略变量如下：

• iot:Connection.Thing.ThingName

• iot:Connection.Thing.ThingTypeName

• iot:Connection.Thing.Attributes[attributeName]

• iot:Connection.Thing.IsAttached

iot:Connection.Thing.ThingName

该属性等于为其评估策略的事物名称。事物名称设置为 MQTT/WebSocket 连接的客户端 ID。此策略变量仅在通过 MQTT 或基于 WebSocket 协议的 MQTT 连接时可用。

iot:Connection.Thing.ThingTypeName

该属性等于与为其评估策略的事物相关联的事物类型。事物名称设置为 MQTT/WebSocket 连接的客户端ID。事物类型名称通过调用 DescribeThing API 获得。此策略变量仅在通过 MQTT 或基于 WebSocket 协议的 MQTT 连接时可用。

iot:Connection.Thing.Attributes[attributeName]

该属性等于与为其评估策略的事物相关联的指定属性的值。事物最多可以具有 50 个属性。每个属性都作为策略变量提供：iot:Connection.Thing.Attributes[attributeName]，其中 attributeName

124

http://docs.aws.amazon.com/iot/latest/apireference/API_AttachThingPrincipal.html


是属性的名称。事物名称设置为 MQTT/WebSocket 连接的客户端 ID。此策略变量仅在通过 MQTT 或基于WebSocket 协议的 MQTT 连接时可用。

iot:Connection.Thing.IsAttached

如果正在为其评估策略的事物附加了证书或 Amazon Cognito 身份，这将解析为 true。

示例策略AWS IoT 策略是在 JSON 文档中指定的。AWS IoT 策略的组成部分如下：

版本

必须设置为 "2012-10-17"。效果

必须设置为 "Allow" 或 "Deny"。操作

必须设置为“iot:operation-name”，其中 operation-name 是以下各项之一：

"iot:Connect"：连接到 AWS IoT

"iot:Receive"：从 AWS IoT 接收消息

"iot:Publish"：MQTT 发布。

"iot:Subscribe"：MQTT 订阅。

"iot:UpdateThingShadow"：更新设备的影子。

"iot:GetThingShadow"：检索设备的影子。

"iot:DeleteThingShadow"：删除设备的影子。资源

必须设置为以下各项之一：

客户端 - arn:aws:iot:region:account-id:client/client-id

主题 ARN - arn:aws:iot:region:account-id:topic/topic-name

主题筛选条件 ARN - arn:aws:iot:region:account-id:topicfilter/topic-filter

连接策略示例

以下策略允许一组客户端 ID 建立连接：

{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "iot:Connect" ], "Resource": [ "arn:aws:iot:us-east-1:123456789012:client/clientid1", "arn:aws:iot:us-east-1:123456789012:client/clientid2",

125


"arn:aws:iot:us-east-1:123456789012:client/clientid3" ] }, { "Effect": "Allow", "Action": [ "iot:Publish", "iot:Subscribe", "iot:Receive" ], "Resource": [ "*" ] } ]}

以下策略禁止一组客户端 ID 建立连接：

{ "Version": "2012-10-17", "Statement": [ { "Effect": "Deny", "Action": [ "iot:Connect" ], "Resource": [ "arn:aws:iot:us-east-1:123456789012:client/clientid1", "arn:aws:iot:us-east-1:123456789012:client/clientid2" ] }, { "Effect": "Allow", "Action": [ "iot:Connect" ], "Resource": [ "*" ] } ]}

以下策略允许证书持有者使用任何客户端 ID 订阅主题筛选条件 foo/*：

{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "iot:Connect" ], "Resource": [ "*" ] }, { "Effect": "Allow", "Action": [

126


"iot:Subscribe" ], "Resource": [ "arn:aws:iot:us-east-1:123456789012:topicfilter/foo/*" ] } ]}

订阅/发布策略示例

您使用的策略取决于您连接到 AWS IoT 的方式。您可以使用 MQTT 客户端、HTTP 或 WebSocket 连接到AWS IoT。通过 MQTT 客户端连接时，将使用 X.509 证书进行身份验证。通过 HTTP 或 WebSocket 协议连接时，将使用签名版本 4 和 Amazon Cognito 进行身份验证。

适用于 MQTT 客户端的策略

当在 AWS IoT 策略中为 MQTT 客户端指定主题筛选条件时，MQTT 通配符“+”和“#”将被视为文本字符。使用它们可能会导致意外行为。例如，以下策略将仅允许客户端订阅主题筛选条件 foo/+/bar：

{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "iot:Connect" ], "Resource": [ "*" ] }, { "Effect": "Allow", "Action": [ "iot:Subscribe" ], "Resource": [ "arn:aws:iot:us-east-1:123456789012:topicfilter/foo/+/bar" ] } ]}

Note

MQTT 通配符“+”在策略中不被视为通配符。尝试订阅符合 foo/+/bar 模式 (如 foo/baz/bar 或foo/goo/bar) 的主题筛选条件将会失败，并且会导致客户端断开连接。

您可以在策略的资源属性中使用“*”作为通配符。例如，以下策略允许证书持有者使用 AWS 账户在所有主题下发布消息以及订阅所有主题筛选条件：

{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "iot:*" ], "Resource": [

127


"*" ] } ]}

以下策略允许证书持有者使用 AWS 账户在所有主题下发布消息：

{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "iot:Publish", "iot:Connect" ], "Resource": [ "*" ] } ]}

您还可以在主题筛选条件的末尾使用“*”通配符。例如，以下策略允许证书持有者订阅符合 foo/bar/* 模式的主题筛选条件：

{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "iot:Connect" ], "Resource": [ "*" ] }, { "Effect": "Allow", "Action": [ "iot:Subscribe" ], "Resource": [ "arn:aws:iot:us-east-1:123456789012:topicfilter/foo/bar/*" ] } ]}

以下策略允许证书持有者在 foo/bar 和 foo/baz 主题下发布消息：

{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "iot:Connect" ], "Resource": [

128


"*" ] }, { "Effect": "Allow", "Action": [ "iot:Publish" ], "Resource": [ "arn:aws:iot:us-east-1:123456789012:topic/foo/bar", "arn:aws:iot:us-east-1:123456789012:topic/foo/baz" ] } ]}

以下策略禁止证书持有者在 foo/bar 主题下发布消息：

{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "iot:Connect" ], "Resource": [ "*" ] }, { "Effect": "Deny", "Action": [ "iot:Publish" ], "Resource": [ "arn:aws:iot:us-east-1:123456789012:topic/foo/bar" ] } ]}

以下策略允许证书持有者在主题 foo 下发布消息，但禁止证书持有者在主题 bar 下发布消息：

{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "iot:Connect" ], "Resource": [ "*" ] }, { "Effect": "Allow", "Action": [ "iot:Publish" ], "Resource": [ "arn:aws:iot:us-east-1:123456789012:topic/foo"

129


] }, { "Effect": "Deny", "Action": [ "iot:Publish" ], "Resource": [ "arn:aws:iot:us-east-1:123456789012:topic/bar" ] } ]}

以下策略允许证书持有者订阅主题筛选条件 foo/bar：

{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "iot:Connect" ], "Resource": [ "*" ] }, { "Effect": "Allow", "Action": [ "iot:Subscribe" ], "Resource": [ "arn:aws:iot:us-east-1:123456789012:topicfilter/foo/bar" ] } ]}

以下策略允许证书持有者在 arn:aws:iot:us-east-1:123456789012:topic/iotmonitor/provisioning/8050373158915119971 主题下发布消息以及订阅主题筛选条件 arn:aws:iot:us-east-1:123456789012:topicfilter/iotmonitor/provisioning/8050373158915119971：

{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "iot:Connect" ], "Resource": [ "*" ] }, { "Effect": "Allow", "Action": [ "iot:Publish", "iot:Receive" ], "Resource": [

130


"arn:aws:iot:us-east-1:123456789012:topic/iotmonitor/provisioning/8050373158915119971" ] }, { "Effect": "Allow", "Action": [ "iot:Subscribe" ], "Resource": [ "arn:aws:iot:us-east-1:123456789012:topicfilter/iotmonitor/provisioning/8050373158915119971" ] } ]}

适用于 HTTP 和 WebSocket 客户端的策略

对于以下操作，AWS IoT 使用附加到 Amazon Cognito 身份（通过 AttachPolicy API）的 AWS IoT 策略缩小附加到 Amazon Cognito 身份池（由经过身份验证的身份组成）的权限范围。这意味着，AmazonCognito 身份需要从附加到池的 IAM 角色策略和通过 AWS IoT AttachPolicy API 附加到 AmazonCognito 身份的 AWS IoT 策略获取权限。

• iot:Connect

• iot:Publish

• iot:Subscribe

• iot:Receive

• iot:GetThingShadow

• iot:UpdateThingShadow

• iot:DeleteThingShadow

Note

对于其他 AWS IoT 操作或未经身份验证的身份，AWS IoT 不会缩小附加到 Amazon Cognito 身份池角色的权限范围。无论是对于经过身份验证的身份还是未经过身份验证的身份，这都是我们建议附加到 Amazon Cognito 池角色的最宽松的策略。

要允许未经过身份验证的 Amazon Cognito 身份通过 HTTP 向任何主题发布消息，请将以下策略附加到Amazon Cognito 身份池角色：

{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "iot:Connect", "iot:Publish", "iot:Subscribe", "iot:Receive", "iot:GetThingShadow", "iot:UpdateThingShadow", "iot:DeleteThingShadow" ], "Resource": ["*"] }]}

131


要允许未经过身份验证的 Amazon Cognito 身份通过 HTTP 向您账户中的任何主题发布 MQTT 消息，请将以下策略附加到 Amazon Cognito 身份池角色：

{ "Version": "2012-10-17", "Statement": [{ "Effect": "Allow", "Action": ["iot:Publish"], "Resource": ["*"] }]}

Note

此示例仅用于说明。除非您的服务确实要求，否则，我们建议您使用较严格的策略，即，禁止未经过身份验证的 Amazon Cognito 身份在任何主题下发布消息的策略。

要允许未经过身份验证的 Amazon Cognito 身份通过 HTTP 在账户中的 topic1 下发布 MQTT 消息，请将以下策略附加到 Amazon Cognito 身份池角色：

{ "Version": "2012-10-17", "Statement": [{ "Effect": "Allow", "Action": ["iot:Publish"], "Resource": ["arn:aws:iot:us-east-1:123456789012:topic/topic1"] }]}

要使经过身份验证的 Amazon Cognito 身份能够通过 HTTP 在 AWS 账户内的 topic1 下发布 MQTT 消息，您必须指定此处列出的两项策略。第一个策略必须附加到 Amazon Cognito 身份池角色。它允许该池中的身份进行发布调用。第二个策略必须使用 AWS IoT AttachPolicy API 附加到 Amazon Cognito 用户。它允许指定的 Amazon Cognito 用户访问 topic1 主题。

Amazon Cognito 身份池策略：

{ "Version": "2012-10-17", "Statement": [{ "Effect": "Allow", "Action": [ "iot:Publish"], "Resource": ["arn:aws:iot:us-east-1:123456789012:topic/topic1"] }]}

Amazon Cognito 用户策略：


同样，以下示例策略允许 Amazon Cognito 用户通过 HTTP 在 topic1 和 topic2 主题下发布 MQTT 消息。需要两项策略。第一项策略允许 Amazon Cognito 身份池角色进行发布调用。第二项策略允许 AmazonCognito 用户访问 topic1 和 topic2 主题。

132

http://docs.aws.amazon.com//iot/latest/apireference/API_AttachPolicy.html




Amazon Cognito 用户策略：

{ "Version": "2012-10-17", "Statement": [{ "Effect": "Allow", "Action": ["iot:Publish"], "Resource": [ "arn:aws:iot:us-east-1:123456789012:topic/topic1", "arn:aws:iot:us-east-1:123456789012:topic/topic2" ] }]}

以下策略允许多个 Amazon Cognito 用户向一个主题发布消息。每个 Amazon Cognito 身份需要两个策略。第一项策略允许 Amazon Cognito 身份池角色进行发布调用。第二个和第三个策略分别允许 Amazon Cognito用户访问主题 topic1 和 topic2。



Amazon Cognito user1 策略：


Amazon Cognito user2 策略：

{ "Version": "2012-10-17", "Statement": [{ "Effect": "Allow", "Action": ["iot:Publish"], "Resource": ["arn:aws:iot:us-east-1:123456789012:topic/topic2"]

133


}]}

接收策略示例

以下策略禁止证书持有者使用任何客户端 ID 接收来自某个主题的消息：

{ "Version": "2012-10-17", "Statement": [ { "Effect": "Deny", "Action": [ "iot:Receive" ], "Resource": [ "arn:aws:iot:us-east-1:123456789012:topic/foo/restricted" ] }, { "Effect": "Allow", "Action": [ "iot:*" ], "Resource": [ "*" ] } ]}

以下策略允许证书持有者使用任何客户端 ID 订阅并接收一个主题中的消息：

{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "iot:Connect" ], "Resource": [*] }, { "Effect": "Allow", "Action": [ "iot:Subscribe" ], "Resource": [ "arn:aws:iot:us-east-1:123456789012:topicfilter/foo/bar" ] }, { "Effect": "Allow", "Action": [ "iot:Receive" ], "Resource": [ "arn:aws:iot:us-east-1:123456789012:topic/foo/bar" ] } ]}

134


证书策略示例以下策略允许设备在名称与设备用于自我身份验证的证书的 certificateId 相同的主题上发布：

{ "Version": "2012-10-17", "Statement": [{ "Effect": "Allow", "Action":["iot:Publish"], "Resource": ["arn:aws:iot:us-east-1:123456789012:topic/${iot:CertificateId}"] }, { "Effect": "Allow", "Action": ["iot:Connect"], "Resource": ["*"] }]}

以下策略允许设备在主题上发布，其中主题名称与设备用于自我身份验证的证书的主题常用名字段相同：

{ "Version": "2012-10-17", "Statement": [{ "Effect": "Allow", "Action":["iot:Publish"], "Resource": ["arn:aws:iot:us-east-1:123456789012:topic/${iot:Certificate.Issuer.CommonName}"] }, { "Effect": "Allow", "Action": ["iot:Connect"], "Resource": ["*"] }]}

当用于对设备进行身份验证的证书的 Subject.CommonName.2 字段设置为“Administrator”时，以下策略允许设备在前缀为“admin/”的主题上发布：

{ "Version": "2012-10-17", "Statement": [{ "Effect": "Allow", "Action": ["iot:Connect"], "Resource": ["*"] }, { "Effect": "Allow", "Action": ["iot:Publish"], "Resource": ["arn:aws:iot:us-east-1:123456789012:topic/admin/*"], "Condition": { "StringEquals": { "iot:Certificate.Subject.CommonName.2": "Administrator" } } }]}

当用于对设备进行身份验证的证书的任意一个 Subject.Common 字段设置为“Administrator”时，以下策略允许设备在前缀为“admin/”的主题上发布：

{

135


"Version": "2012-10-17", "Statement": [{ "Effect": "Allow", "Action": ["iot:Connect"], "Resource": ["*"] }, { "Effect": "Allow", "Action": ["iot:Publish"], "Resource": ["arn:aws:iot:us-east-1:123456789012:topic/admin/*"], "Condition": { "ForAnyValue:StringEquals": { "iot:Certificate.Subject.CommonName.List": "Administrator" } } }]}

事物策略示例

以下策略允许设备在包含事物类型名称和事物名称的特定主题上发布：

{ "Version":"2012-10-17", "Statement":[{ "Effect":"Allow", "Action":["iot:Publish"], "Resource":[ "arn:aws:iot:us-east-1:123456789012:topic/${iot:Connection.Thing.ThingTypeName}/${iot:Connection.Thing.ThingName}" ] }]}

如果用于向 AWS IoT 进行身份验证的证书被附加到正在为其评估策略的事物上，则以下策略允许设备连接。

{ "Version": "2012-10-17", "Statement": [{ "Effect": "Allow", "Action": ["iot:Connect"], "Resource": ["*"], "Condition":{ "Bool":{ "iot:Connection.Thing.IsAttached":["true"] } } }]}

以下策略允许设备在一组主题上发布 (“/foo/bar”和“/foo/baz”)，前提是：

• 与设备关联的事物包含值为“foo”、“bar”或“baz”的“Manufacturer”属性。• 与设备关联的事物位于注册表中，并附加到用于连接 AWS IoT 的证书。

{ "Version": "2012-10-17", "Statement": [{ "Effect": "Allow",

136

AWS IoT 开发人员指南IAM IoT 策略

"Action": ["iot:Publish"], "Resource": [ "arn:aws:iot:us-east-1:123456789012:topic/foo/bar", "arn:aws:iot:us-east-1:123456789012:topic/foo/baz" ], "Condition": { "ForAnyValue:StringLike": { "iot:Connection.Thing.Attributes[Manufacturer]": [ "foo", "bar", "baz" ] } } }]}

以下策略允许设备发布主题，前提是：

• 主题由事物类型名称、“/”和事物名称组成。• 事物位于 Registry 中。• 事物附加到用于连接 AWS IoT 的证书。

{ "Version":"2012-10-17", "Statement":[{ "Effect":"Allow", "Action":["iot:Publish"], "Resource":[ "arn:aws:iot:us-east-1:123456789012:topic/${iot:Connection.Thing.ThingTypeName}/${iot:Connection.Thing.ThingName}" ] }]}

如果相应事物位于注册表中，以下策略将允许设备仅在自己的影子主题上发布。

{ "Version": "2012-10-17", "Statement": [{ "Effect": "Allow", "Action": ["iot:Publish"], "Resource": [ "arn:aws:iot:us-east-1:123456789012:topic/$aws/things/${iot:Connection.Thing.ThingName}/shadow/update" ] }]}

IAM IoT 策略AWS Identity and Access Management 为 AWS IoT 定义的每种操作定义一种策略操作，包括控制层面 API和数据层面 API。

AWS IoT API 权限下表列出了 AWS IoT API、所需的 IAM 权限以及 API 操纵的资源。

137


API 必需权限 (策略操作)

资源

AcceptCertificateTransferiot:AcceptCertificateTransferarn:aws:iot:region:account-id:cert/cert-id

Note

ARN 中指定的 AWS 账户必须是证书将传输到的账户。

AddLoggingRole iot:AddLoggingRole 无

AddThingToThingGroupiot:AddThingToThingGrouparn:aws:iot:region:account-id:thinggroup/thing-group-name

arn:aws:iot:region:account-id:thing/thing-name

AssociateTargetsWithJobiot:AssociateTargetsWithJob无

AttachPolicy iot:AttachPolicy arn:aws:iot:region:account-id:thinggroup/thing-group-name

或者

arn:aws:iot:region:account-id:cert/cert-id

AttachPrincipalPolicy iot:AttachPrincipalPolicyarn:aws:iot:region:account-id:cert/cert-id

AttachThingPrincipal iot:AttachThingPrincipalarn:aws:iot:region:account-id:cert/cert-id

CancelCertificateTransferiot:CancelCertificateTransferarn:aws:iot:region:account-id:cert/cert-id

Note

ARN 中指定的 AWS 账户必须是证书将传输到的账户。

CancelJob iot:CancelJob arn:aws:iot:region:account-id:job/job-id

ClearDefaultAuthorizeriot:ClearDefaultAuthorizer无

CreateAuthorizer iot:CreateAuthorizer arn:aws:iot:region:account-id:authorizer/authorizer-function-name

CreateCertificateFromCsriot:CreateCertificateFromCsr*

CreateJob iot:CreateJob arn:aws:iot:region:account-id:job/job-id

CreateKeysAndCertificateiot:CreateKeysAndCertificate*

CreateMessageSchemaiot:CreateMessageSchema无

CreatePolicy iot:CreatePolicy *

CreatePolicyVersion iot:CreatePolicyVersionarn:aws:iot:region:account-id:policy/policy-name

Note

这必须是 AWS IoT 策略，而不是 IAM 策略。

CreateRoleAlias iot:CreateRoleAlias (参数：roleAlias)

138



资源

arn:aws:iot:region:account-id:rolealias/role-alias-name

CreateThing iot:CreateThing arn:aws:iot:region:account-id:thing/thing-name

CreateThingGroup iot:CreateThingGrouparn:aws:iot:region:account-id:thinggroup/thing-group-name

针对要创建的组和父组 (如果使用)

CreateThingType iot:CreateThingType arn:aws:iot:region:account-id:thingtype/thing-type-name

CreateTopicRule iot:CreateTopicRule arn:aws:iot:region:account-id:rule/rule-name

DeleteAuthorizer iot:DeleteAuthorizer arn:aws:iot:region:account-id:authorizer/authorizer-name

DeleteCACertificate iot:DeleteCACertificatearn:aws:iot:region:account-id:cacert/cert-id

DeleteCertificate iot:DeleteCertificate arn:aws:iot:region:account-id:cert/cert-id

DeleteLoggingLevel iot:DeleteLoggingLevelarn:aws:iot:region:account-id:thinggroup/thing-group-name

DeleteLoggingRole iot:DeleteLoggingRole无

DeleteMessageSchemaiot:DeleteMessageSchema无

DeletePolicy iot:DeletePolicy arn:aws:iot:region:account-id:policy/policy-name

DeletePolicyVersion iot:DeletePolicyVersionarn:aws:iot:region:account-id:policy/policy-name

DeleteRegistrationCodeiot:DeleteRegistrationCode*

DeleteRoleAlias iot:DeleteRoleAlias arn:aws:iot:region:account-id:rolealias/role-alias-name

DeleteThing iot:DeleteThing arn:aws:iot:region:account-id:thing/thing-name

DeleteThingGroup iot:DeleteThingGrouparn:aws:iot:region:account-id:thinggroup/thing-group-name

DeleteThingType iot:DeleteThingType arn:aws:iot:region:account-id:thingtype/thing-type-name

DeleteTopicRule iot:DeleteTopicRule arn:aws:iot:region:account-id:rule/rule-name

DeleteV2LoggingLeveliot:DeleteV2LoggingLevelarn:aws:iot:region:account-id:thinggroup/thing-group-name

DeprecateThingType iot:DeprecateThingTypearn:aws:iot:region:account-id:thingtype/thing-type-name

DescribeAuthorizer iot:DescribeAuthorizerarn:aws:iot:region:account-id:authorizer/authorizer-function-name

(参数：authorizerName)无

139



资源

DescribeCACertificateiot:DescribeCACertificatearn:aws:iot:region:account-id:cacert/cert-id

DescribeCertificate iot:DescribeCertificatearn:aws:iot:region:account-id:cert/cert-id

DescribeDefaultAuthorizeriot:DescribeDefaultAuthorizer无

DescribeEndpoint iot:DescribeEndpoint *

DescribeEventConfigurationsiot:DescribeEventConfigurations无

DescribeIndex iot:DescribeIndex arn:aws:iot:region:account-id:index/index-name

DescribeJob iot:DescribeJob arn:aws:iot:region:account-id:job/job-id

DescribeJobExecutioniot:DescribeJobExecution无

DescribeRoleAlias iot:DescribeRoleAliasarn:aws:iot:region:account-id:rolealias/role-alias-name

DescribeThing iot:DescribeThing arn:aws:iot:region:account-id:thing/thing-name

DescribeThingGroup iot:DescribeThingGrouparn:aws:iot:region:account-id:thinggroup/thing-group-name

DescribeThingRegistrationTaskiot:DescribeThingRegistrationTask无

DescribeThingType iot:DescribeThingTypearn:aws:iot:region:account-id:thingtype/thing-type-name

DetachPolicy iot:DetachPolicy arn:aws:iot:region:account-id:cert/cert-id

或者

arn:aws:iot:region:account-id:thinggroup/thing-group-name

DetachPrincipalPolicyiot:DetachPrincipalPolicyarn:aws:iot:region:account-id:cert/cert-id

DetachThingPrincipaliot:DetachThingPrincipalarn:aws:iot:region:account-id:cert/cert-id

DisableTopicRule iot:DisableTopicRule arn:aws:iot:region:account-id:rule/rule-name

EnableTopicRule iot:EnableTopicRule arn:aws:iot:region:account-id:rule/rule-name

GetEffectivePolicies iot:GetEffectivePoliciesarn:aws:iot:region:account-id:cert/cert-id

GetIndexingConfigurationiot:GetIndexingConfiguration无

GetJobDocument iot:GetJobDocument arn:aws:iot:region:account-id:job/job-id

GetLoggingOptions iot:GetLoggingOptions*

GetLoggingOptionsV29iot:GetLoggingOptionsV2无

GetLoggingRole iot:GetLoggingRole 无

GetMessageSchema iot:GetMessageSchema无

GetPolicy iot:GetPolicy arn:aws:iot:region:account-id:policy/policy-name

140



资源

GetPolicyVersion iot:GetPolicyVersion arn:aws:iot:region:account-id:policy/policy-name

GetRegistrationCode iot:GetRegistrationCode*

GetTopicRule iot:GetTopicRule arn:aws:iot:region:account-id:rule/rule-name

GetV2LoggingOptionsiot:GetV2LoggingOptions无

ListAttachedPolicies iot:ListAttachedPoliciesarn:aws:iot:region:account-id:thinggroup/thing-group-name

或者

arn:aws:iot:region:account-id:cert/cert-id

ListAuthorizers iot:ListAuthorizers 无

ListCACertificates iot:ListCACertificates *

ListCertificates iot:ListCertificates *

ListCertificatesByCA iot:ListCertificatesByCA*

ListIndices iot:ListIndices 无

ListJobExecutionsForJobiot:ListJobExecutionsForJob无

ListJobExecutionsForThingiot:ListJobExecutionsForThing无

ListJobs iot:ListJobs arn:aws:iot:region:account-id:thinggroup/thing-group-name

如果使用 thingGroupName 参数

ListLoggingLevels iot:ListLoggingLevels 无

ListMessageSchemasiot:ListMessageSchemas无

ListOutgoingCertificatesiot:ListOutgoingCertificates*

ListPolicies iot:ListPolicies *

ListPolicyPrincipals iot:ListPolicyPrincipalsarn:aws:iot:region:account-id:policy/policy-name

ListPolicyVersions iot:ListPolicyVersionsarn:aws:iot:region:account-id:policy/policy-name

ListPrincipalPolicies iot:ListPrincipalPoliciesarn:aws:iot:region:account-id:cert/cert-id

ListPrincipalThings iot:ListPrincipalThingsarn:aws:iot:region:account-id:cert/cert-id

ListRoleAliases iot:ListRoleAliases 无

ListTargetsForPolicy iot:ListTargetsForPolicyarn:aws:iot:region:account-id:policy/policy-name

ListThingGroups iot:ListThingGroups 无

ListThingGroupsForThingiot:ListThingGroupsForThingarn:aws:iot:region:account-id:thing/thing-name

ListThingPrincipals iot:ListThingPrincipalsarn:aws:iot:region:account-id:thing/thing-name

141



资源

ListThingRegistrationTaskReportsiot:ListThingRegistrationTaskReports无

ListThingRegistrationTasksiot:ListThingRegistrationTasks无

ListThingTypes iot:ListThingTypes *

ListThings iot:ListThings *

ListThingsInThingGroupiot:ListThingsInThingGrouparn:aws:iot:region:account-id:thinggroup/thing-group-name

ListTopicRules iot:ListTopicRules *

ListV2LoggingLevels iot:ListV2LoggingLevels无

RegisterCACertificateiot:RegisterCACertificate*

RegisterCertificate iot:RegisterCertificate*

RegisterThing iot:RegisterThing 无

RejectCertificateTransferiot:RejectCertificateTransferarn:aws:iot:region:account-id:cert/cert-id

RemoveThingFromThingGroupiot:RemoveThingFromThingGrouparn:aws:iot:region:account-id:thinggroup/thing-group-name

arn:aws:iot:region:account-id:thing/thing-name

ReplaceTopicRule iot:ReplaceTopicRulearn:aws:iot:region:account-id:rule/rule-name

SearchIndex iot:SearchIndex arn:aws:iot:region:account-id:index/index-id

SetDefaultAuthorizer iot:SetDefaultAuthorizerarn:aws:iot:region:account-id:authorizer/authorizer-function-name

SetDefaultPolicyVersioniot:SetDefaultPolicyVersionarn:aws:iot:region:account-id:policy/policy-name

SetLoggingLevel iot:SetLoggingLevel 无

SetLoggingOptions iot:SetLoggingOptionsarn:aws:iot:region:account-id:role/role-name

SetLoggingOptionsV2iot:SetLoggingOptionsV2arn:aws:iot:region:account-id:role/role-name

SetV2LoggingLevel iot:SetV2LoggingLevelarn:aws:iot:region:account-id:thinggroup/thing-group-name

SetV2LoggingOptionsiot:SetV2LoggingOptionsarn:aws:iot:region:account-id:role/role-name

StartThingRegistrationTaskiot:StartThingRegistrationTask无

StopThingRegistrationTaskiot:StopThingRegistrationTask无

TestAuthorization iot:TestAuthorization arn:aws:iot:region:account-id:cert/cert-id

TestInvokeAuthorizeriot:TestInvokeAuthorizer无

TransferCertificate iot:TransferCertificatearn:aws:iot:region:account-id:cert/cert-id

UpdateAuthorizer iot:UpdateAuthorizer arn:aws:iot:region:account-id:authorizerfunction/authorizer-function-name

142



资源

UpdateCACertificate iot:UpdateCACertificatearn:aws:iot:region:account-id:cacert/cert-id

UpdateCertificate iot:UpdateCertificate arn:aws:iot:region:account-id:cert/cert-id

UpdateEventConfigurationsiot:UpdateEventConfigurations无

UpdateIndexingConfigurationiot:UpdateIndexingConfiguration无

UpdateMessageSchemaiot:UpdateMessageSchema无

UpdateRoleAlias iot:UpdateRoleAlias arn:aws:iot:region:account-id:rolealias/role-alias-name

UpdateThing iot:UpdateThing arn:aws:iot:region:account-id:thing/thing-name

UpdateThingGroup iot:UpdateThingGrouparn:aws:iot:region:account-id:thinggroup/thing-group-name

UpdateThingGroupsForThingiot:UpdateThingGroupsForThingarn:aws:iot:region:account-id:thing/thing-name

IAM 策略模板AWS IoT 提供了一组 IAM 策略模板，您可以按原样使用，也可以将其作为起点来创建自定义的 IAM 策略。利用这些模板，您可以访问配置和数据操作。利用配置操作，您可以创建事物、证书、策略和规则。数据操作通过 MQTT 或 HTTP 协议发送数据。下表对这些模板进行了说明。

策略模板描述

AWSIotLogging 允许相关身份配置 CloudWatch 日志记录。本策略附加到您的 CloudWatch 日志记录角色。

AWSIoTConfigAccess 允许相关身份访问所有 AWS IoT 配置操作。请注意，此策略有能力影响数据处理和存储。

AWSIoTConfigReadOnlyAccess 允许相关身份调用只读配置操作。

AWSIoTDataAccess 允许相关身份全面访问所有 AWS IoT 数据操作。数据操作通过 MQTT 或 HTTP 协议发送数据。

AWSIoTFullAccess 允许相关身份全面访问所有 AWS IoT 配置和数据操作。

AWSIoTOTAUpdate 允许相关身份访问权限创建 AWS IoT 作业和 AWSIoT 代码签名作业。

AWSIoTRuleActions 允许相关身份访问 AWS IoT 规则操作中所有受支持的 AWS 服务。

AWSIoTThingsRegistration 允许相关身份使用 StartThingRegistrationTask 批量注册事物。请注意，此策略有能力影响数据处理和存储。

143

http://docs.aws.amazon.com/iot/latest/apireference/API_StartThingRegistrationTask.html

AWS IoT 开发人员指南授予直接调用 AWS 服务的权限

授予直接调用 AWS 服务的权限设备可使用 X.509 证书通过 TLS 双向身份验证协议连接到 AWS IoT。其他 AWS 服务不支持基于证书的身份验证，但可使用签名版本 4 格式的 AWS 凭证调用这些服务。在使用证书对某个设备进行身份验证后，AWS IoT 可代表该设备代入角色并从 IAM 请求临时凭证。随后，该设备可使用该凭证调用其他 AWS 服务。

可使用 HTTP GET 在端口 443 上请求临时凭证，例如：

https://<your-aws-account-id>.credentials.iot.region.amazonaws.com:443/role-aliases/<your-role-alias>/credentials

Note

要查找您的终端节点，可使用 describe-endpoint CLI 命令，并将iot:CredentialProvider 指定为终端节点类型。

要确保您的设备正在与 AWS IoT (而不是假冒它的服务) 进行通信，请将 RSA Amazon Root CA 1 和VeriSign Class 3 Public Primary G5 根 CA 证书复制到您的设备。

在发出临时凭证请求时，您可以选择在名为 x-amzn-iot-thingname 的请求标头中提供事物名称。要在请求标头中使用 thingName，您必须使用 AttachThingPrincipal API 将事物附加到设备证书。在设备通过传递thingName 来请求凭证时，AWS IoT 会检查是否已将 thingName 附加到 TLS 握手期间提供的证书；除非已附加，否则将不会提供临时凭证。

通过在请求中传递事物名称，您可以使用 thingName 和 thingType 作为角色的访问策略中的策略变量以实现精细访问。有关更多信息，请参阅 AWS IoT 策略变量 (p. 121)。除非在请求标头中传递事物名称，否则您无法在策略中使用事物变量。

附加到设备证书的策略必须向设备授予代入角色的权限。您可以通过授予对角色别名的 ARN 执行iot:AssumeRoleWithCertificate 操作的权限来做到这一点，例如 arn:aws:iot:<your-region>:<your-aws-account-id>:rolealias/<role-alias-name>

您可以通过创建一个 IAM 角色并向该角色附加策略，来授予对临时凭证的权限。您可以通过使用策略变量thingName、thingType 和 certificateId，对授予此角色的权限进行精细控制。有关更多信息，请参阅 AWS IoT 策略变量 (p. 121)。

打算直接调用 AWS 服务的设备必须知道在连接到 AWS IoT 时要使用的角色 ARN。而对角色 ARN 进行硬编码并不是一个很好的解决方案，因为您必须在角色 ARN 发生更改时更新设备。更好的解决方案是创建一个指向角色 ARN 的角色别名，并在您的设备上使用该别名。如果角色 ARN 发生更改，则可更新角色别名，而无需在设备上做出任何更改。使用 CreateRoleAlias API 创建角色别名。此 API 接受以下参数：

credentialDurationInSeconds

凭证有效的时间长度 (以秒为单位)。roleAlias

一个标识角色别名的任意字符串。必须为 1-128 个字符，并且只能包含 A-Za-z0-9=,@- 字符。roleArn

角色别名所指向的角色的 ARN。

请注意，执行 CreateRoleAlias 的实体本身必须具有执行此操作所需的足够权限。具体而言，它必须附加了一个策略，该策略允许对创建的 IAM 角色 (将为其创建别名) 的 ARN 执行 iam:PassRole 操作。

在请求临时凭证时，可以在请求标头中传递事物名称。如果存在事物名称，您可以使用事物策略变量来缩小AWS IoT 所返回的凭证的范围。

ThingName 是一个可选的请求参数，可通过名为 x-amzn-iot-thingname 的 HTTP 请求标头传递。

144



http://docs.aws.amazon.com/iot/latest/apireference/API_AttachThingPrincipal.html

AWS IoT 开发人员指南跨账户访问

使用 TLS 双向身份验证在端口 443 上通过 HTTP 向 AWS IoT 发出临时凭证请求。此请求必须是 HTTP GET请求。URL 类似于：

https://<your-iot-endpoint>.iot.<your-aws-region>.amazonaws.com:443/role-aliases/<roleAlias>/credentials

跨账户访问AWS IoT 允许您支持委托人订阅并不属于委托人的 AWS 账户中定义的主题或向该主题发布消息。您可以通过创建 IAM 策略和 IAM 角色并将策略附加到角色来配置跨账户访问。

首先，创建一个 IAM 策略，就像您在 AWS 账户中为其他用户和证书创建策略一样。例如，以下策略允许连接到 /foo/bar 主题并向该主题发布消息。

{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "iot:Connect" ], "Resource": [ "*" ] }, { "Effect": "Allow", "Action": [ "iot:Publish" ], "Resource": [ "arn:aws:iot:us-east-1:123456789012:topic/foo/bar" ] }]}

接下来，请执行为 IAM 用户创建角色中的步骤。输入您希望其共享访问权限的 AWS 账户的 ID。接下来是最后一步，请将您刚刚创建的策略附加到角色。如果您稍后需要修改要向其授予权限的 AWS 账户 ID，可使用以下信任策略格式执行操作。

{ "Version":"2012-10-17", "Statement":[{ "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam:us-east-1:111111111111:user/MyUser" }, "Action": "sts:AssumeRole" }]}

传输安全AWS IoT 消息代理和 Device Shadow 服务可以对通过 TLS 版本 1.2 进行的所有通信加密。TLS 用于确保受AWS IoT 支持的应用程序协议（MQTT、HTTP）的保密性。TLS 适用于许多编程语言和操作系统。

145

http://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-user.html

https://en.wikipedia.org/wiki/Transport_Layer_Security

https://en.wikipedia.org/wiki/Transport_Layer_Security#TLS_1.2

AWS IoT 开发人员指南TLS 密码包支持

对于 MQTT，TLS 可将设备与代理之间的连接加密。AWS IoT 使用 TLS 客户端身份验证来识别设备。对于HTTP，TLS 可将设备与代理之间的连接加密。身份验证工作委派给 AWS Signature 版本 4 执行。

TLS 密码包支持AWS IoT 支持以下密码包：

• ECDHE-ECDSA-AES128-GCM-SHA256（推荐）• ECDHE-RSA-AES128-GCM-SHA256（推荐）• ECDHE-ECDSA-AES128-SHA256• ECDHE-RSA-AES128-SHA256• ECDHE-ECDSA-AES128-SHA• ECDHE-RSA-AES128-SHA• ECDHE-ECDSA-AES256- GCM-SHA384• ECDHE-RSA-AES256- GCM-SHA384• ECDHE-ECDSA-AES256-SHA384• ECDHE-RSA-AES256-SHA384• ECDHE-RSA-AES256-SHA• ECDHE-ECDSA-AES256-SHA• AES128-GCM-SHA256• AES128-SHA256• AES128-SHA• AES256-GCM-SHA384• AES256-SHA256• AES256-SHA

146

AWS IoT 开发人员指南协议

AWS IoT 的消息代理AWS IoT 消息代理是一项发布/订阅代理服务，可与 AWS IoT 相互发送和接收消息。在与 AWS IoT 通信时，客户端将经过编址的消息发送到 Sensor/temp/room1 之类的主题。进而，消息代理将消息发送到已注册接收该主题消息的所有客户端。发送消息的操作被称为发布。已注册接收该主题筛选消息的操作被称为订阅。

每个 AWS 账户和区域对的主题命名空间均是独立的。例如，AWS 账户的 Sensor/temp/room1 主题独立于另一 AWS 账户的 Sensor/temp/room1 主题。在区域方面，情况同样如此。us-east-1 内同一 AWS 账户中的 Sensor/temp/room1 主题独立于 us-east-2 内的同一主题。AWS IoT 不支持跨 AWS 账户和区域发送和接收消息。

消息代理负责维护由所有客户端会话及每个会话的订阅组成的列表。向主题发布消息时，代理将检查订阅映射到该主题的会话。然后，代理将发布消息转发到目前连接到客户端的所有会话。

协议消息代理支持使用 MQTT 协议进行发布和订阅，并支持使用 HTTPS 协议进行发布。两个协议均通过 IP 版本 4 和 IP 版本 6 受支持。消息代理还支持基于 WebSocket 的 MQTT 协议。

协议/端口映射下表显示 AWS IoT 支持的每个协议、身份验证方法和每个协议使用的端口。

协议、身份验证及端口映射

协议身份验证 Port

MQTT 客户端证书 8883、443†

HTTP 客户端证书 8443

HTTP SigV4 443

MQTT + WebSocket SigV4 443

†希望通过将 MQTT 与端口 443 上的 X.509 客户端证书身份验证结合使用来进行连接的客户端必须实施应用程序层协议协商 (ALPN) TLS 扩展并将 x-amzn-mqtt-ca 作为 ProtocolNameList 中的 ProtocolName传递。请注意，通过将 MQTT 与端口 8883 上的 X.509 客户端证书身份验证结合使用来打开连接不需要ALPN。

MQTTMQTT 是专为受限设备设计的、广泛应用的轻型消息处理协议。有关更多信息，请参阅 MQTT。

尽管 AWS IoT 消息代理的实施基于 MQTT 3.1.1 版，但却与规范存在如下偏差：

• 在 AWS IoT 中，利用服务质量 (QoS) 0 订阅主题意味着消息将发送零次或多次。消息可能会多次发送。多次发送的消息在发送时可能会使用不同的数据包 ID。在这些情况下，不会设置 DUP 标志。

• AWS IoT 不支持利用 QoS 2 进行发布和订阅。请求 QoS 2 时，AWS IoT 消息代理不会发送 PUBACK 或SUBACK。

147

https://tools.ietf.org/html/rfc7301

https://tools.ietf.org/html/rfc7301

https://tools.ietf.org/html/rfc7301#section-3.1

https://tools.ietf.org/html/rfc7301#section-3.1

http://www.mqtt.org

AWS IoT 开发人员指南HTTP

• 用于发布和订阅主题的各 QoS 级别之间毫无关系。一个客户端可使用 QoS1 订阅主题，而另一个客户端可使用 QoS0 向同一主题发布消息。

• 在响应连接请求时，消息代理将发送 CONNACK 消息。此消息包含一个标志，用于指明该连接是否会恢复上一个会话。如果两个 MQTT 客户端同时连接到同一客户端 ID，该标志的值可能会不正确。

• 当客户端订阅主题时，在消息代理开始发送 SUBACK 和客户端开始收到新的匹配消息之间存在时间延迟。

• MQTT 规范提供了相应的配置，以供发布者用于请求代理将发送到主题的最新消息保留下来并发送给未来的所有主题订阅者。AWS IoT 不支持保留的消息。如果请求保留消息，则将断开连接。

• 消息代理使用客户端 ID 标识每个客户。客户端 ID 作为 MQTT 有效负载的一部分从客户端传递到消息代理。两个具有相同客户端 ID 的客户端不得同时连接到消息代理。当某个客户端使用另一客户端正在使用的客户端 ID 连接到消息代理时，系统将向两个客户端发送 CONNACK 消息，当前连接的客户端也将断开连接。

• 消息代理不支持持久性会话 (将 cleanSession 标记设置为 false 进行的连接)。AWS IoT 消息代理假设所有会话均为干净会话，并且未在这些会话中存储消息。如果 MQTT 客户端尝试在 cleanSession 设置为 false 的情况下连接到 AWS IoT 消息代理，则客户端将断开连接。

• 在极少数情况下，消息代理可能会使用不同的数据包 ID 再次发送相同的逻辑 PUBLISH 消息。• 消息代理并不保证收到消息和 ACK 的顺序。

HTTP消息代理支持客户端通过 REST API 使用 HTTP 协议进行连接。客户端通过将 POST 消息发送到 <AWS IoTEndpoint>/<url_encoded_topic_name>?qos=1" 进行发布。

例如，您可以使用 curl 模拟按钮按压。如果您按照 AWS IoT 入门 (p. 4)中的教程操作，而不是像在 AWS IoTMQTT 客户端 (p. 28)中一样使用 AWS IoT MQTT 客户端发布消息，则请使用类似如下的命令：

curl --tlsv1.2 --cacert root-CA.crt --cert 4b7828d2e5-certificate.pem.crt --key 4b7828d2e5-private.pem.key -X POST -d "{ \"serialNumber\": \"G030JF053216F1BS\", \"clickType\": \"SINGLE\", \"batteryVoltage\": \"2000mV\" }" "https://a1pn10j0v8htvw.iot.us-east-1.amazonaws.com:8443/topics/iotbutton/virtualButton?qos=1"

--tlsv1.2

使用 TLSv1.2 (SSL)。必须随 OpenSSL 安装 curl，并且务必使用 TLS 1.2 版。--cacert <filename>

用于验证对等项的 CA 证书文件名。--cert <filename>

客户端证书文件名。--key <filename>

私有密钥文件名。-X POST

请求的类型，此处为 POST。-d <data>

要发布的 HTTP POST 数据。在这种情况下，我们会模拟通过一次按钮按压发送的数据。"https://..."

URL。此处指的是事物的 REST API 终端节点。(要查找事物的终端节点，请从 AWS IoT 控制台选择Registry 来展开选项。选择 Things，选择事物，然后选择 Interact。）在终端节点后添加端口 (:8443)，后跟主题；最后，在查询字符串 (?qos=1) 中指定服务质量。

148

https://curl.haxx.se

AWS IoT 开发人员指南基于 WebSocket 的 MQTT 协议

基于 WebSocket 的 MQTT 协议AWS IoT 支持基于 WebSocket 的 MQTT 协议，从而使基于浏览器的远程应用程序能够通过连接到 AWS IoT的设备使用 AWS 凭证发送和接收消息。指定 AWS 凭证时使用的是 AWS 签名版本 4。WebSocket 支持服务适用于 TCP 端口 443，因此，消息可以穿过大多数防火墙和 Web 代理。

通过发送 HTTP GET 请求在客户端上启动 WebSocket 连接。您使用的 URL 应采用以下格式：

wss://<endpoint>.iot.<region>.amazonaws.com/mqtt

wss

指定 WebSocket 协议。终端节点

特定于您的 AWS 账户的 AWS IoT终端节点。您可以使用 AWS IoT CLI describe-endpoint 命令找到该终端节点。

region

您的 AWS 账户所在的 AWS 区域。mqtt

指定您将使用 WebSocket 协议发送 MQTT 消息。

当服务器进行响应时，客户端将发送升级请求，向服务器表明它将使用 WebSocket 协议进行通信。在服务器确认升级请求后，将使用 WebSocket 协议执行所有通信。您使用的 WebSocket 实施将充当传输协议。您使用 WebSocket 协议发送的数据是 MQTT 消息。

在 Web 应用程序中使用 WebSocket 协议大多数 Web 浏览器提供的 WebSocket 实施不允许修改 HTTP 标头，因此，您必须在查询字符串中添加签名版本 4 信息。有关更多信息，请参阅将签名信息添加到查询字符串。

以下 JavaScript 将定义在生成签名版本 4 请求时使用的一些使用程序函数。

/** * utilities to do sigv4 * @class SigV4Utils */ function SigV4Utils() {}

SigV4Utils.getSignatureKey = function (key, date, region, service) { var kDate = AWS.util.crypto.hmac('AWS4' + key, date, 'buffer'); var kRegion = AWS.util.crypto.hmac(kDate, region, 'buffer'); var kService = AWS.util.crypto.hmac(kRegion, service, 'buffer'); var kCredentials = AWS.util.crypto.hmac(kService, 'aws4_request', 'buffer'); return kCredentials;};

SigV4Utils.getSignedUrl = function(host, region, credentials) { var datetime = AWS.util.date.iso8601(new Date()).replace(/[:\-]|\.\d{3}/g, ''); var date = datetime.substr(0, 8);

var method = 'GET'; var protocol = 'wss'; var uri = '/mqtt'; var service = 'iotdevicegateway'; var algorithm = 'AWS4-HMAC-SHA256';

var credentialScope = date + '/' + region + '/' + service + '/' + 'aws4_request';

149

https://en.wikipedia.org/wiki/WebSocket

http://docs.aws.amazon.com/general/latest/gr//sigv4_signing.html

http://docs.aws.amazon.com/cli/latest/reference/iot/describe-endpoint.html

http://docs.aws.amazon.com/general/latest/gr/sigv4-add-signature-to-request.html#sigv4-add-signature-querystring


var canonicalQuerystring = 'X-Amz-Algorithm=' + algorithm; canonicalQuerystring += '&X-Amz-Credential=' + encodeURIComponent(credentials.accessKeyId + '/' + credentialScope); canonicalQuerystring += '&X-Amz-Date=' + datetime; canonicalQuerystring += '&X-Amz-SignedHeaders=host';

var canonicalHeaders = 'host:' + host + '\n'; var payloadHash = AWS.util.crypto.sha256('', 'hex') var canonicalRequest = method + '\n' + uri + '\n' + canonicalQuerystring + '\n' + canonicalHeaders + '\nhost\n' + payloadHash;

var stringToSign = algorithm + '\n' + datetime + '\n' + credentialScope + '\n' + AWS.util.crypto.sha256(canonicalRequest, 'hex'); var signingKey = SigV4Utils.getSignatureKey(credentials.secretAccessKey, date, region, service); var signature = AWS.util.crypto.hmac(signingKey, stringToSign, 'hex');

canonicalQuerystring += '&X-Amz-Signature=' + signature; if (credentials.sessionToken) { canonicalQuerystring += '&X-Amz-Security-Token=' + encodeURIComponent(credentials.sessionToken); }

var requestUrl = protocol + '://' + host + uri + '?' + canonicalQuerystring; return requestUrl;};

创建签名版本 4 请求

1. 创建规范的签名版本 4 请求。

以下 JavaScript 代码将创建规范请求：

var datetime = AWS.util.date.iso8601(new Date()).replace(/[:\-]|\.\d{3}/g, '');var date = datetime.substr(0, 8);

var method = 'GET';var protocol = 'wss';var uri = '/mqtt';var service = 'iotdevicegateway';var algorithm = 'AWS4-HMAC-SHA256';

var credentialScope = date + '/' + region + '/' + service + '/' + 'aws4_request';var canonicalQuerystring = 'X-Amz-Algorithm=' + algorithm;canonicalQuerystring += '&X-Amz-Credential=' + encodeURIComponent(credentials.accessKeyId + '/' + credentialScope);canonicalQuerystring += '&X-Amz-Date=' + datetime;canonicalQuerystring += '&X-Amz-SignedHeaders=host';

var canonicalHeaders = 'host:' + host + '\n';var payloadHash = AWS.util.crypto.sha256('', 'hex')var canonicalRequest = method + '\n' + uri + '\n' + canonicalQuerystring + '\n' + canonicalHeaders + '\nhost\n' + payloadHash;

2. 创建要签名的字符串，生成签名密钥，然后为该字符串签名。

采用在上一步中创建的规范 URL 并将其组合到待签名的字符串中。为此，请创建由哈希算法、日期、凭证范围以及规范请求的 SHA 组成的字符串。然后，生成签名密钥并为该字符串签名，如以下 JavaScript代码所示。

150

AWS IoT 开发人员指南主题：

如果您使用的是当前不受支持的编程或脚本语言，则只要使用 AWS 签名版本 4 为初始 WebSocket 升级请求 (HTTP POST) 签名，便可以使用任何现有的 WebSocket 库。有些 MQTT 客户端（如 Eclipse Paho forJavaScript）可为 WebSocket 协议提供本机支持。

主题：消息代理使用主题将消息从发布客户端路由到订阅客户端。正斜杠 (/) 用于分隔主题层次结构。下表列出了订阅时可在主题筛选条件中使用的通配符。

主题通配符

通配符描述

# 必须是您要订阅的主题中的最后一个字符。通过将当前树与所有子树相匹配来发挥通配符的作用。例如，Sensor/# 订阅将接收发布到Sensor/、Sensor/temp 和 Sensor/temp/room1 的消息，但不会接收发布到 Sensor 的消息。

+ 精确匹配主题层次结构中的一个项目。例如，Sensor/+/room1 订阅将接收发布到Sensor/temp/room1、Sensor/moisture/room1 等的消息。

预留的主题任何以 $ 开头的主题都被视为预留的主题，除非下面列出的主题之外，不支持用于进行发布和订阅。在任何其他以 $ 开头的主题中尝试发布或订阅将导致连接被终止。

主题允许的操作描述

$aws/events/presence/connected/clientId

Subscribe 当使用特定客户端 ID 的MQTT 客户端连接至 AWS IoT时，AWS IoT 将向此主题发布。有关更多信息，请参阅连接/断开连接事件 (p. 155)。

$aws/events/presence/disconnected/clientId

Subscribe 当使用特定客户端 ID 的 MQTT客户端与 AWS IoT 断开连接时，AWS IoT 将向此主题发布。有关更多信息，请参阅连接/断开连接事件 (p. 155)。

$aws/events/subscriptions/subscribed/clientId

Subscribe 当使用特定客户端 ID 的MQTT 客户端订阅 MQTT 主题时，AWS IoT 将向此主题发布。有关更多信息，请参阅订阅/取消订阅事件 (p. 155)。

$aws/events/subscriptions/unsubscribed/clientId

Subscribe 当使用特定客户端 ID 的 MQTT客户端取消订阅 MQTT 主题时，AWS IoT 将向此主题发布。有关更多信息，请参阅订阅/取消订阅事件 (p. 155)。

152

http://www.eclipse.org/paho/

http://www.eclipse.org/paho/

AWS IoT 开发人员指南预留的主题


$aws/things/thingName/shadow/delete

发布/订阅设备或应用程序向此主题发布消息以删除影子。有关更多信息，请参阅 http://docs.aws.amazon.com/iot/latest/developerguide//device-shadow-mqtt.html#delete-pub-sub-topic。

$aws/things/thingName/shadow/delete/accepted

Subscribe 当一个影子被删除时，DeviceShadow 服务将向此主题发送消息。有关更多信息，请参阅 http://docs.aws.amazon.com/iot/latest/developerguide//device-shadow-mqtt.html#delete-accepted-pub-sub-topic。

$aws/things/thingName/shadow/delete/rejected

Subscribe 当删除影子的请求遭拒时，Device Shadow 服务将向此主题发送消息。有关更多信息，请参阅 http://docs.aws.amazon.com/iot/latest/developerguide//device-shadow-mqtt.html#delete-rejected-pub-sub-topic。

$aws/things/thingName/shadow/get

发布/订阅应用程序或事物向此主题发布空消息来获取影子。有关更多信息，请参阅 http://docs.aws.amazon.com/iot/latest/developerguide//device-shadow-mqtt.html。

$aws/things/thingName/shadow/get/accepted

Subscribe 当获取影子的请求获批时，Device Shadow 服务将向此主题发送消息。有关更多信息，请参阅 http://docs.aws.amazon.com/iot/latest/developerguide//device-shadow-mqtt.html#get-accepted-pub-sub-topic。

$aws/things/thingName/shadow/get/rejected

Subscribe 当获取影子的请求遭拒时，Device Shadow 服务将向此主题发送消息。有关更多信息，请参阅 http://docs.aws.amazon.com/iot/latest/developerguide//device-shadow-mqtt.html#get-rejected-pub-sub-topic。

153

http://docs.aws.amazon.com/iot/latest/developerguide//device-shadow-mqtt.html#delete-pub-sub-topic





http://docs.aws.amazon.com/iot/latest/developerguide//device-shadow-mqtt.html#delete-accepted-pub-sub-topic





http://docs.aws.amazon.com/iot/latest/developerguide//device-shadow-mqtt.html#delete-rejected-pub-sub-topic





http://docs.aws.amazon.com/iot/latest/developerguide//device-shadow-mqtt.html




http://docs.aws.amazon.com/iot/latest/developerguide//device-shadow-mqtt.html#get-accepted-pub-sub-topic





http://docs.aws.amazon.com/iot/latest/developerguide//device-shadow-mqtt.html#get-rejected-pub-sub-topic





AWS IoT 开发人员指南生命周期事件


$aws/things/thingName/shadow/update

发布/订阅事物或应用程序向此主题发布消息以更新影子。有关更多信息，请参阅 http://docs.aws.amazon.com/iot/latest/developerguide//device-shadow-mqtt.html#update-pub-sub-topic。

$aws/things/thingName/shadow/update/accepted

Subscribe 当影子更新成功时，DeviceShadow 服务将向此主题发送消息。有关更多信息，请参阅 http://docs.aws.amazon.com/iot/latest/developerguide//device-shadow-mqtt.html#update-accepted-pub-sub-topic。

$aws/things/thingName/shadow/update/rejected

Subscribe 当影子更新遭拒时，DeviceShadow 服务将向此主题发送消息。有关更多信息，请参阅 http://docs.aws.amazon.com/iot/latest/developerguide//device-shadow-mqtt.html#update-rejected-pub-sub-topic。

$aws/things/thingName/shadow/update/delta

Subscribe 当检测到影子的“reported”部分与“desired”部分之间存在差异时，Device Shadow 服务将向此主题发送消息。有关更多信息，请参阅 http://docs.aws.amazon.com/iot/latest/developerguide//device-shadow-mqtt.html#update-delta-pub-sub-topic。

$aws/things/thingName/shadow/update/documents

Subscribe 每次影子更新成功执行时，AWS IoT 都会向该主题发布状态文档。有关更多信息，请参阅 http://docs.aws.amazon.com/iot/latest/developerguide//device-shadow-mqtt.html#update-documents-pub-sub-topic。

生命周期事件AWS IoT 在以下各部分中讨论的 MQTT 主题下发布生命周期事件。借助这些消息，您可以接收消息代理发出的生命周期事件通知。

Note

生命周期消息可能不会按顺序发送。您可能会收到重复的消息。

154

http://docs.aws.amazon.com/iot/latest/developerguide//device-shadow-mqtt.html#update-pub-sub-topic





http://docs.aws.amazon.com/iot/latest/developerguide//device-shadow-mqtt.html#update-accepted-pub-sub-topic





http://docs.aws.amazon.com/iot/latest/developerguide//device-shadow-mqtt.html#update-rejected-pub-sub-topic





http://docs.aws.amazon.com/iot/latest/developerguide//device-shadow-mqtt.html#update-delta-pub-sub-topic





http://docs.aws.amazon.com/iot/latest/developerguide//device-shadow-mqtt.html#update-documents-pub-sub-topic





AWS IoT 开发人员指南连接/断开连接事件

连接/断开连接事件AWS IoT 在客户端建立连接或断开连接时将消息发布到以下 MQTT 主题：

$aws/events/presence/connected/clientId

或者

$aws/events/presence/disconnected/clientId

其中 clientId 是连接到 AWS IoT 消息代理或与之断开连接的 MQTT 客户端 ID。


{ "clientId": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6", "timestamp": 1460065214626, "eventType": "connected", "sessionIdentifier": "00000000-0000-0000-0000-000000000000", "principalIdentifier": "000000000000/ABCDEFGHIJKLMNOPQRSTU:some-user/ABCDEFGHIJKLMNOPQRSTU:some-user"}

下面是一系列 JSON 元素，发布到 $aws/events/presence/connected/clientId 主题的连接/断开连接消息中包含这些元素。

clientId

建立连接或断开连接的客户端的 ID。

Note

包含 # 或 + 的客户端 ID 不接收生命周期事件。eventType

事件类型。有效值为 connected 或 disconnected。principalIdentifier

用于执行身份验证的凭证。对于 TLS 双向身份验证证书，这是证书 ID。对于其他连接，这是 IAM 凭证。

sessionIdentifier

AWS IoT 中的全局唯一标识符，在会话持续时间内存在。timestamp

大致的事件发生时间，使用自 Unix 纪元时间以来的毫秒数表示。时间戳的准确度是 +/- 2 分钟。

订阅/取消订阅事件当客户端订阅或取消订阅 MQTT 主题时，AWS IoT 将向以下 MQTT 主题发布消息：

$aws/events/subscriptions/subscribed/clientId

或者

155

AWS IoT 开发人员指南订阅/取消订阅事件

$aws/events/subscriptions/unsubscribed/clientId

其中 clientId 是连接到 AWS IoT 消息代理的 MQTT 客户端 ID。


{ "clientId": "186b5", "timestamp": 1460065214626, "eventType": "subscribed" | "unsubscribed", "sessionIdentifier": "00000000-0000-0000-0000-000000000000", "principalIdentifier": "000000000000/ABCDEFGHIJKLMNOPQRSTU:some-user/ABCDEFGHIJKLMNOPQRSTU:some-user" "topics" : ["foo/bar","device/data","dog/cat"]}

下面是一系列 JSON 元素，发布到 $aws/events/subscriptions/subscribed/clientId 和 $aws/events/subscriptions/unsubscribed/clientId 主题的已订阅/未订阅消息中包含这些元素。

clientId

订阅或取消订阅的客户端的 ID。

Note

包含 # 或 + 的客户端 ID 不接收生命周期事件。eventType

事件类型。有效值为 subscribed 或 unsubscribed。principalIdentifier

用于执行身份验证的凭证。对于 TLS 双向身份验证证书，这是证书 ID。对于其他连接，这是 IAM 凭证。

sessionIdentifier

AWS IoT 中的全局唯一标识符，在会话持续时间内存在。timestamp

大致的事件发生时间，使用自 Unix 纪元时间以来的毫秒数表示。时间戳的准确度是 +/- 2 分钟。主题

客户端已订阅的一系列 MQTT 主题。

Note

生命周期消息可能不会按顺序发送。您可能会收到重复的消息。

156

AWS IoT 开发人员指南授予 AWS IoT 所需的访问权限

AWS IoT 规则规则使您的设备能够与 AWS 服务交互。基于 MQTT 主题流分析规则并执行操作。您可以使用规则来支持如下任务：

• 补充或筛选从设备接收的数据。• 将从设备接收的数据写入 Amazon DynamoDB 数据库。• 将文件保存到 Amazon S3。• 使用 Amazon SNS 向所有用户发送推送通知。• 将数据发布到 Amazon SQS 队列。• 调用 Lambda 函数来提取数据。• 使用 Amazon Kinesis 处理来自大量设备的消息。• 将数据发送到 Amazon Elasticsearch Service。• 捕获 CloudWatch 指标。• 更改 CloudWatch 警报。• 将 MQTT 消息中的数据发送到 Amazon Machine Learning，以根据 Amazon ML 模型进行预测。• 向 Salesforce IoT 输入流发送消息。

您必须先授予 AWS IoT 代表您访问 AWS 资源的权限，然后才能够执行这些操作。执行这些操作时，即产生了您所使用的 AWS 服务的标准费用。

内容• 授予 AWS IoT 所需的访问权限 (p. 157)• 传递角色权限 (p. 159)• 创建 AWS IoT 规则 (p. 159)• 查看您的规则 (p. 162)• SQL 版本 (p. 163)• 排查规则问题 (p. 164)• 规则错误处理 (p. 164)• 删除规则 (p. 166)• AWS IoT 规则操作 (p. 166)• AWS IoT SQL 参考 (p. 177)

授予 AWS IoT 所需的访问权限您可以使用 IAM 角色来控制每个规则可以访问的 AWS 资源。在创建规则之前，您必须创建一个 IAM 角色，并对其应用允许访问所需 AWS 资源的策略。执行规则时，AWS IoT 将担任此角色。

创建 IAM 角色 (AWS CLI)

1. 将以下信任策略文档（用于授予 AWS IoT 担任此角色的权限）保存到名为 iot-role-trust.json 的文件：

157

AWS IoT 开发人员指南授予 AWS IoT 所需的访问权限

{ "Version":"2012-10-17", "Statement":[{ "Effect": "Allow", "Principal": { "Service": "iot.amazonaws.com" }, "Action": "sts:AssumeRole" }]}

使用 create-role 命令创建 IAM 角色，并指定 iot-role-trust.json 文件：

aws iam create-role --role-name my-iot-role --assume-role-policy-document file://iot-role-trust.json

此命令的输出如下所示：

{ "Role": { "AssumeRolePolicyDocument": "url-encoded-json", "RoleId": "AKIAIOSFODNN7EXAMPLE", "CreateDate": "2015-09-30T18:43:32.821Z", "RoleName": "my-iot-role", "Path": "/", "Arn": "arn:aws:iam::123456789012:role/my-iot-role" }}

2. 将以下 JSON 保存到名为 iot-policy.json 的文件中。

{ "Version": "2012-10-17", "Statement": [{ "Effect": "Allow", "Action": "dynamodb:*", "Resource": "*" }]}

该 JSON 是授予 AWS IoT 管理员对 DynamoDB 的访问权限的示例策略文档。

使用 create-policy 命令授予 AWS IoT 在担任该角色后访问您的 AWS 资源的权限，并传入 iot-policy.json 文件：

aws iam create-policy --policy-name my-iot-policy --policy-document file://my-iot-policy-document.json

有关如何在 AWS IoT 策略中授予对 AWS 服务的访问权限的更多信息，请参阅创建 AWS IoT 规则 (p. 159)。

create-policy 命令的输出中包含该策略的 ARN。您需要将该策略附加到角色。

{ "Policy": { "PolicyName": "my-iot-policy", "CreateDate": "2015-09-30T19:31:18.620Z", "AttachmentCount": 0,

158

http://docs.aws.amazon.com/cli/latest/reference/iam/create-role.html

http://docs.aws.amazon.com/cli/latest/reference/iam/create-policy.html

http://docs.aws.amazon.com/cli/latest/reference/iam/create-policy.html

AWS IoT 开发人员指南传递角色权限

"IsAttachable": true, "PolicyId": "ZXR6A36LTYANPAI7NJ5UV", "DefaultVersionId": "v1", "Path": "/", "Arn": "arn:aws:iam::123456789012:policy/my-iot-policy", "UpdateDate": "2015-09-30T19:31:18.620Z" }}

3. 使用 attach-role-policy 命令将您的策略附加到角色：

aws iam attach-role-policy --role-name my-iot-role --policy-arn "arn:aws:iam::123456789012:policy/my-iot-policy"

传递角色权限规则定义的一部分是 IAM 角色，该角色授予针对规则操作中指定的资源的访问权限。一旦触发规则操作，规则引擎会代入该角色。必须在与规则相同的 AWS 账户中定义该角色。

在创建或替换规则时，您实际上将角色提交到规则引擎中。执行这项操作的用户需要具有 iam:PassRole权限。为确保拥有此权限，您需要创建一个策略以授予 iam:PassRole 权限，并将其附加到您的 IAM 用户。以下策略介绍了如何向角色提供 iam:PassRole 权限。

{ "Version": "2012-10-17", "Statement": [ { "Sid": "Stmt1", "Effect": "Allow", "Action": [ "iam:PassRole" ], "Resource": [ "arn:aws:iam::123456789012:role/myRole" ] } ]}

在此策略示例中，将 iam:PassRole 权限授予了角色 myRole。该角色使用角色的 ARN 指定。您必须将此策略附加到您的 IAM 用户或用户所属的角色。有关更多信息，请参阅使用管理的策略。

Note

Lambda 函数使用基于资源的策略，该策略直接附加至 Lambda 函数本身。创建调用 Lambda 函数的规则时，您未传递角色，因此创建规则的用户无需 iam:PassRole 权限。有关 Lambda 函数授权的更多信息，请参阅使用资源策略授予权限。

创建 AWS IoT 规则您可以配置规则以从连接的设备路由数据。规则包括以下部分：

规则名称

规则的名称。

159

http://docs.aws.amazon.com/cli/latest/reference/iam/attach-role-policy.html

http://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_managed-using.html

http://docs.aws.amazon.com/lambda/latest/dg/intro-permission-model.html#intro-permission-model-access-policy

AWS IoT 开发人员指南创建 AWS IoT 规则

可选说明

规则的文字说明。SQL 语句

一种简化的 SQL 语法，用于筛选接收的 MQTT 主题相关消息并向其他位置推送数据。有关更多信息，请参阅 AWS IoT SQL 参考 (p. 177)。

SQL 版本

评估规则时使用的 SQL 规则引擎的版本。尽管该属性是可选的，但我们强烈建议您指定 SQL 版本。如果未设置该属性，将使用默认值 2015-10-08。

一个或多个操作

执行规则时 AWS IoT 执行的操作。例如，您可以将数据插入 DynamoDB 表、将数据写入 Amazon S3存储桶、发布至 Amazon SNS 主题或调用 Lambda 函数。

错误操作

AWS IoT 在无法执行规则的操作时执行的操作。

当您创建规则时，请注意发布到主题的数据量。如果您创建的规则包含通配符主题模式，它们可能与您的大部分消息匹配，并且您可能需要增加目标操作使用的 AWS 资源容量。另外，如果您创建包含通配符主题模式的重新发布规则，最终可能获得一个造成无限循环的循环规则。

Note

创建和更新规则是管理员级操作。有权创建或更新规则的所有用户都能够访问规则处理的数据。

创建规则 (AWS CLI)

使用 create-topic-rule 命令创建规则：

aws iot create-topic-rule --rule-name my-rule --topic-rule-payload file://my-rule.json

下面是一个负载文件示例，其中包含将发送至 iot/test 主题的所有消息插入指定 DynamoDB 表的规则。SQL 语句筛选消息，角色 ARN 授予写入 DynamoDB 表的 AWS IoT 权限。

{ "sql": "SELECT * FROM 'iot/test'", "ruleDisabled": false, "awsIotSqlVersion": "2016-03-23", "actions": [{ "dynamoDB": { "tableName": "my-dynamodb-table", "roleArn": "arn:aws:iam::123456789012:role/my-iot-role", "hashKeyField": "topic", "hashKeyValue": "${topic(2)}", "rangeKeyField": "timestamp", "rangeKeyValue": "${timestamp()}" } }]}

下面是一个负载文件示例，其中包含将发送至 iot/test 主题的所有消息插入指定 S3 存储桶的规则。SQL语句筛选消息，角色 ARN 授予写入 Amazon S3 存储桶的 AWS IoT 权限。

{ "awsIotSqlVersion": "2016-03-23", "sql": "SELECT * FROM 'iot/test'", "ruleDisabled": false,

160

http://docs.aws.amazon.com/cli/latest/reference/iot/create-topic-rule.html

AWS IoT 开发人员指南创建 AWS IoT 规则

"actions": [ { "s3": { "roleArn": "arn:aws:iam::123456789012:role/aws_iot_s3", "bucketName": "my-bucket", "key": "myS3Key" } } ]}

下面的负载文件示例包含将数据推送至 Amazon ES 的规则：

{ "sql":"SELECT *, timestamp() as timestamp FROM 'iot/test'", "ruleDisabled":false, "awsIotSqlVersion": "2016-03-23", "actions":[ { "elasticsearch":{ "roleArn":"arn:aws:iam::123456789012:role/aws_iot_es", "endpoint":"https://my-endpoint", "index":"my-index", "type":"my-type", "id":"${newuuid()}" } } ]}

下面的负载文件示例包含调用 Lambda 函数的规则：

{ "sql": "expression", "ruleDisabled": false, "awsIotSqlVersion": "2016-03-23", "actions": [{ "lambda": { "functionArn": "arn:aws:lambda:us-west-2:123456789012:function:my-lambda-function" } }]}

下面的负载文件示例包含发布至 Amazon SNS 主题的规则：

{ "sql": "expression", "ruleDisabled": false, "awsIotSqlVersion": "2016-03-23", "actions": [{ "sns": { "targetArn": "arn:aws:sns:us-west-2:123456789012:my-sns-topic", "roleArn": "arn:aws:iam::123456789012:role/my-iot-role" } }]}

下面的负载文件示例包含在不同 MQTT 主题上重新发布的规则：

{

161

AWS IoT 开发人员指南查看您的规则

"sql": "expression", "ruleDisabled": false, "awsIotSqlVersion": "2016-03-23", "actions": [{ "republish": { "topic": "my-mqtt-topic", "roleArn": "arn:aws:iam::123456789012:role/my-iot-role" } }]}

下面的负载文件示例包含将数据推送至 Amazon Kinesis Data Firehose 流的规则：

{ "sql": "SELECT * FROM 'my-topic'", "ruleDisabled": false, "awsIotSqlVersion": "2016-03-23", "actions": [{ "firehose": { "roleArn": ""arn:aws:iam::123456789012:role/my-iot-role", "deliveryStreamName": "my-stream-name" } }]}

在下面的负载文件示例中，具有采用 Amazon Machine Learning machinelearning_predict 函数重新发布至某个主题 (如果 MQTT 负载中的数据分类为 1) 的规则。

{ "sql": "SELECT * FROM 'iot/test' where machinelearning_predict('my-model', 'arn:aws:iam::123456789012:role/my-iot-aml-role', *).predictedLabel=1", "ruleDisabled": false, "awsIotSqlVersion": "2016-03-23", "actions": [{ "republish": { "roleArn": "arn:aws:iam::123456789012:role/my-iot-role", "topic": "my-mqtt-topic" } }]}

下面是一个示例负载文件，该文件包含将消息发布到 Salesforce IoT Cloud 输入流的规则。

{ "sql": "expression", "ruleDisabled": false, "awsIotSqlVersion": "2016-03-23", "actions": [{ "salesforce": { "token": "ABCDEFGHI123456789abcdefghi123456789", "url": "https://ingestion-cluster-id.my-env.sfdcnow.com/streams/stream-id/connection-id/my-event" } }]}

查看您的规则使用 list-topic-rules 命令列出您的规则：

162

http://docs.aws.amazon.com/cli/latest/reference/iot/list-topic-rules.html

AWS IoT 开发人员指南SQL 版本

aws iot list-topic-rules

使用 get-topic-rule 命令获取有关规则的信息：

aws iot get-topic-rule --rule-name my-rule

SQL 版本AWS IoT 规则引擎使用一种类似 SQL 的语法从 MQTT 消息选择数据。SQL 语句基于 SQL 版本进行解释，该版本由描述此规则的 JSON 文档中的 awsIotSqlVersion 属性指定。有关 JSON 规则文档结构的更多信息，请参阅创建规则 (p. 159)。借助 awsIotSqlVersion 属性，您可以指定想要使用的 AWS IoT SQL 规则引擎版本。当部署新版本时，您可继续使用较旧的版本或更改规则以使用新版本。您当前的规则将继续使用创建时所用的版本。

以下 JSON 示例介绍了如何使用 awsIotSqlVersion 属性指定 SQL 版本：

{ "sql": "expression", "ruleDisabled": false, "awsIotSqlVersion": "2016-03-23", "actions": [{ "republish": { "topic": "my-mqtt-topic", "roleArn": "arn:aws:iam::123456789012:role/my-iot-role" } }]}

当前支持的版本包括：

• 2015-10-08，2015 年 10 月 8 日构建的 SQL 原始版本。• 2016-03-23，2016 年 3 月 23 日构建的 SQL 版本。• beta，最新的 SQL 测试版本。使用此版本可能会给您的规则带来破坏性更改。

2016-03-23 SQL 规则引擎版本中的新增功能• 针对选择嵌套 JSON 对象的修复程序。• 针对阵列查询的修复程序。• 对象间查询支持。• 支持将阵列作为顶级对象输出。• 添加 encode(value, encodingScheme) 函数，该函数可应用于 JSON 和非 JSON 格式数据。

对象间查询此功能允许您查询 JSON 对象中的属性。例如，给定了以下 MQTT 消息：

{ "e": [ { "n": "temperature", "u": "Cel", "t": 1234, "v":22.5 }, { "n": "light", "u": "lm", "t": 1235, "v":135 }, { "n": "acidity", "u": "pH", "t": 1235, "v":7 }

163

http://docs.aws.amazon.com/cli/latest/reference/iot/get-topic-rule.html

AWS IoT 开发人员指南排查规则问题

]}

以及以下规则：

SELECT (SELECT v FROM e WHERE n = 'temperature') as temperature FROM 'my/topic'

该规则生成以下输出：

{"temperature": [{"v":22.5}]}

使用相同的 MQTT 消息，并给定一个略复杂的规则，如：

SELECT get((SELECT v FROM e WHERE n = 'temperature'),1).v as temperature FROM 'topic'


{"temperature":22.5}

将 Array 作为顶级对象输出此功能允许规则将阵列作为顶级对象返回。例如，给定了以下 MQTT 消息：

{ "a": {"b":"c"}, "arr":[1,2,3,4]}

以及以下规则：

SELECT VALUE arr FROM 'topic'


[1,2,3,4]

对函数进行编码根据指定的编码方案，将负载（可能是非 JSON 数据）编码为字符串表示形式。

排查规则问题如果您遇到规则问题，应启用 CloudWatch Logs。通过分析您的日志，您可以确定问题是否与授权相关，或者是否为诸如 WHERE 子句状态不匹配的问题。有关使用 Amazon CloudWatch Logs 的更多信息，请参阅设置 CloudWatchLogs。

规则错误处理当 AWS IoT 从设备接收消息时，规则引擎会检查该消息是否匹配规则。如果匹配，将评估规则的 SQL 语句，然后调用规则的操作并向操作传递 SQL 语句的结果。

164

http://docs.aws.amazon.com/iot/latest/developerguide/cloud-watch-logs.html

AWS IoT 开发人员指南错误操作消息格式

如果在调用操作时出现问题，则在为规则指定了错误操作的情况下，规则引擎将调用错误操作。例如，在以下情况下可能会发生此操作：

• 规则没有权限访问 Amazon S3 存储桶。• 用户错误导致超过了 DynamoDB 预配置吞吐量。

错误操作消息格式对于每个规则和每条消息，会生成一条消息。例如，如果同一个规则中的两个规则操作失败，则错误操作将收到包含这些错误的一条消息。

错误操作消息如下所示：

{ "ruleName": "TestAction", "topic": "testme/action", "cloudwatchTraceId": "7e146a2c-95b5-6caf-98b9-50e3969734c7", "clientId": "iotconsole-1511213971966-0", "base64OriginalPayload": "ewogICJtZXNzYWdlIjogIkhlbGxvIHZyb20gQVdTIElvVCBjb25zb2xlIgp9", "failures": [ { "failedAction": "S3Action", "failedResource": "us-east-1-s3-verify-user", "errorMessage": "Failed to put S3 object. The error received was The specified bucket does not exist (Service: Amazon S3; Status Code: 404; Error Code: NoSuchBucket; Request ID: 9DF5416B9B47B9AF; S3 Extended Request ID: yMah1cwPhqTH267QLPhTKeVPKJB8BO5ndBHzOmWtxLTM6uAvwYYuqieAKyb6qRPTxP1tHXCoR4Y=). Message arrived on: error/action, Action: s3, Bucket: us-east-1-s3-verify-user, Key: \"aaa\". Value of x-amz-id-2: yMah1cwPhqTH267QLPhTKeVPKJB8BO5ndBHzOmWtxLTM6uAvwYYuqieAKyb6qRPTxP1tHXCoR4Y=" } ] }

ruleName

触发错误操作的规则的名称。topic

收到原始消息的主题。cloudwatchTraceId

引用 CloudWatch 中错误日志的唯一身份。clientId

消息发布程序的客户端 ID。base64OriginalPayload

base64 编码的原始消息负载。失败

failedAction

无法完成的操作的名称，例如“S3Action”。failedResource

资源的名称，例如 S3 存储桶的名称。

165

AWS IoT 开发人员指南错误操作示例

errorMessage

错误的描述和说明。

错误操作示例下面是一个具有添加的错误操作的规则示例。以下规则具有将消息数据写入到 DynamoDB 表的操作，以及将数据写入到 Amazon S3 存储桶的错误操作：

{ "sql" : "SELECT * FROM ..." "actions" : [{ "dynamoDB" : { "table" : "PoorlyConfiguredTable", "hashKeyField" : "AConstantString", "hashKeyValue" : "AHashKey"}} ], "errorAction" : { "s3" : { "roleArn": "arn:aws:iam::123456789012:role/aws_iot_s3", "bucket" : "message-processing-errors", "key" : "${replace(topic(), '/', '-') + '-' + timestamp() + '-' + newuuid()}" }}}

您可以在错误操作的 SQL 语句中使用任意函数或替换，但外部函数除外 (例如，get_thing_shadow、aws_lambda 和 machinelearning_predict)。

有关规则以及如何指定错误操作的更多信息，请参阅创建 AWS IoT 规则。

有关使用 CloudWatch 监控规则成功还是失败的更多信息，请参阅AWS IoT 指标和维度 (p. 344)。

删除规则用完规则后可以将其删除。

删除规则 (AWS CLI)

使用 delete-topic-rule 命令删除规则：

aws iot delete-topic-rule --rule-name my-rule

AWS IoT 规则操作AWS IoT 规则操作用于指定规则触发后应执行的操作。您可以定义操作以将数据写入 DynamoDB 数据库或Kinesis 流，或者调用 Lambda 函数等。支持以下操作：

• cloudwatchAlarm - 更改 CloudWatch 警报。• cloudwatchMetric - 捕获 CloudWatch 指标。• dynamoDB - 将数据写入 DynamoDB 数据库。• dynamoDBv2 - 将数据写入 DynamoDB 数据库。• elasticsearch - 将数据写入 Amazon Elasticsearch Service 域。• firehose - 将数据写入 Amazon Kinesis Data Firehose 流。

166

http://docs.aws.amazon.com/iot/latest/developerguide/iot-create-rule.html

http://docs.aws.amazon.com/cli/latest/reference/iot/delete-topic-rule.html

AWS IoT 开发人员指南CloudWatch 警报操作

• kinesis - 将数据写入 Kinesis 流。• lambda - 调用 Lambda 函数。• s3 - 将数据写入 Amazon S3 存储桶。• sns - 将数据编写为推送通知。• sqs - 将数据写入 SQS 队列。• republish - 在另一个 MQTT 主题上重新发布消息。• salesforce - 将消息写入 Salesforce IoT 输入流。

Note

AWS IoT 规则引擎当前不会重新尝试传输在发布至另一个服务时失败的消息。

以下部分将详细讨论每项操作。

CloudWatch 警报操作CloudWatch 警报操作允许您更改 CloudWatch 警报状态。您可以在此调用中指定状态更改原因和状态值。使用 CloudWatch 警报操作创建 AWS IoT 规则时，您必须指定以下信息：

roleArn

允许访问 CloudWatch 警报的 IAM 角色。alarmName

CloudWatch 警报名称。stateReason

警报更改的原因。stateValue

警报状态的值。可接受的值包括 OK、ALARM、INSUFFICIENT_DATA。

Note

确保与规则关联的角色拥有授予 cloudwatch:SetAlarmState 权限的策略。

下面的 JSON 示例介绍了如何在 AWS IoT 规则中定义 CloudWatch 警报操作：

{ "rule": { "sql": "SELECT * FROM 'some/topic'", "ruleDisabled": false, "actions": [{ "cloudwatchAlarm": { "roleArn": "arn:aws:iam::123456789012:role/aws_iot_cw", "alarmName": "IotAlarm", "stateReason": "Temperature stabilized.", "stateValue": "OK" } }] }}

有关更多信息，请参阅 CloudWatch 警报。

167

http://docs.aws.amazon.com/AmazonCloudWatch/latest/DeveloperGuide/AlarmThatSendsEmail.html

AWS IoT 开发人员指南CloudWatch 指标操作

CloudWatch 指标操作CloudWatch 指标操作允许您捕获 CloudWatch 指标。您可以指定指标命名空间、名称、值、单位和时间戳。使用 CloudWatch 指标操作创建 AWS IoT 规则时，您必须指定以下信息：

roleArn

允许访问 CloudWatch 指标的 IAM 角色。metricNamespace

CloudWatch 指标命名空间名称。metricName

CloudWatch 指标名称。metricValue

CloudWatch 指标值。metricUnit

CloudWatch 支持的指标单位。metricTimestamp

可选 Unix 时间戳。

Note

确保与规则关联的角色拥有授予 cloudwatch:PutMetricData 权限的策略。

下面的 JSON 示例介绍了如何在 AWS IoT 规则中定义 CloudWatch 指标操作：

{ "rule": { "sql": "SELECT * FROM 'some/topic'", "ruleDisabled": false, "actions": [{ "cloudwatchMetric": { "roleArn": "arn:aws:iam::123456789012:role/aws_iot_cw", "metricNamespace": "IotNamespace", "metricName": "IotMetric", "metricValue": "1", "metricUnit": "Count", "metricTimestamp": "1456821314" } }] }}

有关更多信息，请参阅 CloudWatch 指标。

DynamoDB 操作dynamoDB 操作允许您将所有或部分 MQTT 消息写入 DynamoDB 表。创建 DynamoDB 规则时，您必须指定以下信息：

hashKeyType

哈希键（也称为分区键）的数据类型。有效值为："STRING" 或 "NUMBER"。

168

http://docs.aws.amazon.com/AmazonCloudWatch/latest/DeveloperGuide/CW_Support_For_AWS.html

AWS IoT 开发人员指南DynamoDB 操作

hashKeyField

哈希键（也称为分区键）的名称。hashKeyValue

哈希键的值。rangeKeyType

可选。范围键（也称为排序键）的数据类型。有效值为："STRING" 或 "NUMBER"。rangeKeyField

可选。范围键（也称为排序键）的名称。rangeKeyValue

可选。范围键的值。operation

可选。要执行的操作类型。该信息遵循替换模板，因此可以是 ${operation}，但替换必须产生以下操作之一：INSERT、UPDATE 或 DELETE。

payloadField

可选。负载将写入的字段的名称。如果省略此值，负载将写入 payload 字段。table

DynamoDB 表的名称。roleARN

允许访问 DynamoDB 表的 IAM 角色。该角色至少须允许 dynamoDB:PutItem IAM 操作。

写入 DynamoDB 表的数据是规则的 SQL 语句的结果。hashKeyValue 和 rangeKeyValue 字段通常由表达式 (例如，“${topic()}”或“${timestamp()}”) 组成。

Note

非 JSON 数据以二进制数据形式写入 DynamoDB。DynamoDB 控制台以 Base64 编码文本格式显示数据。确保与规则关联的角色拥有授予 dynamodb:PutItem 权限的策略。

下面的 JSON 示例介绍了如何在 AWS IoT 规则中定义 dynamoDB 操作：

{ "rule": { "ruleDisabled": false, "sql": "SELECT * AS message FROM 'some/topic'", "description": "A test Dynamo DB rule", "actions": [{ "dynamoDB": { "hashKeyField": "key", "roleArn": "arn:aws:iam::123456789012:role/aws_iot_dynamoDB", "tableName": "my_ddb_table", "hashKeyValue": "${topic()}", "rangeKeyValue": "${timestamp()}", "rangeKeyField": "timestamp" } }] }}

有关更多信息，请参阅 Amazon DynamoDB 入门指南。

169

http://docs.aws.amazon.com/amazondynamodb/latest/gettingstartedguide/

AWS IoT 开发人员指南DynamoDBv2 操作

DynamoDBv2 操作dynamoDBv2 操作允许您将所有或部分 MQTT 消息写入 DynamoDB 表。负载的每个属性将写入DynamoDB 数据库的单独一列。创建 DynamoDB 规则时，您必须指定以下信息：

roleARN

允许访问 DynamoDB 表的 IAM 角色。该角色至少须允许 dynamoDB:PutItem IAM 操作。tableName

DynamoDB 表的名称。

Note

如果要定义 MQTT 消息负载，则它必须包含一个与表的主分区键相匹配的根级键，以及一个与表的主排序键相匹配的根级键。

写入 DynamoDB 表的数据是规则的 SQL 语句的结果。

Note

确保与规则关联的角色拥有授予 dynamodb:PutItem 权限的策略。

下面的 JSON 示例介绍了如何在 AWS IoT 规则中定义 dynamoDB 操作：

{ "rule": { "ruleDisabled": false, "sql": "SELECT * AS message FROM 'some/topic'", "description": "A test DynamoDBv2 rule", "actions": [{ "dynamoDBv2": { "roleArn": "arn:aws:iam::123456789012:role/aws_iot_dynamoDBv2", "putItem": { "tableName": "my_ddb_table" } } }] }}

有关更多信息，请参阅 Amazon DynamoDB 入门指南。

Amazon ES 操作elasticsearch 操作允许您将 MQTT 消息中的数据写入 Amazon Elasticsearch Service 域。然后，您可以使用 Kibana 等工具来查询和可视化 Amazon ES 中的数据。当您使用 elasticsearch 操作创建 AWS IoT规则时，必须指定以下信息：

endpoint

您的 Amazon ES 域的终端节点。index

您要在其中存储数据的 Amazon ES 索引。type

您存储的文档类型。

170

http://docs.aws.amazon.com/amazondynamodb/latest/gettingstartedguide/

AWS IoT 开发人员指南Firehose 操作

id

每个文档的唯一标识符。

Note

确保与规则关联的角色拥有授予 es:ESHttpPut 权限的策略。

下面的 JSON 示例介绍了如何在 AWS IoT 规则中定义 elasticsearch 操作：

{ "rule":{ "sql":"SELECT *, timestamp() as timestamp FROM 'iot/test'", "ruleDisabled":false, "actions":[ { "elasticsearch":{ "roleArn":"arn:aws:iam::123456789012:role/aws_iot_es", "endpoint":"https://my-endpoint", "index":"my-index", "type":"my-type", "id":"${newuuid()}" } } ] }}

有关更多信息，请参阅 Amazon ES 开发人员指南。

Firehose 操作firehose 操作可将触发规则的 MQTT 消息中的数据发送至 Kinesis Data Firehose 流。使用 firehose 操作创建规则时，您必须指定以下信息：

deliveryStreamName

消息数据写入的 Kinesis Data Firehose 流。roleArn

允许访问 Kinesis Data Firehose 的 IAM 角色。separator

将用于分隔写入 Firehose 流的记录的字符分隔符。有效值为：'\n'（换行符）、'\t'（制表符）、'\r\n'（Windows 换行符）、','（逗号）。

Note

确保与规则关联的角色拥有授予 firehose:PutRecord 权限的策略。

下面的 JSON 示例介绍了如何使用 firehose 操作创建 AWS IoT 规则：

{ "rule": { "sql": "SELECT * FROM 'some/topic'", "ruleDisabled": false, "actions": [{ "firehose": { "roleArn": "arn:aws:iam::123456789012:role/aws_iot_firehose", "deliveryStreamName": "my_firehose_stream"

171

http://docs.aws.amazon.com/elasticsearch-service/latest/developerguide/

AWS IoT 开发人员指南Kinesis 操作

} }] }}

有关更多信息，请参阅 Kinesis Data Firehose 开发人员指南。

Kinesis 操作kinesis 操作允许您将 MQTT 消息中的数据写入 Kinesis 流。使用 kinesis 操作创建 AWS IoT 规则时，您必须指定以下信息：

stream

数据写入的 Kinesis 流。partitionKey

用于确定将数据写入哪个分区的分区键。分区键通常由表达式 (例如，“${topic()}”或“${timestamp()}”) 组成。

Note

确保与规则关联的策略拥有 kinesis:PutRecord 权限。

下面的 JSON 示例介绍了如何在 AWS IoT 规则中定义 kinesis 操作：

{ "rule": { "sql": "SELECT * FROM 'some/topic'", "ruleDisabled": false, "actions": [{ "kinesis": { "roleArn": "arn:aws:iam::123456789012:role/aws_iot_kinesis", "streamName": "my_kinesis_stream", "partitionKey": "${topic()}" } }], }}

有关更多信息，请参阅 Kinesis 开发人员指南。

Lambda 操作lambda 操作会调用 Lambda 函数，并传入触发规则的 MQTT 消息。为了让 AWS IoT 调用 Lambda函数，您必须配置一个策略以向 AWS IoT 授予 lambda:InvokeFunction 权限。Lambda 函数使用基于资源的策略，因此您必须将该策略附加至 Lambda 函数本身。使用以下 CLI 命令附加授予lambda:InvokeFunction 权限的策略：

aws lambda add-permission --function-name "function_name" --region "region" --principal iot.amazonaws.com --source-arn arn:aws:iot:us-east-2:account_id:rule/rule_name --source-account "account_id" --statement-id "unique_id" --action "lambda:InvokeFunction"

add-permission 命令的参数如下：

--function-name

Lambda 函数的名称，您正在通过添加新的权限来更新其资源策略。

172

http://docs.aws.amazon.com/firehose/latest/dev/

http://docs.aws.amazon.com/streams/latest/dev/introduction.html

AWS IoT 开发人员指南Republish 操作

--region

您的账户所处的 AWS 区域。--principal

获取权限的委托人。这应该是 iot.amazonaws.com，以授予 AWS IoT 调用 Lambda 函数的权限。--source-arn

规则的 ARN。您可以使用 get-topic-rule CLI 命令来获取规则的 ARN。--source-account

定义规则的 AWS 账户。--statement-id

唯一的语句标识符。--action

要在此语句中允许的 Lambda 操作。在本示例中，我们要允许 AWS IoT 调用 Lambda 函数，因此我们指定 lambda:InvokeFunction。

Note

如果您在不提供源 ARN 的情况下为 AWS IoT 委托人添加权限，则所有通过 Lambda 操作创建规则的 AWS 账户都可以触发从 AWS IoT 调用 Lambda 函数的规则。

有关更多信息，请参阅 Lambda 权限模型。

在使用 lambda 操作创建规则时，您必须指定在触发规则后调用的 Lambda 函数。

下面的 JSON 示例介绍了调用 Lambda 函数的规则：

{ "rule": { "sql": "SELECT * FROM 'some/topic'", "ruleDisabled": false, "actions": [{ "lambda": { "functionArn": "arn:aws:lambda:us-east-2:123456789012:function:myLambdaFunction" } }] }}

有关更多信息，请参阅 AWS Lambda 开发人员指南。

Republish 操作republish 操作允许您将触发角色的消息重新发布至另一个 MQTT 主题。使用 republish 操作创建规则时，您必须指定以下信息：

topic

消息重新发布到的 MQTT 主题。roleArn

允许发布至 MQTT 主题的 IAM 角色。

173

http://docs.aws.amazon.com/lambda/latest/dg/intro-permission-model.html


AWS IoT 开发人员指南S3 操作

Note

确保与规则关联的角色拥有授予 iot:Publish 权限的策略。

{ "rule": { "sql": "SELECT * FROM 'some/topic'", "ruleDisabled": false, "actions": [{ "republish": { "topic": "another/topic", "roleArn": "arn:aws:iam::123456789012:role/aws_iot_republish" } }] }}

S3 操作s3 操作可将触发规则的 MQTT 消息中的数据写入 Amazon S3 存储桶。使用 s3 操作创建 AWS IoT 规则时，您必须指定以下信息：

bucket

数据写入的 Amazon S3 存储桶。cannedacl

控制对象访问的 Amazon S3 标准 ACL 由对象键标识。有关更多信息，请参阅 S3 标准 ACL。key

数据写入的文件路径。例如，如果此参数的值为“${topic()}/${timestamp()}”，消息发送至的主题为“this/is/my/topic”，当前时间戳为 1460685389，则数据将写入 Amazon S3 上“this/is/my/topic”文件夹中名为“1460685389”的文件。

Note

使用静态键将导致每次调用规则都会覆盖 Amazon S3 中的单个文件。更常见的使用案例是使用消息时间戳或其他唯一的消息标识符，这样可在 Amazon S3 中针对接收的每个消息保存一个新文件。

roleArn

允许访问 Amazon S3 存储桶的 IAM 角色。

Note

确保与规则关联的角色拥有授予 s3:PutObject 权限的策略。

下面的 JSON 示例介绍了如何在 AWS IoT 规则中定义 s3 操作：

{ "rule": { "sql": "SELECT * FROM 'some/topic'", "ruleDisabled": false, "actions": [{ "s3": { "roleArn": "arn:aws:iam::123456789012:role/aws_iot_s3", "bucketName": "my-bucket", "key": "${topic()}/${timestamp()}" }

174

http://docs.aws.amazon.com/AmazonS3/latest/dev/acl-overview.html#canned-acl

AWS IoT 开发人员指南SNS 操作

}] }}

有关更多信息，请参阅 Amazon S3 开发人员指南。

SNS 操作sns 操作可将触发规则的 MQTT 消息中的数据作为 SNS 推送通知发送。使用 sns 操作创建规则时，您必须指定以下信息：

messageFormat

消息格式。接受的值为“JSON”和“RAW”。该属性的默认值为“RAW”。SNS 使用此设置来确定是否应解析负载，以及是否应提取负载的特定于平台的相关部分。

roleArn

允许访问 SNS 的 IAM 角色。targetArn

推送通知将发送到的 SNS 主题或单个设备。

Note

确保与规则关联的策略拥有 sns:Publish 权限。

下面的 JSON 示例介绍了如何在 AWS IoT 规则中定义 sns 操作：

{ "rule": { "sql": "SELECT * FROM 'some/topic'", "ruleDisabled": false, "actions": [{ "sns": { "targetArn": "arn:aws:sns:us-east-2:123456789012:my_sns_topic", "roleArn": "arn:aws:iam::123456789012:role/aws_iot_sns" } }] }}

有关更多信息，请参阅 Amazon SNS 开发人员指南。

SQS 操作sqs 操作可将触发规则的 MQTT 消息中的数据发送至 SQS 队列。使用 sqs 操作创建规则时，您必须指定以下信息：

queueUrl

数据写入的 SQS 队列的 URL。useBase64

如果您希望 MQTT 消息数据在写入 SQS 队列前进行 Base64 编码，则设置为 true。否则，设置为false。

roleArn

允许访问 SQS 队列的 IAM 角色。

175

http://docs.aws.amazon.com/AmazonS3/latest/dev/

http://docs.aws.amazon.com/sns/latest/dg/

AWS IoT 开发人员指南Salesforce 操作

Note

确保与规则关联的角色拥有授予 sqs:SendMessage 权限的策略。

下面的 JSON 示例介绍了如何使用 sqs 操作创建 AWS IoT 规则：

{ "rule": { "sql": "SELECT * FROM 'some/topic'", "ruleDisabled": false, "actions": [{ "sqs": { "queueUrl": "https://sqs.us-east-2.amazonaws.com/123456789012/my_sqs_queue", "roleArn": "arn:aws:iam::123456789012:role/aws_iot_sqs", "useBase64": false } }] }}

有关更多信息，请参阅 Amazon SQS 开发人员指南。

Salesforce 操作salesforce 操作将来自触发了规则的 MQTT 消息的数据发送到 Salesforce IoT 输入流。使用salesforce 操作创建规则时，您必须指定以下信息：

url

由 Salesforce IoT 输入流公开的 URL。在创建输入流时，可从 Salesforce IoT 平台获得该 URL。请参阅Salesforce IoT 文档以了解更多信息。

token

用于验证对指定的 Salesforce IoT 输入流的访问的令牌。在创建输入流时，可从 Salesforce IoT 平台获得该令牌。请参阅 Salesforce IoT 文档以了解更多信息。

Note

这些参数不支持替换。

下面的 JSON 示例介绍了如何使用 salesforce 操作创建 AWS IoT 规则：

{ "sql": "expression", "ruleDisabled": false, "awsIotSqlVersion": "2016-03-23", "actions": [{ "salesforce": { "token": "ABCDEFGHI123456789abcdefghi123456789", "url": "https://ingestion-cluster-id.my-env.sfdcnow.com/streams/stream-id/connection-id/my-event" } }]}

有关更多信息，请参阅 Salesforce IoT 文档。

176

http://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/

AWS IoT 开发人员指南AWS IoT SQL 参考

AWS IoT SQL 参考在 AWS IoT 中，规则通过一种类似 SQL 的语法来定义。SQL 语句由三类子句组成：

SELECT

必需。从传入负载提取信息并执行转换。FROM

必需。规则接收消息的 MQTT 主题筛选条件。WHERE

可选。添加用于确定是否评估规则以及是否执行其操作的条件逻辑。

SQL 语句的示例如下所示：

SELECT color AS rgb FROM 'a/b' WHERE temperature > 50

MQTT 消息 (也称为传入负载) 的示例如下所示：

{ "color":"red", "temperature":100}

如果此消息在 'a/b' 主题上发布，则触发规则并评估 SQL 语句。如果 "temperature" 属性大于50，SQL 语句将提取 color 属性的值。WHERE 子句指定条件 temperature > 50。AS 关键字将"color" 属性重命名为 "rgb"。结果 (也称为传出负载) 如下所示：

{ "rgb":"red"}

此数据随后将转发至规则的操作，在其中发送数据供后续处理。有关规则操作的更多信息，请参阅 AWS IoT规则操作 (p. 166)。

数据类型AWS IoT 规则引擎支持所有 JSON 数据类型。

受支持数据类型

Type 意义

Int 离散的 Int。最大 34 位。

Decimal 精度为 34 位的 Decimal，最小非零数量级为1E-999，最大数量级为 9.999…E999。

Note

部分功能返回双精度 Decimal，而不是 34位数字精度。

Boolean True 或者 False。

177

AWS IoT 开发人员指南数据类型

Type 意义

String UTF-8 字符串。

Array 不必为相同类型的一系列值。

Object 包含一个键和一个值的 JSON 值。键必须是字符串。值可以是任意类型。

Null Null 由 JSON 定义。它是表示缺少某个值的实际值。您必须通过使用 SQL 语句中 Null 关键字明确创建一个 Null 值。例如："SELECT NULL AS nFROM 'a/b'"

Undefined 非值。在 JSON 中无法明确表示，只能忽略该值。例如，在对象 {"foo": null} 中，键“foo”返回NULL，但键“bar”返回 Undefined。在内部，SQL语言将 Undefined 作为值处理，但它在 JSON 中无法表示，因此，在序列化为 JSON 时，结果为Undefined。

{"foo":null, "bar":undefined}

序列化为 JSON 如下：

{"foo":null}

同样，Undefined 在被自身序列化时会转化为空字符串。使用无效参数 (例如，错误的类型、错误的参数号等) 调用的函数将返回 Undefined。

转换下表列出当一个类型的值转换为另一个类型时 (为函数提供错误类型的值时) 返回的结果。例如，如果绝对值函数“abs”(期待的值类型为 Int 或 Decimal) 被赋予 String 时，它会尝试遵循以下规则将 String 转换为Decimal。在这种情况下，“abs("-5.123")”将被视为“abs(-5.123)”。

Note

不会尝试转换 Array、Object、Null 或 Undefined。

To Decimal

参数类型结果

Int 没有小数点的 Decimal。

Decimal 源值。

Boolean Undefined。(您可以明确使用强制转换函数使 trun= 1.0，false = 0.0。)

String SQL 引擎尝试将字符串解析为 Decimal。AWSIoT 尝试解析与正则表达式相匹配的字符串：^-?\d+(\.\d+)?((?i)E-?\d+)?$。可自动转换为Decimal 的字符串示例包括 "0"、"-1.2"、"5E-12"。

178

AWS IoT 开发人员指南数据类型

参数类型结果

数组 Undefined。

Object Undefined。

Null Null。

未定义 Undefined。

To Int

参数类型结果

Int 源值。

Decimal 源值都舍入到最接近的 Int。

Boolean Undefined。(您可以明确使用强制转换函数使 trun= 1.0，false = 0.0。)

String SQL 引擎会尝试将字符串解析为 Decimal。我们会尝试解析与正则表达式相匹配的字符串：^-?\d+(\.\d+)?((?i)E-?\d+)?$。可自动转换为 Decimal 的字符串示例包括"0"、"-1.2"、"5E-12" 。我们会尝试将 String 转换为 Decimal，然后截断该 Decimal 的小数位，得到一个 Int。

数组 Undefined。

Object Undefined。

Null Null。

未定义 Undefined.

To Boolean

参数类型结果

Int Undefined。(您可以明确使用 cast 函数使 0 =False，任何非零值 = True。)

Decimal Undefined。(您可以明确使用强制转换函数使 0 =False，任何非零值 = True。)

Boolean 原始值。

String "true"=True 和 "false"=False (不区分大小写)。其他字符串值将为 Undefined。

数组 Undefined。

Object Undefined。

Null Undefined。


179

AWS IoT 开发人员指南运算符

To String

参数类型结果

Int 标准表示法中 Int 的字符串表示。

Decimal 科学表示法中 Decimal 值的字符串表示。

Boolean "true" 或 "false"。均为小写。

String 原始值。

数组 Array 序列化为 JSON。结果字符串为逗号分隔的列表，括在方括号中。String 将用引号括起来。Decimal、Int、Boolean 和 Null 不必如此。

Object 序列化为 JSON 的对象。结果字符串为键值对的逗号分隔列表，以大括号开始并结束。String 将用引号括起来。Decimal、Int、Boolean 和 Null 不必如此。

Null Undefined。

未定义未定义。

运算符SELECT、FROM 和 WHERE 子句中可以使用以下运算符。

AND 运算符返回 Boolean 结果。执行逻辑与运算。如果左右操作数为 true，则返回 true。否则返回 false。需要Boolean 操作数或不区分大小写的 "true" 或 "false" 字符串操作数。

语法: expression AND expression.

AND 运算符

左侧操作数右侧操作数输出

Boolean Boolean Boolean。如果两个操作数均为 true，则为 true。否则为false。

String/Boolean String/Boolean 如果所有字符串均为 "true" 或 "false" (不区分大小写)，则它们将被转换为 Boolean 并作为 boolean AND boolean 正常处理。

其他值其他值 Undefined。

OR 运算符返回 Boolean 结果。执行逻辑或运算。如果左右操作数至少有一个为 true，则返回 true。否则返回 false。需要 Boolean 操作数或不区分大小写的 "true" 或 "false" 字符串操作数。

语法: expression OR expression.

180


OR 运算符


Boolean Boolean Boolean。如果任意一个操作数为 true，则为 true。否则为false。

String/Boolean String/Boolean 如果所有字符串均为 "true" 或 "false" (不区分大小写)，则它们将被转换为 Boolean 并作为 boolean OR boolean 正常处理。


NOT 运算符返回 Boolean 结果。执行逻辑非运算。如果操作数为 false，则返回 true。否则返回 true。需要布尔操作数或不区分大小写的 "true" 或 "false" 字符串操作数。

语法: NOT expression.

NOT 运算符

操作数输出

Boolean Boolean。如果操作数为 false，则为 true。否则为false。

String 如果字符串为 "true" 或 "false" (不区分大小写)，它将被转换为对应的布尔值，并返回相反的值。

其他值 Undefined。

> operator返回 Boolean 结果。如果左侧操作数大于右侧操作数，则返回 true。两个操作数将转换为 Decimal，然后进行比较。

语法: expression > expression.

> 运算符


Int/Decimal Int/Decimal Boolean。如果左侧操作数大于右侧操作数，则为 true。否则为 false。

String/Int/Decimal

String/Int/Decimal

如果所有字符串可以转换为 Decimal，则 Boolean。如果左侧操作数大于右侧操作数，则返回 true。否则为 false。

其他值 Undefined。 Undefined。

>= operator返回 Boolean 结果。如果左侧操作数大于等于右侧操作数，则返回 true。两个操作数将转换为 Decimal，然后进行比较。

181


语法: expression >= expression.

>= 运算符


Int/Decimal Int/Decimal Boolean。如果左侧操作数大于等于右侧操作数，则为 true。否则为 false。

String/Int/Decimal

String/Int/Decimal

如果所有字符串可以转换为 Decimal，则 Boolean。如果左侧操作数大于等于右侧操作数，则返回 true。否则为 false。

其他值 Undefined。 Undefined。

< operator返回 Boolean 结果。如果左侧操作数小于右侧操作数，则返回 true。两个操作数将转换为 Decimal，然后进行比较。

语法: expression < expression.

< 运算符


Int/Decimal Int/Decimal Boolean。如果左侧操作数小于右侧操作数，则为 true。否则为 false。

String/Int/Decimal

String/Int/Decimal

如果所有字符串可以转换为 Decimal，则 Boolean。如果左侧操作数小于右侧操作数，则返回 true。否则为 false。

其他值 Undefined Undefined

<= operator返回 Boolean 结果。如果左侧操作数小于等于右侧操作数，则返回 true。两个操作数将转换为 Decimal，然后进行比较。

语法: expression <= expression.

>= 运算符


Int/Decimal Int/Decimal Boolean。如果左侧操作数小于等于右侧操作数，则为 true。否则为 false。

String/Int/Decimal

String/Int/Decimal

如果所有字符串可以转换为 Decimal，则 Boolean。如果左侧操作数小于等于右侧操作数，则返回 true。否则为 false。

其他值 Undefined Undefined

<> operator返回 Boolean 结果。如果左右操作数不相等，则返回 true。否则返回 false。

182


语法: expression <> expression.

<> 运算符


Int Int 如果左侧操作数不等于右侧操作数，则为 true。否则为 false。

Decimal Decimal 如果左侧操作数不等于右侧操作数，则为 true。否则为 false。在比较之前，Int 会被转换为 Decimal。

String String 如果左侧操作数不等于右侧操作数，则为 true。否则为 false。

数组数组如果各个操作数中的项不相等且顺序不同，则为 true。否则为false

Object Object 如果各个操作数的键和值不相等，则为 true。否则为 false。键/值的顺序不重要。

Null Null False.

任意值 Undefined 未定义。

Undefined 任意值未定义。

不匹配的类型不匹配的类型 True.

= operator返回 Boolean 结果。如果左右操作数相等，则返回 true。否则返回 false。

语法: expression = expression.

= 运算符


Int Int 如果左侧操作数等于右侧操作数，则为 true。否则为 false。

Decimal Decimal 如果左侧操作数等于右侧操作数，则为 true。否则为 false。在比较之前，Int 会被转换为 Decimal。

String String 如果左侧操作数等于右侧操作数，则为 true。否则为 false。

数组数组如果各个操作数中的项相等且顺序相同，则为 true。否则为false。

Object Object 如果各个操作数的键和值相等，则为 true。否则为 false。键/值的顺序不重要。

任意值 Undefined Undefined。

Undefined 任意值 Undefined。

不匹配的类型不匹配的类型 False.

+ operator“+”是一个重载运算符。它可用于字符串联接或相加。

183


语法: expression + expression.

+ 运算符


String 任意值将右侧操作数转换为一个字符串，并联接到左侧操作数的末尾。

任意值 String 将左侧操作数转换为一个字符串，并将右侧操作数联接到转换后的左侧操作数的末尾。

Int Int Int 值. 将操作数相加。

Int/Decimal Int/Decimal Decimal 值. 将操作数相加。


- operator从左侧操作数中减去右侧操作数。

语法: expression - expression.

- 运算符


Int Int Int 值. 从左侧操作数中减去右侧操作数。

Int/Decimal Int/Decimal Decimal 值. 从左侧操作数中减去右侧操作数。

String/Int/Decimal

String/Int/Decimal

如果所有字符串都正确转换为 Decimal，则返回Decimal 值。从左侧操作数中减去右侧操作数。否则返回Undefined。



* operator左侧操作数乘以右侧操作数。

语法: expression * expression.

* 运算符


Int Int Int 值. 左侧操作数乘以右侧操作数。

Int/Decimal Int/Decimal Decimal 值. 左侧操作数乘以右侧操作数。

String/Int/Decimal

String/Int/Decimal

如果所有字符串都正确转换为 Decimal，则返回 Decimal值。左侧操作数乘以右侧操作数。否则返回 Undefined。

184

AWS IoT 开发人员指南函数



/ operator左侧操作数除以右侧操作数。

语法: expression / expression.

/ 运算符


Int Int Int 值. 左侧操作数除以右侧操作数。

Int/Decimal Int/Decimal Decimal 值. 左侧操作数除以右侧操作数。

String/Int/Decimal

String/Int/Decimal

如果所有字符串都正确转换为 Decimal，则返回 Decimal值。左侧操作数除以右侧操作数。否则返回 Undefined。


% operator返回左侧操作数除以右侧操作数得到的余数。

语法: expression % expression.

% 运算符


Int Int Int 值. 返回左侧操作数除以右侧操作数得到的余数。

String/Int/Decimal

String/Int/Decimal

如果所有 String 都正确转换为 Decimal，则返回 Decimal值。返回左侧操作数除以右侧操作数得到的余数。否则为Undefined。


函数您可以使用 SQL 表达式的 SELECT 或 WHERE 子句中的以下内置函数。

abs(Decimal)返回数字的绝对值。SQL 版本 2015-10-8 及更高版本支持。

示例：abs(-5) 返回 5。

参数类型结果

Int Int，参数的绝对值。

185


参数类型结果

Decimal Decimal，参数的绝对值。

Boolean Undefined。

String Decimal。结果是参数的绝对值。如果字符串无法转换，则结果为 Undefined。

数组 Undefined。

Object Undefined。

Null Undefined。


accountid()以 String 形式返回拥有该规则的账户的 ID。SQL 版本 2015-10-8 及更高版本支持。

例如：

accountid() = "123456789012"

acos(Decimal)以弧度形式返回数字的反余弦值。在代入函数之前，Decimal 参数舍入到双精度。SQL 版本 2015-10-8 及更高版本支持。

示例：acos(0) = 1.5707963267948966

参数类型结果

Int Decimal (双精度)，参数的反余弦值。虚数结果返回Undefined。

Decimal Decimal (双精度)，参数的反余弦值。虚数结果返回Undefined。


String Decimal，参数的反余弦值。如果字符串无法转换，则结果为 Undefined。虚数结果返回 Undefined。

数组 Undefined。

Object Undefined。

Null Undefined。


asin(Decimal)以弧度形式返回数字的反正弦值。在代入函数之前，Decimal 参数舍入到双精度。SQL 版本 2015-10-8 及更高版本支持。

186


示例：asin(0) = 0.0

参数类型结果

Int Decimal (双精度)，参数的反正弦值。虚数结果返回Undefined。

Decimal Decimal (双精度)，参数的反正弦值。虚数结果返回Undefined。


String Decimal (双精度)，参数的反正弦值。如果字符串无法转换，则结果为 Undefined。虚数结果返回 Undefined。

数组 Undefined。

Object Undefined。

Null Undefined。


atan(Decimal)以弧度形式返回数字的反正切值。在代入函数之前，Decimal 参数舍入到双精度。SQL 版本 2015-10-8 及更高版本支持。

示例：atan(0) = 0.0

参数类型结果

Int Decimal (双精度)，参数的反正切值。虚数结果返回Undefined。

Decimal Decimal (双精度)，参数的反正切值。虚数结果返回Undefined。


String Decimal，参数的反正切值。如果字符串无法转换，则结果为 Undefined。虚数结果返回 Undefined。

数组 Undefined。

Object Undefined。

Null Undefined。


atan2(Decimal, Decimal)以弧度的形式返回 x 轴正方向与由两个参数定义的 (x, y) 点之间的角度。逆时针的角，角度为正数 (上半平面，y > 0)，顺时针的角，角度为负数 (下半平面，y < 0)。在代入函数之前，Decimal 参数舍入到双精度。SQL 版本 2015-10-8 及更高版本支持。

187


示例：atan2(1, 0) = 1.5707963267948966

参数类型参数类型结果

Int/Decimal Int/Decimal Decimal (双精度)，x 轴和指定的 (x,y) 点之间的角度。

Int/Decimal/String Int/Decimal/String Decimal，所描述点的反正切值。如果字符串无法转换，则结果为 Undefined。


aws_lambda(functionArn, inputJson)调用指定的 Lambda 函数并将 inputJson 传递给 Lambda 函数，并且返回 Lambda 函数生成的 JSON。

参数

参数描述

functionArn 要调用的 Lambda 函数的 ARN。Lambda 函数必须返回 JSON 数据。

inputJson 传递到 Lambda 函数的 JSON 输入。

您必须授予 AWS IoT lambda:InvokeFunction 权限以调用指定的 Lambda 函数。以下示例说明如何使用AWS CLI 授予 lambda:InvokeFunction 权限：

aws lambda add-permission --function-name "function_name"--region "region"--principal iot.amazonaws.com --source-arn arn:aws:iot:us-east-1:account_id:rule/rule_name--source-account "account_id"--statement-id "unique_id" --action "lambda:InvokeFunction"

add-permission 命令的参数如下：

--function-name

Lambda 函数的名称，您正在通过添加新的权限来更新其资源策略。--region

您的账户所处的 AWS 区域。--principal

获取权限的委托人。这应该是 iot.amazonaws.com，以授予 AWS IoT 调用 Lambda 函数的权限。--source-arn

规则的 ARN。您可以使用 get-topic-rule CLI 命令来获取规则的 ARN。--source-account

定义规则的 AWS 账户。--statement-id

唯一的语句标识符。

188


--action

要在此语句中允许的 Lambda 操作。在本示例中，我们要允许 AWS IoT 调用 Lambda 函数，因此我们指定 lambda:InvokeFunction。

Note

如果您在不提供源 ARN 的情况下为 AWS IoT 委托人添加权限，则所有通过 Lambda 操作创建规则的 AWS 账户都可以触发从 AWS IoT 调用 Lambda 函数的规则。

有关更多信息，请参阅 Lambda 权限模型。

以下规则说明如何调用 aws_lambda 函数：

SELECTaws_lambda("arn:aws:lambda:us-east-1:account_id:function:lambda_function", payload.inner.element).some.value as output FROM 'a/b'

payload.inner.element 从在主题“a/b”上发布的消息选择数据。

some.value 从 Lambda 函数生成的输出中选择数据。Note

规则引擎限制 Lambda 函数的执行持续时间。从规则执行的 Lambda 函数调用应在 2000 毫秒内完成。

bitand(Int, Int)在两个 Int (转换成的) 参数的位表示之间逐位执行与运算。SQL 版本 2015-10-8 及更高版本支持。

示例：bitand(13, 5) = 5


Int Int Int，对两个参数逐位执行与运算。

Int/Decimal Int/Decimal Int，对两个参数逐位执行与运算。所有非 Int 数字向下舍入至最近的 Int。如果任意参数不能转换为 Int，则结果为Undefined。

Int/Decimal/String Int/Decimal/String Int，对两个参数逐位执行与运算。所有字符串转换为Decimal 并向下舍入至最近 Int。如果转换失败，结果为Undefined。


bitor(Int, Int)在两个参数的位表示之间逐位执行或运算。SQL 版本 2015-10-8 及更高版本支持。

示例：bitor(8, 5) = 13


Int Int Int，对两个参数逐位执行或运算。

189

http://docs.aws.amazon.com/lambda/latest/dg/intro-permission-model.html



Int/Decimal Int/Decimal Int，对两个参数逐位执行或运算。所有非 Int 数字向下舍入至最近的 Int。如果转换失败，结果为 Undefined。

Int/Decimal/String Int/Decimal/String Int，对两个参数逐位执行或运算。所有字符串转换为Decimal 并向下舍入至最近 Int。如果转换失败，结果为Undefined。


bitxor(Int, Int)在两个 Int (转换成的) 参数的位表示之间逐位执行异或运算。SQL 版本 2015-10-8 及更高版本支持。

示例：bitor(13, 5) = 8


Int Int Int，对两个参数逐位执行异或运算。

Int/Decimal Int/Decimal Int，对两个参数逐位执行异或运算。非 Int 数字向下舍入至最近的 Int。

Int/Decimal/String Int/Decimal/String Int，对两个参数逐位执行异或运算。String 将转换为Decimal 并向下舍入至最近的 Int。如果任何转换失败，结果为 Undefined。


bitnot(Int)对 Int (转换成的) 参数的位表示逐位执行非运算。SQL 版本 2015-10-8 及更高版本支持。

示例：bitnot(13) = 2

参数类型结果

Int Int，对参数逐位执行非运算。

Decimal Int，对参数逐位执行非运算。Decimal 值会向下舍入至最近的 Int。

String Int，对参数逐位执行非运算。String 将转换为 Decimal并向下舍入至最近的 Int。如果任何转换失败，结果为Undefined。

其他值其他值。

cast()将值从一个数据类型转换为另一个数据类型。强制转换的行为在大多数情况下与标准转换相似，增加了在数字与 Boolean 值之间强制转换的功能。如果 AWS IoT 无法确定一种类型如何强制转换为另一种类型，则结果为 Undefined。SQL 版本 2015-10-8 及更高版本支持。格式：cast(值 as 值值)。

190


例如：

cast(true as Decimal) = 1.0

在调用 cast 时“as”后面可以出现以下关键字：

Keyword 结果

Decimal 将值强制转换为 Decimal。

Bool 将值强制转换为 Boolean。

Boolean 将值强制转换为 Boolean。

String 将值强制转换为 String。

Nvarchar 将值强制转换为 String。

文本将值强制转换为 String。

Ntext 将值强制转换为 String。

varchar 将值强制转换为 String。

Int 将值强制转换为 Int。

Int 将值强制转换为 Int。

强制转换规则：

强制转换为 Decimal

参数类型结果

Int 没有小数点的 Decimal。

Decimal 源值。

Boolean true = 1.0，false = 0.0。

String 会尝试将字符串解析为 Decimal。我们将尝试解析字符串来匹配正则表达式：^-?\d+(\.\d+)?((?i)E-?\d+)?$。可自动转换为 Decimal 的 String 示例包括 "0"、"-1.2"、"5E-12"。

数组 Undefined。

Object Undefined。

Null Undefined。


强制转换为 Int

参数类型结果

Int 源值。

Decimal 源值，向下舍入到最近的 Int。

191


参数类型结果

Boolean true = 1.0，false = 0.0。

String 会尝试将字符串解析为 Decimal。我们将尝试解析字符串来匹配正则表达式：^-?\d+(\.\d+)?((?i)E-?\d+)?$。可自动转换为 Decimal} 的 String 示例包括 "0"、"-1.2"、"5E-12"。我们会尝试将字符串转换为Decimal，然后向下舍入到最近的 Int。

数组 Undefined。

Object Undefined。

Null Undefined。


强制转换为 Boolean

参数类型结果

Int 0 = False，任何非零值 = True。

Decimal 0 = False，任何非零值 = True。

Boolean 源值。

String "true" = True 和 "false" = False (不区分大小写)。其他字符串值 = Undefined。

数组 Undefined。

Object Undefined。

Null Undefined。


强制转换为 String

参数类型结果

Int 标准表示法中 Int 的字符串表示。

Decimal 科学表示法中 Decimal 值的字符串表示。

Boolean "true" 或 "false"，全小写。

String "true"=True 和 "false"=False (不区分大小写)。其他字符串值 = Undefined。

数组数组序列化为 JSON。结果字符串为逗号分隔的列表，括在方括号中。String 用引号括起来。Decimal、Int、Boolean 不必如此。

Object 序列化为 JSON 的对象。JSON 字符串为键值对的逗号分隔列表，以大括号开始并结束。String 用引号括起来。Decimals、Int、Boolean 和 Null 不必如此。

192


参数类型结果

Null Undefined。


ceil(Decimal)将给定的 Decimal 向上舍入到最近的 Int。SQL 版本 2015-10-8 及更高版本支持。

示例：

ceil(1.2) = 2

ceil(11.2) = -1

参数类型结果

Int Int，参数值。

Decimal Int，Decimal 值向上舍入到最近的 Int。

String Int。字符串将转换为 Decimal 并向上舍入到最近的 Int。如果字符串无法转换为 Decimal，则结果为Undefined。


chr(String)返回给定 Int 参数对应的 ASCII 字符。SQL 版本 2015-10-8 及更高版本支持。

示例：

chr(65) = "A".

chr(49) = "1".

参数类型结果

Int 与指定的 ASCII 值对应的字符。如果参数不是有效的 ASCII值，则结果为 Undefined。

Decimal 与指定的 ASCII 值对应的字符。Decimal 参数会向下舍入至最近的 Int。如果参数不是有效的 ASCII 值，则结果为Undefined。


String 如果 String 可以转换为 Decimal，则向下舍入到最近的 Int。如果参数不是有效的 ASCII 值，则结果为Undefined。

数组 Undefined。

Object Undefined。

193


参数类型结果

Null Undefined。


clientid()返回发送消息的 MQTT 客户端的 ID，如果未通过 MQTT 发送消息，则返回 n/a。SQL 版本 2015-10-8 及更高版本支持。

例如：

clientid() = "123456789012"

concat()联接数组或字符串。该函数可接受任意数量的参数，并返回 String 或 Array。SQL 版本 2015-10-8 及更高版本支持。

示例：

concat() = Undefined。

concat(1) = "1".

concat([1, 2, 3], 4) = [1, 2, 3, 4]。

concat([1, 2, 3], "hello") = [1, 2, 3, "hello"]

concat("con", "cat") = "concat"

concat(1, "hello") = "1hello"

concat("he","is","man") = "heisman"

concat([1, 2, 3], "hello", [4, 5, 6]) = [1, 2, 3, "hello", 4, 5, 6]

参数数量结果

0 Undefined。

1 不经修改返回参数。

2+ 如果任意参数为 Array，那么结果为包含所有参数的一个数组。如果没有参数为 Array，并且至少有一个参数为String，则结果是所有参数的 String 表示的联接。参数将使用上文列出的标准转换被转换为 String。。

cos(Decimal)以弧度形式返回数字的余弦值。在代入函数之前，Decimal 参数舍入到双精度。SQL 版本 2015-10-8 及更高版本支持。

例如：

194


cos(0) = 1.

参数类型结果

Int Decimal (双精度)，参数的余弦值。虚数结果返回Undefined。

Decimal Decimal (双精度)，参数的余弦值。虚数结果返回Undefined。


String Decimal (双精度)，参数的余弦值。如果字符串无法转换为 Decimal，则结果为 Undefined。虚数结果返回Undefined。

数组 Undefined。

Object Undefined。

Null Undefined。


cosh(Decimal)以弧度形式返回数字的双曲余弦值。在代入函数之前，Decimal 参数舍入到双精度。SQL 版本 2015-10-8及更高版本支持。

示例：cosh(2.3) = 5.037220649268761。

参数类型结果

Int Decimal (双精度)，参数的双曲余弦值。虚数结果返回Undefined。

Decimal Decimal (双精度)，参数的双曲余弦值。虚数结果返回Undefined。


String Decimal (双精度)，参数的双曲余弦值。如果字符串无法转换为 Decimal，则结果为 Undefined。虚数结果返回Undefined。

数组 Undefined。

Object Undefined。

Null Undefined。


encode(value, encodingScheme)根据编码方案，使用 encode 函数将负载（可能是非 JSON 数据）编码为字符串表示形式。SQL 版本2016-03-23 及更高版本支持。

195


值

AWS IoT SQL 参考 (p. 177) 中所定义的任何有效的表达式。此外，您还可以指定 * 以对整个负载进行编码，无论它是否为 JSON 格式。如果您提供了表达式，评估结果将在编码之前首先转换为字符串。

encodingScheme

代表您要使用的编码方案的文字字符串。目前仅支持 'base64'。

endswith(String, String)返回 Boolean 来表示第一个 String 参数是否以第二个 String 参数结尾。如果任一参数为 Null 或Undefined，则结果为 Undefined。SQL 版本 2015-10-8 及更高版本支持。

示例：endswith("cat","at") = true。

参数类型 1 参数类型 2 结果

String String 如果第一个参数以第二个参数结尾，则为 true。否则为false。

其他值其他值两个参数都使用标准转换规则被转换为 String。如果第一个参数以第二个参数结尾，则为 true。否则为false。如果任一参数为 Null 或 Undefined，则结果为Undefined。

exp(Decimal)返回 e 的 Decimal 参数次方。在代入函数之前，Decimal 参数舍入到双精度。SQL 版本 2015-10-8 及更高版本支持。

示例：exp(1) = e.

参数类型结果

Int Decimal (双精度)，e ^ 参数。

Decimal Decimal (双精度)，e ^ 参数。

String Decimal (双精度)，e ^ 参数。如果 String 无法转换为Decimal，则结果为 Undefined。


get从一个集合数据类型 (数组、字符串、对象) 中提取值。第一个参数不会进行任何转换。根据表中的记载对第二个参数进行转换。SQL 版本 2015-10-8 及更高版本支持。

示例：

get(["a", "b", "c"], 1) = "b"

get({"a":"b"}, "a") = "b"

get("abc", 1) = "b"

196



数组任何类型 (转换为 Int) 在第二个参数 (已经转换为 Int) 提供的 Array 中，从零开始索引得到的项目。如果转换已不成功，结果为Undefined。如果索引超出 Array 的范围 (负值或大于等于数组长度)，则结果为 Undefined。

字符串任何类型 (转换为 Int) 在第二个参数 (已经转换为 Int) 提供的字符串中，从零开始索引得到的字符。如果转换已不成功，结果为Undefined。如果索引超出字符串的范围 (负值或大于等于字符串长度)，则结果为 Undefined。

Object String (不进行转换) 第一个参数对象中存储的值与作为第二个参数提供的字符串键相对应。

其他值任意值 Undefined。

get_thing_shadow(thingName, roleARN)返回指定事物的影子。SQL 版本 2016-03-23 及更高版本支持。

thingName

String：您要检索其影子的事物的名称。roleArn

String：具有 iot:GetThingShadow 的 ARN 角色。

例如：

SELECT * from 'a/b'

WHERE get_thing_shadow("MyThing","arn:aws:iam::123456789012:role/AllowsThingShadowAccess") .state.reported.alarm = 'ON'

哈希函数AWS IoT 提供了以下哈希函数：

• md2• md5• sha1• sha224• sha256• sha384• sha512

所有哈希函数都可以输入一个字符串参数。结果为该字符串的哈希值。对非字符串参数进行标准字符串转换。所有哈希函数在 SQL 版本 2015-10-8 及更高版本中均受支持。

示例：

md2("hello") = "a9046c73e00331af68917d3804f70655"

md5("hello") = "5d41402abc4b2a76b9719d911017c592"

197


indexof(String, String)返回第二个参数的第一个索引 (从零开始) 作为第一个参数的子字符串。两个参数均为字符串。如果参数数据类型不是字符串，则应用标准字符串转换规则进行转换。此函数只对字符串有效，不适用于数组。SQL 版本2015-10-8 及更高版本支持。

示例：

indexof("abcd", "bc") = 1

isNull()返回该参数是否为 Null 值。SQL 版本 2015-10-8 及更高版本支持。

示例：

isNull(5) = false.

isNull(Null) = true.

参数类型结果

Int false

Decimal false

Boolean false

String false

Array false

Object false

Null true

Undefined false

isUndefined()返回该参数是否为 Undefined。SQL 版本 2015-10-8 及更高版本支持。

示例：

isUndefined(5) = false.

isNull(floor([1,2,3]))) = true.

参数类型结果

Int false

Decimal false

Boolean false

String false

198


参数类型结果

Array false

Object false

Null false

Undefined true

length(String)返回输入字符数中的字符数。对非 String 参数应用标准转换规则。SQL 版本 2015-10-8 及更高版本支持。

示例：

length("hi") = 2

length(false) = 5

ln(Decimal)返回参数的自然对数。在代入函数之前，Decimal 参数舍入到双精度。SQL 版本 2015-10-8 及更高版本支持。

示例：ln(e) = 1。

参数类型结果

Int Decimal (双精度)，参数的自然对数。

Decimal Decimal (双精度)，参数的自然对数。


String Decimal (双精度)，参数的自然对数。如果字符串无法转换为 Decimal，则结果为 Undefined。

数组 Undefined。

Object Undefined。

Null Undefined。


log(Decimal)返回参数的以 10 为底的对数。在代入函数之前，Decimal 参数舍入到双精度。SQL 版本 2015-10-8 及更高版本支持。

示例：log(100) = 2.0。

参数类型结果

Int Decimal (双精度)，参数以 10 为底的对数。

199


参数类型结果

Decimal Decimal (双精度)，参数以 10 为底的对数。


String Decimal (双精度)，参数以 10 为底的对数。如果 String无法转换为 Decimal，则结果为 Undefined。

数组 Undefined。

Object Undefined。

Null Undefined。


lower(String)返回给定 String 的小写版本。非字符串参数使用标准转换规则转换为 String。SQL 版本 2015-10-8 及更高版本支持。

示例：

lower("HELLO") = "hello"。

lower(["HELLO"]) = "[\"hello\"]"。

lpad(String, Int)返回 String 参数，在输入参数的左侧填充由第二个参数指定的数量的空格。Int 参数必须介于 0 到1000 之间。如果输入的值在这一有效范围之外，则参数将被设置为与其最近的值 (0 或 1000)。SQL 版本2015-10-8 及更高版本支持。

示例：

lpad("hello", 2) = " hello"。

lpad(1, 3) = " 1"


String Int String，在输入 String 左侧填充由 Int 指定的数量的空格。

String Decimal Decimal 参数将向下舍入到最近的 Int，并在 String 左侧填充指定数量的空格。

String String 第二个参数将被转换为 Decimal，向下舍入到最近的Int，并在 String 左侧填充指定数量的空格。如果第二个参数无法转换为 Int，则结果为 Undefined。

其他值 Int/Decimal/String 第一个值将使用标准转换规则转换为 String，然后对该String 应用 LPAD 函数。如果它无法转换，则结果为Undefined。

任意值其他值 Undefined。

200


ltrim(String)从输入的 String 中删除所有前导空白 (制表符和空格)。SQL 版本 2015-10-8 及更高版本支持。

例如：

Ltrim(" h i ") = "hi "。

参数类型结果

Int Int 在删除所有前导空白之后的 String 表示。

Decimal Decimal 在删除所有前导空白之后的 String 表示。

Boolean 布尔值 ("true" 或 "false") 在删除所有前导空白之后的String 表示。

String 删除所有前导空白的参数。

数组 Array (使用标准转换规则) 删除所有前导空白之后的String 表示。

Object 对象 (使用标准转换规则) 删除所有前导空白之后的 String表示。

Null Undefined。


machinelearning_predict(modelId)利用 machinelearning_predict 函数，并根据 Amazon Machine Learning (Amazon ML) 模型使用来自MQTT 消息的数据进行预测。SQL 版本 2015-10-8 及更高版本支持。machinelearning_predict 函数的参数如下：

modelId

对其运行预测的模型的 ID。必须启用模型的实时终端节点。roleArn

IAM 角色，拥有具备 machinelearning:Predict 和 machinelearning:GetMLModel 权限的策略并允许访问运行预测所针对的模型。

record

要传递到 Amazon ML 预测 API 的数据。该参数应表示为单层 JSON 对象。如果记录是多级 JSON 对象，该记录将通过序列化值来进行平展。例如，以下 JSON：

{ "key1": {"innerKey1": "value1"}, "key2": 0}

会变为：

{ "key1": "{\"innerKey1\": \"value1\"}", "key2": 0}

该函数返回具有以下字段的 JSON 对象：

201


predictedLabel

基于模型的输入分类。details

包含以下属性：PredictiveModelType

模型类型。有效值为 REGRESSION、BINARY、MULTICLASS。Algorithm

Amazon ML 用于预测的算法。该值必须为 SGD。predictedScores

包含与每个标签对应的原始分类分数。predictedValue

Amazon ML 预测的值。

mod(Decimal, Decimal)返回第一个参数除以第二个参数的余数。SQL 版本 2015-10-8 及更高版本支持。您还可以使用“%”作为相同取模功能的插入运算符。SQL 版本 2015-10-8 及更高版本支持。

示例：mod(8, 3) = 2。


Int Int Int，第一个参数对第二个参数取模。

Int/Decimal Int/Decimal Decimal，第一个参数对第二个操作数取模。

String/Int/Decimal String/Int/Decimal 如果所有字符串转换为 Decimal，则结果为第一个参数对第二个参数取模的值。否则为 Undefined。


nanvl(AnyValue, AnyValue)如果第一个参数为有效的 Decimal，则返回第一个参数。否则返回第二个参数。SQL 版本 2015-10-8 及更高版本支持。

示例：Nanvl(8, 3) = 8。

参数类型 1 参数类型 2 输出

未定义任意值第二个参数。

Null 任意值第二个参数。

Decimal (NaN) 任意值第二个参数。

Decimal (非 NaN) 任意值第一个参数。

202



其他值任意值第一个参数。

newuuid()返回随机的 16 字节 UUID。SQL 版本 2015-10-8 及更高版本支持。

示例: newuuid() = 123a4567-b89c-12d3-e456-789012345000

numbytes(String)返回输入字符串 UTF-8 编码中的字节数。对非 String 参数应用标准转换规则。SQL 版本 2015-10-8 及更高版本支持。

示例：

numbytes("hi") = 2

numbytes("€") = 3

principal()根据收到请求的终端节点 (MQTT 或 HTTP) 类型，返回 X.509 证书的指纹或事物名称。SQL 版本 2015-10-8及更高版本支持。

例如：

principal() = "ba67293af50bf2506f5f93469686da660c7c844e7b3950bfb16813e0d31e9373"

parse_time(String, Long, [String])使用 parse_time 函数可将时间戳的格式设置为人类可读的日期/时间格式。SQL 版本 2016-03-23 及更高版本支持。parse_time 函数的参数如下：

pattern

(String) 符合 ISO 8601 标准格式的日期/时间模式。(具体而言，此函数支持 Joda-Time 格式。)timestamp

(Long) 要采用自 Unix 纪元时间以来的毫秒数格式表示的时间。请参阅函数 timestamp() (p. 213)。timezone

(String) [Optional] 采用日期/时间格式的时区。默认值为“UTC”。此函数支持 Joda-Time 时区

示例：

在将此消息发布到主题“A/B”时，负载 {"ts": "1970.01.01 AD at 21:46:40 CST"} 将发送到 S3 存储桶：

{ "ruleArn": "arn:aws:iot:us-east-2:ACCOUNT_ID:rule/RULE_NAME", "rule": { "awsIotSqlVersion": "2016-03-23", "sql": "SELECT parse_time("yyyy.MM.dd G 'at' HH:mm:ss z", 100000000, "America/Belize" ) as ts FROM 'A/B'",

"ruleDisabled": false,

203

https://en.wikipedia.org/wiki/ISO_8601

http://www.joda.org/joda-time/apidocs/org/joda/time/format/DateTimeFormat.html

http://joda-time.sourceforge.net/timezones.html


"actions": [ { "s3": { "roleArn": "arn:aws:iam::ACCOUNT_ID:rule:role/ROLE_NAME", "bucketName": "BUCKET_NAME", "key": "KEY_NAME" } } ], "ruleName": "RULE_NAME" }}

在将此消息发布到主题“A/B”时，与 {"ts": "2017.06.09 AD at 17:19:46 UTC"} 类似 (但具有当前日期/时间) 的负载将发送到 S3 存储桶：

{ "ruleArn": "arn:aws:iot:us-east-2:ACCOUNT_ID:rule/RULE_NAME", "rule": { "awsIotSqlVersion": "2016-03-23", "sql": "SELECT parse_time("yyyy.MM.dd G 'at' HH:mm:ss z", timestamp() ) as ts FROM 'A/B'", "ruleDisabled": false, "actions": [ { "s3": { "roleArn": "arn:aws:iam::ACCOUNT_ID:rule:role/ROLE_NAME", "bucketName": "BUCKET_NAME", "key": "KEY_NAME" } } ], "ruleName": "RULE_NAME" }}

parse_time() 也可用作替换模板。例如，在将此消息发布到主题“A/B”时，负载将发送到密钥为“2017”的S3 存储桶：

{ "ruleArn": "arn:aws:iot:us-east-2:ACCOUNT_ID:rule/RULE_NAME", "rule": { "awsIotSqlVersion": "2016-03-23", "sql": "SELECT * FROM 'A/B'", "ruleDisabled": false, "actions": [ { "s3": { "roleArn": "arn:aws:iam::ACCOUNT_ID:rule:role/ROLE_NAME", "bucketName": BUCKET_NAME, "key": "${parse_time("yyyy", timestamp(), "UTC")}" } } ], "ruleName": "RULE_NAME" }}

power(Decimal, Decimal)返回第一个参数的第二个参数次幂的值。在代入函数之前，Decimal 参数舍入到双精度。SQL 版本2015-10-8 及更高版本支持。SQL 版本 2015-10-8 及更高版本支持。

204


示例：power(2, 5) = 32.0。


Int/Decimal Int/Decimal Decimal (双精度)，返回第一个参数的第二个参数次幂的值。

Int/Decimal/String Int/Decimal/String Decimal (双精度) 返回第一个参数的第二个参数次幂的值。所有字符串均转换为 Decimal。如果任何 String 转换为 Decimal 失败，则结果为 Undefined。


rand()返回在 0.0 到 1.0 之间均匀分布的伪随机双精度值。SQL 版本 2015-10-8 及更高版本支持。

例如：

rand() = 0.8231909191640703

regexp_matches(String, String)返回第一个参数是否包含第二个参数的匹配值 (正则表达式)。

例如：

Regexp_matches("aaaa", "a{2,}") = true.

Regexp_matches("aaaa", "b") = false.

第一个参数：

参数类型结果

Int Int 的 String 表示。

Decimal Decimal 的 String 表示。

Boolean 布尔值 ("true" 或 "false") 的 String 表示。

String 这些区域有： String.

数组 Array (使用标准转换规则) 的 String 表示。

Object 对象 (使用标准转换规则) 的 String 表示。

Null Undefined。


第二个参数：

必须是有效的正则表达式。非字符串类型使用标准转换规则转换为 String。根据类型，生成的字符串不一定是正则表达式。如果 (转换后的) 参数不是有效的正则表达式，则结果为 Undefined。

第三个参数：

205


必须是有效的正则表达式替代字符串。(可以引用捕获组。)非字符串类型将使用标准转换规则转换为String。如果 (转换后的) 参数不是有效的正则表达式替代字符串，则结果为 Undefined。

regexp_replace(String, String, String)用第三个参数替换在第一个参数中出现的所有第二个参数 (正则表达式)。用“$”引用捕获组。SQL 版本2015-10-8 及更高版本支持。

例如：

Regexp_replace("abcd", "bc", "x") = "axd"。

Regexp_replace("abcd", "b(.*)d", "$1") = "ac"。

第一个参数：

参数类型结果




String 源值。



Null Undefined。


第二个参数：


第三个参数：

必须是有效的正则表达式替代字符串。(可以引用捕获组。)非字符串类型将使用标准转换规则转换为String。如果 (转换后的) 参数不是有效的正则表达式替代字符串，则结果为 Undefined。

regexp_substr(String, String)在第一个参数中查找第二个参数 (正则表达式) 的第一个匹配。用“$”引用捕获组。SQL 版本 2015-10-8 及更高版本支持。

例如：

regexp_substr("hihihello", "hi") => "hi"

regexp_substr("hihihello", "(hi)*") => "hihi"。

第一个参数：

参数类型结果


206


参数类型结果



String String 参数。



Null Undefined。


第二个参数：


第三个参数：

必须是有效的正则表达式替代字符串。(可以引用捕获组。)非字符串类型将使用标准转换规则转换为String。如果参数不是有效的正则表达式替代字符串，则结果为 Undefined。

rpad(String, Int)返回字符串参数，在输入参数的右侧填充在第二个参数中指定的数量的空格。Int 参数必须介于 0 到1000 之间。如果输入的值在这一有效范围之外，则参数将被设置为与其最近的值 (0 或 1000)。SQL 版本2015-10-8 及更高版本支持。

示例：

rpad("hello", 2) = "hello "。

rpad(1, 3) = "1 ".


String Int 在String的右侧填充由Int 指定数量的空格。

String Decimal Decimal参数将向下舍入到最近的Int，并且在字符串的右侧

207


参数类型 1 参数类型 2 结果填充由Int 指定数量的空格。

String String 第二个参数将转换为Decimal，并向下舍入到最近的Int。在String的右侧填充由Int 值指定数量的空格。

其他值 Int/Decimal/String 第一个值将使用标准转换规则转换为String，然后对该String应用rpad函数。如果它无法转换，则结果为Undefined。

任意值其他值 Undefined。

round(Decimal)将给定的 Decimal 舍入到最近的 Int。如果 Decimal 与上下两个 Int 值距离相同 (例如 0.5)，Decimal将向上进位。SQL 版本 2015-10-8 及更高版本支持。

示例：Round(1.2) = 1。

Round(1.5) = 2.

Round(1.7) = 2.

Round(-1.1) = -1.

208


Round(-1.5) = -2.

参数类型结果

Int 参数。

Decimal Decimal 会向下舍入至最近的 Int。

String Decimal 会向下舍入至最近的 Int。如果字符串无法转换为 Decimal，则结果为 Undefined。


rtrim(String)从输入的 String 中删除所有尾随空白 (制表符和空格)。SQL 版本 2015-10-8 及更高版本支持。

示例：

rtrim(" h i ") = " h i"

参数类型结果






Null Undefined。

未定义 Undefined

sign(Decimal)返回给定数字的符号。当参数的符号为正时，将返回 1。当参数的符号为负时，将返回 -1。如果参数为 0，则返回 0。SQL 版本 2015-10-8 及更高版本支持。

示例：

sign(-7) = -1.

sign(0) = 0。

sign(13) = 1.

参数类型结果

Int Int，Int 值的符号。

Decimal Int，Decimal 值的符号。

209


参数类型结果

String Int，Decimal 值的符号。字符串将转换为 Decimal 值，并返回 Decimal 值的符号。如果 String 无法转换为Decimal，则结果为 Undefined。SQL 版本 2015-10-8 及更高版本支持。


sin(Decimal)以弧度形式返回数字的正弦值。在代入函数之前，Decimal 参数舍入到双精度。SQL 版本 2015-10-8 及更高版本支持。

示例：sin(0) = 0.0

参数类型结果

Int Decimal (双精度)，参数的正弦值。

Decimal Decimal (双精度)，参数的正弦值。


String Decimal (双精度)，参数的正弦值。如果字符串无法转换为Decimal，则结果为 Undefined。

数组 Undefined。

Object Undefined。

Null Undefined。

Undefined Undefined。

sinh(Decimal)返回数字的双曲正弦。在代入函数之前，Decimal 值舍入到双精度。结果是双精度的 Decimal 值。SQL 版本 2015-10-8 及更高版本支持。

示例：sinh(2.3) = 4.936961805545957

参数类型结果

Int Decimal (双精度)，参数的双曲正弦值。

Decimal Decimal (双精度)，参数的双曲正弦值。


String Decimal (双精度)，参数的双曲正弦值。如果字符串无法转换为 Decimal，则结果为 Undefined。

数组 Undefined。

Object Undefined。

210


参数类型结果

Null Undefined。


substring(String, Int [, Int])输入值为 String 后跟一个或两个 Int 值。对于 String 和单个 Int 参数，此函数在输入的 String 中从指定的 Int 索引 (从零开始，包括零) 到 String 结束提取子字符串并返回。对于 String 和两个 Int参数，此函数在输入的 String 中从第一个 Int 索引参数 (从零开始，包括零) 到第二个 Int 索引参数(从零开始，包括零) 提取子字符串并返回。索引小于零时将设置为零。大于 String 长度的索引将设置为String 长度。在三个参数的版本中，如果第一个索引大于等于第二个索引，那么结果为空 String。

如果提供的参数不是 (String、Int) 或 (String、Int、Int)，则将对参数应用标准转换以将其转换为正确的类型。如果无法转换类型，函数的结果为 Undefined。SQL 版本 2015-10-8 及更高版本支持。

示例：

substring("012345", 0) = "012345"。

substring("012345", 2) = "2345"。

substring("012345", 2.745) = "2345"。

substring(123, 2) = "3".

substring("012345", -1) = "012345"。

substring(true, 1.2) = "rue"。

substring(false, -2.411E247) = "false".

substring("012345", 1, 3) = "12".

substring("012345", -50, 50) = "012345"。

substring("012345", 3, 1) = ""。

sqrt(Decimal)返回数字的平方根。在代入函数之前，Decimal 参数舍入到双精度。SQL 版本 2015-10-8 及更高版本支持。

示例：sqrt(9) = 3.0。

参数类型结果

Int 参数的平方根。

Decimal 参数的平方根。


String 参数的平方根。如果字符串无法转换为 Decimal，则结果为 Undefined。

数组 Undefined。

211


参数类型结果

Object Undefined。

Null Undefined。


startswith(String, String)返回显示第一个字符串参数是否以第二个字符串参数开头的 Boolean。如果任一参数为 Null 或Undefined，则结果为 Undefined。SQL 版本 2015-10-8 及更高版本支持。

例如：

startswith("ranger","ran") = true


String String 第一个字符串是否以第二个字符串开头。

其他值其他值两个参数都使用标准转换规则被转换为 String。返回第一个字符串是否以第二个字符串开头。如果任一参数为 Null或 Undefined，则结果为 Undefined。

tan(Decimal)以弧度形式返回数字的正切值。在代入函数之前，Decimal 值舍入到双精度。SQL 版本 2015-10-8 及更高版本支持。

示例：tan(3) = -0.1425465430742778

参数类型结果

Int Decimal (双精度)，参数的正切值。

Decimal Decimal (双精度)，参数的正切值。


String Decimal (双精度)，参数的正切值。如果字符串无法转换为Decimal，则结果为 Undefined。

数组 Undefined。

Object Undefined。

Null Undefined。


tanh(Decimal)以弧度形式返回数字的双曲正切值。在代入函数之前，Decimal 值舍入到双精度。SQL 版本 2015-10-8 及更高版本支持。

212


示例：tanh(2.3) = 0.9800963962661914

参数类型结果

Int Decimal (双精度)，参数的双曲正切值。

Decimal Decimal (双精度)，参数的双曲正切值。


String Decimal (双精度)，参数的双曲正切值。如果字符串无法转换为 Decimal，则结果为 Undefined。

数组 Undefined。

Object Undefined。

Null Undefined。


timestamp()返回 AWS IoT 规则引擎观察到的当前时间戳，用距离 1970 年 1 月 1 日（星期四）协调世界时 (UTC)00:00:00 的毫秒数来表示。SQL 版本 2015-10-8 及更高版本支持。

示例: timestamp() = 1481825251155

topic(Decimal)返回已向其发送触发规则的消息的主题。如果未指定参数，则返回整个主题。Decimal 参数用于指定从 1 开始的特定主题段。对于主题 foo/bar/baz，主题(1) 将返回 foo，主题(2) 将返回 bar，以此类推。SQL 版本 2015-10-8 及更高版本支持。

示例：

topic() = "things/myThings/thingOne"

topic(1) = "things"

traceid()返回 MQTT 消息的跟踪 ID (UUID)，如果未通过 MQTT 发送消息，则返回 Undefined。SQL 版本2015-10-8 及更高版本支持。

例如：

traceid() = "12345678-1234-1234-1234-123456789012"

trunc(Decimal, Int)按照第二个参数指定的 Decimal 位数截断第一个参数。如果第二个参数小于零，则会设置为零。如果参数第二大于 34，则会设置为 34。将从结果中删除结尾的零。SQL 版本 2015-10-8 及更高版本支持。

示例：

trunc(2.3, 0) = 2.

213


trunc(2.3123, 2 = 2.31。

trunc(2.888, 2) = 2.88。

(2.00, 5) = 2.


Int Int 源值。

Int/Decimal Int/Decimal 第一个参数被截断到由第二个参数所指定的长度。第二个参数如果不是 Int，将向下舍入至最近的 Int。

Int/Decimal/String 第一个参数被截断到由第二个参数所指定的长度。第二个参数如果不是 Int，将向下舍入至最近的 Int。String将转换为 Decimal 值。如果字符串转换失败，则结果为Undefined。


trim(String)从输入的 String 中删除所有前导和尾随的空白。SQL 版本 2015-10-8 及更高版本支持。

例如：

Trim(" hi ") = "hi"

参数类型结果

Int Int 在删除所有前导和尾随空白之后的 String 表示。

Decimal Decimal 在删除所有前导和尾随空白之后的 String 表示。

Boolean Boolean ("true" 或 "false") 在删除所有前导和尾随空白之后的 String 表示。

String 删除所有前导和尾随空白之后的 String。

数组 Array 使用标准转换规则进行转换后的 String 表示。

Object 对象使用标准转换规则进行转换后的 String 表示。

Null Undefined。


upper(String)返回给定 String 的大写版本。非 String 参数将使用标准转换规则转换为 String。SQL 版本 2015-10-8及更高版本支持。

示例：

upper("hello") = "HELLO"

214

AWS IoT 开发人员指南SELECT 语句

upper(["hello"]) = "[\"HELLO\"]"

SELECT 语句AWS IoT SELECT 子句基本与 ANSI SQL SELECT 子句相同，仅存在一些细微区别。

您可以使用 SELECT 子句从传入 MQTT 消息中提取信息。SELECT * 可以用于检索整个传入消息负载。例如：

Incoming payload published on topic 'a/b': {"color":"red", "temperature":50}SQL statement: SELECT * FROM 'a/b'Outgoing payload: {"color":"red", "temperature":50}

如果负载是 JSON 对象，您可以参考对象中的键。您的传出负载将包含键值对。例如：

Incoming payload published on topic 'a/b': {"color":"red", "temperature":50}SQL statement: SELECT color FROM 'a/b'Outgoing payload: {"color":"red"}

您可以使用 AS 关键字重命名键。例如：

Incoming payload published on topic 'a/b':{"color":"red", "temperature":50}SQL:SELECT color AS my_color FROM 'a/b'Outgoing payload: {"my_color":"red"}

您可以通过用逗号分隔来选择多个项目。例如：

Incoming payload published on topic 'a/b': {"color":"red", "temperature":50}SQL: SELECT color as my_color, temperature as farenheit FROM 'a/b'Outgoing payload: {"my_color":"red","farenheit":50}

您可以通过在向传入负载添加项目时包括“*”来选择多个项目。例如：

Incoming payload published on topic 'a/b': {"color":"red", "temperature:50}SQL: SELECT *, 15 as speed FROM 'a/b'Outgoing payload: {"color":"red", "temperature:50, speed:15}"

您可以使用 "VALUE" 关键字来生成不属于 JSON 对象的传出负载。您只能选择一个项目。例如：

Incoming payload published on topic 'a/b': {"color":"red", "temperature":50}SQL: SELECT VALUE color FROM 'a/b'Outgoing payload: "red"

您可以使用 '.' 语法深入剖析传入负载中的嵌套 JSON 对象。例如：

Incoming payload published on topic 'a/b': {"color":{"red":255,"green":0,"blue":0}, "temperature":50}SQL: SELECT color.red as red_value FROM 'a/b'Outgoing payload: {"red_value":255}

您可以使用函数 (参阅函数 (p. 185)) 来转换传入负载。可使用圆括号进行分组。例如：

Incoming payload published on topic 'a/b': {"color":"red", "temperature":50}SQL: SELECT (temperature – 32) * 5 / 9 AS celsius, upper(color) as my_color FROM 'a/b'

215

AWS IoT 开发人员指南FROM 子句

Outgoing payload: {"celsius":10,"my_color":"RED"}

使用二进制负载当消息负载应作为原始二进制数据 (而不是 JSON 对象) 进行处理时，可以使用 * 运算符在 SELECT 子句中对其进行引用。

必须遵循以下规则使用 * 将消息负载作为原始二进制数据引用：

1. SQL 语句和模板不得引用除 * 之外的 JSON 名称。2. SELECT 语句必须具有 * 作为唯一项目，或者必须只具有函数，例如：

SELECT * FROM 'a/b'

SELECT encode(*, 'base64') AS data, timestamp() AS ts FROM 'a/b'

二进制负载示例以下 SELECT 子句可与二进制负载配合使用，因为它未引用任何 JSON 名称。

SELECT * FROM 'a/b'

以下 SELECT 无法与二进制负载配合使用，因为它在 WHERE 子句中引用了 device_type。

SELECT * FROM 'a/b' WHERE device_type = 'thermostat'

以下 SELECT 无法与二进制负载配合使用，因为它违反了第 2 条规则。

SELECT *, timestamp() AS timestamp FROM 'a/b'

以下 SELECT 可以与二进制负载配合使用，因为它并未违反任意一条规则。

SELECT * FROM 'a/b' WHERE timestamp() % 12 = 0

以下 AWS IoT 规则无法与二进制负载配合使用，因为它违反了第 1 条规则。

{ "sql": "SELECT * FROM 'a/b'" "actions": [{ "republish": { "topic":"device/${device_id}" } }]}

FROM 子句FROM 子句在主题或主题筛选条件中订阅您的规则。主题筛选条件可用于订阅一组类似的主题。

例如：

传入负载已发布至主题 'a/b'：{temperature: 50}

216

AWS IoT 开发人员指南WHERE 子句

传入负载已发布至主题 'a/c'：{temperature: 50}

SQL: "SELECT temperature AS t FROM 'a/b'".

规则已订阅 'a/b'，因此，传入负载已传递至规则，并且传出负载 (已传递给规则操作) 为：{t: 50}。规则未订阅 'a/c'，因此在 'a/c' 上发布的消息不会触发规则。

您可以使用 # 通配符来匹配主题筛选条件中的任何子路径：

例如：

传入负载已发布至主题 'a/b'：{temperature: 50}。

传入负载已发布至主题 'a/c'：{temperature: 60}。

传入负载已发布至主题 'a/e/f'：{temperature: 70}。

传入负载已发布至主题 'b/x'：{temperature: 80}。

SQL: "SELECT temperature AS t FROM 'a/#'".

规则已订阅以 'a' 开头的所有主题，因此它将执行三次，将 {t: 50} (for a/b), {t: 60} (适用于 a/c) 和 {t: 70} (适用于 a/e/f) 的传出负载发送至其操作。它未订阅 'b/x'，因此，{temperature: 80} 消息不会触发规则。

您可以使用“+”字符匹配任何一个特定的路径元素：

例如：

传入负载已发布至主题 'a/b'：{temperature: 50}。

传入负载已发布至主题 'a/c'：{temperature: 60}。

传入负载已发布至主题 'a/e/f'：{temperature: 70}。

传入负载已发布至主题 'b/x'：{temperature: 80}。

SQL: "SELECT temperature AS t FROM 'a/+'".

规则已订阅包含两个路径元素的所有主题，其中第一个元素为 'a'。规则将对发送至 'a/b' 和 'a/c' 的消息执行，但不会对发送至 'a/e/f' 或 'b/x' 的消息执行。

您可以在 WHERE 子句中使用函数和运算符。在 WHERE 子句中，您无法引用在 SELECT 子句中通过 AS关键字创建的任何别名。(首先评估 WHERE 语句，再确定是否评估 SELECT 子句。)

WHERE 子句WHERE 子句确定在向已订阅规则的 MQTT 主题发送消息时是否评估规则。如果 WHERE 子句的计算结果为 true，则将评估规则。否则不评估规则。

例如：

传入负载已发布至 a/b：{"color":"red", "temperature":40}。

SQL: SELECT color AS my_color FROM 'a/b' WHERE temperature > 50 AND color <>'red'.

在本例中，不会评估规则，不存在传出负载，也不会触发规则操作。

您可以在 WHERE 子句中使用函数和运算符。但是，您无法引用在 SELECT 中通过 AS 关键字创建的任何别名。(首先评估 WHERE 语句，再确定是否评估 SELECT。)

217

AWS IoT 开发人员指南文本

文本您可以直接在规则 SQL 的 SELECT 和 WHERE 子句中指定文本对象，该对象可用于传递信息。

Note

文本只能在 SQL 版本 2016-03-23 或更高版本中使用。

使用 JSON 对象语法 (键值对、逗号分隔、键为字符串/值为 JSON 值、括在大括号 {} 中)。例如：

传入负载已发布至主题 a/b："{lat_long: [47.606,-122.332]}"

SQL 语句: SELECT {'latitude': get(lat_long, 0),'longitude':get(lat_long, 1)} aslat_long FROM 'a/b'

生成的传出负载为：{'latitude':47.606,'longitude':-122.332}。

您也可以在规则 SQL 的 SELECT 和 WHERE 子句中直接指定数组，用于分组信息。使用 JSON 语法 (在方括号 [] 中用逗号分隔项目来创建数组文本)。例如：

传入负载已发布至主题 a/b：{lat: 47.696, long: -122.332}

SQL 语句: SELECT [lat,long] as lat_long FROM 'a/b'

生成的传出负载为：{"lat_long": [47.606,-122.332]}。

Case 语句与 Switch 语句和 If/Else 语句类似，Case 语句可用于执行分支。

语法：

CASE v WHEN t[1] THEN r[1] WHEN t[2] THEN r[2] ... WHEN t[n] THEN r[n] ELSE r[e] END

评估 v 表达式，并与每个 t[i] 表达式进行相等匹配。如果找到匹配，相应的 r[i] 表达式会成为 Case 语句的结果。如果可能存在多个匹配，则选择第一个匹配。如果没有匹配，则 Else 语句的 re 将用作结果。如果没有匹配也没有 Else 语句，则 Case 语句的结果为 Undefined。例如：

传入负载已发布至主题 a/b：{"color":"yellow"}

SQL 语句: SELECT CASE color WHEN 'green' THEN 'go' WHEN 'yellow' THEN 'caution'WHEN 'red' THEN 'stop' ELSE 'you are not at a stop light' END as instructionsFROM 'a/b'

生成的传出负载为：{"instructions":"caution"}。

Case 语句需要至少一个 WHEN 子句。不需要 ELSE 子句。

Note

如果 v 等于 Undefined，则 Case 语句的结果为 Undefined。

JSON 扩展您可以使用以下 ANSI SQL 语法扩展，更加轻松地使用嵌套 JSON 对象。

218

AWS IoT 开发人员指南替换模板

“.”运算符

此运算符可访问与 ANSI SQL 和 JavaScript 相同的嵌入式 JSON 对象和函数的成员。例如：

SELECT foo.bar AS bar.baz FROM 'a/b'

* 运算符

该运算符与 ANSI SQL 中的 * 通配符的运作方式相同。该运算符仅用于 SELECT 子句，并会创建包含消息数据的全新 JSON 对象。如果消息负载不是 JSON 格式，* 将以原始字节形式返回整个消息负载。例如：

SELECT * FROM 'a/b'

将函数应用到属性值

下面显示了一个可由设备发布的 JSON 负载示例：

{ "deviceid" : "iot123", "temp" : 54.98, "humidity" : 32.43, "coords" : { "latitude" : 47.615694, "longitude" : -122.3359976 }}

下面的示例将函数应用到 JSON 负载中的一个属性值：

SELECT temp, md5(deviceid) AS hashed_id FROM topic/#

此查询的结果为以下 JSON 对象：

{ "temp": 54.98, "hashed_id": "e37f81fb397e595c4aeb5645b8cbbbd1"}

替换模板您可以使用替换模板来补充规则已触发且 AWS IoT 执行操作时返回的 JSON 数据。替换模板的语法是${expression}，其中 expression 可以是 SELECT 或 WHERE 子句中 AWS IoT 支持的任意表达式。有关支持的表达式的更多信息，请参阅AWS IoT SQL 参考 (p. 177)。

替换模板显示在规则的 SELECT 子句中：

{ "sql": "SELECT *, topic() AS topic FROM 'my/iot/topic'", "ruleDisabled": false, "actions": [{ "republish": { "topic": "${topic()}/republish", "roleArn": "arn:aws:iam::123456789012:role/my-iot-role" } }]}

219

AWS IoT 开发人员指南替换模板

如果该规则由以下 JSON 触发：

{ "deviceid" : "iot123", "temp" : 54.98, "humidity" : 32.43, "coords" : { "latitude" : 47.615694, "longitude" : -122.3359976 }}

规则的输出内容如下：

{ "coords":{ "longitude":-122.3359976, "latitude":47.615694 }, "humidity":32.43, "temp":54.98, "deviceid":"iot123", "topic":"my/iot/topic"}

220

AWS IoT 开发人员指南Device Shadow 服务数据流

适用于 AWS IoT 的 Device Shadow服务

设备的影子是用于存储和检索设备的当前状态信息的 JSON 文档。Device Shadow 服务可以为您连接到AWS IoT 的每台设备保留一个影子。您可以使用该影子通过 MQTT 或 HTTP 获取和设置设备的状态，无论该设备是否连接到 Internet。每台设备的影子都由相应事物的名称唯一标识。

内容• Device Shadow 服务数据流 (p. 221)• Device Shadow 服务文档 (p. 228)• 使用影子 (p. 231)• Device Shadow RESTful API (p. 239)• 影子 MQTT 主题 (p. 242)• 影子文档语法 (p. 248)• 影子错误消息 (p. 250)

Device Shadow 服务数据流Device Shadow 服务充当中介，支持设备和应用程序检索和更新设备的影子。

为了说明设备和应用程序如何与 Device Shadow 服务进行通信，本节将介绍如何使用 AWS IoT MQTT 客户端和 AWS CLI 模拟连接了 Internet 的灯泡、应用程序和 Device Shadow 服务之间的通信。

Device Shadow 服务使用 MQTT 主题来促进应用程序和设备之间的通信。要了解相应运作方式，请使用AWS IoT MQTT 客户端订阅以下 QoS 1 级 MQTT 主题：

$aws/things/myLightBulb/shadow/update/accepted

当设备的影子更新成功时，Device Shadow 服务将向此主题发送消息。$aws/things/myLightBulb/shadow/update/rejected

当设备的影子更新遭拒时，Device Shadow 服务将向此主题发送消息。$aws/things/myLightBulb/shadow/update/delta

当检测到设备的影子的“reported”部分与“desired”部分之间存在差异时，Device Shadow 服务将向此主题发送消息。有关更多信息，请参阅 /update/delta (p. 244)。

$aws/things/myLightBulb/shadow/get/accepted

当获取设备的影子的请求获批时，Device Shadow 服务将向此主题发送消息。$aws/things/myLightBulb/shadow/get/rejected

当获取设备的影子的请求遭拒时，Device Shadow 服务将向此主题发送消息。$aws/things/myLightBulb/shadow/delete/accepted

当设备的影子被删除时，Device Shadow 服务将向此主题发送消息。$aws/things/myLightBulb/shadow/delete/rejected

当删除设备的影子的请求遭拒时，Device Shadow 服务将向此主题发送消息。

221


$aws/things/myLightBulb/shadow/update/documents

每次设备的影子更新成功执行时，Device Shadow 服务都会向此主题发布状态文档。

要了解有关 Device Shadow 服务使用的所有 MQTT 主题的更多信息，请参阅影子 MQTT 主题 (p. 242)。

Note

建议您订阅 .../rejected 主题，以查看 Device Shadow 服务发送的任何错误。

当灯泡联机时，它将向 $aws/things/myLightBulb/shadow/update 主题发送 MQTT 消息，告知Device Shadow 服务其当前状态。

要模拟这一过程，请使用 AWS IoT MQTT 客户端向 $aws/things/myLightbulb/shadow/update 主题发布以下消息：

{ "state": { "reported": { "color": "red" } }}

此消息将灯泡的颜色设为红色 (“red”)。

Device Shadow 服务通过向 $aws/things/myLightBulb/shadow/update/accepted 主题发送以下消息进行响应：

{ "messageNumber": 4, "payload": { "state": { "reported": { "color": "red" } }, "metadata": { "reported": { "color": { "timestamp": 1469564492 } } }, "version": 1, "timestamp": 1469564492 }, "qos": 0, "timestamp": 1469564492848, "topic": "$aws/things/myLightBulb/shadow/update/accepted"}

此消息表明 Device Shadow 服务已收到 UPDATE 请求并更新了设备的影子。如果事物影子不存在，Shadows 服务则将创建事物影子；如果存在，则将使用消息中的数据更新该影子。如果您发现没有任何消息发布至 $aws/things/myLightBulb/shadow/update/accepted，请查看 $aws/things/myLightBulb/shadow/update/rejected 订阅，了解该主题下是否有任何错误消息。

此外，Device Shadow 服务还会向 $aws/things/myLightBulb/shadow/update/documents 主题发布以下消息。

222


{ "previous":null, "current":{ "state":{ "reported":{ "color":"red" } }, "metadata":{ "reported":{ "color":{ "timestamp":1483467764 } } }, "version":1 }, "timestamp":1483467764}

每次设备的影子更新成功执行时，都会向 /update/documents 主题发布消息。有关发布到此主题的消息内容的更多信息，请参阅影子 MQTT 主题 (p. 242)。

与电灯泡交互的应用程序联机并请求获取电灯泡的当前状态。该应用程序将向 $aws/things/myLightBulb/shadow/get 主题发送一条空消息。要模拟这一过程，请使用 AWS IoT MQTT 客户端向$aws/things/myLightBulb/shadow/get 主题发布一条空消息 ("")。

Device Shadow 服务通过向 $aws/things/myLightBulb/shadow/get/accepted 主题发布请求获取的影子进行响应：

{ "messageNumber": 1, "payload": { "state": { "reported": { "color": "red" } }, "metadata": { "reported": { "color": { "timestamp": 1469564492 } } }, "version": 1, "timestamp": 1469564571 }, "qos": 0, "timestamp": 1469564571533, "topic": "$aws/things/myLightBulb/shadow/get/accepted"}

如果您在 $aws/things/myLightBulb/shadow/get/accepted 主题下没有看到任何消息，请查看$aws/things/myLightBulb/shadow/get/rejected 主题，了解该主题下是否有任何错误消息。

应用程序向用户显示此信息，用户请求更改电灯泡的颜色（将红色更改为绿色）。为此，该应用程序将向$aws/things/myLightBulb/shadow/update 主题发布消息：

{ "state": {

223


"desired": { "color": "green" } }}

要模拟这一过程，请使用 AWS IoT MQTT 客户端向 $aws/things/myLightBulb/shadow/update 主题发布之前的消息。

Device Shadow 服务通过向 $aws/things/myLightBulb/shadow/update/accepted 主题发送以下消息进行响应：

{ "messageNumber": 5, "payload": { "state": { "desired": { "color": "green" } }, "metadata": { "desired": { "color": { "timestamp": 1469564658 } } }, "version": 2, "timestamp": 1469564658 }, "qos": 0, "timestamp": 1469564658286, "topic": "$aws/things/myLightBulb/shadow/update/accepted"}

并向 $aws/things/myLightBulb/shadow/update/delta 主题发送以下消息进行响应：

{ "messageNumber": 1, "payload": { "version": 2, "timestamp": 1469564658, "state": { "color": "green" }, "metadata": { "color": { "timestamp": 1469564658 } } }, "qos": 0, "timestamp": 1469564658309, "topic": "$aws/things/myLightBulb/shadow/update/delta"}

当此主题接受影子更新并且生成的影子包含不同的预期状态和报告状态值时，Device Shadow 服务将向此主题发布消息。

Device Shadow 服务还会向 $aws/things/myLightBulb/shadow/update/documents 主题发布消息：

224


{ "previous":{ "state":{ "reported":{ "color":"red" } }, "metadata":{ "reported":{ "color":{ "timestamp":1483467764 } } }, "version":1 }, "current":{ "state":{ "desired":{ "color":"green" }, "reported":{ "color":"red" } }, "metadata":{ "desired":{ "color":{ "timestamp":1483468612 } }, "reported":{ "color":{ "timestamp":1483467764 } } }, "version":2 }, "timestamp":1483468612}

电灯泡已订阅 $aws/things/myLightBulb/shadow/update/delta 主题，因此可以接收到消息、更改其颜色并发布新状态。要模拟这一过程，请使用 AWS IoT MQTT 客户端向 $aws/things/myLightbulb/shadow/update 主题发布以下消息，以更新影子状态：

{ "state":{ "reported":{ "color":"green" }, "desired":null} }}

Device Shadow 服务通过向 $aws/things/myLightBulb/shadow/update/accepted 主题发送消息进行响应：

{ "messageNumber": 6, "payload": { "state": {

225


"reported": { "color": "green" }, "desired": null }, "metadata": { "reported": { "color": { "timestamp": 1469564801 } }, "desired": { "timestamp": 1469564801 } }, "version": 3, "timestamp": 1469564801 }, "qos": 0, "timestamp": 1469564801673, "topic": "$aws/things/myLightBulb/shadow/update/accepted"}

并向 $aws/things/myLightBulb/shadow/update/documents 主题发送以下消息进行响应：

{ "previous":{ "state":{ "reported":{ "color":"red" } }, "metadata":{ "reported":{ "color":{ "timestamp":1483470355 } } }, "version":3 }, "current":{ "state":{ "reported":{ "color":"green" } }, "metadata":{ "reported":{ "color":{ "timestamp":1483470364 } } }, "version":4 }, "timestamp":1483470364}

应用程序向 Device Shadow 服务请求获取当前状态并显示最新状态数据。要模拟这一过程，请运行以下命令：

aws iot-data get-thing-shadow --thing-name "myLightBulb" "output.txt" && cat "output.txt"

226

AWS IoT 开发人员指南检测事物是否已连接

Note

在 Windows 上，请忽略 && cat "output.txt" 命令，该命令用于向控制台显示 output.txt 内容。您可以在记事本或任何文本编辑器中打开该文件，以查看影子的内容。

Device Shadow 服务将返回影子文档：

{ "state":{ "reported":{ "color":"green" } }, "metadata":{ "reported":{ "color":{ "timestamp":1469564801 } } }, "version":3, "timestamp":1469564864}

要删除设备的影子，请将一条空消息发布到 $aws/things/myLightBulb/shadow/delete 主题。AWSIoT 通过向 $aws/things/myLightBulb/shadow/delete/accepted 主题发布消息来做出响应：

{ "version" : 1, "timestamp" : 1488565234}

检测事物是否已连接要确定设备当前是否已连接，请在影子中包含一个已连接设置，然后使用 MQTT Last Will and Testament(LWT) 消息，该消息会在设备由于错误而断开连接时将已连接设置设为 false。

Note

目前，AWS IoT Device Shadow 服务将忽略发送至 AWS IoT 预留主题 (以 $ 开头的主题) 的 LWT消息，但订阅的客户端和 AWS IoT 规则引擎仍会处理此类消息。如果您希望 Device Shadow 服务接收 LWT 消息，请将一条 LWT 消息注册为非预留主题，然后创建一条在预留的主题中重新发布消息的规则。以下示例将展示如何创建重新发布规则，以侦听 my/things/myLightBulb/update主题发布的消息并将其重新发布到 $aws/things/myLightBulb/shadow/update 主题。

{ "rule": { "ruleDisabled": false, "sql": "SELECT * FROM 'my/things/myLightBulb/update'", "description": "Turn my/things/ into $aws/things/", "actions": [{ "republish": { "topic": "$$aws/things/myLightBulb/shadow/update", "roleArn": "arn:aws:iam::123456789012:role/aws_iot_republish" } }] }}

当设备成功连接后，它将注册一条 LWT 消息并将已连接设置设为 false：

227

AWS IoT 开发人员指南Device Shadow 服务文档

{ "state": { "reported": { "connected":"false" } }}

它还会在其更新主题 ($aws/things/myLightBulb/shadow/update) 下发布一条消息，以将其连接状态设置为 true：

{ "state": { "reported": { "connected":"true" } }}

当设备正常断开连接时，它将在其更新主题下发布消息并将其连接状态设置为 false：

{ "state": { "reported":{ "connected":"false" } }}

如果设备由于错误而断开连接，其 LWT 消息将自动发布到更新主题。

Device Shadow 服务文档Device Shadow 服务遵守 JSON 规范下的所有规则。值、对象和数组均存储在设备的影子文档中。

内容• 文档属性 (p. 228)• Device Shadow 的版本控制 (p. 229)• 客户端令牌 (p. 229)• 示例文档 (p. 229)• 空白部分 (p. 230)• 数组 (p. 230)

文档属性设备的影子文档具有以下属性：

state

desired

事物的预期状态。应用程序可以向本文档部分写入数据来更新事物的状态，且无需直接连接到该事物。

228

AWS IoT 开发人员指南Device Shadow 的版本控制

reported

事物的报告状态。事物可以向本文档部分写入数据，以报告其新状态。应用程序可以读取本文档部分，以确定事物的状态。

metadata

有关存储在文档 state 部分的数据的信息，其中包括 state 部分中每个属性的时间戳（以 Epoch 时间表示），让您能够确定它们的更新时间。

timestamp

指明 AWS IoT 传输消息的时间。通过在消息中使用时间戳并对 desired 或 reported 部分中的不同属性使用时间戳，事物可以确定已更新项目的存在时间，即使它不具有内部时钟特性。

clientToken

特定于设备的字符串，让您能在 MQTT 环境中将响应与请求关联起来。version

文档版本。文档每次更新时，此版本号都会递增。用于确保正在更新的文档为最新版本。

有关更多信息，请参阅影子文档语法 (p. 248)。

Device Shadow 的版本控制Device Shadow 服务支持对每个更新消息 (包括请求和响应) 实施版本控制，这意味着，设备的影子每次更新时，JSON 文档的版本都会递增。这可以确保两件事情：

• 如果客户端尝试使用旧版本号覆盖影子，它将收到错误消息。客户端将被告知必须先进行重新同步，然后才能更新设备的影子。

• 如果消息的版本比客户端存储的版本低，客户端则可决定不对该消息执行操作。

在有些情况下，客户端可以通过不提交版本来绕过版本匹配。

客户端令牌收发基于 MQTT 的消息时，您可以使用客户端令牌，以验证请求和请求响应是否包含相同的客户端令牌。这可以确保响应与请求相互关联。

示例文档以下为示例影子文档：

{ "state" : { "desired" : { "color" : "RED", "sequence" : [ "RED", "GREEN", "BLUE" ] }, "reported" : { "color" : "GREEN" } }, "metadata" : { "desired" : { "color" : { "timestamp" : 12345 },

229

AWS IoT 开发人员指南空白部分

"sequence" : { "timestamp" : 12345 } }, "reported" : { "color" : { "timestamp" : 12345 } } }, "version" : 10, "clientToken" : "UniqueClientToken", "timestamp": 123456789}

空白部分仅当影子文档具有预期状态时，它才包含 desired 部分。例如，以下文档为没有 desired 部分的有效状态文档：

{ "reported" : { "temp": 55 }}

reported 部分也可以为空：

{ "desired" : { "color" : "RED" }}

如果更新导致 desired 或 reported 部分为空，则该部分将从文档中删除。要从文档中删除 desired 部分 (例如，对设备更新状态做出响应)，请将“desired”部分设置为 null：

{ "state": { "reported": { "color": "red" }, "desired": null } }

影子文档也有可能不包含 desired 或 reported 部分。在此情况下，影子文档将为空。例如，以下文档也是一个有效文档：

{}

数组影子支持数组，但将其视为正常值进行处理，因为对数组的更新将替换整个数组。无法更新数组的某个部分。

初始状态：

{ "desired" : { "colors" : ["RED", "GREEN", "BLUE" ] }

230

AWS IoT 开发人员指南使用影子

}

更新:

{ "desired" : { "colors" : ["RED"] }}

最终状态：

{ "desired" : { "colors" : ["RED"] }}

数组不能包含空值。例如，以下数组无效并将被拒绝。

{ "desired" : { "colors" : [ null, "RED", "GREEN" ] }}

使用影子AWS IoT 针对设备的影子提供了三项操作：

UPDATE

如果设备的影子不存在，则创建一个该影子；如果存在，则使用请求中提供的数据更新设备的影子的内容。存储数据时使用时间戳信息，以指明最新更新时间。向所有订阅者发送消息，告知 desired状态与 reported 状态之间的差异 (增量)。接收到消息的事物或应用程序可以根据 desired 状态和reported 状态之间的差异执行操作。例如，设备可将其状态更新为预期状态，或者应用程序可以更新其 UI，以反映设备状态的更改。

GET

检索设备的影子中存储的最新状态 (例如，在设备启动期间，检索配置和最新操作状态)。此操作将返回整个 JSON 文档，其中包括元数据。

DELETE

删除设备的影子，包括其所有内容。这将从数据存储中删除 JSON 文档。您无法还原已删除的设备的影子，但可以创建具有相同名称的新影子。

协议支持MQTT 和通过 HTTPS 的 RESTful API 都支持这些操作。由于 MQTT 是一种发布/订阅的通信模式，AWSIoT 将采用一组预留主题。为了实施请求 – 响应操作，事物或应用程序应先订阅这些主题，然后向请求主题发布消息。有关更多信息，请参阅影子 MQTT 主题 (p. 242) 和 Device Shadow RESTful API (p. 239)。

更新影子您可以通过使用 UpdateThingShadow (p. 240) RESTful API 或向 /更新 (p. 242) 主题发布消息来更新设备的影子。更新仅影响请求中指定的字段。

231

http://docs.oasis-open.org/mqtt/mqtt/v3.1.1/mqtt-v3.1.1.html

AWS IoT 开发人员指南检索影子文档

初始状态：

{ "state": { "reported" : { "color" : { "r" :255, "g": 255, "b": 0 } } }}

发送一条更新信息：

{ "state": { "desired" : { "color" : { "r" : 10 }, "engine" : "ON" } }}

设备收到由之前的 /update 消息触发的 desired 状态 (位于 /update/delta 主题下)，然后执行预期更改。结束后，设备应通过影子 JSON 文档中的 reported 部分确认其更新后的状态。

最终状态：

{ "state": { "reported" : { "color" : { "r" : 10, "g" : 255, "b": 0 }, "engine" : "ON" } }}

检索影子文档您可以通过使用 GetThingShadow (p. 240) RESTful API 或通过订阅和发布消息到 /get (p. 245) 主题来检索设备的影子。这将检索整个文档以及 desired 状态与 reported 状态之间的增量。

示例文档：

{ "state": { "desired": { "lights": { "color": "RED" }, "engine": "ON" }, "reported": { "lights": { "color": "GREEN" }, "engine": "ON" } }, "metadata": { "desired": {

232


"lights": { "color": { "timestamp": 123456 }, "engine": { "timestamp": 123456 } } }, "reported": { "lights": { "color": { "timestamp": 789012 } }, "engine": { "timestamp": 789012 } }, "version": 10, "timestamp": 123456789 }}

响应:

{ "state": { "desired": { "lights": { "color": "RED" }, "engine": "ON" }, "reported": { "lights": { "color": "GREEN" }, "engine": "ON" }, "delta": { "lights": { "color": "RED" } } }, "metadata": { "desired": { "lights": { "color": { "timestamp": 123456 }, } "engine": { "timestamp": 123456 } }, "reported": { "lights": { "color": { "timestamp": 789012 } }, "engine": { "timestamp": 789012

233


} }, "delta": { "lights": { "color": { "timestamp": 123456 } } } }, "version": 10, "timestamp": 123456789}

乐观锁您可以使用状态文档版本来确保正在更新的设备的影子文档为最新版本。当您为更新请求提供版本时，如果状态文档的当前版本与提供的版本不符，该服务将显示 HTTP 409 冲突响应代码并拒绝请求。

例如：

初始文档：

{ "state" : { "desired" : { "colors" : ["RED", "GREEN", "BLUE" ] } }, "version" : 10}

更新：（版本不匹配；请求将被拒绝）

{ "state": { "desired": { "colors": [ "BLUE" ] } }, "version": 9}

结果:

409 Conflict

更新：（版本匹配；请求将被接受）


234

AWS IoT 开发人员指南删除数据

最终状态：


删除数据您可以通过将消息发布到 /更新 (p. 242) 主题并将要删除的字段设置为空，从设备的影子中删除数据。值为null 的所有字段均将从文档中删除。

初始状态：

{ "state": { "desired" : { "lights": { "color": "RED" }, "engine" : "ON" }, "reported" : { "lights" : { "color": "GREEN" }, "engine" : "OFF" } }}

发送一条更新信息：

{ "state": { "desired": null, "reported": { "engine": null } }}

最终状态：

{ "state": { "reported" : { "lights" : { "color" : "GREEN" } } }}

您可以将设备的影子的状态设置为 null 来从中删除所有数据。例如，发送以下消息时将删除所有状态数据，但仍将保留设备的影子。

{

235

AWS IoT 开发人员指南删除影子

"state": null}

即使状态为 null，设备的影子仍然存在。在下次更新时，该影子的版本将递增。

删除影子您可以通过使用 DeleteThingShadow (p. 241) RESTful API 或向 /delete (p. 246) 主题发布消息来删除设备的影子文档。

Note

删除设备的影子不会删除事物。删除事物不会删除相应设备的影子。

初始状态：

{ "state": { "desired" : { "lights": { "color": "RED" }, "engine" : "ON" }, "reported" : { "lights" : { "color": "GREEN" }, "engine" : "OFF" } }}

在 /delete 主题下发布了空消息。

最终状态：

HTTP 404 - resource not found

增量状态增量状态是一种虚拟类型的状态，包含 desired 状态和 reported 状态之间的差异。对于 desired 部分中的字段，如果 reported 部分没有这些字段，则它们将包含在增量中。对于 reported 部分中的字段，如果 desired 部分没有这些字段，则它们不会包含在增量中。增量包含元数据，且其值与 desired 字段的元数据相同。例如：

{ "state": { "desired": { "color": "RED", "state": "STOP" }, "reported": { "color": "GREEN", "engine": "ON" }, "delta": { "color": "RED", "state": "STOP" } }, "metadata": { "desired": {

236

AWS IoT 开发人员指南增量状态

"color": { "timestamp": 12345 }, "state": { "timestamp": 12345 }, "reported": { "color": { "timestamp": 12345 }, "engine": { "timestamp": 12345 } }, "delta": { "color": { "timestamp": 12345 }, "state": { "timestamp": 12345 } } }, "version": 17, "timestamp": 123456789 }}

当嵌套对象不同时，增量将包含根路径。

{ "state": { "desired": { "lights": { "color": { "r": 255, "g": 255, "b": 255 } } }, "reported": { "lights": { "color": { "r": 255, "g": 0, "b": 255 } } }, "delta": { "lights": { "color": { "g": 255 } } } }, "version": 18, "timestamp": 123456789}

Device Shadow 服务通过循环访问 desired 状态中的每个字段并将其与 reported 状态进行比较来计算增量。

237

AWS IoT 开发人员指南观察状态更改

数组的处理方式与值类似。如果 desired 部分中的数组与 reported 部分中的数组不匹配，则整个预期数组将被复制到增量中。

观察状态更改设备的影子更新后，将在两个 MQTT 主题下发布消息：

• $aws/things/thing-name/shadow/update/accepted• $aws/things/thing-name/shadow/update/delta

发送到 update/delta 主题的消息将用于状态正在更新的事物。此消息仅包含设备的影子文档中 desired部分与 reported 部分之间的差异。在收到此消息后，设备应立即决定是否要执行请求的更改。如果设备的状态发生变化，它应向 $aws/things/thing-name/shadow/update 主题发布其当前最新状态。

设备和应用程序可以订阅任一主题，以便在文档状态更改后收到通知。

以下是该流程的示例：

1. 一台设备报告了自身的状态。2. 系统在其持久性数据存储中更新状态文档。3. 系统发布仅包含增量并面向订阅设备的增量消息。要接收更新，设备应订阅此主题。4. 设备的影子发布接受的消息，包括内含元数据的整个已接收文档。要接收更新，应用程序应订阅此主题。

消息顺序不保证 AWS IoT 服务发送的消息按任何特定顺序到达设备。

初始状态文档：

{ "state" : { "reported" : { "color" : "blue" } }, "version" : 10, "timestamp": 123456777}

更新 1：

{ "state": { "desired" : { "color" : "RED" } }, "version": 10, "timestamp": 123456777}

更新 2：

{ "state": { "desired" : { "color" : "GREEN" } }, "version": 11 , "timestamp": 123456778}

最终状态文档：

238

AWS IoT 开发人员指南修剪影子消息

{ "state": { "reported": { "color" : "GREEN" } }, "version": 12, "timestamp": 123456779}

这将产生两个增量消息：

{ "state": { "color": "RED" }, "version": 11, "timestamp": 123456778}

{ "state": { "color" : "GREEN" }, "version": 12, "timestamp": 123456779}

设备可能不会按次序收到这些消息。由于这些消息中的状态是累计的，设备可以安全地弃用版本号比正在追踪的版本号更早的所有消息。如果设备在接收版本 11 的增量之前收到版本 12 的增量，则可以安全地弃用版本 11 的消息。

修剪影子消息要降低发送到您的设备的影子消息的大小，请定义一项规则，以仅选择设备所需的字段然后将消息重新发布到设备正在侦听的 MQTT 主题。

规则应在 JSON 中指定，且应与以下内容类似：

{ "sql": "SELECT state, version FROM '$aws/things/+/shadow/update/delta'", "ruleDisabled": false, "actions": [{ "republish": { "topic": "${topic(2)}/delta", "roleArn": "arn:aws:iam::123456789012:role/my-iot-role" } }]}

SELECT 语句用于确定将消息中的哪些字段重新发布到指定的主题。“+”通配符用于匹配所有影子名称。该规则指定，应将所有匹配的消息重新发布到指定的主题。在此情况下，可以使用 "topic()" 函数指定将消息重新发布到哪个主题。topic(2) 用于评估原始主题中的事物名称。有关创建规则的更多信息，请参阅规则。

Device Shadow RESTful API影子将显示用于更新状态信息的以下 URI：

239

http://docs.aws.amazon.com/iot/latest/developerguide//iot-rules.html

http://docs.aws.amazon.com/iot/latest/developerguide//iot-rules.html

AWS IoT 开发人员指南GetThingShadow

https://endpoint/things/thingName/shadow

您的 AWS 账户具有特定的终端节点。要检索您的终端节点，请使用 describe-endpoint 命令。终端节点的格式如下：

identifier.iot.region.amazonaws.com

API 操作• GetThingShadow (p. 240)• UpdateThingShadow (p. 240)• DeleteThingShadow (p. 241)

GetThingShadow获取指定事物的影子。

响应状态文档包括 desired 状态与 reported 状态之间的增量。

请求

该请求包括标准的 HTTP 标头以及以下 URI：

HTTP GET https://endpoint/things/thingName/shadow

响应

请求成功后，响应将包括标准的 HTTP 标头以及以下代码和正文：

HTTP 200BODY: response state document

有关更多信息，请参阅响应状态文档示例 (p. 248)。

授权

要检索影子，需要一项允许发起人执行 iot:GetThingShadow 操作的策略。Device Shadow 服务接受两种形式的身份验证：使用 IAM 凭证的签名版本 4 或使用客户端证书的 TLS 双向身份验证。

以下是允许发起人检索设备的影子的示例策略：

{ "Version": "2012-10-17", "Statement": [{ "Effect": "Allow", "Action": "iot:GetThingShadow", "Resource": ["arn:aws:iot:region:account:thing/thing"] }]}

UpdateThingShadow更新指定事物的影子。

240

http://docs.aws.amazon.com/cli/latest/reference/iot/describe-endpoint.html

AWS IoT 开发人员指南DeleteThingShadow

更新仅影响请求状态文档中指定的字段。值为 null 的所有字段都会从设备的影子中删除。

请求

该请求包括标准的 HTTP 标头以及以下 URI 和正文：

HTTP POST https://endpoint/things/thingName/shadowBODY: request state document

有关更多信息，请参阅请求状态文档示例 (p. 248)。

响应


HTTP 200BODY: response state document

有关更多信息，请参阅响应状态文档示例 (p. 248)。

授权

要更新影子，需要一项允许发起人执行 iot:UpdateThingShadow 操作的策略。Device Shadow 服务接受两种形式的身份验证：使用 IAM 凭证的签名版本 4 或使用客户端证书的 TLS 双向身份验证。

以下是允许发起人更新设备的影子的示例策略：

{ "Version": "2012-10-17", "Statement": [{ "Effect": "Allow", "Action": "iot:UpdateThingShadow", "Resource": ["arn:aws:iot:region:account:thing/thing"] }]}

DeleteThingShadow删除指定事物的影子。

请求

该请求包括标准的 HTTP 标头以及以下 URI：

HTTP DELETE https://endpoint/things/thingName/shadow

响应


HTTP 200BODY: Empty response state document

授权

要删除设备的影子，需要一项允许发起人执行 iot:DeleteThingShadow 操作的策略。Device Shadow 服务接受两种形式的身份验证：使用 IAM 凭证的签名版本 4 或使用客户端证书的 TLS 双向身份验证。

241

AWS IoT 开发人员指南MQTT 发布/订阅主题

以下是允许发起人删除设备的影子的示例策略：

{ "Version": "2012-10-17", "Statement": [{ "Effect": "Allow", "Action": "iot:DeleteThingShadow", "Resource": ["arn:aws:iot:region:account:thing/thing"] }]}

影子 MQTT 主题Device Shadow 服务使用预留的 MQTT 主题，使应用程序和设备获取、更新或删除设备 (影子) 的状态信息。这些主题的名称以 $aws/things/thingName/shadow 开头。要订阅影子主题并向该主题发布消息，需要获得基于主题的授权。AWS IoT 保留向现有主题结构添加新主题的权利。为此，建议您订阅影子主题时勿使用通配符。例如，请勿在订阅时使用诸如 $aws/things/thingName/shadow/# 的主题筛选条件，因为与该主题筛选条件匹配的主题数量可能会随着 AWS IoT 引入新的影子主题而增加。要了解针对这些主题发布的消息示例，请查看 Device Shadow 服务数据流 (p. 221)。

以下是用于与影子交互的 MQTT 主题。

主题：• /更新 (p. 242)• /update/accepted (p. 243)• /update/documents (p. 243)• /update/rejected (p. 244)• /update/delta (p. 244)• /get (p. 245)• /get/accepted (p. 245)• /get/rejected (p. 246)• /delete (p. 246)• /delete/accepted (p. 247)• /delete/rejected (p. 247)

/更新向此主题发布请求状态文档来更新设备的影子：

$aws/things/thingName/shadow/update

尝试更新事物状态的客户端会发送类似如下的 JSON 请求状态文档：

{ "state" : { "desired" : { "color" : "red", "power" : "on" } }}

242

AWS IoT 开发人员指南/update/accepted

更新其影子的设备会发送类似于下面的 JSON 请求状态文档：

{ "state" : { "reported" : { "color" : "red", "power" : "on" } }}

AWS IoT 通过向 /update/accepted (p. 243) 或 /update/rejected (p. 244) 发布消息来进行响应。

有关更多信息，请参阅请求状态文档 (p. 248)。

示例策略以下是所需策略的示例：

{ "Version": "2012-10-17", "Statement": [{ "Effect": "Allow", "Action": ["iot:Publish"], "Resource": ["arn:aws:iot:region:account:topic/$aws/things/thingName/shadow/update"] }]}

/update/acceptedAWS IoT 在接受设备的影子的更改时向此主题发布响应状态文档：

$aws/things/thingName/shadow/update/accepted

有关更多信息，请参阅响应状态文档 (p. 248)。


{ "Version": "2012-10-17", "Statement": [{ "Effect": "Allow", "Action": [ "iot:Subscribe", "iot:Receive" ], "Resource": ["arn:aws:iot:region:account:topicfilter/$aws/things/thingName/shadow/update/accepted"] }]}

/update/documents每次影子更新成功执行时，AWS IoT 都会向该主题发布状态文档：

243

AWS IoT 开发人员指南/update/rejected

$aws/things/thingName/shadow/update/documents

JSON 文档包含两个主要节点：previous 和 current。previous 节点包含执行更新之前完整影子文档的内容，而 current 节点则包含成功更新之后完整影子文档的内容。首次更新 (创建) 影子时，previous 节点将包含 null。


{ "Version": "2012-10-17", "Statement": [{ "Effect": "Allow", "Action": [ "iot:Subscribe", "iot:Receive" ], "Resource": ["arn:aws:iot:region:account:topicfilter/$aws/things/thingName/shadow/update/documents"] }]}

/update/rejectedAWS IoT 在拒绝设备的影子的更改时向此主题发布错误响应文档：

$aws/things/thingName/shadow/update/rejected

有关更多信息，请参阅错误响应文档 (p. 249)。


{ "Version": "2012-10-17", "Statement": [{ "Effect": "Allow", "Action": [ "iot:Subscribe", "iot:Receive" ], "Resource": ["arn:aws:iot:region:account:topicfilter/$aws/things/thingName/shadow/update/rejected"] }]}

/update/deltaAWS IoT 在接受设备的影子的更改时向此主题发布响应状态文档，且请求状态文档包含不同的 desired 状态值和 reported 状态值：

$aws/things/thingName/shadow/update/delta

244

AWS IoT 开发人员指南/get


发布详情• 发布到 update/delta 的消息仅包括 desired 部分和 reported 部分之间有所不同的预期属性。它将

包含所有此类属性，无论这些属性包含在当前更新消息中还是已存储在 AWS IoT 中。desired 部分和reported 部分之间相同的属性则不包含在内。

• 如果某个属性位于 reported 部分，但在 desired 部分没有等效值，则不会包含在内。• 如果某个属性位于 desired 部分，但在 reported 部分没有等效值，则将包含在内。• 如果某个属性已从 reported 部分删除，但仍存在于 desired 部分，则将包含在内。


{ "Version": "2012-10-17", "Statement": [{ "Effect": "Allow", "Action": [ "iot:Subscribe", "iot:Receive" ], "Resource": ["arn:aws:iot:region:account:topicfilter/$aws/things/thingName/shadow/update/delta"] }]}

/get要获得设备的影子，请在此主题下发布一条空消息：

$aws/things/thingName/shadow/get

AWS IoT 通过向 /get/accepted (p. 245) 或 /get/rejected (p. 246) 发布消息来进行响应。


{ "Version": "2012-10-17", "Statement": [{ "Effect": "Allow", "Action": [ "iot:Publish" ], "Resource": ["arn:aws:iot:region:account:topic/$aws/things/thingName/shadow/get"] }]}

/get/acceptedAWS IoT 在返回设备的影子时向此主题发布响应状态文档：

245

AWS IoT 开发人员指南/get/rejected

$aws/things/thingName/shadow/get/accepted



{ "Version": "2012-10-17", "Statement": [{ "Effect": "Allow", "Action": [ "iot:Subscribe", "iot:Receive" ], "Resource": ["arn:aws:iot:region:account:topicfilter/$aws/things/thingName/shadow/get/accepted"] }]}

/get/rejectedAWS IoT 在无法返回设备的影子时向此主题发布错误响应文档：

$aws/things/thingName/shadow/get/rejected



{ "Version": "2012-10-17", "Statement": [{ "Action": [ "iot:Subscribe", "iot:Receive" ], "Resource": ["arn:aws:iot:region:account:topicfilter/$aws/things/thingName/shadow/get/rejected"] }]}

/delete要删除设备的影子，请将一条空消息发布到删除主题：

$aws/things/thingName/shadow/delete

消息内容将被忽略。

AWS IoT 通过向 /delete/accepted (p. 247) 或 /delete/rejected (p. 247) 发布消息来进行响应。

246

AWS IoT 开发人员指南/delete/accepted


{ "Version": "2012-10-17", "Statement": [{ "Effect": "Allow", "Action": [ "iot:Subscribe", "iot:Receive" ], "Resource": ["arn:aws:iot:region:account:topic filter/$aws/things/thingName/shadow/delete"] }]}

/delete/acceptedAWS IoT 在删除设备的影子时在此主题下发布消息：

$aws/things/thingName/shadow/delete/accepted


{ "Version": "2012-10-17", "Statement": [{ "Effect": "Allow", "Action": [ "iot:Subscribe", "iot:Receive" ], "Resource": ["arn:aws:iot:region:account:topicfilter/$aws/things/thingName/shadow/delete/accepted"] }]}

/delete/rejectedAWS IoT 在无法删除设备的影子时向此主题发布错误响应文档：

$aws/things/thingName/shadow/delete/rejected



{ "Version": "2012-10-17", "Statement": [{ "Effect": "Allow",

247

AWS IoT 开发人员指南文档语法

"Action": [ "iot:Subscribe", "iot:Receive" ], "Resource": ["arn:aws:iot:region:account:topicfilter/$aws/things/thingName/shadow/delete/rejected"] }]}

影子文档语法在使用 RESTful API (p. 239) 或 MQTT 发布/订阅消息 (p. 242)的 UPDATE、GET 和 DELETE 操作中，Device Shadow 服务使用以下文档。有关更多信息，请参阅 Device Shadow 服务文档 (p. 228)。

示例• 请求状态文档 (p. 248)• 响应状态文档 (p. 248)• 错误响应文档 (p. 249)

请求状态文档请求状态文档具有以下格式：

{ "state": { "desired": { "attribute1": integer2, "attribute2": "string2", ... "attributeN": boolean2 }, "reported": { "attribute1": integer1, "attribute2": "string1", ... "attributeN": boolean1 } } "clientToken": "token", "version": version}

• state – 更新仅影响指定字段。• clientToken – 如果使用，您可以验证请求和响应是否包含相同的客户端令牌。• version - 如果使用，仅当指定的版本与 Device Shadow 服务拥有的最新版本相符时，该服务才会处理更

新。

响应状态文档响应状态文档具有以下格式：

{ "state": {

248

AWS IoT 开发人员指南错误响应文档

"desired": { "attribute1": integer2, "attribute2": "string2", ... "attributeN": boolean2 }, "reported": { "attribute1": integer1, "attribute2": "string1", ... "attributeN": boolean1 }, "delta": { "attribute3": integerX, "attribute5": "stringY" } }, "metadata": { "desired": { "attribute1": { "timestamp": timestamp }, "attribute2": { "timestamp": timestamp }, ... "attributeN": { "timestamp": timestamp } }, "reported": { "attribute1": { "timestamp": timestamp }, "attribute2": { "timestamp": timestamp }, ... "attributeN": { "timestamp": timestamp } } }, "timestamp": timestamp, "clientToken": "token", "version": version}

• state

• reported – 仅当事物报告了 reported 部分的任何数据时存在，且仅包含请求状态文档中的字段。• desired – 仅当事物报告了 desired 部分的任何数据时存在，且仅包含请求状态文档中的字段。

• metadata – 包含 desired 和 reported 部分中每个属性的时间戳，因此，您可以确定状态的更新时间。

• timestamp – AWS IoT 生成响应时的 Epoch 日期和时间。• clientToken — 仅当客户端令牌用于向 /update 主题发布有效 JSON 时存在。• version – AWS IoT 中共享的设备影子文档的当前版本。它将在文档先前版本号的基础上增加一个数。

错误响应文档错误响应文档具有以下格式：

249

AWS IoT 开发人员指南错误消息

{ "code": error-code, "message": "error-message", "timestamp": timestamp, "clientToken": "token"}

• code – 用于表明错误类型的 HTTP 响应代码。• message – 用于提供额外信息的文本消息。• timestamp – AWS IoT 生成响应时的日期和时间。• clientToken — 仅当客户端令牌用于向 /update 主题发布有效 JSON 时存在。

有关更多信息，请参阅影子错误消息 (p. 250)。

影子错误消息Device Shadow 服务在尝试更改状态文档失败时向错误主题发布消息 (通过 MQTT)。此消息仅将作为对发布到其中一个预留 $aws 主题的请求的响应。如果客户端使用 REST API 来更新文档，则客户端将收到作为响应一部分的 HTTP 错误代码，且不会发送任何 MQTT 错误消息。

HTTP 错误代码错误消息

400（错误请求） • JSON 无效• 必需节点缺失：状态• 状态节点必须是对象• 预期节点必须是对象• 报告节点必须是对象• 版本无效• clientToken 无效• JSON 包含的嵌套层级过多；最多嵌套 6 个层级• 状态包含无效节点

401（未授权） • 未授权

403（禁止访问） • 禁止

404（未找到） • 事物未找到

409（冲突） • 版本冲突

413（有效负载过大） • 有效负载超出允许的最大值

415（媒体类型不受支持） • 文档编码不受支持；受支持的编码是 UTF-8

429（请求过多） • 如果正在传输的请求超过 10 个，则 Device Shadow 服务将生成此条错误消息。

500（内部服务器错误） • 内部服务故障

250

AWS IoT 开发人员指南Jobs 关键概念

工作AWS IoT Jobs 是一项服务，允许您定义一组远程操作，这些操作将发送到连接至 AWS IoT 的一台或多台设备并在这些设备上执行。

Jobs 关键概念任务

任务是发送到一台或多台连接到 AWS IoT 的设备并在这些设备上执行的操作。例如，您可以定义一个任务，该任务指示一组设备下载并安装应用程序或固件更新、重启、轮换证书或执行远程故障排除操作。

任务文档

要创建任务，您必须先创建一个任务文档，该文档是要由设备执行的远程操作的描述。

任务文档是 UTF-8 编码的 JSON 文档，应包含您的设备执行任务所需的任何信息。任务文档最有可能包含一个或多个 URL，设备可从这些 URL 下载更新或其他数据。任务文档本身可存储在 Amazon S3 存储桶中，或者与用于创建任务的命令内联包含。

target

在创建任务时，您需要指定一系列目标，它们是应执行操作的设备。目标可以是事物和/或事物组 (p. 97)。AWS IoT Jobs 会向每个目标发送一条消息以向该目标告知任务可用。

任务执行

任务执行是目标设备上的任务的实例。目标通过下载任务文档来开始执行任务。目标随后会执行文档指定的操作并将其进度报告给 AWS IoT。执行编号是特定目标上的特定任务执行的唯一标识符。Jobs 服务提供的命令可跟踪特定目标上的任务执行的进度以及某个任务在其所有目标中的执行的整体进度。

快照任务

默认情况下，任务将发送到您在创建该任务时指定的所有目标。在这些目标完成任务 (或报告它们无法执行此操作) 后，任务即完成。这是一个快照任务。

持续任务

持续任务会持续运行，在目标中检测到更改时即执行。例如，当代表设备的某个事物添加到目标组时，会在该设备上运行任务，即使是组中原有的全部事物已经完成了任务。在将设备添加到组时，可使用持续任务加入或升级设备。您可以通过在创建任务时设置可选参数，来使任务成为持续任务。

部署

在创建任务时，您可以指定向目标发送待处理任务执行通知的速度。这样，您就可以创建一个分段部署以更好地管理更新、重启和其他操作。

可将以下字段添加到 CreateJob 请求以指定每分钟向其通知任务的最大目标数：

"jobExecutionRolloutConfig": { "maximumPerMinute": "integer" }

预签名 URL

要使设备能够对任务文档本身包含的数据之外的其他数据进行限定时间的安全访问，您可以使用预签名Amazon S3 URL。您可以将数据放置在 Amazon S3 存储桶中，并添加一个指向任务文档中的数据的占位符链接。当 Jobs 服务收到任务文档的请求时，它会分析任务文档以查找占位符链接并将其替换为预签名 Amazon S3 URL。

251

AWS IoT 开发人员指南管理任务

占位符链接采用以下形式：

${aws:iot:s3-presigned-url:https://s3.amazonaws.com/bucket/key}

其中 bucket 是您的存储桶名称，key 是您链接到的存储桶中的对象。

管理任务Jobs 是使用 Jobs HTTPS API、AWS Command Line Interface 或 AWS 开发工具包创建和管理的。有关这些工具的更多信息，请参阅任务管理和控制 API (p. 266)、AWS CLI 命令参考：iot 或 AWS 开发工具包和工具。

创建任务CreateJob

可使用 CreateJob 命令创建任务。任务将进行排队以便在您指定的目标 (事物或事物组) 上执行。要创建任务，您需要一个任务文档，该文档可包含在请求的正文中或作为指向 Amazon S3 文档的链接。如果任务包含使用预签名 Amazon S3 URL 下载文件，则您需要一个 IAM 角色 ARN，它具有下载文件的权限并会向 AWS IoT 授予代入角色的权限。

更多信息 (1)

如果您有一个存储在名为 jobBucket 的 Amazon S3 存储桶中的名为 job-document.json 的文件，并且具有从 Amazon S3 下载文件的权限的角色名为 S3DownloadRole，则用于创建任务的 CLI 命令将类似于以下内容：

aws iot create-job \ --job-id 010 \ --targets arn:aws:iot:us-east-1:123456789012:thing/thingOne \ --document-source https://s3.amazonaws.com/jobBucket/job-document.json \ --presigned-url-config "{\"roleArn\":\"arn:aws:iam::123456789012:role/S3DownloadRole\", \"expiresInSec\":3600}"

如果您需要指定内联任务文档，可使用 --document 参数而非 --document-source 参数。

将按任务在 --targets 列表中的显示顺序发送任务并在目标上执行任务。例如，如果目标列表为：

[ arn:aws:iot:us-east-1:123456789012:thing/thingOne, arn:aws:iot:us-east-1:123456789012:thinggroup/thinggroupOne, arn:aws:iot:us-east-1:123456789012:thing/thingTwo, arn:aws:iot:us-east-1:123456789012:thinggroup/thinggroupTwo ]

则将在 thingOne 上执行任务，随后依次在 thinggroupOne 中的事物、thingTwo 和thinggroupTwo 中的事物上执行。

Note

在您创建任务时将检索指定为 Amazon S3 文件的任务文档。在创建任务后，更改用作任务文档源的 Amazon S3 文件的内容时不会更改发送到任务目标的内容。

授予权限

在创建使用预签名 Amazon S3 URL 的任务时，您必须提供一个 IAM 角色 ARN 来授予从存储数据或更新的 Amazon S3 存储桶中下载文件的权限。该角色还必须向 AWS IoT 授予代入角色的权限。

要向 Jobs 授予代入角色的权限，请执行以下操作：

1. 登录 AWS 管理控制台并通过以下网址打开 IAM 控制台 https://console.aws.amazon.com/iam/。

252




https://console.aws.amazon.com/iam/

AWS IoT 开发人员指南取消任务

2. 在左侧导航窗格中，选择 Roles。3. 搜索您的角色，然后选择它。4. 选择 Trust Relationships 选项卡。5. 选择编辑信任关系按钮。6. 在编辑信任关系页面上，将策略文档替换为以下 JSON：

{ "Version": "2012-10-17", "Statement": [ { "Sid": "", "Effect": "Allow", "Principal": { "Service": [ "iot.amazonaws.com" ] }, "Action": "sts:AssumeRole" } ]}

7. 选择 Update Trust Policy

您可以选择性地指定预签名 URL 的超时值。有关更多信息，请参阅 CreateJob (p. 275)。

取消任务CancelJob

可使用 CancelJob 命令取消任务。取消任务将使 AWS IoT 停止为任务部署任何新的任务执行。这还将取消处于 QUEUED 状态的任何任务执行。IoT 会将任何任务执行保留为 IN_PROGRESS 状态或将最终状态保持不变，因为设备已在执行任务或已完成任务。

更多信息 (2)

aws iot cancel-job --job-id 010

该命令不显示任何输出。

将取消处于 QUEUED 状态的任务执行，而不会取消处于 IN_PROGRESS 或最终状态的任务执行。已取消任务或其某个任务执行的状态最终是一致的 - IoT 将停止计划新的任务执行，并且不会尽快将该任务的QUEUED 任务执行提供给设备。不过，将任务执行的状态更改为 CANCELED 可能需要一些时间，具体取决于设备数和其他因素。

获取任务文档GetJobDocument

可使用 GetJobDocument 命令检索任务的任务文档。更多信息 (3)

aws iot get-job-document --job-id 010

253

AWS IoT 开发人员指南列出任务

该命令返回指定任务的任务文档：

{ "document": "{\n\t\"operation\":\"install\",\n\t\"url\":\"http://amazon.com/firmWareUpate-01\",\n\t\"data\":\"${aws:iot:s3-presigned-url:https://s3.amazonaws.com/job-test-bucket/datafile}\"\n}"}

Note

在使用此命令检索任务文档时，所有占位符 URL 都不会替换为预签名 Amazon S3 URL。占位符 URL 将替换为在设备调用 GetPendingJobExecutions (p. 300) MQTT API 时返回的任务文档中的预签名 Amazon S3 URL。

列出任务ListJobs

可使用 ListJobs 命令获取 AWS 账户中的所有任务的列表。请注意，任务数据和任务执行数据将在 90天后被清除。

更多信息 (4)

aws iot list-jobs

该命令将列出您账户中按任务状态排序的所有任务：

{ "jobs": [ { "status": "IN_PROGRESS", "lastUpdatedAt": 1486687079.743, "jobArn": "arn:aws:iot:us-east-1:123456789012:job/013", "createdAt": 1486687079.743, "targetSelection": "SNAPSHOT", "jobId": "013" }, { "status": "COMPLETED", "lastUpdatedAt": 1486685868.444, "jobArn": "arn:aws:iot:us-east-1:123456789012:job/012", "createdAt": 1486685868.444, "completedAt": 148668789.690, "targetSelection": "SNAPSHOT", "jobId": "012" }, { "status": "CANCELED", "lastUpdatedAt": 1486678850.575, "jobArn": "arn:aws:iot:us-east-1:123456789012:job/011", "createdAt": 1486678850.575, "targetSelection": "SNAPSHOT", "jobId": "011" } ]}

254

AWS IoT 开发人员指南描述任务

描述任务DescribeJob

可使用 DescribeJob 命令获取特定任务的状态。更多信息 (5)

$ aws iot describe-job --job-id 010

该命令返回指定任务的状态：

{ "documentSource": "https://s3.amazonaws.com/job-test-bucket/job-document.json", "job": { "status": "IN_PROGRESS", "jobArn": "arn:aws:iot:us-east-1:123456789012:job/010", "targets": [ "arn:aws:iot:us-east-1:123456789012:thing/myThing" ], "jobProcessDetails": { "numberOfCanceledThings": 0, "numberOfFailedThings": 0, "numberOfInProgressThings": 0, "numberOfQueuedThings": 0, "numberOfRejectedThings": 0, "numberOfRemovedThings": 0, "numberOfSucceededThings": 0, "processingTargets": [ arn:aws:iot:us-east-1:123456789012:thing/thingOne, arn:aws:iot:us-east-1:123456789012:thinggroup/thinggroupOne, arn:aws:iot:us-east-1:123456789012:thing/thingTwo, arn:aws:iot:us-east-1:123456789012:thinggroup/thinggroupTwo ] }, "presignedUrlConfig": { "expiresInSec": 60, "roleArn": "arn:aws:iam::123456789012:role/S3DownloadRole" }, "jobId": "010", "lastUpdatedAt": 1486593195.006, "createdAt": 1486593195.006, "targetSelection": "SNAPSHOT" }}

列出任务的执行ListJobExecutionsForJob

在特定设备上运行的任务由任务执行对象表示。可使用 ListJobExecutionsForJob 命令列出任务的所有任务执行。

更多信息 (6)

aws iot list-job-executions-for-job --job-id 010

该命令将返回任务执行的列表：

255

AWS IoT 开发人员指南列出事物的任务执行

{ "executionSummaries": [ { "thingArn": "arn:aws:iot:us-east-1:123456789012:thing/thingOne", "jobExecutionSummary": { "status": "QUEUED", "lastUpdatedAt": 1486593196.378, "queuedAt": 1486593196.378, "executionNumber": 1234567890 } }, { "thingArn": "arn:aws:iot:us-east-1:123456789012:thing/thingTwo", "jobExecutionSummary": { "status": "IN_PROGRESS", "lastUpdatedAt": 1486593345.659, "queuedAt": 1486593196.378, "startedAt": 1486593345.659, "executionNumber": 4567890123 } } ]}

列出事物的任务执行ListJobExecutionsForThing

可使用 ListJobExecutionsForThing 命令列出正在事物上运行的所有任务执行。更多信息 (7)

aws iot list-job-executions-for-thing --thing-name thingOne

该命令将返回正在指定事物上运行的或在指定事物上运行过的任务执行的列表：

{ "executionSummaries": [ { "jobExecutionSummary": { "status": "QUEUED", "lastUpdatedAt": 1486687082.071, "queuedAt": 1486687082.071, "executionNumber": 9876543210 }, "jobId": "013" }, { "jobExecutionSummary": { "status": "IN_PROCESS", "startAt": 1486685870.729, "lastUpdatedAt": 1486685870.729, "queuedAt": 1486685870.729, "executionNumber": 1357924680 }, "jobId": "012" }, { "jobExecutionSummary": { "status": "COMPLETED", "startAt": 1486678853.415,

256

AWS IoT 开发人员指南描述任务执行

"lastUpdatedAt": 1486678853.415, "queuedAt": 1486678853.415, "executionNumber": 4357680912 }, "jobId": "011" }, { "jobExecutionSummary": { "status": "CANCELED", "startAt": 1486593196.378, "lastUpdatedAt": 1486593196.378, "queuedAt": 1486593196.378, "executionNumber": 2143174250 }, "jobId": "010" } ]}

描述任务执行DescribeJobExecution

可使用 DescribeJobExecution 命令获取特定任务执行的状态。您可以指定任务 ID 和事物名称 (也可以选择指定执行编号) 来标识任务执行。

任务的执行状态必须为 QUEUED 或 IN_PROGRESS。更多信息 (8)

aws iot describe-job-execution --job-id 017 --thing-name thingOne

该命令将返回 JobExecution (p. 269)：

{ "execution": { "jobId": "017", "executionNumber": 4516820379, "thingArn": "arn:aws:iot:us-east-1:123456789012:thing/thingOne", "createdAt": 1489084805.285, "lastUpdatedAt": 1489086279.937, "startedAt": 1489086279.937, "status": "IN_PROGRESS", "statusDetails": { "status": "IN_PROGRESS", "detailsMap": { "percentComplete": "10" } } }}

任务事件当任务待处理、已完成或已取消时，或者当设备在执行任务时报告成功或失败时，Jobs 还将发布到 MQTT协议上的预留主题。设备或管理和监控应用程序可以通过订阅这些主题来跟踪任务的状态。

有关发布和订阅 MQTT 主题的更多信息，请参阅AWS IoT 的消息代理 (p. 147)

257

AWS IoT 开发人员指南任务事件

任务待处理

当某个事物的待处理任务执行列表中添加或删除了任务时，或者对列表中任务的顺序有更改时，AWSIoT Jobs 会在 MQTT 主题上发布消息：

• $aws/things/thingName/jobs/notify

• $aws/things/thingName/jobs/notify-next

更多信息 (9)

消息包含以下示例负载：

$aws/things/thingName/jobs/notify：

{ "jobs" : { "JobExecutionState": [ JobExecutionSummary (p. 270) ... ], }, "timestamp": timestamp,}

$aws/things/thingName/jobs/notify-next：

{ "execution" : JobExecutionData (p. 297), "timestamp": timestamp,}

任务已完成/已取消

当任务已完成或已取消时，AWS IoT Jobs 会在 MQTT 主题上发布消息：

• $aws/events/job/jobID/completed

• $aws/events/job/jobID/canceled

更多信息 (10)

“已完成”消息包含以下示例负载：

{ "eventType": "JOB", "eventId": "7364ffd1-8b65-4824-85d5-6c14686c97c6", "timestamp": 1234567890, "operation": "completed", "jobId": "27450507-bf6f-4012-92af-bb8a1c8c4484", "status": "COMPLETED", "targetSelection": "SNAPSHOT|CONTINUOUS", "targets": [ "arn:aws:iot:us-east-1:123456789012:thing/a39f6f91-70cf-4bd2-a381-9c66df1a80d0", "arn:aws:iot:us-east-1:123456789012:thinggroup/2fc4c0a4-6e45-4525-a238-0fe8d3dd21bb" ], "description": "My Job Description", "completedAt": 1234567890123, "createdAt": 1234567890123, "lastUpdatedAt": 1234567890123, "jobProcessDetails": {

258


"numberOfCanceledThings": 0, "numberOfRejectedThings": 0, "numberOfFailedThings": 0, "numberOfRemovedThings": 0, "numberOfSucceededThings": 3 }}

“已取消”消息包含以下示例负载：

{ "eventType": "JOB", "eventId": "568d2ade-2e9c-46e6-a115-18afa1286b06", "timestamp": 1234567890, "operation": "canceled", "jobId": "4d2a531a-da2e-47bb-8b9e-ff5adcd53ef0", "status": "CANCELED", "targetSelection": "SNAPSHOT|CONTINUOUS", "targets": [ "arn:aws:iot:us-east-1:123456789012:thing/Thing0-947b9c0c-ff10-4a80-b4b3-cd33d0145a0f", "arn:aws:iot:us-east-1:123456789012:thinggroup/ThingGroup1-95c644d5-1621-41a6-9aa5-ad2de581d18f" ], "description": "My job description", "createdAt": 1234567890123, "lastUpdatedAt": 1234567890123}

任务执行最终状态

当设备将任务执行更新为最终状态时，AWS IoT Jobs 会发布消息：

• $aws/events/jobExecution/jobID/succeeded

• $aws/events/jobExecution/jobID/failed

• $aws/events/jobExecution/jobID/rejected

• $aws/events/jobExecution/jobID/canceled

• $aws/events/jobExecution/jobID/removed

或者，您也可以使用以下命令订阅所有这些项：

• $aws/events/jobExecution/jobID/#

更多信息 (11)


{ "eventType": "JOB_EXECUTION", "eventId": "cca89fa5-8a7f-4ced-8c20-5e653afb3572", "timestamp": 1234567890, "operation": "succeeded|failed|rejected|canceled|removed", "jobId": "154b39e5-60b0-48a4-9b73-f6f8dd032d27", "thingArn": "arn:aws:iot:us-east-1:123456789012:myThing/6d639fbc-8f85-4a90-924d-a2867f8366a7", "status": "SUCCEEDED|FAILED|REJECTED|CANCELED|REMOVED", "statusDetails": { "key": "value"

259

AWS IoT 开发人员指南设备和任务

}}

设备和任务设备与 Jobs 的通信

设备可通过以下三种方法之一与 Jobs 进行通信：

• MQTT• HTTP SigV4• HTTP TLS

使用 MQTT 协议

Jobs 服务和设备之间的通信可通过 MQTT 协议进行。设备将订阅 MQTT 主题，以便获得新任务通知和接收来自 Jobs 服务的响应。设备在 MQTT 主题上发布以查询或更新任务执行的状态。每台设备都有自己的一般 MQTT 主题。有关发布和订阅 MQTT 主题的更多信息，请参阅AWS IoT 的消息代理 (p. 147)

Note

您在通过 MQTT 与 Jobs 进行通信时必须使用正确的终端节点。要查找该终端节点，请使用DescribeEndpoint 命令。例如，使用以下 CLI：

aws iot describe-endpoint --endpoint-type iot:Data

您将获得一个类似于下面的结果：

{ "endpointAddress": "a1b2c3d4e5f6g7.iot.us-west-2.amazonaws.com"}

利用此方法，您的设备可使用其特定于设备的证书和私有密钥对 Jobs 服务进行身份验证。

设备可以：

• 在某个设备的待处理任务执行列表中添加或删除任务执行时收到通知，方式是通过订阅 $aws/things/thing-name/jobs/notify MQTT 主题，其中 thing-name 是与设备关联的事物的名称。

• 在下一个待处理任务执行发生更改时收到通知，方式是通过订阅 $aws/things/thing-name/jobs/notify-next MQTT 主题，其中 thing-name 是与设备关联的事物的名称。

• 通过调用 UpdateJobExecution (p. 312) API 来更新任务执行的状态。• 通过调用 DescribeJobExecution (p. 308) API 来查询任务执行的状态。• 通过调用 GetPendingJobExecutions (p. 300) API 来检索待处理任务执行的列表。• 通过使用 jobId $next 调用 DescribeJobExecution (p. 308) API 来检索下一个待处理任务执行。• 通过调用 StartNextPendingJobExecution (p. 303) API 来获取和开始下一个待处理任务执行。

Jobs 服务通过将 accepted 或 rejected 追加到用于发出请求的主题，在 MQTT 主题上发布成功和失败消息。例如，如果在 $aws/things/myThing/jobs/get 主题上发布请求消息，则 Jobs 服务将在 $aws/things/myThing/jobs/get/accepted 主题上发布成功消息，并在 $aws/things/myThing/jobs/get/rejected 主题上发布已拒绝消息。

260

AWS IoT 开发人员指南设备和任务

使用 HTTP SigV4

Jobs 服务和设备之间的通信可通过端口 443 上的 HTTP SigV4 进行。这是由 AWS 开发工具包和 CLI使用的方法。有关这些工具的更多信息，请参阅 AWS CLI 命令参考：iot-jobs-data 或 AWS 开发工具包和工具并参考您的首选语言的 IotJobsDataPlane 部分。

Note

在通过 HTTP SigV4 或者使用 AWS 开发工具包或 CLI IotJobsDataPlane 命令与 Jobs 进行通信时，您必须使用正确的终端节点。要查找该终端节点，请使用 DescribeEndpoint 命令。例如，使用以下 CLI：

aws iot describe-endpoint --endpoint-type iot:Jobs


{ "endpointAddress": "a1b2c3d4e5f6g7.jobs.iot.us-west-2.amazonaws.com"}

利用这种通信方法，您的设备将使用 IAM 凭证对 Jobs 服务进行身份验证。

可以使用此方法执行以下命令：

• DescribeJobExecution

aws iot-jobs-data describe-job-execution ...

• GetPendingJobExecutions

aws iot-jobs-data get-pending-job-executions ...

• StartNextPendingJobExecution

aws iot-jobs-data start-next-pending-job-execution ...

• UpdateJobExecution

aws iot-jobs-data update-job-execution ...

使用 HTTP TLS

Jobs 服务和设备之间的通信可通过端口 8443 上的 HTTP TLS，使用支持此协议的第三方软件客户端进行。

Note

您在通过 HTTP TLS 与 Jobs 进行通信时必须使用正确的终端节点。要查找该终端节点，请使用 DescribeEndpoint 命令。例如，使用以下 CLI：

aws iot describe-endpoint --endpoint-type iot:Jobs


{ "endpointAddress": "a1b2c3d4e5f6g7.jobs.iot.us-west-2.amazonaws.com"}

利用此方法，您的设备可使用基于身份验证的 X509 证书 (例如，使用其特定于设备的证书和私有密钥)。

可以使用此方法执行以下命令：

261

http://docs.aws.amazon.com/cli/latest/reference/iot-jobs-data/index.html



AWS IoT 开发人员指南对设备进行编程以使用 Jobs

• DescribeJobExecution• GetPendingJobExecutions• StartNextPendingJobExecution• UpdateJobExecution

对设备进行编程以使用 Jobs本节中的示例使用 MQTT 来演示设备如何使用 Jobs。或者，您也可以按需使用对应的 API 或 CLI 命令。对于这些示例，我们假定一台名为 MyThing 的设备将订阅以下 MQTT 主题：

• $aws/things/MyThing/jobs/notify (或者 $aws/things/MyThing/jobs/notify-next)• $aws/things/MyThing/jobs/get/accepted

• $aws/things/MyThing/jobs/get/rejected

• $aws/things/MyThing/jobs/jobId/get/accepted

• $aws/things/MyThing/jobs/jobId/get/rejected

设备工作流程通常，设备可通过两种方式处理要执行的任务。

选项 A：获取下一个任务

1. 当设备首次联机时，它应订阅设备的 notify-next 主题。2. 使用 jobId $next 调用 DescribeJobExecution (p. 308) MQTT API 以获取下一个任务、其任务文

档和其他详细信息，包括保存在 statusDetails 中的任何状态。3. 调用 UpdateJobExecution (p. 312) MQTT API 以更新任务状态。或者，要在一个调用中将此步骤

与上一步骤合并，设备可调用 StartNextPendingJobExecution (p. 303)。4. 使用 UpdateJobExecution (p. 312) MQTT API 执行任务文档所指定的操作以报告任务的进度。5. 再次调用 UpdateJobExecution (p. 312) MQTT API 以更新任务状态并报告成功或失败。6. 由于此任务的执行状态已更改为最终状态，因此，可用于执行的下一个任务 (如果有) 将发生更改。

设备将收到下一个待处理任务执行已更改的通知。此时，设备将按照步骤 2 中所述继续操作。

如果设备保持联机状态，则它在完成任务或添加新的待处理任务执行时，将继续收到下一个待处理任务执行的通知，包括其 JobExecutionData。在发生此情况时，设备将按照步骤 2 中所述继续操作。

选项 B：从可用任务中选取

1. 当设备首次联机时，它应订阅事物的 notify 主题。2. 调用 GetPendingJobExecutions (p. 300) MQTT API 以获取待处理任务执行的列表。3. 如果列表包含一个或多个任务执行，请选取一个任务执行。4. 调用 DescribeJobExecution (p. 308) MQTT API 以获取任务文档和其他详细信息，包括保存在

statusDetails 中的任何状态。5. 调用 UpdateJobExecution (p. 312) MQTT API 以更新任务状态。如果在此命令中将

includeJobDocument 字段设置为 true，则设备可跳过上一个步骤并在此时检索任务文档。6. 使用 UpdateJobExecution (p. 312) MQTT API 执行任务文档所指定的操作以报告任务的进度。7. 再次调用 UpdateJobExecution (p. 312) MQTT API 以更新任务状态并报告成功或失败。

如果设备保持联机状态，则在一个新的待处理任务执行变为可用时，它将收到所有待处理任务执行的通知。在发生此情况时，设备可按照步骤 2 中所述继续操作。

262


如果设备无法执行任务，它将调用 UpdateJobExecution (p. 312) MQTT API 来将任务状态更新为REJECTED。

开始新任务新任务通知

在创建新任务时，Jobs 将在 $aws/things/thing-name/jobs/notify 主题上为每个目标设备发布一条消息。

更多信息 (13)

消息包含以下信息：

{ "timestamp":1476214217017, "jobs":{ "QUEUED":[{ "jobId":"0001", "queuedAt":1476214216981, "lastUpdatedAt":1476214216981, "versionNumber" : 1 }] }}

在对任务执行进行排队时，设备将在“$aws/things/thingName/jobs/notify”主题中收到此消息。

获取任务信息

要获取有关任务执行的更多信息，请调用 DescribeJobExecution (p. 308) MQTT API 并将includeJobDocument 字段设置为 true。

更多信息 (14)

如果请求成功，Jobs 将在 $aws/things/MyThing/jobs/0023/get/accepted 主题上发布消息：

{ "clientToken" : "client-001", "timestamp" : 1489097434407, "execution" : { "jobId" : "023", "status" : "QUEUED", "queuedAt" : 1489097374841, "lastUpdatedAt" : 1489097374841, "versionNumber" : 1, "jobDocument" : { < contents of job document > } }}

Note

如果请求失败，Jobs 将在 $aws/things/MyThing/jobs/0023/get/rejected 主题上发布消息。

设备现在已有任务文档，它可解释该文档以执行任务的远程操作。如果任务文档包含一个 Amazon S3 预签名 URL，则设备可使用该 URL 下载任务的任何所需文件。

263


设备可调用 StartNextPendingJobExecution (p. 303) MQTT API 来通过一个步骤请求更多信息并开始任何待处理任务执行。

报告任务执行状态更新执行状态

当设备执行任务时，它可调用 UpdateJobExecution (p. 312) MQTT API 来更新任务执行的状态。更多信息 (15)

例如，设备可通过在 $aws/things/MyThing/jobs/0023/update 主题上发布以下消息来将任务执行状态更新为 IN_PROGRESS：

{ "status":"IN_PROGRESS", "statusDetails": { "progress":"50%" }, "expectedVersion":"1", "clientToken":"client001"}

Jobs 通过将消息发布到 $aws/things/MyThing/jobs/0023/update/accepted 或 $aws/things/MyThing/jobs/0023/update/rejected 主题来做出响应：

{ "clientToken":"client001", "timestamp":1476289222841}

设备可通过调用 StartNextPendingJobExecution (p. 303) 来合并前两个以前的请求，这将获取并开始下一个待处理任务执行，并允许设备更新任务执行状态。此请求还在有待处理任务执行时返回任务文档。

status 字段可设置为 QUEUED、IN_PROGRESS、SUCCESS、FAILED、REJECTED、REMOVED 或CANCELED。您无法更新已处于最终状态的任务执行的状态。

报告执行已完成

在设备执行完任务后，它将调用 UpdateJobExecution (p. 312) MQTT API。如果任务已成功，则将status 设置为 SUCCESS，并在消息负载的 statusDetails 中，将有关任务的其他信息作为名称/值对添加。

更多信息 (16)

例如：

{ "status":"SUCCESS", "statusDetails": { "progress":"100%" }, "expectedVersion":"2", "clientToken":"client-001"}

如果任务未成功，则将 status 设置为 FAILED，并在 statusDetails 中，添加有关出现的错误的信息：

264

AWS IoT 开发人员指南使用 AWS IoT Jobs API

{ "status":"FAILED", "statusDetails": { "errorCode":"101", "errorMsg":"Unable to install update" }, "expectedVersion":"2", "clientToken":"client-001"}

Note

statusDetails 属性可包含任意数量的名称/值对。

在 Jobs 检索此更新时，它会在 $aws/things/MyThing/jobs/notify 主题上发布消息以指示任务执行已完成：

{ "timestamp":1476290692776, "jobs":{}}

其他任务其他任务

如果设备有其他待处理的任务执行，这些任务执行将包含在发布到 $aws/things/MyThing/jobs/notify 的消息中。

更多信息 (17)

例如：

{ "timestamp":1476290692776, "jobs":{ "QUEUED":[{ "jobId":"0002", "queuedAt":1476290646230, "lastUpdatedAt":1476290646230 }], "IN_PROCESS":[{ "jobId":"0003", "queuedAt":1476290646230, "lastUpdatedAt":1476290646230 }] }}

使用 AWS IoT Jobs API有两类在 AWS IoT Jobs 中使用的 API：

• 用于管理和控制任务的 API。• 由执行这些任务的设备使用的 API。

265

AWS IoT 开发人员指南任务管理和控制 API

通常，任务的管理和控制操作将使用 HTTPS 协议 API。设备可以使用 MQTT 或 HTTPS 协议 API。(HTTPSAPI 旨在用于通常在创建和跟踪任务时进行的少量调用。它通常会为一个请求打开一个连接，然后在收到响应后关闭此连接。MQTT API 允许长轮询。它旨在用于可扩展至数百万台设备的大量流量。)

Note

每个 Jobs HTTPS API 均有一个对应的命令，您可使用该命令从 AWS CLI 调用该 API。命令采用小写形式，并且在构成 API 名称的单词之间使用连字符。例如，您可以通过键入以下内容，在 CLI 上调用 CreateJob API：

aws iot create-job ...

任务管理和控制 API任务管理和控制数据类型管理和控制应用程序使用以下数据类型与 Jobs 进行通信。

任务

Job 数据类型

Job 对象包含有关任务的详细信息。语法 (1)

{ "jobArn": "string", "jobId": "string", "status": "IN_PROGRESS|CANCELED|COMPLETED", "targetSelection": "CONTINUOUS|SNAPSHOT", "comment": "string", "targets": ["string"], "description": "string", "createdAt": timestamp, "lastUpdatedAt": timestamp, "completedAt": timestamp, "jobProcessDetails": { "processingTargets": ["string"], "numberOfCanceledThings": "long", "numberOfSucceededThings": "long", "numberOfFailedThings": "long", "numberOfRejectedThings": "long", "numberOfQueuedThings": "long", "numberOfInProgressThings": "long", "numberOfRemovedThings": "long", }, "presignedUrlConfig": { "expiresInSec": number, "roleArn": "string" }, "jobExecutionRolloutConfig": { "maximumPerMinute": "integer" }}

描述 (1)

jobArn

一个标识任务的 ARN，格式为“arn:aws:iot:region:account:job/jobId”。

266


jobId

您在创建此任务时向其分配的唯一标识符。status

任务的状态，为 IN_PROGRESS、CANCELED 或 COMPLETED 之一。targetSelection

指定任务是继续运行 (CONTINUOUS)，还是在指定作为目标的事物完成任务后完成(SNAPSHOT)。如果为 CONTINUOUS，则在目标中检测到更改时，任务也可能会在事物上运行。例如，在将一个事物添加到目标组时，任务会在该事物上运行，甚至在组中原有的所有事物都完成任务后也是如此。

comment

如果任务已更新，介绍更新原因。targets

任务应发送到的 AWS IoT 事物和事物组的列表。description

任务的简短文本描述。createdAt

创建任务的时间，用从纪元开始的毫秒数表示。lastUpdatedAt

上次更新任务的时间，用从纪元开始的毫秒数表示。completedAt

完成任务的时间，用从纪元开始的毫秒数表示。jobProcessDetails

有关任务流程的详细信息：processingTargets

当前正在执行任务的 AWS IoT 事物和事物组的列表。numberOfCanceledThings

已取消任务的 AWS IoT 事物的数量。numberOfSucceededThings

已成功完成任务的 AWS IoT 事物的数量。numberOfFailedThings

未能完成任务的 AWS IoT 事物的数量。numberOfRejectedThings

已拒绝任务的 AWS IoT 事物的数量。numberOfQueuedThings

正在等待任务执行的 AWS IoT 事物的数量。numberOfInProgressThings

当前正在执行任务的 AWS IoT 事物的数量。

267


numberOfRemovedThings

因其已从作为任务目标的组中被删除或移除而不再计划执行的 AWS IoT 事物的数量。presignedUrlConfig

预签名 Amazon S3 URL 的配置信息。expiresInSec

预签名 URL 的有效期时间长度 (以秒为单位)。有效值为 60-3600。默认值为 3600 秒。在 Jobs收到任务文档的 MQTT 请求时会生成预签名 URL。

roleArn

授予从 Amazon S3 存储桶下载文件的权限的 IAM 角色的 ARN。该角色还必须向 AWS IoT 授予下载文件的权限。有关如何创建和配置角色的更多信息，请参阅创建任务 (p. 252)。

jobExecutionRolloutConfig

允许您创建任务的分段部署。maximumPerMinute

每分钟将任务发送到的用于执行任务的事物 (设备) 的最大数量。

JobSummary

JobSummary 数据类型

JobSummary 对象包含任务摘要。语法 (2)

{ "jobArn": "string", "jobId": "string", "status": "IN_PROGRESS|CANCELED|COMPLETED", "description": "string", "targetSelection": "CONTINUOUS|SNAPSHOT", "thingGroupId": "string", "createdAt": timestamp, "lastUpdatedAt": timestamp, "completedAt": timestamp}

描述 (2)

jobArn

一个标识任务的 ARN。jobId


任务状态。可以为以下值之一：IN_PROGRESS、CANCELED 或 COMPLETED。targetSelection

指定任务是继续运行 (CONTINUOUS)，还是在指定作为目标的所有事物完成任务后完成(SNAPSHOT)。如果为 CONTINUOUS，则在目标中检测到更改时，任务也可能会在事物上运行。例如，在将一个事物添加到目标组时，任务会在该事物上运行，甚至在组中原有的所有事物都完成任务后也是如此。

268


thingGroupId

事物组的 ID。createdAt

创建任务的时间的 UNIX 时间戳。lastUpdatedAt

上次更新任务的时间的 UNIX 时间戳。completedAt

完成任务的时间的 UNIX 时间戳。

JobExecution

JobExection 数据类型

JobExecution 对象表示特定设备上的任务执行。语法 (3)

{ "jobId": "string", "executionNumber": 1234567890, "thingArn": "string", "queuedAt": timestamp, "lastUpdatedAt": timestamp, "startedAt": timestamp, "status": "QUEUED|IN_PROGRESS|FAILED|SUCCESS|CANCELED|REJECTED|REMOVED", "statusDetails": { "detailsMap": { "string": "string" ... }, "status": "string" }, }

描述 (3)

jobId

您在创建此任务时向其分配的唯一标识符。executionNumber

一个标识该特定设备上的此任务执行的数字。它可随后在返回或更新任务执行信息的命令中使用。thingArn

AWS IoT 事物 ARN。queuedAt

任务执行入队的时间，用从纪元开始的毫秒数表示。lastUpdatedAt

上次更新任务执行的时间，用从纪元开始的毫秒数表示。startedAt

任务执行开始的时间，用从纪元开始的毫秒数表示。

269


status

任务执行的状态。可以为以下值之一：“QUEUED”、“IN_PROGRESS”、“FAILED”、“SUCCESS”、“CANCELED”、“REJECTED”或“REMOVED”。

statusDetails

描述任务执行状态的名称/值对的集合。

JobExecutionSummary

JobExecutionSummary 数据类型

JobExecutionSummary 对象包含任务执行摘要信息：语法 (4)

{ "executionNumber": 1234567890, "queuedAt": timestamp, "lastUpdatedAt": timestamp, "startedAt": timestamp, "status": "QUEUED|IN_PROGRESS|FAILED|SUCCESS|CANCELED|REJECTED|REMOVED"}

描述 (4)

executionNumber

标识特定设备上的特定任务执行的数字。它可随后在返回或更新任务执行信息的命令中使用。queuedAt

任务执行入队的时间，用从纪元开始的毫秒数表示。lastUpdatedAt

上次更新任务执行的时间，用从纪元开始的毫秒数表示。startAt

任务执行开始的时间，用从纪元开始的毫秒数表示。status

任务执行的状态：QUEUED、IN_PROGRESS、FAILED、SUCCESS、CANCELED、REJECTED或 REMOVED。

JobExecutionSummaryForJob

JobExecutionSummaryForJob 数据类型

JobExecutionSummaryForJob 对象包含有关特定任务的任务执行的信息摘要。语法 (5)

{ "executionSummary": [ { "thingArn": "string", "jobExecutionSummary": { JobExecutionSummary } } ... ]

270


}

描述 (5)

thingArn

AWS IoT 事物 ARN。jobExecutionSummary

一个 JobExecutionSummary (p. 270) 对象。

JobExecutionSummaryForThing

JobExecutionSummaryForThing 数据类型

JobExecutionSummaryForThing 对象包含有关特定事物上的任务执行的信息摘要。语法 (6)

{ "jobId": "string", "jobExecutionSummary": { JobExecutionSummary }}

描述 (6)

jobId

您在创建此任务时向其分配的唯一标识符。jobExecutionSummary

一个 JobExecutionSummary (p. 270) 对象。

任务管理和控制 HTTPS 命令以下命令可供管理和控制应用程序通过 HTTPS 协议使用。

AssociateTargetsWithJob

AssociateTargetsWithJob 命令

将组与持续任务关联。有关更多信息，请参阅 CreateJob (p. 275)。必须满足以下标准：

• 创建任务时必须将 targetSelection 字段设置为“CONTINUOUS”。• 任务状态当前必须为“IN_PROGRESS”。• 与任务关联的目标总数不能超过 100。

HTTPS (1)

请求:

POST /jobs/jobId/targets

{ "targets": [ "string" ], "comment": "string"}

271


jobId

您在创建此任务时向其分配的唯一标识符。targets

定义任务目标的事物组 ARN 列表。comment

可选。一个备注字符串，描述将任务与目标关联的原因。

响应:

{ "jobArn": "string", "jobId": "string", "description": "string"}

jobArn

标识任务的 ARN。jobId

您在创建此任务时向其分配的唯一标识符。description

任务的简短文本描述。

CLI (1)

摘要:

aws iot associate-targets-with-job \ --targets <value> \ --job-id <value> \ [--comment <value>] \ [--cli-input-json <value>] \ [--generate-cli-skeleton]

cli-input-json format:

{ "targets": [ "string" ], "jobId": "string", "comment": "string"}

cli-input-json 字段：

名称类型描述

目标列表

成员：TargetArn

定义任务目标的事物组 ARN 列表。

272


名称类型描述

TargetArn 字符串

jobId 字符串

最大长度：64，最小长度：1

模式：[a-zA-Z0-9_-]+

您在创建此任务时向其分配的唯一标识符。

comment 字符串

最大长度：2028

模式：[^\\p{C}]+

一个可选的备注字符串，用于描述为什么将任务与目标关联。

输出:


cli 输出字段：

名称类型描述

jobArn 字符串标识任务的 ARN。

jobId 字符串


模式：[a-zA-Z0-9_-]+


description 字符串

最大长度：2028

模式：[^\\p{C}]+


MQTT (1)

不可用。

CancelJob

CancelJob 命令

取消任务。HTTPS (2)

请求:

PUT /jobs/jobId/cancel

273


{ "comment": "string"}

jobId

您在创建此任务时向其分配的唯一标识符。comment

[可选] 一个备注字符串，描述取消任务的原因。

响应:


jobArn

任务 ARN。jobId

您在创建此任务时向其分配的唯一标识符。description


CLI (2)

摘要:

aws iot cancel-job \ --job-id <value> \ [--comment <value>] \ [--cli-input-json <value>] \ [--generate-cli-skeleton]


{ "jobId": "string", "comment": "string"}


名称类型描述

jobId 字符串


模式：[a-zA-Z0-9_-]+


274


名称类型描述

comment 字符串

最大长度：2028

模式：[^\\p{C}]+

一个可选的备注字符串，用于描述为什么取消任务。

输出:


cli 输出字段：

名称类型描述

jobArn 字符串任务 ARN。

jobId 字符串


模式：[a-zA-Z0-9_-]+



最大长度：2028

模式：[^\\p{C}]+


MQTT (2)

不可用。

CreateJob

CreateJob 命令

创建任务。您可以通过指向 Amazon S3 存储桶中文件的链接 (documentSource 参数) 的方式来提供任务文档，或者在请求正文 (document 参数) 中提供任务文档。

可通过将可选的 targetSelection 参数设置为“CONTINUOUS”，使任务成为持续任务。(默认值为“SNAPSHOT”。) 持续任务可用于在将设备添加到组时加入或升级设备，因为它将继续运行并在新添加的事物上执行，甚至在组中的事物在创建任务期间完成任务后也是如此。

对 CreateJob API 的参数执行以下验证：

• targets 参数必须是有效事物或事物组 ARN 的列表。所有事物和事物组必须在您的 AWS 账户中。• documentSource 参数必须是指向任务文档的有效 Amazon S3 URL。Amazon S3 URL 的形式

为：https://s3.amazonaws.com/bucketName/objectName。• 存储在由 documentSource 参数指定的 URL 中的文档必须是 UTF-8 编码的 JSON 文档。

275


• 由于 MQTT 消息大小限制 (128 KB) 和加密的原因，任务文档的大小限制为 32 KB。• jobId 在您的 AWS 账户内必须是唯一的。

HTTPS (3)

请求:

PUT /jobs/jobId

{ "targets": [ "string" ], "document": "string", "documentSource": "string", "description": "string", "presignedUrlConfigData": { "roleArn": "string", "expiresInSec": "integer" }, "targetSelection": "CONTINUOUS|SNAPSHOT", "jobExecutionsRolloutConfig": { "maximumPerMinute": "integer" }}

jobId

一个任务标识符，它对您的 AWS 账户必须是唯一的。我们建议使用 UUID。字母数字字符，此处可使用“-”和“_”。

targets

定义任务目标的事物或事物组 ARN 的列表。document

可选。任务文档。documentSource

可选。指向任务文档的 Amazon S3 链接。description

可选。任务的简短文本描述。presignedUrlConfigData

可选。预签名 Amazon S3 URL 的配置信息。roleArn

包含 Amazon S3 存储桶的访问权限的 IAM 角色的 ARN。这是包含设备通过预签名 AmazonS3 URL 下载的数据的存储桶。该角色还必须向 AWS IoT 授予代入角色的权限。有关更多信息，请参阅创建任务 (p. 252)。

expiresInSec

预签名 URL 的有效期时间长度 (以秒为单位)。有效值为 60-3600。默认值为 3600 秒。在 Jobs收到任务文档的 MQTT 请求时会生成预签名 URL。

targetSelection

可选。指定任务是继续运行 (CONTINUOUS)，还是在指定作为目标的所有事物完成任务后完成(SNAPSHOT)。如果为 CONTINUOUS，则在目标中检测到更改时，也可能会计划在事物上运行任

276


务。例如，在将一个事物添加到目标组时，会计划在该事物上运行任务，甚至在组中原有的所有事物都完成任务后也是如此。

jobExecutionRolloutConfig

可选。允许您创建任务的分段部署。maximumPerMinute

每分钟将任务发送到用于执行任务的事物的最大数量。有效值为 1 到 1000. 如果未指定，默认值为 1000。在任何特定的分钟间隔内接收任务的事物的实际数量可能会少一些 (由于系统延迟)，但不会超过指定的值。

响应:


jobArn

任务的 ARN。jobId

您分配给此任务的唯一标识符。description

任务的可选简短文本描述。

CLI (3)

摘要:

aws iot create-job \ --job-id <value> \ --targets <value> \ [--document-source <value>] \ [--document <value>] \ [--description <value>] \ [--presigned-url-config <value>] \ [--target-selection <value>] \ [--job-executions-rollout-config <value>] \ [--document-parameters <value>] \ [--cli-input-json <value>] \ [--generate-cli-skeleton]


{ "jobId": "string", "targets": [ "string" ], "documentSource": "string", "document": "string", "description": "string",

277


"presignedUrlConfig": { "roleArn": "string", "expiresInSec": "long" }, "targetSelection": "string", "jobExecutionsRolloutConfig": { "maximumPerMinute": "integer" }, "documentParameters": { "string": "string" }}


名称类型描述

jobId 字符串


模式：[a-zA-Z0-9_-]+

任务的标识符，必须是您的AWS 账户的唯一标识符。我们建议使用 UUID。此处可以使用字母数字字符、“-”和“_”。

targets 列表

成员：TargetArn

任务应发送到的事物和事物组的列表。

TargetArn 字符串

documentSource 字符串


指向任务文档的 S3 链接。

文档字符串

最大长度：32768

任务文档。


最大长度：2028

模式：[^\\p{C}]+


presignedUrlConfig PresignedUrlConfig 预签名 S3 URL 的配置信息。

roleArn 字符串


IAM 角色的 ARN，该角色授予权限以从存储任务数据/更新的S3 存储桶下载文件。该角色还必须授予 IoT 下载文件的权限。

expiresInSec long

java 类：java.lang.Long

范围 – 最大值：3600，最小值：60

预签名 URL 的有效时间长度(以秒为单位)。有效值为 60 –3600，默认值为 3600 秒。预签名 URL 在 Jobs 接收任务文档的MQTT 请求时生成。

targetSelection 字符串

枚举：CONTINUOUS |SNAPSHOT

指定任务将继续运行(CONTINUOUS)，还是在指定作为目标的所有事物完成任务之后完成 (SNAPSHOT)。如果继续运行，则在检测到目标中出

278


名称类型描述java 类：com.amazonaws.iot.laser.TargetSelection

现更改时，任务也会在事物上运行。例如，当某个事物添加到目标组时会在该事物上运行任务，即使是组中原有的全部事物已经完成了任务。

jobExecutionsRolloutConfig JobExecutionsRolloutConfig 允许您创建任务的分段部署。

maximumPerMinute integer

java 类：java.lang.Integer


待处理任务每分钟通知事物的最大数量。此参数允许您创建分段部署。

documentParameters map

键：ParameterKey

值：ParameterValue

任务文档的参数。

ParameterKey 字符串


模式：[a-zA-Z0-9:_-]+

ParameterValue 字符串


模式：[^\\p{C}]+

输出:


cli 输出字段：

名称类型描述


jobId 字符串


模式：[a-zA-Z0-9_-]+

您分配给此任务的唯一标识符。


最大长度：2028

模式：[^\\p{C}]+

任务描述。

279


MQTT (3)

不可用。

DescribeJob

DescribeJob 命令

获取指定任务的详细信息。HTTPS (4)

请求:

GET /jobs/jobId

jobId


响应:

{ "documentSource": "string", "job": Job }

documentSource

指向任务文档的 Amazon S3 链接。job

一个任务 (p. 266) 对象。

CLI (4)

摘要:

aws iot describe-job \ --job-id <value> \ [--cli-input-json <value>] \ [--generate-cli-skeleton]


{ "jobId": "string"}


名称类型描述

jobId 字符串



280


名称类型描述模式：[a-zA-Z0-9_-]+

输出:

{ "documentSource": "string", "job": { "jobArn": "string", "jobId": "string", "targetSelection": "string", "status": "string", "comment": "string", "targets": [ "string" ], "description": "string", "presignedUrlConfig": { "roleArn": "string", "expiresInSec": "long" }, "jobExecutionsRolloutConfig": { "maximumPerMinute": "integer" }, "createdAt": "timestamp", "lastUpdatedAt": "timestamp", "completedAt": "timestamp", "jobProcessDetails": { "processingTargets": [ "string" ], "numberOfCanceledThings": "integer", "numberOfSucceededThings": "integer", "numberOfFailedThings": "integer", "numberOfRejectedThings": "integer", "numberOfQueuedThings": "integer", "numberOfInProgressThings": "integer", "numberOfRemovedThings": "integer" }, "documentParameters": { "string": "string" } }}

cli 输出字段：

名称类型描述




任务任务该任务的相关信息。

jobArn 字符串标识任务的 ARN，格式为“arn:aws:iot:region:account:job/jobId”。

jobId 字符串您在创建此任务时向其分配的唯一标识符。

281


名称类型描述最大长度：64，最小长度：1

模式：[a-zA-Z0-9_-]+



java 类：com.amazonaws.iot.laser.TargetSelection

指定任务将继续运行(CONTINUOUS)，还是在指定作为目标的所有事物完成任务之后完成 (SNAPSHOT)。如果继续运行，则在检测到目标中出现更改时，任务也会在事物上运行。例如，当代表设备的某个事物添加到目标组时，会在该设备上运行任务，即使是组中原有的全部事物已经完成了任务。

status 字符串

枚举：IN_PROGRESS |CANCELED | COMPLETED

java 类：ccom.amazonaws.iot.laser.common.JobStatus

任务的状态，为IN_PROGRESS、CANCELED 或COMPLETED 之一。

comment 字符串

最大长度：2028

模式：[^\\p{C}]+

如果任务已更新，介绍更新原因。

targets 列表

成员：TargetArn

任务应发送到的 IoT 事物和事物组的列表。

TargetArn 字符串


最大长度：2028

模式：[^\\p{C}]+


presignedUrlConfig PresignedUrlConfig 预签名 S3 URL 的配置。

roleArn 字符串


IAM 角色的 ARN，该角色授予权限以从存储任务数据/更新的S3 存储桶下载文件。该角色还必须授予 IoT 下载文件的权限。

expiresInSec long





282


名称类型描述





createdAt timestamp 创建任务的时间，用从纪元开始的毫秒数表示。

lastUpdatedAt timestamp 上次更新任务的时间，用从纪元开始的毫秒数表示。

completedAt timestamp 完成任务的时间，用从纪元开始的毫秒数表示。

jobProcessDetails JobProcessDetails 任务流程的详细信息。

processingTargets 列表

成员：ProcessingTargetName

java 类：java.util.List

执行任务的设备。

ProcessingTargetName 字符串

numberOfCanceledThings integer


取消了任务的事物数。

numberOfSucceededThings integer


成功完成任务的事物数。

numberOfFailedThings integer


任务执行失败的事物数。

numberOfRejectedThings integer


拒绝了任务的事物数。

numberOfQueuedThings integer


等待任务执行的事物数。

numberOfInProgressThings integer


当前正在执行任务的事物数。

numberOfRemovedThings integer


因其已从作为任务目标的组中被删除或移除而不再计划执行的事物的数量。


键：ParameterKey


为任务文档指定的参数。

283


名称类型描述



模式：[a-zA-Z0-9:_-]+



模式：[^\\p{C}]+

MQTT (4)

不可用。

DescribeJobExecution

DescribeJobExecution 命令

获取任务执行的详细信息。任务的执行状态必须为 SUCCEEDED 或 FAILED。HTTPS (5)

请求:

GET /things/thingName/jobs/jobId?executionNumber=executionNumber

jobId

您在创建此任务时向其分配的唯一标识符。thingName

与正在运行任务执行的设备关联的事物名称。executionNumber

可选。一个用于指定特定设备上的特定任务执行的数字。(请参阅 JobExecution (p. 269).) 如果未指定，则返回最新的任务执行。

响应:

{ "execution": { JobExecution }}

execution

一个 JobExecution (p. 269) 对象。

CLI (5)

摘要:

aws iot describe-job-execution \

284


--job-id <value> \ --thing-name <value> \ [--execution-number <value>] \ [--cli-input-json <value>] \ [--generate-cli-skeleton]


{ "jobId": "string", "thingName": "string", "executionNumber": "long"}


名称类型描述

jobId 字符串


模式：[a-zA-Z0-9_-]+


thingName 字符串


模式：[a-zA-Z0-9:_-]+

正在运行任务执行的事物的名称。

executionNumber long


一个由从“0”到“9”的数字组成的字符串，用于指定特定设备上的特定任务执行。

输出:

{ "execution": { "jobId": "string", "status": "string", "statusDetails": { "detailsMap": { "string": "string" } }, "thingArn": "string", "queuedAt": "timestamp", "startedAt": "timestamp", "lastUpdatedAt": "timestamp", "executionNumber": "long" }}

cli 输出字段：

名称类型描述

execution JobExecution 任务执行的相关信息。

285


名称类型描述

jobId 字符串


模式：[a-zA-Z0-9_-]+

您在创建任务时向其分配的唯一标识符。

status 字符串

枚举：QUEUED |IN_PROGRESS | SUCCEEDED| FAILED | REJECTED |REMOVED | CANCELED

java 类：com.amazonaws.iot.laser.common.JobExecutionStatus

任务执行的状态(IN_PROGRESS、QUEUED、FAILED、SUCCESS、CANCELED或 REJECTED)。

statusDetails JobExecutionStatusDetails 描述任务执行状态的名称/值对的集合。

detailsMap map

键：DetailsKey

值：DetailsValue

任务执行状态。

DetailsKey 字符串


模式：[a-zA-Z0-9:_-]+

DetailsValue 字符串


模式：[^\\p{C}]*+

thingArn 字符串正在运行任务执行的事物的ARN。

queuedAt timestamp 任务执行入队的时间，用从纪元开始的毫秒数表示。

startedAt timestamp 任务执行开始的时间，用从纪元开始的毫秒数表示。

lastUpdatedAt timestamp 上次更新任务执行的时间，用从纪元开始的毫秒数表示。



一个由从“0”到“9”的数字组成的字符串，用于标识此特定设备上的该特定任务执行。它可在返回或更新任务执行信息的命令中使用。

MQTT (5)

不可用。

286


GetJobDocument

GetJobDocument 命令

获取任务的任务文档。Note

占位符 URL 不会替换为所返回文档中的预签名 Amazon S3 URL。仅在 Jobs 通过 MQTT 接收请求时生成预签名 URL。

HTTPS (6)

请求:

GET /jobs/jobId/job-document

jobId


响应:

{ "document": "string"}

document

任务文档内容。

CLI (6)

摘要:

aws iot get-job-document \ --job-id <value> \ [--cli-input-json <value>] \ [--generate-cli-skeleton]




名称类型描述

jobId 字符串


模式：[a-zA-Z0-9_-]+


输出:

287



cli 输出字段：

名称类型描述

文档字符串



MQTT (6)

不可用。

ListJobExecutionsForJob

ListExecutionsForJob 命令

获取任务的任务执行的列表。HTTPS (7)

请求:

GET /jobs/jobId/things?status=status&maxResults=maxResults&nextToken=nextToken

jobId


可选。可用于搜索具有指定状态的任务的筛选条件：QUEUED、IN_PROGRESS、SUCCESS、FAILED、REJECTED、REMOVED 或 CANCELED。

maxResults

可选。每个请求返回的最大结果数。nextToken

可选。用于检索下一组结果的令牌。

响应:

{ "executionSummaries": [ JobExecutionSummary ... ]}

executionSummaries

与指定的任务 ID 关联的 JobExecutionSummary (p. 270) 对象的列表。

CLI (7)

摘要:

288


aws iot list-job-executions-for-job \ --job-id <value> \ [--status <value>] \ [--max-results <value>] \ [--next-token <value>] \ [--cli-input-json <value>] \ [--generate-cli-skeleton]


{ "jobId": "string", "status": "string", "maxResults": "integer", "nextToken": "string"}


名称类型描述

jobId 字符串


模式：[a-zA-Z0-9_-]+


status 字符串



任务的状态。

maxResults integer


范围 - 最大值：250，最小值：1

每个请求返回的最大结果数。

nextToken 字符串用于检索下一组结果的令牌。

输出:

{ "executionSummaries": [ { "thingArn": "string", "jobExecutionSummary": { "status": "string", "queuedAt": "timestamp", "startedAt": "timestamp", "lastUpdatedAt": "timestamp", "executionNumber": "long" } } ],

289


"nextToken": "string"}

cli 输出字段：

名称类型描述

executionSummaries 列表

成员：JobExecutionSummaryForJob


任务执行摘要的列表。

JobExecutionSummaryForJob JobExecutionSummaryForJob


jobExecutionSummary JobExecutionSummary 包含有关任务执行的信息的子集。

status 字符串



任务执行的状态。






一个由从“0”到“9”的数字组成的字符串，用于标识此特定设备上的该特定任务执行。它可随后在返回或更新任务执行信息的命令中使用。

nextToken 字符串下一组结果的令牌，没有更多结果时为 null。

MQTT (7)

不可用。

ListJobExecutionsForThing

ListJobExecutionsForThing 命令

获取事物的任务执行的列表。

290


HTTPS (8)

请求:

GET /things/thingName/jobs?status=status&maxResults=maxResults&nextToken=nextToken

thingName

将列出其 JobExecutions 的事物的名称。status

可用于搜索具有指定状态的任务的可选筛选条件：QUEUED、IN_PROGRESS、SUCCESS、FAILED、REJECTED、REMOVED 或 CANCELED。

maxResults

每个请求返回的最大结果数。nextToken

下一组结果的令牌，没有更多结果时为 null。

响应:

{ "executionSummaries": [ JobExecutionSummary ... ]}

executionSummaries

与指定事物关联的任务执行的 JobExecutionSummary (p. 270) 对象的列表。

CLI (8)

摘要:

aws iot list-job-executions-for-thing \ --thing-name <value> \ [--status <value>] \ [--max-results <value>] \ [--next-token <value>] \ [--cli-input-json <value>] \ [--generate-cli-skeleton]


{ "thingName": "string", "status": "string", "maxResults": "integer", "nextToken": "string"}


名称类型描述

thingName 字符串事物名称。

291



模式：[a-zA-Z0-9:_-]+

status 字符串



一个可选筛选条件，允许您搜索具有指定状态的任务。

maxResults integer





输出:

{ "executionSummaries": [ { "jobId": "string", "jobExecutionSummary": { "status": "string", "queuedAt": "timestamp", "startedAt": "timestamp", "lastUpdatedAt": "timestamp", "executionNumber": "long" } } ], "nextToken": "string"}

cli 输出字段：

名称类型描述


成员：JobExecutionSummaryForThing



JobExecutionSummaryForThing JobExecutionSummaryForThing

jobId 字符串


模式：[a-zA-Z0-9_-]+


292


名称类型描述


status 字符串











MQTT (8)

不可用。

ListJobs

ListJobs 命令

获取 AWS 账户中的任务的列表。HTTPS (9)

请求:

GET /jobs?status=status&targetSelection=targetSelection&thingGroupName=thingGroupName&thingGroupId=thingGroupId&maxResults=maxResults&nextToken=nextToken

status

可选。可用于搜索具有指定状态的任务的筛选条件：IN_PROGRESS、CANCELED 或COMPLETED。

targetSelection

可选。可用于搜索具有指定 targetSelection 值的任务的筛选条件：CONTINUOUS 或SNAPSHOT。

293


thingGroupName

可选。可用于搜索具有指定事物组名称作为目标的任务的筛选条件。thingGroupId

可选。可用于搜索具有指定事物组 ID 作为目标的任务的筛选条件。maxResults

可选。每个请求返回的最大结果数。nextToken

可选。用于检索下一组结果的令牌。

响应:

{ "jobs": [ JobSummary ... ],}

jobs

JobSummary (p. 268) 对象的列表，每个对象对应于 AWS 账户中的一个匹配指定筛选条件的任务。

CLI (9)

摘要:

aws iot list-jobs \ [--status <value>] \ [--target-selection <value>] \ [--max-results <value>] \ [--next-token <value>] \ [--thing-group-name <value>] \ [--thing-group-id <value>] \ [--cli-input-json <value>] \ [--generate-cli-skeleton]


{ "status": "string", "targetSelection": "string", "maxResults": "integer", "nextToken": "string", "thingGroupName": "string", "thingGroupId": "string"}


名称类型描述

status 字符串



294


名称类型描述java 类：ccom.amazonaws.iot.laser.common.JobStatus




指定任务将继续运行(CONTINUOUS)，还是在指定作为目标的所有事物完成任务之后完成 (SNAPSHOT)。如果继续运行，则在检测到目标中出现更改时，任务也会在事物上运行。例如，当某个事物添加到目标组时会在该事物上运行任务，即使是组中原有的全部事物已经完成了任务。

maxResults integer





thingGroupName 字符串


模式：[a-zA-Z0-9:_-]+

一个筛选条件，用于将返回的任务限制为指定组的任务。

thingGroupId 字符串


模式：[a-zA-Z0-9-]+


输出:

{ "jobs": [ { "jobArn": "string", "jobId": "string", "thingGroupId": "string", "targetSelection": "string", "status": "string", "createdAt": "timestamp", "lastUpdatedAt": "timestamp", "completedAt": "timestamp" } ], "nextToken": "string"}

cli 输出字段：

名称类型描述

jobs 列表任务列表。

295


名称类型描述成员：Job Summary


JobSummary JobSummary


jobId 字符串


模式：[a-zA-Z0-9_-]+




模式：[a-zA-Z0-9-]+

事物组的 ID。





status 字符串



任务摘要状态。





MQTT (9)

不可用。

296

AWS IoT 开发人员指南Jobs 设备 MQTT 和 HTTPS API

Jobs 设备 MQTT 和 HTTPS API设备 MQTT 和 HTTPS 数据类型可使用以下数据类型通过 MQTT 和 HTTPS 协议与 Jobs 进行通信。

JobExecution

JobExecution 数据类型

包含有关任务执行的数据。语法 (7)

{ "jobId" : "string", "thingName" : "string", "jobDocument" : "string", "status": "QUEUED|IN_PROGRESS|FAILED|SUCCESS|CANCELED|REJECTED|REMOVED", "statusDetails": { "string": "string" } "queuedAt" : "timestamp", "startedAt" : "timestamp", "lastUpdatedAt" : "timestamp", "versionNumber" : "number", "executionNumber": "long"}

描述 (7)

jobId

您在创建此任务时向其分配的唯一标识符。thingName

正在执行任务的事物的名称。jobDocument

任务文档的内容。status

任务执行的状态。可以为以下值之一：“QUEUED"、“IN_PROGRESS”、“FAILED”、“SUCCESS”、“CANCELED”、“REJECTED”或“REMOVED”。

statusDetails

描述任务执行状态的名称/值对的集合。queuedAt

任务执行入队的时间，用从纪元开始的毫秒数表示。startedAt

任务执行开始的时间，用从纪元开始的毫秒数表示。lastUpdatedAt

上次更新任务执行的时间，用从纪元开始的毫秒数表示。

297


versionNumber

任务执行的版本。每次设备更新任务执行版本时，版本将递增。executionNumber

标识特定设备上的特定任务执行的数字。它可随后在返回或更新任务执行信息的命令中使用。

JobExecutionState

JobExecutionState 数据类型

包含有关任务执行的状态的数据。语法 (8)

{ "status": "QUEUED|IN_PROGRESS|FAILED|SUCCESS|CANCELED|REJECTED|REMOVED", "statusDetails": { "string": "string" ... } "versionNumber": "number"}

描述 (8)

status


statusDetails

描述任务执行状态的名称/值对的集合。versionNumber

任务执行的版本。每次设备更新任务执行版本时，版本将递增。

JobExecutionSummary

JobExecutionSummary 数据类型

包含有关任务执行的信息的子集。语法 (9)

{ "jobId": "string", "queuedAt": timestamp, "startedAt": timestamp, "lastUpdatedAt": timestamp, "versionNumber": "number", "executionNumber": "long" }

描述 (9)

jobId


298


queuedAt

任务执行入队的时间，用从纪元开始的毫秒数表示。startedAt

任务执行开始的时间，用从纪元开始的毫秒数表示。lastUpdatedAt

上次更新任务执行的时间，用从纪元开始的毫秒数表示。versionNumber

任务执行的版本。每当 AWS IoT Jobs 收到来自设备的更新时，任务执行版本都会递增。executionNumber

标识特定设备上的特定任务执行的数字。

ErrorResponse

ErrorRepsonse 数据类型

包含有关 Jobs 操作期间发生的错误的信息。语法 (10)

{ "code": "ErrorCode", "message": "string", "clientToken": "string", "timestamp": timestamp, "executionState": JobExecutionState}

描述 (10)

code

可将 ErrorCode 设置为：InvalidTopic

请求已发送至 Jobs 命名空间中未映射到任何 API 的主题。InvalidJson

请求的内容无法解释为有效的 UTF-8 编码的 JSON。InvalidRequest

请求的内容无效。例如，当 UpdateJobExecution 请求包含无效的状态详细信息时，将返回此代码。消息包含有关错误的详细信息。

InvalidStateTransition

更新尝试将任务执行更改为某个状态，但该状态由于任务执行的当前状态而无效 (例如，尝试将处于 SUCCESS 状态的请求更改为 IN_PROGRESS 状态)。在这种情况下，错误消息的正文还包含 executionState 字段。

ResourceNotFound

请求主题所指定的 JobExecution 不存在。

299


VersionMismatch

请求中指定的预期版本与 Jobs 中的任务执行版本不匹配。在这种情况下，错误消息的正文还包含 executionState 字段。

InternalError

处理请求时出现内部错误。RequestThrottled

请求已被阻止。TerminalStateReached

在处于最终状态的任务上执行描述任务的命令时发生。message

错误消息字符串。clientToken

用于将请求与其答复关联起来的任意字符串。timestamp

用自纪元以来的毫秒数表示的时间。executionState

一个 JobExecutionState (p. 298) 对象。仅在 code 字段具有 InvalidStateTransition或 VersionMismatch 值时包含此字段。在这些情况下，这使得不必执行单独的DescribeJobExecution 请求以获取当前任务执行状态数据。

设备命令可通过 MQTT 和 HTTPS 协议使用以下命令。

GetPendingJobExecutions

GetPendingJobExecutions 命令

获取未处于最终状态的事物的所有任务列表。MQTT (11)

要调用此 API，请在 $aws/things/thingName/jobs/get 上发布消息。

请求负载：

{ "clientToken": "string" }

clientToken

可选。用于将请求和响应关联起来的客户端令牌。在此处输入任意值，它将反映在响应中。

要接收响应，请订阅：

• $aws/things/thingName/jobs/get/accepted ...和...• $aws/things/thingName/jobs/get/rejected ...或者...

300


• $aws/things/thingName/jobs/get/# ...for both...

响应负载：

{ "inProgressJobs" : [ JobExecutionSummary ... ], "queuedJobs" : [ JobExecutionSummary ... ], "timestamp" : 1489096425069, "clientToken" : "client-001"}

inPrograssJobs

状态为 IN_PROGRESS 的 JobExecutionSummary (p. 298) 对象的列表。queuedJobs

状态为 QUEUED 的 JobExecutionSummary (p. 298) 对象的列表。clientToken

用于将请求和响应关联起来的客户端令牌。timestamp

发送消息的时间 (用从纪元开始的秒数表示)。

HTTPS (11)

请求:

GET /things/thingName/jobs

thingName

与设备关联的事物的名称。

响应:

{ "inProgressJobs" : [ JobExecutionSummary ... ], "queuedJobs" : [ JobExecutionSummary ... ]}

inPrograssJobs

JobExecutionSummary (p. 298) 对象的列表。queuedJobs

JobExecutionSummary (p. 298) 对象的列表。

CLI (11)

摘要:

aws iot-jobs-data get-pending-job-executions \ --thing-name <value> \ [--cli-input-json <value>] \

301


[--generate-cli-skeleton]


{ "thingName": "string"}


名称类型描述

thingName 字符串


模式：[a-zA-Z0-9:_-]+

正在执行任务的事物的名称。

输出:

{ "inProgressJobs": [ { "jobId": "string", "queuedAt": "long", "startedAt": "long", "lastUpdatedAt": "long", "versionNumber": "long", "executionNumber": "long" } ], "queuedJobs": [ { "jobId": "string", "queuedAt": "long", "startedAt": "long", "lastUpdatedAt": "long", "versionNumber": "long", "executionNumber": "long" } ]}

cli 输出字段：

名称类型描述

inProgressJobs 列表

成员：JobExecutionSummary


状态为 IN_PROGRESS 的JobExecutionSummary 对象的列表。

JobExecutionSummary JobExecutionSummary

jobId 字符串


模式：[a-zA-Z0-9_-]+


302


名称类型描述

queuedAt long 任务执行入队的时间，用从纪元开始的毫秒数表示。

startedAt long



lastUpdatedAt long 上次更新任务执行的时间，用从纪元开始的毫秒数表示。

versionNumber long 任务执行的版本。每次 AWS IoTJobs 从设备收到更新时，任务执行版本会递增。




queuedJobs 列表



状态为 QUEUED 的JobExecutionSummary 对象的列表。


jobId 字符串


模式：[a-zA-Z0-9_-]+



startedAt long








StartNextPendingJobExecution

StartNextPendingJobExecution 命令

获取并启动事物的下一个待处理 (状态 IN_PROGRESS 或 QUEUED) 任务执行。

• 首先返回状态为 IN_PROGRESS 的所有任务执行。• 按任务执行的创建顺序返回这些执行。

303


• 如果下一个待处理任务执行的状态为 QUEUED，则其状态将更改为 IN_PROGRESS，并且任务执行的状态详细信息将设定为指定内容。

• 如果下一个待处理任务执行已处于 IN_PROGRESS 状态，则不会更改其状态。• 如果没有待处理的任务执行，则响应不包括 execution 字段。

MQTT (12)

要调用此 API，请在 $aws/things/thingName/jobs/start-next 上发布消息。

请求负载：

{ "statusDetails": { "string": "job-execution-state" ... }, "clientToken": "string"}

statusDetails

描述任务执行状态的名称/值对的集合。如果未指定，则 statusDetails 保持不变。clientToken

用于将请求和响应关联起来的客户端令牌。在此处输入任意值，它将反映在响应中。


• $aws/things/thingName/jobs/start-next/accepted ...和...• $aws/things/thingName/jobs/start-next/rejected ...或者...• $aws/things/thingName/jobs/start-next/# ...for both...

响应负载：

{ "execution" : JobExecutionData, "timestamp" : timestamp, "clientToken" : "string"}

execution

一个 JobExecution (p. 297) 对象。例如：

{ "execution" : { "jobId" : "022", "thingName" : "MyThing", "jobDocument" : "< contents of job document >", "status" : "IN_PROGRESS", "queuedAt" : 1489096123309, "lastUpdatedAt" : 1489096123309, "versionNumber" : 1, "executionNumber" : 1234567890 }, "clientToken" : "client-1", "timestamp" : 1489088524284,

304


}

timestamp

将消息发送到设备的时间 (用从纪元开始的秒数表示)。clientToken

用于将请求和响应关联起来的客户端令牌。

HTTPS (12)

请求:

PUT /things/thingName/jobs/$next{ "statusDetails": { "string": "string" ... }}

thingName

与设备关联的事物的名称。statusDetails

描述任务执行状态的名称/值对的集合。如果未指定，则 statusDetails 保持不变。

响应:

{ "execution" : JobExecution }

execution

一个 JobExecution (p. 297) 对象。例如：

{ "execution" : { "jobId" : "022", "thingName" : "MyThing", "jobDocument" : "< contents of job document >", "status" : "IN_PROGRESS", "queuedAt" : 1489096123309, "lastUpdatedAt" : 1489096123309, "versionNumber" : 1, "executionNumber" : 1234567890 }, "clientToken" : "client-1", "timestamp" : 1489088524284,}

CLI (12)

摘要:

aws iot-jobs-data start-next-pending-job-execution \

305


--thing-name <value> \ [--status-details <value>] \ [--cli-input-json <value>] \ [--generate-cli-skeleton]


{ "thingName": "string", "statusDetails": { "string": "string" }}


名称类型描述

thingName 字符串


模式：[a-zA-Z0-9:_-]+


statusDetails map

键：DetailsKey

值：DetailsValue

描述任务执行状态的名称/值对的集合。如果未指定，则statusDetails 保持不变。



模式：[a-zA-Z0-9:_-]+



模式：[^\\p{C}]*+

输出:

{ "execution": { "jobId": "string", "thingName": "string", "status": "string", "statusDetails": { "string": "string" }, "queuedAt": "long", "startedAt": "long", "lastUpdatedAt": "long", "versionNumber": "long", "executionNumber": "long", "jobDocument": "string" }}

306


cli 输出字段：

名称类型描述

execution JobExecution JobExecution 对象。

jobId 字符串


模式：[a-zA-Z0-9_-]+


thingName 字符串


模式：[a-zA-Z0-9:_-]+


status 字符串




statusDetails map

键：DetailsKey

值：DetailsValue




模式：[a-zA-Z0-9:_-]+



模式：[^\\p{C}]*+


startedAt long




versionNumber long 任务执行的版本。每次设备更新任务执行版本时，版本将递增。




307


名称类型描述

jobDocument 字符串


任务文档的内容。

DescribeJobExecution

DescribeJobExecution 命令

获取有关任务执行的详细信息。

您可以将 jobId 设置为 $next 以返回事物的下一个待处理 (状态 IN_PROGRESS 或 QUEUED) 任务执行。

MQTT (13)

要调用此 API，请在 $aws/things/thingName/jobs/jobId/get 上发布消息。

请求负载：

{ "executionNumber": "long", "includeJobDocument": "boolean", "clientToken": "string" }

thingName

与设备关联的事物的名称。jobId

创建此任务时向其分配的唯一标识符。

或使用 $next 返回事物的下一个待处理 (状态 IN_PROGRESS 或 QUEUED) 任务执行。在此情况下，首先返回状态为 IN_PROGRESS 的所有任务执行。按任务执行的创建顺序返回这些执行。

executionNumber

可选。标识特定设备上的特定任务执行的数字。如果未指定，则返回最新的任务执行。includeJobDocument

可选。设置为 true 时，响应将包含任务文档。默认为 true。clientToken



• $aws/things/thingName/jobs/jobId/get/accepted ...和...• $aws/things/thingName/jobs/jobId/get/rejected ...或者...• $aws/things/thingName/jobs/jobId/get/# ...for both...

响应负载：

{

308


"execution" : JobExecutionData, "timestamp": "timestamp", "clientToken": "string"}

execution

一个 JobExecution (p. 297) 对象。timestamp

发送消息的时间 (用从纪元开始的秒数表示)。clientToken


HTTPS (13)

任务的执行状态必须为 QUEUED 或 IN_PROGRESS。

请求:

GET /things/thingName/jobs/jobId?executionNumber=executionNumber&includeJobDocument=includeJobDocument

thingName

与设备关联的事物的名称。jobId


或使用 $next 返回事物的下一个待处理 (状态 IN_PROGRESS 或 QUEUED) 任务执行。在此情况下，首先返回状态为 IN_PROGRESS 的所有任务执行。按任务执行的创建顺序返回这些执行。

includeJobDocument

可选。设置为 true 时，响应将包含任务文档。默认为 false。executionNumber

可选。标识特定设备上的特定任务执行的数字。如果未指定，则返回最新的任务执行。

响应:

{ "execution" : JobExecution,}

execution

一个 JobExecution (p. 297) 对象。

CLI (13)

任务的执行状态必须为 QUEUED 或 IN_PROGRESS。

309


摘要:

aws iot-jobs-data describe-job-execution \ --job-id <value> \ --thing-name <value> \ [--include-job-document | --no-include-job-document] \ [--execution-number <value>] \ [--cli-input-json <value>] \ [--generate-cli-skeleton]


{ "jobId": "string", "thingName": "string", "includeJobDocument": "boolean", "executionNumber": "long"}


名称类型描述

jobId 字符串

模式：[a-zA-Z0-9_-]+|^$next

在此任务创建时分配给它的唯一标识符，或者用于返回事物的下一个待处理 (状态IN_PROGRESS 或 QUEUED)任务执行的 $next。在此情况下，首先返回状态为IN_PROGRESS 的所有任务执行。按任务执行的创建顺序返回这些执行。

thingName 字符串


模式：[a-zA-Z0-9:_-]+

与正在运行任务执行的设备关联的事物名称。

includeJobDocument 布尔值

java 类：java.lang.Boolean

可选。设置为 true 时，响应将包含任务文档。默认为 false。




输出:

{ "execution": { "jobId": "string", "thingName": "string", "status": "string", "statusDetails": { "string": "string" }, "queuedAt": "long", "startedAt": "long",

310


"lastUpdatedAt": "long", "versionNumber": "long", "executionNumber": "long", "jobDocument": "string" }}

cli 输出字段：

名称类型描述

execution JobExecution 包含有关任务执行的数据。

jobId 字符串


模式：[a-zA-Z0-9_-]+


thingName 字符串


模式：[a-zA-Z0-9:_-]+


status 字符串




statusDetails map

键：DetailsKey

值：DetailsValue




模式：[a-zA-Z0-9:_-]+



模式：[^\\p{C}]*+


startedAt long




311


名称类型描述








UpdateJobExecution

UpdateJobExecution 命令

更新任务执行的状态。MQTT (14)

要调用此 API，请在 $aws/things/thingName/jobs/jobId/update 上发布消息。

请求负载：

{ "status": "job-execution-state", "statusDetails": { "string": "string" ... }, "expectedVersion": "number", "executionNumber": "long", "includeJobExecutionState": "boolean", "includeJobDocument": "boolean", "clientToken": "string"}

status

任务执行的新状态 (IN_PROGRESS、FAILED、SUCCEEDED 或 REJECTED)。这必须在每次更新时指定。

statusDetails

描述任务执行状态的名称/值对的集合。如果未指定，则 statusDetails 保持不变。expectedVersion

任务执行的预期当前版本。每次更新任务执行时，其版本将递增。如果存储在 Jobs 中的任务执行版本不匹配，则更新将被拒绝并出现 VersionMismatch 错误，并且将返回包含当前任务执行状态数据的 ErrorResponse (p. 299)。(这样就不必执行单独的 DescribeJobExecution 请求以获取任务执行状态数据。)

executionNumber

可选。标识特定设备上的特定任务执行的数字。如果未指定，则使用最新的任务执行。includeJobExecutionState

可选。在包含此项并设置为 true 时，响应将包含 JobExecutionState 字段。默认为 false。

312


includeJobDocument

可选。在包含此参数且设置为 true 时，响应将包含 JobDocument。默认为 false。clientToken



• $aws/things/thingName/jobs/jobId/update/accepted ...和...• $aws/things/thingName/jobs/jobId/update/rejected ...或者...• $aws/things/thingName/jobs/jobId/update/# ...for both...

响应负载：

{ "executionState": JobExecutionState, "jobDocument": "string", "timestamp": timestamp, "clientToken": "string"}

executionState

一个 JobExecutionState (p. 298) 对象。jobDocument

一个任务文档 (p. 251)对象。timestamp

发送消息的时间 (用从纪元开始的秒数表示)。clientToken


HTTPS (14)

请求:

POST /things/thingName/jobs/jobId{ "status": "job-execution-state", "statusDetails": { "string": "string" ... }, "expectedVersion": "number", "includeJobExecutionState": "boolean", "includeJobDocument": "boolean", "executionNumber": "long" }

thingName


313


jobId

创建此任务时向其分配的唯一标识符。status

任务执行的新状态 (IN_PROGRESS、FAILED、SUCCEEDED 或 REJECTED)。这必须在每次更新时指定。

statusDetails

可选。描述任务执行状态的名称/值对的集合。如果未指定，则 statusDetails 保持不变。expectedVersion

可选。任务执行的预期当前版本。每次更新任务执行时，其版本将递增。如果存储在 Jobs 中的任务执行版本不匹配，则更新将被拒绝并出现 VersionMismatch 错误，并且将返回包含当前任务执行状态数据的 ErrorResponse (p. 299)。(这样就不必执行单独的 DescribeJobExecution 请求以获取任务执行状态数据。)

includeJobExecutionState

可选。在包括此项并设置为 true 时，响应将包含 JobExecutionState 数据。默认为 false。includeJobDocument

可选。设置为 true 时，响应将包含任务文档。默认为 false。executionNumber

可选。标识特定设备上的特定任务执行的数字。

响应:

{ "executionState": JobExecutionState, "jobDocument": "string"}

executionState

一个 JobExecutionState (p. 298) 对象。jobDocument

任务文档 (p. 251)的内容。

CLI (14)

摘要:

aws iot-jobs-data update-job-execution \ --job-id <value> \ --thing-name <value> \ --status <value> \ [--status-details <value>] \ [--expected-version <value>] \ [--include-job-execution-state | --no-include-job-execution-state] \ [--include-job-document | --no-include-job-document] \ [--execution-number <value>] \ [--cli-input-json <value>] \ [--generate-cli-skeleton]

314



{ "jobId": "string", "thingName": "string", "status": "string", "statusDetails": { "string": "string" }, "expectedVersion": "long", "includeJobExecutionState": "boolean", "includeJobDocument": "boolean", "executionNumber": "long"}


名称类型描述

jobId 字符串


模式：[a-zA-Z0-9_-]+


thingName 字符串


模式：[a-zA-Z0-9:_-]+


status 字符串



任务执行的新状态(IN_PROGRESS、FAILED、SUCCESS或 REJECTED)。这必须在每次更新时指定。

statusDetails map

键：DetailsKey

值：DetailsValue

可选。描述任务执行状态的名称/值对的集合。如果未指定，则statusDetails 保持不变。



模式：[a-zA-Z0-9:_-]+



模式：[^\\p{C}]*+

expectedVersion long


可选。任务执行的预期当前版本。每次更新任务执行时，

315


名称类型描述其版本将递增。如果存储在Jobs 中的任务执行版本不匹配，则更新将被拒绝并出现VersionMismatch 错误，并且将返回包含当前任务执行状态数据的 ErrorResponse。(这样就不再需要执行单独的DescribeJobExecution 请求来获取任务执行状态数据。)

includeJobExecutionState 布尔值


可选。包括此项并设置为 true 时，响应将包含JobExecutionState 数据。默认为 false。







输出:

{ "executionState": { "status": "string", "statusDetails": { "string": "string" }, "versionNumber": "long" }, "jobDocument": "string"}

cli 输出字段：

名称类型描述

executionState JobExecutionState JobExecutionState 对象。

status 字符串




statusDetails map

键：DetailsKey

值：DetailsValue


316


名称类型描述



模式：[a-zA-Z0-9:_-]+



模式：[^\\p{C}]*+





JobExecutionsChanged

JobExecutionsChanged 消息

在事物的待处理任务执行列表中添加或删除任务执行时发送。MQTT (15)

主题: $aws/things/thingName/jobs/notify

消息负载：

{ "jobs" : { "JobExecutionState": [ JobExecutionSummary (p. 270) ... ] }, "timestamp": timestamp,}

HTTPS (15)

不可用。CLI (15)

不可用。

NextJobExecutionChanged

NextJobExecutionChanged 消息

当存在对事物的待处理任务执行列表中的下一个任务执行的更改 (由 jobId 为 $next 的DescribeJobExecution (p. 308) 定义) 时发送。当下一个任务的执行详细信息发送更改时不会发送此消息，而仅在将由 jobId 为 $next 的 DescribeJobExecution 返回的下一个任务发生更改时发送。考虑状态为 QUEUED 的任务执行 J1 和 J2。J1 是待处理任务执行列表中的下一个待处理任务执行。如果J2 的状态更改为 IN_PROGRESS，而 J1 的状态保持不变，则将发送此通知，并且此通知包含 J2 的详细信息。

317

AWS IoT 开发人员指南任务限制

MQTT (16)

主题: $aws/things/thingName/jobs/notify-next

消息负载：

{ "execution" : JobExecutionData (p. 297), "timestamp": timestamp,}

HTTPS (16)

不可用。CLI (16)

不可用。

任务限制要了解任务限制信息，请参阅 AWS General Reference 中的 AWS IoT 任务限制。

318

http://docs.aws.amazon.com/general/latest/gr/aws_service_limits.html#job-limits

AWS IoT 开发人员指南预配置模板

设备预配置要预配置设备，请创建一个描述您的设备所需的资源的模板。设备需要一个事物、一个证书以及一个或多个策略。事物是注册表中的一个条目，其中包含描述设备的属性。设备使用证书针对 AWS IoT 进行身份验证。策略确定设备在 AWS IoT 中可执行的操作。

模板包含在将模板用于预配置设备时替换的变量。字典 (映射) 用于为模板中使用的变量提供值。您可以使用同一个模板来预配置多个设备。只需在字典中为模板变量传递不同的值。

预配置模板预配置模板是一个 JSON 文档，该文档使用参数来描述设备与 AWS IoT 交互时必须使用的资源。模板包含两个部分：Parameters 和 Resources。

参数部分Parameters 部分声明在 Resources 部分中使用的参数。每个参数声明一个名称、一个类型以及一个可选的默认值。在随模板传入的字典不包含参数的值时，会使用默认值。模板文档的 Parameters 部分类似于以下所示：

"Parameters" : { "ThingName" : { "Type" : "String", }, "SerialNumber" : { "Type" : "String", }, "Location" : { "Type" : "String", "Default" : "WA" }, "CSR" : { "Type" : "String", } }

此模板片段声明四个参数：ThingName、SerialNumber、Location 和 CSR。所有这些参数均为 String类型。Location 参数声明了默认值 "WA"。

资源部分模板的 Resources 部分声明了设备与 AWS IoT 通信所需的资源：事物、证书以及一个或多个策略。每个资源指定一个逻辑名称、一个类型和一组属性。

您可以使用逻辑名称在模板的其他位置引用资源。

类型指定您所声明的资源的种类。有效类型为：

• AWS::IoT::Thing

• AWS::IoT::Certificate

319

AWS IoT 开发人员指南资源部分

• AWS::IoT::Policy

您指定的属性取决于所声明的资源的类型。

事物资源事物资源使用以下属性进行声明：

• ThingName: 字符串.• AttributePayload：名称/值对的列表。• ThingTypeName: 可选. 用于事物的关联事物类型的字符串。• ThingGroups: 可选. 事物所属的组的列表。

证书资源可以使用以下方法之一指定证书：

• 证书签名请求 (CSR)。• 现有设备证书的证书 ID。• 使用注册到 AWS IoT 的 CA 证书创建的设备证书。如果您有多个 CA 证书注册到相同主题字段，则还必须

传入用于对设备证书进行签名的 CA 证书。

Note

当您在模板中声明证书时，请只使用前述方法之一。如果使用 CSR，就不能同时指定证书 ID 或设备证书。

有关证书和 AWS IoT 的更多信息，请参阅 AWS IoT 和证书。

证书资源使用以下属性进行声明：

• CertificateSigningRequest: 字符串.• CertificatePem: 字符串.• CACertificatePem: 字符串.• Status: 可选. 字符串，可以是以下值之一：ACTIVE、INACTIVE、PENDING_ACTIVATION。默认值为

ACTIVE。

策略资源策略资源使用以下属性之一进行声明：

• PolicyName: 可选. 字符串。默认值为策略文档的哈希值。• PolicyDocument：字符串化的 JSON 对象。可选。如果未提供 PolicyDocument，则必须已经创建了

策略。

Note

如果存在 Policy 部分，则必须指定 PolicyName 或 PolicyDocument，但不能同时指定。

覆盖设置如果模板指定了已经存在的资源，则使用 OverrideSettings 部分可以指定要采取的操作：

320

http://docs.aws.amazon.com/iot/latest/developerguide/x509-certs.html

AWS IoT 开发人员指南资源部分

DO_NOTHING

将资源保留为原样。REPLACE

使用在模板中指定的资源替换该资源。FAIL

导致请求失败，出现 ResourceConflictsException。MERGE

仅对 thing 的 ThingGroups 和 AttributePayload 属性有效。将事物的现有属性或组成员资格与模板中指定的同等内容合并。

资源示例以下模板片段声明了一个事物、一个证书和一个策略：

"Resources" : { "thing" : { "Type" : "AWS::IoT::Thing", "Properties" : { "ThingName" : {"Ref" : "ThingName"}, "AttributePayload" : { "version" : "v1", "serialNumber" : {"Ref" : "SerialNumber"}}, "ThingTypeName" : "lightBulb-versionA", "ThingGroups" : ["v1-lightbulbs", {"Ref" : "Location"}] }, "OverrideSettings" : { "AttributePayload" : "MERGE", "ThingTypeName" : "REPLACE", "ThingGroups" : "DO_NOTHING" } }, "certificate" : { "Type" : "AWS::IoT::Certificate", "Properties" : { "CertificateSigningRequest": {"Ref" : "CSR"}, "Status" : "ACTIVE" }, "OverrideSettings" : { "Status" : "DO_NOTHING" } }, "policy" : { "Type" : "AWS::IoT::Policy", "Properties" : { "PolicyDocument" : "{ \"Version\": \"2012-10-17\", \"Statement\": [{ \"Effect\": \"Allow\", \"Action\":[\"iot:Publish\"], \"Resource\": [\"arn:aws:iot:us-east-1:123456789012:topic/foo/bar\"] }] }" } } }

使用以下项声明事物：

• 逻辑名称 "thing"。• 类型 AWS::IoT::Thing。

321

AWS IoT 开发人员指南模板示例

• 一组事物属性。

事物属性包括事物名称、一组属性、一个事物类型名称 (可选) 以及事物所属的事物组列表 (可选)。

使用 {"Ref": "<parameter-name>"} 引用参数。评估模板时，使用随模板传入的字典中提供的参数值来替换参数。

使用以下项声明证书：

• 逻辑名称 "certificate"。• 类型 AWS::IoT::Certificate。• 一组属性。

属性包括证书的 CSR 并将状态设置为 ACTIVE。CSR 文本作为随模板传入的字典中的参数传递。

使用以下项声明策略：

• 逻辑名称 "policy"。• 类型 AWS::IoT::Policy。• 现有策略的名称或策略文档的名称。

模板示例以下 JSON 文件是一个完整预配置模板的示例：

(请注意，PolicyDocument 字段值必须是字符串化 JSON 对象。)

{ "Parameters" : { "ThingName" : { "Type" : "String" }, "SerialNumber" : { "Type" : "String" }, "Location" : { "Type" : "String", "Default" : "WA" }, "CSR" : { "Type" : "String" } }, "Resources" : { "thing" : { "Type" : "AWS::IoT::Thing", "Properties" : { "ThingName" : {"Ref" : "ThingName"}, "AttributePayload" : { "version" : "v1", "serialNumber" : {"Ref" : "SerialNumber"}}, "ThingTypeName" : "lightBulb-versionA", "ThingGroups" : ["v1-lightbulbs", {"Ref" : "Location"}] } }, "certificate" : {

322

AWS IoT 开发人员指南以编程方式预配置

"Type" : "AWS::IoT::Certificate", "Properties" : { "CertificateSigningRequest": {"Ref" : "CSR"}, "Status" : "ACTIVE" } }, "policy" : { "Type" : "AWS::IoT::Policy", "Properties" : { "PolicyDocument" : "{ \"Version\": \"2012-10-17\", \"Statement\": [{ \"Effect\": \"Allow\", \"Action\":[\"iot:Publish\"], \"Resource\": [\"arn:aws:iot:us-east-1:123456789012:topic/foo/bar\"] }] }" } } } }

以编程方式预配置要预配置事物，请使用 RegisterThing API 或 register-thing CLI 命令。register-thing CLI 命令接受以下参数：

--template-body

预配置模板。--parameters

在预配置模板中使用的参数的名称/值对列表，采用 JSON 格式。例如：{"ThingName" :"MyProvisionedThing", "CSR" : "<csr-text>"}

请参阅预配置模板 (p. 319)。

RegisterThing 或 register-thing 返回资源的 ARN 以及它创建的证书的文本：

{ "certificatePem": "<certificate-text>", "resourceArns": { "PolicyLogicalName": "arn:aws:iot:us-west-2:123456789012:policy/2A6577675B7CD1823E271C7AAD8184F44630FFD7", "certificate": "arn:aws:iot:us-west-2:123456789012:cert/cd82bb924d4c6ccbb14986dcb4f40f30d892cc6b3ce7ad5008ed6542eea2b049", "thing": "arn:aws:iot:us-west-2:123456789012:thing/MyProvisionedThing" }}

如果在字典中省略了参数，则使用默认值。如果未指定默认值，则不使用值来替换参数。

即时预配置您可在设备首次尝试连接到 AWS IoT 时对设备进行预配置。即时预配置 (JITP) 设置在 CA 证书上进行。您必须启用自动注册，并将预配置模板与用于对设备证书 (您正用于预配置设备的设备证书) 进行签名的 CA 证书关联。

323

http://docs.aws.amazon.com/iot/latest/apireference/API_RegisterThing.html


AWS IoT 开发人员指南批量配置

您可以使用 RegisterCACertificate API 或 register-ca-certificate CLI 命令，在注册新 CA 证书时执行这些设置。

aws iot register-ca-certificate --ca-certificate <your-ca-cert> --verification-cert <your-verification-cert> --set-as-active --allow-auto-registration --registration-config <your-template>

有关更多信息，请参阅注册 CA 证书。

您还可以使用 UpdateCACertificate API 或 update-ca-certificate CLI 命令来更新 CA 证书的设置：

$ aws iot update-ca-certificate --cert-id <caCertificateId> --new-auto-registration-status ENABLE --registration-config <your-template>

当设备尝试使用由已注册 CA 证书签名的证书连接到 AWS IoT 时，AWS IoT 会从 CA 证书加载模板并使用模板调用 RegisterThing。

AWS IoT 定义了可在预配置模板中声明和引用的下列参数：

• AWS::IoT::Certificate::Country

• AWS::IoT::Certificate::Organization

• AWS::IoT::Certificate::OrganizationalUnit

• AWS::IoT::Certificate::DistinguishedNameQualifier

• AWS::IoT::Certificate::StateName

• AWS::IoT::Certificate::CommonName

• AWS::IoT::Certificate::SerialNumber

• AWS::IoT::Certificate::Id

这些预配置模板参数的值是从正在预配置的设备的证书中提取的。

批量配置您可以使用 start-thing-registration-task 命令批量预配置事物。此命令接受预配置模板、AmazonS3 存储桶名称、键名以及允许访问 Amazon S3 存储桶中文件的角色 ARN。Amazon S3 存储桶中的文件包含用于替换模板中参数的值。该文件必须为以换行符分隔的 JSON 文件。每一行包含用于预配置单个设备的所有参数值。例如：

{"ThingName": "foo", "SerialNumber": "123", "CSR": "csr1"}{"ThingName": "bar", "SerialNumber": "456", "CSR": "csr2"}

此外，以下批量预置相关的 API 可能会有用：

• ListThingRegistrationTasks – 列出当前的批量事物预置任务。• DescribeThingRegistrationTask – 提供有关特定批量事物预置任务的信息。• StopThingRegistrationTask – 停止批量事物预置任务。• ListThingRegistrationTaskReports – 用于检查批量事物预置任务的结果和/或故障。

Note

一次只能运行一个批量预预置操作任务 (每个账户)。

324

http://docs.aws.amazon.com/iot/latest/apireference/API_RegisterCACertificate.html

AWS IoT ??????device-certs-your-own.html#register-CA-cert

http://docs.aws.amazon.com/iot/latest/apireference/API_UpdateCACertificate.html


http://docs.aws.amazon.com/iot/latest/apireference/API_StartThingRegistrationTask.html

http://docs.aws.amazon.com/iot/latest/apireference/API_ListThingRegistrationTasks.html

http://docs.aws.amazon.com/iot/latest/apireference/API_DescribeThingRegistrationTask.html

http://docs.aws.amazon.com/iot/latest/apireference/API_StopThingRegistrationTask.html

http://docs.aws.amazon.com/iot/latest/apireference/API_ListThingRegistrationTaskReports.html

AWS IoT 开发人员指南管理索引

机群索引服务机群索引是一项托管服务，让您可以对云中的注册表和影子数据进行索引编制和搜索。设置机群索引之后，这项服务将管理对您的所有注册表和影子更新的索引编制。您可以使用基于流行的开源搜索引擎 ApacheLucene 的简单查询语言，在这些数据中搜索。

要开始使用，请启用索引，此时 AWS IoT 将为您的事物创建索引。在索引处于活动状态之后，您可以对索引运行查询。AWS IoT 使用您最新的数据保持索引的持续更新。

您可以使用 AWS IoT 控制台管理您的索引配置和运行您的搜索查询。如果您更喜欢以编程方式访问，则可以使用 AWS 开发工具包或 AWS CLI。

请注意，除了 AWS IoT 服务的标准费用之外，使用此服务需要额外支付费用，这些费用在 AWS IoT 设备管理定价中进行了简要介绍。

管理索引AWS_Things 是为您的所有事物创建的索引。您可以控制仅为注册表数据编制索引还是同时为注册表和影子数据编制索引。

启用索引您可以创建 AWS_Things 索引并使用 UpdateIndexingConfiguration API 中的 thing-indexing-configuration 设置来控制其配置。您可以使用 GetIndexingConfiguration API 检索当前索引配置。

以下命令说明了如何使用 get-indexing-configuration CLI 命令来检索当前事物索引配置：

aws iot get-indexing-configuration{ "thingIndexingConfiguration": { "thingIndexingMode": "OFF" }}

您可以使用 AWS IoT update-indexing-configuration CLI 命令更新事物索引配置：

aws iot update-indexing-configuration --thing-indexing-configuration thingIndexingMode=REGISTRY_AND_SHADOW

thing-indexing-configuration 的有效值为：

OFF

无索引/删除索引。REGISTRY

创建或配置 AWS_Things 索引以仅为注册表数据编制索引。REGISTRY_AND_SHADOW

创建或配置 AWS_Things 索引以仅为注册表和影子数据编制索引。

325


https://aws.amazon.com/iot-device-management/pricing

https://aws.amazon.com/iot-device-management/pricing

http://docs.aws.amazon.com/iot/latest/apireference/API_UpdateIndexingConfiguration.html

http://docs.aws.amazon.com/iot/latest/apireference/API_GetIndexingConfiguration.html

AWS IoT 开发人员指南描述索引

Note

影子通常是加密的。但是，如果您决定在 AWS_Things 索引中包含影子，数据将被解密以便为影子编制索引。

描述索引以下命令说明了如何使用 describe-index CLI 命令来检索索引的当前状态：

aws iot describe-index --index-name "AWS_Things"{ "indexName": "AWS_Things", "indexStatus": "BUILDING", "schema": "REGISTRY_AND_SHADOW"}

首次启用索引时，AWS IoT 将构建您的索引。如果 indexStatus 为 BUILDING，您无法查询索引。架构指示要索引的数据类型是 REGISTRY 还是 REGISTRY_AND_SHADOW。

更改索引的配置会导致重新生成索引。在此过程中，indexStatus 为 REBUILDING。在重新生成期间，您可以针对现有数据执行查询。例如，如果您将索引配置从 REGISTRY 更改为 REGISTRY_AND_SHADOW，同时正在重新生成索引，则您可以查询注册表数据，包括最新的更新。但是，在重新生成操作完成之前，无法查询影子数据。生成或重新生成索引所需的时间量取决于数据量。

什么是编制索引请注意以下限制：

具有复杂类型的影子字段：

只有字段的值是简单类型或完全由简单类型组成的数组时，才会对影子字段编制索引。(“简单类型”是指一个字符串、数字或文本 true、false 或 null 之一。) 如果一个字段的值本身就是一个 JSON 对象或一个包含对象的数组，则不会在该字段上进行索引编制。例如，给定的影子状态：

{ "state": { "reported": { "switched": "ON", "colors": [ "RED", "GREEN", "BLUE" ], "palette": [ { "name": "RED", "intensity": 124 }, { "name": "GREEN", "intensity": 68 }, { "name": "BLUE", "intensity": 201 } ] } }}

字段 "palette" 的值将不会编制索引，因为它是一个其项目为“对象”的数组。字段“颜色”的值将会编制索引，因为数组中的每个值都是一个字符串。

326

AWS IoT 开发人员指南查询索引

影子元数据：

影子的元数据部分中的字段编制了索引，但仅当影子的 "state" 部分中的相应字段编制了索引时才这样。(在上面的示例中，影子的元数据部分中的“调色板”字段不会也编制索引。)

已注销的影子：

如果您使用尚未在您的 AWS IoT 账户中注册的事物名称创建影子 (使用 CreateThing)，则该影子中的字段将不会编制索引。

数字值：

如果编制索引的任何注册表或影子数据被服务识别为数值，则会对其照此编制索引。您可以针对数字值创建涉及范围和比较运算符的查询，例如 "attribute.foo<5" 或 "shadow.reported.foo:[75TO 80]"。要识别为数字，数据的值必须是有效的 JSON“数字”类型文本 (范围 -2^53...2^53-1 中的整数，或具有可选指数表示法的双精度浮点数) 或仅包含此类值的数组的一部分。

查询索引以下命令说明了如何使用 search-index CLI 命令来查询索引中的数据：

aws iot search-index --index-name "AWS_Things" --query-string "thingName:mything*"{ "things":[{ "thingName":"mything1", "thingGroupNames":[ "mygroup1" ], "thingId":"a4b9f759-b0f2-4857-8a4b-967745ed9f4e", "attributes":{ "attribute1":"abc" } }, { "thingName":"mything2", "thingTypeName":"MyThingType", "thingGroupNames":[ "mygroup1", "mygroup2" ], "thingId":"01014ef9-e97e-44c6-985a-d0b06924f2af", "attributes":{ "model":"1.2", "country":"usa" }, "shadow":{ "desired":{ "location":"new york", "myvalues":[3, 4, 5] }, "reported":{ "location":"new york", "myvalues":[1, 2, 3], "stats":{ "battery":78 } }, "metadata":{ "desired":{ "location":{ "timestamp":123456789 }, "myvalues":{

327

http://docs.aws.amazon.com/iot/latest/developerguide/thing-registry.html#create-thing

AWS IoT 开发人员指南查询语法

"timestamp":123456789 } }, "reported":{ "location":{ "timestamp":34535454 }, "myvalues":{ "timestamp":34535454 }, "stats":{ "battery":{ "timestamp":34535454 } } } }, "version":10, "timestamp":34535454 } }], "nextToken":"AQFCuvk7zZ3D9pOYMbFCeHbdZ+h=G"}

查询语法可使用类似 Lucene 的查询语法来指定查询。有关更多信息，请参阅 Apache 网站上的 Lucene 查询语法概览。

Lucene 查询语法支持以下功能：

• 术语和短语• 搜索字段• 前缀搜索• 范围搜索• 布尔运算符 AND、OR、NOT 和 –• 分组• 字段分组• 对特殊字符转义

Lucene 查询语法不支持以下功能：

• 前导通配符搜索 (例如“*xyz”)，搜索“*”将匹配所有事物• 正则表达式• 提升• 排名• 模糊搜索• 近似搜索• 排序• 聚合

关于查询语言需要注意的几点：

• 默认运算符为 AND。查询“thingName:abc thingType:xyz”等同于“thingName:abc AND thingType:xyz”。• 如果未指定字段，AWS IoT 将在所有字段中搜索术语。

328

https://lucene.apache.org/core/6_5_0/queryparser/org/apache/lucene/queryparser/classic/package-summary.html#Overview

https://lucene.apache.org/core/6_5_0/queryparser/org/apache/lucene/queryparser/classic/package-summary.html#Overview

AWS IoT 开发人员指南示例查询

• 所有字段名称均区分大小写。• 搜索不区分大小写。单词使用空格字符分隔，如 Java 的 Character.isWhitespace(int) 中所定义。• 影子数据的索引编制包括“reported”、“desired”、“delta”和“metadata”部分。• 影子和注册表版本不可搜索，但在响应中提供。• 查询中术语数量上限为 5 个。

示例查询查询在查询字符串中使用类似于 Lucene 的查询语法指定，并传递到 API。SearchIndex下表列出了一些示例查询字符串：

查询字符串结果

"abc" 在任意注册表或影子字段中查询“abc”。

"thingName:myThingName" 查询名为“myThingName”的事物。

"thingName:my*" 查询名称以“my”开头的事物。

"thingName:ab?" 查询名称为“ab”以及另外一个字符的事物，例如：“aba”、“abb”、“abc”等。

"attributes.myAttribute:75" 查询属性名为“MyAttribute”且属性值为 75 的事物。

"attributes.myAttribute:[75 TO 80]" 查询属性名为“MyAttribute”，且属性值在数字范围(75 – 80，含) 之内的事物。

"attributes.myAttribute:{75 TO 80]" 查询属性名为“MyAttribute”，且属性值在数字范围(大于 75 且小于等于 <80) 之内的事物。

'attributes.serialNumber["abcd" TO "abcf"]' 查询属性名为“serialNumber”，且属性值在字母数字字符串范围之内的事物。此查询将返回属性名为“serialNumber”，且其值为“abcd”、“abce”或“abcf”的事物。

"attributes.myAttribute:i*t" 查询属性名为“MyAttribute”，且其值为以“i”开头、以“t”结尾、中间有任意数量字符的事物。

"attributes.attr1:abc AND attributes.attr2<5 NOTattributes.attr3>10

使用布尔表达式组合术语来查询事物。此查询将返回具有下列特征的事物：属性名为“attr1”且值为“abc”；属性名为“attr2”且值小于 5；以及属性名为“attr3”且值不大于 10。

"shadow.hasDelta:true" 查询其影子具有增量元素的事物。

"-attributes.model:legacy" 查询属性模型不是“legacy”的事物。

"shadow.reported.stats.battery:(>70 AND <100) (v2| v3) -attributes.model:legacy"

查询具有以下特征的事物：

• 事物的影子 stats.battery 属性具有介于 70到 100 之间的值。

• 文本“v2”或“v3”出现在事物的名称、类型名称或属性值中。

• 事物的 model 属性未设置为“legacy”。

"shadow.reported.myvalues:2" 查询具有以下特征的事物：影子的“reported”部分中的 myvalues 数组包含值 2。

329

http://docs.aws.amazon.com/iot/latest/apireference/API_SearchIndex.html

AWS IoT 开发人员指南授权

查询字符串结果

"shadow.reported.location:* NOTshadow.desired.stats.battery:*"

查询具有以下特征的事物：

• 影子的 reported 部分中存在 location 属性。• 影子的 desired 部分中不存在 stats.battery

属性。

授权您可以指定事物索引作为 AWS IoT 策略操作中的资源 ARN：

操作资源

iot:SearchIndex 索引 ARN (例如，arn:aws:iot:<your-aws-region>:index/AWS_Things)。

iot:DescribeIndex 索引 ARN (例如，arn:aws:iot:<your-aws-region>:index/AWS_Things)。

330

AWS IoT 开发人员指南注册表事件

AWS IoT 事件AWS IoT 在发生特定事件时将发布事件消息。例如，在添加、更新或删除事物时，由注册表生成事件。每个事件将导致发送单个事件消息。事件消息通过 MQTT 随 JSON 负载一起发布。负载的内容取决于事件的类型。

您可以通过调用 UpdateEventConfigurations API 来控制发布哪些事件类型。

您可以通过调用 DescribeEventConfigurations API 来获取当前事件配置。

要接收事件消息，您的设备必须使用合适的策略，该策略允许设备连接到 AWS IoT 设备网关并订阅 MQTT事件主题。您还必须订阅合适的主题筛选器。

以下是接收生命周期事件时需要用到的策略的示例：

{ "Version":"2012-10-17", "Statement":[{ "Effect":"Allow", "Action":[ "iot:Subscribe", "iot:Receive" ], "Resource":[ "arn:aws:iot:region:account:/$aws/events/*" ] }]}

Note

保证事件消息发布一次。事件消息可能会多次发布。事件消息的顺序无法保证。

注册表事件在创建、更新或删除了事物、事物类型和事物组时，注册表将发布事件消息。注册表当前支持以下事件类型：

事物已创建/已更新/已删除

在创建、更新或删除了事物时，注册表将发布以下事件消息：• $aws/events/thing/<thingName>/created

• $aws/events/thing/<thingName>/updated

• $aws/events/thing/<thingName>/deleted


{ "eventType" : "thingEvent", "eventId" : "f5ae9b94-8b8e-4d8e-8c8f-b3266dd89853", "timestamp" : 1234567890123, "operation" : "CREATED|UPDATED|DELETED", "accountId" : "123456789012",

331

http://docs.aws.amazon.com/iot/latest/apireference/API_UpdateEventConfigurations.html

http://docs.aws.amazon.com/iot/latest/apireference/API_DescribeEventConfigurations.html


"thingId" : "b604f69c-aa9a-4d4a-829e-c480e958a0b5", "thingName" : "MyThing", "versionNumber" : 1, "thingTypeName" : null, "attributes": { "attribute3": "value3", "attribute1": "value1", "attribute2": "value2" }}

负载包含以下属性：eventType

设置为“thingEvent”。eventId

唯一事件 ID (字符串)。timestamp

事件发生的 UNIX 时间戳。operation

触发事件的操作。有效值为：• CREATED• UPDATED• DELETED

accountId

您的 AWS 账户 ID。thingId

要创建、更新或删除的事物的 ID。thingName

要创建、更新或删除的事物的名称。versionNumber

要创建、更新或删除的事物的版本。在创建事物时，此值设置为 1。每次更新事物时，此值增加 1。thingTypeName

与事物关联的事物类型 (如果存在)。否则为 null。个属性

与事物关联的名称/值对的集合。事物类型已创建/已弃用/已取消弃用/已删除

在创建、弃用、取消弃用或删除了事物类型时，注册表将发布以下事件消息：• $aws/events/thingType/<thingTypeName>/created

• $aws/events/thing/<thingTypeName>/updated

• $aws/events/thing/<thingTypeName>/deleted


{

332


"eventType" : "thingTypeEvent", "eventId" : "8827376c-4b05-49a3-9b3b-733729df7ed5", "timestamp" : 1234567890123, "operation" : "CREATED|UPDATED|DELETED", "accountId" : "123456789012", "thingTypeId" : "c530ae83-32aa-4592-94d3-da29879d1aac", "thingTypeName" : "MyThingType", "isDeprecated" : false|true, "deprecationDate" : null, "searchableAttributes" : [ "attribute1", "attribute2", "attribute3" ], "description" : "My thing type"}


设置为“thingTypeEvent”。eventId




accountId

您的 AWS 账户 ID。thingTypeId

要创建、弃用或删除的事物类型的 ID。thingTypeName

要创建、弃用或删除的事物类型的名称。isDeprecated

如果事物类型已弃用，则为 true。否则为 false。deprecationDate

弃用事物类型的 UNIX 时间戳。searchableAttributes

与可用于搜索的事物类型关联的名称/值对集合。description

事物类型的描述。事物类型已与某个事物关联/取消关联

当事物类型与某个事物关联或取消关联时，注册表将发布以下事件消息。• $aws/events/thingTypeAssociation/thing/<thingName>/<typeName>


333


{ "eventId" : "87f8e095-531c-47b3-aab5-5171364d138d", "eventType" : "THING_TYPE_ASSOCIATION_EVENT", "operation" : "CREATED|DELETED", "thingId" : "b604f69c-aa9a-4d4a-829e-c480e958a0b5", "thingName": "myThing", "thingTypeName" : "MyThingType", "timestamp" : 1234567890123,}

负载包含以下属性：eventId

唯一事件 ID (字符串)。eventType

设置为“THING_TYPE_ASSOCIATION_EVENT”。operation

触发事件的操作。有效值为：• CREATED• DELETED

thingId

已更改其类型关联的事物的 ID。thingName

已更改其类型关联的事物的名称。thingTypeName

已与事物关联或不再与事物关联的事物类型。timestamp

事件发生的 UNIX 时间戳。事物组已创建/已更新/已删除

在创建、更新或删除了事物组时，注册表将发布以下事件消息。• $aws/events/thingGroup/<groupName>/created

• $aws/events/thingGroup/<groupName>/updated

• $aws/events/thingGroup/<groupName>/deleted


{ "eventType" : "thingGroupEvent", "eventId" : "87f8e095-531c-47b3-aab5-5171364d138d", "timestamp" : 1234567890123, "operation" : "CREATED|UPDATED|DELETED", "accountId" : "123456789012", "thingGroupId" : "8f82a106-6b1d-4331-8984-a84db5f6f8cb", "thingGroupName" : "MyRootThingGroup", "versionNumber" : 1, "parentGroupName" : null, "parentGroupId" : null, "description" : "My root thing group", "rootToParentThingGroups" : null, "attributes" : {

334


"attribute1" : "value1", "attribute3" : "value3", "attribute2" : "value2" }}


设置为“thingGroupEvent”。eventId




accountId

您的 AWS 账户 ID。thingGroupId

要创建、更新或删除的事物组的 ID。thingGroupName

要创建、更新或删除的事物组的名称。versionNumber

事物组的版本。在创建事物组时，此值设置为 1。每次更新事物组时，此值增加 1。parentGroupName

父事物组的名称 (如果存在)。parentGroupId

父事物组的 ID (如果存在)。description

事物组的描述。rootToParentThingGroups

有关父事物组的信息数组。每个父事物组都有一个条目，以当前事物组的父级开始，继续直至达到根事物组。每个条目均包含事物组名称和事物组 ARN。

个属性

与事物组关联的名称/值对的集合。事物已添加到/删除自事物组

当事物已添加到事物组或从事物组中删除时，注册表将发布以下事件消息。• $aws/events/thingGroupMembership/thingGroup/<thingGroupName>/thing/<thingName>/added

335


• $aws/events/thingGroupMembership/thingGroup/<thingGroupName>/thing/<thingName>/removed


{ "eventType" : "thingGroupMembershipEvent", "eventId" : "d684bd5f-6f6e-48e1-950c-766ac7f02fd1", "timestamp" : 1234567890123, "operation" : "ADDED|REMOVED", "accountId" : "123456789012", "groupArn" : "arn:aws:iot:ap-northeast-2:123456789012:thinggroup/MyChildThingGroup", "groupId" : "06838589-373f-4312-b1f2-53f2192291c4", "thingArn" : "arn:aws:iot:ap-northeast-2:123456789012:thing/MyThing", "thingId" : "b604f69c-aa9a-4d4a-829e-c480e958a0b5", "membershipId" : "8505ebf8-4d32-4286-80e9-c23a4a16bbd8"}


设置为“thingGroupMembershipEvent”。eventId

事件 ID。timestamp


将事物添加到事物组中时为 ADDED。从事物组中删除事物时为 REMOVED。accountId

您的 AWS 账户 ID。groupArn

事物组的 ARN。groupId

组的 ID。thingArn

在事物组中添加或删除的事物的 ARN。thingId

在事物组中添加或删除的事物的 ID。membershipId

表示事物与事物组之间关系的 ID。将事物添加到事物组时生成此值。事物组已添加到/删除自事物组

当某个事物组已添加到另一个事物组或从另一个事物组中删除时，注册表将发布以下事件消息。• $aws/events/thingGroupHierarchy/thingGroup/<parentThingGroupName>/childThingGroup/<childThingGroupName>/added

• $aws/events/thingGroupHierarchy/thingGroup/<parentThingGroupName>/childThingGroup/<childThingGroupName>/removed

336



{ "eventType" : "thingGroupHierarchyEvent", "eventId" : "264192c7-b573-46ef-ab7b-489fcd47da41", "timestamp" : 1234567890123, "operation" : "ADDED|REMOVED", "accountId" : "123456789012", "thingGroupId" : "8f82a106-6b1d-4331-8984-a84db5f6f8cb", "thingGroupName" : "MyRootThingGroup", "childGroupId" : "06838589-373f-4312-b1f2-53f2192291c4", "childGroupName" : "MyChildThingGroup"}


设置为“thingGroupHierarchyEvent”。eventId

事件 ID。timestamp


将事物添加到事物组中时为 ADDED。从事物组中删除事物时为 REMOVED。accountId

您的 AWS 账户 ID。thingGroupId

父事物组的 ID。thingGroupName

父事物组的名称。childGroupId

子事物组的 ID。childGroupName

子事物组的名称。

任务事件当任务待处理、已完成或已取消时，或者设备在执行任务时报告成功或失败，Jobs 会发布到 MQTT 协议上的预留主题。设备或管理和监控应用程序可以通过订阅这些主题来跟踪任务的状态。

任务已完成/已取消

当任务已完成或已取消时，AWS IoT Jobs 会在 MQTT 主题上发布消息：• $aws/events/job/jobID/completed

• $aws/events/job/jobID/canceled

“已完成”消息包含以下示例负载：

337


{ "eventType": "JOB", "eventId": "7364ffd1-8b65-4824-85d5-6c14686c97c6", "timestamp": 1234567890, "operation": "completed", "jobId": "27450507-bf6f-4012-92af-bb8a1c8c4484", "status": "COMPLETED", "targetSelection": "SNAPSHOT|CONTINUOUS", "targets": [ "arn:aws:iot:us-east-1:123456789012:thing/a39f6f91-70cf-4bd2-a381-9c66df1a80d0", "arn:aws:iot:us-east-1:123456789012:thinggroup/2fc4c0a4-6e45-4525-a238-0fe8d3dd21bb" ], "description": "My Job Description", "completedAt": 1234567890123, "createdAt": 1234567890123, "lastUpdatedAt": 1234567890123, "jobProcessDetails": { "numberOfCanceledThings": 0, "numberOfRejectedThings": 0, "numberOfFailedThings": 0, "numberOfRemovedThings": 0, "numberOfSucceededThings": 3 }}

“已取消”消息包含以下示例负载：

{ "eventType": "JOB", "eventId": "568d2ade-2e9c-46e6-a115-18afa1286b06", "timestamp": 1234567890, "operation": "canceled", "jobId": "4d2a531a-da2e-47bb-8b9e-ff5adcd53ef0", "status": "CANCELED", "targetSelection": "SNAPSHOT|CONTINUOUS", "targets": [ "arn:aws:iot:us-east-1:123456789012:thing/Thing0-947b9c0c-ff10-4a80-b4b3-cd33d0145a0f", "arn:aws:iot:us-east-1:123456789012:thinggroup/ThingGroup1-95c644d5-1621-41a6-9aa5-ad2de581d18f" ], "description": "My job description", "createdAt": 1234567890123, "lastUpdatedAt": 1234567890123}

任务执行最终状态

当设备将任务执行更新为最终状态时，AWS IoT Jobs 会发布消息：• $aws/events/jobExecution/jobID/succeeded

• $aws/events/jobExecution/jobID/failed

• $aws/events/jobExecution/jobID/rejected

• $aws/events/jobExecution/jobID/canceled

• $aws/events/jobExecution/jobID/removed

或者，您也可以使用以下命令订阅所有这些项：• $aws/events/jobExecution/jobID/#


338


{ "eventType": "JOB_EXECUTION", "eventId": "cca89fa5-8a7f-4ced-8c20-5e653afb3572", "timestamp": 1234567890, "operation": "succeeded|failed|rejected|canceled|removed", "jobId": "154b39e5-60b0-48a4-9b73-f6f8dd032d27", "thingArn": "arn:aws:iot:us-east-1:123456789012:myThing/6d639fbc-8f85-4a90-924d-a2867f8366a7", "status": "SUCCEEDED|FAILED|REJECTED|CANCELED|REMOVED", "statusDetails": { "key": "value" }}

339

AWS IoT 开发人员指南适用于 Android 的 AWS 移动软件开发工具包

AWS IoT 软件开发工具包内容

• 适用于 Android 的 AWS 移动软件开发工具包 (p. 340)• Arduino Yún 软件开发工具包 (p. 340)• 适用于嵌入式 C 的 AWS IoT 设备软件开发工具包 (p. 340)• AWS IoT C++ 设备开发工具包 (p. 341)• 适用于 iOS 的 AWS 移动软件开发工具包 (p. 341)• 适用于 Java 的 AWS IoT 设备软件开发工具包 (p. 341)• 适用于 JavaScript 的 AWS IoT 设备软件开发工具包 (p. 341)• 适用于 Python 的 AWS IoT 设备软件开发工具包 (p. 341)

AWS IoT 设备软件开发工具包帮助您快速轻松地将设备连接至 AWS IoT。AWS IoT 设备软件开发工具包包括开源库、开发人员指南 (含示例) 和移植指南，便于您在自己选择的硬件平台上构建富有创新精神的 IoT 产品或解决方案。

适用于 Android 的 AWS 移动软件开发工具包适用于 Android 的 AWS 软件开发工具包包含为开发人员提供的库、示例和文档，以便于他们使用 AWS 构建联网的移动应用程序。此软件开发工具包也支持调用 AWS IoT API。有关更多信息，请参阅下列内容：

• GitHub 上适用于 Android 的 AWS 移动软件开发工具包• 适用于 Android 的 AWS 移动软件开发工具包自述文件• 适用于 Android 的 AWS 移动软件开发工具包示例

Arduino Yún 软件开发工具包开发人员可以使用 AWS IoT Arduino Yún 开发工具包将与 Arduino Yún 兼容的设备连接到 AWS IoT。通过将设备连接到 AWS IoT，用户可以安全地使用由 AWS IoT 提供的消息代理、规则和影子，以及 AWSLambda、Kinesis 和 Amazon S3 等其他 AWS 服务。有关更多信息，请参阅下列内容：

• GitHub 上的 Arduino Yún 软件开发工具包• Arduino Yún 软件开发工具包自述文件

适用于嵌入式 C 的 AWS IoT 设备软件开发工具包适用于嵌入式 C 的 AWS IoT 设备软件开发工具包是 C 源文件的集合，可以在嵌入式应用程序中使用，以安全地连接到 AWS IoT 平台。它包括传输客户端、TLS 实施以及它们的使用示例。它还支持特定于 AWS IoT的功能，例如，用于访问 Device Shadow 服务的 API。它以源代码的形式分发，旨在与应用程序代码、其他库和 RTOS 一起内置到客户的固件中。有关更多信息，请参阅下列内容：

• 适用于嵌入式 C 的 AWS IoT 设备软件开发工具包 GitHub• 适用于嵌入式 C 的 AWS IoT 设备软件开发工具包自述文件• 适用于嵌入式 C 的 AWS IoT 设备软件开发工具包移植指南

340

https://github.com/aws/aws-sdk-android

https://github.com/aws/aws-sdk-android/blob/master/README.md

https://github.com/awslabs/aws-sdk-android-samples

https://github.com/aws/aws-iot-device-sdk-arduino-yun

https://github.com/aws/aws-iot-device-sdk-arduino-yun/blob/master/README.md

https://github.com/aws/aws-iot-device-sdk-embedded-C

https://github.com/aws/aws-iot-device-sdk-embedded-C/blob/master/README.md

https://github.com/aws/aws-iot-device-sdk-embedded-C/blob/master/PortingGuide.md

AWS IoT 开发人员指南AWS IoT C++ 设备开发工具包

AWS IoT C++ 设备开发工具包AWS IoT C++ 设备开发工具包使得开发人员可以使用 AWS 和 AWS IoT API 生成互连应用程序。特别是，此开发工具包面向没有资源限制且需要高级功能 (例如，消息队列、多线程支持和最新的语言功能) 的设备设计。有关更多信息，请参阅下列内容：

• AWS IoT C++ 设备开发工具包 GitHub• AWS IoT C++ 设备开发工具包自述文件

适用于 iOS 的 AWS 移动软件开发工具包适用于 iOS 的 AWS 软件开发工具包是开源的软件开发套件，依据 Apache 开源许可分发。适用于 iOS 的软件开发工具包为开发人员提供库、代码示例和文档，以便于他们使用 AWS 构建联网的移动应用程序。此软件开发工具包也支持调用 AWS IoT API。

• GitHub 上适用于 iOS 的 AWS 软件开发工具包• 适用于 iOS 的 AWS 软件开发工具包自述文件• 适用于 iOS 的 AWS 软件开发工具包示例

适用于 Java 的 AWS IoT 设备软件开发工具包借助适用于 Java 的 AWS IoT 设备开发工具包，Java 开发人员能够通过 MQTT 或基于 WebSocket协议的 MQTT 来访问 AWS IoT 平台。该开发工具包内置有影子支持。您可以使用 HTTP 方法 (包括GET、UPDATE 和 DELETE) 访问影子。该开发工具包还支持简化的影子访问模型，开发人员只需要使用getter 和 setter 方法即可与影子交换数据，而不必对任何 JSON 文档进行序列化或反序列化。有关更多信息，请参阅下列内容：

• GitHub 上适用于 Java 的 AWS IoT 设备软件开发工具包• 适用于 Java 的 AWS IoT 设备软件开发工具包自述文件

适用于 JavaScript 的 AWS IoT 设备软件开发工具包借助 aws-iot-device-sdk.js 软件包，开发人员可以编写使用 MQTT 或基于 WebSocket 协议的 MQTT 来访问AWS IoT 的 JavaScript 应用程序。它可用于 Node.js 环境和浏览器应用程序。有关更多信息，请参阅下列内容：

• GitHub 上适用于 JavaScript 的 AWS IoT 设备软件开发工具包• 适用于 JavaScript 的 AWS IoT 设备软件开发工具包自述文件

适用于 Python 的 AWS IoT 设备软件开发工具包借助适用于 Python 的 AWS IoT 设备开发工具包，开发人员可以编写 Python 脚本，以使用其设备通过MQTT 或基于 WebSocket 协议的 MQTT 来访问 AWS IoT 平台。通过将设备连接到 AWS IoT，用户可以安全地使用由 AWS IoT 提供的消息代理、规则和影子，以及 AWS Lambda、Kinesis、Amazon S3 和更多其他 AWS 服务。

• GitHub 上适用于 Python 的 AWS IoT 设备软件开发工具包• 适用于 Python 的 AWS IoT 设备软件开发工具包自述文件

341

https://github.com/aws/aws-iot-device-sdk-cpp/tree/release

https://github.com/aws/aws-iot-device-sdk-cpp/blob/release/README.md

https://github.com/aws/aws-sdk-ios

https://github.com/aws/aws-sdk-ios/blob/master/README.md

https://github.com/aws/aws-sdk-ios/blob/master/README.md#iot-sample-swift

https://github.com/aws/aws-iot-device-sdk-java

https://github.com/aws/aws-iot-device-sdk-java/blob/master/README.md

https://github.com/aws/aws-iot-device-sdk-js

https://github.com/aws/aws-iot-device-sdk-js/blob/master/README.md

https://github.com/aws/aws-iot-device-sdk-python

https://github.com/aws/aws-iot-device-sdk-python/blob/master/README.rst

AWS IoT 开发人员指南监控工具

监控 AWS IoT监控是保持 AWS IoT 和 AWS 解决方案的可靠性、可用性和性能的重要环节。您应从 AWS 解决方案的各个部分收集监控数据，以便更轻松地调试出现的多点故障。开始监控 AWS IoT 之前，您应制定一个监控计划并在计划中回答下列问题：

• 您的监控目标是什么？• 您将监控哪些资源？• 监控这些资源的频率如何？• 您将使用哪些监控工具？• 谁负责执行监控任务？• 出现错误时应通知谁？

接下来，通过在不同时间和不同负载条件下衡量性能，在您的环境中建立为正常的 AWS IoT 性能建立基准。监控 AWS IoT 时，将历史监控数据存储下来，以便可以将其与当前性能数据进行比较，确定正常性能模式和异常性能表现，并设计出问题解决方法。

例如，如果您使用的是 Amazon EC2，则可以监控实例的 CPU 利用率、磁盘 I/O 和网络利用率。如果性能低于您所建立的基准，则您可能需要重新配置或优化实例以降低 CPU 使用率、改进磁盘 I/O 或减少网络流量。

要建立基准，您至少应监控以下各项：

• PublishIn.Success• PublishOut.Success• Subscribe.Success• Ping.Success• Connect.Success• GetThingShadow.Accepted• UpdateThingShadow.Accepted• DeleteThingShadow.Accepted• RulesExecuted

主题• 监控工具 (p. 342)• 使用 Amazon CloudWatch 进行监控 (p. 343)• 使用 AWS CloudTrail 记录 AWS IoT API 调用 (p. 351)

监控工具AWS 为您提供了各种可用于监控 AWS IoT 的工具。您可以配置其中的一些工具来为您执行监控任务，但有些工具需要手动干预。建议您尽可能实现监控任务自动化。

自动监控工具您可以使用以下自动化监控工具来监控 AWS IoT 并在出现错误时进行报告：

342

AWS IoT 开发人员指南手动工具

• Amazon CloudWatch Alarms – Watch a single metric over a time period that you specify, and performone or more actions based on the value of the metric relative to a given threshold over a number of timeperiods. The action is a notification sent to an Amazon Simple Notification Service (Amazon SNS) topicor Amazon EC2 Auto Scaling policy. CloudWatch alarms do not invoke actions simply because they arein a particular state; the state must have changed and been maintained for a specified number of periods.For more information, see 使用 Amazon CloudWatch 进行监控 (p. 343).

• Amazon CloudWatch Logs – Monitor, store, and access your log files from AWS CloudTrail or othersources. For more information, see Monitoring Log Files in the Amazon CloudWatch 用户指南.

• Amazon CloudWatch Events – Match events and route them to one or more target functions or streamsto make changes, capture state information, and take corrective action. For more information, see Whatis Amazon CloudWatch Events in the Amazon CloudWatch 用户指南.

• AWS CloudTrail Log Monitoring – Share log files between accounts, monitor CloudTrail log files in realtime by sending them to CloudWatch Logs, write log processing applications in Java, and validate thatyour log files have not changed after delivery by CloudTrail. For more information, see Working withCloudTrail Log Files in the AWS CloudTrail User Guide.

手动监控工具监控 AWS IoT 时的另一个重要环节是手动监控 CloudWatch 警报未涵盖的那些项。AWS IoT、CloudWatch和其他 AWS 控制台仪表板均提供 AWS 环境状态的概览视图。建议您还要查看 AWS IoT 上的日志文件。

• AWS IoT 仪表板显示：• CA 证书• 证书• 策略• 规则• 事物

• CloudWatch 主页显示：• 当前警报和状态• 警报和资源的图表• 服务运行状况

此外，您还可以使用 CloudWatch 执行以下操作：• 创建自定义控制面板以监控您关心的服务• 绘制指标数据图，以排除问题并弄清楚趋势• 搜索并浏览您所有的 AWS 资源指标• 创建和编辑警报以接收有关问题的通知

使用 Amazon CloudWatch 进行监控您可以使用 CloudWatch 监控 AWS IoT，此工具可从 AWS IoT 收集原始数据，并将数据处理为便于读取的近乎实时的指标。这些统计数据会保存两周，从而使您能够访问历史信息，并能够更好地了解您的Web 应用程序或服务的执行情况。默认情况下，系统将在 1 分钟的时间段内自动将 AWS IoT 指标数据发送至 CloudWatch。有关更多信息，请参阅什么是 Amazon CloudWatch、Amazon CloudWatch Events 和Amazon CloudWatch Logs？（位于 Amazon CloudWatch 用户指南中）。

主题• AWS IoT 指标和维度 (p. 344)• 如何使用 AWS IoT 指标？ (p. 349)• 创建 CloudWatch 警报以监控 AWS IoT (p. 349)

343

http://docs.aws.amazon.com/AmazonCloudWatch/latest/DeveloperGuide/WhatIsCloudWatchLogs.html

http://docs.aws.amazon.com/AmazonCloudWatch/latest/DeveloperGuide/WhatIsCloudWatchEvents.html

http://docs.aws.amazon.com/AmazonCloudWatch/latest/DeveloperGuide/WhatIsCloudWatchEvents.html

http://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-working-with-log-files.html

http://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-working-with-log-files.html

http://docs.aws.amazon.com/AmazonCloudWatch/latest/DeveloperGuide/CloudWatch_Dashboards.html

http://docs.aws.amazon.com/AmazonCloudWatch/latest/DeveloperGuide/WhatIsCloudWatch.html

http://docs.aws.amazon.com/AmazonCloudWatch/latest/DeveloperGuide/WhatIsCloudWatch.html

AWS IoT 开发人员指南指标与维度

AWS IoT 指标和维度当您与 AWS IoT 交互时，它每一分钟向 CloudWatch 发送一次下列指标和维度。您可以按照以下步骤查看AWS IoT 的各项指标。

使用 CloudWatch 控制台查看指标

指标的分组首先依据服务命名空间，然后依据每个命名空间内的各种维度组合。

1. 通过以下网址打开 CloudWatch 控制台：https://console.aws.amazon.com/cloudwatch/。2. 在导航窗格中，选择 Metrics。3. 在 CloudWatch Metrics by Category 窗格中，在 AWS IoT 的指标类别下，选择一个指标类别，然后在

上方窗格中，向下滚动以查看完整的指标列表。

使用 AWS CLI 查看指标

• 在命令提示符处，输入以下命令：

aws cloudwatch list-metrics --namespace "AWS/IoT"

CloudWatch 会显示 AWS IoT 的以下指标：

AWS IoT MetricsAWS IoT sends the following metrics to CloudWatch once per received request.

IoT Metrics

Metric Description

RulesExecuted The number of AWS IoT rules executed.

Rule Metrics

Metric Description

TopicMatch The number of incoming messages published on a topicon which a rule is listening. The RuleName dimensioncontains the name of the rule.

ParseError The number of JSON parse errors that occurred inmessages published on a topic on which a rule islistening. The RuleName dimension contains the name ofthe rule.

Rule Action Metrics

Metric Description

Success The number of successful rule action invocations. TheRuleName dimension contains the name of the rule

344

https://console.aws.amazon.com/cloudwatch/


Metric Descriptionthat specifies the action. The ActionType dimensioncontains the type of action that was invoked.

Failure The number of failed rule action invocations. TheRuleName dimension contains the name of the rulethat specifies the action. The RuleName dimensioncontains the name of the rule that specifies the action.The ActionType dimension contains the type of actionthat was invoked.

Message Broker Metrics

Metric Description

Connect.AuthError The number of connection requests that could not beauthorized by the message broker. The Protocoldimension contains the protocol used to send theCONNECT. message.

Connect.ClientError The number of connection requests rejected because theMQTT message did not meet the requirements defined inAWS IoT Limits. The Protocol dimension contains theprotocol used to send the CONNECT. message.

Connect.ServerError The number of connection requests that failed becausean internal error occurred. The Protocol dimensioncontains the protocol used to send the CONNECTmessage.

Connect.Success The number of successful connections to the messagebroker. The Protocol dimension contains the protocolused to send the CONNECT message.

Connect.Throttle The number of connection requests that were throttledbecause the client exceeded the allowed connect requestrate. The Protocol dimension contains the protocolused to send the CONNECT message.

Ping.Success The number of ping messages received by the messagebroker. The Protocol dimension contains the protocolused to send the ping message.

PublishIn.AuthError The number of publish requests the message broker wasunable to authorize. The Protocol dimension containsthe protocol used to publish the message.

PublishIn.ClientError The number of publish requests rejected by themessage broker because the message did not meet therequirements defined in AWS IoT Limits. The Protocoldimension contains the protocol used to publish themessage.

PublishIn.ServerError The number of publish requests the message brokerfailed to process because an internal error occurred. TheProtocol dimension contains the protocol used to sendthe PUBLISH message.

345

http://docs.aws.amazon.com/iot/latest/developerguide/iot-limits.html



Metric Description

PublishIn.Success The number of publish requests successfully processedby the message broker. The Protocol dimensioncontains the protocol used to send the PUBLISHmessage.

PublishIn.Throttle The number of publish request that were throttledbecause the client exceeded the allowed inboundmessage rate. The Protocol dimension contains theprotocol used to send the PUBLISH message.

PublishOut.AuthError The number of publish requests made by the messagebroker that could not be authorized by AWS IoT. TheProtocol dimension contains the protocol used to sendthe PUBLISH message.

PublishOut.ClientError The number of publish requests made by the messagebroker that were rejected because the message did notmeet the requirements defined in AWS IoT Limits. TheProtocol dimension contains the protocol used to sendthe PUBLISH message.

PublishOut.Success The number of publish requests successfully made by themessage broker. The Protocol dimension contains theprotocol used to send the PUBLISH message.

Subscribe.AuthError The number of subscription requests made by a clientthat could not be authorized. The Protocol dimensioncontains the protocol used to send the SUBSCRIBEmessage.

Subscribe.ClientError The number of subscribe requests that were rejectedbecause the SUBSCRIBE message did not meet therequirements defined in AWS IoT Limits. The Protocoldimension contains the protocol used to send theSUBSCRIBE message.

Subscribe.ServerError The number of subscribe requests that were rejectedbecause an internal error occurred. The Protocoldimension contains the protocol used to send theSUBSCRIBE message.

Subscribe.Success The number of subscribe requests that were successfullyprocessed by the message broker. The Protocoldimension contains the protocol used to send theSUBSCRIBE message.

Subscribe.Throttle The number of subscribe requests that were throttledbecause the client exceeded the allowed subscriberequest rate. The Protocol dimension contains theprotocol used to send the SUBSCRIBE message.

Unsubscribe.ClientError The number of unsubscribe requests that were rejectedbecause the UNSUBSCRIBE message did not meet therequirements defined in AWS IoT Limits. The Protocoldimension contains the protocol used to send theUNSUBSCRIBE message.

346





Metric Description

Unsubscribe.ServerError The number of unsubscribe requests that were rejectedbecause an internal error occurred. The Protocoldimension contains the protocol used to send theUNSUBSCRIBE message.

Unsubscribe.Success The number of unsubscribe requests that weresuccessfully processed by the message broker. TheProtocol dimension contains the protocol used to sendthe UNSUBSCRIBE message.

Unsubscribe.Throttle The number of unsubscribe requests that were rejectedbecause the client exceeded the allowed unsubscriberequest rate. The Protocol dimension contains theprotocol used to send the UNSUBSCRIBE message.

Note

The message broker metrics are displayed in the AWS IoT console under Protocol Metrics.

Device Shadow Metrics

Metric Description

DeleteThingShadow.Accepted The number of DeleteThingShadow requests processedsuccessfully. The Protocol dimension contains theprotocol used to make the request.

GetThingShadow.Accepted The number of GetThingShadow requests processedsuccessfully. The Protocol dimension contains theprotocol used to make the request.

UpdateThingShadow.Accepted The number of UpdateThingShadow requests processedsuccessfully. The Protocol dimension contains theprotocol used to make the request.

Note

The device shadow metrics are displayed in the AWS IoT console under Protocol Metrics.

Jobs Metrics

Metric Description

ServerError The number of server errors generated while executingthe job. The JobId dimension contains the ID of the job.

ClientError The number of client errors generated while executingthe job. The JobId dimension contains the ID of the job.

QueuedJobExecutionTotalCount The total number of job executions whose status isQUEUED for the given job. The JobId dimension containsthe ID of the job.

InProgressJobExecutionTotalCount The total number of job executions whose status isIN_PROGRESS for the given job. The JobId dimensioncontains the ID of the job.

347


Metric Description

FailedJobExecutionTotalCount The total number of job executions whose status isFAILED for the given job. The JobId dimension containsthe ID of the job.

SuccededJobExecutionTotalCount The total number of job executions whose status isSUCCESS for the given job. The JobId dimensioncontains the ID of the job.

CanceledJobExecutionTotalCount The total number of job executions whose status isCANCELED for the given job. The JobId dimensioncontains the ID of the job.

RejectedJobExecutionTotalCount The total number of job executions whose status isREJECTED for the given job. The JobId dimensioncontains the ID of the job.

RemovedJobExecutionTotalCount The total number of job executions whose status isREMOVED for the given job. The JobId dimensioncontains the ID of the job.

QueuedJobExecutionCount The number of job executions whose status has changedto QUEUED since the last enquiry for the given job. TheJobId dimension contains the ID of the job.

InProgressJobExecutionCount The number of job executions whose status has changedto IN_PROGRESS since the last enquiry for the given job.The JobId dimension contains the ID of the job.

FailedJobExecutionCount The number of job executions whose status has changedto FAILED since the last enquiry for the given job. TheJobId dimension contains the ID of the job.

SuccededJobExecutionCount The number of job executions whose status has changedto SUCCESS since the last enquiry for the given job. TheJobId dimension contains the ID of the job.

CanceledJobExecutionCount The number of job executions whose status has changedto CANCELED since the last enquiry for the given job. TheJobId dimension contains the ID of the job.

RejectedJobExecutionCount The number of job executions whose status has changedto REJECTED since the last enquiry for the given job. TheJobId dimension contains the ID of the job.

RemovedJobExecutionCount The number of job executions whose status has changedto REMOVED since the last enquiry for the given job. TheJobId dimension contains the ID of the job.

Dimensions for MetricsMetrics use the namespace and provide metrics for the following dimension(s):

348

AWS IoT 开发人员指南使用 AWS IoT 指标

Dimension Description

ActionType The action type specified by the rule that triggered by therequest.

Protocol The protocol used to make the request. Valid values are:MQTT or HTTP

RuleName The name of the rule triggered by the request.

JobId The ID of the job whose progress or message connectionsuccess/failure is being monitored.

如何使用 AWS IoT 指标？您可以通过多种方式分析 AWS IoT 报告指标提供的信息。以下使用案例基于您每天将十个事物连接一次Internet 的场景。每天：

• 十个事物几乎在同一时间连接到 AWS IoT。• 每个事物都会订阅主题筛选条件，接着在等待一个小时后断开连接。在此期间，事物之间相互通信并探索

更多与环境状态有关的信息。• 每个事物都会基于其新发现的数据，使用 UpdateThingShadow 发布一些看法，• 然后断开与 AWS IoT 的连接。

下面列出的是能够带您入门的启发式问题，但并不全面。

• 我如何知道事物每天是否成功建立连接？ (p. 349)• 我如何知道事物每天是否发布数据？ (p. 350)• 我如何知道事物影子更新每天是否遭到拒绝？ (p. 351)

创建 CloudWatch 警报以监控 AWS IoT您可以创建 CloudWatch 警报，以在警报改变状态时发送 Amazon SNS 消息。警报会在您指定的时间段内监控一个指标，并根据指标值在多个时间段内相对于给定阈值的情况执行一项或多项操作。操作是向 AmazonSNS 主题或 Auto Scaling 策略发送的通知。警报只会调用操作进行持续的状态变更。CloudWatch 警报将不会调用操作，因为这些操作处于特定状态；该状态必须改变并在指定数量的时间段内一直保持。

我如何知道事物每天是否成功建立连接？1. 创建一个 Amazon SNS 主题：arn:aws:sns:us-east-1:123456789012:things-not-connecting-

successfully。

有关更多信息，请参阅设置 Amazon Simple Notification Service。2. 创建警报。

Prompt>aws cloudwatch put-metric-alarm \ --alarm-name ConnectSuccessAlarm \ --alarm-description "Alarm when my Things don't connect successfully" \ --namespace AWS/IoT \ --metric-name Connect.Success \ --dimensions Name=Protocol,Value=MQTT \

349

http://docs.aws.amazon.com/iot/latest/developerguide/iot-rule-actions.html

Amazon Simple Notification Service ??????US_SetupSNS.html

AWS IoT 开发人员指南创建 CloudWatch 警报

--statistic Sum \ --threshold 10 \ --comparison-operator LessThanThreshold \ --period 86400 \ --unit Count \ --evaluation-periods 1 \ --alarm-actions arn:aws:sns:us-east-1:1234567890:things-not-connecting-successfully

Prompt>aws cloudwatch put-metric-alarm \ --alarm-name ConnectSuccessAlarm \ --alarm-description "Alarm when my Things don't connect successfully" \ --namespace AWS/IoT \ --metric-name Connect.Success \ --dimensions Name=Protocol,Value=MQTT \ --statistic Sum \ --threshold 10 \ --comparison-operator LessThanThreshold \ --period 86400 \ --unit Count \ --evaluation-periods 1 \ --alarm-actions arn:aws:sns:us-east-1:1234567890:things-not-connecting-successfully

3. 测试警报。

Prompt>aws cloudwatch set-alarm-state --alarm-name ConnectSuccessAlarm --state-reason "initializing" --state-value OK

Prompt>aws cloudwatch set-alarm-state --alarm-name ConnectSuccessAlarm --state-reason "initializing" --state-value ALARM

我如何知道事物每天是否发布数据？1. 创建一个 Amazon SNS 主题：arn:aws:sns:us-east-1:123456789012:things-not-

publishing-data。


Prompt>aws cloudwatch put-metric-alarm \ --alarm-name PublishInSuccessAlarm\ --alarm-description "Alarm when my Things don't publish their data \ --namespace AWS/IoT \ --metric-name PublishIn.Success \ --dimensions Name=Protocol,Value=MQTT \ --statistic Sum \ --threshold 10 \ --comparison-operator LessThanThreshold \ --period 86400 \ --unit Count \ --evaluation-periods 1 \ --alarm-actions arn:aws:sns:us-east-1:1234567890:things-not-publishing-data

3. 测试警报。

Prompt>aws cloudwatch set-alarm-state --alarm-name PublishInSuccessAlarm --state-reason "initializing" --state-value OK

350


AWS IoT 开发人员指南使用 AWS CloudTrail 记录 AWS IoT API 调用

Prompt>aws cloudwatch set-alarm-state --alarm-name PublishInSuccessAlarm --state-reason "initializing" --state-value ALARM

我如何知道事物影子更新每天是否遭到拒绝？1. 创建一个 Amazon SNS 主题：arn:aws:sns:us-east-1:1234567890:things-shadow-updates-rejected。


Prompt>aws cloudwatch put-metric-alarm \ --alarm-name UpdateThingShadowSuccessAlarm \ --alarm-description "Alarm when my Things Shadow updates are getting rejected" \ --namespace AWS/IoT \ --metric-name UpdateThingShadow.Success \ --dimensions Name=Protocol,Value=MQTT \ --statistic Sum \ --threshold 10 \ --comparison-operator LessThanThreshold \ --period 86400 \ --unit Count \ --evaluation-periods 1 \ --alarm-actions arn:aws:sns:us-east-1:1234567890:things-shadow-updates-rejected

3. 测试警报。

Prompt>aws cloudwatch set-alarm-state --alarm-name UpdateThingShadowSuccessAlarm --state-reason "initializing" --state-value OK

Prompt>aws cloudwatch set-alarm-state --alarm-name UpdateThingShadowSuccessAlarm --state-reason "initializing" --state-value ALARM

使用 AWS CloudTrail 记录 AWS IoT API 调用AWS IoT 与 CloudTrail 集成，后者可捕获所有 AWS IoT API 调用并将日志文件传输到您指定的 Amazon S3存储桶中。CloudTrail 可捕获来自 AWS IoT 控制台的 API 调用或者从您的代码对 AWS IoT API 进行的调用。通过使用 CloudTrail 收集的信息，您可以确定向 AWS IoT 发出了什么请求、发出请求的源 IP 地址、何人发出的请求以及请求的发出时间等。

要了解有关 CloudTrail 的更多信息，包括如何对其进行配置和启用，请参阅 AWS CloudTrail User Guide。

CloudTrail 中的 AWS IoT 信息在您的 AWS 账户中启用 CloudTrail 日志记录后，会在 CloudTrail 日志文件中跟踪对 AWS IoT 操作执行的大多数 API 调用，这些操作会随其他 AWS 服务记录一起写入到这些日志文件。CloudTrail 基于时间段和文件大小来确定何时创建新文件并向其写入内容。

Note

AWS IoT 数据层面操作 (设备端) 不由 CloudTrail 记录。使用 CloudWatch 可监控这些操作。

AWS IoT 控制层面操作由 CloudTrail 记录。例如，对 CreateThing、ListThings 和 ListTopicRules 部分的调用均将在 CloudTrail 日志文件中生成条目。

351


http://docs.aws.amazon.com/awscloudtrail/latest/userguide/

AWS IoT 开发人员指南了解 AWS IoT 日志文件条目

每个日志条目都包含有关生成请求的人员的信息。日志条目中的用户身份信息可帮助您确定以下内容：

• 请求是使用根用户凭证还是 IAM 用户凭证发出的.• 请求是使用角色还是联合身份用户的临时安全凭证发出的。• 请求是否由其他 AWS 服务发出。

有关更多信息，请参阅 CloudTrail userIdentity 元素。AWS IoT 操作在 AWS IoT API 参考中记录。

日志文件可以在 Amazon S3 存储桶中存储任意长时间，不过您也可以定义 Amazon S3 生命周期规则以自动存档或删除日志文件。默认情况下，将使用 Amazon S3 服务器端加密 (SSE) 对日志文件进行加密。

如果您需要获得日志文件传输的通知，则可以将 CloudTrail 配置为在传输新日志文件时发布 Amazon SNS通知。有关更多信息，请参阅为 CloudTrail 配置 Amazon SNS 通知。

您还可以将多个 AWS 区域和多个 AWS 账户中的 AWS IoT 日志文件聚合到单个 Amazon S3 存储桶中。

有关更多信息，请参阅接收多个区域中的 CloudTrail 日志文件和从多个账户中接收 CloudTrail 日志文件。

了解 AWS IoT 日志文件条目CloudTrail 日志文件可以包含一个或多个日志条目。每个条目列出了多个 JSON 格式的事件。一个日志条目表示来自任何源的一个请求，包括有关所请求的操作、操作的日期和时间、请求参数等方面的信息。日志条目不是公用 API 调用的有序堆栈跟踪，因此它们不会以任何特定顺序显示。

下面的示例显示了一个 CloudTrail 日志条目，该条目说明了 AttachPolicy 操作。

{ "timestamp":"1460159496", "AdditionalEventData":"", "Annotation":"", "ApiVersion":"", "ErrorCode":"", "ErrorMessage":"", "EventID":"8bff4fed-c229-4d2d-8264-4ab28a487505", "EventName":"AttachPolicy", "EventTime":"2016-04-08T23:51:36Z", "EventType":"AwsApiCall", "ReadOnly":"", "RecipientAccountList":"", "RequestID":"d4875df2-fde4-11e5-b829-23bf9b56cbcd", "RequestParamters":{ "principal":"arn:aws:iot:us-east-1:123456789012:cert/528ce36e8047f6a75ee51ab7beddb4eb268ad41d2ea881a10b67e8e76924d894", "policyName":"ExamplePolicyForIoT" }, "Resources":"", "ResponseElements":"", "SourceIpAddress":"52.90.213.26", "UserAgent":"aws-internal/3", "UserIdentity":{ "type":"AssumedRole", "principalId":"AKIAI44QH8DHBEXAMPLE", "arn":"arn:aws:sts::12345678912:assumed-role/iotmonitor-us-east-1-beta-InstanceRole-1C5T1YCYMHPYT/i-35d0a4b6", "accountId":"222222222222", "accessKeyId":"access-key-id", "sessionContext":{ "attributes":{ "mfaAuthenticated":"false", "creationDate":"Fri Apr 08 23:51:10 UTC 2016"

352

http://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-event-reference-user-identity.html

http://docs.aws.amazon.com/iot/latest/apireference/

http://docs.aws.amazon.com/awscloudtrail/latest/userguide/getting_notifications_top_level.html

http://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-receive-logs-from-multiple-accounts.html

http://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-receive-logs-from-multiple-accounts.html

AWS IoT 开发人员指南了解 AWS IoT 日志文件条目

}, "sessionIssuer":{ "type":"Role", "principalId":"AKIAI44QH8DHBEXAMPLE", "arn":"arn:aws:iam::123456789012:role/executionServiceEC2Role/iotmonitor-us-east-1-beta-InstanceRole-1C5T1YCYMHPYT", "accountId":"222222222222", "userName":"iotmonitor-us-east-1-InstanceRole-1C5T1YCYMHPYT" } }, "invokedBy":{ "serviceAccountId":"111111111111" } }, "VpcEndpointId":""}

353

AWS IoT 开发人员指南诊断连接问题

AWS IoT 故障排除以下信息可帮助您处理 AWS IoT 中的常见问题。

任务• 诊断连接问题 (p. 354)• 使用 AWS IoT 设置 CloudWatch Logs (p. 354)• 诊断 Shadows 问题 (p. 371)• 诊断 Salesforce IoT 输入流操作问题 (p. 372)• AWS IoT 错误 (p. 373)

诊断连接问题身份验证我的设备如何对 AWS IoT 终端节点进行身份验证？

将 AWS IoT CA 证书添加到您的客户端信任的存储。您可以从此处下载 CA 证书。如何验证证书的配置是否正确？

请使用 OpenSSL s_client 命令测试与 AWS IoT 终端节点的连接：

openssl s_client -connect custom_endpoint.iot.us-east-1.amazonaws.com:8443 -CAfile CA.pem -cert cert.pem -key privateKey.pem

授权我收到了代理发送的 PUBNACK 或 SUBNACK 回复。我应该怎么办？

请确保当前有策略附加到您用于调用 AWS IoT 的证书。默认情况下，所有的发布/订阅操作均将被拒绝。

使用 AWS IoT 设置 CloudWatch Logs当消息从您的设备通过消息代理和规则引擎传递时，AWS IoT 会发送关于每条消息的进度事件。要查看这些日志，您必须配置 AWS IoT 以生成由 CloudWatch 使用的日志。

有关 CloudWatch Logs 的更多信息，请参阅CloudWatch Logs。

要启用 AWS IoT 日志记录，您必须创建一个 IAM 角色，将该角色注册到 AWS IoT，然后配置 AWS IoT 日志记录。

Note

在启用 AWS IoT 日志记录之前，请务必了解 CloudWatch Logs 访问权限。拥有 CloudWatch Logs访问权限的用户能够从您的设备查看调试信息。有关更多信息，请参阅 Amazon CloudWatch Logs的身份验证和访问控制。

354


http://docs.aws.amazon.com/AmazonCloudWatch/latest/DeveloperGuide/WhatIsCloudWatchLogs.html

http://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring//auth-and-access-control-cwl.html

http://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring//auth-and-access-control-cwl.html

AWS IoT 开发人员指南创建日志记录角色

创建日志记录角色使用 IAM 控制台可创建日志记录角色。

1. 从导航窗格中，选择角色，然后选择创建新角色。2. 选择 AWS 服务角色；对于服务角色类型，选择 AWS IoT。3. 选择 AWSIoTLogging 角色，然后选择下一步。4. 键入角色的名称和描述，然后选择创建角色。

日志记录角色策略以下策略文档提供了角色策略和信任策略，借助这些策略，AWS IoT 可代表您向 CloudWatch 提交日志。

Note

在您创建日志记录角色时已为您创建这些文档。

角色策略:

{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "logs:CreateLogGroup", "logs:CreateLogStream", "logs:PutLogEvents", "logs:PutMetricFilter", "logs:PutRetentionPolicy" ], "Resource": [ "*" ] } ]}

信任策略:

{ "Version": "2012-10-17", "Statement": [ { "Sid": "", "Effect": "Allow", "Principal": { "Service": "iot.amazonaws.com" }, "Action": "sts:AssumeRole" } ]}

日志级别日志级别指定了将生成哪些类型的日志。

355

https://console.aws.amazon.com/iam/

AWS IoT 开发人员指南配置 AWS IoT 日志记录

ERROR

导致操作失败的任何错误。

日志仅包含 ERROR 信息。WARN

可能导致系统中出现不一致问题，但不会导致操作失败的所有情况。

日志包括 ERROR 和 WARN 信息。INFO

有关事物流的高级别信息。

日志包括 INFO、ERROR 和 WARN 信息。DEBUG

可能有助于调试问题的信息。

日志包括 DEBUG、INFO、ERROR 和 WARN 信息。DISABLED

所有日志记录均处于禁用状态。

配置 AWS IoT 日志记录您可以通过两种方式配置日志记录，即全局日志记录和精细日志记录。全局日志记录为所有日志设置一个日志记录级别，而无论是什么资源触发了日志。精细日志记录可让您为一种特定资源或一组资源设置日志记录级别。当前仅支持事物组。

全局日志记录使用 set-logging-options CLI 命令可为您的账户设置日志记录选项。set-logging-options 包含两个参数：

roleArn

您的日志记录角色 ARN。日志记录角色将向 AWS IoT 授予对 CloudWatch Logs 的写入权限。logLevel

要使用的日志级别。有效值为：ERROR、WARN、INFO、DEBUG 或 DISABLED

例如：

aws iot set-logging-options --logging-options-payload roleArn="arn:aws:iam::<your-aws-account-num>:role/<IoTLoggingRole>",logLevel="<INFO>"

您可以使用 get-logging-options CLI 命令来获取当前日志记录选项。

精细日志记录可通过精细日志记录为目标指定日志记录级别。目标由资源类型和资源名称定义。目前，AWS IoT 支持将事物组作为目标。可通过精细日志记录为特定的事物组设置日志记录级别。假设我们有一个名为“Phones”的事

356

AWS IoT 开发人员指南CloudWatch 日志条目格式

物组，该组包含代表不同类型的电话的事物。然后，我们创建另一个名为“MobilePhones”的事物组，并将其设置为“Phones”事物组的子级。利用精细日志记录功能，您可以为“Phones”组 (以及任何子组) 中的所有事物配置一个日志记录级别，并为“MobilePhones”组中的事物配置另一个日志记录级别。在此示例中，我们已为“MobilePhones”组中的事物分配了两个不同的日志记录级别 (一个来自“Phones”事物组的日志记录级别，另一个来自“MobilePhones”事物组) – 不过，为子事物组指定的日志记录级别将覆盖为父事物组指定的日志记录级别。

使用 set-v2-logging-options CLI 命令可启用精细日志记录，并设置默认日志记录级别。它接受以下可选参数：

--role-arn

一个允许 AWS IoT 写入到您的 CloudWatch Logs 的 IAM 角色。如果未指定此参数，则 AWS IoT 将使用与您的账户关联的日志记录角色。在创建日志记录角色时，它将与您的账户关联。有关更多信息，请参阅创建日志记录角色 (p. 355)。

--default-log-level

在未指定日志记录级别的情况下使用的日志记录级别。有效值为：DEBUG、INFO、ERROR、WARN 和DISABLED

--disable-all-logging

如果设置为 true，则将禁用所有日志记录。

get-v2-logging-options CLI 命令返回配置的 IAM 日志记录角色、默认日志记录级别和disableAllLogs 值。

使用 set-v2-logging-level CLI 命令可为目标配置精细日志记录。它接受以下参数：

--log-target

一个 JSON 文档，其中包含您为其配置日志记录的实体的资源类型和名称。AWS IoT 目前支持将THING_GROUP 作为资源类型。您最多可配置 10 个日志记录目标。

--log-level

为指定资源生成日志时使用的日志记录级别。有效值为：DEBUG、INFO、ERROR、WARN 和 DISABLED

使用 list-v2-logging-levels CLI 命令可获取当前配置的精细日志记录级别的列表。调用 delete-v2-logging-level CLI 命令可删除日志记录级别。使用 delete-v2-logging-level 命令可删除精细日志记录级别。

CloudWatch 日志条目格式AWS IoT 的每个组件均会生成自己的日志。每个日志条目均有一个 eventType，指示哪项操作导致生成了日志。此部分介绍以下 AWS IoT 组件所生成的日志：

• 消息代理 (p. 358)• Device Shadow 服务 (p. 362)• 规则引擎 (p. 364)• 工作 (p. 367)

所有 CloudWatch Logs 都具有以下通用属性：

timestamp

客户端连接到 AWS IoT 消息代理的时间的 UNIX 时间戳。

357


logLevel

所使用的日志级别。有关更多信息，请参阅 the section called “日志级别” (p. 355)。traceId

一个随机生成的标识符，可用于将特定请求的所有日志关联起来。accountId

您的 AWS 账户 ID。status

请求的状态。eventType

已为其生成日志的事件类型。以下各部分列出了每个事件的事件类型的值。

消息代理日志AWS IoT 消息代理会生成以下事件的日志：

Connect 日志

在 MQTT 客户端进行连接时，AWS IoT 消息代理会生成 Connect 日志。更多信息 (1)

例如：

{ "timestamp": "2017-08-10 15:37:23.476", "logLevel": "INFO", "traceId": "20b23f3f-d7f1-feae-169f-82263394fbdb", "accountId": "123456789012", "status": "Success", "eventType": "Connect", "protocol": "MQTT", "clientId": "abf27092886e49a8a5c1922749736453", "principalId": "145179c40e2219e18a909d896a5340b74cf97a39641beec2fc3eeafc5a932167", "sourceIp": "205.251.233.181", "sourcePort": 13490 }

除了所有 CloudWatch Logs 通用的属性之外，Connect 日志条目还包含以下属性：

eventType

Connect (针对连接日志)。protocol

发出请求时使用的协议。有效值为 MQTT 或 HTTP。clientId

发出请求的客户端的 ID。principalId

发出请求的委托人的 ID。sourceIp

请求的源 IP 地址。

358


sourcePort

请求的源端口。

Subscribe 日志

在 MQTT 客户端订阅主题时，AWS IoT 消息代理会生成 Subscribe 日志。更多信息 (2)

例如：

{ "timestamp": "2017-08-10 15:39:04.413", "logLevel": "INFO", "traceId": "7aa5c38d-1b49-3753-15dc-513ce4ab9fa6", "accountId": "123456789012", "status": "Success", "eventType": "Subscribe", "protocol": "MQTT", "topicName": "$aws/things/MyThing/shadow/#", "clientId": "abf27092886e49a8a5c1922749736453", "principalId": "145179c40e2219e18a909d896a5340b74cf97a39641beec2fc3eeafc5a932167", "sourceIp": "205.251.233.181", "sourcePort": 13490 }

除了所有 CloudWatch Logs 通用的属性之外，Subscribe 日志条目还包含以下属性：

eventType

Subscribe (针对订阅日志)。protocol

发出请求时使用的协议。有效值为 MQTT 或 HTTP。topicName

已订阅主题的名称。clientId



请求的源 IP 地址。sourcePort


Publish-In 日志

在 AWS IoT 消息代理收到 MQTT 消息时，该代理会生成 Publish-In 日志。更多信息 (3)

例如：

{

359


"timestamp": "2017-08-10 15:39:30.961", "logLevel": "INFO", "traceId": "672ec480-31ce-fd8b-b5fb-22e3ac420699", "accountId": "123456789012", "status": "Success", "eventType": "Publish-In", "protocol": "MQTT", "topicName": "$aws/things/MyThing/shadow/get", "clientId": "abf27092886e49a8a5c1922749736453", "principalId": "145179c40e2219e18a909d896a5340b74cf97a39641beec2fc3eeafc5a932167", "sourceIp": "205.251.233.181", "sourcePort": 13490 }

除了所有 CloudWatch Logs 通用的属性之外，Publish-In 日志条目还包含以下属性：

eventType

Publish-In (在消息代理收到消息时)。status

请求的状态。protocol







Publish-Out 日志

在 AWS IoT 消息代理发布 MQTT 消息时，该代理会生成 Publish-Out 日志。更多信息 (4)

例如：

{ "timestamp": "2017-08-10 15:39:30.961", "logLevel": "INFO", "traceId": "672ec480-31ce-fd8b-b5fb-22e3ac420699", "accountId": "123456789012", "status": "Success", "eventType": "Publish-Out", "protocol": "MQTT", "topicName": "$aws/things/MyThing/shadow/get", "clientId": "abf27092886e49a8a5c1922749736453", "principalId": "145179c40e2219e18a909d896a5340b74cf97a39641beec2fc3eeafc5a932167",

360


"sourceIp": "205.251.233.181", "sourcePort": 13490 }

除了所有 CloudWatch Logs 通用的属性之外，Publish-Out 日志条目还包含以下属性：

eventType

Publish-Out (在消息代理发布消息时)。status

请求的状态。protocol







Disconnect 日志

在 MQTT 客户端断开连接时，AWS IoT 消息代理会生成 Disconnect 日志。更多信息 (5)

例如：

{ "timestamp": "2017-08-10 15:37:23.476", "logLevel": "INFO", "traceId": "20b23f3f-d7f1-feae-169f-82263394fbdb", "accountId": "123456789012", "status": "Success", "eventType": "Disconnect", "protocol": "MQTT", "clientId": "abf27092886e49a8a5c1922749736453", "principalId": "145179c40e2219e18a909d896a5340b74cf97a39641beec2fc3eeafc5a932167", "sourceIp": "205.251.233.181", "sourcePort": 13490 }

除了所有 CloudWatch Logs 通用的属性之外，Disconnect 日志条目还包含以下属性：

eventType

Disconnect (针对连接日志)。

361


protocol






Device Shadow 日志AWS IoT Device Shadow 服务会生成以下事件的日志：

GetThingShadow 日志

在收到影子的获取请求时，Device Shadow 服务会生成 GetThingShadow 日志。更多信息 (6)

例如：

{ "timestamp": "2017-08-09 17:56:30.941", "logLevel": "INFO", "traceId": "b575f19a-97a2-cf72-0ed0-c64a783a2504", "accountId": "123456789012", "status": "Success", "eventType": "GetThingShadow", "protocol": "MQTT", "deviceShadowName": "MyThing", "topicName": "$aws/things/MyThing/shadow/get" }

除了所有 CloudWatch Logs 通用的属性之外，GetThingShadow 日志条目还包含以下属性：

eventType

GetThingShadow (针对 GetThingShadow 日志)。protocol

发出请求时使用的协议。有效值为 MQTT 或 HTTP。deviceShadowName

所请求的影子的名称。topicName

发布请求时所基于的主题的名称。

UpdateThingShadow 日志

在收到设备的影子的更新请求时，Device Shadow 服务会生成 UpdateThingShadow 日志。

362


更多信息 (7)

例如：

{ "timestamp": "2017-08-07 18:43:59.436", "logLevel": "INFO", "traceId": "d0074ba8-0c4b-a400-69df-76326d414c28", "accountId": "123456789012", "status": "Success", "eventType": "UpdateThingShadow", "protocol": "MQTT", "deviceShadowName": "Jack", "topicName": "$aws/things/Jack/shadow/update" }

除了所有 CloudWatch Logs 通用的属性之外，UpdateThingShadow 日志条目还包含以下属性：

eventType

UpdateThingShadow (针对更新影子日志)。protocol

发出请求时使用的协议。有效值为 MQTT 或 HTTP。deviceShadowName

要更新的影子的名称。topicName


DeleteThingShadow 日志

在收到设备的影子的删除请求时，Device Shadow 服务会生成 DeleteThingShadow 日志。更多信息 (8)

例如：

{ "timestamp": "2017-08-07 18:47:56.664", "logLevel": "INFO", "traceId": "1a60d02e-15b9-605b-7096-a9f584a6ad3f", "accountId": "123456789012", "status": "Success", "eventType": "DeleteThingShadow", "protocol": "MQTT", "deviceShadowName": "Jack", "topicName": "$aws/things/Jack/shadow/delete" }

除了所有 CloudWatch Logs 通用的属性之外，DeleteThingShadow 日志条目还包含以下属性：

eventType

DeleteThingShadow (针对 DeleteThingShadow 日志)。protocol

发出请求时使用的协议。有效值为 MQTT 或 HTTP。

363


deviceShadowName

要更新的影子的名称。topicName


规则引擎日志AWS IoT 规则引擎服务会生成以下事件的日志：

规则匹配日志

在消息代理收到与规则匹配的消息时，AWS IoT 规则引擎会生成 RuleMatch 日志。更多信息 (9)

例如：

{ "timestamp": "2017-08-10 16:32:46.002", "logLevel": "INFO", "traceId": "30aa7ccc-1d23-0b97-aa7b-76196d83537e", "accountId": "123456789012", "status": "Success", "eventType": "RuleMatch", "clientId": "abf27092886e49a8a5c1922749736453", "topicName": "rules/test", "ruleName": "JSONLogsRule", "principalId": "145179c40e2219e18a909d896a5340b74cf97a39641beec2fc3eeafc5a932167" }

除了所有 CloudWatch Logs 通用的属性之外，RuleMatch 日志条目还包含以下属性：

eventType

RuleMatch (针对规则匹配日志)。clientId

发出请求的客户端的 ID。topicName

已订阅主题的名称。ruleName

匹配规则的名称。principalId

发出请求的委托人的 ID。

函数执行日志

在规则的 SQL 查询调用外部函数时，规则引擎会生成 FunctionExecution 日志。在规则的操作向 AWS IoT 或其他 Web 服务发出 HTTP 请求 (例如，调用 get_thing_shadow 或machinelearning_predict) 时，将调用外部函数。

更多信息 (10)

FunctionExecution 日志看起来与以下内容类似：

364


{ "timestamp": "2017-07-13 18:33:51.903”, "logLevel": "DEBUG”, "traceId": "180532b7-0cc7-057b-687a-5ca1824838f5”, "status": "Success”, "eventType": "FunctionExecution”, "clientId": "N/A”, "topicName":"rules/test”, "ruleName": "ruleTestPredict”, "ruleAction": "MachinelearningPredict”, "resources": { "ModelId": "predict-model” }, "principalId": "145179c40e2219e18a909d896a5340b74cf97a39641beec2fc3eeafc5a932167”}

除了所有 CloudWatch Logs 通用的属性之外，FunctionExecution 日志条目还包含以下属性：

eventType

FunctionExecution (针对规则匹配日志)。clientId

N/A (针对 FunctionExecution 日志)。topicName


匹配规则的名称。resources

规则的操作所使用的资源的集合。principalId


开始执行日志

在 AWS IoT 规则引擎开始调用规则的操作时，该引擎会生成 StartingExecution 日志。更多信息 (11)

例如：

{ "timestamp": "2017-08-10 16:32:46.002", "logLevel": "DEBUG", "traceId": "30aa7ccc-1d23-0b97-aa7b-76196d83537e", "accountId": "123456789012", "status": "Success", "eventType": "StartingRuleExecution", "clientId": "abf27092886e49a8a5c1922749736453", "topicName": "rules/test", "ruleName": "JSONLogsRule", "ruleAction": "RepublishAction", "principalId": "145179c40e2219e18a909d896a5340b74cf97a39641beec2fc3eeafc5a932167" }

除了所有 CloudWatch Logs 通用的属性之外，StartingExecution 日志条目还包含以下属性：

365


eventType

StartingRuleExecution (针对开始规则执行日志)。clientId



匹配规则的名称。ruleAction

已调用操作的名称。principalId


规则执行日志

在 AWS IoT 规则引擎调用规则的操作时，该规则引擎会生成 RuleExecution 日志。更多信息 (12)

例如：

{ "timestamp": "2017-08-10 16:32:46.070", "logLevel": "INFO", "traceId": "30aa7ccc-1d23-0b97-aa7b-76196d83537e", "accountId": "123456789012", "status": "Success", "eventType": "RuleExecution", "clientId": "abf27092886e49a8a5c1922749736453", "topicName": "rules/test", "ruleName": "JSONLogsRule", "ruleAction": "RepublishAction", "resources": { "RepublishTopic": "rules/republish" }, "principalId": "145179c40e2219e18a909d896a5340b74cf97a39641beec2fc3eeafc5a932167" }

除了所有 CloudWatch Logs 通用的属性之外，RuleExecution 日志条目还包含以下属性：

eventType

RuleExecution (针对规则执行日志)。clientId



匹配规则的名称。

366


ruleAction

已调用操作的名称。resources

规则的操作所使用的资源的集合。principalId


任务日志AWS IoT 任务服务会生成以下事件的日志：

获取任务执行日志

在任务服务收到任务执行请求时，AWS IoT 规则引擎会生成 GetJobExecution 日志。更多信息 (13)

例如：

{ "timestamp": "2017-08-10 19:08:05.813", "logLevel": "DEBUG", "accountId": "123456789012", "status": "Success", "eventType": "GetJobExecution", "protocol": "MQTT", "clientId": "thingOne", "topicName": "$aws/things/thingOne/jobs/get", "details": "The request status is SUCCESS." }

除了所有 CloudWatch Logs 通用的属性之外，GetJobExecution 日志条目还包含以下属性：

eventType

GetJobExecution (针对获取任务执行日志)。protocol



已订阅主题的名称。details

来自任务服务的其他信息。

描述任务执行日志

在任务服务收到描述任务执行的请求时，AWS IoT 规则引擎会生成 DescribeJobExecution 日志。更多信息 (14)

例如：

367


{ "timestamp": "2017-08-10 19:13:22.841", "logLevel": "DEBUG", "accountId": "123456789012", "status": "Success", "eventType": "DescribeJobExecution", "protocol": "MQTT", "clientId": "thingOne", "jobId": "002", "topicName": "$aws/things/thingOne/jobs/002/get", "clientToken": "myToken", "details": "The request status is SUCCESS." }

除了所有 CloudWatch Logs 通用的属性之外，GetJobExecution 日志条目还包含以下属性：

eventType

DescribeJobExecution (针对描述任务执行日志)。protocol


发出请求的客户端的 ID。jobId

任务执行的任务 ID。topicName

发出请求所使用的主题。clientToken

客户端令牌。details


更新任务执行日志

在任务服务收到更新任务执行的请求时，AWS IoT 规则引擎会生成 UpdateJobExecution 日志。更多信息 (15)

例如：

{ "timestamp": "2017-08-10 19:25:14.758", "logLevel": "DEBUG", "accountId": "123456789012", "status": "Success", "eventType": "UpdateJobExecution", "protocol": "MQTT", "clientId": "thingOne", "jobId": "002", "topicName": "$aws/things/thingOne/jobs/002/update", "clientToken": "myClientToken", "versionNumber": "1", "details": "The destination status is IN_PROGRESS. The request status is SUCCESS." }

368


除了所有 CloudWatch Logs 通用的属性之外，UpdateJobExecution 日志条目还包含以下属性：

eventType

UpdateJobExecution (针对更新任务执行日志)。protocol


发出请求的客户端的 ID。jobId

任务执行的任务 ID。topicName

发出请求所使用的主题。clientToken

客户端令牌。versionNumber

任务执行的版本。details


报告最终任务执行计数

在任务完成时，AWS IoT 任务服务会生成 ReportFinalJobExecutionCount 日志。更多信息 (16)

例如：

{ "timestamp": "2017-08-10 19:44:16.776", "logLevel": "INFO", "accountId": "123456789012", "status": "Success", "eventType": "ReportFinalJobExecutionCount", "protocol": "MQTT", "jobId": "002", "details": "Job 002 completed. QUEUED job execution count: 0 IN_PROGRESS job execution count: 0 FAILED job execution count: 0 SUCCESS job execution count: 1 CANCELED job execution count: 0 REJECTED job execution count: 0 REMOVED job execution count: 0" }

除了所有 CloudWatch Logs 通用的属性之外，ReportFinalJobExecutionCount 日志条目还包含以下属性：

eventType

ReportFinalJobExecutionCount (针对报告最终任务执行计数日志)。protocol

发出请求时使用的协议。有效值为 MQTT 或 HTTP。jobId

任务执行的任务 ID。

369

AWS IoT 开发人员指南查看日志

details


查看日志查看日志

1. 浏览到 https://console.aws.amazon.com/cloudwatch/。在导航窗格中，选择 Logs。2. 在筛选条件文本框中，键入 AWSIotLogsV2，然后按 Enter。3. 双击 AWSIotLogsV2 日志组。4. 选择搜索日志组。显示为您的账户生成的 AWS IoT 日志的完整列表。5. 选择展开图标可查看单个流。

您也可以在筛选事件文本框中键入查询。可以尝试以下受到较多关注的查询：

• { $.logLevel = "INFO" }

查找所有日志级别为 INFO 的日志。• { $.status = "Success" }

查找所有状态为 Success 的日志。• { $.status = "Success" && $.eventType = "GetThingShadow" }

查找所有状态为 Success 且事件类型为 GetThingShadow 的日志。

有关创建筛选条件表达式的更多信息，请参阅 CloudWatch Logs 查询。

诊断规则问题CloudWatch Logs 是您对规则所存在的问题进行调试的最佳位置。为 AWS IoT 启用 CloudWatch Logs 后，您可了解哪些规则被触发以及操作是成功还是失败。您还可以了解 WHERE 子句条件是否匹配。

最常见的规则问题是授权问题。可通过日志了解您的角色是否获得对资源执行 AssumeRole 操作所需的权限。下面是一个精细日志记录 (p. 356)功能生成的示例日志：

{ "timestamp": "2017-12-09 22:49:17.954", "logLevel": "ERROR", "traceId": "ff563525-6469-506a-e141-78d40375fc4e", "accountId": "123456789012", "status": "Failure", "eventType": "RuleExecution", "clientId": "iotconsole-123456789012-3", "topicName": "test-topic", "ruleName": "rule1", "ruleAction": "DynamoAction", "resources": { "ItemHashKeyField": "id", "Table": "trashbin", "Operation": "Insert", "ItemHashKeyValue": "id", "IsPayloadJSON": "true" }, "principalId": "ABCDEFG1234567ABCD890:outis",

370

https://console.aws.amazon.com/cloudwatch/

http://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/FilterAndPatternSyntax.html

AWS IoT 开发人员指南诊断 Shadows 问题

"details": "User: arn:aws:sts::123456789012:assumed-role/dynamo-testbin/5aUMInJH is not authorized to perform: dynamodb:PutItem on resource: arn:aws:dynamodb:us-east-1:123456789012:table/testbin (Service: AmazonDynamoDBv2; Status Code: 400; Error Code: AccessDeniedException; Request ID: AKQJ987654321AKQJ123456789AKQJ987654321AKQJ987654321)"}

下面是一个全局日志记录 (p. 356)功能生成的类似示例日志：

2017-12-09 22:49:17.954 TRACEID:ff562535-6964-506a-e141-78d40375fc4e PRINCIPALID:ABCDEFG1234567ABCD890:outis [ERROR] EVENT:DynamoActionFailure TOPICNAME:test-topic CLIENTID:iotconsole-123456789012-3 MESSAGE:Dynamo Insert record failed. The error received was User: arn:aws:sts::123456789012:assumed-role/dynamo-testbin/5aUMInJI is not authorized to perform: dynamodb:PutItem on resource: arn:aws:dynamodb:us-east-1:123456789012:table/testbin (Service: AmazonDynamoDBv2; Status Code: 400; Error Code: AccessDeniedException; Request ID: AKQJ987654321AKQJ987654321AKQJ987654321AKQJ987654321). Message arrived on: test-topic, Action: dynamo, Table: trashbin, HashKeyField: id, HashKeyValue: id, RangeKeyField: None, RangeKeyValue: 123456789012No newer events found at the moment. Retry.

有关更多信息，请参阅 the section called “查看日志” (p. 370)。

外部服务由最终用户控制。在执行规则之前，请确保为外部服务设置了足够的吞吐量和容量单位。

诊断 Shadows 问题诊断影子

问题故障排除指南

设备的影子文档被拒绝，错误消息为“JSON 文档无效”。

如果您不熟悉 JSON，请修改本指南中提供的示例，以供您自己使用。有关更多信息，请参阅Device Shadow 文档语法。

我提交了正确的 JSON，但设备的影子文档中没有存储其中的任何内容或仅存储了一部分。

请确保您遵循了以下 JSON 格式指南。仅存储desired 和 reported 部分中的 JSON 字段。这些部分以外的 JSON 内容 (即使格式正确) 将被忽略。

我收到一条错误消息，称设备的影子超出了允许的大小。

设备的影子仅支持 8KB 数据。请尝试缩短您的JSON 文档中的字段名称。您也可以通过创建更多事物来创建更多影子。一个设备可拥有无限数量的事物/与之关联的影子。唯一的要求是，您账户中的每个事物名称都必须是唯一的。

我收到了一个超过 8KB 的设备的影子。这是怎么回事？

在您收到设备的影子之后，AWS IoT 服务会向其添加元数据。该服务将此类数据添加到其响应中，但此类数据不会计入 8KB 的限制中。只有发送到设备的影子的状态文档中有关 desired 状态和reported 状态的数据才会计入到此限制中。

我的请求由于版本错误而被拒绝了。我应该怎么办？

执行 GET 操作，以同步至最新的状态文档版本。使用 MQTT 时，请订阅 /update/accepted 主题，这样您便会收到有关状态更改的通知以及最新版本的JSON 文档。

371

http://docs.aws.amazon.com/iot/latest/developerguide/device-shadow-document-syntax.html

AWS IoT 开发人员指南诊断 Salesforce 操作问题

问题故障排除指南

时间戳关闭了几秒钟。单个字段和整个 JSON 文档的时间戳会在 AWS IoT服务收到文档或状态文档发布到./update/accepted和./update/delta 消息后更新。消息可能会由于网络发生延迟，从而导致时间戳关闭几秒钟。

我的设备可以在相应的影子主题下发布消息并订阅这些主题，但当我尝试通过 HTTP REST API 更新影子文档时，我收到了 HTTP 403 错误消息。

请确保您已在 IAM 中创建了相应的策略，能够访问这些主题并针对您使用的凭据执行相应的操作(UPDATE/GET/DELETE)。IAM 策略和证书策略是相互独立的。

其他问题。 Device Shadow 服务会将错误记录到 CloudWatchLogs。要找出设备和配置问题，请启用CloudWatch Logs 并查看日志，以获取调试信息。

诊断 Salesforce IoT 输入流操作问题执行跟踪如何查看 Salesforce 操作的执行跟踪？

如果未设置 CloudWatch Logs，请参阅使用 AWS IoT 设置 CloudWatch Logs (p. 354)部分。激活日志后，您将能够查看 Salesforce 操作的执行跟踪。

操作成功和失败如何检查是否已成功将消息发送到 Salesforce IoT 输入流？

查看在 CloudWatch Logs 中执行 Salesforce 操作所生成的日志。如果您看到“Action executedsuccessfully”，则表示 AWS IoT 规则引擎已收到来自 Salesforce IoT 的确认信息，表明消息已成功推送到目标输入流。

如果您在使用 Salesforce IoT 平台时遇到问题，请联系 Salesforce IoT 支持。如果消息未成功发送到 Salesforce IoT 输入流，该怎么办？

查看在 CloudWatch Logs 中执行 Salesforce 操作所生成的日志。您可以尝试以下操作，具体取决于日志条目：Failed to locate the host

检查此操作的 url 参数是否正确，以及您的 Salesforce IoT 输入流是否存在。Received Internal Server Error from Salesforce

重试. 如果问题仍然存在，请联系 Salesforce IoT 支持。Received Bad Request Exception from Salesforce

检查您正在发送的负载是否存在错误。Received Unsupported Media Type Exception from Salesforce

Salesforce IoT 目前不支持二进制负载。检查您是否正在发送 JSON 负载。Received Unauthorized Exception from Salesforce

检查此操作的 token 参数是否正确，以及您的令牌是否仍有效。

372

AWS IoT 开发人员指南AWS IoT 错误

Received Not Found Exception from Salesforce

检查此操作的 url 参数是否正确，以及您的 Salesforce IoT 输入流是否存在。

如果您收到此处未列出的错误，请联系 AWS Support。

AWS IoT 错误此部分列出了 AWS IoT 发送的错误代码。

消息代理错误代码

错误代码错误描述

400 错误请求。

401 未授权。

403 禁止.

503 服务不可用。

身份和安全错误代码


401 未授权。

Device Shadow 错误代码


400 错误请求。

401 未授权。

403 禁止.

404 未找到。

409 冲突.

413 请求太大。

422 无法处理请求。

429 过多请求。

500 内部错误。

503 服务不可用。

373


IoT 命令本章包含以下部分：

• AcceptCertificateTransfer (p. 377)• AddThingToThingGroup (p. 378)• AssociateTargetsWithJob (p. 380)• AttachPolicy (p. 383)• AttachPrincipalPolicy (p. 385)• AttachThingPrincipal (p. 386)• CancelCertificateTransfer (p. 388)• CancelJob (p. 389)• ClearDefaultAuthorizer (p. 392)• CreateAuthorizer (p. 393)• CreateCertificateFromCsr (p. 396)• CreateJob (p. 399)• CreateKeysAndCertificate (p. 403)• CreateOTAUpdate (p. 406)• CreatePolicy (p. 412)• CreatePolicyVersion (p. 415)• CreateRoleAlias (p. 418)• CreateStream (p. 421)• CreateThing (p. 424)• CreateThingGroup (p. 428)• CreateThingType (p. 431)• CreateTopicRule (p. 434)• DeleteAuthorizer (p. 448)• DeleteCACertificate (p. 450)• DeleteCertificate (p. 452)• DeleteOTAUpdate (p. 453)• DeletePolicy (p. 455)• DeletePolicyVersion (p. 456)• DeleteRegistrationCode (p. 458)• DeleteRoleAlias (p. 459)• DeleteStream (p. 461)• DeleteThing (p. 462)• DeleteThingGroup (p. 464)• DeleteThingShadow (p. 465)• DeleteThingType (p. 467)• DeleteTopicRule (p. 469)• DeleteV2LoggingLevel (p. 470)• DeprecateThingType (p. 472)• DescribeAuthorizer (p. 473)• DescribeCACertificate (p. 476)

374


• DescribeCertificate (p. 479)• DescribeDefaultAuthorizer (p. 483)• DescribeEndpoint (p. 485)• DescribeEventConfigurations (p. 487)• DescribeIndex (p. 489)• DescribeJob (p. 491)• DescribeJobExecution (p. 496)• DescribeJobExecution (p. 500)• DescribeRoleAlias (p. 503)• DescribeStream (p. 506)• DescribeThing (p. 509)• DescribeThingGroup (p. 512)• DescribeThingRegistrationTask (p. 516)• DescribeThingType (p. 519)• DetachPolicy (p. 522)• DetachPrincipalPolicy (p. 524)• DetachThingPrincipal (p. 526)• DisableTopicRule (p. 527)• EnableTopicRule (p. 529)• GetEffectivePolicies (p. 530)• GetIndexingConfiguration (p. 533)• GetJobDocument (p. 534)• GetLoggingOptions (p. 536)• GetOTAUpdate (p. 537)• GetPendingJobExecutions (p. 544)• GetPolicy (p. 547)• GetPolicyVersion (p. 549)• GetRegistrationCode (p. 552)• GetThingShadow (p. 553)• GetTopicRule (p. 555)• GetV2LoggingOptions (p. 569)• ListAttachedPolicies (p. 571)• ListAuthorizers (p. 574)• ListCACertificates (p. 577)• ListCertificates (p. 579)• ListCertificatesByCA (p. 582)• ListIndices (p. 585)• ListJobExecutionsForJob (p. 588)• ListJobExecutionsForThing (p. 591)• ListJobs (p. 594)• ListOTAUpdates (p. 599)• ListOutgoingCertificates (p. 601)• ListPolicies (p. 604)• ListPolicyPrincipals (p. 606)• ListPolicyVersions (p. 609)

375


• ListPrincipalPolicies (p. 611)• ListPrincipalThings (p. 614)• ListRoleAliases (p. 616)• ListStreams (p. 619)• ListTargetsForPolicy (p. 622)• ListThingGroups (p. 624)• ListThingGroupsForThing (p. 627)• ListThingPrincipals (p. 629)• ListThingRegistrationTaskReports (p. 631)• ListThingRegistrationTasks (p. 634)• ListThingTypes (p. 636)• ListThings (p. 640)• ListThingsInThingGroup (p. 643)• ListTopicRules (p. 646)• ListV2LoggingLevels (p. 648)• 发布 (p. 651)• RegisterCACertificate (p. 653)• RegisterCertificate (p. 656)• RegisterThing (p. 659)• RejectCertificateTransfer (p. 662)• RemoveThingFromThingGroup (p. 664)• ReplaceTopicRule (p. 665)• SearchIndex (p. 679)• SetDefaultAuthorizer (p. 683)• SetDefaultPolicyVersion (p. 686)• SetLoggingOptions (p. 687)• SetV2LoggingLevel (p. 689)• SetV2LoggingOptions (p. 690)• StartNextPendingJobExecution (p. 692)• StartThingRegistrationTask (p. 696)• StopThingRegistrationTask (p. 698)• TestAuthorization (p. 699)• TestInvokeAuthorizer (p. 706)• TransferCertificate (p. 709)• UpdateAuthorizer (p. 712)• UpdateCACertificate (p. 715)• UpdateCertificate (p. 717)• UpdateEventConfigurations (p. 719)• UpdateIndexingConfiguration (p. 721)• UpdateJobExecution (p. 722)• UpdateRoleAlias (p. 727)• UpdateStream (p. 730)• UpdateThing (p. 733)• UpdateThingGroup (p. 737)• UpdateThingGroupsForThing (p. 740)

376

AWS IoT 开发人员指南AcceptCertificateTransfer

• UpdateThingShadow (p. 742)

AcceptCertificateTransfer接受待处理证书传输。证书的默认状态为“INACTIVE”。

要检查待处理证书传输，请调用 ListCertificates 以枚举证书。

请求语法：

PATCH /accept-certificate-transfer/certificateId?setAsActive=setAsActive

URI 请求参数：

名称类型请求？描述

certificateId CertificateId 是证书的 ID。(证书 ARN的最后一部分包含证书ID。)

setAsActive SetAsActive 否指定证书是否活动。

错误:

ResourceNotFoundException

指定的资源不存在。

HTTP 响应代码：404TransferAlreadyCompletedException

由于传输已完成，您无法还原证书传输。

HTTP 响应代码：410InvalidRequestException

请求的内容无效。例如，UpdateJobExecution 请求包含无效状态详细信息时，将返回此代码。消息包含有关错误的详细信息。

HTTP 响应代码：400ThrottlingException

速率超过限制。

HTTP 响应代码：429UnauthorizedException

您没有权限执行此操作。

HTTP 响应代码：401ServiceUnavailableException

服务暂时不可用。

HTTP 响应代码：503

377

AWS IoT 开发人员指南CLI

InternalFailureException

出现意外错误。


CLI摘要:

aws iot accept-certificate-transfer \ --certificate-id <value> \ [--set-as-active | --no-set-as-active] \ [--cli-input-json <value>] \ [--generate-cli-skeleton]


{ "certificateId": "string", "setAsActive": "boolean"}


名称类型描述

certificateId 字符串


模式：(0x)?[a-fA-F0-9]+

证书的 ID。(证书 ARN 的最后一部分包含证书 ID。)

setAsActive 布尔值指定证书是否活动。

输出:

无

AddThingToThingGroup将事物添加到事物组。

请求语法：

PUT /thing-groups/addThingToThingGroup Content-type: application/json

{ "thingGroupName": "string", "thingGroupArn": "string", "thingName": "string", "thingArn": "string"}

378


请求正文参数：


thingGroupName ThingGroupName 否正在将事物添加到的组的名称。

thingGroupArn ThingGroupArn 否将要添加事物的组ARN。

thingName ThingName 否要添加到组中的事物的名称。

thingArn ThingArn 否要添加到组中的事物的ARN。

错误:

InvalidRequestException




HTTP 响应代码：429InternalFailureException


HTTP 响应代码：500ResourceNotFoundException



CLI摘要:

aws iot add-thing-to-thing-group \ [--thing-group-name <value>] \ [--thing-group-arn <value>] \ [--thing-name <value>] \ [--thing-arn <value>] \ [--cli-input-json <value>] \ [--generate-cli-skeleton]


{ "thingGroupName": "string",

379

AWS IoT 开发人员指南AssociateTargetsWithJob

"thingGroupArn": "string", "thingName": "string", "thingArn": "string"}


名称类型描述



模式：[a-zA-Z0-9:_-]+

正在将事物添加到的组的名称。

thingGroupArn 字符串将要添加事物的组 ARN。

thingName 字符串


模式：[a-zA-Z0-9:_-]+

要添加到组中的事物的名称。

thingArn 字符串要添加到组中的事物的 ARN。

输出:

无

AssociateTargetsWithJob将组与持续任务关联。必须满足以下标准：

• 创建任务时必须将 targetSelection 字段设置为“CONTINUOUS”。• 任务状态当前必须为“IN_PROGRESS”。• 与任务关联的目标总数不能超过 100。

请求语法：

POST /jobs/jobId/targets Content-type: application/json

{ "targets": [ "string" ], "comment": "string"}

URI 请求参数：


jobId JobId 是您在创建此任务时向其分配的唯一标识符。

380

AWS IoT 开发人员指南AssociateTargetsWithJob



targets JobTargets 是定义任务目标的事物组ARN 列表。

comment 评论否一个可选的备注字符串，用于描述为什么将任务与目标关联。

响应语法：

Content-type: application/json


响应正文参数：


jobArn JobArn 否标识任务的 ARN。

jobId JobId 否您在创建此任务时向其分配的唯一标识符。

description JobDescription 否任务的简短文本描述。

错误:





HTTP 响应代码：404LimitExceededException

附加的实体数超过了限制。




381


ServiceUnavailableException



CLI摘要:

aws iot associate-targets-with-job \ --targets <value> \ --job-id <value> \ [--comment <value>] \ [--cli-input-json <value>] \ [--generate-cli-skeleton]


{ "targets": [ "string" ], "jobId": "string", "comment": "string"}


名称类型描述

目标列表

成员：TargetArn

定义任务目标的事物组 ARN 列表。

TargetArn 字符串

jobId 字符串


模式：[a-zA-Z0-9_-]+


comment 字符串

最大长度：2028

模式：[^\\p{C}]+

一个可选的备注字符串，用于描述为什么将任务与目标关联。

输出:


382

AWS IoT 开发人员指南AttachPolicy

cli 输出字段：

名称类型描述

jobArn 字符串标识任务的 ARN。

jobId 字符串


模式：[a-zA-Z0-9_-]+



最大长度：2028

模式：[^\\p{C}]+


AttachPolicy将策略附加到指定的目标。

请求语法：

PUT /target-policies/policyName Content-type: application/json

{ "target": "string"}

URI 请求参数：


policyName PolicyName 是要附加的策略的名称。



target PolicyTarget 是策略附加到的身份。

错误:






383


ThrottlingException











CLI摘要:

aws iot attach-policy \ --policy-name <value> \ --target <value> \ [--cli-input-json <value>] \ [--generate-cli-skeleton]


{ "policyName": "string", "target": "string"}


名称类型描述

policyName 字符串


模式：[w+=,.@-]+

要附加的策略的名称。

target 字符串策略附加到的身份。

输出:

无

384

AWS IoT 开发人员指南AttachPrincipalPolicy

AttachPrincipalPolicy将指定的策略附加到指定的委托人 (证书或其他凭证)。

注意：此 API 已弃用。请改用 AttachPolicy。

请求语法：

PUT /principal-policies/policyName x-amzn-iot-principal: principal

URI 请求参数：


policyName PolicyName 是策略名称。

principal 委托人是委托人，可以是证书 ARN (从CreateCertificate 操作返回) 或 Amazon CognitoID。

错误:















385



CLI摘要:

aws iot attach-principal-policy \ --policy-name <value> \ --principal <value> \ [--cli-input-json <value>] \ [--generate-cli-skeleton]


{ "policyName": "string", "principal": "string"}


名称类型描述



模式：[w+=,.@-]+

策略名称。

principal 字符串委托人，可以是证书 ARN (从CreateCertificate 操作返回) 或Amazon Cognito ID。

输出:

无

AttachThingPrincipal将指定的委托人附加到指定的事物。

请求语法：

PUT /things/thingName/principals x-amzn-principal: principal

URI 请求参数：


thingName ThingName 是事物的名称。

principal 委托人是委托人，例如证书或其他凭证。

386


错误:














CLI摘要:

aws iot attach-thing-principal \ --thing-name <value> \ --principal <value> \ [--cli-input-json <value>] \ [--generate-cli-skeleton]


{ "thingName": "string", "principal": "string"}


名称类型描述

thingName 字符串事物的名称。

387

AWS IoT 开发人员指南CancelCertificateTransfer


模式：[a-zA-Z0-9:_-]+

principal 字符串委托人，例如证书或其他凭证。

输出:

无

CancelCertificateTransfer取消指定证书的待处理传输。

注意：只有传输源账户可以使用此操作来取消传输。(传输目标可以改为使用 RejectCertificateTransfer。) 在传输之后，AWS IoT 会将 INACTIVE 状态的证书返回到源账户。目标账户接受传输之后，无法取消传输。

取消证书传输之后，证书的状态从 PENDING_TRANSFER 更改为 INACTIVE。

请求语法：

PATCH /cancel-certificate-transfer/certificateId

URI 请求参数：



错误:










388


UnauthorizedException







CLI摘要:

aws iot cancel-certificate-transfer \ --certificate-id <value> \ [--cli-input-json <value>] \ [--generate-cli-skeleton]


{ "certificateId": "string"}


名称类型描述



模式：(0x)?[a-fA-F0-9]+


输出:

无

CancelJob取消任务。

请求语法：

PUT /jobs/jobId/cancel Content-type: application/json

{ "comment": "string"

389

AWS IoT 开发人员指南CancelJob

}

URI 请求参数：




名称类型请求？说明

comment 评论否一个可选的备注字符串，用于描述为什么取消任务。

响应语法：





jobArn JobArn 否任务 ARN。

jobId JobId 否您在创建此任务时向其分配的唯一标识符。


错误:








390





CLI摘要:

aws iot cancel-job \ --job-id <value> \ [--comment <value>] \ [--cli-input-json <value>] \ [--generate-cli-skeleton]


{ "jobId": "string", "comment": "string"}


名称类型描述

jobId 字符串


模式：[a-zA-Z0-9_-]+


comment 字符串

最大长度：2028

模式：[^\\p{C}]+

一个可选的备注字符串，用于描述为什么取消任务。

输出:


cli 输出字段：

名称类型描述


jobId 字符串


模式：[a-zA-Z0-9_-]+


391

AWS IoT 开发人员指南ClearDefaultAuthorizer

名称类型描述


最大长度：2028

模式：[^\\p{C}]+


ClearDefaultAuthorizer清除默认授权方。

请求语法：

DELETE /default-authorizer

错误:














CLI摘要:

aws iot clear-default-authorizer \ [--cli-input-json <value>] \ [--generate-cli-skeleton]

392

AWS IoT 开发人员指南CreateAuthorizer


{}

输出:

无

CreateAuthorizer创建授权方。

请求语法：

POST /authorizer/authorizerName Content-type: application/json

{ "authorizerFunctionArn": "string", "tokenKeyName": "string", "tokenSigningPublicKeys": { "string": "string" }, "status": "string"}

URI 请求参数：


authorizerName AuthorizerName 是授权方名称。



authorizerFunctionArn AuthorizerFunctionArn 是授权方 Lambda 函数的ARN。

tokenKeyName TokenKeyName 是用于从 HTTP 标头提取令牌的令牌密钥的名称。

tokenSigningPublicKeys PublicKeyMap 是用于验证由自定义身份验证服务返回的数字签名的公有密钥。

status AuthorizerStatus 否创建授权方请求的状态。

响应语法：


393


{ "authorizerName": "string", "authorizerArn": "string"}



authorizerName AuthorizerName 否授权方的名称。

authorizerArn AuthorizerArn 否授权方 ARN。

错误:

ResourceAlreadyExistsException

该资源已存在。














CLI摘要:

aws iot create-authorizer \ --authorizer-name <value> \

394


--authorizer-function-arn <value> \ --token-key-name <value> \ --token-signing-public-keys <value> \ [--status <value>] \ [--cli-input-json <value>] \ [--generate-cli-skeleton]


{ "authorizerName": "string", "authorizerFunctionArn": "string", "tokenKeyName": "string", "tokenSigningPublicKeys": { "string": "string" }, "status": "string"}


名称类型描述

authorizerName 字符串


模式：[w=,@-]+

授权方名称。

authorizerFunctionArn 字符串授权方 Lambda 函数的 ARN。

tokenKeyName 字符串


模式：[a-zA-Z0-9_-]+

用于从 HTTP 标头提取令牌的令牌密钥的名称。

tokenSigningPublicKeys map

键：KeyName

值：KeyValue

用于验证由自定义身份验证服务返回的数字签名的公有密钥。

KeyName 字符串


模式：[a-zA-Z0-9:_-]+

KeyValue 字符串

最大长度：5120

status 字符串

枚举：ACTIVE | INACTIVE

java 类：iot.identity.service.AuthorizerStatus

创建授权方请求的状态。

输出:

395

AWS IoT 开发人员指南CreateCertificateFromCsr


cli 输出字段：

名称类型描述



模式：[w=,@-]+

授权方的名称。

authorizerArn 字符串授权方 ARN。

CreateCertificateFromCsr使用指定的证书签名请求创建 X.509 证书。

注意：CSR 必须包含一个公有密钥，该密钥可以是长度至少为 2048 位的 RSA 密钥，或者是来自 NISTP-256 或 NIST P-384 曲线的 ECC 密钥。

注意：重新使用同一证书签名请求 (CSR) 会生成不同的证书。

您可以通过创建一个目录，将多个 .csr 文件复制到该目录中，然后在命令行上指定该目录，以此来成批创建多个证书。以下命令显示如何通过提供一批 CSR 来创建一批证书。

假设一组 CSR 位于目录 my-csr-directory 中：

在 Linux 和 OS X 上，命令是：

$ ls my-csr-directory/ | xargs -I aws iot create-certificate-from-csr --certificate-signing-request file://my-csr-directory/

此命令列出 my-csr-directory 中的所有 CSR 并将各个 CSR 文件名以管道方式传输到 aws iot create-certificate-from-csr AWS CLI 命令，以便为对应的 CSR 创建证书。

命令的 aws iot create-certificate-from-csr 部分也可以并行运行，以加快证书创建过程：

$ ls my-csr-directory/ | xargs -P 10 -I aws iot create-certificate-from-csr --certificate-signing-request file://my-csr-directory/

在 Windows PowerShell 上，为 my-csr-directory 中的所有 CSR 创建证书的命令为：

> ls -Name my-csr-directory | % aws iot create-certificate-from-csr --certificate-signing-request file://my-csr-directory/$_

在 Windows 命令提示符中，为 my-csr-directory 中的所有 CSR 创建证书的命令为：

> forfiles /p my-csr-directory /c "cmd /c aws iot create-certificate-from-csr --certificate-signing-request file://@path"

请求语法：

POST /certificates?setAsActive=setAsActive Content-type: application/json

{ "certificateSigningRequest": "string"

396

AWS IoT 开发人员指南CreateCertificateFromCsr

}

URI 请求参数：





certificateSigningRequest CertificateSigningRequest 是证书签名请求 (CSR)。

响应语法：


{ "certificateArn": "string", "certificateId": "string", "certificatePem": "string"}



certificateArn CertificateArn 否证书的 Amazon 资源名称 (ARN)。您可以将ARN 用作策略操作的委托人。

certificateId CertificateId 否证书的 ID。证书管理操作仅接受 certificateId。

certificatePem CertificatePem 否 PEM 格式的证书数据。

错误:








397







CLI摘要:

aws iot create-certificate-from-csr \ --certificate-signing-request <value> \ [--set-as-active | --no-set-as-active] \ [--cli-input-json <value>] \ [--generate-cli-skeleton]


{ "certificateSigningRequest": "string", "setAsActive": "boolean"}


名称类型描述

certificateSigningRequest 字符串

最小长度：1

证书签名请求 (CSR)。


输出:

{ "certificateArn": "string", "certificateId": "string", "certificatePem": "string"}

cli 输出字段：

名称类型描述

certificateArn 字符串证书的 Amazon 资源名称(ARN)。您可以将 ARN 用作策略操作的委托人。

certificateId 字符串证书的 ID。证书管理操作仅接受certificateId。

398

AWS IoT 开发人员指南CreateJob


模式：(0x)?[a-fA-F0-9]+

certificatePem 字符串


PEM 格式的证书数据。

CreateJob创建任务。

请求语法：

PUT /jobs/jobId Content-type: application/json

{ "targets": [ "string" ], "documentSource": "string", "document": "string", "description": "string", "presignedUrlConfig": { "roleArn": "string", "expiresInSec": "long" }, "targetSelection": "string", "jobExecutionsRolloutConfig": { "maximumPerMinute": "integer" }, "documentParameters": { "string": "string" }}

URI 请求参数：


jobId JobId 是任务的标识符，必须是您的 AWS 账户的唯一标识符。我们建议使用UUID。此处可以使用字母数字字符、“-”和“_”。



targets JobTargets 是任务应发送到的事物和事物组的列表。

documentSource JobDocumentSource 否指向任务文档的 S3 链接。

399

AWS IoT 开发人员指南CreateJob


文档 JobDocument 否任务文档。


presignedUrlConfig PresignedUrlConfig 否预签名 S3 URL 的配置信息。

targetSelection TargetSelection 否指定任务将继续运行(CONTINUOUS)，还是在指定作为目标的所有事物完成任务之后完成(SNAPSHOT)。如果继续运行，则在检测到目标中出现更改时，任务也会在事物上运行。例如，当某个事物添加到目标组时会在该事物上运行任务，即使是组中原有的全部事物已经完成了任务。

jobExecutionsRolloutConfigJobExecutionsRolloutConfig否允许您创建任务的分段部署。

documentParameters JobDocumentParameters 否任务文档的参数。

响应语法：





jobArn JobArn 否任务 ARN。

jobId JobId 否您分配给此任务的唯一标识符。

description JobDescription 否任务描述。

错误:




400




HTTP 响应代码：404ResourceAlreadyExistsException









CLI摘要:

aws iot create-job \ --job-id <value> \ --targets <value> \ [--document-source <value>] \ [--document <value>] \ [--description <value>] \ [--presigned-url-config <value>] \ [--target-selection <value>] \ [--job-executions-rollout-config <value>] \ [--document-parameters <value>] \ [--cli-input-json <value>] \ [--generate-cli-skeleton]


{ "jobId": "string", "targets": [ "string" ], "documentSource": "string", "document": "string", "description": "string", "presignedUrlConfig": { "roleArn": "string", "expiresInSec": "long" }, "targetSelection": "string", "jobExecutionsRolloutConfig": {

401


"maximumPerMinute": "integer" }, "documentParameters": { "string": "string" }}


名称类型描述

jobId 字符串


模式：[a-zA-Z0-9_-]+

任务的标识符，必须是您的 AWS账户的唯一标识符。我们建议使用 UUID。此处可以使用字母数字字符、“-”和“_”。

targets 列表

成员：TargetArn

任务应发送到的事物和事物组的列表。

TargetArn 字符串




文档字符串


任务文档。


最大长度：2028

模式：[^\\p{C}]+


presignedUrlConfig PresignedUrlConfig 预签名 S3 URL 的配置信息。

roleArn 字符串


IAM 角色的 ARN，该角色授予权限以从存储任务数据/更新的 S3存储桶下载文件。该角色还必须授予 IoT 下载文件的权限。

expiresInSec long








402

AWS IoT 开发人员指南CreateKeysAndCertificate

名称类型描述







键：ParameterKey


任务文档的参数。



模式：[a-zA-Z0-9:_-]+



模式：[^\\p{C}]+

输出:


cli 输出字段：

名称类型描述


jobId 字符串


模式：[a-zA-Z0-9_-]+

您分配给此任务的唯一标识符。


最大长度：2028

模式：[^\\p{C}]+

任务描述。

CreateKeysAndCertificate创建 2048 位 RSA 密钥对，并使用已发布公有密钥颁发 X.509 证书。

403

AWS IoT 开发人员指南CreateKeysAndCertificate

注意：这是 AWS IoT 唯一一次发布此证书的私有密钥，因此请务必将其保存在安全的位置。

请求语法：

POST /keys-and-certificate?setAsActive=setAsActive

URI 请求参数：



响应语法：


{ "certificateArn": "string", "certificateId": "string", "certificatePem": "string", "keyPair": { "PublicKey": "string", "PrivateKey": "string" }}



certificateArn CertificateArn 否证书的 ARN。

certificateId CertificateId 否证书的 ID。AWS IoT发布证书的默认主题名称 (例如，“AWS IoTCertificate”)。

certificatePem CertificatePem 否 PEM 格式的证书数据。

keyPair KeyPair 否生成的密钥对。

错误:







404







CLI摘要:

aws iot create-keys-and-certificate \ [--set-as-active | --no-set-as-active] \ [--cli-input-json <value>] \ [--generate-cli-skeleton]


{ "setAsActive": "boolean"}


名称类型描述


输出:

{ "certificateArn": "string", "certificateId": "string", "certificatePem": "string", "keyPair": { "PublicKey": "string", "PrivateKey": "string" }}

cli 输出字段：

名称类型描述

certificateArn 字符串证书的 ARN。



模式：(0x)?[a-fA-F0-9]+

证书的 ID。AWS IoT 发布证书的默认主题名称 (例如，“AWS IoTCertificate”)。

405

AWS IoT 开发人员指南CreateOTAUpdate

名称类型描述




keyPair KeyPair 生成的密钥对。

PublicKey 字符串

最小长度：1

公有密钥。

PrivateKey 字符串

最小长度：1

私有密钥。

CreateOTAUpdate在事物或事物组的目标组上创建 AWS IoT OTAUpdate。

请求语法：

POST /otaUpdates/otaUpdateId Content-type: application/json

{ "description": "string", "targets": [ "string" ], "targetSelection": "string", "files": [ { "fileName": "string", "fileVersion": "string", "fileSource": { "streamId": "string", "fileId": "integer" }, "codeSigning": { "awsSignerJobId": "string", "customCodeSigning": { "signature": { "stream": { "streamId": "string", "fileId": "integer" }, "inlineDocument": "blob" }, "certificateChain": { "stream": { "streamId": "string", "fileId": "integer" }, "certificateName": "string", "inlineDocument": "string" }, "hashAlgorithm": "string", "signatureAlgorithm": "string" } },

406


"attributes": { "string": "string" } } ], "roleArn": "string", "additionalParameters": { "string": "string" }}

URI 请求参数：


otaUpdateId OTAUpdateId 是要创建的 OTA 更新的ID。



description OTAUpdateDescription 否 OTA 更新的描述。

targets 目标是接收 OTA 更新的目标设备。

targetSelection TargetSelection 否指定更新将继续运行(CONTINUOUS)，还是在指定作为目标的所有事物完成更新之后完成 (SNAPSHOT)。如果继续运行，则在检测到目标中出现更改时，更新也会在事物上运行。例如，当某个事物添加到目标组时会在该事物上运行更新，即使是组中原有的全部事物已经完成了更新。有效值：CONTINUOUS |SNAPSHOT。

files OTAUpdateFiles 是应由 OTA 更新流式处理的文件。

roleArn RoleArn 是允许访问 AWS IoT Jobs服务的 IAM 角色。

additionalParameters AdditionalParameterMap 否其他 OTA 更新参数 (名称/值对) 的列表。

响应语法：


{

407


"otaUpdateId": "string", "awsIotJobId": "string", "otaUpdateArn": "string", "awsIotJobArn": "string", "otaUpdateStatus": "string"}



otaUpdateId OTAUpdateId 否 OTA 更新 ID。

awsIotJobId AwsIotJobId 否与 OTA 更新关联的AWS IoT 任务 ID。

otaUpdateArn OTAUpdateArn 否 OTA 更新 ARN。

awsIotJobArn AwsIotJobArn 否与 OTA 更新关联的AWS IoT 任务 ARN。

otaUpdateStatus OTAUpdateStatus 否 OTA 更新状态。

错误:
















408


CLI摘要:

aws iot create-ota-update \ --ota-update-id <value> \ [--description <value>] \ --targets <value> \ [--target-selection <value>] \ --files <value> \ --role-arn <value> \ [--additional-parameters <value>] \ [--cli-input-json <value>] \ [--generate-cli-skeleton]


{ "otaUpdateId": "string", "description": "string", "targets": [ "string" ], "targetSelection": "string", "files": [ { "fileName": "string", "fileVersion": "string", "fileSource": { "streamId": "string", "fileId": "integer" }, "codeSigning": { "awsSignerJobId": "string", "customCodeSigning": { "signature": { "stream": { "streamId": "string", "fileId": "integer" }, "inlineDocument": "blob" }, "certificateChain": { "stream": { "streamId": "string", "fileId": "integer" }, "certificateName": "string", "inlineDocument": "string" }, "hashAlgorithm": "string", "signatureAlgorithm": "string" } }, "attributes": { "string": "string" } } ], "roleArn": "string", "additionalParameters": { "string": "string" }

409


}


名称类型描述

otaUpdateId 字符串


模式：[a-zA-Z0-9_-]+

要创建的 OTA 更新的 ID。


最大长度：2028

模式：[^\\p{C}]+

OTA 更新的描述。

targets 列表

成员：Target

接收 OTA 更新的目标设备。

Target 字符串



指定更新将继续运行(CONTINUOUS)，还是在指定作为目标的所有事物完成更新之后完成 (SNAPSHOT)。如果继续运行，则在检测到目标中出现更改时，更新也会在事物上运行。例如，当某个事物添加到目标组时会在该事物上运行更新，即使是组中原有的全部事物已经完成了更新。有效值：CONTINUOUS |SNAPSHOT。

files 列表

成员：OTAUpdateFile

应由 OTA 更新流式处理的文件。

OTAUpdateFile OTAUpdateFile

fileName 字符串文件的名称。

fileVersion 字符串文件版本。

fileSource 流文件的源。

streamId 字符串


模式：[a-zA-Z0-9_-]+

流 ID。

fileId integer



与流关联的文件的 ID。

codeSigning CodeSigning 文件的代码签名方法。

410


名称类型描述

awsSignerJobId 字符串已创建用于对文件签名的AWSSignerJob 的 ID。

customCodeSigning CustomCodeSigning 用于对文件执行代码签名的自定义方法。

签名 CodeSigningSignature 文件的签名。

stream 流代码签署签名的流。

streamId 字符串


模式：[a-zA-Z0-9_-]+

流 ID。

fileId integer




inlineDocument blob 代码签署签名的 base64 编码二进制表示形式。

certificateChain CodeSigningCertificateChain 证书链。

stream 流证书链文件的流。

streamId 字符串


模式：[a-zA-Z0-9_-]+

流 ID。

fileId integer




certificateName 字符串证书的名称。

inlineDocument 字符串代码签名证书链的 base64 编码二进制表示形式。

hashAlgorithm 字符串用于对文件进行代码签名的哈希算法。

signatureAlgorithm 字符串用于对文件进行代码签名的签名算法。

个属性 map

键：Key

值：Value

名称/属性对的列表。

Key 字符串

411

AWS IoT 开发人员指南CreatePolicy

名称类型描述

值字符串

roleArn 字符串


允许访问 AWS IoT Jobs 服务的IAM 角色。

additionalParameters map

键：Key

值：Value

其他 OTA 更新参数 (名称/值对)的列表。

Key 字符串

值字符串

输出:

{ "otaUpdateId": "string", "awsIotJobId": "string", "otaUpdateArn": "string", "awsIotJobArn": "string", "otaUpdateStatus": "string"}

cli 输出字段：

名称类型描述



模式：[a-zA-Z0-9_-]+

OTA 更新 ID。

awsIotJobId 字符串与 OTA 更新关联的 AWS IoT 任务 ID。

otaUpdateArn 字符串 OTA 更新 ARN。

awsIotJobArn 字符串与 OTA 更新关联的 AWS IoT 任务 ARN。

otaUpdateStatus 字符串

枚举：CREATE_PENDING| CREATE_IN_PROGRESS| CREATE_COMPLETE |CREATE_FAILED

OTA 更新状态。

CreatePolicy创建 AWS IoT 策略。

创建的策略是策略的默认版本。此操作使用版本标识符 1 创建策略版本，并将策略的默认版本设置为 1。

412

AWS IoT 开发人员指南CreatePolicy

请求语法：

POST /policies/policyName Content-type: application/json

{ "policyDocument": "string"}

URI 请求参数：





policyDocument PolicyDocument 是描述该策略的 JSON 文档。policyDocument 的最小长度为 1，最大长度为 2048，不包括空格。

响应语法：


{ "policyName": "string", "policyArn": "string", "policyDocument": "string", "policyVersionId": "string"}



policyName PolicyName 否策略名称。

policyArn PolicyArn 否策略 ARN。

policyDocument PolicyDocument 否描述该策略的 JSON 文档。

policyVersionId PolicyVersionId 否策略版本 ID。

错误:




413


MalformedPolicyException

策略文档无效。












CLI摘要:

aws iot create-policy \ --policy-name <value> \ --policy-document <value> \ [--cli-input-json <value>] \ [--generate-cli-skeleton]


{ "policyName": "string", "policyDocument": "string"}


名称类型描述



模式：[w+=,.@-]+

策略名称。

414

AWS IoT 开发人员指南CreatePolicyVersion

名称类型描述

policyDocument 字符串描述该策略的 JSON 文档。policyDocument 的最小长度为 1，最大长度为 2048，不包括空格。

输出:

{ "policyName": "string", "policyArn": "string", "policyDocument": "string", "policyVersionId": "string"}

cli 输出字段：

名称类型描述



模式：[w+=,.@-]+

策略名称。

policyArn 字符串策略 ARN。

policyDocument 字符串描述该策略的 JSON 文档。

policyVersionId 字符串

模式：[0-9]+

策略版本 ID。

CreatePolicyVersion创建指定 AWS IoT 策略的新版本。要更新策略，请创建新策略版本。一个托管策略最多可以有五个版本。如果策略有五个版本，则在创建新版本之前，必须使用 DeletePolicyVersion 删除一个现有版本。

(可选) 您可以将新版本设置为策略的默认版本。默认版本是有效版本 (即，该版本对策略所附加到的证书生效)。

请求语法：

POST /policies/policyName/version?setAsDefault=setAsDefault Content-type: application/json

{ "policyDocument": "string"}

URI 请求参数：



415

AWS IoT 开发人员指南CreatePolicyVersion


setAsDefault SetAsDefault 否指定是否将策略版本设置为默认版本。当此参数为 true 时，新策略版本将成为有效版本 (即，该版本对策略所附加到的证书生效)。



policyDocument PolicyDocument 是描述该策略的 JSON 文档。最小长度为 1。最大长度为 2048，不包括空格。

响应语法：


{ "policyArn": "string", "policyDocument": "string", "policyVersionId": "string", "isDefaultVersion": "boolean"}






isDefaultVersion IsDefaultVersion 否指定策略版本是否为默认版本。

错误:



HTTP 响应代码：404MalformedPolicyException

策略文档无效。


416


VersionsLimitExceededException

策略版本数超过了限制。












CLI摘要:

aws iot create-policy-version \ --policy-name <value> \ --policy-document <value> \ [--set-as-default | --no-set-as-default] \ [--cli-input-json <value>] \ [--generate-cli-skeleton]


{ "policyName": "string", "policyDocument": "string", "setAsDefault": "boolean"}


名称类型描述



策略名称。

417

AWS IoT 开发人员指南CreateRoleAlias

名称类型描述模式：[w+=,.@-]+

policyDocument 字符串描述该策略的 JSON 文档。最小长度为 1。最大长度为 2048，不包括空格。

setAsDefault 布尔值指定是否将策略版本设置为默认版本。当此参数为 true 时，新策略版本将成为有效版本 (即，该版本对策略所附加到的证书生效)。

输出:

{ "policyArn": "string", "policyDocument": "string", "policyVersionId": "string", "isDefaultVersion": "boolean"}

cli 输出字段：

名称类型描述




模式：[0-9]+

策略版本 ID。

isDefaultVersion 布尔值指定策略版本是否为默认版本。

CreateRoleAlias创建角色别名。

请求语法：

POST /role-aliases/roleAlias Content-type: application/json

{ "roleArn": "string", "credentialDurationSeconds": "integer"}

URI 请求参数：


roleAlias RoleAlias 是指向角色 ARN 的角色别名。这样您就可以更

418

AWS IoT 开发人员指南CreateRoleAlias

名称类型请求？描述改角色，而无需更新设备。



roleArn RoleArn 是角色 ARN。

credentialDurationSecondsCredentialDurationSeconds否凭证有效的时间长度 (以秒为单位)。

响应语法：


{ "roleAlias": "string", "roleAliasArn": "string"}



roleAlias RoleAlias 否角色别名。

roleAliasArn RoleAliasArn 否角色别名 ARN。

错误:











419







CLI摘要:

aws iot create-role-alias \ --role-alias <value> \ --role-arn <value> \ [--credential-duration-seconds <value>] \ [--cli-input-json <value>] \ [--generate-cli-skeleton]


{ "roleAlias": "string", "roleArn": "string", "credentialDurationSeconds": "integer"}


名称类型描述

roleAlias 字符串


模式：[w=,@-]+

指向角色 ARN 的角色别名。这样您就可以更改角色，而无需更新设备。

roleArn 字符串


角色 ARN。

credentialDurationSeconds integer


范围 – 最大值：3600，最小值：900

凭证有效的时间长度 (以秒为单位)。

输出:

{ "roleAlias": "string", "roleAliasArn": "string"

420

AWS IoT 开发人员指南CreateStream

}

cli 输出字段：

名称类型描述

roleAlias 字符串


模式：[w=,@-]+

角色别名。

roleAliasArn 字符串角色别名 ARN。

CreateStream创建一个流，以便通过 MQTT 以分块形式传送一个或多个大文件。流将来自 S3 之类的源的数据字节打包为MQTT 消息，以块或数据块的形式传输。您可以将一个或多个文件与一个流关联。与流关联的文件的总大小不能超过 2 MB。创建流时版本为 0 。如果创建流使用的 streamID 与曾经存在但在过去 90 天内删除的流相同，我们会将版本增加 1 来重新使用旧的流。

请求语法：

POST /streams/streamId Content-type: application/json

{ "description": "string", "files": [ { "fileId": "integer", "s3Location": { "bucket": "string", "key": "string", "version": "string" } } ], "roleArn": "string"}

URI 请求参数：


streamId StreamId 是流 ID。



description StreamDescription 否流的描述。

files StreamFiles 是要流式处理的文件。

roleArn RoleArn 是一个 IAM 角色，IoT 服务委托人可以代入该角色以访问您的 S3 文件。

421

AWS IoT 开发人员指南CreateStream

响应语法：


{ "streamId": "string", "streamArn": "string", "description": "string", "streamVersion": "integer"}



streamId StreamId 否流 ID。

streamArn StreamArn 否流 ARN。


streamVersion StreamVersion 否流的版本。

错误:















422



CLI摘要:

aws iot create-stream \ --stream-id <value> \ [--description <value>] \ --files <value> \ --role-arn <value> \ [--cli-input-json <value>] \ [--generate-cli-skeleton]


{ "streamId": "string", "description": "string", "files": [ { "fileId": "integer", "s3Location": { "bucket": "string", "key": "string", "version": "string" } } ], "roleArn": "string"}


名称类型描述

streamId 字符串


模式：[a-zA-Z0-9_-]+

流 ID。


最大长度：2028

模式：[^\\p{C}]+

流的描述。

files 列表

成员：StreamFile

要流式处理的文件。

StreamFile StreamFile

fileId integer



文件 ID。

423

AWS IoT 开发人员指南CreateThing

名称类型描述

s3Location S3 位置 S3 中文件的位置。

bucket 字符串

最小长度：1

包含要流式处理的文件的 S3 存储桶。

key 字符串

最小长度：1

S3 存储桶中要流式处理的文件的名称。

version 字符串文件版本。

roleArn 字符串


一个 IAM 角色，IoT 服务委托人可以代入该角色以访问您的 S3 文件。

输出:


cli 输出字段：

名称类型描述

streamId 字符串


模式：[a-zA-Z0-9_-]+

流 ID。

streamArn 字符串流 ARN。


最大长度：2028

模式：[^\\p{C}]+

流的描述。

streamVersion integer



流的版本。

CreateThing在注册表中创建事物记录。

请求语法：

424

AWS IoT 开发人员指南CreateThing

POST /things/thingName Content-type: application/json

{ "thingTypeName": "string", "attributePayload": { "attributes": { "string": "string" }, "merge": "boolean" }}

URI 请求参数：


thingName ThingName 是要创建的事物的名称。



thingTypeName ThingTypeName 否与新事物关联的事物类型的名称。

attributePayload AttributePayload 否属性负载，由 JSON 文档中最多三个名称/值对组成。例如：

\"attributes\":{\"string1\":\"string2\"}

响应语法：


{ "thingName": "string", "thingArn": "string", "thingId": "string"}



thingName ThingName 否新事物的名称。

thingArn ThingArn 否新事物的 ARN。

thingId 事物 ID 否事物 ID。

错误:

425

















CLI摘要:

aws iot create-thing \ --thing-name <value> \ [--thing-type-name <value>] \ [--attribute-payload <value>] \ [--cli-input-json <value>] \ [--generate-cli-skeleton]


{ "thingName": "string", "thingTypeName": "string", "attributePayload": { "attributes": {

426


"string": "string" }, "merge": "boolean" }}


名称类型描述

thingName 字符串


模式：[a-zA-Z0-9:_-]+

要创建的事物的名称。

thingTypeName 字符串


模式：[a-zA-Z0-9:_-]+

与新事物关联的事物类型的名称。

attributePayload AttributePayload 属性负载，由 JSON 文档中最多三个名称/值对组成。例如：


个属性 map

键：AttributeName

值：AttributeValue

一个 JSON 字符串，其中最多包含三个 JSON 格式的键/值对。例如：


AttributeName 字符串

最大长度：128

模式：[a-zA-Z0-9_.,@/:#-]+

AttributeValue 字符串

最大长度：800

模式：[a-zA-Z0-9_.,@/:#-]*

merge 布尔值指定在 AttributePayload 中提供的属性列表是否与存储在注册表中的属性合并，而不是覆盖。

要删除属性，请使用空属性值调用 UpdateThing。

Note

merge 属性仅在调用UpdateThing 时有效。

427

AWS IoT 开发人员指南CreateThingGroup

输出:

{ "thingName": "string", "thingArn": "string", "thingId": "string"}

cli 输出字段：

名称类型描述

thingName 字符串


模式：[a-zA-Z0-9:_-]+

新事物的名称。

thingArn 字符串新事物的 ARN。

thingId 字符串事物 ID。

CreateThingGroup创建事物组。

请求语法：

POST /thing-groups/thingGroupName Content-type: application/json

{ "parentGroupName": "string", "thingGroupProperties": { "thingGroupDescription": "string", "attributePayload": { "attributes": { "string": "string" }, "merge": "boolean" } }}

URI 请求参数：


thingGroupName ThingGroupName 是要创建的事物组名称。



parentGroupName ThingGroupName 否父事物组的名称。

428



thingGroupProperties ThingGroupProperties 否事物组属性。

响应语法：


{ "thingGroupName": "string", "thingGroupArn": "string", "thingGroupId": "string"}



thingGroupName ThingGroupName 否事物组名称。

thingGroupArn ThingGroupArn 否事物组 ARN。

thingGroupId ThingGroupId 否事物组 ID。

错误:










CLI摘要:

aws iot create-thing-group \

429


--thing-group-name <value> \ [--parent-group-name <value>] \ [--thing-group-properties <value>] \ [--cli-input-json <value>] \ [--generate-cli-skeleton]


{ "thingGroupName": "string", "parentGroupName": "string", "thingGroupProperties": { "thingGroupDescription": "string", "attributePayload": { "attributes": { "string": "string" }, "merge": "boolean" } }}


名称类型描述



模式：[a-zA-Z0-9:_-]+

要创建的事物组名称。

parentGroupName 字符串


模式：[a-zA-Z0-9:_-]+

父事物组的名称。

thingGroupProperties ThingGroupProperties 事物组属性。

thingGroupDescription 字符串

最大长度：2028

模式：[\\p {Graph}]*

事物组的描述。

attributePayload AttributePayload JSON 格式的事物组属性。

个属性 map

键：AttributeName





最大长度：128

模式：[a-zA-Z0-9_.,@/:#-]+

430

AWS IoT 开发人员指南CreateThingType

名称类型描述


最大长度：800

模式：[a-zA-Z0-9_.,@/:#-]*



Note


输出:

{ "thingGroupName": "string", "thingGroupArn": "string", "thingGroupId": "string"}

cli 输出字段：

名称类型描述



模式：[a-zA-Z0-9:_-]+

事物组名称。

thingGroupArn 字符串事物组 ARN。



模式：[a-zA-Z0-9-]+

事物组 ID。

CreateThingType创建新事物类型。

请求语法：

POST /thing-types/thingTypeName Content-type: application/json

431

AWS IoT 开发人员指南CreateThingType

{ "thingTypeProperties": { "thingTypeDescription": "string", "searchableAttributes": [ "string" ] }}

URI 请求参数：


thingTypeName ThingTypeName 是事务类型的名称。



thingTypeProperties ThingTypeProperties 否要创建的事物类型的ThingTypeProperties。它包含有关新事物类型的信息 (包括描述)，以及可搜索事物属性名称的列表。

响应语法：


{ "thingTypeName": "string", "thingTypeArn": "string", "thingTypeId": "string"}



thingTypeName ThingTypeName 否事务类型的名称。

thingTypeArn ThingTypeArn 否事物类型的 Amazon 资源名称 (ARN)。

thingTypeId ThingTypeId 否事物类型 ID。

错误:




432


ThrottlingException











CLI摘要:

aws iot create-thing-type \ --thing-type-name <value> \ [--thing-type-properties <value>] \ [--cli-input-json <value>] \ [--generate-cli-skeleton]


{ "thingTypeName": "string", "thingTypeProperties": { "thingTypeDescription": "string", "searchableAttributes": [ "string" ] }}


名称类型描述



模式：[a-zA-Z0-9:_-]+

事务类型的名称。

433

AWS IoT 开发人员指南CreateTopicRule

名称类型描述

thingTypeProperties ThingTypeProperties 要创建的事物类型的ThingTypeProperties。它包含有关新事物类型的信息 (包括描述)，以及可搜索事物属性名称的列表。

thingTypeDescription 字符串

最大长度：2028


事物类型的描述。

searchableAttributes 列表

成员：AttributeName


可搜索事物属性名称的列表。


最大长度：128

模式：[a-zA-Z0-9_.,@/:#-]+

输出:

{ "thingTypeName": "string", "thingTypeArn": "string", "thingTypeId": "string"}

cli 输出字段：

名称类型描述



模式：[a-zA-Z0-9:_-]+


thingTypeArn 字符串事物类型的 Amazon 资源名称(ARN)。

thingTypeId 字符串事物类型 ID。

CreateTopicRule创建规则。创建规则是管理员级别操作。有权创建规则的所有用户都将能够访问规则所处理的数据。

请求语法：

POST /rules/ruleName

434



{ "topicRulePayload": { "sql": "string", "description": "string", "actions": [ { "dynamoDB": { "tableName": "string", "roleArn": "string", "operation": "string", "hashKeyField": "string", "hashKeyValue": "string", "hashKeyType": "string", "rangeKeyField": "string", "rangeKeyValue": "string", "rangeKeyType": "string", "payloadField": "string" }, "dynamoDBv2": { "roleArn": "string", "putItem": { "tableName": "string" } }, "lambda": { "functionArn": "string" }, "sns": { "targetArn": "string", "roleArn": "string", "messageFormat": "string" }, "sqs": { "roleArn": "string", "queueUrl": "string", "useBase64": "boolean" }, "kinesis": { "roleArn": "string", "streamName": "string", "partitionKey": "string" }, "republish": { "roleArn": "string", "topic": "string" }, "s3": { "roleArn": "string", "bucketName": "string", "key": "string", "cannedAcl": "string" }, "firehose": { "roleArn": "string", "deliveryStreamName": "string", "separator": "string" }, "cloudwatchMetric": { "roleArn": "string", "metricNamespace": "string", "metricName": "string", "metricValue": "string", "metricUnit": "string", "metricTimestamp": "string"

435


}, "cloudwatchAlarm": { "roleArn": "string", "alarmName": "string", "stateReason": "string", "stateValue": "string" }, "elasticsearch": { "roleArn": "string", "endpoint": "string", "index": "string", "type": "string", "id": "string" }, "salesforce": { "token": "string", "url": "string" } } ], "ruleDisabled": "boolean", "awsIotSqlVersion": "string", "errorAction": { "dynamoDB": { "tableName": "string", "roleArn": "string", "operation": "string", "hashKeyField": "string", "hashKeyValue": "string", "hashKeyType": "string", "rangeKeyField": "string", "rangeKeyValue": "string", "rangeKeyType": "string", "payloadField": "string" }, "dynamoDBv2": { "roleArn": "string", "putItem": { "tableName": "string" } }, "lambda": { "functionArn": "string" }, "sns": { "targetArn": "string", "roleArn": "string", "messageFormat": "string" }, "sqs": { "roleArn": "string", "queueUrl": "string", "useBase64": "boolean" }, "kinesis": { "roleArn": "string", "streamName": "string", "partitionKey": "string" }, "republish": { "roleArn": "string", "topic": "string" }, "s3": { "roleArn": "string", "bucketName": "string",

436


"key": "string", "cannedAcl": "string" }, "firehose": { "roleArn": "string", "deliveryStreamName": "string", "separator": "string" }, "cloudwatchMetric": { "roleArn": "string", "metricNamespace": "string", "metricName": "string", "metricValue": "string", "metricUnit": "string", "metricTimestamp": "string" }, "cloudwatchAlarm": { "roleArn": "string", "alarmName": "string", "stateReason": "string", "stateValue": "string" }, "elasticsearch": { "roleArn": "string", "endpoint": "string", "index": "string", "type": "string", "id": "string" }, "salesforce": { "token": "string", "url": "string" } } }}

URI 请求参数：


ruleName RuleName 是规则的名称。



topicRulePayload TopicRulePayload 是规则负载。

错误:

SqlParseException

无法正确解析 Rule-SQL 表达式。

HTTP 响应代码：400InternalException



437









CLI摘要:

aws iot create-topic-rule \ --rule-name <value> \ --topic-rule-payload <value> \ [--cli-input-json <value>] \ [--generate-cli-skeleton]


{ "ruleName": "string", "topicRulePayload": { "sql": "string", "description": "string", "actions": [ { "dynamoDB": { "tableName": "string", "roleArn": "string", "operation": "string", "hashKeyField": "string", "hashKeyValue": "string", "hashKeyType": "string", "rangeKeyField": "string", "rangeKeyValue": "string", "rangeKeyType": "string", "payloadField": "string" }, "dynamoDBv2": { "roleArn": "string", "putItem": { "tableName": "string" } }, "lambda": { "functionArn": "string" }, "sns": { "targetArn": "string",

438


"roleArn": "string", "messageFormat": "string" }, "sqs": { "roleArn": "string", "queueUrl": "string", "useBase64": "boolean" }, "kinesis": { "roleArn": "string", "streamName": "string", "partitionKey": "string" }, "republish": { "roleArn": "string", "topic": "string" }, "s3": { "roleArn": "string", "bucketName": "string", "key": "string", "cannedAcl": "string" }, "firehose": { "roleArn": "string", "deliveryStreamName": "string", "separator": "string" }, "cloudwatchMetric": { "roleArn": "string", "metricNamespace": "string", "metricName": "string", "metricValue": "string", "metricUnit": "string", "metricTimestamp": "string" }, "cloudwatchAlarm": { "roleArn": "string", "alarmName": "string", "stateReason": "string", "stateValue": "string" }, "elasticsearch": { "roleArn": "string", "endpoint": "string", "index": "string", "type": "string", "id": "string" }, "salesforce": { "token": "string", "url": "string" } } ], "ruleDisabled": "boolean", "awsIotSqlVersion": "string", "errorAction": { "dynamoDB": { "tableName": "string", "roleArn": "string", "operation": "string", "hashKeyField": "string", "hashKeyValue": "string", "hashKeyType": "string", "rangeKeyField": "string",

439


"rangeKeyValue": "string", "rangeKeyType": "string", "payloadField": "string" }, "dynamoDBv2": { "roleArn": "string", "putItem": { "tableName": "string" } }, "lambda": { "functionArn": "string" }, "sns": { "targetArn": "string", "roleArn": "string", "messageFormat": "string" }, "sqs": { "roleArn": "string", "queueUrl": "string", "useBase64": "boolean" }, "kinesis": { "roleArn": "string", "streamName": "string", "partitionKey": "string" }, "republish": { "roleArn": "string", "topic": "string" }, "s3": { "roleArn": "string", "bucketName": "string", "key": "string", "cannedAcl": "string" }, "firehose": { "roleArn": "string", "deliveryStreamName": "string", "separator": "string" }, "cloudwatchMetric": { "roleArn": "string", "metricNamespace": "string", "metricName": "string", "metricValue": "string", "metricUnit": "string", "metricTimestamp": "string" }, "cloudwatchAlarm": { "roleArn": "string", "alarmName": "string", "stateReason": "string", "stateValue": "string" }, "elasticsearch": { "roleArn": "string", "endpoint": "string", "index": "string", "type": "string", "id": "string" }, "salesforce": { "token": "string",

440


"url": "string" } } }}


名称类型描述

ruleName 字符串


模式：^[a-zA-Z0-9_]+$

规则的名称。

topicRulePayload TopicRulePayload 规则负载。

sql 字符串用于查询主题的 SQL 语句。有关更多信息，请参阅 AWS IoT 开发人员指南中的 AWS IoT SQL 参考。

description 字符串规则的描述。

操作列表

成员：Action

与该规则关联的操作。

操作操作

dynamoDB DynamoDBAction 写入到 DynamoDB 表。

tableName 字符串 DynamoDB 表的名称。

roleArn 字符串授予对 DynamoDB 表的访问权限的 IAM 角色的 ARN。

operation 字符串要执行的操作类型。该信息遵循替换模板，因此可以是 $operation，但替换必须产生以下操作之一：INSERT、UPDATE或 DELETE。

hashKeyField 字符串哈希键名称。

hashKeyValue 字符串哈希键值。

hashKeyType 字符串

枚举：STRING | NUMBER

java 类：iot.goldeneye.service.DynamoKeyType

哈希键类型。有效值为“STRING”或“NUMBER”

rangeKeyField 字符串范围键名称。

rangeKeyValue 字符串范围键值。

rangeKeyType 字符串


范围键类型。有效值为“STRING”或“NUMBER”

441

http://docs.aws.amazon.com/iot/latest/developerguide/iot-rules.html#aws-iot-sql-reference



名称类型描述java 类：iot.goldeneye.service.DynamoKeyType

payloadField 字符串操作负载。此名称可以自定义。

dynamoDBv2 DynamoDBv2Action 写入到 DynamoDB 表。这是DynamoDB 操作的新版本。它允许您将 MQTT 消息负载中的各个属性分别写入不同的 DynamoDB列。


putItem PutItemInput 指定消息数据将写入的DynamoDB 表。例如：

{ "dynamoDBv2":{ "roleArn":"aws:iam:12341251:my-role" "putItem":{ "tableName": "my-table" } } }

消息负载中的每个属性将写入到DynamoDB 数据库中的单独一列。

tableName 字符串消息数据将写入的表

lambda LambdaAction 调用 Lambda 函数。

functionArn 字符串 Lambda 函数的 ARN。

sns SnsAction 发布到 Amazon SNS 主题。

targetArn 字符串 SNS 主题的 ARN。

roleArn 字符串授予访问权限的 IAM 角色的ARN。

messageFormat 字符串

枚举：RAW | JSON

java 类：iot.goldeneye.service.MessageFormat

要发布的消息的消息格式。可选。接受的值为“JSON”和“RAW”。该属性的默认值为“RAW”。SNS 使用此设置来确定是否应解析负载，以及是否应提取负载的特定于平台的相关位。要了解有关 SNS 消息格式的更多信息，请访问 http://docs.aws.amazon.com/sns/latest/dg/json-formats.html 以查看其官方文档。

sqs SqsAction 发布到 Amazon SQS 队列。


442

http://docs.aws.amazon.com/sns/latest/dg/json-formats.html




名称类型描述

queueUrl 字符串 Amazon SQS 队列的 URL。

useBase64 布尔值


指定是否使用 Base64 编码。

kinesis KinesisAction 将数据写入 Amazon Kinesis 流。

roleArn 字符串授予对 Amazon Kinesis 流的访问权限的 IAM 角色的 ARN。

streamName 字符串 Amazon Kinesis 流的名称。

partitionKey 字符串分区键。

重新发布 RepublishAction 发布到其他 MQTT 主题。


topic 字符串 MQTT; 主题的名称。

S3 S3 操作写入 Amazon S3 存储桶。


bucketName 字符串 Amazon S3 存储桶。

key 字符串对象键。

cannedAcl 字符串

枚举：private | public-read |public-read-write | aws-exec-read| authenticated-read | bucket-owner-read | bucket-owner-full-control | log-delivery-write

java 类：iot.goldeneye.service.CannedAccessControlList

Amazon S3 标准 ACL，用于控制对由对象键标识的对象的访问权限。有关更多信息，请参阅 S3 标准 ACL。

firehose FirehoseAction 将数据写入 Amazon KinesisFirehose 流。

roleArn 字符串授予对 Amazon Kinesis Firehose流的访问权限的 IAM 角色。

deliveryStreamName 字符串传输流名称。

separator 字符串

pattern: ([ ])|( )|(,)

将用于分隔写入到 Firehose 流的记录的字符分隔符。有效值为：'\n'（换行符）、'\t'（制表符）、'\r\n'（Windows 换行符）、','（逗号）。

cloudwatchMetric CloudwatchMetricAction 捕获 CloudWatch 指标。

443




名称类型描述

roleArn 字符串允许访问 CloudWatch 指标的IAM 角色。

metricNamespace 字符串 CloudWatch 指标命名空间名称。

metricName 字符串 CloudWatch 指标名称。

metricValue 字符串 CloudWatch 指标值。

metricUnit 字符串 CloudWatch 支持的指标单位。

metricTimestamp 字符串可选 Unix 时间戳。

cloudwatchAlarm CloudwatchAlarmAction 更改 CloudWatch 警报的状态。

roleArn 字符串允许访问 CloudWatch 警报的IAM 角色。

alarmName 字符串 CloudWatch 警报名称。

stateReason 字符串警报更改的原因。

stateValue 字符串警报状态的值。可接受的值为：OK、ALARM、INSUFFICIENT_DATA。

elasticsearch ElasticsearchAction 将数据写入 AmazonElasticsearch Service 域。

roleArn 字符串具有 Elasticsearch 访问权限的IAM 角色 ARN。

endpoint 字符串

模式：https?://.*

Elasticsearch 域的终端节点。

index 字符串您要在其中存储数据的Elasticsearch 索引。

type 字符串您存储的文档类型。

id 字符串您将要存储的文档的唯一标识符。

salesforce SalesforceAction 向 Salesforce IoT Cloud 输入流发送消息。

token 字符串

最小长度：40

用于验证对 Salesforce IoT Cloud输入流的访问权限的令牌。在创建输入流之后，可从 SalesforceIoT Cloud 平台获取该令牌。

url 字符串

最大长度：2000

模式：https://ingestion-[a-zA-Z0-9]{1,12}.[a-zA-Z0-9]+.((sfdc-matrix.net)|(sfdcnow.com))/streams/w 1,20/w 1,20/event

由 Salesforce IoT Cloud 输入流公开的 URL。在创建输入流之后，可从 Salesforce IoT Cloud 平台获取该 URL。

444

http://docs.aws.amazon.com/AmazonCloudWatch/latest/DeveloperGuide/cloudwatch_concepts.html#Unit

http://docs.aws.amazon.com/AmazonCloudWatch/latest/DeveloperGuide/cloudwatch_concepts.html#about_timestamp


名称类型描述

ruleDisabled 布尔值


指定是否禁用规则。

awsIotSqlVersion 字符串评估规则时使用的 SQL 规则引擎的版本。

errorAction 操作发生错误时要执行的操作。




















445


名称类型描述











枚举：RAW | JSON






useBase64 布尔值







446





名称类型描述








cannedAcl 字符串







separator 字符串

pattern: ([ ])|( )|(,)










447





AWS IoT 开发人员指南DeleteAuthorizer

名称类型描述







endpoint 字符串







token 字符串

最小长度：40


url 字符串

最大长度：2000



输出:

无

DeleteAuthorizer删除授权方。

请求语法：

DELETE /authorizer/authorizerName

448


URI 请求参数：


authorizerName AuthorizerName 是要删除的授权方的名称。

错误:

DeleteConflictException

由于资源已附加到一个或多个资源，您无法删除资源。














CLI摘要:

aws iot delete-authorizer \ --authorizer-name <value> \ [--cli-input-json <value>] \

449

AWS IoT 开发人员指南DeleteCACertificate



{ "authorizerName": "string"}


名称类型描述



模式：[w=,@-]+

要删除的授权方的名称。

输出:

无

DeleteCACertificate删除已注册的 CA 证书。

请求语法：

DELETE /cacertificate/caCertificateId

URI 请求参数：


certificateId CertificateId 是要删除的证书的 ID。(证书 ARN 的最后一部分包含证书 ID。)

错误:



HTTP 响应代码：400CertificateStateException

不允许执行该证书操作。


450


ThrottlingException











CLI摘要:

aws iot delete-ca-certificate \ --certificate-id <value> \ [--cli-input-json <value>] \ [--generate-cli-skeleton]




名称类型描述



模式：(0x)?[a-fA-F0-9]+

要删除的证书的 ID。(证书 ARN的最后一部分包含证书 ID。)

输出:

无

451

AWS IoT 开发人员指南DeleteCertificate

DeleteCertificate删除指定的证书。

如果证书上已经附加了策略或者其状态设置为 ACTIVE，则无法删除该证书。要删除证书，请先使用DetachPrincipalPolicy API 分离所有策略。接下来，使用 UpdateCertificate API 将证书设置为 INACTIVE 状态。

请求语法：

DELETE /certificates/certificateId?forceDelete=forceDelete

URI 请求参数：



forceDelete ForceDelete 否强制删除证书请求。

错误:

CertificateStateException


HTTP 响应代码：406DeleteConflictException











452







CLI摘要:

aws iot delete-certificate \ --certificate-id <value> \ [--force-delete | --no-force-delete] \ [--cli-input-json <value>] \ [--generate-cli-skeleton]


{ "certificateId": "string", "forceDelete": "boolean"}


名称类型描述



模式：(0x)?[a-fA-F0-9]+


forceDelete 布尔值强制删除证书请求。

输出:

无

DeleteOTAUpdate删除 OTA 更新。

请求语法：

DELETE /otaUpdates/otaUpdateId

453


URI 请求参数：


otaUpdateId OTAUpdateId 是要删除的 OTA 更新 ID。

错误:














CLI摘要:

aws iot delete-ota-update \ --ota-update-id <value> \ [--cli-input-json <value>] \ [--generate-cli-skeleton]


{ "otaUpdateId": "string"}

454

AWS IoT 开发人员指南DeletePolicy


名称类型描述



模式：[a-zA-Z0-9_-]+

要删除的 OTA 更新 ID。

输出:

无

DeletePolicy删除指定的策略。

如果策略具有非默认版本或者已经附加到了任何证书，则无法删除该策略。

要删除策略，请使用 DeletePolicyVersion API 删除策略的所有非默认版本；使用 DetachPrincipalPolicy API将策略从所有证书上分离；然后使用 DeletePolicy API 删除策略。

使用 DeletePolicy 删除策略后，将随之删除其默认版本。

请求语法：

DELETE /policies/policyName

URI 请求参数：


policyName PolicyName 是要删除的策略的名称。

错误:









455









CLI摘要:

aws iot delete-policy \ --policy-name <value> \ [--cli-input-json <value>] \ [--generate-cli-skeleton]


{ "policyName": "string"}


名称类型描述



模式：[w+=,.@-]+

要删除的策略的名称。

输出:

无

DeletePolicyVersion删除指定策略的指定版本。您无法使用此 API 删除策略的默认版本。要删除策略的默认版本，请使用DeletePolicy。要查明策略的哪个版本标记为默认版本，请使用 ListPolicyVersions。

请求语法：

456


DELETE /policies/policyName/version/policyVersionId

URI 请求参数：


policyName PolicyName 是策略的名称。

policyVersionId PolicyVersionId 是策略版本 ID。

错误:
















CLI摘要:

aws iot delete-policy-version \

457

AWS IoT 开发人员指南DeleteRegistrationCode

--policy-name <value> \ --policy-version-id <value> \ [--cli-input-json <value>] \ [--generate-cli-skeleton]


{ "policyName": "string", "policyVersionId": "string"}


名称类型描述



模式：[w+=,.@-]+

策略的名称。


模式：[0-9]+

策略版本 ID。

输出:

无

DeleteRegistrationCode删除 CA 证书注册代码。

请求语法：

DELETE /registrationcode

错误:

ThrottlingException







458







CLI摘要:

aws iot delete-registration-code \ [--cli-input-json <value>] \ [--generate-cli-skeleton]


{}

输出:

无

DeleteRoleAlias删除角色别名。

请求语法：

DELETE /role-aliases/roleAlias

URI 请求参数：


roleAlias RoleAlias 是要删除的角色别名。

错误:





459













CLI摘要:

aws iot delete-role-alias \ --role-alias <value> \ [--cli-input-json <value>] \ [--generate-cli-skeleton]


{ "roleAlias": "string"}


名称类型描述

roleAlias 字符串


模式：[w=,@-]+

要删除的角色别名。

输出:

460

AWS IoT 开发人员指南DeleteStream

无

DeleteStream删除流。

请求语法：

DELETE /streams/streamId

URI 请求参数：



错误:



HTTP 响应代码：404DeleteConflictException












461



CLI摘要:

aws iot delete-stream \ --stream-id <value> \ [--cli-input-json <value>] \ [--generate-cli-skeleton]


{ "streamId": "string"}


名称类型描述

streamId 字符串


模式：[a-zA-Z0-9_-]+

流 ID。

输出:

无

DeleteThing删除指定的事物。

请求语法：

DELETE /things/thingName?expectedVersion=expectedVersion

URI 请求参数：


thingName ThingName 是要删除的事物的名称。

expectedVersion OptionalVersion 否注册表中预期的事物记录的版本。如果注册表中记录的版本与请求中指定的预期版本不匹配，则使用VersionConflictException拒绝 DeleteThing 请求。

462


错误:



HTTP 响应代码：404VersionConflictException

传递到命令的事物的版本不同于使用 --version 参数指定的版本时，将引发异常错误。












CLI摘要:

aws iot delete-thing \ --thing-name <value> \ [--expected-version <value>] \ [--cli-input-json <value>] \ [--generate-cli-skeleton]


{ "thingName": "string", "expectedVersion": "long"

463

AWS IoT 开发人员指南DeleteThingGroup

}


名称类型描述

thingName 字符串


模式：[a-zA-Z0-9:_-]+

要删除的事物的名称。



注册表中预期的事物记录的版本。如果注册表中记录的版本与请求中指定的预期版本不匹配，则使用VersionConflictException拒绝 DeleteThing 请求。

输出:

无

DeleteThingGroup删除事物组。

请求语法：

DELETE /thing-groups/thingGroupName?expectedVersion=expectedVersion

URI 请求参数：


thingGroupName ThingGroupName 是要删除的事物组的名称。

expectedVersion OptionalVersion 否要删除的事物组的预期版本。

错误:






464


ThrottlingException





CLI摘要:

aws iot delete-thing-group \ --thing-group-name <value> \ [--expected-version <value>] \ [--cli-input-json <value>] \ [--generate-cli-skeleton]


{ "thingGroupName": "string", "expectedVersion": "long"}


名称类型描述



模式：[a-zA-Z0-9:_-]+

要删除的事物组的名称。



要删除的事物组的预期版本。

输出:

无

DeleteThingShadow删除指定事物的影子。

有关更多信息，请参阅《AWS IoT 开发人员指南》中的 DeleteThingShadow。

请求语法：

465

http://docs.aws.amazon.com/iot/latest/developerguide/API_DeleteThingShadow.html

AWS IoT 开发人员指南DeleteThingShadow

DELETE /things/thingName/shadow

URI 请求参数：



响应语法：


{ "payload": "blob"}



payload JsonDocument 是状态信息，采用 JSON格式。

错误:














466


MethodNotAllowedException

不支持指定的 HTTP 动词和 URI 组合。

HTTP 响应代码：405UnsupportedDocumentEncodingException

不支持的编码。


CLI摘要:

aws iot-data delete-thing-shadow \ --thing-name <value> \ [--cli-input-json <value>] \ [--generate-cli-skeleton]




名称类型描述

thingName 字符串


模式：[a-zA-Z0-9:_-]+

事物的名称。

输出:


cli 输出字段：

名称类型描述

payload blob 状态信息，采用 JSON 格式。

DeleteThingType删除指定的事物类型。如果有事物与事物类型关联，则无法删除该事物类型。要删除事物类型，请先通过调用 DeprecateThingType 将其标记为已弃用，然后调用 UpdateThing 移除任意关联的事物以更改任意关联事物上的事物类型，最后使用 DeleteThingType 删除事物类型。

467


请求语法：

DELETE /thing-types/thingTypeName

URI 请求参数：



错误:














CLI摘要:

aws iot delete-thing-type \ --thing-type-name <value> \ [--cli-input-json <value>] \ [--generate-cli-skeleton]

468

AWS IoT 开发人员指南DeleteTopicRule


{ "thingTypeName": "string"}


名称类型描述



模式：[a-zA-Z0-9:_-]+


输出:

无

DeleteTopicRule删除规则。

请求语法：

DELETE /rules/ruleName

URI 请求参数：


ruleName RuleName 否规则的名称。

错误:

InternalException







469





CLI摘要:

aws iot delete-topic-rule \ [--rule-name <value>] \ [--cli-input-json <value>] \ [--generate-cli-skeleton]


{ "ruleName": "string"}


名称类型描述

ruleName 字符串


模式：^[a-zA-Z0-9_]+$

规则的名称。

输出:

无

DeleteV2LoggingLevel删除日志记录级别。

请求语法：

DELETE /v2LoggingLevel?targetName=targetName&targetType=targetType

URI 请求参数：


targetType LogTargetType 是您要配置日志记录的资源的类型。必须是THING_Group。

470



targetName LogTargetName 是您要配置日志记录的资源的名称。

错误:

InternalException







CLI摘要:

aws iot delete-v2-logging-level \ --target-type <value> \ --target-name <value> \ [--cli-input-json <value>] \ [--generate-cli-skeleton]


{ "targetType": "string", "targetName": "string"}


名称类型描述

targetType 字符串

枚举：DEFAULT |THING_GROUP

java 类：iot.goldeneye.service.LogTargetType

您要配置日志记录的资源的类型。必须是 THING_Group。

targetName 字符串您要配置日志记录的资源的名称。

471

AWS IoT 开发人员指南DeprecateThingType

输出:

无

DeprecateThingType弃用事物类型。您不能将新事物与已弃用事物类型关联。

请求语法：

POST /thing-types/thingTypeName/deprecate Content-type: application/json

{ "undoDeprecate": "boolean"}

URI 请求参数：


thingTypeName ThingTypeName 是要弃用的事物类型的名称。



undoDeprecate UndoDeprecate 否是否取消弃用已弃用的事物类型。如果为true，则不再弃用该事物类型，您可以将其与事物关联。

错误:








472









CLI摘要:

aws iot deprecate-thing-type \ --thing-type-name <value> \ [--undo-deprecate | --no-undo-deprecate] \ [--cli-input-json <value>] \ [--generate-cli-skeleton]


{ "thingTypeName": "string", "undoDeprecate": "boolean"}


名称类型描述



模式：[a-zA-Z0-9:_-]+

要弃用的事物类型的名称。

undoDeprecate 布尔值是否取消弃用已弃用的事物类型。如果为 true，则不再弃用该事物类型，您可以将其与事物关联。

输出:

无

DescribeAuthorizer描述授权方。

473

AWS IoT 开发人员指南DescribeAuthorizer

请求语法：

GET /authorizer/authorizerName

URI 请求参数：


authorizerName AuthorizerName 是要描述的授权方的名称。

响应语法：


{ "authorizerDescription": { "authorizerName": "string", "authorizerArn": "string", "authorizerFunctionArn": "string", "tokenKeyName": "string", "tokenSigningPublicKeys": { "string": "string" }, "status": "string", "creationDate": "timestamp", "lastModifiedDate": "timestamp" }}



authorizerDescription AuthorizerDescription 否授权方的描述。

错误:








474









CLI摘要:

aws iot describe-authorizer \ --authorizer-name <value> \ [--cli-input-json <value>] \ [--generate-cli-skeleton]




名称类型描述



模式：[w=,@-]+

要描述的授权方的名称。

输出:

{ "authorizerDescription": { "authorizerName": "string", "authorizerArn": "string", "authorizerFunctionArn": "string", "tokenKeyName": "string", "tokenSigningPublicKeys": { "string": "string" }, "status": "string", "creationDate": "timestamp", "lastModifiedDate": "timestamp"

475

AWS IoT 开发人员指南DescribeCACertificate

}}

cli 输出字段：

名称类型描述

authorizerDescription AuthorizerDescription 授权方的描述。



模式：[w=,@-]+

授权方名称。


authorizerFunctionArn 字符串授权方的 Lambda 函数 ARN。



模式：[a-zA-Z0-9_-]+

用于从 HTTP 标头提取令牌的键。


键：KeyName

值：KeyValue

用于验证由自定义身份验证服务返回的令牌签名的公有密钥。

KeyName 字符串


模式：[a-zA-Z0-9:_-]+

KeyValue 字符串

最大长度：5120

status 字符串



授权方的状态。

creationDate timestamp 创建授权方的时间的 UNIX 时间戳。

lastModifiedDate timestamp 上次更新授权方的时间的 UNIX 时间戳。

DescribeCACertificate描述已注册的 CA 证书。

请求语法：

476

AWS IoT 开发人员指南DescribeCACertificate

GET /cacertificate/caCertificateId

URI 请求参数：


certificateId CertificateId 是 CA 证书标识符。

响应语法：


{ "certificateDescription": { "certificateArn": "string", "certificateId": "string", "status": "string", "certificatePem": "string", "ownedBy": "string", "creationDate": "timestamp", "autoRegistrationStatus": "string" }, "registrationConfig": { "templateBody": "string", "roleArn": "string" }}



certificateDescription CACertificateDescription 否 CA 证书描述。

registrationConfig RegistrationConfig 否有关注册配置的信息。

错误:








477









CLI摘要:

aws iot describe-ca-certificate \ --certificate-id <value> \ [--cli-input-json <value>] \ [--generate-cli-skeleton]




名称类型描述



模式：(0x)?[a-fA-F0-9]+

CA 证书标识符。

输出:

{ "certificateDescription": { "certificateArn": "string", "certificateId": "string", "status": "string", "certificatePem": "string", "ownedBy": "string", "creationDate": "timestamp", "autoRegistrationStatus": "string" }, "registrationConfig": {

478

AWS IoT 开发人员指南DescribeCertificate

"templateBody": "string", "roleArn": "string" }}

cli 输出字段：

名称类型描述

certificateDescription CACertificateDescription CA 证书描述。

certificateArn 字符串 CA 证书 ARN。



模式：(0x)?[a-fA-F0-9]+

CA 证书 ID。

status 字符串


java 类：iot.identity.service.CACertificateStatus

CA 证书的状态。



PEM 格式的 CA 证书数据。

ownedBy 字符串

模式：[0-9]{12}

CA 证书的所有者。

creationDate timestamp CA 证书的创建日期。

autoRegistrationStatus 字符串

枚举：ENABLE | DISABLE

java 类：iot.identity.service.AutoRegistrationStatus

是否为设备证书的自动注册配置 CA 证书。有效值为“ENABLE”和“DISABLE”

registrationConfig RegistrationConfig 有关注册配置的信息。

templateBody 字符串模板正文。

roleArn 字符串


角色的 ARN。

DescribeCertificate获取有关指定证书的信息。

请求语法：

GET /certificates/certificateId

479

AWS IoT 开发人员指南DescribeCertificate

URI 请求参数：



响应语法：


{ "certificateDescription": { "certificateArn": "string", "certificateId": "string", "caCertificateId": "string", "status": "string", "certificatePem": "string", "ownedBy": "string", "previousOwnedBy": "string", "creationDate": "timestamp", "lastModifiedDate": "timestamp", "transferData": { "transferMessage": "string", "rejectReason": "string", "transferDate": "timestamp", "acceptDate": "timestamp", "rejectDate": "timestamp" } }}



certificateDescription CertificateDescription 否证书的描述。

错误:








480









CLI摘要:

aws iot describe-certificate \ --certificate-id <value> \ [--cli-input-json <value>] \ [--generate-cli-skeleton]




名称类型描述



模式：(0x)?[a-fA-F0-9]+


输出:

{ "certificateDescription": { "certificateArn": "string", "certificateId": "string", "caCertificateId": "string", "status": "string", "certificatePem": "string", "ownedBy": "string", "previousOwnedBy": "string", "creationDate": "timestamp", "lastModifiedDate": "timestamp", "transferData": { "transferMessage": "string", "rejectReason": "string", "transferDate": "timestamp",

481


"acceptDate": "timestamp", "rejectDate": "timestamp" } }}

cli 输出字段：

名称类型描述

certificateDescription CertificateDescription 证书的描述。




模式：(0x)?[a-fA-F0-9]+

证书的 ID。

caCertificateId 字符串


模式：(0x)?[a-fA-F0-9]+

签名此证书所用 CA 证书的证书ID。

status 字符串

枚举：ACTIVE |INACTIVE | REVOKED |PENDING_TRANSFER |REGISTER_INACTIVE |PENDING_ACTIVATION

java 类：iot.identity.service.CertificateStatus

证书的状态。




ownedBy 字符串

模式：[0-9]{12}

拥有证书的 AWS 账户的 ID。

previousOwnedBy 字符串

模式：[0-9]{12}

证书以前拥有者的 AWS 账户ID。

creationDate timestamp 证书的创建日期和时间。

lastModifiedDate timestamp 上次修改证书的日期和时间。

transferData TransferData 传输数据。

transferMessage 字符串

最大长度：128

传输消息。

rejectReason 字符串

最大长度：128

拒绝传输的原因。

482

AWS IoT 开发人员指南DescribeDefaultAuthorizer

名称类型描述

transferDate timestamp 传输发生的日期。

acceptDate timestamp 接受传输的日期。

rejectDate timestamp 拒绝传输的日期。

DescribeDefaultAuthorizer描述默认授权方。

请求语法：

GET /default-authorizer

响应语法：





authorizerDescription AuthorizerDescription 否默认授权方的描述。

错误:







483









CLI摘要:

aws iot describe-default-authorizer \ [--cli-input-json <value>] \ [--generate-cli-skeleton]


{}

输出:


cli 输出字段：

名称类型描述

authorizerDescription AuthorizerDescription 默认授权方的描述。



模式：[w=,@-]+

授权方名称。

484

AWS IoT 开发人员指南DescribeEndpoint

名称类型描述


authorizerFunctionArn 字符串授权方的 Lambda 函数 ARN。



模式：[a-zA-Z0-9_-]+



键：KeyName

值：KeyValue

用于验证由自定义身份验证服务返回的令牌签名的公有密钥。

KeyName 字符串


模式：[a-zA-Z0-9:_-]+

KeyValue 字符串

最大长度：5120

status 字符串



授权方的状态。

creationDate timestamp 创建授权方的时间的 UNIX 时间戳。

lastModifiedDate timestamp 上次更新授权方的时间的 UNIX 时间戳。

DescribeEndpoint返回特定于发出调用的 AWS 账户的唯一终端节点。

请求语法：

GET /endpoint?endpointType=endpointType

URI 请求参数：


endpointType EndpointType 否终端节点类型。

响应语法：

485



{ "endpointAddress": "string"}



endpointAddress EndpointAddress 否终端节点。终端节点的格式如下：identifier.iot.region.amazonaws.com。

错误:










CLI摘要:

aws iot describe-endpoint \ [--endpoint-type <value>] \ [--cli-input-json <value>] \ [--generate-cli-skeleton]


{ "endpointType": "string"}

486

AWS IoT 开发人员指南DescribeEventConfigurations


名称类型描述

endpointType 字符串终端节点类型。

输出:

{ "endpointAddress": "string"}

cli 输出字段：

名称类型描述

endpointAddress 字符串终端节点。终端节点的格式如下：identifier.iot.region.amazonaws.com。

DescribeEventConfigurations描述事件配置。

请求语法：

GET /event-configurations

响应语法：


{ "eventConfigurations": { "string": { "Enabled": "boolean" } }, "creationDate": "timestamp", "lastModifiedDate": "timestamp"}



eventConfigurations EventConfigurations 否事件配置。

creationDate CreationDate 否事件配置的创建日期。

lastModifiedDate LastModifiedDate 否上次修改事件配置的日期。

错误:

487







CLI摘要:

aws iot describe-event-configurations \ [--cli-input-json <value>] \ [--generate-cli-skeleton]


{}

输出:

{ "eventConfigurations": { "string": { "Enabled": "boolean" } }, "creationDate": "timestamp", "lastModifiedDate": "timestamp"}

cli 输出字段：

名称类型描述

eventConfigurations map

键：EventType

值：Configuration

事件配置。

EventType 字符串

枚举：THING | THING_GROUP| THING_TYPE |THING_GROUP_MEMBERSHIP| THING_GROUP_HIERARCHY| THING_TYPE_ASSOCIATION |JOB | JOB_EXECUTION

java 类：com.amazonaws.iot.common.types.enums.EventType

488

AWS IoT 开发人员指南DescribeIndex

名称类型描述

配置配置

启用布尔值为 True 时启用配置。

creationDate timestamp 事件配置的创建日期。

lastModifiedDate timestamp 上次修改事件配置的日期。

DescribeIndex描述搜索索引。

请求语法：

GET /indices/indexName

URI 请求参数：


indexName IndexName 是索引名称。

响应语法：


{ "indexName": "string", "indexStatus": "string", "schema": "string"}



indexName IndexName 否索引名称。

indexStatus IndexStatus 否索引状态。

schema IndexSchema 否包含一个特定于所执行索引类型的值。有效值为：

1. REGISTRY - 您的事物索引将只包含注册表数据。

2. REGISTRY_AND_SHADOW- 您的事物索引将包含注册表数据和影子数据。

489


错误:














CLI摘要:

aws iot describe-index \ --index-name <value> \ [--cli-input-json <value>] \ [--generate-cli-skeleton]


{ "indexName": "string"}


名称类型描述

indexName 字符串


模式：[a-zA-Z0-9:_-]+

索引名称。

490

AWS IoT 开发人员指南DescribeJob

输出:

{ "indexName": "string", "indexStatus": "string", "schema": "string"}

cli 输出字段：

名称类型描述

indexName 字符串


模式：[a-zA-Z0-9:_-]+

索引名称。

indexStatus 字符串

枚举：ACTIVE | BUILDING |REBUILDING

java 类：com.amazonaws.iot.indexing.IndexStatus

索引状态。

schema 字符串包含一个特定于所执行索引类型的值。有效值为：

1. REGISTRY - 您的事物索引将只包含注册表数据。

2. REGISTRY_AND_SHADOW -您的事物索引将包含注册表数据和影子数据。

DescribeJob描述任务。

请求语法：

GET /jobs/jobId

URI 请求参数：



响应语法：

491

AWS IoT 开发人员指南DescribeJob


{ "documentSource": "string", "job": { "jobArn": "string", "jobId": "string", "targetSelection": "string", "status": "string", "comment": "string", "targets": [ "string" ], "description": "string", "presignedUrlConfig": { "roleArn": "string", "expiresInSec": "long" }, "jobExecutionsRolloutConfig": { "maximumPerMinute": "integer" }, "createdAt": "timestamp", "lastUpdatedAt": "timestamp", "completedAt": "timestamp", "jobProcessDetails": { "processingTargets": [ "string" ], "numberOfCanceledThings": "integer", "numberOfSucceededThings": "integer", "numberOfFailedThings": "integer", "numberOfRejectedThings": "integer", "numberOfQueuedThings": "integer", "numberOfInProgressThings": "integer", "numberOfRemovedThings": "integer" }, "documentParameters": { "string": "string" } }}



documentSource JobDocumentSource 否指向任务文档的 S3 链接。

任务任务否该任务的相关信息。

错误:





492







CLI摘要:

aws iot describe-job \ --job-id <value> \ [--cli-input-json <value>] \ [--generate-cli-skeleton]




名称类型描述

jobId 字符串


模式：[a-zA-Z0-9_-]+


输出:

{ "documentSource": "string", "job": { "jobArn": "string", "jobId": "string", "targetSelection": "string", "status": "string", "comment": "string", "targets": [ "string" ], "description": "string", "presignedUrlConfig": { "roleArn": "string", "expiresInSec": "long" },

493


"jobExecutionsRolloutConfig": { "maximumPerMinute": "integer" }, "createdAt": "timestamp", "lastUpdatedAt": "timestamp", "completedAt": "timestamp", "jobProcessDetails": { "processingTargets": [ "string" ], "numberOfCanceledThings": "integer", "numberOfSucceededThings": "integer", "numberOfFailedThings": "integer", "numberOfRejectedThings": "integer", "numberOfQueuedThings": "integer", "numberOfInProgressThings": "integer", "numberOfRemovedThings": "integer" }, "documentParameters": { "string": "string" } }}

cli 输出字段：

名称类型描述




任务任务该任务的相关信息。

jobArn 字符串标识任务的 ARN，格式为“arn:aws:iot:region:account:job/jobId”。

jobId 字符串


模式：[a-zA-Z0-9_-]+





指定任务将继续运行(CONTINUOUS)，还是在指定作为目标的所有事物完成任务之后完成 (SNAPSHOT)。如果继续运行，则在检测到目标中出现更改时，任务也会在事物上运行。例如，当代表设备的某个事物添加到目标组时，会在该设备上运行任务，即使是组中原有的全部事物已经完成了任务。

status 字符串



任务的状态，为IN_PROGRESS、CANCELED 或COMPLETED 之一。

494


名称类型描述

comment 字符串

最大长度：2028

模式：[^\\p{C}]+

如果任务已更新，介绍更新原因。

targets 列表

成员：TargetArn

任务应发送到的 IoT 事物和事物组的列表。

TargetArn 字符串


最大长度：2028

模式：[^\\p{C}]+


presignedUrlConfig PresignedUrlConfig 预签名 S3 URL 的配置。

roleArn 字符串


IAM 角色的 ARN，该角色授予权限以从存储任务数据/更新的 S3存储桶下载文件。该角色还必须授予 IoT 下载文件的权限。

expiresInSec long












jobProcessDetails JobProcessDetails 任务流程的详细信息。

processingTargets 列表

成员：ProcessingTargetName


执行任务的设备。

ProcessingTargetName 字符串

495

AWS IoT 开发人员指南DescribeJobExecution

名称类型描述

numberOfCanceledThings integer


取消了任务的事物数。

numberOfSucceededThings integer


成功完成任务的事物数。

numberOfFailedThings integer


任务执行失败的事物数。

numberOfRejectedThings integer


拒绝了任务的事物数。

numberOfQueuedThings integer


等待任务执行的事物数。

numberOfInProgressThings integer


当前正在执行任务的事物数。

numberOfRemovedThings integer


因其已从作为任务目标的组中被删除或移除而不再计划执行的事物的数量。


键：ParameterKey


为任务文档指定的参数。



模式：[a-zA-Z0-9:_-]+



模式：[^\\p{C}]+

DescribeJobExecution描述任务执行。

请求语法：

GET /things/thingName/jobs/jobId?executionNumber=executionNumber

496


URI 请求参数：



thingName ThingName 是正在运行任务执行的事物的名称。

executionNumber ExecutionNumber 否一个由从“0”到“9”的数字组成的字符串，用于指定特定设备上的特定任务执行。

响应语法：


{ "execution": { "jobId": "string", "status": "string", "statusDetails": { "detailsMap": { "string": "string" } }, "thingArn": "string", "queuedAt": "timestamp", "startedAt": "timestamp", "lastUpdatedAt": "timestamp", "executionNumber": "long" }}



execution JobExecution 否任务执行的相关信息。

错误:







497





CLI摘要:

aws iot describe-job-execution \ --job-id <value> \ --thing-name <value> \ [--execution-number <value>] \ [--cli-input-json <value>] \ [--generate-cli-skeleton]


{ "jobId": "string", "thingName": "string", "executionNumber": "long"}


名称类型描述

jobId 字符串


模式：[a-zA-Z0-9_-]+


thingName 字符串


模式：[a-zA-Z0-9:_-]+

正在运行任务执行的事物的名称。



一个由从“0”到“9”的数字组成的字符串，用于指定特定设备上的特定任务执行。

输出:

{ "execution": { "jobId": "string", "status": "string", "statusDetails": { "detailsMap": { "string": "string" } }, "thingArn": "string",

498


"queuedAt": "timestamp", "startedAt": "timestamp", "lastUpdatedAt": "timestamp", "executionNumber": "long" }}

cli 输出字段：

名称类型描述

execution JobExecution 任务执行的相关信息。

jobId 字符串


模式：[a-zA-Z0-9_-]+

您在创建任务时向其分配的唯一标识符。

status 字符串



任务执行的状态(IN_PROGRESS、QUEUED、FAILED、SUCCESS、CANCELED或 REJECTED)。

statusDetails JobExecutionStatusDetails 描述任务执行状态的名称/值对的集合。

detailsMap map

键：DetailsKey

值：DetailsValue

任务执行状态。



模式：[a-zA-Z0-9:_-]+



模式：[^\\p{C}]*+





499


名称类型描述



一个由从“0”到“9”的数字组成的字符串，用于标识此特定设备上的该特定任务执行。它可在返回或更新任务执行信息的命令中使用。

DescribeJobExecution获取任务执行的详细信息。

请求语法：

GET /things/thingName/jobs/jobId?executionNumber=executionNumber&includeJobDocument=includeJobDocument

URI 请求参数：


jobId DescribeJobExecutionJobId是创建此任务时向其分配的唯一标识符。

thingName ThingName 是与正在运行任务执行的设备关联的事物名称。

includeJobDocument IncludeJobDocument 否可选。设置为 true 时，响应将包含任务文档。默认为 false。

executionNumber ExecutionNumber 否可选。标识特定设备上的特定任务执行的数字。如果未指定，则返回最新的任务执行。

响应语法：


{ "execution": { "jobId": "string", "thingName": "string", "status": "string", "statusDetails": { "string": "string" }, "queuedAt": "long", "startedAt": "long", "lastUpdatedAt": "long", "versionNumber": "long", "executionNumber": "long", "jobDocument": "string" }

500


}



execution JobExecution 否包含有关任务执行的数据。

错误:









HTTP 响应代码：503CertificateValidationException

证书无效。

HTTP 响应代码：400TerminalStateException

任务处于最终状态。


CLI摘要:

aws iot-jobs-data describe-job-execution \ --job-id <value> \ --thing-name <value> \ [--include-job-document | --no-include-job-document] \ [--execution-number <value>] \ [--cli-input-json <value>] \ [--generate-cli-skeleton]


{

501


"jobId": "string", "thingName": "string", "includeJobDocument": "boolean", "executionNumber": "long"}


名称类型描述

jobId 字符串

模式：[a-zA-Z0-9_-]+|^$next


thingName 字符串


模式：[a-zA-Z0-9:_-]+

与正在运行任务执行的设备关联的事物名称。







输出:


cli 输出字段：

名称类型描述

execution JobExecution 包含有关任务执行的数据。

jobId 字符串


模式：[a-zA-Z0-9_-]+


thingName 字符串正在执行任务的事物的名称。

502

AWS IoT 开发人员指南DescribeRoleAlias


模式：[a-zA-Z0-9:_-]+

status 字符串




statusDetails map

键：DetailsKey

值：DetailsValue




模式：[a-zA-Z0-9:_-]+



模式：[^\\p{C}]*+


startedAt long











DescribeRoleAlias描述角色别名。

请求语法：

503

AWS IoT 开发人员指南DescribeRoleAlias

GET /role-aliases/roleAlias

URI 请求参数：


roleAlias RoleAlias 是要描述的角色别名。

响应语法：


{ "roleAliasDescription": { "roleAlias": "string", "roleArn": "string", "owner": "string", "credentialDurationSeconds": "integer", "creationDate": "timestamp", "lastModifiedDate": "timestamp" }}



roleAliasDescription RoleAliasDescription 否角色别名描述。

错误:












504





CLI摘要:

aws iot describe-role-alias \ --role-alias <value> \ [--cli-input-json <value>] \ [--generate-cli-skeleton]


{ "roleAlias": "string"}


名称类型描述

roleAlias 字符串


模式：[w=,@-]+

要描述的角色别名。

输出:

{ "roleAliasDescription": { "roleAlias": "string", "roleArn": "string", "owner": "string", "credentialDurationSeconds": "integer", "creationDate": "timestamp", "lastModifiedDate": "timestamp" }}

cli 输出字段：

名称类型描述

roleAliasDescription RoleAliasDescription 角色别名描述。

roleAlias 字符串


模式：[w=,@-]+

角色别名。

roleArn 字符串角色 ARN。

505

AWS IoT 开发人员指南DescribeStream


owner 字符串

模式：[0-9]{12}

角色别名所有者。



范围 – 最大值：3600，最小值：900

凭证有效的秒数。

creationDate timestamp 创建角色别名的时间的 UNIX 时间戳。

lastModifiedDate timestamp 上次修改角色别名的时间的 UNIX时间戳。

DescribeStream获取有关流的信息。

请求语法：

GET /streams/streamId

URI 请求参数：



响应语法：


{ "streamInfo": { "streamId": "string", "streamArn": "string", "streamVersion": "integer", "description": "string", "files": [ { "fileId": "integer", "s3Location": { "bucket": "string", "key": "string", "version": "string" } } ], "createdAt": "timestamp", "lastUpdatedAt": "timestamp", "roleArn": "string"

506


}}



streamInfo StreamInfo 否有关流的信息。

错误:














CLI摘要:

aws iot describe-stream \ --stream-id <value> \ [--cli-input-json <value>] \ [--generate-cli-skeleton]


{ "streamId": "string"}

507



名称类型描述

streamId 字符串


模式：[a-zA-Z0-9_-]+

流 ID。

输出:

{ "streamInfo": { "streamId": "string", "streamArn": "string", "streamVersion": "integer", "description": "string", "files": [ { "fileId": "integer", "s3Location": { "bucket": "string", "key": "string", "version": "string" } } ], "createdAt": "timestamp", "lastUpdatedAt": "timestamp", "roleArn": "string" }}

cli 输出字段：

名称类型描述

streamInfo StreamInfo 有关流的信息。

streamId 字符串


模式：[a-zA-Z0-9_-]+

流 ID。





流版本。


最大长度：2028

模式：[^\\p{C}]+

流的描述。

508

AWS IoT 开发人员指南DescribeThing

名称类型描述

files 列表

成员：StreamFile

要流式处理的文件。


fileId integer



文件 ID。


bucket 字符串

最小长度：1


key 字符串

最小长度：1

S3 存储桶中要流式处理的文件的名称。


createdAt timestamp 创建流的日期。

lastUpdatedAt timestamp 上次更新流的日期。

roleArn 字符串


AWS IoT 代入以访问您的 S3 文件的 IAM 角色。

DescribeThing获取有关指定事物的信息。

请求语法：

GET /things/thingName

URI 请求参数：



响应语法：


{ "defaultClientId": "string", "thingName": "string", "thingId": "string", "thingArn": "string",

509

AWS IoT 开发人员指南DescribeThing

"thingTypeName": "string", "attributes": { "string": "string" }, "version": "long"}



defaultClientId ClientId 否默认客户端 ID。

thingName ThingName 否事物的名称。

thingId 事物 ID 否要描述的事物的 ID。

thingArn ThingArn 否要描述的事物的 ARN。

thingTypeName ThingTypeName 否事物类型名称。

个属性属性否事物属性。

version 版本否注册表中事物记录的当前版本。

Note

为避免意外更改注册表中的信息，您可以在UpdateThing和DeleteThing调用的expectedVersion参数中传递版本信息。

错误:









510







CLI摘要:

aws iot describe-thing \ --thing-name <value> \ [--cli-input-json <value>] \ [--generate-cli-skeleton]




名称类型描述

thingName 字符串


模式：[a-zA-Z0-9:_-]+

事物的名称。

输出:

{ "defaultClientId": "string", "thingName": "string", "thingId": "string", "thingArn": "string", "thingTypeName": "string", "attributes": { "string": "string" }, "version": "long"}

cli 输出字段：

名称类型描述

defaultClientId 字符串默认客户端 ID。

thingName 字符串事物的名称。

511

AWS IoT 开发人员指南DescribeThingGroup


模式：[a-zA-Z0-9:_-]+

thingId 字符串要描述的事物的 ID。

thingArn 字符串要描述的事物的 ARN。



模式：[a-zA-Z0-9:_-]+

事物类型名称。

个属性 map

键：AttributeName


事物属性。


最大长度：128

模式：[a-zA-Z0-9_.,@/:#-]+


最大长度：800

模式：[a-zA-Z0-9_.,@/:#-]*

version long 注册表中事物记录的当前版本。

Note

为避免意外更改注册表中的信息，您可以在 UpdateThing 和DeleteThing 调用的expectedVersion 参数中传递版本信息。

DescribeThingGroup描述事物组。

请求语法：

GET /thing-groups/thingGroupName

URI 请求参数：


thingGroupName ThingGroupName 是事物组的名称。

512

AWS IoT 开发人员指南DescribeThingGroup

响应语法：


{ "thingGroupName": "string", "thingGroupId": "string", "thingGroupArn": "string", "version": "long", "thingGroupProperties": { "thingGroupDescription": "string", "attributePayload": { "attributes": { "string": "string" }, "merge": "boolean" } }, "thingGroupMetadata": { "parentGroupName": "string", "rootToParentThingGroups": [ { "groupName": "string", "groupArn": "string" } ], "creationDate": "timestamp" }}



thingGroupName ThingGroupName 否事物组的名称。

thingGroupId ThingGroupId 否事物组 ID。

thingGroupArn ThingGroupArn 否事物组 ARN。

version 版本否事物组的版本。

thingGroupProperties ThingGroupProperties 否事物组属性。

thingGroupMetadata ThingGroupMetadata 否事物组元数据。

错误:






513







CLI摘要:

aws iot describe-thing-group \ --thing-group-name <value> \ [--cli-input-json <value>] \ [--generate-cli-skeleton]


{ "thingGroupName": "string"}


名称类型描述



模式：[a-zA-Z0-9:_-]+

事物组的名称。

输出:

{ "thingGroupName": "string", "thingGroupId": "string", "thingGroupArn": "string", "version": "long", "thingGroupProperties": { "thingGroupDescription": "string", "attributePayload": { "attributes": { "string": "string" }, "merge": "boolean" } }, "thingGroupMetadata": { "parentGroupName": "string", "rootToParentThingGroups": [ { "groupName": "string", "groupArn": "string" }

514


], "creationDate": "timestamp" }}

cli 输出字段：

名称类型描述



模式：[a-zA-Z0-9:_-]+

事物组的名称。



模式：[a-zA-Z0-9-]+

事物组 ID。

thingGroupArn 字符串事物组 ARN。

version long 事物组的版本。



最大长度：2028




个属性 map

键：AttributeName





最大长度：128

模式：[a-zA-Z0-9_.,@/:#-]+


最大长度：800

模式：[a-zA-Z0-9_.,@/:#-]*



515

AWS IoT 开发人员指南DescribeThingRegistrationTask

名称类型描述

Note


thingGroupMetadata ThingGroupMetadata 事物组元数据。

parentGroupName 字符串


模式：[a-zA-Z0-9:_-]+

父事物组的名称。

rootToParentThingGroups 列表

成员：GroupNameAndArn


根父事物组。

GroupNameAndArn GroupNameAndArn

groupName 字符串


模式：[a-zA-Z0-9:_-]+

组名称。

groupArn 字符串组 ARN。

creationDate timestamp 创建事物组的时间的 UNIX 时间戳。

DescribeThingRegistrationTask描述批量事物预配置任务。

请求语法：

GET /thing-registration-tasks/taskId

URI 请求参数：


taskId TaskId 是任务 ID。

响应语法：


{ "taskId": "string", "creationDate": "timestamp", "lastModifiedDate": "timestamp", "templateBody": "string",

516

AWS IoT 开发人员指南DescribeThingRegistrationTask

"inputFileBucket": "string", "inputFileKey": "string", "roleArn": "string", "status": "string", "message": "string", "successCount": "integer", "failureCount": "integer", "percentageProgress": "integer"}



taskId TaskId 否任务 ID。

creationDate CreationDate 否任务创建日期。

lastModifiedDate LastModifiedDate 否上次修改任务的日期。

templateBody TemplateBody 否任务的模板。

inputFileBucket RegistryS3BucketName 否包含输入文件的 S3 存储桶。

inputFileKey RegistryS3KeyName 否输入文件密钥。

roleArn RoleArn 否授予对输入文件存储桶的访问权限的角色ARN。

status Status 否批量事物预配置任务的状态。

message ErrorMessage 否消息。

successCount Count 否成功预配置的事物数量。

failureCount Count 否预配置失败的事物数量。

percentageProgress 百分比否以百分比表示的批量预配置任务的进度。

错误:







517







CLI摘要:

aws iot describe-thing-registration-task \ --task-id <value> \ [--cli-input-json <value>] \ [--generate-cli-skeleton]


{ "taskId": "string"}


名称类型描述

taskId 字符串

最大长度：40

任务 ID。

输出:

{ "taskId": "string", "creationDate": "timestamp", "lastModifiedDate": "timestamp", "templateBody": "string", "inputFileBucket": "string", "inputFileKey": "string", "roleArn": "string", "status": "string", "message": "string", "successCount": "integer", "failureCount": "integer", "percentageProgress": "integer"}

cli 输出字段：

名称类型描述

taskId 字符串任务 ID。

518

AWS IoT 开发人员指南DescribeThingType

名称类型描述最大长度：40

creationDate timestamp 任务创建日期。

lastModifiedDate timestamp 上次修改任务的日期。

templateBody 字符串任务的模板。

inputFileBucket 字符串


模式：[a-zA-Z0-9._-]+

包含输入文件的 S3 存储桶。

inputFileKey 字符串


模式：[a-zA-Z0-9!_.*'()-/]+

输入文件密钥。

roleArn 字符串


授予对输入文件存储桶的访问权限的角色 ARN。

status 字符串

枚举：InProgress | Completed |Failed | Cancelled | Cancelling

java 类：com.amazonaws.iot.common.types.enums.Status

批量事物预配置任务的状态。

message 字符串

最大长度：2048

消息。

successCount integer 成功预配置的事物数量。

failureCount integer 预配置失败的事物数量。

percentageProgress integer


以百分比表示的批量预配置任务的进度。

DescribeThingType获取有关指定事物类型的信息。

请求语法：

GET /thing-types/thingTypeName

URI 请求参数：



519

AWS IoT 开发人员指南DescribeThingType

响应语法：


{ "thingTypeName": "string", "thingTypeId": "string", "thingTypeArn": "string", "thingTypeProperties": { "thingTypeDescription": "string", "searchableAttributes": [ "string" ] }, "thingTypeMetadata": { "deprecated": "boolean", "deprecationDate": "timestamp", "creationDate": "timestamp" }}




thingTypeId ThingTypeId 否事物类型 ID。

thingTypeArn ThingTypeArn 否事物类型 ARN。

thingTypeProperties ThingTypeProperties 否 ThingTypeProperties 包含有关事物类型的信息(包括描述)，以及可搜索事物属性名称的列表。

thingTypeMetadata ThingTypeMetadata 否 ThingTypeMetadata 包含有关事物类型的其他信息，包括：创建日期和时间、指示该事物类型是否已弃用的值以及弃用的日期和时间。

错误:







520









CLI摘要:

aws iot describe-thing-type \ --thing-type-name <value> \ [--cli-input-json <value>] \ [--generate-cli-skeleton]


{ "thingTypeName": "string"}


名称类型描述



模式：[a-zA-Z0-9:_-]+


输出:

{ "thingTypeName": "string", "thingTypeId": "string", "thingTypeArn": "string", "thingTypeProperties": { "thingTypeDescription": "string", "searchableAttributes": [ "string" ] }, "thingTypeMetadata": { "deprecated": "boolean", "deprecationDate": "timestamp",

521

AWS IoT 开发人员指南DetachPolicy

"creationDate": "timestamp" }}

cli 输出字段：

名称类型描述



模式：[a-zA-Z0-9:_-]+


thingTypeId 字符串事物类型 ID。

thingTypeArn 字符串事物类型 ARN。

thingTypeProperties ThingTypeProperties ThingTypeProperties 包含有关事物类型的信息 (包括描述)，以及可搜索事物属性名称的列表。


最大长度：2028








最大长度：128

模式：[a-zA-Z0-9_.,@/:#-]+

thingTypeMetadata ThingTypeMetadata ThingTypeMetadata 包含有关事物类型的其他信息，包括：创建日期和时间、指示该事物类型是否已弃用的值以及弃用的日期和时间。

已弃用布尔值事物类型是否已弃用。如果为true，则新事物无法与此类型关联。

deprecationDate timestamp 弃用事物类型的日期和时间。

creationDate timestamp 创建事物类型的日期和时间。

DetachPolicy从指定目标分离策略。

请求语法：

522


POST /target-policies/policyName Content-type: application/json

{ "target": "string"}

URI 请求参数：


policyName PolicyName 是要分离的策略。



target PolicyTarget 是将从中分离策略的目标。

错误:














CLI摘要:

523

AWS IoT 开发人员指南DetachPrincipalPolicy

aws iot detach-policy \ --policy-name <value> \ --target <value> \ [--cli-input-json <value>] \ [--generate-cli-skeleton]


{ "policyName": "string", "target": "string"}


名称类型描述



模式：[w+=,.@-]+

要分离的策略。

target 字符串将从中分离策略的目标。

输出:

无

DetachPrincipalPolicy从指定的证书中删除指定的策略。

注意：此 API 已弃用。请改用 DetachPolicy。

请求语法：

DELETE /principal-policies/policyName x-amzn-iot-principal: principal

URI 请求参数：


policyName PolicyName 是要分离的策略的名称。

principal 委托人是委托人。

如果委托人是证书，请指定证书 ARN。如果委托人是 Amazon Cognito身份，请指定身份 ID。

错误:

524















CLI摘要:

aws iot detach-principal-policy \ --policy-name <value> \ --principal <value> \ [--cli-input-json <value>] \ [--generate-cli-skeleton]


{ "policyName": "string", "principal": "string"}


名称类型描述



模式：[w+=,.@-]+

要分离的策略的名称。

525

AWS IoT 开发人员指南DetachThingPrincipal

名称类型描述

principal 字符串委托人。

如果委托人是证书，请指定证书ARN。如果委托人是 AmazonCognito 身份，请指定身份 ID。

输出:

无

DetachThingPrincipal从指定的事物分离指定的委托人。

请求语法：

DELETE /things/thingName/principals x-amzn-principal: principal

URI 请求参数：



principal 委托人是如果委托人是证书，此值必须为证书的 ARN。如果委托人是 AmazonCognito 身份，此值必须是 Amazon Cognito 身份的 ID。

错误:









526







CLI摘要:

aws iot detach-thing-principal \ --thing-name <value> \ --principal <value> \ [--cli-input-json <value>] \ [--generate-cli-skeleton]


{ "thingName": "string", "principal": "string"}


名称类型描述

thingName 字符串


模式：[a-zA-Z0-9:_-]+

事物的名称。

principal 字符串如果委托人是证书，此值必须为证书的 ARN。如果委托人是Amazon Cognito 身份，此值必须是 Amazon Cognito 身份的 ID。

输出:

无

DisableTopicRule禁用规则。

请求语法：

527


POST /rules/ruleName/disable

URI 请求参数：


ruleName RuleName 是要禁用的规则的名称。

错误:

InternalException









CLI摘要:

aws iot disable-topic-rule \ --rule-name <value> \ [--cli-input-json <value>] \ [--generate-cli-skeleton]




名称类型描述

ruleName 字符串


模式：^[a-zA-Z0-9_]+$

要禁用的规则的名称。

528

AWS IoT 开发人员指南EnableTopicRule

输出:

无

EnableTopicRule启用规则。

请求语法：

POST /rules/ruleName/enable

URI 请求参数：


ruleName RuleName 是要启用的主题规则的名称。

错误:

InternalException









CLI摘要:

aws iot enable-topic-rule \ --rule-name <value> \ [--cli-input-json <value>] \ [--generate-cli-skeleton]


529

AWS IoT 开发人员指南GetEffectivePolicies



名称类型描述

ruleName 字符串


模式：^[a-zA-Z0-9_]+$

要启用的主题规则的名称。

输出:

无

GetEffectivePolicies获取生效策略。

请求语法：

POST /effective-policies?thingName=thingName Content-type: application/json

{ "principal": "string", "cognitoIdentityPoolId": "string"}

URI 请求参数：


thingName ThingName 否事物名称。



principal 委托人否委托人。

cognitoIdentityPoolId CognitoIdentityPoolId 否 Cognito 身份池 ID。

响应语法：


{ "effectivePolicies": [ {

530


"policyName": "string", "policyArn": "string", "policyDocument": "string" } ]}



effectivePolicies EffectivePolicies 否生效策略。

错误:
















CLI摘要:

aws iot get-effective-policies \

531


[--principal <value>] \ [--cognito-identity-pool-id <value>] \ [--thing-name <value>] \ [--cli-input-json <value>] \ [--generate-cli-skeleton]


{ "principal": "string", "cognitoIdentityPoolId": "string", "thingName": "string"}


名称类型描述


cognitoIdentityPoolId 字符串 Cognito 身份池 ID。

thingName 字符串


模式：[a-zA-Z0-9:_-]+

事物名称。

输出:

{ "effectivePolicies": [ { "policyName": "string", "policyArn": "string", "policyDocument": "string" } ]}

cli 输出字段：

名称类型描述

effectivePolicies 列表

成员：EffectivePolicy


生效策略。

EffectivePolicy EffectivePolicy



模式：[w+=,.@-]+

策略名称。


532

AWS IoT 开发人员指南GetIndexingConfiguration

名称类型描述

policyDocument 字符串 IAM 策略文档。

GetIndexingConfiguration获取搜索配置。

请求语法：

GET /indexing/config

响应语法：


{ "thingIndexingConfiguration": { "thingIndexingMode": "string" }}



thingIndexingConfigurationThingIndexingConfiguration否事物索引配置。

错误:











533



CLI摘要:

aws iot get-indexing-configuration \ [--cli-input-json <value>] \ [--generate-cli-skeleton]


{}

输出:


cli 输出字段：

名称类型描述

thingIndexingConfiguration ThingIndexingConfiguration 事物索引配置。

thingIndexingMode 字符串

枚举：OFF | REGISTRY |REGISTRY_AND_SHADOW

java 类：com.amazonaws.iot.indexing.ThingIndexingMode

事物索引模式。有效值为：

• REGISTRY - 您的事物索引将只包含注册表数据。

• REGISTRY_AND_SHADOW -您的事物索引将包含注册表数据和影子数据。

• OFF - 事物索引已禁用。

GetJobDocument获取任务文档。

请求语法：

GET /jobs/jobId/job-document

URI 请求参数：



534


响应语法：





文档 JobDocument 否任务文档内容。

错误:










CLI摘要:

aws iot get-job-document \ --job-id <value> \ [--cli-input-json <value>] \ [--generate-cli-skeleton]



535

AWS IoT 开发人员指南GetLoggingOptions


名称类型描述

jobId 字符串


模式：[a-zA-Z0-9_-]+


输出:


cli 输出字段：

名称类型描述

文档字符串



GetLoggingOptions获取日志记录选项。

请求语法：

GET /loggingOptions

响应语法：


{ "roleArn": "string", "logLevel": "string"}



roleArn AwsArn 否授予访问权限的 IAM 角色的 ARN。

logLevel 日志级别否日志记录的级别。

错误:

536


InternalException







CLI摘要:

aws iot get-logging-options \ [--cli-input-json <value>] \ [--generate-cli-skeleton]


{}

输出:

{ "roleArn": "string", "logLevel": "string"}

cli 输出字段：

名称类型描述


logLevel 字符串

枚举：DEBUG | INFO | ERROR |WARN | DISABLED

java 类：iot.goldeneye.service.LogLevel

日志记录的级别。

GetOTAUpdate获取 OTA 更新。

537

AWS IoT 开发人员指南GetOTAUpdate

请求语法：

GET /otaUpdates/otaUpdateId

URI 请求参数：


otaUpdateId OTAUpdateId 是 OTA 更新 ID。

响应语法：


{ "otaUpdateInfo": { "otaUpdateId": "string", "otaUpdateArn": "string", "creationDate": "timestamp", "lastModifiedDate": "timestamp", "description": "string", "targets": [ "string" ], "targetSelection": "string", "otaUpdateFiles": [ { "fileName": "string", "fileVersion": "string", "fileSource": { "streamId": "string", "fileId": "integer" }, "codeSigning": { "awsSignerJobId": "string", "customCodeSigning": { "signature": { "stream": { "streamId": "string", "fileId": "integer" }, "inlineDocument": "blob" }, "certificateChain": { "stream": { "streamId": "string", "fileId": "integer" }, "certificateName": "string", "inlineDocument": "string" }, "hashAlgorithm": "string", "signatureAlgorithm": "string" } }, "attributes": { "string": "string" } } ], "otaUpdateStatus": "string",

538


"awsIotJobId": "string", "awsIotJobArn": "string", "errorInfo": { "code": "string", "message": "string" }, "additionalParameters": { "string": "string" } }}



otaUpdateInfo OTAUpdateInfo 否 OTA 更新信息。

错误:














CLI摘要:

aws iot get-ota-update \ --ota-update-id <value> \ [--cli-input-json <value>] \

539




{ "otaUpdateId": "string"}


名称类型描述



模式：[a-zA-Z0-9_-]+

OTA 更新 ID。

输出:

{ "otaUpdateInfo": { "otaUpdateId": "string", "otaUpdateArn": "string", "creationDate": "timestamp", "lastModifiedDate": "timestamp", "description": "string", "targets": [ "string" ], "targetSelection": "string", "otaUpdateFiles": [ { "fileName": "string", "fileVersion": "string", "fileSource": { "streamId": "string", "fileId": "integer" }, "codeSigning": { "awsSignerJobId": "string", "customCodeSigning": { "signature": { "stream": { "streamId": "string", "fileId": "integer" }, "inlineDocument": "blob" }, "certificateChain": { "stream": { "streamId": "string", "fileId": "integer" }, "certificateName": "string", "inlineDocument": "string" }, "hashAlgorithm": "string", "signatureAlgorithm": "string" } },

540


"attributes": { "string": "string" } } ], "otaUpdateStatus": "string", "awsIotJobId": "string", "awsIotJobArn": "string", "errorInfo": { "code": "string", "message": "string" }, "additionalParameters": { "string": "string" } }}

cli 输出字段：

名称类型描述

otaUpdateInfo OTAUpdateInfo OTA 更新信息。



模式：[a-zA-Z0-9_-]+

OTA 更新 ID。


creationDate timestamp 创建 OTA 更新的日期。

lastModifiedDate timestamp 上次更新 OTA 更新的日期。


最大长度：2028

模式：[^\\p{C}]+

OTA 更新的描述。

目标列表

成员：Target

OTA 更新的目标。

Target 字符串



指定 OTA 更新将继续运行(CONTINUOUS)，还是在指定作为目标的所有事物完成 OTA 更新之后完成 (SNAPSHOT)。如果继续运行，则在检测到目标中出现更改时，OTA 更新也会在事物上运行。例如，当某个事物添加到目标组时会在该事物上运行 OTA更新，即使是组中原有的全部事物已经完成了 OTA 更新。

otaUpdateFiles 列表

成员：OTAUpdateFile

与 OTA 更新关联的文件列表。

541


名称类型描述

OTAUpdateFile OTAUpdateFile

fileName 字符串文件的名称。

fileVersion 字符串文件版本。

fileSource 流文件的源。

streamId 字符串


模式：[a-zA-Z0-9_-]+

流 ID。

fileId integer




codeSigning CodeSigning 文件的代码签名方法。

awsSignerJobId 字符串已创建用于对文件签名的AWSSignerJob 的 ID。

customCodeSigning CustomCodeSigning 用于对文件执行代码签名的自定义方法。

签名 CodeSigningSignature 文件的签名。

stream 流代码签署签名的流。

streamId 字符串


模式：[a-zA-Z0-9_-]+

流 ID。

fileId integer




inlineDocument blob 代码签署签名的 base64 编码二进制表示形式。

certificateChain CodeSigningCertificateChain 证书链。

stream 流证书链文件的流。

streamId 字符串


模式：[a-zA-Z0-9_-]+

流 ID。

542


名称类型描述

fileId integer




certificateName 字符串证书的名称。

inlineDocument 字符串代码签名证书链的 base64 编码二进制表示形式。

hashAlgorithm 字符串用于对文件进行代码签名的哈希算法。

signatureAlgorithm 字符串用于对文件进行代码签名的签名算法。

个属性 map

键：Key

值：Value

名称/属性对的列表。

Key 字符串

值字符串



OTA 更新的状态。

awsIotJobId 字符串与 OTA 更新关联的 AWS IoT 任务 ID。

awsIotJobArn 字符串与 OTA 更新关联的 AWS IoT 任务 ARN。

errorInfo ErrorInfo 与 OTA 更新关联的错误信息。

code 字符串错误代码。

message 字符串错误消息。

additionalParameters map

键：Key

值：Value

名称/值对的集合

Key 字符串

值字符串

543

AWS IoT 开发人员指南GetPendingJobExecutions

GetPendingJobExecutions获取未处于最终状态的事物的所有任务列表。

请求语法：

GET /things/thingName/jobs

URI 请求参数：


thingName ThingName 是正在执行任务的事物的名称。

响应语法：


{ "inProgressJobs": [ { "jobId": "string", "queuedAt": "long", "startedAt": "long", "lastUpdatedAt": "long", "versionNumber": "long", "executionNumber": "long" } ], "queuedJobs": [ { "jobId": "string", "queuedAt": "long", "startedAt": "long", "lastUpdatedAt": "long", "versionNumber": "long", "executionNumber": "long" } ]}



inProgressJobs JobExecutionSummaryList否状态为IN_PROGRESS 的JobExecutionSummary对象的列表。

queuedJobs JobExecutionSummaryList否状态为 QUEUED 的JobExecutionSummary对象的列表。

错误:

544











证书无效。


CLI摘要:

aws iot-jobs-data get-pending-job-executions \ --thing-name <value> \ [--cli-input-json <value>] \ [--generate-cli-skeleton]




名称类型描述

thingName 字符串


模式：[a-zA-Z0-9:_-]+


输出:

{ "inProgressJobs": [ { "jobId": "string",

545


"queuedAt": "long", "startedAt": "long", "lastUpdatedAt": "long", "versionNumber": "long", "executionNumber": "long" } ], "queuedJobs": [ { "jobId": "string", "queuedAt": "long", "startedAt": "long", "lastUpdatedAt": "long", "versionNumber": "long", "executionNumber": "long" } ]}

cli 输出字段：

名称类型描述

inProgressJobs 列表



状态为 IN_PROGRESS 的JobExecutionSummary 对象的列表。


jobId 字符串


模式：[a-zA-Z0-9_-]+



startedAt long








queuedJobs 列表



状态为 QUEUED 的JobExecutionSummary 对象的列表。


546

AWS IoT 开发人员指南GetPolicy

名称类型描述

jobId 字符串


模式：[a-zA-Z0-9_-]+



startedAt long








GetPolicy获取具有默认版本策略文档的指定策略的相关信息。

请求语法：

GET /policies/policyName

URI 请求参数：



响应语法：


{ "policyName": "string", "policyArn": "string", "policyDocument": "string", "defaultVersionId": "string"}




547





defaultVersionId PolicyVersionId 否默认策略版本 ID。

错误:














CLI摘要:

aws iot get-policy \ --policy-name <value> \ [--cli-input-json <value>] \ [--generate-cli-skeleton]



548

AWS IoT 开发人员指南GetPolicyVersion


名称类型描述



模式：[w+=,.@-]+

策略的名称。

输出:

{ "policyName": "string", "policyArn": "string", "policyDocument": "string", "defaultVersionId": "string"}

cli 输出字段：

名称类型描述



模式：[w+=,.@-]+

策略名称。



defaultVersionId 字符串

模式：[0-9]+

默认策略版本 ID。

GetPolicyVersion获取有关指定策略版本的信息。

请求语法：

GET /policies/policyName/version/policyVersionId

URI 请求参数：




响应语法：

549

AWS IoT 开发人员指南GetPolicyVersion


{ "policyArn": "string", "policyName": "string", "policyDocument": "string", "policyVersionId": "string", "isDefaultVersion": "boolean"}







isDefaultVersion IsDefaultVersion 否指定策略版本是否为默认版本。

错误:














550


CLI摘要:

aws iot get-policy-version \ --policy-name <value> \ --policy-version-id <value> \ [--cli-input-json <value>] \ [--generate-cli-skeleton]




名称类型描述



模式：[w+=,.@-]+

策略的名称。


模式：[0-9]+

策略版本 ID。

输出:

{ "policyArn": "string", "policyName": "string", "policyDocument": "string", "policyVersionId": "string", "isDefaultVersion": "boolean"}

cli 输出字段：

名称类型描述




模式：[w+=,.@-]+

策略名称。



模式：[0-9]+

策略版本 ID。

551

AWS IoT 开发人员指南GetRegistrationCode

名称类型描述


GetRegistrationCode获取用于将 CA 证书注册到 AWS IoT 的注册代码。

请求语法：

GET /registrationcode

响应语法：


{ "registrationCode": "string"}



registrationCode RegistrationCode 否 CA 证书注册代码。

错误:

ThrottlingException











552


CLI摘要:

aws iot get-registration-code \ [--cli-input-json <value>] \ [--generate-cli-skeleton]


{}

输出:

{ "registrationCode": "string"}

cli 输出字段：

名称类型描述

registrationCode 字符串


模式：(0x)?[a-fA-F0-9]+

CA 证书注册代码。

GetThingShadow获取指定事物的影子。

有关更多信息，请参阅《AWS IoT 开发人员指南》中的 GetThingShadow。

请求语法：

GET /things/thingName/shadow

URI 请求参数：



响应语法：



553

http://docs.aws.amazon.com/iot/latest/developerguide/API_GetThingShadow.html




payload JsonDocument 否状态信息，采用 JSON格式。

错误:













HTTP 响应代码：500MethodNotAllowedException





CLI摘要:

aws iot-data get-thing-shadow \ --thing-name <value> \ [--cli-input-json <value>] \

554

AWS IoT 开发人员指南GetTopicRule





名称类型描述

thingName 字符串


模式：[a-zA-Z0-9:_-]+

事物的名称。

输出:


cli 输出字段：

名称类型描述


GetTopicRule获取有关规则的信息。

请求语法：

GET /rules/ruleName

URI 请求参数：



响应语法：


{ "ruleArn": "string", "rule": { "ruleName": "string", "sql": "string",

555


"description": "string", "createdAt": "timestamp", "actions": [ { "dynamoDB": { "tableName": "string", "roleArn": "string", "operation": "string", "hashKeyField": "string", "hashKeyValue": "string", "hashKeyType": "string", "rangeKeyField": "string", "rangeKeyValue": "string", "rangeKeyType": "string", "payloadField": "string" }, "dynamoDBv2": { "roleArn": "string", "putItem": { "tableName": "string" } }, "lambda": { "functionArn": "string" }, "sns": { "targetArn": "string", "roleArn": "string", "messageFormat": "string" }, "sqs": { "roleArn": "string", "queueUrl": "string", "useBase64": "boolean" }, "kinesis": { "roleArn": "string", "streamName": "string", "partitionKey": "string" }, "republish": { "roleArn": "string", "topic": "string" }, "s3": { "roleArn": "string", "bucketName": "string", "key": "string", "cannedAcl": "string" }, "firehose": { "roleArn": "string", "deliveryStreamName": "string", "separator": "string" }, "cloudwatchMetric": { "roleArn": "string", "metricNamespace": "string", "metricName": "string", "metricValue": "string", "metricUnit": "string", "metricTimestamp": "string" }, "cloudwatchAlarm": { "roleArn": "string", "alarmName": "string",

556


"stateReason": "string", "stateValue": "string" }, "elasticsearch": { "roleArn": "string", "endpoint": "string", "index": "string", "type": "string", "id": "string" }, "salesforce": { "token": "string", "url": "string" } } ], "ruleDisabled": "boolean", "awsIotSqlVersion": "string", "errorAction": { "dynamoDB": { "tableName": "string", "roleArn": "string", "operation": "string", "hashKeyField": "string", "hashKeyValue": "string", "hashKeyType": "string", "rangeKeyField": "string", "rangeKeyValue": "string", "rangeKeyType": "string", "payloadField": "string" }, "dynamoDBv2": { "roleArn": "string", "putItem": { "tableName": "string" } }, "lambda": { "functionArn": "string" }, "sns": { "targetArn": "string", "roleArn": "string", "messageFormat": "string" }, "sqs": { "roleArn": "string", "queueUrl": "string", "useBase64": "boolean" }, "kinesis": { "roleArn": "string", "streamName": "string", "partitionKey": "string" }, "republish": { "roleArn": "string", "topic": "string" }, "s3": { "roleArn": "string", "bucketName": "string", "key": "string", "cannedAcl": "string" }, "firehose": {

557


"roleArn": "string", "deliveryStreamName": "string", "separator": "string" }, "cloudwatchMetric": { "roleArn": "string", "metricNamespace": "string", "metricName": "string", "metricValue": "string", "metricUnit": "string", "metricTimestamp": "string" }, "cloudwatchAlarm": { "roleArn": "string", "alarmName": "string", "stateReason": "string", "stateValue": "string" }, "elasticsearch": { "roleArn": "string", "endpoint": "string", "index": "string", "type": "string", "id": "string" }, "salesforce": { "token": "string", "url": "string" } } }}



ruleArn RuleArn 否规则 ARN。

规则 TopicRule 否规则。

错误:

InternalException








558



CLI摘要:

aws iot get-topic-rule \ --rule-name <value> \ [--cli-input-json <value>] \ [--generate-cli-skeleton]




名称类型描述

ruleName 字符串


模式：^[a-zA-Z0-9_]+$

规则的名称。

输出:

{ "ruleArn": "string", "rule": { "ruleName": "string", "sql": "string", "description": "string", "createdAt": "timestamp", "actions": [ { "dynamoDB": { "tableName": "string", "roleArn": "string", "operation": "string", "hashKeyField": "string", "hashKeyValue": "string", "hashKeyType": "string", "rangeKeyField": "string", "rangeKeyValue": "string", "rangeKeyType": "string", "payloadField": "string" }, "dynamoDBv2": { "roleArn": "string", "putItem": { "tableName": "string" } }, "lambda": { "functionArn": "string"

559


}, "sns": { "targetArn": "string", "roleArn": "string", "messageFormat": "string" }, "sqs": { "roleArn": "string", "queueUrl": "string", "useBase64": "boolean" }, "kinesis": { "roleArn": "string", "streamName": "string", "partitionKey": "string" }, "republish": { "roleArn": "string", "topic": "string" }, "s3": { "roleArn": "string", "bucketName": "string", "key": "string", "cannedAcl": "string" }, "firehose": { "roleArn": "string", "deliveryStreamName": "string", "separator": "string" }, "cloudwatchMetric": { "roleArn": "string", "metricNamespace": "string", "metricName": "string", "metricValue": "string", "metricUnit": "string", "metricTimestamp": "string" }, "cloudwatchAlarm": { "roleArn": "string", "alarmName": "string", "stateReason": "string", "stateValue": "string" }, "elasticsearch": { "roleArn": "string", "endpoint": "string", "index": "string", "type": "string", "id": "string" }, "salesforce": { "token": "string", "url": "string" } } ], "ruleDisabled": "boolean", "awsIotSqlVersion": "string", "errorAction": { "dynamoDB": { "tableName": "string", "roleArn": "string", "operation": "string", "hashKeyField": "string",

560


"hashKeyValue": "string", "hashKeyType": "string", "rangeKeyField": "string", "rangeKeyValue": "string", "rangeKeyType": "string", "payloadField": "string" }, "dynamoDBv2": { "roleArn": "string", "putItem": { "tableName": "string" } }, "lambda": { "functionArn": "string" }, "sns": { "targetArn": "string", "roleArn": "string", "messageFormat": "string" }, "sqs": { "roleArn": "string", "queueUrl": "string", "useBase64": "boolean" }, "kinesis": { "roleArn": "string", "streamName": "string", "partitionKey": "string" }, "republish": { "roleArn": "string", "topic": "string" }, "s3": { "roleArn": "string", "bucketName": "string", "key": "string", "cannedAcl": "string" }, "firehose": { "roleArn": "string", "deliveryStreamName": "string", "separator": "string" }, "cloudwatchMetric": { "roleArn": "string", "metricNamespace": "string", "metricName": "string", "metricValue": "string", "metricUnit": "string", "metricTimestamp": "string" }, "cloudwatchAlarm": { "roleArn": "string", "alarmName": "string", "stateReason": "string", "stateValue": "string" }, "elasticsearch": { "roleArn": "string", "endpoint": "string", "index": "string", "type": "string", "id": "string"

561


}, "salesforce": { "token": "string", "url": "string" } } }}

cli 输出字段：

名称类型描述

ruleArn 字符串规则 ARN。

规则 TopicRule 规则。

ruleName 字符串


模式：^[a-zA-Z0-9_]+$

规则的名称。

sql 字符串用于查询主题的 SQL 语句。使用多行 SQL 查询时，请确保对换行符转义。


createdAt timestamp 创建规则的日期和时间。

操作列表

成员：Action


操作操作












562


名称类型描述



















枚举：RAW | JSON



563





名称类型描述




useBase64 布尔值














cannedAcl 字符串







564




名称类型描述

separator 字符串

pattern: ([ ])|( )|(,)
















endpoint 字符串







token 字符串

最小长度：40


565




名称类型描述

url 字符串

最大长度：2000

























566


名称类型描述













枚举：RAW | JSON






useBase64 布尔值



567





名称类型描述












cannedAcl 字符串







separator 字符串

pattern: ([ ])|( )|(,)






568



AWS IoT 开发人员指南GetV2LoggingOptions

名称类型描述











endpoint 字符串







token 字符串

最小长度：40


url 字符串

最大长度：2000



GetV2LoggingOptions获取精细日志记录选项。

569




请求语法：

GET /v2LoggingOptions

响应语法：


{ "roleArn": "string", "defaultLogLevel": "string", "disableAllLogs": "boolean"}



roleArn AwsArn 否 AWS IoT 写入您的CloudWatch 日志时使用的 IAM 角色 ARN。

defaultLogLevel 日志级别否默认日志级别。

disableAllLogs DisableAllLogs 否禁用所有日志。

错误:

InternalException







CLI摘要:

aws iot get-v2-logging-options \ [--cli-input-json <value>] \ [--generate-cli-skeleton]


570

AWS IoT 开发人员指南ListAttachedPolicies

{}

输出:


cli 输出字段：

名称类型描述

roleArn 字符串 AWS IoT 写入您的 CloudWatch日志时使用的 IAM 角色 ARN。

defaultLogLevel 字符串



默认日志级别。

disableAllLogs 布尔值禁用所有日志。

ListAttachedPolicies列出附加到指定事物组的策略。

请求语法：

POST /attached-policies/target?recursive=recursive&pageSize=pageSize&marker=marker

URI 请求参数：


target PolicyTarget 是将列出其策略的组。

recursive 递归否为 true 时，以递归方式列出附加策略。

标记 Marker 否用于检索下一组结果的令牌。

pageSize PageSize 否每个请求返回的最大结果数。

响应语法：


571

AWS IoT 开发人员指南ListAttachedPolicies

{ "policies": [ { "policyName": "string", "policyArn": "string" } ], "nextMarker": "string"}



策略策略否策略。

nextMarker Marker 否用于检索下一组结果的令牌，没有更多结果时为 null。

错误:
















572


CLI摘要:

aws iot list-attached-policies \ --target <value> \ [--recursive | --no-recursive] \ [--marker <value>] \ [--page-size <value>] \ [--cli-input-json <value>] \ [--generate-cli-skeleton]


{ "target": "string", "recursive": "boolean", "marker": "string", "pageSize": "integer"}


名称类型描述

target 字符串将列出其策略的组。

recursive 布尔值为 true 时，以递归方式列出附加策略。

标记字符串

模式：[A-Za-z0-9+/]+={0,2}

用于检索下一组结果的令牌。

pageSize integer




输出:


cli 输出字段：

名称类型描述

策略列表策略。

573

AWS IoT 开发人员指南ListAuthorizers

名称类型描述成员：Policy


策略策略



模式：[w+=,.@-]+

策略名称。


nextMarker 字符串

模式：[A-Za-z0-9+/]+={0,2}

用于检索下一组结果的令牌，没有更多结果时为 null。

ListAuthorizers列出您账户中已注册的授权方。

请求语法：

GET /authorizers/?pageSize=pageSize&marker=marker&isAscendingOrder=ascendingOrder&status=status

URI 请求参数：


pageSize PageSize 否一次性返回的最大结果数。

标记 Marker 否用于获取下一组结果的标记。

ascendingOrder AscendingOrder 否按字母顺序的升序返回授权方列表。

status AuthorizerStatus 否列出授权方请求的状态。

响应语法：


{ "authorizers": [ { "authorizerName": "string", "authorizerArn": "string" } ],

574


"nextMarker": "string"}



authorizers 授权方否授权方。

nextMarker Marker 否用于获取下一组结果的标记。

错误:












CLI摘要:

aws iot list-authorizers \ [--page-size <value>] \ [--marker <value>] \ [--ascending-order | --no-ascending-order] \ [--status <value>] \ [--cli-input-json <value>] \ [--generate-cli-skeleton]


{ "pageSize": "integer",

575


"marker": "string", "ascendingOrder": "boolean", "status": "string"}


名称类型描述

pageSize integer



一次性返回的最大结果数。

标记字符串

模式：[A-Za-z0-9+/]+={0,2}

用于获取下一组结果的标记。

ascendingOrder 布尔值按字母顺序的升序返回授权方列表。

status 字符串



列出授权方请求的状态。

输出:

{ "authorizers": [ { "authorizerName": "string", "authorizerArn": "string" } ], "nextMarker": "string"}

cli 输出字段：

名称类型描述

authorizers 列表

成员：AuthorizerSummary


授权方。

AuthorizerSummary AuthorizerSummary



模式：[w=,@-]+

授权方名称。


576

AWS IoT 开发人员指南ListCACertificates

名称类型描述


模式：[A-Za-z0-9+/]+={0,2}


ListCACertificates列出为您的 AWS 账户注册的 CA 证书。

对结果进行分页的默认页面大小为 25。您可以使用返回的标记来检索更多结果。

请求语法：

GET /cacertificates?pageSize=pageSize&marker=marker&isAscendingOrder=ascendingOrder

URI 请求参数：


pageSize PageSize 否结果页面大小。


ascendingOrder AscendingOrder 否确定结果的顺序。

响应语法：


{ "certificates": [ { "certificateArn": "string", "certificateId": "string", "status": "string", "creationDate": "timestamp" } ], "nextMarker": "string"}



证书 CACertificates 否在您的 AWS 账户中注册的 CA 证书。

nextMarker Marker 否 CA 证书列表中的当前位置。

错误:

577













CLI摘要:

aws iot list-ca-certificates \ [--page-size <value>] \ [--marker <value>] \ [--ascending-order | --no-ascending-order] \ [--cli-input-json <value>] \ [--generate-cli-skeleton]


{ "pageSize": "integer", "marker": "string", "ascendingOrder": "boolean"}


名称类型描述

pageSize integer



结果页面大小。

578

AWS IoT 开发人员指南ListCertificates

名称类型描述

标记字符串

模式：[A-Za-z0-9+/]+={0,2}


ascendingOrder 布尔值确定结果的顺序。

输出:


cli 输出字段：

名称类型描述

证书列表

成员：CACertificate


在您的 AWS 账户中注册的 CA 证书。

CACertificate CACertificate

certificateArn 字符串 CA 证书的 ARN。



模式：(0x)?[a-fA-F0-9]+

CA 证书的 ID。

status 字符串



CA 证书的状态。

状态值 REGISTER_INACTIVE 已弃用，不应再使用。

creationDate timestamp CA 证书的创建日期。


模式：[A-Za-z0-9+/]+={0,2}

CA 证书列表中的当前位置。

ListCertificates列出在您的 AWS 账户中注册的证书。

579

AWS IoT 开发人员指南ListCertificates

对结果进行分页的默认页面大小为 25。您可以使用返回的标记来检索更多结果。

请求语法：

GET /certificates?pageSize=pageSize&marker=marker&isAscendingOrder=ascendingOrder

URI 请求参数：




ascendingOrder AscendingOrder 否指定结果的顺序。如果为 True，结果按创建日期的升序返回。

响应语法：





证书证书否证书的描述。

nextMarker Marker 否下一组结果的标记，没有更多结果时为 null。

错误:





580









CLI摘要:

aws iot list-certificates \ [--page-size <value>] \ [--marker <value>] \ [--ascending-order | --no-ascending-order] \ [--cli-input-json <value>] \ [--generate-cli-skeleton]




名称类型描述

pageSize integer




标记字符串

模式：[A-Za-z0-9+/]+={0,2}


ascendingOrder 布尔值指定结果的顺序。如果为 True，结果按创建日期的升序返回。

输出:

581

AWS IoT 开发人员指南ListCertificatesByCA


cli 输出字段：

名称类型描述

证书列表

成员：Certificate


证书的描述。

证书证书




模式：(0x)?[a-fA-F0-9]+


status 字符串



证书的状态。




模式：[A-Za-z0-9+/]+={0,2}

下一组结果的标记，没有更多结果时为 null。

ListCertificatesByCA列出由指定 CA 证书签名的设备证书。

请求语法：

GET /certificates-by-ca/caCertificateId?pageSize=pageSize&marker=marker&isAscendingOrder=ascendingOrder

582

AWS IoT 开发人员指南ListCertificatesByCA

URI 请求参数：


caCertificateId CertificateId 是 CA 证书的 ID。此操作将列出由该 CA 证书签名的所有已注册设备证书。




响应语法：





证书证书否由指定 CA 证书签名的设备证书。


错误:






583









CLI摘要:

aws iot list-certificates-by-ca \ --ca-certificate-id <value> \ [--page-size <value>] \ [--marker <value>] \ [--ascending-order | --no-ascending-order] \ [--cli-input-json <value>] \ [--generate-cli-skeleton]


{ "caCertificateId": "string", "pageSize": "integer", "marker": "string", "ascendingOrder": "boolean"}


名称类型描述

caCertificateId 字符串


模式：(0x)?[a-fA-F0-9]+

CA 证书的 ID。此操作将列出由该CA 证书签名的所有已注册设备证书。

pageSize integer




标记字符串

模式：[A-Za-z0-9+/]+={0,2}



584

AWS IoT 开发人员指南ListIndices

输出:


cli 输出字段：

名称类型描述

证书列表

成员：Certificate


由指定 CA 证书签名的设备证书。

证书证书




模式：(0x)?[a-fA-F0-9]+


status 字符串



证书的状态。




模式：[A-Za-z0-9+/]+={0,2}


ListIndices列出搜索索引。

请求语法：

GET /indices?nextToken=nextToken&maxResults=maxResults

585

AWS IoT 开发人员指南ListIndices

URI 请求参数：


nextToken NextToken 否用于获取下一组结果的令牌，没有更多结果时为 null。

maxResults QueryMaxResults 否一次性返回的最大结果数。

响应语法：


{ "indexNames": [ "string" ], "nextToken": "string"}



indexNames IndexNamesList 否索引名称。


错误:











586



CLI摘要:

aws iot list-indices \ [--next-token <value>] \ [--max-results <value>] \ [--cli-input-json <value>] \ [--generate-cli-skeleton]


{ "nextToken": "string", "maxResults": "integer"}


名称类型描述

nextToken 字符串用于获取下一组结果的令牌，没有更多结果时为 null。

maxResults integer




输出:

{ "indexNames": [ "string" ], "nextToken": "string"}

cli 输出字段：

名称类型描述

indexNames 列表

成员：IndexName


索引名称。

IndexName 字符串


模式：[a-zA-Z0-9:_-]+

587

AWS IoT 开发人员指南ListJobExecutionsForJob

名称类型描述


ListJobExecutionsForJob列出任务的任务执行。

请求语法：

GET /jobs/jobId/things?status=status&maxResults=maxResults&nextToken=nextToken

URI 请求参数：



status JobExecutionStatus 否任务的状态。

maxResults LaserMaxResults 否每个请求返回的最大结果数。

nextToken NextToken 否用于检索下一组结果的令牌。

响应语法：


{ "executionSummaries": [ { "thingArn": "string", "jobExecutionSummary": { "status": "string", "queuedAt": "timestamp", "startedAt": "timestamp", "lastUpdatedAt": "timestamp", "executionNumber": "long" } } ], "nextToken": "string"}



executionSummaries JobExecutionSummaryForJobList否任务执行摘要的列表。

588



nextToken NextToken 否下一组结果的令牌，没有更多结果时为 null。

错误:










CLI摘要:

aws iot list-job-executions-for-job \ --job-id <value> \ [--status <value>] \ [--max-results <value>] \ [--next-token <value>] \ [--cli-input-json <value>] \ [--generate-cli-skeleton]


{ "jobId": "string", "status": "string", "maxResults": "integer", "nextToken": "string"}


名称类型描述

jobId 字符串您在创建此任务时向其分配的唯一标识符。

589



模式：[a-zA-Z0-9_-]+

status 字符串



任务的状态。

maxResults integer





输出:

{ "executionSummaries": [ { "thingArn": "string", "jobExecutionSummary": { "status": "string", "queuedAt": "timestamp", "startedAt": "timestamp", "lastUpdatedAt": "timestamp", "executionNumber": "long" } } ], "nextToken": "string"}

cli 输出字段：

名称类型描述


成员：JobExecutionSummaryForJob



JobExecutionSummaryForJob JobExecutionSummaryForJob



590

AWS IoT 开发人员指南ListJobExecutionsForThing

名称类型描述

status 字符串











ListJobExecutionsForThing列出指定事物的任务执行。

请求语法：

GET /things/thingName/jobs?status=status&maxResults=maxResults&nextToken=nextToken

URI 请求参数：


thingName ThingName 是事物名称。

status JobExecutionStatus 否一个可选筛选条件，允许您搜索具有指定状态的任务。



响应语法：

591



{ "executionSummaries": [ { "jobId": "string", "jobExecutionSummary": { "status": "string", "queuedAt": "timestamp", "startedAt": "timestamp", "lastUpdatedAt": "timestamp", "executionNumber": "long" } } ], "nextToken": "string"}



executionSummaries JobExecutionSummaryForThingList否任务执行摘要的列表。


错误:










CLI摘要:

aws iot list-job-executions-for-thing \

592


--thing-name <value> \ [--status <value>] \ [--max-results <value>] \ [--next-token <value>] \ [--cli-input-json <value>] \ [--generate-cli-skeleton]


{ "thingName": "string", "status": "string", "maxResults": "integer", "nextToken": "string"}


名称类型描述

thingName 字符串


模式：[a-zA-Z0-9:_-]+

事物名称。

status 字符串




maxResults integer





输出:

{ "executionSummaries": [ { "jobId": "string", "jobExecutionSummary": { "status": "string", "queuedAt": "timestamp", "startedAt": "timestamp", "lastUpdatedAt": "timestamp", "executionNumber": "long" } } ], "nextToken": "string"

593

AWS IoT 开发人员指南ListJobs

}

cli 输出字段：

名称类型描述


成员：JobExecutionSummaryForThing



JobExecutionSummaryForThing JobExecutionSummaryForThing

jobId 字符串


模式：[a-zA-Z0-9_-]+



status 字符串











ListJobs列出任务。

请求语法：

594

AWS IoT 开发人员指南ListJobs

GET /jobs?status=status&targetSelection=targetSelection&maxResults=maxResults&nextToken=nextToken&thingGroupName=thingGroupName&thingGroupId=thingGroupId

URI 请求参数：


status JobStatus 否一个可选筛选条件，允许您搜索具有指定状态的任务。

targetSelection TargetSelection 否指定任务将继续运行(CONTINUOUS)，还是在指定作为目标的所有事物完成任务之后完成(SNAPSHOT)。如果继续运行，则在检测到目标中出现更改时，任务也会在事物上运行。例如，当某个事物添加到目标组时会在该事物上运行任务，即使是组中原有的全部事物已经完成了任务。



thingGroupName ThingGroupName 否一个筛选条件，用于将返回的任务限制为指定组的任务。

thingGroupId ThingGroupId 否一个筛选条件，用于将返回的任务限制为指定组的任务。

响应语法：


{ "jobs": [ { "jobArn": "string", "jobId": "string", "thingGroupId": "string", "targetSelection": "string", "status": "string", "createdAt": "timestamp", "lastUpdatedAt": "timestamp", "completedAt": "timestamp" } ], "nextToken": "string"

595


}



jobs JobSummaryList 否任务列表。


错误:










CLI摘要:

aws iot list-jobs \ [--status <value>] \ [--target-selection <value>] \ [--max-results <value>] \ [--next-token <value>] \ [--thing-group-name <value>] \ [--thing-group-id <value>] \ [--cli-input-json <value>] \ [--generate-cli-skeleton]


{ "status": "string", "targetSelection": "string", "maxResults": "integer", "nextToken": "string",

596


"thingGroupName": "string", "thingGroupId": "string"}


名称类型描述

status 字符串








maxResults integer







模式：[a-zA-Z0-9:_-]+




模式：[a-zA-Z0-9-]+


输出:

{ "jobs": [ { "jobArn": "string", "jobId": "string", "thingGroupId": "string", "targetSelection": "string", "status": "string", "createdAt": "timestamp", "lastUpdatedAt": "timestamp", "completedAt": "timestamp"

597


} ], "nextToken": "string"}

cli 输出字段：

名称类型描述

jobs 列表

成员：Job Summary


任务列表。

JobSummary JobSummary


jobId 字符串


模式：[a-zA-Z0-9_-]+




模式：[a-zA-Z0-9-]+

事物组的 ID。





status 字符串



任务摘要状态。





598

AWS IoT 开发人员指南ListOTAUpdates

ListOTAUpdates列出 OTA 更新。

请求语法：

GET /otaUpdates?maxResults=maxResults&nextToken=nextToken&otaUpdateStatus=otaUpdateStatus

URI 请求参数：


maxResults MaxResults 否一次性返回的最大结果数。


otaUpdateStatus OTAUpdateStatus 否 OTA 更新任务状态。

响应语法：


{ "otaUpdates": [ { "otaUpdateId": "string", "otaUpdateArn": "string", "creationDate": "timestamp" } ], "nextToken": "string"}



otaUpdates OTAUpdatesSummary 否 OTA 更新任务列表。

nextToken NextToken 否用于获取下一组结果的令牌。

错误:






599









CLI摘要:

aws iot list-ota-updates \ [--max-results <value>] \ [--next-token <value>] \ [--ota-update-status <value>] \ [--cli-input-json <value>] \ [--generate-cli-skeleton]


{ "maxResults": "integer", "nextToken": "string", "otaUpdateStatus": "string"}


名称类型描述

maxResults integer







OTA 更新任务状态。

输出:

{ "otaUpdates": [

600

AWS IoT 开发人员指南ListOutgoingCertificates

{ "otaUpdateId": "string", "otaUpdateArn": "string", "creationDate": "timestamp" } ], "nextToken": "string"}

cli 输出字段：

名称类型描述

otaUpdates 列表

成员：OTAUpdateSummary

OTA 更新任务列表。

OTAUpdateSummary OTAUpdateSummary



模式：[a-zA-Z0-9_-]+

OTA 更新 ID。


creationDate timestamp 创建 OTA 更新的日期。

nextToken 字符串用于获取下一组结果的令牌。

ListOutgoingCertificates列出正在传输但尚未接受的证书。

请求语法：

GET /certificates-out-going?pageSize=pageSize&marker=marker&isAscendingOrder=ascendingOrder

URI 请求参数：





响应语法：


601


{ "outgoingCertificates": [ { "certificateArn": "string", "certificateId": "string", "transferredTo": "string", "transferDate": "timestamp", "transferMessage": "string", "creationDate": "timestamp" } ], "nextMarker": "string"}



outgoingCertificates OutgoingCertificates 否正在传输但尚未接受的证书。


错误:












CLI摘要:

aws iot list-outgoing-certificates \ [--page-size <value>] \

602


[--marker <value>] \ [--ascending-order | --no-ascending-order] \ [--cli-input-json <value>] \ [--generate-cli-skeleton]




名称类型描述

pageSize integer




标记字符串

模式：[A-Za-z0-9+/]+={0,2}



输出:

{ "outgoingCertificates": [ { "certificateArn": "string", "certificateId": "string", "transferredTo": "string", "transferDate": "timestamp", "transferMessage": "string", "creationDate": "timestamp" } ], "nextMarker": "string"}

cli 输出字段：

名称类型描述

outgoingCertificates 列表

成员：OutgoingCertificate


正在传输但尚未接受的证书。

OutgoingCertificate OutgoingCertificate

certificateArn 字符串证书 ARN。

603

AWS IoT 开发人员指南ListPolicies

名称类型描述



模式：(0x)?[a-fA-F0-9]+

证书 ID。

transferredTo 字符串

模式：[0-9]{12}

传输到的 AWS 账户。

transferDate timestamp 启动传输的日期。


最大长度：128

传输消息。

creationDate timestamp 证书创建日期。


模式：[A-Za-z0-9+/]+={0,2}


ListPolicies列出您的策略。

请求语法：

GET /policies?marker=marker&pageSize=pageSize&isAscendingOrder=ascendingOrder

URI 请求参数：




ascendingOrder AscendingOrder 否指定结果的顺序。如果为 True，结果按创建顺序的升序返回。

响应语法：


{ "policies": [ { "policyName": "string", "policyArn": "string" } ], "nextMarker": "string"

604


}



策略策略否策略的描述。


错误:












CLI摘要:

aws iot list-policies \ [--marker <value>] \ [--page-size <value>] \ [--ascending-order | --no-ascending-order] \ [--cli-input-json <value>] \ [--generate-cli-skeleton]


{ "marker": "string", "pageSize": "integer", "ascendingOrder": "boolean"}

605

AWS IoT 开发人员指南ListPolicyPrincipals


名称类型描述

标记字符串

模式：[A-Za-z0-9+/]+={0,2}


pageSize integer




ascendingOrder 布尔值指定结果的顺序。如果为 True，结果按创建顺序的升序返回。

输出:


cli 输出字段：

名称类型描述

策略列表

成员：Policy


策略的描述。

策略策略



模式：[w+=,.@-]+

策略名称。



模式：[A-Za-z0-9+/]+={0,2}


ListPolicyPrincipals列出与指定策略关联的委托人。

注意：此 API 已弃用。请改用 ListTargetsForPolicy。

606

AWS IoT 开发人员指南ListPolicyPrincipals

请求语法：

GET /policy-principals?marker=marker&pageSize=pageSize&isAscendingOrder=ascendingOrder x-amzn-iot-policy: policyName

URI 请求参数：






响应语法：


{ "principals": [ "string" ], "nextMarker": "string"}



principals 委托人否委托人的描述。


错误:







607









CLI摘要:

aws iot list-policy-principals \ --policy-name <value> \ [--marker <value>] \ [--page-size <value>] \ [--ascending-order | --no-ascending-order] \ [--cli-input-json <value>] \ [--generate-cli-skeleton]


{ "policyName": "string", "marker": "string", "pageSize": "integer", "ascendingOrder": "boolean"}


名称类型描述



模式：[w+=,.@-]+

策略名称。

标记字符串

模式：[A-Za-z0-9+/]+={0,2}


pageSize integer




608

AWS IoT 开发人员指南ListPolicyVersions

名称类型描述


输出:

{ "principals": [ "string" ], "nextMarker": "string"}

cli 输出字段：

名称类型描述

principals 列表

成员：PrincipalArn


委托人的描述。

PrincipalArn 字符串


模式：[A-Za-z0-9+/]+={0,2}


ListPolicyVersions列出指定策略的版本并标识默认版本。

请求语法：

GET /policies/policyName/version

URI 请求参数：



响应语法：


{ "policyVersions": [ { "versionId": "string", "isDefaultVersion": "boolean", "createDate": "timestamp" }

609


]}



policyVersions PolicyVersions 否策略版本。

错误:














CLI摘要:

aws iot list-policy-versions \ --policy-name <value> \ [--cli-input-json <value>] \ [--generate-cli-skeleton]



610

AWS IoT 开发人员指南ListPrincipalPolicies


名称类型描述



模式：[w+=,.@-]+

策略名称。

输出:

{ "policyVersions": [ { "versionId": "string", "isDefaultVersion": "boolean", "createDate": "timestamp" } ]}

cli 输出字段：

名称类型描述

policyVersions 列表

成员：PolicyVersion


策略版本。

PolicyVersion PolicyVersion

versionId 字符串

模式：[0-9]+

策略版本 ID。


createDate timestamp 创建策略的日期和时间。

ListPrincipalPolicies列出附加到指定委托人的策略。如果您使用 Cognito 身份，ID 必须使用 AmazonCognito 身份格式。

注意：此 API 已弃用。请改用 ListAttachedPolicies。

请求语法：

GET /principal-policies?marker=marker&pageSize=pageSize&isAscendingOrder=ascendingOrder x-amzn-iot-principal: principal

URI 请求参数：



611

http://docs.aws.amazon.com/cognitoidentity/latest/APIReference/API_GetCredentialsForIdentity.html#API_GetCredentialsForIdentity_RequestSyntax

AWS IoT 开发人员指南ListPrincipalPolicies





响应语法：





策略策略否策略。


错误:










612







CLI摘要:

aws iot list-principal-policies \ --principal <value> \ [--marker <value>] \ [--page-size <value>] \ [--ascending-order | --no-ascending-order] \ [--cli-input-json <value>] \ [--generate-cli-skeleton]


{ "principal": "string", "marker": "string", "pageSize": "integer", "ascendingOrder": "boolean"}


名称类型描述


标记字符串

模式：[A-Za-z0-9+/]+={0,2}


pageSize integer





输出:

{ "policies": [ { "policyName": "string", "policyArn": "string"

613

AWS IoT 开发人员指南ListPrincipalThings

} ], "nextMarker": "string"}

cli 输出字段：

名称类型描述

策略列表

成员：Policy


策略。

策略策略



模式：[w+=,.@-]+

策略名称。



模式：[A-Za-z0-9+/]+={0,2}


ListPrincipalThings列出与指定委托人关联的事物。

请求语法：

GET /principals/things?maxResults=maxResults&nextToken=nextToken x-amzn-principal: principal

URI 请求参数：



maxResults RegistryMaxResults 否此操作中要返回的最大结果数。


响应语法：


{

614


"things": [ "string" ], "nextToken": "string"}



things ThingNameList 否事物。


错误:














CLI摘要:

aws iot list-principal-things \ [--next-token <value>] \ [--max-results <value>] \

615

AWS IoT 开发人员指南ListRoleAliases

--principal <value> \ [--cli-input-json <value>] \ [--generate-cli-skeleton]


{ "nextToken": "string", "maxResults": "integer", "principal": "string"}


名称类型描述


maxResults integer



此操作中要返回的最大结果数。


输出:

{ "things": [ "string" ], "nextToken": "string"}

cli 输出字段：

名称类型描述

things 列表

成员：ThingName

事物。

ThingName 字符串


模式：[a-zA-Z0-9:_-]+


ListRoleAliases列出您账户中已注册的角色别名。

616

AWS IoT 开发人员指南ListRoleAliases

请求语法：

GET /role-aliases?pageSize=pageSize&marker=marker&isAscendingOrder=ascendingOrder

URI 请求参数：




ascendingOrder AscendingOrder 否按字母顺序的升序返回角色别名列表。

响应语法：


{ "roleAliases": [ "string" ], "nextMarker": "string"}



roleAliases RoleAliases 否角色别名。


错误:








617







CLI摘要:

aws iot list-role-aliases \ [--page-size <value>] \ [--marker <value>] \ [--ascending-order | --no-ascending-order] \ [--cli-input-json <value>] \ [--generate-cli-skeleton]




名称类型描述

pageSize integer




标记字符串

模式：[A-Za-z0-9+/]+={0,2}


ascendingOrder 布尔值按字母顺序的升序返回角色别名列表。

输出:

{ "roleAliases": [ "string" ], "nextMarker": "string"}

618

AWS IoT 开发人员指南ListStreams

cli 输出字段：

名称类型描述

roleAliases 列表

成员：RoleAlias


角色别名。

RoleAlias 字符串


模式：[w=,@-]+


模式：[A-Za-z0-9+/]+={0,2}


ListStreams列出您的 AWS 账户中的所有流。

请求语法：

GET /streams?maxResults=maxResults&nextToken=nextToken&isAscendingOrder=ascendingOrder

URI 请求参数：


maxResults MaxResults 否一次性返回的最大结果数。


ascendingOrder AscendingOrder 否设置为 true 时，将按照升序返回流的列表。

响应语法：


{ "streams": [ { "streamId": "string", "streamArn": "string", "streamVersion": "integer", "description": "string" } ], "nextToken": "string"}

619




streams StreamsSummary 否流的列表。


错误:












CLI摘要:

aws iot list-streams \ [--max-results <value>] \ [--next-token <value>] \ [--ascending-order | --no-ascending-order] \ [--cli-input-json <value>] \ [--generate-cli-skeleton]


{ "maxResults": "integer", "nextToken": "string", "ascendingOrder": "boolean"}

620



名称类型描述

maxResults integer





ascendingOrder 布尔值设置为 true 时，将按照升序返回流的列表。

输出:

{ "streams": [ { "streamId": "string", "streamArn": "string", "streamVersion": "integer", "description": "string" } ], "nextToken": "string"}

cli 输出字段：

名称类型描述

streams 列表

成员：StreamSummary

流的列表。

StreamSummary StreamSummary

streamId 字符串


模式：[a-zA-Z0-9_-]+

流 ID。





流版本。


最大长度：2028

模式：[^\\p{C}]+

流的描述。


621

AWS IoT 开发人员指南ListTargetsForPolicy

ListTargetsForPolicy列出指定策略的目标。

请求语法：

POST /policy-targets/policyName?marker=marker&pageSize=pageSize

URI 请求参数：





响应语法：


{ "targets": [ "string" ], "nextMarker": "string"}



目标 PolicyTargets 否策略目标。


错误:






622


ThrottlingException











CLI摘要:

aws iot list-targets-for-policy \ --policy-name <value> \ [--marker <value>] \ [--page-size <value>] \ [--cli-input-json <value>] \ [--generate-cli-skeleton]


{ "policyName": "string", "marker": "string", "pageSize": "integer"}


名称类型描述



模式：[w+=,.@-]+

策略名称。

623

AWS IoT 开发人员指南ListThingGroups

名称类型描述

标记字符串

模式：[A-Za-z0-9+/]+={0,2}


pageSize integer




输出:

{ "targets": [ "string" ], "nextMarker": "string"}

cli 输出字段：

名称类型描述

目标列表

成员：PolicyTarget


策略目标。

PolicyTarget 字符串


模式：[A-Za-z0-9+/]+={0,2}


ListThingGroups列出您账户中的事物组。

请求语法：

GET /thing-groups?maxResults=maxResults&nextToken=nextToken&parentGroup=parentGroup&namePrefixFilter=namePrefixFilter&recursive=recursive

URI 请求参数：



maxResults RegistryMaxResults 否一次性返回的最大结果数。

624

AWS IoT 开发人员指南ListThingGroups


parentGroup ThingGroupName 否一个筛选条件，用于将结果限制为指定的父组。

namePrefixFilter ThingGroupName 否一个筛选条件，用于将结果限制为具有指定名称前缀的组。

recursive RecursiveWithoutDefault 否如果为 true，则还会返回子组。

响应语法：


{ "thingGroups": [ { "groupName": "string", "groupArn": "string" } ], "nextToken": "string"}



thingGroups ThingGroupNameAndArnList否事物组。


错误:








625


CLI摘要:

aws iot list-thing-groups \ [--next-token <value>] \ [--max-results <value>] \ [--parent-group <value>] \ [--name-prefix-filter <value>] \ [--recursive | --no-recursive] \ [--cli-input-json <value>] \ [--generate-cli-skeleton]


{ "nextToken": "string", "maxResults": "integer", "parentGroup": "string", "namePrefixFilter": "string", "recursive": "boolean"}


名称类型描述


maxResults integer




parentGroup 字符串


模式：[a-zA-Z0-9:_-]+

一个筛选条件，用于将结果限制为指定的父组。

namePrefixFilter 字符串


模式：[a-zA-Z0-9:_-]+

一个筛选条件，用于将结果限制为具有指定名称前缀的组。

recursive 布尔值


如果为 true，则还会返回子组。

输出:

{ "thingGroups": [ { "groupName": "string",

626

AWS IoT 开发人员指南ListThingGroupsForThing

"groupArn": "string" } ], "nextToken": "string"}

cli 输出字段：

名称类型描述

thingGroups 列表



事物组。


groupName 字符串


模式：[a-zA-Z0-9:_-]+

组名称。



ListThingGroupsForThing指定事物所属的事物组列表。

请求语法：

GET /things/thingName/thing-groups?maxResults=maxResults&nextToken=nextToken

URI 请求参数：


thingName ThingName 是事物名称。



响应语法：


{

627


"thingGroups": [ { "groupName": "string", "groupArn": "string" } ], "nextToken": "string"}



thingGroups ThingGroupNameAndArnList否事物组。


错误:








CLI摘要:

aws iot list-thing-groups-for-thing \ --thing-name <value> \ [--next-token <value>] \ [--max-results <value>] \ [--cli-input-json <value>] \ [--generate-cli-skeleton]


{ "thingName": "string", "nextToken": "string", "maxResults": "integer"}

628

AWS IoT 开发人员指南ListThingPrincipals


名称类型描述

thingName 字符串


模式：[a-zA-Z0-9:_-]+

事物名称。


maxResults integer




输出:

{ "thingGroups": [ { "groupName": "string", "groupArn": "string" } ], "nextToken": "string"}

cli 输出字段：

名称类型描述

thingGroups 列表



事物组。


groupName 字符串


模式：[a-zA-Z0-9:_-]+

组名称。



ListThingPrincipals列出与指定事物关联的委托人。

629

AWS IoT 开发人员指南ListThingPrincipals

请求语法：

GET /things/thingName/principals

URI 请求参数：



响应语法：


{ "principals": [ "string" ]}



principals 委托人否与事物关联的委托人。

错误:













630



CLI摘要:

aws iot list-thing-principals \ --thing-name <value> \ [--cli-input-json <value>] \ [--generate-cli-skeleton]




名称类型描述

thingName 字符串


模式：[a-zA-Z0-9:_-]+

事物的名称。

输出:

{ "principals": [ "string" ]}

cli 输出字段：

名称类型描述

principals 列表

成员：PrincipalArn


与事物关联的委托人。

PrincipalArn 字符串

ListThingRegistrationTaskReports有关事物注册任务的信息。

请求语法：

631

AWS IoT 开发人员指南ListThingRegistrationTaskReports

GET /thing-registration-tasks/taskId/reports?reportType=reportType&maxResults=maxResults&nextToken=nextToken

URI 请求参数：


taskId TaskId 是任务的 ID。

reportType ReportType 是任务报告的类型。


maxResults RegistryMaxResults 否每个请求返回的最大结果数。

响应语法：


{ "resourceLinks": [ "string" ], "reportType": "string", "nextToken": "string"}



resourceLinks S3FileUrlList 否任务资源的链接。

reportType ReportType 否任务报告的类型。


错误:







632





CLI摘要:

aws iot list-thing-registration-task-reports \ --task-id <value> \ --report-type <value> \ [--next-token <value>] \ [--max-results <value>] \ [--cli-input-json <value>] \ [--generate-cli-skeleton]


{ "taskId": "string", "reportType": "string", "nextToken": "string", "maxResults": "integer"}


名称类型描述

taskId 字符串

最大长度：40

任务的 ID。

reportType 字符串

枚举：ERRORS | RESULTS

java 类：com.amazonaws.iot.common.types.enums.ReportType

任务报告的类型。


maxResults integer




输出:

{ "resourceLinks": [ "string"

633

AWS IoT 开发人员指南ListThingRegistrationTasks

], "reportType": "string", "nextToken": "string"}

cli 输出字段：

名称类型描述

resourceLinks 列表

成员：S3FileUrl

任务资源的链接。

S3FileUrl 字符串


reportType 字符串

枚举：ERRORS | RESULTS

java 类：com.amazonaws.iot.common.types.enums.ReportType

任务报告的类型。


ListThingRegistrationTasks列出批量事物预配置任务。

请求语法：

GET /thing-registration-tasks?maxResults=maxResults&nextToken=nextToken&status=status

URI 请求参数：




status Status 否批量事物预配置任务的状态。

响应语法：


{ "taskIds": [ "string"

634


], "nextToken": "string"}



taskIds TaskIdList 否批量事物预配置任务 ID的列表。


错误:










CLI摘要:

aws iot list-thing-registration-tasks \ [--next-token <value>] \ [--max-results <value>] \ [--status <value>] \ [--cli-input-json <value>] \ [--generate-cli-skeleton]


{ "nextToken": "string", "maxResults": "integer",

635

AWS IoT 开发人员指南ListThingTypes

"status": "string"}


名称类型描述


maxResults integer




status 字符串

枚举：InProgress | Completed |Failed | Cancelled | Cancelling

java 类：com.amazonaws.iot.common.types.enums.Status

批量事物预配置任务的状态。

输出:

{ "taskIds": [ "string" ], "nextToken": "string"}

cli 输出字段：

名称类型描述

taskIds 列表

成员：TaskId

批量事物预配置任务 ID 的列表。

TaskId 字符串

最大长度：40


ListThingTypes列出现有事物类型。

请求语法：

GET /thing-types?maxResults=maxResults&nextToken=nextToken&thingTypeName=thingTypeName

636

AWS IoT 开发人员指南ListThingTypes

URI 请求参数：





响应语法：


{ "thingTypes": [ { "thingTypeName": "string", "thingTypeArn": "string", "thingTypeProperties": { "thingTypeDescription": "string", "searchableAttributes": [ "string" ] }, "thingTypeMetadata": { "deprecated": "boolean", "deprecationDate": "timestamp", "creationDate": "timestamp" } } ], "nextToken": "string"}



thingTypes ThingTypeList 否事物类型。


错误:






637









CLI摘要:

aws iot list-thing-types \ [--next-token <value>] \ [--max-results <value>] \ [--thing-type-name <value>] \ [--cli-input-json <value>] \ [--generate-cli-skeleton]


{ "nextToken": "string", "maxResults": "integer", "thingTypeName": "string"}


名称类型描述


maxResults integer






模式：[a-zA-Z0-9:_-]+


输出:

{ "thingTypes": [

638


{ "thingTypeName": "string", "thingTypeArn": "string", "thingTypeProperties": { "thingTypeDescription": "string", "searchableAttributes": [ "string" ] }, "thingTypeMetadata": { "deprecated": "boolean", "deprecationDate": "timestamp", "creationDate": "timestamp" } } ], "nextToken": "string"}

cli 输出字段：

名称类型描述

thingTypes 列表

成员：ThingTypeDefinition


事物类型。

ThingTypeDefinition ThingTypeDefinition



模式：[a-zA-Z0-9:_-]+


thingTypeArn 字符串事物类型 ARN。

thingTypeProperties ThingTypeProperties 事物类型的ThingTypeProperties。


最大长度：2028








最大长度：128

模式：[a-zA-Z0-9_.,@/:#-]+

thingTypeMetadata ThingTypeMetadata ThingTypeMetadata 包含有关事物类型的其他信息，包括：创建日期和时间、指示该事物类型是

639

AWS IoT 开发人员指南ListThings

名称类型描述否已弃用的值以及弃用的日期和时间。

已弃用布尔值事物类型是否已弃用。如果为true，则新事物无法与此类型关联。

deprecationDate timestamp 弃用事物类型的日期和时间。

creationDate timestamp 创建事物类型的日期和时间。


ListThings列出您的事物。使用 attributeName 和 attributeValue 参数来筛选事物。例如，使用 attributeName=Color和 attributeValue=Red 调用 ListThings 可检索注册表中包含属性 Color 并且值为 Red 的所有事物。

请求语法：

GET /things?maxResults=maxResults&nextToken=nextToken&attributeName=attributeName&attributeValue=attributeValue&thingTypeName=thingTypeName

URI 请求参数：




attributeName AttributeName 否用于搜索事物的属性名称。

attributeValue AttributeValue 否用于搜索事物的属性值。

thingTypeName ThingTypeName 否用于搜索事物的事物类型的名称。

响应语法：


{ "things": [ { "thingName": "string", "thingTypeName": "string",

640


"thingArn": "string", "attributes": { "string": "string" }, "version": "long" } ], "nextToken": "string"}



things ThingAttributeList 否事物。


错误:












CLI摘要:

aws iot list-things \ [--next-token <value>] \

641


[--max-results <value>] \ [--attribute-name <value>] \ [--attribute-value <value>] \ [--thing-type-name <value>] \ [--cli-input-json <value>] \ [--generate-cli-skeleton]


{ "nextToken": "string", "maxResults": "integer", "attributeName": "string", "attributeValue": "string", "thingTypeName": "string"}


名称类型描述


maxResults integer




attributeName 字符串

最大长度：128

模式：[a-zA-Z0-9_.,@/:#-]+

用于搜索事物的属性名称。

attributeValue 字符串

最大长度：800

模式：[a-zA-Z0-9_.,@/:#-]*

用于搜索事物的属性值。



模式：[a-zA-Z0-9:_-]+

用于搜索事物的事物类型的名称。

输出:

{ "things": [ { "thingName": "string", "thingTypeName": "string", "thingArn": "string", "attributes": { "string": "string" }, "version": "long"

642

AWS IoT 开发人员指南ListThingsInThingGroup

} ], "nextToken": "string"}

cli 输出字段：

名称类型描述

things 列表

成员：ThingAttribute


事物。

ThingAttribute ThingAttribute

thingName 字符串


模式：[a-zA-Z0-9:_-]+

事物的名称。



模式：[a-zA-Z0-9:_-]+

如果事物已经与类型关联，则为事物类型的名称。

thingArn 字符串事物 ARN。

个属性 map

键：AttributeName


名称/值对形式的事物属性的列表。


最大长度：128

模式：[a-zA-Z0-9_.,@/:#-]+


最大长度：800

模式：[a-zA-Z0-9_.,@/:#-]*

version long 注册表中事物记录的版本。


ListThingsInThingGroup列出指定组中的事物。

请求语法：

643

AWS IoT 开发人员指南ListThingsInThingGroup

GET /thing-groups/thingGroupName/things?recursive=recursive&maxResults=maxResults&nextToken=nextToken

URI 请求参数：


thingGroupName ThingGroupName 是事物组名称。

recursive 递归否为 true 时，列出此事物组及其所有子组中的事物。



响应语法：





things ThingNameList 否列出指定事物组中的事物。


错误:






644





CLI摘要:

aws iot list-things-in-thing-group \ --thing-group-name <value> \ [--recursive | --no-recursive] \ [--next-token <value>] \ [--max-results <value>] \ [--cli-input-json <value>] \ [--generate-cli-skeleton]


{ "thingGroupName": "string", "recursive": "boolean", "nextToken": "string", "maxResults": "integer"}


名称类型描述



模式：[a-zA-Z0-9:_-]+

事物组名称。

recursive 布尔值为 true 时，列出此事物组及其所有子组中的事物。


maxResults integer




输出:


645

AWS IoT 开发人员指南ListTopicRules

cli 输出字段：

名称类型描述

things 列表

成员：ThingName

列出指定事物组中的事物。

ThingName 字符串


模式：[a-zA-Z0-9:_-]+


ListTopicRules列出特定主题的规则。

请求语法：

GET /rules?topic=topic&maxResults=maxResults&nextToken=nextToken&ruleDisabled=ruleDisabled

URI 请求参数：


topic 主题否主题。

maxResults GEMaxResults 否要返回的最大结果数量。

nextToken NextToken 否用于检索下一个值的令牌。

ruleDisabled IsDisabled 否指定是否禁用规则。

响应语法：


{ "rules": [ { "ruleArn": "string", "ruleName": "string", "topicPattern": "string", "createdAt": "timestamp", "ruleDisabled": "boolean" } ], "nextToken": "string"}

646




规则 TopicRuleList 否规则。

nextToken NextToken 否用于检索下一个值的令牌。

错误:

InternalException







CLI摘要:

aws iot list-topic-rules \ [--topic <value>] \ [--max-results <value>] \ [--next-token <value>] \ [--rule-disabled | --no-rule-disabled] \ [--cli-input-json <value>] \ [--generate-cli-skeleton]


{ "topic": "string", "maxResults": "integer", "nextToken": "string", "ruleDisabled": "boolean"}


名称类型描述

topic 字符串主题。

maxResults integer 要返回的最大结果数量。

647

AWS IoT 开发人员指南ListV2LoggingLevels

名称类型描述java 类：java.lang.Integer


nextToken 字符串用于检索下一个值的令牌。




输出:

{ "rules": [ { "ruleArn": "string", "ruleName": "string", "topicPattern": "string", "createdAt": "timestamp", "ruleDisabled": "boolean" } ], "nextToken": "string"}

cli 输出字段：

名称类型描述

规则列表

成员：TopicRuleListItem

规则。

TopicRuleListItem TopicRuleListItem

ruleArn 字符串规则 ARN。

ruleName 字符串


模式：^[a-zA-Z0-9_]+$

规则的名称。

topicPattern 字符串应用的主题名称的模式。

createdAt timestamp 创建规则的日期和时间。




nextToken 字符串用于检索下一个值的令牌。

ListV2LoggingLevels列出日志记录级别。

648

AWS IoT 开发人员指南ListV2LoggingLevels

请求语法：

GET /v2LoggingLevel?maxResults=maxResults&nextToken=nextToken&targetType=targetType

URI 请求参数：


targetType LogTargetType 否您要配置日志记录的资源的类型。必须是THING_Group。


maxResults SkyfallMaxResults 否一次性返回的最大结果数。

响应语法：


{ "logTargetConfigurations": [ { "logTarget": { "targetType": "string", "targetName": "string" }, "logLevel": "string" } ], "nextToken": "string"}



logTargetConfigurations LogTargetConfigurations 否目标的日志记录配置。


错误:

InternalException


HTTP 响应代码：500NotConfiguredException

未配置的资源。

649







CLI摘要:

aws iot list-v2-logging-levels \ [--target-type <value>] \ [--next-token <value>] \ [--max-results <value>] \ [--cli-input-json <value>] \ [--generate-cli-skeleton]


{ "targetType": "string", "nextToken": "string", "maxResults": "integer"}


名称类型描述




您要配置日志记录的资源的类型。必须是 THING_Group。


maxResults integer




输出:

{

650

AWS IoT 开发人员指南发布

"logTargetConfigurations": [ { "logTarget": { "targetType": "string", "targetName": "string" }, "logLevel": "string" } ], "nextToken": "string"}

cli 输出字段：

名称类型描述

logTargetConfigurations 列表

成员：LogTargetConfiguration

目标的日志记录配置。

LogTargetConfiguration LogTargetConfiguration

logTarget LogTarget 日志目标




目标类型。

targetName 字符串目标名称。

logLevel 字符串



日志记录的级别。


发布发布状态信息。

有关更多信息，请参阅《AWS IoT 开发人员指南》中的 HTTP 协议。

请求语法：

POST /topics/topic?qos=qos Content-type: application/json


651

http://docs.aws.amazon.com/iot/latest/developerguide/protocols.html#http


URI 请求参数：


topic 主题否 MQTT; 主题的名称。

qos Qos 否服务质量 (QoS) 级别。



payload Payload 否状态信息，采用 JSON格式。

错误:










CLI摘要:

aws iot-data publish \ [--topic <value>] \ [--qos <value>] \ [--payload <value>] \ [--cli-input-json <value>] \ [--generate-cli-skeleton]


{ "topic": "string", "qos": "integer", "payload": "blob"

652

AWS IoT 开发人员指南RegisterCACertificate

}


名称类型描述


qos integer


服务质量 (QoS) 级别。


输出:

无

RegisterCACertificate向 AWS IoT 注册 CA 证书。此 CA 证书可用于对设备证书进行签名，而设备证书随后可注册到 AWS IoT。您最多可以为每个 AWS 账户注册 10 个具有相同主题字段的 CA 证书。这使得您可以让最多 10 个证书颁发机构对您的设备证书进行签名。如果您注册了多个 CA 证书，请确保在使用 RegisterCertificate API 注册设备证书时传递了 CA 证书。

请求语法：

POST /cacertificate?setAsActive=setAsActive&allowAutoRegistration=allowAutoRegistration Content-type: application/json

{ "caCertificate": "string", "verificationCertificate": "string", "registrationConfig": { "templateBody": "string", "roleArn": "string" }}

URI 请求参数：


setAsActive SetAsActive 否指定 CA 证书是否设置为活动状态的布尔值。

allowAutoRegistration AllowAutoRegistration 否允许将此 CA 证书用于自动注册设备证书。



caCertificate CertificatePem 是 CA 证书。

verificationCertificate CertificatePem 是私有密钥验证证书。

653

AWS IoT 开发人员指南RegisterCACertificate



响应语法：


{ "certificateArn": "string", "certificateId": "string"}



certificateArn CertificateArn 否 CA 证书 ARN。

certificateId CertificateId 否 CA 证书标识符。

错误:



HTTP 响应代码：409RegistrationCodeValidationException

注册代码无效。




证书无效。







654







CLI摘要:

aws iot register-ca-certificate \ --ca-certificate <value> \ --verification-certificate <value> \ [--set-as-active | --no-set-as-active] \ [--allow-auto-registration | --no-allow-auto-registration] \ [--registration-config <value>] \ [--cli-input-json <value>] \ [--generate-cli-skeleton]


{ "caCertificate": "string", "verificationCertificate": "string", "setAsActive": "boolean", "allowAutoRegistration": "boolean", "registrationConfig": { "templateBody": "string", "roleArn": "string" }}


名称类型描述

caCertificate 字符串


CA 证书。

verificationCertificate 字符串


私有密钥验证证书。

setAsActive 布尔值指定 CA 证书是否设置为活动状态的布尔值。

allowAutoRegistration 布尔值允许将此 CA 证书用于自动注册设备证书。



655

AWS IoT 开发人员指南RegisterCertificate

名称类型描述

roleArn 字符串


角色的 ARN。

输出:


cli 输出字段：

名称类型描述

certificateArn 字符串 CA 证书 ARN。



模式：(0x)?[a-fA-F0-9]+


RegisterCertificate向 AWS IoT 注册设备证书。如果您有多个 CA 证书具有相同主题字段，则必须指定用于对所注册设备证书进行签名的 CA 证书。

请求语法：

POST /certificate/register?setAsActive=setAsActive Content-type: application/json

{ "certificatePem": "string", "caCertificatePem": "string", "status": "string"}

URI 请求参数：


setAsActive SetAsActiveFlag 否指定 CA 证书是否设置为活动状态的布尔值。



certificatePem CertificatePem 是 PEM 格式的证书数据。

656

AWS IoT 开发人员指南RegisterCertificate


caCertificatePem CertificatePem 否用于对所要注册的设备证书进行签名的 CA 证书。

status CertificateStatus 否注册证书请求的状态。

响应语法：





certificateArn CertificateArn 否证书 ARN。

certificateId CertificateId 否证书标识符。

错误:






证书无效。



HTTP 响应代码：406CertificateConflictException

无法验证用于对您尝试注册的设备证书进行签名的 CA 证书。当您注册了具有相同主题字段和公有密钥的多个 CA 证书时，会出现这种情况。


657


ThrottlingException









CLI摘要:

aws iot register-certificate \ --certificate-pem <value> \ [--ca-certificate-pem <value>] \ [--set-as-active | --no-set-as-active] \ [--status <value>] \ [--cli-input-json <value>] \ [--generate-cli-skeleton]


{ "certificatePem": "string", "caCertificatePem": "string", "status": "string"}


名称类型描述




caCertificatePem 字符串


用于对所要注册的设备证书进行签名的 CA 证书。

status 字符串

枚举：ACTIVE |INACTIVE | REVOKED |PENDING_TRANSFER |

注册证书请求的状态。

658

AWS IoT 开发人员指南RegisterThing

名称类型描述REGISTER_INACTIVE |PENDING_ACTIVATION


输出:


cli 输出字段：

名称类型描述

certificateArn 字符串证书 ARN。



模式：(0x)?[a-fA-F0-9]+

证书标识符。

RegisterThing预配置事物。

请求语法：

POST /things Content-type: application/json

{ "templateBody": "string", "parameters": { "string": "string" }}



templateBody TemplateBody 是预配置模板。有关更多信息，请参阅以编程方式进行预置。

parameters 参数否用于预配置事物的参数。有关更多信息，请参阅以编程方式进行预置。

659

http://docs.aws.amazon.com/iot/latest/developerguide/programmatic-provisioning.html




AWS IoT 开发人员指南RegisterThing

响应语法：


{ "certificatePem": "string", "resourceArns": { "string": "string" }}



certificatePem CertificatePem 否

resourceArns ResourceArns 否所生成资源的 ARN。

错误:











HTTP 响应代码：429ConflictingResourceUpdateException

资源更新冲突异常。在两个待处理更新导致冲突时，会引发此异常。

HTTP 响应代码：409ResourceRegistrationFailureException

资源注册失败。


660


CLI摘要:

aws iot register-thing \ --template-body <value> \ [--parameters <value>] \ [--cli-input-json <value>] \ [--generate-cli-skeleton]


{ "templateBody": "string", "parameters": { "string": "string" }}


名称类型描述

templateBody 字符串预配置模板。有关更多信息，请参阅以编程方式进行预置。

parameters map

键：Parameter

值：Value

用于预配置事物的参数。有关更多信息，请参阅以编程方式进行预置。

参数字符串

值字符串

输出:

{ "certificatePem": "string", "resourceArns": { "string": "string" }}

cli 输出字段：

名称类型描述



resourceArns map

键：ResourceLogicalId

值：ResourceArn

所生成资源的 ARN。

661




AWS IoT 开发人员指南RejectCertificateTransfer

名称类型描述

ResourceLogicalId 字符串

ResourceArn 字符串

RejectCertificateTransfer拒绝待处理证书传输。AWS IoT 拒绝证书传输之后，证书状态会从 PENDING_TRANSFER 更改为INACTIVE。

要检查待处理证书传输，请调用 ListCertificates 以枚举证书。

此操作只能由传输目标调用。在调用后，证书将以 INACTIVE 状态返回到源的账户。

请求语法：

PATCH /reject-certificate-transfer/certificateId Content-type: application/json

{ "rejectReason": "string"}

URI 请求参数：





rejectReason Message 否拒绝证书传输的原因。

错误:







662











CLI摘要:

aws iot reject-certificate-transfer \ --certificate-id <value> \ [--reject-reason <value>] \ [--cli-input-json <value>] \ [--generate-cli-skeleton]


{ "certificateId": "string", "rejectReason": "string"}


名称类型描述



模式：(0x)?[a-fA-F0-9]+


rejectReason 字符串

最大长度：128

拒绝证书传输的原因。

输出:

663

AWS IoT 开发人员指南RemoveThingFromThingGroup

无

RemoveThingFromThingGroup从指定组中删除指定事物。

请求语法：

PUT /thing-groups/removeThingFromThingGroup Content-type: application/json




thingGroupName ThingGroupName 否组名称。

thingGroupArn ThingGroupArn 否组 ARN。

thingName ThingName 否要从组中删除的事物的名称。

thingArn ThingArn 否要从组中删除的事物的ARN。

错误:










664


CLI摘要:

aws iot remove-thing-from-thing-group \ [--thing-group-name <value>] \ [--thing-group-arn <value>] \ [--thing-name <value>] \ [--thing-arn <value>] \ [--cli-input-json <value>] \ [--generate-cli-skeleton]




名称类型描述



模式：[a-zA-Z0-9:_-]+

组名称。

thingGroupArn 字符串组 ARN。

thingName 字符串


模式：[a-zA-Z0-9:_-]+

要从组中删除的事物的名称。

thingArn 字符串要从组中删除的事物的 ARN。

输出:

无

ReplaceTopicRule替换规则。您必须为新规则指定所有参数。创建规则是管理员级别操作。有权创建规则的所有用户都将能够访问规则所处理的数据。

请求语法：

PATCH /rules/ruleName Content-type: application/json

665

AWS IoT 开发人员指南ReplaceTopicRule

{ "topicRulePayload": { "sql": "string", "description": "string", "actions": [ { "dynamoDB": { "tableName": "string", "roleArn": "string", "operation": "string", "hashKeyField": "string", "hashKeyValue": "string", "hashKeyType": "string", "rangeKeyField": "string", "rangeKeyValue": "string", "rangeKeyType": "string", "payloadField": "string" }, "dynamoDBv2": { "roleArn": "string", "putItem": { "tableName": "string" } }, "lambda": { "functionArn": "string" }, "sns": { "targetArn": "string", "roleArn": "string", "messageFormat": "string" }, "sqs": { "roleArn": "string", "queueUrl": "string", "useBase64": "boolean" }, "kinesis": { "roleArn": "string", "streamName": "string", "partitionKey": "string" }, "republish": { "roleArn": "string", "topic": "string" }, "s3": { "roleArn": "string", "bucketName": "string", "key": "string", "cannedAcl": "string" }, "firehose": { "roleArn": "string", "deliveryStreamName": "string", "separator": "string" }, "cloudwatchMetric": { "roleArn": "string", "metricNamespace": "string", "metricName": "string", "metricValue": "string", "metricUnit": "string", "metricTimestamp": "string" },

666


"cloudwatchAlarm": { "roleArn": "string", "alarmName": "string", "stateReason": "string", "stateValue": "string" }, "elasticsearch": { "roleArn": "string", "endpoint": "string", "index": "string", "type": "string", "id": "string" }, "salesforce": { "token": "string", "url": "string" } } ], "ruleDisabled": "boolean", "awsIotSqlVersion": "string", "errorAction": { "dynamoDB": { "tableName": "string", "roleArn": "string", "operation": "string", "hashKeyField": "string", "hashKeyValue": "string", "hashKeyType": "string", "rangeKeyField": "string", "rangeKeyValue": "string", "rangeKeyType": "string", "payloadField": "string" }, "dynamoDBv2": { "roleArn": "string", "putItem": { "tableName": "string" } }, "lambda": { "functionArn": "string" }, "sns": { "targetArn": "string", "roleArn": "string", "messageFormat": "string" }, "sqs": { "roleArn": "string", "queueUrl": "string", "useBase64": "boolean" }, "kinesis": { "roleArn": "string", "streamName": "string", "partitionKey": "string" }, "republish": { "roleArn": "string", "topic": "string" }, "s3": { "roleArn": "string", "bucketName": "string", "key": "string",

667


"cannedAcl": "string" }, "firehose": { "roleArn": "string", "deliveryStreamName": "string", "separator": "string" }, "cloudwatchMetric": { "roleArn": "string", "metricNamespace": "string", "metricName": "string", "metricValue": "string", "metricUnit": "string", "metricTimestamp": "string" }, "cloudwatchAlarm": { "roleArn": "string", "alarmName": "string", "stateReason": "string", "stateValue": "string" }, "elasticsearch": { "roleArn": "string", "endpoint": "string", "index": "string", "type": "string", "id": "string" }, "salesforce": { "token": "string", "url": "string" } } }}

URI 请求参数：





topicRulePayload TopicRulePayload 是规则负载。

错误:

SqlParseException

无法正确解析 Rule-SQL 表达式。

HTTP 响应代码：400InternalException



668









CLI摘要:

aws iot replace-topic-rule \ --rule-name <value> \ --topic-rule-payload <value> \ [--cli-input-json <value>] \ [--generate-cli-skeleton]


{ "ruleName": "string", "topicRulePayload": { "sql": "string", "description": "string", "actions": [ { "dynamoDB": { "tableName": "string", "roleArn": "string", "operation": "string", "hashKeyField": "string", "hashKeyValue": "string", "hashKeyType": "string", "rangeKeyField": "string", "rangeKeyValue": "string", "rangeKeyType": "string", "payloadField": "string" }, "dynamoDBv2": { "roleArn": "string", "putItem": { "tableName": "string" } }, "lambda": { "functionArn": "string" }, "sns": { "targetArn": "string",

669


"roleArn": "string", "messageFormat": "string" }, "sqs": { "roleArn": "string", "queueUrl": "string", "useBase64": "boolean" }, "kinesis": { "roleArn": "string", "streamName": "string", "partitionKey": "string" }, "republish": { "roleArn": "string", "topic": "string" }, "s3": { "roleArn": "string", "bucketName": "string", "key": "string", "cannedAcl": "string" }, "firehose": { "roleArn": "string", "deliveryStreamName": "string", "separator": "string" }, "cloudwatchMetric": { "roleArn": "string", "metricNamespace": "string", "metricName": "string", "metricValue": "string", "metricUnit": "string", "metricTimestamp": "string" }, "cloudwatchAlarm": { "roleArn": "string", "alarmName": "string", "stateReason": "string", "stateValue": "string" }, "elasticsearch": { "roleArn": "string", "endpoint": "string", "index": "string", "type": "string", "id": "string" }, "salesforce": { "token": "string", "url": "string" } } ], "ruleDisabled": "boolean", "awsIotSqlVersion": "string", "errorAction": { "dynamoDB": { "tableName": "string", "roleArn": "string", "operation": "string", "hashKeyField": "string", "hashKeyValue": "string", "hashKeyType": "string", "rangeKeyField": "string",

670


"rangeKeyValue": "string", "rangeKeyType": "string", "payloadField": "string" }, "dynamoDBv2": { "roleArn": "string", "putItem": { "tableName": "string" } }, "lambda": { "functionArn": "string" }, "sns": { "targetArn": "string", "roleArn": "string", "messageFormat": "string" }, "sqs": { "roleArn": "string", "queueUrl": "string", "useBase64": "boolean" }, "kinesis": { "roleArn": "string", "streamName": "string", "partitionKey": "string" }, "republish": { "roleArn": "string", "topic": "string" }, "s3": { "roleArn": "string", "bucketName": "string", "key": "string", "cannedAcl": "string" }, "firehose": { "roleArn": "string", "deliveryStreamName": "string", "separator": "string" }, "cloudwatchMetric": { "roleArn": "string", "metricNamespace": "string", "metricName": "string", "metricValue": "string", "metricUnit": "string", "metricTimestamp": "string" }, "cloudwatchAlarm": { "roleArn": "string", "alarmName": "string", "stateReason": "string", "stateValue": "string" }, "elasticsearch": { "roleArn": "string", "endpoint": "string", "index": "string", "type": "string", "id": "string" }, "salesforce": { "token": "string",

671


"url": "string" } } }}


名称类型描述

ruleName 字符串


模式：^[a-zA-Z0-9_]+$

规则的名称。

topicRulePayload TopicRulePayload 规则负载。

sql 字符串用于查询主题的 SQL 语句。有关更多信息，请参阅 AWS IoT 开发人员指南中的 AWS IoT SQL 参考。


操作列表

成员：Action


操作操作
















672




名称类型描述java 类：iot.goldeneye.service.DynamoKeyType














枚举：RAW | JSON





673





名称类型描述


useBase64 布尔值














cannedAcl 字符串







separator 字符串

pattern: ([ ])|( )|(,)



674




名称类型描述














endpoint 字符串







token 字符串

最小长度：40


url 字符串

最大长度：2000



675




名称类型描述

























676


名称类型描述











枚举：RAW | JSON






useBase64 布尔值







677





名称类型描述








cannedAcl 字符串







separator 字符串

pattern: ([ ])|( )|(,)










678





AWS IoT 开发人员指南SearchIndex

名称类型描述







endpoint 字符串







token 字符串

最小长度：40


url 字符串

最大长度：2000



输出:

无

SearchIndex查询搜索索引。

请求语法：

POST /indices/search

679

AWS IoT 开发人员指南SearchIndex


{ "indexName": "string", "queryString": "string", "nextToken": "string", "maxResults": "integer", "queryVersion": "string"}



indexName IndexName 否搜索索引名称。

queryString QueryString 是搜索查询字符串。


maxResults QueryMaxResults 否一次性返回的最大结果数。

queryVersion QueryVersion 否查询版本。

响应语法：


{ "nextToken": "string", "things": [ { "thingName": "string", "thingId": "string", "thingTypeName": "string", "thingGroupNames": [ "string" ], "attributes": { "string": "string" }, "shadow": "string" } ]}




things ThingDocumentList 否与查询搜索匹配的事物。

680


错误:













HTTP 响应代码：404InvalidQueryException

查询无效。

HTTP 响应代码：400IndexNotReadyException

索引未准备就绪。


CLI摘要:

aws iot search-index \ [--index-name <value>] \ --query-string <value> \ [--next-token <value>] \ [--max-results <value>] \ [--query-version <value>] \ [--cli-input-json <value>] \ [--generate-cli-skeleton]


{

681


"indexName": "string", "queryString": "string", "nextToken": "string", "maxResults": "integer", "queryVersion": "string"}


名称类型描述

indexName 字符串


模式：[a-zA-Z0-9:_-]+

搜索索引名称。

queryString 字符串


搜索查询字符串。


maxResults integer




queryVersion 字符串查询版本。

输出:

{ "nextToken": "string", "things": [ { "thingName": "string", "thingId": "string", "thingTypeName": "string", "thingGroupNames": [ "string" ], "attributes": { "string": "string" }, "shadow": "string" } ]}

cli 输出字段：

名称类型描述


things 列表与查询搜索匹配的事物。

682

AWS IoT 开发人员指南SetDefaultAuthorizer

名称类型描述成员：ThingDocument


ThingDocument ThingDocument

thingName 字符串


模式：[a-zA-Z0-9:_-]+

事物名称。

thingId 字符串事物 ID。



模式：[a-zA-Z0-9:_-]+

事物类型名称。

thingGroupNames 列表

成员：ThingGroupName


事物组名称。

ThingGroupName 字符串


模式：[a-zA-Z0-9:_-]+

个属性 map

键：AttributeName


属性。


最大长度：128

模式：[a-zA-Z0-9_.,@/:#-]+


最大长度：800

模式：[a-zA-Z0-9_.,@/:#-]*

shadow 字符串影子。

SetDefaultAuthorizer设置默认授权方。如果在没有指定授权方的情况下进行 websocket 连接，则将使用此项。

请求语法：

683

AWS IoT 开发人员指南SetDefaultAuthorizer

POST /default-authorizer Content-type: application/json





响应语法：





authorizerName AuthorizerName 否授权方名称。


错误:










684







CLI摘要:

aws iot set-default-authorizer \ --authorizer-name <value> \ [--cli-input-json <value>] \ [--generate-cli-skeleton]




名称类型描述



模式：[w=,@-]+

授权方名称。

输出:


cli 输出字段：

名称类型描述



模式：[w=,@-]+

授权方名称。


685

AWS IoT 开发人员指南SetDefaultPolicyVersion

SetDefaultPolicyVersion将指定策略的指定版本设置为策略的默认 (有效) 版本。此操作会影响策略附加到的所有证书。要列出策略附加到的所有委托人，请使用 ListPrincipalPolicy API。

请求语法：

PATCH /policies/policyName/version/policyVersionId

URI 请求参数：




错误:














CLI摘要:

686

AWS IoT 开发人员指南SetLoggingOptions

aws iot set-default-policy-version \ --policy-name <value> \ --policy-version-id <value> \ [--cli-input-json <value>] \ [--generate-cli-skeleton]




名称类型描述



模式：[w+=,.@-]+

策略名称。


模式：[0-9]+

策略版本 ID。

输出:

无

SetLoggingOptions设置日志记录选项。

请求语法：

POST /loggingOptions Content-type: application/json

{ "loggingOptionsPayload": { "roleArn": "string", "logLevel": "string" }}



loggingOptionsPayload LoggingOptionsPayload 是日志记录选项负载。

错误:

687


InternalException







CLI摘要:

aws iot set-logging-options \ --logging-options-payload <value> \ [--cli-input-json <value>] \ [--generate-cli-skeleton]


{ "loggingOptionsPayload": { "roleArn": "string", "logLevel": "string" }}


名称类型描述

loggingOptionsPayload LoggingOptionsPayload 日志记录选项负载。


logLevel 字符串



日志级别。

输出:

无

688

AWS IoT 开发人员指南SetV2LoggingLevel

SetV2LoggingLevel设置日志记录级别。

请求语法：

POST /v2LoggingLevel Content-type: application/json

{ "logTarget": { "targetType": "string", "targetName": "string" }, "logLevel": "string"}



logTarget LogTarget 是日志目标。

logLevel 日志级别是日志级别。

错误:

InternalException


HTTP 响应代码：500NotConfiguredException

未配置的资源。






CLI摘要:

aws iot set-v2-logging-level \ --log-target <value> \

689

AWS IoT 开发人员指南SetV2LoggingOptions

--log-level <value> \ [--cli-input-json <value>] \ [--generate-cli-skeleton]


{ "logTarget": { "targetType": "string", "targetName": "string" }, "logLevel": "string"}


名称类型描述

logTarget LogTarget 日志目标。




目标类型。

targetName 字符串目标名称。

logLevel 字符串



日志级别。

输出:

无

SetV2LoggingOptions为 V2 日志记录服务设置日志记录选项。

请求语法：

POST /v2LoggingOptions Content-type: application/json


690




roleArn AwsArn 否允许 IoT 写入Cloudwatch 日志的角色ARN。

defaultLogLevel 日志级别否默认日志记录级别。

disableAllLogs DisableAllLogs 否如果禁用所有日志，则设置为 true；否则设置为 false。

错误:

InternalException







CLI摘要:

aws iot set-v2-logging-options \ [--role-arn <value>] \ [--default-log-level <value>] \ [--disable-all-logs | --no-disable-all-logs] \ [--cli-input-json <value>] \ [--generate-cli-skeleton]




名称类型描述

roleArn 字符串允许 IoT 写入 Cloudwatch 日志的角色 ARN。

691

AWS IoT 开发人员指南StartNextPendingJobExecution

名称类型描述

defaultLogLevel 字符串



默认日志记录级别。

disableAllLogs 布尔值如果禁用所有日志，则设置为true；否则设置为 false。

输出:

无

StartNextPendingJobExecution获取并启动事物的下一个待处理 (状态 IN_PROGRESS 或 QUEUED) 任务执行。

请求语法：

PUT /things/thingName/jobs/$next Content-type: application/json

{ "statusDetails": { "string": "string" }}

URI 请求参数：


thingName ThingName 是与设备关联的事物的名称。



statusDetails DetailsMap 否描述任务执行状态的名称/值对的集合。如果未指定，则 statusDetails保持不变。

响应语法：


{

692


"execution": { "jobId": "string", "thingName": "string", "status": "string", "statusDetails": { "string": "string" }, "queuedAt": "long", "startedAt": "long", "lastUpdatedAt": "long", "versionNumber": "long", "executionNumber": "long", "jobDocument": "string" }}



execution JobExecution 否 JobExecution 对象。

错误:










证书无效。


CLI摘要:

aws iot-jobs-data start-next-pending-job-execution \

693


--thing-name <value> \ [--status-details <value>] \ [--cli-input-json <value>] \ [--generate-cli-skeleton]


{ "thingName": "string", "statusDetails": { "string": "string" }}


名称类型描述

thingName 字符串


模式：[a-zA-Z0-9:_-]+


statusDetails map

键：DetailsKey

值：DetailsValue

描述任务执行状态的名称/值对的集合。如果未指定，则statusDetails 保持不变。



模式：[a-zA-Z0-9:_-]+



模式：[^\\p{C}]*+

输出:


694


cli 输出字段：

名称类型描述

execution JobExecution JobExecution 对象。

jobId 字符串


模式：[a-zA-Z0-9_-]+


thingName 字符串


模式：[a-zA-Z0-9:_-]+


status 字符串




statusDetails map

键：DetailsKey

值：DetailsValue




模式：[a-zA-Z0-9:_-]+



模式：[^\\p{C}]*+


startedAt long








695

AWS IoT 开发人员指南StartThingRegistrationTask

名称类型描述




StartThingRegistrationTask创建批量事物预配置任务。

请求语法：

POST /thing-registration-tasks Content-type: application/json

{ "templateBody": "string", "inputFileBucket": "string", "inputFileKey": "string", "roleArn": "string"}



templateBody TemplateBody 是预配置模板。

inputFileBucket RegistryS3BucketName 是包含输入文件的 S3 存储桶。

inputFileKey RegistryS3KeyName 是 S3 存储桶中输入文件的名称。此文件包含以换行符分隔的 JSON 文件。每一行包含用于预配置一个设备 (事物) 的参数值。

roleArn RoleArn 是授予输入文件权限的IAM 角色 ARN。

响应语法：





taskId TaskId 否批量事物预配置任务ID。

696


错误:










CLI摘要:

aws iot start-thing-registration-task \ --template-body <value> \ --input-file-bucket <value> \ --input-file-key <value> \ --role-arn <value> \ [--cli-input-json <value>] \ [--generate-cli-skeleton]


{ "templateBody": "string", "inputFileBucket": "string", "inputFileKey": "string", "roleArn": "string"}


名称类型描述

templateBody 字符串预配置模板。

inputFileBucket 字符串


模式：[a-zA-Z0-9._-]+

包含输入文件的 S3 存储桶。

697

AWS IoT 开发人员指南StopThingRegistrationTask

名称类型描述

inputFileKey 字符串


模式：[a-zA-Z0-9!_.*'()-/]+

S3 存储桶中输入文件的名称。此文件包含以换行符分隔的 JSON文件。每一行包含用于预配置一个设备 (事物) 的参数值。

roleArn 字符串


授予输入文件权限的 IAM 角色ARN。

输出:


cli 输出字段：

名称类型描述

taskId 字符串

最大长度：40

批量事物预配置任务 ID。

StopThingRegistrationTask取消批量事物预配置任务。

请求语法：

PUT /thing-registration-tasks/taskId/cancel

URI 请求参数：


taskId TaskId 是批量事物预配置任务ID。

错误:





698









CLI摘要:

aws iot stop-thing-registration-task \ --task-id <value> \ [--cli-input-json <value>] \ [--generate-cli-skeleton]




名称类型描述

taskId 字符串

最大长度：40

批量事物预配置任务 ID。

输出:

无

TestAuthorization测试自定义授权。

请求语法：

POST /test-authorization?clientId=clientId

699

AWS IoT 开发人员指南TestAuthorization


{ "principal": "string", "cognitoIdentityPoolId": "string", "authInfos": [ { "actionType": "string", "resources": [ "string" ] } ], "policyNamesToAdd": [ "string" ], "policyNamesToSkip": [ "string" ]}

URI 请求参数：


clientId ClientId 否 MQTT 客户端 ID。



principal 委托人否委托人。

cognitoIdentityPoolId CognitoIdentityPoolId 否 Cognito 身份池 ID。

authInfos AuthInfos 是授权信息对象的列表。模拟授权将为列表中的各个 authInfo 对象创建响应。

policyNamesToAdd PolicyNames 否测试自定义授权时，此处指定的策略将被视为已附加到要授权的委托人。

policyNamesToSkip PolicyNames 否测试自定义授权时，此处指定的策略将被视为没有附加到要授权的委托人。

响应语法：


{ "authResults": [ { "authInfo": {

700

AWS IoT 开发人员指南TestAuthorization

"actionType": "string", "resources": [ "string" ] }, "allowed": { "policies": [ { "policyName": "string", "policyArn": "string" } ] }, "denied": { "implicitDeny": { "policies": [ { "policyName": "string", "policyArn": "string" } ] }, "explicitDeny": { "policies": [ { "policyName": "string", "policyArn": "string" } ] } }, "authDecision": "string", "missingContextValues": [ "string" ] } ]}



authResults AuthResults 否身份验证结果。

错误:







701











CLI摘要:

aws iot test-authorization \ [--principal <value>] \ [--cognito-identity-pool-id <value>] \ --auth-infos <value> \ [--client-id <value>] \ [--policy-names-to-add <value>] \ [--policy-names-to-skip <value>] \ [--cli-input-json <value>] \ [--generate-cli-skeleton]


{ "principal": "string", "cognitoIdentityPoolId": "string", "authInfos": [ { "actionType": "string", "resources": [ "string" ] } ], "clientId": "string", "policyNamesToAdd": [ "string" ], "policyNamesToSkip": [ "string" ]}

702



名称类型描述


cognitoIdentityPoolId 字符串 Cognito 身份池 ID。

authInfos 列表

成员：AuthInfo

授权信息对象的列表。模拟授权将为列表中的各个 authInfo 对象创建响应。

AuthInfo AuthInfo

actionType 字符串

枚举：PUBLISH | SUBSCRIBE |RECEIVE | CONNECT

java 类：com.amazonaws.iot.identity.enums.ActionType

向委托人授权的操作的类型。

resources 列表

成员：Resource

授权委托人执行指定操作的资源。

资源字符串

clientId 字符串 MQTT 客户端 ID。

policyNamesToAdd 列表

成员：PolicyName


测试自定义授权时，此处指定的策略将被视为已附加到要授权的委托人。

PolicyName 字符串


模式：[w+=,.@-]+

policyNamesToSkip 列表

成员：PolicyName


测试自定义授权时，此处指定的策略将被视为没有附加到要授权的委托人。

PolicyName 字符串


模式：[w+=,.@-]+

输出:

{ "authResults": [ { "authInfo": { "actionType": "string",

703


"resources": [ "string" ] }, "allowed": { "policies": [ { "policyName": "string", "policyArn": "string" } ] }, "denied": { "implicitDeny": { "policies": [ { "policyName": "string", "policyArn": "string" } ] }, "explicitDeny": { "policies": [ { "policyName": "string", "policyArn": "string" } ] } }, "authDecision": "string", "missingContextValues": [ "string" ] } ]}

cli 输出字段：

名称类型描述

authResults 列表

成员：AuthResult

身份验证结果。

AuthResult AuthResult

authInfo AuthInfo 授权信息。

actionType 字符串

枚举：PUBLISH | SUBSCRIBE |RECEIVE | CONNECT

java 类：com.amazonaws.iot.identity.enums.ActionType

向委托人授权的操作的类型。

resources 列表

成员：Resource

授权委托人执行指定操作的资源。

资源字符串

704


名称类型描述

已允许已允许允许指定操作的策略和语句。

策略列表

成员：Policy


允许身份验证的策略的列表。

策略策略



模式：[w+=,.@-]+

策略名称。


denied Denied 拒绝指定操作的策略和语句。

implicitDeny ImplicitDeny 隐式拒绝授权的信息。当策略没有明确拒绝或允许资源上的操作时，将其视为隐式拒绝。

策略列表

成员：Policy


对指定资源上的指定操作不包含匹配的允许或拒绝语句的策略。

策略策略



模式：[w+=,.@-]+

策略名称。


explicitDeny ExplicitDeny 明确拒绝授权的信息。

策略列表

成员：Policy


拒绝授权的策略。

策略策略



模式：[w+=,.@-]+

策略名称。


705

AWS IoT 开发人员指南TestInvokeAuthorizer

名称类型描述

authDecision 字符串

枚举：ALLOWED |EXPLICIT_DENY |IMPLICIT_DENY

java 类：com.amazonaws.iot.identity.enums.AuthDecision

此场景的最终授权决定。确定授权决定时要考虑到多个语句。明确拒绝语句可以覆盖多个允许语句。

missingContextValues 列表

成员：MissingContextValue


包含在评估策略时缺少的任何上下文值。

MissingContextValue 字符串

TestInvokeAuthorizer调用指定的自定义授权方以用于测试目的。

请求语法：

POST /authorizer/authorizerName/test Content-type: application/json

{ "token": "string", "tokenSignature": "string"}

URI 请求参数：


authorizerName AuthorizerName 是自定义授权方名称。



token Token 是您的自定义身份验证服务返回的令牌。

tokenSignature TokenSignature 是由令牌以及您的自定义身份验证服务的私有密钥构成的签名。

响应语法：


706

AWS IoT 开发人员指南TestInvokeAuthorizer

{ "isAuthenticated": "boolean", "principalId": "string", "policyDocuments": [ "string" ], "refreshAfterInSeconds": "integer", "disconnectAfterInSeconds": "integer"}



isAuthenticated IsAuthenticated 否如果令牌已通过身份验证，则为 True；否则为False。

principalId 委托人 ID 否委托人 ID。

policyDocuments PolicyDocuments 否 IAM 策略文档。

refreshAfterInSeconds Seconds 否秒数，在此之后刷新临时凭证。

disconnectAfterInSeconds Seconds 否秒数，在此之后终止连接。

错误:













707


HTTP 响应代码：500InvalidResponseException

响应无效。


CLI摘要:

aws iot test-invoke-authorizer \ --authorizer-name <value> \ --token <value> \ --token-signature <value> \ [--cli-input-json <value>] \ [--generate-cli-skeleton]


{ "authorizerName": "string", "token": "string", "tokenSignature": "string"}


名称类型描述



模式：[w=,@-]+

自定义授权方名称。

token 字符串


您的自定义身份验证服务返回的令牌。

tokenSignature 字符串


模式：[A-Za-z0-9+/]+={0,2}

由令牌以及您的自定义身份验证服务的私有密钥构成的签名。

输出:

{ "isAuthenticated": "boolean", "principalId": "string", "policyDocuments": [ "string" ], "refreshAfterInSeconds": "integer", "disconnectAfterInSeconds": "integer"}

708

AWS IoT 开发人员指南TransferCertificate

cli 输出字段：

名称类型描述

isAuthenticated 布尔值


如果令牌已通过身份验证，则为True；否则为 False。

principalId 字符串


模式：[a-zA-Z0-9]+

委托人 ID。

policyDocuments 列表

成员：PolicyDocument

IAM 策略文档。

PolicyDocument 字符串

refreshAfterInSeconds integer


秒数，在此之后刷新临时凭证。

disconnectAfterInSeconds integer


秒数，在此之后终止连接。

TransferCertificate将指定证书传输到指定 AWS 账户。

在接收方确认之前，您可以取消传输。

系统不向传输目标的账户发送任何通知，而是由调用方通知传输目标。

所传输的证书不能处于 ACTIVE 状态。您可以使用 UpdateCertificate API 来停用它。

该证书不能附加有任何策略。您可以使用 DetachPrincipalPolicy API 来分离它们。

请求语法：

PATCH /transfer-certificate/certificateId?targetAwsAccount=targetAwsAccount Content-type: application/json

{ "transferMessage": "string"}

URI 请求参数：



targetAwsAccount AwsAccountId 是 AWS 账户。

709

AWS IoT 开发人员指南TransferCertificate



transferMessage Message 否传输消息。

响应语法：


{ "transferredCertificateArn": "string"}



transferredCertificateArn CertificateArn 否证书的 ARN。

错误:







HTTP 响应代码：406TransferConflictException

由于仍附加有授权策略，您无法传输证书。







710





CLI摘要:

aws iot transfer-certificate \ --certificate-id <value> \ --target-aws-account <value> \ [--transfer-message <value>] \ [--cli-input-json <value>] \ [--generate-cli-skeleton]


{ "certificateId": "string", "targetAwsAccount": "string", "transferMessage": "string"}


名称类型描述



模式：(0x)?[a-fA-F0-9]+


targetAwsAccount 字符串

模式：[0-9]{12}

AWS 账户。


最大长度：128

传输消息。

输出:

{ "transferredCertificateArn": "string"}

cli 输出字段：

名称类型描述

transferredCertificateArn 字符串证书的 ARN。

711

AWS IoT 开发人员指南UpdateAuthorizer

UpdateAuthorizer更新授权方。

请求语法：

PUT /authorizer/authorizerName Content-type: application/json

{ "authorizerFunctionArn": "string", "tokenKeyName": "string", "tokenSigningPublicKeys": { "string": "string" }, "status": "string"}

URI 请求参数：





authorizerFunctionArn AuthorizerFunctionArn 否授权方 Lambda 函数的ARN。

tokenKeyName TokenKeyName 否用于从 HTTP 标头提取令牌的键。

tokenSigningPublicKeys PublicKeyMap 否用于验证令牌签名的公有密钥。

status AuthorizerStatus 否更新授权方请求的状态。

响应语法：





authorizerName AuthorizerName 否授权方名称。

712




错误:
















CLI摘要:

aws iot update-authorizer \ --authorizer-name <value> \ [--authorizer-function-arn <value>] \ [--token-key-name <value>] \ [--token-signing-public-keys <value>] \ [--status <value>] \ [--cli-input-json <value>] \

713




{ "authorizerName": "string", "authorizerFunctionArn": "string", "tokenKeyName": "string", "tokenSigningPublicKeys": { "string": "string" }, "status": "string"}


名称类型描述



模式：[w=,@-]+

授权方名称。

authorizerFunctionArn 字符串授权方 Lambda 函数的 ARN。



模式：[a-zA-Z0-9_-]+



键：KeyName

值：KeyValue

用于验证令牌签名的公有密钥。

KeyName 字符串


模式：[a-zA-Z0-9:_-]+

KeyValue 字符串

最大长度：5120

status 字符串



更新授权方请求的状态。

输出:

{ "authorizerName": "string", "authorizerArn": "string"

714

AWS IoT 开发人员指南UpdateCACertificate

}

cli 输出字段：

名称类型描述



模式：[w=,@-]+

授权方名称。


UpdateCACertificate更新已注册的 CA 证书。

请求语法：

PUT /cacertificate/caCertificateId?newStatus=newStatus&newAutoRegistrationStatus=newAutoRegistrationStatus Content-type: application/json

{ "registrationConfig": { "templateBody": "string", "roleArn": "string" }, "removeAutoRegistration": "boolean"}

URI 请求参数：


certificateId CertificateId 是 CA 证书标识符。

newStatus CACertificateStatus 否 CA 证书更新后的状态。

注意：状态值REGISTER_INACTIVE已弃用，不应再使用。

newAutoRegistrationStatusAutoRegistrationStatus 否自动注册状态的新值。有效值为：“ENABLE”或“DISABLE”。




removeAutoRegistration RemoveAutoRegistration 否如果为 true，则删除自动注册。

715


错误:














CLI摘要:

aws iot update-ca-certificate \ --certificate-id <value> \ [--new-status <value>] \ [--new-auto-registration-status <value>] \ [--registration-config <value>] \ [--remove-auto-registration | --no-remove-auto-registration] \ [--cli-input-json <value>] \ [--generate-cli-skeleton]


{ "certificateId": "string", "newStatus": "string", "newAutoRegistrationStatus": "string", "registrationConfig": { "templateBody": "string", "roleArn": "string" }, "removeAutoRegistration": "boolean"}

716

AWS IoT 开发人员指南UpdateCertificate


名称类型描述



模式：(0x)?[a-fA-F0-9]+


newStatus 字符串



CA 证书更新后的状态。

注意：状态值REGISTER_INACTIVE 已弃用，不应再使用。

newAutoRegistrationStatus 字符串

枚举：ENABLE | DISABLE

java 类：iot.identity.service.AutoRegistrationStatus

自动注册状态的新值。有效值为：“ENABLE”或“DISABLE”。



roleArn 字符串


角色的 ARN。

removeAutoRegistration 布尔值如果为 true，则删除自动注册。

输出:

无

UpdateCertificate更新指定证书的状态。此操作是幂等的。

将证书移出 ACTIVE 状态 (包括 REVOKED) 不会断开当前连接的设备，但这些设备将无法重新连接。

使用证书对连接到 AWS IoT 的设备进行身份验证时，证书必须为 ACTIVE 状态。

请求语法：

PUT /certificates/certificateId?newStatus=newStatus

URI 请求参数：



717



newStatus CertificateStatus 是新的状态。

注意：将状态设置为PENDING_TRANSFER将导致引发异常。PENDING_TRANSFER是由 AWS IoT 内部使用的状态。它不提供给开发人员使用。

注意：状态值REGISTER_INACTIVE已弃用，不应再使用。

错误:
















CLI摘要:

718

AWS IoT 开发人员指南UpdateEventConfigurations

aws iot update-certificate \ --certificate-id <value> \ --new-status <value> \ [--cli-input-json <value>] \ [--generate-cli-skeleton]


{ "certificateId": "string", "newStatus": "string"}


名称类型描述



模式：(0x)?[a-fA-F0-9]+


newStatus 字符串



新的状态。

注意：将状态设置为PENDING_TRANSFER 将导致引发异常。PENDING_TRANSFER是由 AWS IoT 内部使用的状态。它不提供给开发人员使用。

注意：状态值REGISTER_INACTIVE 已弃用，不应再使用。

输出:

无

UpdateEventConfigurations更新事件配置。

请求语法：

PATCH /event-configurations Content-type: application/json

{ "eventConfigurations": { "string": { "Enabled": "boolean" } }}

719




eventConfigurations EventConfigurations 否新事件配置值。

错误:








CLI摘要:

aws iot update-event-configurations \ [--event-configurations <value>] \ [--cli-input-json <value>] \ [--generate-cli-skeleton]


{ "eventConfigurations": { "string": { "Enabled": "boolean" } }}


名称类型描述

eventConfigurations map

键：EventType

值：Configuration

新事件配置值。

EventType 字符串

720

AWS IoT 开发人员指南UpdateIndexingConfiguration

名称类型描述枚举：THING | THING_GROUP| THING_TYPE |THING_GROUP_MEMBERSHIP| THING_GROUP_HIERARCHY| THING_TYPE_ASSOCIATION |JOB | JOB_EXECUTION

java 类：com.amazonaws.iot.common.types.enums.EventType

配置配置

启用布尔值为 True 时启用配置。

输出:

无

UpdateIndexingConfiguration更新搜索配置。

请求语法：

POST /indexing/config Content-type: application/json




thingIndexingConfigurationThingIndexingConfiguration否事物索引配置。

错误:







721







CLI摘要:

aws iot update-indexing-configuration \ [--thing-indexing-configuration <value>] \ [--cli-input-json <value>] \ [--generate-cli-skeleton]




名称类型描述

thingIndexingConfiguration ThingIndexingConfiguration 事物索引配置。

thingIndexingMode 字符串

枚举：OFF | REGISTRY |REGISTRY_AND_SHADOW

java 类：com.amazonaws.iot.indexing.ThingIndexingMode

事物索引模式。有效值为：

• REGISTRY - 您的事物索引将只包含注册表数据。

• REGISTRY_AND_SHADOW -您的事物索引将包含注册表数据和影子数据。

• OFF - 事物索引已禁用。

输出:

无

UpdateJobExecution更新任务执行的状态。

请求语法：

POST /things/thingName/jobs/jobId

722

AWS IoT 开发人员指南UpdateJobExecution


{ "status": "string", "statusDetails": { "string": "string" }, "expectedVersion": "long", "includeJobExecutionState": "boolean", "includeJobDocument": "boolean", "executionNumber": "long"}

URI 请求参数：


jobId JobId 是创建此任务时向其分配的唯一标识符。

thingName ThingName 是与设备关联的事物的名称。



status JobExecutionStatus 是任务执行的新状态(IN_PROGRESS、FAILED、SUCCESS或 REJECTED)。这必须在每次更新时指定。

statusDetails DetailsMap 否可选。描述任务执行状态的名称/值对的集合。如果未指定，则statusDetails 保持不变。

expectedVersion ExpectedVersion 否可选。任务执行的预期当前版本。每次更新任务执行时，其版本将递增。如果存储在 Jobs 中的任务执行版本不匹配，则更新将被拒绝并出现VersionMismatch 错误，并且将返回包含当前任务执行状态数据的ErrorResponse。(这样就不再需要执行单独的DescribeJobExecution请求来获取任务执行状态数据。)

includeJobExecutionState IncludeExecutionState 否可选。包括此项并设置为 true 时，响应将包含JobExecutionState 数据。默认为 false。

723

AWS IoT 开发人员指南UpdateJobExecution


includeJobDocument IncludeJobDocument 否可选。设置为 true 时，响应将包含任务文档。默认为 false。

executionNumber ExecutionNumber 否可选。标识特定设备上的特定任务执行的数字。

响应语法：


{ "executionState": { "status": "string", "statusDetails": { "string": "string" }, "versionNumber": "long" }, "jobDocument": "string"}



executionState JobExecutionState 否 JobExecutionState 对象。

jobDocument JobDocument 否任务文档的内容。

错误:









724



证书无效。

HTTP 响应代码：400InvalidStateTransitionException

更新尝试将任务执行更改为某个状态，但该状态由于任务执行的当前状态而无效 (例如，尝试将处于 SUCCESS 状态的请求更改为 IN_PROGRESS 状态)。在这种情况下，错误消息的正文还包含executionState 字段。


CLI摘要:

aws iot-jobs-data update-job-execution \ --job-id <value> \ --thing-name <value> \ --status <value> \ [--status-details <value>] \ [--expected-version <value>] \ [--include-job-execution-state | --no-include-job-execution-state] \ [--include-job-document | --no-include-job-document] \ [--execution-number <value>] \ [--cli-input-json <value>] \ [--generate-cli-skeleton]


{ "jobId": "string", "thingName": "string", "status": "string", "statusDetails": { "string": "string" }, "expectedVersion": "long", "includeJobExecutionState": "boolean", "includeJobDocument": "boolean", "executionNumber": "long"}


名称类型描述

jobId 字符串


模式：[a-zA-Z0-9_-]+


thingName 字符串



725


名称类型描述模式：[a-zA-Z0-9:_-]+

status 字符串



任务执行的新状态(IN_PROGRESS、FAILED、SUCCESS或 REJECTED)。这必须在每次更新时指定。

statusDetails map

键：DetailsKey

值：DetailsValue

可选。描述任务执行状态的名称/值对的集合。如果未指定，则statusDetails 保持不变。



模式：[a-zA-Z0-9:_-]+



模式：[^\\p{C}]*+



可选。任务执行的预期当前版本。每次更新任务执行时，其版本将递增。如果存储在Jobs 中的任务执行版本不匹配，则更新将被拒绝并出现VersionMismatch 错误，并且将返回包含当前任务执行状态数据的 ErrorResponse。(这样就不再需要执行单独的DescribeJobExecution 请求来获取任务执行状态数据。)

includeJobExecutionState 布尔值


可选。包括此项并设置为 true 时，响应将包含JobExecutionState 数据。默认为false。







输出:

{

726

AWS IoT 开发人员指南UpdateRoleAlias

"executionState": { "status": "string", "statusDetails": { "string": "string" }, "versionNumber": "long" }, "jobDocument": "string"}

cli 输出字段：

名称类型描述

executionState JobExecutionState JobExecutionState 对象。

status 字符串




statusDetails map

键：DetailsKey

值：DetailsValue




模式：[a-zA-Z0-9:_-]+



模式：[^\\p{C}]*+





UpdateRoleAlias更新角色别名。

请求语法：

PUT /role-aliases/roleAlias Content-type: application/json

727

AWS IoT 开发人员指南UpdateRoleAlias

{ "roleArn": "string", "credentialDurationSeconds": "integer"}

URI 请求参数：


roleAlias RoleAlias 是要更新的角色别名。



roleArn RoleArn 否角色 ARN。

credentialDurationSecondsCredentialDurationSeconds否凭证有效的秒数。

响应语法：


{ "roleAlias": "string", "roleAliasArn": "string"}



roleAlias RoleAlias 否角色别名。

roleAliasArn RoleAliasArn 否角色别名 ARN。

错误:









728







CLI摘要:

aws iot update-role-alias \ --role-alias <value> \ [--role-arn <value>] \ [--credential-duration-seconds <value>] \ [--cli-input-json <value>] \ [--generate-cli-skeleton]


{ "roleAlias": "string", "roleArn": "string", "credentialDurationSeconds": "integer"}


名称类型描述

roleAlias 字符串


模式：[w=,@-]+

要更新的角色别名。

roleArn 字符串


角色 ARN。



范围 – 最大值：3600，最小值：900

凭证有效的秒数。

输出:

{ "roleAlias": "string", "roleAliasArn": "string"

729

AWS IoT 开发人员指南UpdateStream

}

cli 输出字段：

名称类型描述

roleAlias 字符串


模式：[w=,@-]+

角色别名。

roleAliasArn 字符串角色别名 ARN。

UpdateStream更新现有的流。流版本将递增 1。

请求语法：

PUT /streams/streamId Content-type: application/json

{ "description": "string", "files": [ { "fileId": "integer", "s3Location": { "bucket": "string", "key": "string", "version": "string" } } ], "roleArn": "string"}

URI 请求参数：






files StreamFiles 否与流关联的文件。

roleArn RoleArn 否一个 IAM 角色，IoT 服务委托人可以代入该角色以访问您的 S3 文件。

响应语法：

730






streamId StreamId 否流 ID。

streamArn StreamArn 否流 ARN。


streamVersion StreamVersion 否流版本。

错误:














CLI摘要:

731


aws iot update-stream \ --stream-id <value> \ [--description <value>] \ [--files <value>] \ [--role-arn <value>] \ [--cli-input-json <value>] \ [--generate-cli-skeleton]


{ "streamId": "string", "description": "string", "files": [ { "fileId": "integer", "s3Location": { "bucket": "string", "key": "string", "version": "string" } } ], "roleArn": "string"}


名称类型描述

streamId 字符串


模式：[a-zA-Z0-9_-]+

流 ID。


最大长度：2028

模式：[^\\p{C}]+

流的描述。

files 列表

成员：StreamFile

与流关联的文件。


fileId integer



文件 ID。


bucket 字符串

最小长度：1


key 字符串 S3 存储桶中要流式处理的文件的名称。

732

AWS IoT 开发人员指南UpdateThing

名称类型描述最小长度：1


roleArn 字符串


一个 IAM 角色，IoT 服务委托人可以代入该角色以访问您的 S3 文件。

输出:


cli 输出字段：

名称类型描述

streamId 字符串


模式：[a-zA-Z0-9_-]+

流 ID。



最大长度：2028

模式：[^\\p{C}]+

流的描述。




流版本。

UpdateThing更新事物的数据。

请求语法：

PATCH /things/thingName Content-type: application/json

{ "thingTypeName": "string", "attributePayload": { "attributes": {

733

AWS IoT 开发人员指南UpdateThing

"string": "string" }, "merge": "boolean" }, "expectedVersion": "long", "removeThingType": "boolean"}

URI 请求参数：


thingName ThingName 是要更新的事物的名称。




attributePayload AttributePayload 否事物属性的列表，采用包含名称/值对的 JSON字符串形式。例如：

\"attributes\":{\"name1\":\"value2\"}

此数据用于添加新属性或更新现有属性。

expectedVersion OptionalVersion 否注册表中预期的事物记录的版本。如果注册表中记录的版本与请求中指定的预期版本不匹配，则使用VersionConflictException拒绝 UpdateThing 请求。

removeThingType RemoveThingType 否删除事物类型关联。如果为 true，则删除关联。

错误:






734


ThrottlingException











CLI摘要:

aws iot update-thing \ --thing-name <value> \ [--thing-type-name <value>] \ [--attribute-payload <value>] \ [--expected-version <value>] \ [--remove-thing-type | --no-remove-thing-type] \ [--cli-input-json <value>] \ [--generate-cli-skeleton]


{ "thingName": "string", "thingTypeName": "string", "attributePayload": { "attributes": { "string": "string" }, "merge": "boolean" }, "expectedVersion": "long", "removeThingType": "boolean"}


名称类型描述

thingName 字符串要更新的事物的名称。

735



模式：[a-zA-Z0-9:_-]+



模式：[a-zA-Z0-9:_-]+


attributePayload AttributePayload 事物属性的列表，采用包含名称/值对的 JSON 字符串形式。例如：

\"attributes\":{\"name1\":\"value2\"}

此数据用于添加新属性或更新现有属性。

个属性 map

键：AttributeName





最大长度：128

模式：[a-zA-Z0-9_.,@/:#-]+


最大长度：800

模式：[a-zA-Z0-9_.,@/:#-]*



Note




注册表中预期的事物记录的版本。如果注册表中记录的版本与请求中指定的预期版本不匹配，则使用VersionConflictException拒绝 UpdateThing 请求。

736

AWS IoT 开发人员指南UpdateThingGroup

名称类型描述

removeThingType 布尔值删除事物类型关联。如果为true，则删除关联。

输出:

无

UpdateThingGroup更新事物组。

请求语法：

PATCH /thing-groups/thingGroupName Content-type: application/json

{ "thingGroupProperties": { "thingGroupDescription": "string", "attributePayload": { "attributes": { "string": "string" }, "merge": "boolean" } }, "expectedVersion": "long"}

URI 请求参数：


thingGroupName ThingGroupName 是要更新的事物组。



thingGroupProperties ThingGroupProperties 是事物组属性。

expectedVersion OptionalVersion 否事物组的预期版本。如果这与所更新的事物组的版本不匹配，更新将失败。

响应语法：


{

737


"version": "long"}


名称类型请求？说明

版本版本否已更新事物组的版本。

错误:












CLI摘要:

aws iot update-thing-group \ --thing-group-name <value> \ --thing-group-properties <value> \ [--expected-version <value>] \ [--cli-input-json <value>] \ [--generate-cli-skeleton]


{ "thingGroupName": "string", "thingGroupProperties": { "thingGroupDescription": "string",

738


"attributePayload": { "attributes": { "string": "string" }, "merge": "boolean" } }, "expectedVersion": "long"}


名称类型描述



模式：[a-zA-Z0-9:_-]+

要更新的事物组。



最大长度：2028




个属性 map

键：AttributeName





最大长度：128

模式：[a-zA-Z0-9_.,@/:#-]+


最大长度：800

模式：[a-zA-Z0-9_.,@/:#-]*



Note


739

AWS IoT 开发人员指南UpdateThingGroupsForThing

名称类型描述



事物组的预期版本。如果这与所更新的事物组的版本不匹配，更新将失败。

输出:

{ "version": "long"}

cli 输出字段：

名称类型描述

版本 long 已更新事物组的版本。

UpdateThingGroupsForThing更新事物所属的组。

请求语法：

PUT /thing-groups/updateThingGroupsForThing Content-type: application/json

{ "thingName": "string", "thingGroupsToAdd": [ "string" ], "thingGroupsToRemove": [ "string" ]}



thingName ThingName 否将更新其组成员资格的事物。

thingGroupsToAdd ThingGroupList 否将添加事物的组。

thingGroupsToRemove ThingGroupList 否将从中删除事物的组。

错误:



740









CLI摘要:

aws iot update-thing-groups-for-thing \ [--thing-name <value>] \ [--thing-groups-to-add <value>] \ [--thing-groups-to-remove <value>] \ [--cli-input-json <value>] \ [--generate-cli-skeleton]


{ "thingName": "string", "thingGroupsToAdd": [ "string" ], "thingGroupsToRemove": [ "string" ]}


名称类型描述

thingName 字符串


模式：[a-zA-Z0-9:_-]+

将更新其组成员资格的事物。

thingGroupsToAdd 列表


将添加事物的组。



模式：[a-zA-Z0-9:_-]+

741

AWS IoT 开发人员指南UpdateThingShadow

名称类型描述

thingGroupsToRemove 列表


将从中删除事物的组。



模式：[a-zA-Z0-9:_-]+

输出:

无

UpdateThingShadow更新指定事物的影子。

有关更多信息，请参阅《AWS IoT 开发人员指南》中的 UpdateThingShadow。

请求语法：

POST /things/thingName/shadow Content-type: application/json


URI 请求参数：





payload JsonDocument 是状态信息，采用 JSON格式。

响应语法：



742

http://docs.aws.amazon.com/iot/latest/developerguide/API_UpdateThingShadow.html

AWS IoT 开发人员指南UpdateThingShadow



payload JsonDocument 否状态信息，采用 JSON格式。

错误:

ConflictException

指定的版本与文档的版本不匹配。

HTTP 响应代码：409RequestEntityTooLargeException

有效负载超出允许的最大值.
















743


CLI摘要:

aws iot-data update-thing-shadow \ --thing-name <value> \ --payload <value> \ [--cli-input-json <value>] \ [--generate-cli-skeleton]


{ "thingName": "string", "payload": "blob"}


名称类型描述

thingName 字符串


模式：[a-zA-Z0-9:_-]+

事物的名称。


输出:


cli 输出字段：

名称类型描述


744

aws iot - 开发人员指南 · pdf fileaws iot 开发人员指南 创建 aws iot 规则

Documents

aws iot - 开发人员指南 · pdf fileaws iot 开发人员指南创建 aws iot 规则