As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.
# Regras para AWS IoT
As regras permitem que seus dispositivos interajam com Serviços da AWS. As regras são analisadas e as ações são realizadas com base no fluxo de tópicos do MQTT. Você pode usar as regras para dar suporte a tarefas como estas:
+ Aumentar ou filtrar os dados recebidos de um dispositivo.
+ Gravar os dados recebidos de um dispositivo em um banco de dados do Amazon DynamoDB.
+ Salvar um arquivo no Amazon S3.
+ Enviar uma notificação por push para todos os usuários usando o Amazon SNS.
+ Publicar dados em uma fila do Amazon SQS.
+ Invocar uma função do Lambda para extrair dados.
+ Processar mensagens de um grande número de dispositivos usando o Amazon Kinesis.
+ Envie dados para o Amazon OpenSearch Service.
+ Capture uma CloudWatch métrica.
+ Troque um CloudWatch alarme.
+ Envie os dados de uma mensagem MQTT para a Amazon SageMaker AI para fazer previsões com base em um modelo de aprendizado de máquina (ML).
+ Enviar uma mensagem para o fluxo de entrada da Salesforce IoT.
+ Iniciar a execução de uma máquina de estado do Step Functions. Iniciar o processo de uma máquina de estados do Step Functions.
+ Envie dados da mensagem para uma AWS IoT Events entrada.
+ Enviar dados de mensagem para uma propriedade de ativo em AWS IoT SiteWise.
+ Enviar dados de mensagens para um serviço ou aplicativo da web.
Suas regras podem usar mensagens MQTT que passam pelo publish/subscribe protocolo suportado pelo[Protocolos de comunicação do dispositivo](protocols.md). [Você também pode usar o recurso [Basic Ingest](iot-basic-ingest.md) para enviar com segurança os dados do dispositivo para os Serviços da AWS listados anteriormente, sem incorrer em custos de mensagens.](https://aws.amazon.com/iot-core/pricing/) O recurso [Basic Ingest](iot-basic-ingest.md) otimiza o fluxo de dados removendo o agente de publish/subscribe mensagens do caminho de ingestão. Isso o torna econômico e, ao mesmo tempo, mantém os recursos de segurança e processamento de dados do AWS IoT.
Antes de AWS IoT poder realizar essas ações, você deve conceder permissão para que ele acesse seus AWS recursos em seu nome. Quando as ações são executadas, você incorre nas cobranças padrão do Serviços da AWS que você usa.
**Topics**
+ [Conceder a uma AWS IoT regra o acesso que ela exige](iot-create-role.md)
+ [Transmitir as permissões de função](pass-role.md)
+ [Criação de uma AWS IoT regra](iot-create-rule.md)
+ [Gerenciando uma AWS IoT regra](iot-managae-rule.md)
+ [AWS IoT ações de regras](iot-rule-actions.md)
+ [Solucionar problemas de uma regra](#iot-troubleshoot-rule)
+ [Acessando recursos entre contas usando regras AWS IoT](accessing-cross-account-resources-using-rules.md)
+ [Tratamento de erros (ação de erro)](rule-error-handling.md)
+ [Reduzir custos do sistema de mensagens com Ingestão básica](iot-basic-ingest.md)
+ [AWS IoT Referência SQL](iot-sql-reference.md)
# Conceder a uma AWS IoT regra o acesso que ela exige
Use as funções do IAM para controlar os AWS recursos aos quais cada regra tem acesso. Antes de criar uma regra, você deve criar uma função do IAM com uma política que permita o acesso aos AWS recursos necessários. AWS IoT assume essa função ao implementar uma regra.
**Conclua as etapas a seguir para criar a função e a AWS IoT política do IAM que concedem a uma AWS IoT regra o acesso necessário (AWS CLI).**
1. Salve o seguinte documento de política de confiança, que concede AWS IoT permissão para assumir a função, em um arquivo chamado`iot-role-trust.json`.
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Service": "iot.amazonaws.com"
},
"Action": "sts:AssumeRole",
"Condition": {
"StringEquals": {
"aws:SourceAccount": "123456789012"
},
"ArnLike": {
"aws:SourceArn": "arn:aws:iot:us-east-1:123456789012:rule/rulename"
}
}
}
]
}
```
Use o comando [criar-função](https://docs.aws.amazon.com/cli/latest/reference/iam/create-role.html) para criar um perfil do IAM especificando o arquivo `iot-role-trust.json`:
```
aws iam create-role --role-name my-iot-role --assume-role-policy-document file://iot-role-trust.json
```
A saída desse comando é semelhante à seguinte:
```
{
"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"
}
}
```
1. Salve o seguinte JSON em um arquivo chamado `my-iot-policy.json`.
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "dynamodb:*",
"Resource": "*"
}
]
}
```
Esse JSON é um exemplo de documento de política que concede acesso de AWS IoT administrador ao DynamoDB.
Use o comando [create-policy](https://docs.aws.amazon.com/cli/latest/reference/iam/create-policy.html) para conceder AWS IoT acesso aos seus AWS recursos ao assumir a função, transmitindo o arquivo: `my-iot-policy.json`
```
aws iam create-policy --policy-name my-iot-policy --policy-document file://my-iot-policy.json
```
Para obter mais informações sobre como conceder acesso às Serviços da AWS políticas do AWS IoT, consulte[Criação de uma AWS IoT regra](iot-create-rule.md).
A saída do comando [criar-política](https://docs.aws.amazon.com/cli/latest/reference/iam/create-policy.html) contém o ARN da política. Anexar uma política a uma função.
```
{
"Policy": {
"PolicyName": "my-iot-policy",
"CreateDate": "2015-09-30T19:31:18.620Z",
"AttachmentCount": 0,
"IsAttachable": true,
"PolicyId": "ZXR6A36LTYANPAI7NJ5UV",
"DefaultVersionId": "v1",
"Path": "/",
"Arn": "arn:aws:iam::123456789012:policy/my-iot-policy",
"UpdateDate": "2015-09-30T19:31:18.620Z"
}
}
```
1. Use o [attach-role-policy](https://docs.aws.amazon.com/cli/latest/reference/iam/attach-role-policy.html)comando para anexar sua política à sua função:
```
aws iam attach-role-policy --role-name my-iot-role --policy-arn "arn:aws:iam::123456789012:policy/my-iot-policy"
```
## Revogar o acesso ao mecanismo de regras
Para revogar imediatamente o acesso ao mecanismo de regras, faça o seguinte:
1. Remova iot.amazonaws.com da [política de confiança](https://docs.aws.amazon.com/iot/latest/developerguide/iot-create-role.html).
1. Siga as etapas para [revogar as sessões do perfil de IoT](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use_revoke-sessions.html).
# Transmitir as permissões de função
Parte de uma definição de regra é um perfil do IAM que concede permissão para acessar os recursos especificados na ação da regra. O mecanismo de regras assume essa função quando a ação da regra é invocada. A função deve ser definida da mesma forma Conta da AWS que a regra.
Ao criar ou substituir uma regra, você está, na verdade, transferindo uma função para o mecanismo de regras. A permissão `iam:PassRole` é necessária para executar essa operação. Para garantir que você tenha essa permissão, crie uma política que conceda a `iam:PassRole` permissão e anexe-a ao seu usuário do IAM. A política a seguir mostra como conceder `iam:PassRole` a permissão para uma função.
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "Stmt1",
"Effect": "Allow",
"Action": [
"iam:PassRole"
],
"Resource": [
"arn:aws:iam::123456789012:role/myRole"
]
}
]
}
```
Nesse exemplo de política, a `iam:PassRole` permissão é concedida para a função `myRole`. A função é especificada usando o ARN da função. Anexe essa política ao usuário do IAM ou a função a que o usuário pertence. Para obter mais informações, consulte [Como trabalhar com políticas gerenciadas](https://docs.aws.amazon.com/service-authorization/latest/reference/access_policies_managed-using.html).
**nota**
As funções Lambda usam política baseada em recursos, em que a política é vinculada diretamente à própria função do Lambda. Ao criar uma regra que invoca uma função do Lambda, você não transmite uma função, assim, o usuário que está criando a regra não precisa da permissão do `iam:PassRole`. Para obter mais informações sobre a autorização de função do Lambda, consulte [Como conceder permissões usando uma política de recurso](https://docs.aws.amazon.com/lambda/latest/dg/intro-permission-model.html#intro-permission-model-access-policy).
# Criação de uma AWS IoT regra
Você pode criar AWS IoT regras para rotear dados de suas coisas conectadas para interagir com outros AWS serviços. Uma AWS IoT regra consiste nos seguintes componentes:
**Componentes de uma regra**
| Componente | Description | Obrigatório/opcional |
| --- | --- | --- |
| Nome da regra | O nome da regra. Observe que não recomendamos o uso de informações de identificação do usuário em nomes de regras. | Obrigatório. |
| Descrição da regra | Um texto de descrição da regra. Observe que não recomendamos o uso de informações de identificação pessoal nas descrições de suas regras. | Opcional. |
| Declaração do SQL | Uma sintaxe SQL simplificada para filtrar as mensagens recebidas em um tópico do MQTT e enviar os dados para outro lugar. Para obter mais informações, consulte [AWS IoT Referência SQL](iot-sql-reference.md). | Obrigatório. |
| Versão do SQL | A versão do mecanismo de regras do SQL a ser usado ao avaliar a regra. Embora essa propriedade seja opcional, é recomendável especificar a versão do SQL. O AWS IoT Core console define essa `2016-03-23` propriedade como padrão. Se essa propriedade não for definida, como em um AWS CLI comando ou CloudFormation modelo, `2015-10-08` será usada. Para obter mais informações, consulte [Versões do SQL](iot-rule-sql-version.md). | Obrigatório. |
| Uma ou mais ações | As ações são AWS IoT executadas ao promulgar a regra. Por exemplo, você pode inserir dados em uma tabela do DynamoDB, gravar dados em um bucket do Amazon S3, publicar em um tópico do Amazon SNS ou invocar uma função do Lambda. | Obrigatório. |
| Uma ação de erro | A ação é AWS IoT executada quando não consegue realizar a ação de uma regra. | Opcional. |
Antes de criar uma AWS IoT regra, você deve criar uma função do IAM com uma política que permita o acesso aos AWS recursos necessários. AWS IoT assume essa função ao implementar uma regra. Para obter mais informações, consulte [Conceder a uma AWS IoT regra o acesso necessário](https://docs.aws.amazon.com//iot/latest/developerguide/iot-create-role.html) e [Transferir permissões de função](https://docs.aws.amazon.com//iot/latest/developerguide/pass-role.html).
Ao criar uma regra, veja a quantidade de dados que você está publicando nos tópicos. Se você criar regras que incluam um padrão de tópico curinga, elas poderão corresponder a uma grande porcentagem de suas mensagens. Se for esse o caso, talvez seja necessário aumentar a capacidade dos AWS recursos usados pelas ações de destino. Recomendamos evitar padrões de tópicos curinga nas regras de republicação a fim de evitar o processamento duplicado e reduzir custos.
**nota**
A criação e atualização de regras são ações no nível de administrador. Qualquer usuário com permissão para criar ou atualizar regras pode acessar os dados processados pelas regras.
## Criar uma regra (console)
**Para criar uma regra (Console de gerenciamento da AWS)**
Use o comando [Console de gerenciamento da AWS](https://console.aws.amazon.com//iot/home#/home) para criar uma regra:
1. Abra o [console do AWS IoT](https://console.aws.amazon.com//iot/home#/home).
1. No painel de navegação à esquerda, escolha **Roteamento de mensagens** na seção **Gerenciar**. Em seguida, escolha **Regras**.
1. Na página **Regras**, selecione **Criar uma regra**.
1. Na página **Especificar propriedades da regra**, insira um nome para a regra. **Descrição da regra** e **Tags** são opcionais. Escolha **Próximo**.
1. Na página **Configurar instrução SQL**, escolha uma versão SQL e insira uma instrução SQL. Um exemplo de instrução SQL pode ser `SELECT temperature FROM 'iot/topic' WHERE temperature > 50`. Para obter mais informações, consulte [Versões de SQL](https://docs.aws.amazon.com//iot/latest/developerguide/iot-rule-sql-version.html) e [Referência de SQL de AWS IoT](https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-reference.html).
1. Na página **Anexar ações de regras**, adicione ações de regra para rotear dados para outros AWS serviços.
1. Em **Ações de regra**, selecione uma ação de regra na lista suspensa. Por exemplo, você pode escolher o **Kinesis Stream**. Para obter mais informações sobre as ações de regra, consulte [Ações de regra de AWS IoT](https://docs.aws.amazon.com//iot/latest/developerguide/iot-rule-actions.html).
1. Dependendo da ação de regra escolhida, insira os detalhes de configuração relacionados. Por exemplo, se você escolher o **Kinesis Stream**, precisará escolher ou criar um recurso de fluxo de dados e, opcionalmente, inserir detalhes de configuração, como **Chave de partição**, que é usada para agrupar dados por fragmento em um steam.
1. Na **função do IAM**, escolha ou crie uma função para conceder AWS IoT acesso ao seu endpoint. Observe que isso AWS IoT criará automaticamente uma política com o prefixo de `aws-iot-rule` abaixo da sua função do IAM selecionada. Você pode escolher **Exibir** para visualizar o perfil do IAM e a política no console do IAM. A **ação de erro** é opcional. Você pode encontrar mais informações em [Tratamento de erros (ação de erro)](https://docs.aws.amazon.com//iot/latest/developerguide/rule-error-handling.html). Para obter mais informações sobre como criar um perfil do IAM para sua regra, consulte [Conceder a uma regra o acesso necessário](https://docs.aws.amazon.com//iot/latest/developerguide/iot-create-role.html). Escolha **Próximo**.
1. Na página **Revisar e criar**, revise toda a configuração e faça edições, se necessário. Escolha **Criar**.
Depois de criar uma regra com sucesso, você verá a regra na página **Regras**. Você pode selecionar uma regra para abrir a página **Detalhes**, na qual pode visualizar, editar, desativar e excluir uma regra.
## Criar uma regra (CLI)
**Para criar uma regra (AWS CLI)**
Use o comando [create-topic-rule](https://docs.aws.amazon.com/cli/latest/reference/iot/create-topic-rule.html) para criar uma regra:
```
aws iot create-topic-rule --rule-name myrule --topic-rule-payload file://myrule.json
```
Veja a seguir um exemplo de arquivo de carga útil com uma regra que insere todas as mensagens enviadas para o tópico `iot/test` em uma tabela do DynamoDB especificada. A instrução SQL filtra as mensagens e o ARN da função concede AWS IoT permissão para gravar na tabela do DynamoDB.
```
{
"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()}"
}
}
]
}
```
Veja a seguir um exemplo de arquivo de carga útil com uma regra que insere todas as mensagens enviadas para o tópico `iot/test` no bucket do S3 especificado. A instrução SQL filtra as mensagens, e o ARN da função concede AWS IoT permissão para gravar no bucket do Amazon S3.
```
{
"awsIotSqlVersion": "2016-03-23",
"sql": "SELECT * FROM 'iot/test'",
"ruleDisabled": false,
"actions": [
{
"s3": {
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_s3",
"bucketName": "amzn-s3-demo-bucket",
"key": "myS3Key"
}
}
]
}
```
Veja a seguir um exemplo de arquivo de carga útil com uma regra que envia dados para o Amazon OpenSearch Service:
```
{
"sql": "SELECT *, timestamp() as timestamp FROM 'iot/test'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"OpenSearch": {
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_es",
"endpoint": "https://my-endpoint",
"index": "my-index",
"type": "my-type",
"id": "${newuuid()}"
}
}
]
}
```
Veja a seguir um exemplo de arquivo de carga útil com uma regra que invoca uma função do Lambda:
```
{
"sql": "expression",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"lambda": {
"functionArn": "arn:aws:lambda:us-west-2:123456789012:function:my-lambda-function"
}
}
]
}
```
Veja a seguir um exemplo de arquivo de carga útil com uma regra que publica em um tópico do 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"
}
}
]
}
```
Veja a seguir um exemplo de arquivo de carga útil com uma regra que publica novamente em um tópico diferente do MQTT:
```
{
"sql": "expression",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"republish": {
"topic": "my-mqtt-topic",
"roleArn": "arn:aws:iam::123456789012:role/my-iot-role"
}
}
]
}
```
A seguir está um exemplo de arquivo de carga útil com uma regra que envia dados para um fluxo do Amazon 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"
}
}
]
}
```
Veja a seguir um exemplo de arquivo de carga útil com uma regra que usa a `machinelearning_predict` função Amazon SageMaker AI para republicar em um tópico se os dados na carga do MQTT forem classificados como 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"
}
}
]
}
```
O seguinte é um exemplo de arquivo de carga útil com uma regra que publica mensagens em um fluxo de entrada do 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"
}
}
]
}
```
Veja a seguir um exemplo de arquivo de carga útil com uma regra que inicie a execução de uma máquina de estados Step Functions.
```
{
"sql": "expression",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"stepFunctions": {
"stateMachineName": "myCoolStateMachine",
"executionNamePrefix": "coolRunning",
"roleArn": "arn:aws:iam::123456789012:role/my-iot-role"
}
}
]
}
```
# Gerenciando uma AWS IoT regra
Você pode usar as ações a seguir para gerenciar suas AWS IoT regras.
**Topics**
+ [Marcar uma regra](#iot-create-rule-tagging)
+ [Visualizar uma regra](#iot-view-rules)
+ [Como excluir uma regra](#iot-delete-rule)
## Marcar uma regra
Para adicionar outra camada de especificidade às suas regras novas ou existentes, você pode aplicar a marcação. A marcação aproveita os pares de valores-chave em suas regras para fornecer maior controle sobre como e onde suas regras são aplicadas aos seus AWS IoT recursos e serviços. Por exemplo, você pode limitar o escopo da sua regra para aplicá-la somente em seu ambiente beta para testes de pré-lançamento (`Key=environment, Value=beta`) ou capturar todas as mensagens enviadas ao tópico `iot/test` de um endpoint específico e armazená-las em um bucket do Amazon S3.
### Exemplo de política do IAM
Para ver um exemplo que mostra como conceder permissões de marcação para uma regra, considere um usuário que executa o comando a seguir para criar uma regra e marcá-la para aplicá-la somente ao ambiente beta.
No exemplo, substitua:
+ *MyTopicRuleName*com o nome da regra.
+ *myrule.json*com o nome do documento de política.
```
aws iot create-topic-rule
--rule-name MyTopicRuleName
--topic-rule-payload file://myrule.json
--tags "environment=beta"
```
Para este exemplo, você deve usar a seguinte política do IAM:
****
```
{
"Version":"2012-10-17",
"Statement":
{
"Action": [ "iot:CreateTopicRule", "iot:TagResource" ],
"Effect": "Allow",
"Resource": [
"arn:aws:iot:us-east-1:123456789012:rule/MyTopicRuleName"
]
}
}
```
O exemplo acima mostra uma regra recém-criada chamada `MyTopicRuleName` que se aplica somente ao seu ambiente beta. A `iot:TagResource` declaração de política com a indicação `MyTopicRuleName` específica permite a marcação ao criar ou atualizar `MyTopicRuleName`. O parâmetro `--tags "environment=beta"` usado ao criar a regra limita o escopo de `MyTopicRuleName` somente ao seu ambiente beta. Se você remover o parâmetro `--tags "environment=beta"`, então `MyTopicRuleName` será aplicado a todos os ambientes.
Para obter mais informações sobre a criação de perfis do IAM e políticas específicas para uma regra, AWS IoT consulte [Conceder a uma AWS IoT regra o acesso que ela exige](iot-create-role.md)
Para obter informações gerais sobre a marcação de recursos, consulte [Marcando seus recursos AWS IoT](tagging-iot.md).
## Visualizar uma regra
Use o [list-topic-rules](https://docs.aws.amazon.com/cli/latest/reference/iot/list-topic-rules.html)comando para listar suas regras:
```
aws iot list-topic-rules
```
Use o [get-topic-rule](https://docs.aws.amazon.com/cli/latest/reference/iot/get-topic-rule.html)comando para obter informações sobre uma regra:
```
aws iot get-topic-rule --rule-name myrule
```
## Como excluir uma regra
Quando não precisar mais de uma regra, você poderá excluí-la.
**Para excluir uma regra (AWS CLI)**
Use o [delete-topic-rule](https://docs.aws.amazon.com/cli/latest/reference/iot/delete-topic-rule.html)comando para excluir uma regra:
```
aws iot delete-topic-rule --rule-name myrule
```
# AWS IoT ações de regras
AWS IoT as ações de regra especificam o que fazer quando uma regra é invocada. Você pode definir ações para enviar dados para um banco de dados do Amazon DynamoDB, enviar dados para o Amazon Kinesis Data Streams, AWS Lambda invocar uma função e assim por diante. AWS IoT suporta as seguintes ações em Regiões da AWS que o serviço da ação está disponível.
| Ação da regra | Descrição | Nome na API |
| --- | --- | --- |
| [Apache Kafka](apache-kafka-rule-action.md) | Envia uma mensagem para um cluster Apache Kafka. | kafka |
| [CloudWatch alarmes](cloudwatch-alarms-rule-action.md) | Altera o estado de um CloudWatch alarme da Amazon. | cloudwatchAlarm |
| [CloudWatch Registros](cloudwatch-logs-rule-action.md) | Envia uma mensagem para a Amazon CloudWatch Logs. | cloudwatchLogs |
| [CloudWatch métricas](cloudwatch-metrics-rule-action.md) | Envia uma mensagem para uma CloudWatch métrica. | cloudwatchMetric |
| [DynamoDB](dynamodb-rule-action.md) | Envia uma mensagem para uma tabela do DynamoDB. | dynamoDB |
| [Dínamo DBv2](dynamodb-v2-rule-action.md) | Envia dados de mensagens para várias colunas em uma tabela do DynamoDB. | dynamoDBv2 |
| [Elasticsearch](elasticsearch-rule-action.md) | Envia uma mensagem para um OpenSearch endpoint. | OpenSearch |
| [HTTP](https-rule-action.md) | Publica uma mensagem em um endpoint HTTPS. | http |
| [AWS IoT Events](iotevents-rule-action.md) | Envia uma mensagem para uma AWS IoT Events entrada. | iotEvents |
| [AWS IoT SiteWise](iotsitewise-rule-action.md) | Envia dados da mensagem para as propriedades do AWS IoT SiteWise ativo. | iotSiteWise |
| [Firehose](kinesis-firehose-rule-action.md) | Envia uma mensagem para o fluxo de entrega do Firehose. | firehose |
| [Kinesis Data Streams](kinesis-rule-action.md) | Envia uma mensagem para o fluxo de dados do Kinesis. | kinesis |
| [Lambda](lambda-rule-action.md) | Invoca uma função do Lambda com dados da mensagem como entrada. | lambda |
| [Local](location-rule-action.md) | Envia dados de localização para o Amazon Location Service. | location |
| [OpenSearch](opensearch-rule-action.md) | Envia uma mensagem para um endpoint OpenSearch do Amazon Service. | OpenSearch |
| [Nova publicação](republish-rule-action.md) | Publica novamente uma mensagem em outro tópico do MQTT. | republish |
| [S3](s3-rule-action.md) | Armazena uma mensagem em um bucket do Amazon Simple Storage Service (Amazon S3). | s3 |
| [IoT do Salesforce](salesforce-iot-rule-action.md) | Envia uma mensagem para o fluxo de entrada da Salesforce IoT. | salesforce |
| [SNS](sns-rule-action.md) | Publica uma mensagem como uma notificação push do Amazon Simple Notification Service (Amazon SNS) | sns |
| [SQS](sqs-rule-action.md) | Envia uma mensagem para uma fila do Amazon Simple Queue Service (Amazon SQS). | sqs |
| [Step Functions](stepfunctions-rule-action.md) | Inicia uma máquina de AWS Step Functions estado. | stepFunctions |
| [Timestream](timestream-rule-action.md) | Envia uma mensagem para uma tabela de banco de dados do Amazon Timestream. | timestream |
**Observações**
Defina a regra da mesma forma Região da AWS que o recurso de outro serviço para que a ação da regra possa interagir com esse recurso.
O mecanismo de AWS IoT regras pode fazer várias tentativas para realizar uma ação se ocorrerem erros intermitentes. Se todas as tentativas falharem, a mensagem será descartada e o erro estará disponível nos seus CloudWatch registros. Você pode especificar uma ação de erro para cada regra que é invocada depois de ocorrer uma falha. Para obter mais informações, consulte [Tratamento de erros (ação de erro)](rule-error-handling.md).
Algumas ações de regra acionam ações em serviços que se integram ao AWS Key Management Service (AWS KMS) para oferecer suporte à criptografia de dados em repouso. Se você usar uma chave gerenciada pelo cliente AWS KMS key (chave KMS) para criptografar dados em repouso, o serviço deverá ter permissão para usar a chave KMS em nome do chamador. Para saber como gerenciar permissões para sua chave KMS gerenciada pelo cliente, consulte os tópicos de criptografia de dados no guia de serviço apropriado. Para obter mais informações sobre chaves KMS gerenciadas pelo cliente, consulte os [AWS Key Management Service conceitos](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html) no *AWS Key Management Service Guia do desenvolvedor*.
Você pode usar qualquer [função](iot-sql-functions.md) ou [modelo de substituição](https://docs.aws.amazon.com//iot/latest/developerguide/iot-substitution-templates.html) na instrução SQL de uma ação de erro, incluindo as funções externas: [https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-func-aws-lambda](https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-func-aws-lambda), [https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-sql-function-get-registry_data](https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-sql-function-get-registry_data), [https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-sql-function-get-thing-shadow](https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-sql-function-get-thing-shadow), [https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-sql-function-get-secret](https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-sql-function-get-secret), [https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-sql-function-machine-learning](https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-sql-function-machine-learning), e. [https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-sql-decode-base64](https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-sql-decode-base64) Se uma ação de erro exigir a chamada de uma função externa, a invocação da ação de erro poderá resultar em cobrança adicional para a função externa.
# Apache Kafka
A ação Apache Kafka (Kafka) envia mensagens diretamente ao [Amazon Managed Streaming for Apache Kafka](https://docs.aws.amazon.com//msk/latest/developerguide/what-is-msk.html) (Amazon MSK), clusters do Apache Kafka gerenciados por provedores de terceiros, como [Confluent Cloud](https://www.confluent.io/) ou clusters autogerenciados do Apache Kafka. Com a ação da regra do Kafka, você pode rotear seus dados de IoT para clusters do Kafka. Isso permite criar pipelines de dados de alto desempenho para várias finalidades, como análise de streaming, integração de dados, visualização e aplicações comerciais essenciais.
**nota**
Este tópico pressupõe familiaridade com a plataforma Apache Kafka e conceitos relacionados. Para obter mais informações sobre o Apache Kafka, consulte [Apache Kafka](https://kafka.apache.org/). Não há suporte para [MSK com tecnologia sem servidor](https://docs.aws.amazon.com//msk/latest/developerguide/serverless.html). Os clusters do MSK com tecnologia sem servidor só podem ser feitos por meio da autenticação do IAM, que não é compatível com a ação de regra do Apache Kafka no momento. Para obter mais informações sobre como configurar AWS IoT Core com o Confluent, consulte [Aproveitando o Confluent e AWS resolvendo desafios de gerenciamento de dados e dispositivos de IoT](https://aws.amazon.com/blogs/apn/leveraging-confluent-and-aws-to-solve-iot-device-and-data-management-challenges/).
## Requisitos
Esta ação de regra tem os seguintes requisitos:
+ Uma função do IAM que AWS IoT pode ser assumida para realizar as `ec2:DescribeSecurityGroups` operações `ec2:CreateNetworkInterface` `ec2:DescribeNetworkInterfaces` `ec2:CreateNetworkInterfacePermission``ec2:DeleteNetworkInterface`,`ec2:DescribeSubnets`,`ec2:DescribeVpcs`,`ec2:DescribeVpcAttribute`,,, e. Essa função cria e gerencia interfaces de rede elásticas para o Amazon Virtual Private Cloud para alcançar seu agente Kafka. Para obter mais informações, consulte [Conceder a uma AWS IoT regra o acesso que ela exige](iot-create-role.md).
No AWS IoT console, você pode escolher ou criar uma função para permitir AWS IoT Core a execução dessa ação de regra.
Para obter mais informações sobre interfaces de rede, consulte [Interfaces de rede elásticas](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-eni.html) no *Guia do usuário do Amazon EC2*.
A política vinculada à função que você especificar deve ser semelhante à do exemplo a seguir.
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"ec2:CreateNetworkInterface",
"ec2:DescribeNetworkInterfaces",
"ec2:CreateNetworkInterfacePermission",
"ec2:DeleteNetworkInterface",
"ec2:DescribeSubnets",
"ec2:DescribeVpcs",
"ec2:DescribeVpcAttribute",
"ec2:DescribeSecurityGroups"
],
"Resource": "*"
}
]
}
```
+ Se você costuma AWS Secrets Manager armazenar as credenciais necessárias para se conectar ao seu corretor Kafka, deve criar uma função do IAM que AWS IoT Core possa ser assumida para realizar as operações e. `secretsmanager:GetSecretValue` `secretsmanager:DescribeSecret`
A política vinculada à função que você especificar deve ser semelhante à do exemplo a seguir.
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"secretsmanager:GetSecretValue",
"secretsmanager:DescribeSecret"
],
"Resource": [
"arn:aws:secretsmanager:us-east-1:123456789012:secret:kafka_client_truststore-*",
"arn:aws:secretsmanager:us-east-1:123456789012:secret:kafka_keytab-*"
]
}
]
}
```
+ Você pode executar seus clusters do Apache Kafka dentro do Amazon Virtual Private Cloud (Amazon VPC). Você deve criar um destino de Nuvem Privada Virtual (VPC) Apache Kafka e usar um gateway NAT em suas sub-redes para encaminhar mensagens para um cluster público do Kafka. AWS IoT O mecanismo de AWS IoT regras cria uma interface de rede em cada uma das sub-redes listadas no destino para rotear o tráfego diretamente para a VPC. Quando você faz o destino, o mecanismo de AWS IoT regras cria automaticamente uma ação de regra de VPC. Para obter mais informações sobre ações de regras de VPC, consulte [Destinos da Nuvem Privada Virtual (VPC) Apache Kafka](kafka-vpc-destination.md).
+ Se você usar uma chave gerenciada pelo cliente AWS KMS key (chave KMS) para criptografar dados em repouso, o serviço deverá ter permissão para usar a chave KMS em nome do chamador. Para obter mais informações, consulte [Criptografia do Amazon MSK](https://docs.aws.amazon.com/msk/latest/developerguide/msk-encryption.html) no *Guia do desenvolvedor do Amazon Managed Streaming for Apache Kafka*.
## Parâmetros
Ao criar uma AWS IoT regra com essa ação, você deve especificar as seguintes informações:
destinationArn
O Amazon Resource Name (ARN) do destino da Nuvem Privada Virtual (VPC) Apache Kafka. Para obter informações sobre como criar um destino, consulte[Destinos da Nuvem Privada Virtual (VPC) Apache Kafka](kafka-vpc-destination.md).
tópico
O tópico do Kafka para mensagens enviadas ao agente do Kafka.
Você pode substituir esse campo usando um modelo de substituição. Para obter mais informações, consulte [Modelos de substituição](iot-substitution-templates.md).
chave (opcional)
A chave de mensagem do Kafka.
Você pode substituir esse campo usando um modelo de substituição. Para obter mais informações, consulte [Modelos de substituição](iot-substitution-templates.md).
cabeçalhos (opcional)
A lista de cabeçalhos Kafka que você especifica. Cada cabeçalho é um par de chave-valor que você pode especificar ao criar uma ação do Kafka. Você pode usar esses cabeçalhos para rotear dados de clientes IoT para clusters Kafka downstream sem modificar a carga útil da mensagem.
Você pode substituir esse campo usando um modelo de substituição. Para entender como passar uma função de regra integrada como um modelo de substituição no cabeçalho do Kafka Action, consulte [Exemplos](#apache-kafka-rule-action-examples). Para obter mais informações, consulte [Modelos de substituição](iot-substitution-templates.md).
Não há compatibilidade com cabeçalhos em formato binário.
partição (opcional)
A partição de mensagens do Kafka.
Você pode substituir esse campo usando um modelo de substituição. Para obter mais informações, consulte [Modelos de substituição](iot-substitution-templates.md).
clientProperties
Um objeto que define as propriedades do cliente produtor Apache Kafka.
acks (opcional)
O número de confirmações que o produtor exige que o servidor tenha recebido antes de considerar uma solicitação concluída.
Se você especificar 0 como valor, o produtor não aguardará nenhuma confirmação do servidor. Se o servidor não receber a mensagem, o produtor não tentará enviá-la novamente.
Valores válidos: `-1`, `0`, `1`, `all`. O valor padrão é `1`.
bootstrap.servers
Uma lista de pares de host e porta (por exemplo,`host1:port1`, `host2:port2`) usados para estabelecer a conexão inicial com o cluster Kafka.
compression.type (opcional)
O tipo de compressão para todos os dados gerados pelo produtor.
Valores válidos: `none`, `gzip`, `snappy`, `lz4`, `zstd`. O valor padrão é `none`.
security.protocol
O protocolo de segurança usado para se conectar ao seu agente Kafka.
Valores válidos: `SSL`, `SASL_SSL`. O valor padrão é `SSL`.
key.serializer
Especifica como transformar os principais objetos que você fornece com o`ProducerRecord` em bytes.
Valor válido: `StringSerializer`.
value.serializador
Especifica como transformar os principais objetos que você fornece com o `ProducerRecord` em bytes.
Valor válido: `ByteBufferSerializer`.
ssl.truststore
O arquivo truststore no formato base64 ou a localização do arquivo truststore em [AWS Secrets Manager](https://docs.aws.amazon.com/secretsmanager/latest/userguide/). Esse valor não será necessário se o seu arquivo truststore for certificado pelas autoridades de certificação (CA) da Amazon.
Este campo oferece suporte a modelos de substituição. Se você usar o Secrets Manager para armazenar as credenciais necessárias para se conectar ao seu agente Kafka, poderá usar a função `get_secret` SQL para recuperar o valor desse campo. Para obter mais informações sobre modelos de substituição, consulte [Modelos de substituição](iot-substitution-templates.md). Para obter mais informações sobre a `get_secret` função SQL, consulte [get\$1secret (secretId, secretType, chave, roleArn)](iot-sql-functions.md#iot-sql-function-get-secret). Se o arquivo truststore estiver na forma de um arquivo, use o parâmetro `SecretBinary`. Se o arquivo truststore estiver na forma de uma string, use o parâmetro `SecretString`.
O tamanho máximo desse valor é 65 KB.
ssl.truststore.password
A senha do arquivo truststore. Esse valor é necessário somente se você tiver criado uma senha para o arquivo truststore.
ssl.keystore
O arquivo de armazenamento de chaves. Esse valor é necessário quando você especifica `SSL` como valor para `security.protocol`.
Este campo oferece suporte a modelos de substituição. Use o Secrets Manager para armazenar as credenciais necessárias para se conectar ao seu agente Kafka. Para recuperar o valor desse campo, use a `get_secret` função SQL. Para obter mais informações sobre modelos de substituição, consulte [Modelos de substituição](iot-substitution-templates.md). Para obter mais informações sobre a `get_secret` função SQL, consulte [get\$1secret (secretId, secretType, chave, roleArn)](iot-sql-functions.md#iot-sql-function-get-secret). Use o parâmetro `SecretBinary`.
ssl.keystore.password
A senha de armazenamento do arquivo keystore. Esse valor será exigido se um valor para `ssl.keystore` for especificado.
O valor desse campo pode ser texto simples. Este campo oferece suporte a modelos de substituição. Use o Secrets Manager para armazenar as credenciais necessárias para se conectar ao seu agente Kafka. Para recuperar o valor desse campo, use a `get_secret` função SQL. Para obter mais informações sobre modelos de substituição, consulte [Modelos de substituição](iot-substitution-templates.md). Para obter mais informações sobre a `get_secret` função SQL, consulte [get\$1secret (secretId, secretType, chave, roleArn)](iot-sql-functions.md#iot-sql-function-get-secret). Use o parâmetro `SecretString`.
ssl.key.password
A senha da chave privada em seu arquivo keystore.
Este campo oferece suporte a modelos de substituição. Use o Secrets Manager para armazenar as credenciais necessárias para se conectar ao seu agente Kafka. Para recuperar o valor desse campo, use a `get_secret` função SQL. Para obter mais informações sobre modelos de substituição, consulte [Modelos de substituição](iot-substitution-templates.md). Para obter mais informações sobre a `get_secret` função SQL, consulte [get\$1secret (secretId, secretType, chave, roleArn)](iot-sql-functions.md#iot-sql-function-get-secret). Use o parâmetro `SecretString`.
sasl.mechanism
O mecanismo de segurança usado para se conectar ao seu agente Kafka. Esse valor é necessário quando você especifica `SASL_SSL` para `security.protocol`.
Valores válidos: `PLAIN`, `SCRAM-SHA-512`, `GSSAPI`.
`SCRAM-SHA-512`é o único mecanismo de segurança suportado nas regiões cn-north-1, cn-northwest-1, -1 e -1. us-gov-east us-gov-west
sasl.plain.username
O nome de usuário usado para recuperar a string secreta do Secrets Manager. Esse valor é necessário quando você especifica `SASL_SSL` para `security.protocol` e `PLAIN` para `sasl.mechanism` .
sasl.plain.password
A senha usada para recuperar a string secreta do Secrets Manager. Esse valor é necessário quando você especifica `SASL_SSL` para `security.protocol` e `PLAIN` para `sasl.mechanism`.
sasl.scram.username
O nome de usuário usado para recuperar a string secreta do Secrets Manager. Esse valor é necessário quando você especifica `SASL_SSL` para `security.protocol` e `SCRAM-SHA-512` para `sasl.mechanism` .
sasl.scram.password
A senha usada para recuperar a string secreta do Secrets Manager. Esse valor é necessário quando você especifica `SASL_SSL` para `security.protocol` e `SCRAM-SHA-512` para `sasl.mechanism`.
sasl.kerberos.keytab
O arquivo keytab para autenticação Kerberos no Secrets Manager. Esse valor é necessário quando você especifica `SASL_SSL` para `security.protocol` e `GSSAPI` para `sasl.mechanism`.
Este campo oferece suporte a modelos de substituição. Use o Secrets Manager para armazenar as credenciais necessárias para se conectar ao seu agente Kafka. Para recuperar o valor desse campo, use a `get_secret` função SQL. Para obter mais informações sobre modelos de substituição, consulte [Modelos de substituição](iot-substitution-templates.md). Para obter mais informações sobre a `get_secret` função SQL, consulte [get\$1secret (secretId, secretType, chave, roleArn)](iot-sql-functions.md#iot-sql-function-get-secret). Use o parâmetro `SecretBinary`.
sasl.kerberos.service.name
O nome principal do Kerberos sob o qual o Apache Kafka é executado. Esse valor é necessário quando você especifica `SASL_SSL` para `security.protocol` e `GSSAPI` para `sasl.mechanism`.
sasl.kerberos.krb5.kdc
O nome do host do centro de distribuição de chaves (KDC) ao qual seu cliente produtor do Apache Kafka se conecta. Esse valor é necessário quando você especifica `SASL_SSL` para `security.protocol` e `GSSAPI` para `sasl.mechanism`.
sasl.kerberos.krb5.realm
A região à qual seu cliente produtor Apache Kafka se conecta. Esse valor é necessário quando você especifica `SASL_SSL` para `security.protocol` e `GSSAPI` para `sasl.mechanism`.
sasl.kerberos.principal
A identidade Kerberos exclusiva à qual o Kerberos pode atribuir tickets para acessar serviços compatíveis com Kerberos. Esse valor é necessário quando você especifica `SASL_SSL` para `security.protocol` e `GSSAPI` para `sasl.mechanism`.
## Exemplos
O exemplo de JSON a seguir define uma ação do Apache Kafka em uma regra. AWS IoT O exemplo a seguir passa a função integrada [sourceIP()](iot-sql-functions.md#iot-function-sourceip) como um [ modelo de substituição](https://docs.aws.amazon.com//iot/latest/developerguide/iot-substitution-templates.html) no cabeçalho Kafka Action.
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"kafka": {
"destinationArn": "arn:aws:iot:region:123456789012:ruledestination/vpc/VPCDestinationARN",
"topic": "TopicName",
"clientProperties": {
"bootstrap.servers": "kafka.com:9092",
"security.protocol": "SASL_SSL",
"ssl.truststore": "${get_secret('kafka_client_truststore', 'SecretBinary','arn:aws:iam::123456789012:role/kafka-get-secret-role-name')}",
"ssl.truststore.password": "kafka password",
"sasl.mechanism": "GSSAPI",
"sasl.kerberos.service.name": "kafka",
"sasl.kerberos.krb5.kdc": "kerberosdns.com",
"sasl.kerberos.keytab": "${get_secret('kafka_keytab','SecretBinary', 'arn:aws:iam::123456789012:role/kafka-get-secret-role-name')}",
"sasl.kerberos.krb5.realm": "KERBEROSREALM",
"sasl.kerberos.principal": "kafka-keytab/kafka-keytab.com"
},
"headers": [
{
"key": "static_header_key",
"value": "static_header_value"
},
{
"key": "substitutable_header_key",
"value": "${value_from_payload}"
},
{
"key": "source_ip",
"value": "${sourceIp()}"
}
]
}
}
]
}
}
```
**Notas importantes sobre a configuração do Kerberos**
+ Seu centro de distribuição de chaves (KDC) deve ser resolvido por meio de um sistema de nomes de domínio (DNS) privado em sua VPC de destino. Uma abordagem possível é adicionar a entrada DNS do KDC a uma zona hospedada privada. Para obter mais informações sobre essa abordagem, consulte [Como trabalhar com zonas hospedadas privadas](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/hosted-zones-private.html).
+ Cada VPC deve ter a resolução DNS habilitada. Para obter mais informações, consulte [Como usar o DNS com sua VPC](https://docs.aws.amazon.com/vpc/latest/userguide/vpc-dns.html).
+ Os grupos de segurança da interface de rede e os grupos de segurança em nível de instância no destino da VPC devem permitir o tráfego de dentro da sua VPC nas seguintes portas.
+ Tráfego TCP na porta do receptor do bootstrap broker (geralmente 9092, mas deve estar na faixa de 9000—9100)
+ Tráfego TCP e UDP na porta 88 para o KDC
+ `SCRAM-SHA-512`é o único mecanismo de segurança suportado nas regiões cn-north-1, cn-northwest-1, -1 e -1. us-gov-east us-gov-west
# Destinos da Nuvem Privada Virtual (VPC) Apache Kafka
A ação da regra Apache Kafka roteia dados para um cluster Apache Kafka em uma Amazon Virtual Private Cloud (Amazon VPC). A configuração de VPC usada pela ação da regra do Apache Kafka é ativada automaticamente quando você especifica o destino da VPC para sua ação de regra.
Um destino da Nuvem Privada Virtual (VPC) Apache Kafka contém uma lista de sub-redes dentro da VPC. O mecanismo de regras cria uma interface de rede elástica em cada sub-rede que você especificar nessa lista. Para obter mais informações sobre interfaces de rede, consulte [Interfaces de rede elásticas](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-eni.html) no Guia do usuário do Amazon EC2.
## Requisitos e considerações
+ Se você estiver usando um cluster Apache Kafka autogerenciado que será acessado usando um endpoint público na Internet:
+ Crie um gateway NAT para instâncias em suas sub-redes. O gateway NAT tem um endereço IP público que pode se conectar à Internet, o que permite que o mecanismo de regras encaminhe suas mensagens para o cluster público do Kafka.
+ Aloque um endereço IP elástico com as interfaces de rede elástica (ENIs) que são criadas pelo destino da Nuvem Privada Virtual (VPC) do Apache Kafka. Os grupos de segurança que você usa devem ser configurados para bloquear o tráfego de entrada.
**nota**
Se o destino da Nuvem Privada Virtual (VPC) Apache Kafka for desativado e reativado, você deverá associar novamente o elástico ao novo. IPs ENIs
+ Se um destino da Nuvem Privada Virtual (VPC) Apache Kafka não receber nenhum tráfego por 30 dias consecutivos, ele será desativado.
+ Se algum recurso usado pelo destino da Nuvem Privada Virtual (VPC) Apache Kafka mudar, o destino será desativado e não poderá ser usado.
+ Algumas mudanças que podem desativar um destino de Nuvem Privada Virtual (VPC) Apache Kafka incluem:
+ Excluindo a VPC, as sub-redes, os grupos de segurança ou a função usada.
+ Modificar a função para não ter mais as permissões necessárias.
+ Atingindo quase a capacidade da sub-rede, o que nos impede de aplicar os patches do [FedRAMP.](https://aws.amazon.com/compliance/fedramp/)
+ Desativando o destino.
## Definição de preço
Para fins de preço, uma ação de regra de VPC é medida, além da ação que envia uma mensagem a um recurso quando o recurso está em sua VPC. Para obter informações sobre preços, consulte [AWS IoT Core preços](https://aws.amazon.com/iot-core/pricing/).
## Criação de destinos de Nuvem Privada Virtual (VPC) Apache Kafka
Você cria um destino de Nuvem Privada Virtual (VPC) Apache Kafka usando a API ou o console. [CreateTopicRuleDestination](https://docs.aws.amazon.com/iot/latest/apireference/API_CreateTopicRuleDestination.html) AWS IoT Core
Ao criar um destino, você deve especificar as seguintes informações.
vpcId
O ID exclusivo da Amazon VPC.
subnetIds
Uma lista de sub-redes nas quais o mecanismo de regras cria interfaces de rede elásticas. O mecanismo de regras aloca uma única interface de rede para cada sub-rede na lista.
securityGroups (opcional)
Uma lista de grupos de segurança a serem aplicados às interfaces de rede.
roleArn
O nome do recurso da Amazon (ARN) de uma função que tem permissão para criar interfaces de rede em seu nome.
Esse ARN deve ter uma política anexada a ele que se pareça com o exemplo a seguir.
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"ec2:CreateNetworkInterface",
"ec2:DescribeNetworkInterfaces",
"ec2:DescribeVpcs",
"ec2:DeleteNetworkInterface",
"ec2:DescribeSubnets",
"ec2:DescribeVpcAttribute",
"ec2:DescribeSecurityGroups"
],
"Resource": "*"
},
{
"Effect": "Allow",
"Action": "ec2:CreateNetworkInterfacePermission",
"Resource": "*",
"Condition": {
"StringEquals": {
"ec2:ResourceTag/VPCDestinationENI": "true"
}
}
},
{
"Effect": "Allow",
"Action": [
"ec2:CreateTags"
],
"Resource": "*",
"Condition": {
"StringEquals": {
"ec2:CreateAction": "CreateNetworkInterface",
"aws:RequestTag/VPCDestinationENI": "true"
}
}
}
]
}
```
### Criação de um destino de Nuvem Privada Virtual (VPC) Apache Kafka usando AWS CLI
O exemplo a seguir mostra como criar um destino usando AWS CLI o.
```
aws --region regions iot create-topic-rule-destination --destination-configuration 'vpcConfiguration={subnetIds=["subnet-123456789101230456"],securityGroups=[],vpcId="vpc-123456789101230456",roleArn="arn:aws:iam::123456789012:role/role-name"}'
```
Depois de executar esse comando, o status de destino será`IN_PROGRESS`. Depois de alguns minutos, seu status mudará para `ERROR` (se o comando não for bem-sucedido) ou `ENABLED`. Quando o status de destino é `ENABLED`, estará pronto para uso.
Você pode usar o comando a seguir para obter o status do seu destino da Nuvem Privada Virtual (VPC) Apache Kafka.
```
aws --region region iot get-topic-rule-destination --arn "VPCDestinationARN"
```
### Criação de um destino de Nuvem Privada Virtual (VPC) Apache Kafka usando o console AWS IoT Core
As etapas a seguir descrevem como criar um destino usando o AWS IoT Core console.
1. Navegue até o AWS IoT Core console. No painel esquerdo, na guia **Agir**, escolha **Destinos**.
1. Insira valores para os seguintes campos.
+ **ID da VPC**
+ **Sub-rede IDs**
+ **Grupo de segurança**
1. Selecione uma função que tenha as permissões necessárias para criar interfaces de rede. O exemplo de política anterior contém essas permissões.
Quando o status de destino da Nuvem Privada Virtual (VPC) Apache Kafka **é ATIVADO, ele está** pronto para uso.
# CloudWatch alarmes
A ação CloudWatch alarm (`cloudWatchAlarm`) altera o estado de um CloudWatch alarme da Amazon. Você pode especificar o motivo da alteração do estado e o valor nessa chamada.
## Requisitos
Esta ação de regra tem os seguintes requisitos:
+ Uma função do IAM que AWS IoT você pode assumir para realizar a `cloudwatch:SetAlarmState` operação. Para obter mais informações, consulte [Conceder a uma AWS IoT regra o acesso que ela exige](iot-create-role.md).
No AWS IoT console, você pode escolher ou criar uma função para permitir AWS IoT a execução dessa ação de regra.
## Parâmetros
Ao criar uma AWS IoT regra com essa ação, você deve especificar as seguintes informações:
`alarmName`
O nome do CloudWatch alarme.
Suporta [modelos de substituição](iot-substitution-templates.md): API e somente AWS CLI
`stateReason`
O motivo para a alteração do alarme.
Compatível com [modelos de substituição](iot-substitution-templates.md): Sim
`stateValue`
O valor do estado do alarme. Valores válidos: `OK`, `ALARM`, `INSUFFICIENT_DATA`.
Compatível com [modelos de substituição](iot-substitution-templates.md): Sim
`roleArn`
A função do IAM que permite o acesso ao CloudWatch alarme. Para obter mais informações, consulte [Requisitos](#cloudwatch-alarms-rule-action-requirements).
Compatível com [modelos de substituição](iot-substitution-templates.md): Não
## Exemplos
O exemplo de JSON a seguir define uma ação CloudWatch de alarme em uma AWS IoT regra.
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"cloudwatchAlarm": {
"alarmName": "IotAlarm",
"stateReason": "Temperature stabilized.",
"stateValue": "OK",
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_cw"
}
}
]
}
}
```
## Consulte também
+ [O que é a Amazon CloudWatch?](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/) no *Guia do CloudWatch usuário da Amazon*
+ [Usando CloudWatch alarmes da Amazon](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/AlarmThatSendsEmail.html) no Guia do * CloudWatch usuário da Amazon*
# CloudWatch Registros
A ação CloudWatch Logs (`cloudwatchLogs`) envia dados para o Amazon CloudWatch Logs. Você pode usar `batchMode` para carregar e marcar com data e hora vários registros de log do dispositivo em uma mensagem. Você pode também especificar o grupo de logs para o qual a ação envia dados.
## Requisitos
Esta ação de regra tem os seguintes requisitos:
+ Uma função do IAM que você AWS IoT pode assumir para realizar as `logs:PutLogEvents` operações `logs:CreateLogStream``logs:DescribeLogStreams`, e. Para obter mais informações, consulte [Conceder a uma AWS IoT regra o acesso que ela exige](iot-create-role.md).
No AWS IoT console, você pode escolher ou criar uma função para permitir AWS IoT a execução dessa ação de regra.
+ Se você usar uma chave gerenciada pelo cliente AWS KMS key (chave KMS) para criptografar dados de registro no CloudWatch Logs, o serviço deverá ter permissão para usar a chave KMS em nome do chamador. Para obter mais informações, consulte [Criptografar dados de log em CloudWatch registros usando AWS KMS](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/encrypt-log-data-kms.html) o *Guia do usuário do Amazon CloudWatch Logs*.
## Requisitos de formato de mensagem MQTT para `batchMode`
Se você usar a ação de regra de CloudWatch registros com `batchMode` desativada, não há requisitos de formatação de mensagens do MQTT. (Nota: o `batchMode` valor padrão do parâmetro é `false`.) No entanto, se você usar a ação de regra de CloudWatch registros `batchMode` ativada (o valor do parâmetro é`true`), as mensagens MQTT contendo registros do lado do dispositivo deverão ser formatadas para conter um carimbo de data/hora e uma carga útil da mensagem. **Nota:** `timestamp` representa a hora em que o evento ocorreu e é expresso como um número de milissegundos após 1º de janeiro de 1970 00:00:00 UTC.
A seguir está um exemplo do formato de publicação:
```
[
{"timestamp": 1673520691093, "message": "Test message 1"},
{"timestamp": 1673520692879, "message": "Test message 2"},
{"timestamp": 1673520693442, "message": "Test message 3"}
]
```
Dependendo de como os registros do lado do dispositivo são gerados, poderá ser necessário filtrá-los e reformatá-los antes de serem enviados para cumprir este requisito. Para obter mais informações, consulte [Carga útil da mensagem MQTT](https://docs.aws.amazon.com/iot/latest/developerguide/topicdata.html).
Independentemente do `batchMode` parâmetro, o `message` conteúdo deve estar em conformidade com as limitações de tamanho da AWS IoT mensagem. Para obter mais informações, consulte [AWS IoT Core Endpoints e cotas](https://docs.aws.amazon.com/general/latest/gr/iot-core.html).
## Parâmetros
Ao criar uma AWS IoT regra com essa ação, você deve especificar as seguintes informações:
`logGroupName`
O grupo de CloudWatch registros para o qual a ação envia dados.
Suporta [modelos de substituição](iot-substitution-templates.md): API e somente AWS CLI
`roleArn`
A função do IAM que permite acesso ao grupo de CloudWatch registros. Para obter mais informações, consulte [Requisitos](#cloudwatch-logs-rule-action-requirements).
Compatível com [modelos de substituição](iot-substitution-templates.md): Não
(opcional) `batchMode`
Indica se lotes de registros de log serão extraídos e enviados para. CloudWatch Os valores incluem `true` ou `false` (padrão). Para obter mais informações, consulte [Requisitos](#cloudwatch-logs-rule-action-requirements).
Compatível com [modelos de substituição](iot-substitution-templates.md): Não
## Exemplos
O exemplo de JSON a seguir define uma ação de CloudWatch registros em uma AWS IoT regra.
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"cloudwatchLogs": {
"logGroupName": "IotLogs",
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_cw",
"batchMode": false
}
}
]
}
}
```
## Consulte também
+ [O que é o Amazon CloudWatch Logs?](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/) no *Guia do usuário do Amazon CloudWatch Logs*
# CloudWatch métricas
A ação CloudWatch metric (`cloudwatchMetric`) captura uma CloudWatch métrica da Amazon. Você pode especificar o namespace, nome, valor, unidade e marcação de data e hora da métrica.
## Requisitos
Esta ação de regra tem os seguintes requisitos:
+ Uma função do IAM que AWS IoT você pode assumir para realizar a `cloudwatch:PutMetricData` operação. Para obter mais informações, consulte [Conceder a uma AWS IoT regra o acesso que ela exige](iot-create-role.md).
No AWS IoT console, você pode escolher ou criar uma função para permitir AWS IoT a execução dessa ação de regra.
## Parâmetros
Ao criar uma AWS IoT regra com essa ação, você deve especificar as seguintes informações:
`metricName`
O nome da CloudWatch métrica.
Compatível com [modelos de substituição](iot-substitution-templates.md): Sim
`metricNamespace`
O nome do namespace CloudWatch métrico.
Compatível com [modelos de substituição](iot-substitution-templates.md): Sim
`metricUnit`
A unidade métrica suportada por CloudWatch.
Compatível com [modelos de substituição](iot-substitution-templates.md): Sim
`metricValue`
Uma string que contém o valor da CloudWatch métrica.
Compatível com [modelos de substituição](iot-substitution-templates.md): Sim
`metricTimestamp`
(Opcional) que contém o carimbo de data/hora, expresso em segundos na época do Unix. O padrão é a época atual do Unix.
Compatível com [modelos de substituição](iot-substitution-templates.md): Sim
`roleArn`
A função do IAM que permite acesso à CloudWatch métrica. Para obter mais informações, consulte [Requisitos](#cloudwatch-metrics-rule-action-requirements).
Compatível com [modelos de substituição](iot-substitution-templates.md): Não
## Exemplos
O exemplo de JSON a seguir define uma ação CloudWatch métrica em uma AWS IoT regra.
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"cloudwatchMetric": {
"metricName": "IotMetric",
"metricNamespace": "IotNamespace",
"metricUnit": "Count",
"metricValue": "1",
"metricTimestamp": "1456821314",
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_cw"
}
}
]
}
}
```
O exemplo de JSON a seguir define uma ação CloudWatch métrica com modelos de substituição em uma AWS IoT regra.
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"cloudwatchMetric": {
"metricName": "${topic()}",
"metricNamespace": "${namespace}",
"metricUnit": "${unit}",
"metricValue": "${value}",
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_cw"
}
}
]
}
}
```
## Consulte também
+ [O que é a Amazon CloudWatch?](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/) no *Guia do CloudWatch usuário da Amazon*
+ [Usando CloudWatch métricas da Amazon](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/working_with_metrics.html) no *Guia do CloudWatch usuário da Amazon*
# DynamoDB
A ação DynamoDB(`dynamoDB`) grava toda ou parte de uma mensagem MQTT em uma tabela do Amazon DynamoDB.
Você pode seguir um tutorial que mostra como criar e testar uma regra com uma ação do DynamoDB. Para obter mais informações, consulte [Tutorial: Armazenamento de dados do dispositivo em uma tabela do DynamoDB](iot-ddb-rule.md).
**nota**
Esta regra grava dados não JSON no DynamoDB como dados binários. O console do DynamoDB exibe os dados como texto codificado em Base64.
## Requisitos
Esta ação de regra tem os seguintes requisitos:
+ Uma função do IAM que AWS IoT você pode assumir para realizar a `dynamodb:PutItem` operação. Para obter mais informações, consulte [Conceder a uma AWS IoT regra o acesso que ela exige](iot-create-role.md).
No AWS IoT console, você pode escolher ou criar uma função para permitir AWS IoT a execução dessa ação de regra.
+ Se você usa uma chave gerenciada pelo cliente AWS KMS key (chave KMS) para criptografar dados em repouso no DynamoDB, o serviço deve ter permissão para usar a chave KMS em nome do chamador. Para obter mais informações, consulte a [chave KMS gerenciada pelo cliente](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/encryption.howitworks.html#managed-cmk-customer-managed) no *Guia de conceitos básicos do Amazon DynamoDB*.
## Parâmetros
Ao criar uma AWS IoT regra com essa ação, você deve especificar as seguintes informações:
`tableName`
O nome da tabela do DynamoDB.
Suporta [modelos de substituição](iot-substitution-templates.md): API e somente AWS CLI
`hashKeyField`
O nome da chave de hash (também chamada de chave de partição).
Suporta [modelos de substituição](iot-substitution-templates.md): API e somente AWS CLI
`hashKeyType`
(Opcional) O tipo de dados da chave de hash (também chamada de chave de partição). Valores válidos: `STRING`, `NUMBER`.
Suporta [modelos de substituição](iot-substitution-templates.md): API e somente AWS CLI
`hashKeyValue`
O valor da chave de hash. Considere usar um modelo de substituição, como `${topic()}` ou `${timestamp()}`.
Compatível com [modelos de substituição](iot-substitution-templates.md): Sim
`rangeKeyField`
(Opcional) O nome da chave de intervalo (também chamada de chave de classificação).
Suporta [modelos de substituição](iot-substitution-templates.md): API e somente AWS CLI
`rangeKeyType`
(Opcional) O tipo de dados da chave de intervalo (também chamada de chave de classificação). Valores válidos: `STRING`, `NUMBER`.
Suporta [modelos de substituição](iot-substitution-templates.md): API e somente AWS CLI
`rangeKeyValue`
(Opcional) O valor da chave de intervalo. Considere usar um modelo de substituição, como `${topic()}` ou `${timestamp()}`.
Compatível com [modelos de substituição](iot-substitution-templates.md): Sim
`payloadField`
(Opcional) O nome da coluna em que a carga útil é gravada. Se esse valor for omitido, a carga útil será gravada na coluna nomeada `payload`.
Compatível com [modelos de substituição](iot-substitution-templates.md): Sim
`operation`
(Opcional) O tipo de operação a executar. Valores válidos: `INSERT`, `UPDATE`, `DELETE`.
Compatível com [modelos de substituição](iot-substitution-templates.md): Sim
`roleARN`
O perfil do IAM que permite o acesso à tabela do DynamoDB. Para obter mais informações, consulte [Requisitos](#dynamodb-rule-action-requirements).
Compatível com [modelos de substituição](iot-substitution-templates.md): Não
Os dados gravados na tabela do DynamoDB são o resultado da instrução SQL da regra.
## Exemplos
O exemplo de JSON a seguir define uma ação do DynamoDB em uma regra. AWS IoT
```
{
"topicRulePayload": {
"sql": "SELECT * AS message FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"dynamoDB": {
"tableName": "my_ddb_table",
"hashKeyField": "key",
"hashKeyValue": "${topic()}",
"rangeKeyField": "timestamp",
"rangeKeyValue": "${timestamp()}",
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_dynamoDB"
}
}
]
}
}
```
## Consulte também
+ [O que é o Amazon DynamoDB?](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/) no *Guia do desenvolvedor do Amazon DynamoDB*
+ [Conceitos básicos do DynamoDB](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/GettingStartedDynamoDB.html) no *Guia do desenvolvedor do Amazon DynamoDB*
+ [Tutorial: Armazenamento de dados do dispositivo em uma tabela do DynamoDB](iot-ddb-rule.md)
# Dínamo DBv2
A ação Dynamo DBv2 (`dynamoDBv2`) grava toda ou parte de uma mensagem MQTT em uma tabela do Amazon DynamoDB. Cada atributo na carga útil é gravado em uma coluna separada no banco de dados DynamoDB.
## Requisitos
Esta ação de regra tem os seguintes requisitos:
+ Uma função do IAM que AWS IoT você pode assumir para realizar a `dynamodb:PutItem` operação. Para obter mais informações, consulte [Conceder a uma AWS IoT regra o acesso que ela exige](iot-create-role.md).
No AWS IoT console, você pode escolher ou criar uma função para permitir AWS IoT a execução dessa ação de regra.
+ A carga útil da mensagem MQTT deve conter uma chave de nível raiz que corresponda à chave de partição primária da tabela e uma chave de nível raiz que corresponda à chave de classificação primária da tabela, se alguma estiver definida.
+ Se você usa uma chave gerenciada pelo cliente AWS KMS key (chave KMS) para criptografar dados em repouso no DynamoDB, o serviço deve ter permissão para usar a chave KMS em nome do chamador. Para obter mais informações, consulte a [chave KMS gerenciada pelo cliente](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/encryption.howitworks.html#managed-cmk-customer-managed) no *Guia de conceitos básicos do Amazon DynamoDB*.
## Parâmetros
Ao criar uma AWS IoT regra com essa ação, você deve especificar as seguintes informações:
`putItem`
Um objeto que especifica a tabela do DynamoDB na qual os dados da mensagem serão gravados. Este objeto deve conter as seguintes informações:
`tableName`
O nome da tabela do DynamoDB.
Suporta [modelos de substituição](iot-substitution-templates.md): API e somente AWS CLI
`roleARN`
O perfil do IAM que permite o acesso à tabela do DynamoDB. Para obter mais informações, consulte [Requisitos](#dynamodb-v2-rule-action-requirements).
Compatível com [modelos de substituição](iot-substitution-templates.md): Não
Os dados gravados na tabela do DynamoDB são o resultado da instrução SQL da regra.
## Exemplos
O exemplo de JSON a seguir define uma DBv2 ação do Dynamo em uma AWS IoT regra.
```
{
"topicRulePayload": {
"sql": "SELECT * AS message FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"dynamoDBv2": {
"putItem": {
"tableName": "my_ddb_table"
},
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_dynamoDBv2",
}
}
]
}
}
```
O exemplo de JSON a seguir define uma ação do DynamoDB com modelos de substituição em uma regra. AWS IoT
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2015-10-08",
"actions": [
{
"dynamoDBv2": {
"putItem": {
"tableName": "${topic()}"
},
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_dynamoDBv2"
}
}
]
}
}
```
## Consulte também
+ [O que é o Amazon DynamoDB?](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/) no *Guia do desenvolvedor do Amazon DynamoDB*
+ [Conceitos básicos do DynamoDB](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/GettingStartedDynamoDB.html) no *Guia do desenvolvedor do Amazon DynamoDB*
# Elasticsearch
A ação Elasticsearch (`elasticsearch`) grava dados de mensagens MQTT em um domínio do Amazon OpenSearch Service. Em seguida, você pode usar ferramentas como OpenSearch painéis para consultar e visualizar dados no OpenSearch Service.
**Atenção**
A ação `Elasticsearch` só pode ser usada por ações de regras existentes. Para criar uma nova ação de regra ou atualizar uma existente, use a ação de regra `OpenSearch`. Para obter mais informações, consulte [OpenSearch](opensearch-rule-action.md).
## Requisitos
Esta ação de regra tem os seguintes requisitos:
+ Uma função do IAM que AWS IoT você pode assumir para realizar a `es:ESHttpPut` operação. Para obter mais informações, consulte [Conceder a uma AWS IoT regra o acesso que ela exige](iot-create-role.md).
No AWS IoT console, você pode escolher ou criar uma função para permitir AWS IoT a execução dessa ação de regra.
+ Se você usar uma chave gerenciada pelo cliente AWS KMS key (chave KMS) para criptografar dados em repouso OpenSearch, o serviço deverá ter permissão para usar a chave KMS em nome do chamador. Para obter mais informações, consulte [Criptografia de dados em repouso para o Amazon OpenSearch Service](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/encryption-at-rest.html) no *Amazon OpenSearch Service Developer Guide*.
## Parâmetros
Ao criar uma AWS IoT regra com essa ação, você deve especificar as seguintes informações:
`endpoint`
O endpoint do seu domínio de serviço.
Suporta [modelos de substituição](iot-substitution-templates.md): API e somente AWS CLI
`index`
O índice onde você deseja armazenar seus dados.
Compatível com [modelos de substituição](iot-substitution-templates.md): Sim
`type`
O tipo de documento que você está armazenando.
Compatível com [modelos de substituição](iot-substitution-templates.md): Sim
`id`
O identificador exclusivo de cada documento.
Compatível com [modelos de substituição](iot-substitution-templates.md): Sim
`roleARN`
A função do IAM que permite acesso ao domínio do OpenSearch Serviço. Para obter mais informações, consulte [Requisitos](#elasticsearch-rule-action-requirements).
Compatível com [modelos de substituição](iot-substitution-templates.md): Não
## Exemplos
O exemplo de JSON a seguir define uma ação do Elasticsearch em uma AWS IoT regra e como você pode especificar os campos para a ação. `elasticsearch` Para obter mais informações, consulte [ElasticsearchAction](https://docs.aws.amazon.com/iot/latest/apireference/API_ElasticsearchAction.html).
```
{
"topicRulePayload": {
"sql": "SELECT *, timestamp() as timestamp FROM 'iot/test'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"elasticsearch": {
"endpoint": "https://my-endpoint",
"index": "my-index",
"type": "my-type",
"id": "${newuuid()}",
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_es"
}
}
]
}
}
```
O exemplo de JSON a seguir define uma ação do Elasticsearch com modelos de substituição em uma regra. AWS IoT
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"elasticsearch": {
"endpoint": "https://my-endpoint",
"index": "${topic()}",
"type": "${type}",
"id": "${newuuid()}",
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_es"
}
}
]
}
}
```
## Consulte também
+ [OpenSearch](opensearch-rule-action.md)
+ [O que é o Amazon OpenSearch Service?](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/)
# HTTP
A ação HTTPS (`http`) envia dados de uma mensagem MQTT para um endpoint HTTPS, que pode apontar para um aplicativo ou serviço web.
## Requisitos
Esta ação de regra tem os seguintes requisitos:
+ Você deve confirmar e ativar os endpoints HTTPS antes que o mecanismo de regras possa usá-los. Para obter mais informações, consulte [Destinos de ação HTTP](http-action-destination.md).
## Parâmetros
Ao criar uma AWS IoT regra com essa ação, você deve especificar as seguintes informações:
`url`
O endpoint HTTPS para o qual a mensagem é enviada usando o método HTTP POST. Se você usar um endereço IP no lugar de um nome de host, ele deverá ser um IPv4 endereço. IPv6 endereços não são suportados.
Compatível com [modelos de substituição](iot-substitution-templates.md): Sim
`confirmationUrl`
(Opcional) Se especificado, AWS IoT usa o URL de confirmação para criar um destino de regra de tópico correspondente. Você deve habilitar o destino da ação HTTP antes de usá-la em uma ação HTTP. Para obter mais informações, consulte [Destinos de ação HTTP](http-action-destination.md). Se você usar modelos de substituição, deverá criar manualmente um destino de ação HTTP antes que a `http` ação possa ser usada. `confirmationUrl`deve ser um prefixo de. `url`
A relação entre `url` e `confirmationUrl` é descrita pelo seguinte:
+ Se `url` estiver codificado e não `confirmationUrl` for fornecido, tratamos implicitamente o `url` campo como o. `confirmationUrl` AWS IoT cria um destino de regra de tópico para`url`.
+ Se `url` e `confirmationUrl` estiverem codificados, `url` deve começar com. `confirmationUrl` AWS IoT cria um destino de regra de tópico para`confirmationUrl`.
+ Se `url` contiver um modelo de substituição, você deverá especificar `confirmationUrl` e `url` deverá começar com `confirmationUrl`. Se `confirmationUrl` contiver modelos de substituição, você deverá criar manualmente um destino de ação HTTP antes que a `http` ação possa ser usada. Se `confirmationUrl` não contiver modelos de substituição, AWS IoT cria um destino de regra de tópico para`confirmationUrl`.
Compatível com [modelos de substituição](iot-substitution-templates.md): Sim
`headers`
(Opcional) A lista de cabeçalhos a serem incluídos nas solicitações HTTP para o endpoint. Cada cabeçalho deve conter as seguintes informações:
`key`
A chave do cabeçalho.
Compatível com [modelos de substituição](iot-substitution-templates.md): Não
`value`
O valor do cabeçalho.
Compatível com [modelos de substituição](iot-substitution-templates.md): Sim
O tipo de conteúdo padrão é application/json quando a carga está no formato JSON. Caso contrário, é application/octet-stream. Você pode substituí-lo especificando o tipo de conteúdo exato no cabeçalho com o tipo de conteúdo da chave (sem distinção entre maiúsculas e minúsculas).
`auth`
(Opcional) A autenticação usada pelo mecanismo de regras para se conectar ao URL do endpoint especificado no argumento `url`. Atualmente, o Signature versão 4 é o único tipo de autenticação suportado. Para obter mais informações, consulte [Autorização HTTP](https://docs.aws.amazon.com/iot/latest/apireference/API_HttpAuthorization.html).
Compatível com [modelos de substituição](iot-substitution-templates.md): Não
`enableBatching`
(Opcional) Se as mensagens de ação HTTP devem ser processadas em uma única solicitação para um determinado URL. O valor pode ser verdadeiro ou falso. Para obter mais informações sobre agrupamento em lotes, consulte Mensagens de [ação HTTP em lotes](http_batching.md).
Valor booleano
Compatível com [modelos de substituição](iot-substitution-templates.md): Não
`batchConfig`
(Opcional) Configurações para agrupamento em lotes. Depois de ativados, `batchConfig` os parâmetros devem ser especificados. Se `batchConfig` os parâmetros não forem especificados, os valores padrão serão usados.
`maxBatchOpenMs`
O tempo máximo (em milissegundos) que uma mensagem de saída espera por outras mensagens para criar o lote. Quanto maior a configuração, maior a latência da ação HTTP em lote.
Valor mínimo: 5 ms. Valor máximo: 200 ms.
Valor padrão: 20 ms
Compatível com [modelos de substituição](iot-substitution-templates.md): Não
`maxBatchSize`
O número máximo de mensagens que são agrupadas em lotes em uma única execução de ação.
Compatível com [modelos de substituição](iot-substitution-templates.md): Não
Valor mínimo: 2 mensagens. Valor máximo: 10 mensagens
Valor padrão: 10 mensagens
`maxBatchSizeBytes`
Tamanho máximo de um lote de mensagens, em bytes.
Valor mínimo: 100 bytes. Valor máximo: 131.072 bytes
Valor padrão: 5.120 bytes
Compatível com [modelos de substituição](iot-substitution-templates.md): Não
O tipo de conteúdo padrão é application/json quando a carga está no formato JSON. Caso contrário, é application/octet-stream. Você pode substituí-lo especificando o tipo de conteúdo exato no cabeçalho com o tipo de conteúdo da chave (sem distinção entre maiúsculas e minúsculas).
## Exemplos
O exemplo de JSON a seguir define uma AWS IoT regra com uma ação HTTP.
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"http": {
"url": "https://www.example.com/subpath",
"confirmationUrl": "https://www.example.com",
"headers": [
{
"key": "static_header_key",
"value": "static_header_value"
},
{
"key": "substitutable_header_key",
"value": "${value_from_payload}"
}
]
}
}
]
}
}
```
```
"http": {
"url": "https://www.example.com/subpath",
"confirmationUrl": "https://www.example.com",
"headers": [
{
"key": "Content-Type",
"value": "application/json"
}
],
"enableBatching": true,
"batchConfig": {
"maxBatchOpenMs": 123,
"maxBatchSize": 5,
"maxBatchSizeBytes": 131072,
}
},
"errorAction": {
"http": {
"url": "https://www.example.com/subpath",
"confirmationUrl": "https://www.example.com"
// batchConfig is not allowed here
}
}
```
## Lógica de repetição da ação HTTP
O mecanismo de AWS IoT regras tenta novamente a ação HTTP de acordo com estas regras:
+ O mecanismo de regras tenta enviar uma mensagem pelo menos uma vez.
+ O mecanismo de regras tenta novamente no máximo duas vezes. O número máximo de tentativas é três.
+ O mecanismo de regras não fará uma nova tentativa se:
+ A tentativa anterior tiver fornecido uma resposta maior do que 16.384 bytes.
+ O serviço ou aplicativo web downstream fechar a conexão TCP após a tentativa.
+ O tempo total para concluir uma solicitação com repetições tiver excedido o limite de tempo limite da solicitação.
+ A solicitação retorna um código de status HTTP diferente de 429, 500–599.
**nota**
[Custos padrão de transferência de dados](https://aws.amazon.com/ec2/pricing/on-demand/) se aplicam a novas tentativas.
## Consulte também
+ [Agrupar mensagens de ação HTTP em lote](http_batching.md)
+ [Destinos de ação HTTP](http-action-destination.md)
+ [Encaminhe dados diretamente AWS IoT Core para seus serviços da Web](https://aws.amazon.com/blogs/iot/route-data-directly-from-iot-core-to-your-web-services/) na *Internet das Coisas no AWS* blog
# Agrupar mensagens de ação HTTP em lote
Você pode usar o agrupamento em lotes para enviar várias mensagens de ação HTTP em uma única solicitação.
## Visão geral do
O agrupamento em lotes permite que você envie mensagens do AWS IoT Core Rules Engine para seus endpoints HTTP em lotes. Essa funcionalidade pode ajudar a reduzir seus custos diminuindo o número de execuções de ações HTTP, bem como melhorar a eficiência ao reduzir a sobrecarga associada ao estabelecimento de novas conexões.
**nota**
A ação HTTP em lote é medida como uma única ação. Você é medido em incrementos de 5 KiB, com base no tamanho da carga útil em lote de saída emitida pelo Mecanismo de AWS IoT Core Regras para o serviço downstream. Para obter mais informações, consulte a [página de definição de preços do AWS IoT Core](https://aws.amazon.com/iot-core/pricing/).
Quando você ativa o agrupamento em lotes na definição de sua Ação de Regra de IoT, os seguintes parâmetros estarão disponíveis para configuração:
`maxBatchOpenMs`
O tempo máximo (em milissegundos) que uma mensagem de saída espera por outras mensagens para criar o lote. Quanto maior a configuração, maior a latência da ação HTTP em lote.
Valor mínimo: 5 ms. Valor máximo: 200 ms.
Valor padrão: 20 ms
Compatível com [modelos de substituição](iot-substitution-templates.md): Não
`maxBatchSize`
O número máximo de mensagens que são agrupadas em lotes em uma única execução de ação de regra de IoT.
Valor mínimo: 2 mensagens. Valor máximo: 10 mensagens
Valor padrão: 10 mensagens
Compatível com [modelos de substituição](iot-substitution-templates.md): Não
`maxBatchSizeBytes`
Tamanho máximo de um lote de mensagens, em bytes.
Valor mínimo: 100 bytes. Valor máximo: 131.072 bytes
Valor padrão: 5120 bytes
Compatível com [modelos de substituição](iot-substitution-templates.md): Não
**Importante**
Quando você especifica vários parâmetros de lote, o lote é concluído quando o primeiro limite é atingido. Por exemplo, se você especificar 100 ms como o Tempo Máximo de Abertura do Lote e 5 KiB como o Tamanho Máximo do Lote, e o Rules Engine agrupar somente 2 KiB em 100 ms, um lote de 2 KiB será criado e enviado.
## Usando cabeçalhos HTTP em um lote
Quando você usa cabeçalhos em sua ação HTTP, a solicitação em lote usa o valor do cabeçalho da última mensagem que foi adicionada ao lote (não necessariamente a última mensagem que você publicou). Recomendamos usar valores de cabeçalho que sejam:
+ Idêntico em todas as mensagens do lote
+ Aplicável a todas as mensagens (por exemplo, credenciais de autenticação)
Os cabeçalhos são enviados com a solicitação HTTP e não fazem parte do corpo da mensagem.
**nota**
Quando o agrupamento em lotes está ativado:
A solicitação em lote inclui automaticamente o `Content-Type: application/json` cabeçalho, pois o lote é enviado como uma matriz JSON.
Não podemos garantir que a última mensagem do lote seja a última mensagem que você publicou. É a última mensagem que entrou no lote.
## Exemplo de carga
O exemplo a seguir mostra a estrutura de uma carga de mensagens em lote enviada ao seu endpoint HTTP:
```
[
{
"user_id": "user1",
"steps_today": 1000
},
{
"user_id": "user2",
"steps_today": 21000
},
{
"user_id": "user8",
"steps_today": 1500
},
...
]
```
## Limitações
A seguir estão as limitações do agrupamento em lotes:
+ AWS IoT Core não garante a ordem geral das mensagens. O agrupamento em lotes é realizado localmente em cada host, o que pode fazer com que as mensagens dentro de um lote sejam processadas em uma ordem diferente da que foram recebidas.
+ AWS IoT Core não fornece suporte ao processamento de mensagens no lado do receptor. Você é responsável por garantir que seu serviço downstream esteja configurado para aceitar e processar dados em lotes.
+ O agrupamento em lotes entre contas não é suportado, mesmo que as mensagens sejam destinadas ao mesmo identificador de recurso (URL HTTP ou ARN do recurso).
+ AWS IoT Core não garante que o tamanho do lote atenda à configuração especificada. Os lotes podem ser menores do que os limites configurados com base no tempo e no fluxo de mensagens.
+ Quando o agrupamento em lotes está ativado, cargas binárias (dados não UTF-8) não são suportadas. Somente cargas de texto UTF-8 (como JSON) são aceitas. Para enviar dados binários, codifice-os em base64 antes de enviá-los para a ação HTTP e, em seguida, decodifique-os no ponto final de recebimento. Por exemplo, você pode usar a [função de codificação](iot-sql-functions.html#iot-function-encode) nas regras de IoT para codificar a carga binária. Como alternativa, você pode codificar a carga binária em seu dispositivo de IoT e publicá-la no. AWS IoT Core
## Ações de erro para agrupamento em lotes
Você não poderá definir uma lógica de lote separada em sua definição de Ação de Erro. No entanto, sua ação de erro suportará o agrupamento em lotes se você tiver definido a lógica de lote em sua ação principal.
Quando uma solicitação em lote falha, o mecanismo de AWS IoT Core regras segue a [lógica de repetição da ação HTTP](https-rule-action.md#https-rule-action-retry-logic). Após a última tentativa de repetição, uma ação de erro será invocada para todo o lote com falha.
Veja a seguir um exemplo de uma mensagem de ação de erro com o agrupamento em lotes ativado:
```
{
"ruleName": "FailedTopicRule",
"topic": "topic/rulesengine",
"payloadsWithMetadata": [
{
"id": 1,
"cloudwatchTraceId": "bebd6d93-6d4a-899e-9e40-56e82252d2be",
"clientId": "Test",
"sourceIp": "10.0.0.0",
"base64OriginalPayload": "eyJ1c2VyX2lkIjogInVzZXI1NjQ3IiwgInN0ZXBzX3RvZGF5IjogMTMzNjUsICJ0aW1lc3RhbXAiOiAiMjAyNS0xMC0wOVQwNzoyMjo1OC45ODQ3OTAxNzZaIn0="
},
{
"id": 2,
"cloudwatchTraceId": "af94d3b8-0b18-1dbf-2c7d-513f5cb9e2e1",
"clientId": "Test",
"sourceIp": "10.0.0.0",
"base64OriginalPayload": "eyJ1c2VyX2lkIjogInVzZXI1NjQ3IiwgInN0ZXBzX3RvZGF5IjogMTMzNjUsICJ0aW1lc3RhbXAiOiAiMjAyNS0xMC0wOVQwNzoyMjo1OC45ODQ3OTAxNzZaIn0="
},
{
"id": 3,
"cloudwatchTraceId": "ca441266-c2ce-c916-6aee-b9e5c7831675",
"clientId": "Test",
"sourceIp": "10.0.0.0",
"base64OriginalPayload": "eyJ1c2VyX2lkIjogInVzZXI1NjQ3IiwgInN0ZXBzX3RvZGF5IjogMTMzNjUsICJ0aW1lc3RhbXAiOiAiMjAyNS0xMC0wOVQwNzoyMjo1OC45ODQ3OTAxNzZaIn0="
}
],
"failures": [
{
"affectedIds": [
1,
2,
3
],
"failedAction": "HttpAction",
"failedResource": "https://example.foobar.com/HttpAction",
"errorMessage": "HttpAction failed to make a request to the specified endpoint. StatusCode: 500. Reason: Internal Server Error."
},
{
"affectedIds": [
3
],
"failedAction": "S3Action",
"failedResource": "amzn-s3-demo-bucket",
"errorMessage": "Failed to put S3 object. The error received was The specified bucket does not exist"
},
{
"affectedIds": [
3
],
"failedAction": "LambdaAction",
"failedResource": "arn:aws:lambda:us-west-2:123456789012:function:dummy",
"errorMessage": "Failed to invoke lambda function. Received Server error from Lambda. The error code is 403"
}
]
}
```
**nota**
Falhas de ação em lote também geram cargas de ação de erro maiores, o que pode aumentar a probabilidade de falhas de ação de erro devido ao tamanho. Você pode monitorar falhas na ação de erro usando a `ErrorActionFailure` métrica. Consulte [Métricas de ação da regra](metrics_dimensions.md#rule-action-metrics) para obter mais informações.
## Envio de mensagens de ação HTTP em lote com o AWS CLI
### Criação ou atualização de uma ação de regra com o agrupamento em lotes
1. Use o AWS CLI comando apropriado para criar ou atualizar uma regra:
+ Para criar uma nova regra, use o [create-topic-rule](https://docs.aws.amazon.com/cli/latest/reference/iot/create-topic-rule.html)comando:
```
aws iot create-topic-rule --rule-name myrule --topic-rule-payload file://myrule.json
```
+ Para atualizar uma regra existente, use o [replace-topic-rule](https://docs.aws.amazon.com/cli/latest/reference/iot/replace-topic-rule.html)comando:
```
aws iot replace-topic-rule --rule-name myrule --topic-rule-payload file://myrule.json
```
1. Ative os recursos de agrupamento em lotes definindo o parâmetro enableBatching como verdadeiro na carga útil da regra de tópico:
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"http": {
"url": "https://www.example.com/subpath",
"confirmationUrl": "https://www.example.com",
"headers": [
{
"key": "static_header_key",
"value": "static_header_value"
},
{
"key": "substitutable_header_key",
"value": "${value_from_payload}"
}
],
"enableBatching": true,
"batchConfig": {
"maxBatchOpenMs": 100,
"maxBatchSize": 5,
"maxBatchSizeBytes": 1024
}
}
}
]
}
```
1. Configure os parâmetros de agrupamento em lotes. Você não precisa especificar todos os parâmetros do lote. Você pode optar por especificar 1, 2 ou todos os 3 parâmetros de lote. Se você não especificar um parâmetro de lote, o Mecanismo de Regras atualizará esse parâmetro com os valores padrão. Para obter mais informações sobre parâmetros de lote e seus valores padrão, consulte [Parâmetros HTTP](https-rule-action.md#https-rule-action-parameters).
# Destinos de ação HTTP
Um destino de ação HTTP é um serviço da Web para o qual o mecanismo de regras pode rotear dados de uma regra de tópico. Um AWS IoT Core recurso descreve o serviço web para AWS IoT. Os recursos de destino podem ser compartilhados por regras diferentes.
Antes de AWS IoT Core poder enviar dados para outro serviço da Web, ele deve confirmar que pode acessar o endpoint do serviço.
## Visão geral do
Um destino de ação HTTP se refere a um serviço da Web que oferece suporte a uma URL de confirmação e a uma ou mais coletas de dados URLs. O recurso de destino contém o URL de confirmação do seu serviço web. Ao configurar uma ação HTTP, você especifica a URL real do endpoint que deve receber os dados junto com a URL de confirmação do serviço web. Após a confirmação do destino, a regra do tópico envia o resultado da instrução SQL para o endpoint HTTPS (e não para a URL de confirmação).
O destino de uma ação HTTP pode estar em um dos seguintes estados:
ENABLED
O destino foi confirmado e pode ser usado por uma ação de regra. Um destino deve estar no estado `ENABLED` para que seja usado em uma regra. Você só pode habilitar destinos com status DISABLED.
DISABLED
O destino foi confirmado mas não pode ser usado por uma ação de regra. Isso é útil se você quiser impedir temporariamente o tráfego para seu endpoint sem precisar passar pelo processo de confirmação novamente. Você só pode desabilitar destinos com status ENABLED.
IN\$1PROGRESS
A confirmação do destino está em andamento.
ERRO
A confirmação do destino expirou.
Depois que um destino de ação HTTP for confirmado e ativado, ele poderá ser usado com qualquer regra em sua conta.
## Gerenciando destinos de ações HTTP
Você pode usar as operações a seguir para gerenciar seus destinos de ação HTTP.
### Criação de destinos de ação HTTP
Você cria um destino de ação HTTP chamando a `CreateTopicRuleDestination` operação ou usando o AWS IoT console.
Depois de criar um destino, AWS IoT envia uma solicitação de confirmação para o URL de confirmação. A solicitação de confirmação tem o seguinte formato:
```
HTTP POST {confirmationUrl}/?confirmationToken={confirmationToken}
Headers:
x-amz-rules-engine-message-type: DestinationConfirmation
x-amz-rules-engine-destination-arn:"arn:aws:iot:us-east-1:123456789012:ruledestination/http/7a280e37-b9c6-47a2-a751-0703693f46e4"
Content-Type: application/json
Body:
{
"arn":"arn:aws:iot:us-east-1:123456789012:ruledestination/http/7a280e37-b9c6-47a2-a751-0703693f46e4",
"confirmationToken": "AYADeMXLrPrNY2wqJAKsFNn-…NBJndA",
"enableUrl": "https://iot.us-east-1.amazonaws.com/confirmdestination/AYADeMXLrPrNY2wqJAKsFNn-…NBJndA",
"messageType": "DestinationConfirmation"
}
```
O conteúdo do pedido de confirmação inclui as seguintes informações:
arn
O Amazon Resource Name (ARN) do destino da ação HTTP a ser confirmado.
confirmationToken
O token de confirmação enviado por AWS IoT Core. O token no exemplo é truncado. Seu token será mais longo. Você precisará desse token para confirmar seu destino em AWS IoT Core.
enableUrl
O URL para o qual você navega para confirmar um destino de regra de tópico.
messageType
O tipo de mensagem.
### Confirmando destinos de ações HTTP
Para concluir o processo de confirmação do endpoint, se você estiver usando a AWS CLI, deverá realizar as seguintes etapas após o URL de confirmação receber a solicitação de confirmação.
1.
**Confirme se o destino está pronto para receber mensagens**
Para confirmar se o destino da ação HTTP está pronto para receber mensagens de IoT, chame o `enableUrl` na solicitação de confirmação ou execute a operação da `ConfirmTopicRuleDestination` API e transmita a `confirmationToken` partir da solicitação de confirmação.
1.
**Defina o status da regra de tópico como ativado**
Depois de confirmar que o destino pode receber mensagens, você deve realizar a operação de API `UpdateTopicRuleDestination` para definir o status da regra de tópico como `ENABLED`.
Se você estiver usando o AWS IoT console, `confirmationToken` copie e cole na caixa de diálogo de confirmação do destino no AWS IoT console. Em seguida, você pode ativar a regra do tópico.
### Enviando uma nova solicitação de confirmação
Para acionar uma nova mensagem de confirmação para um destino, faça uma chamada para `UpdateTopicRuleDestination` e defina o status do destino da regra de tópico como `IN_PROGRESS`.
Repita o processo de confirmação depois de enviar uma nova solicitação de confirmação.
### Desabilitando e excluindo um destino de ação HTTP
Para desativar um destino, chame `UpdateTopicRuleDestination` e defina o status do destino da regra de tópico como `DISABLED`. Uma regra de tópico no estado DISABLED pode ser ativada novamente sem a necessidade de enviar uma nova solicitação de confirmação.
Para excluir um destino de ação HTTP, chame`DeleteTopicRuleDestination`.
## Support da Autoridade Certificadora
**nota**
Não há suporte para certificados autoassinados.
Os endpoints HTTPS em um destino de ação HTTP oferecem suporte a certificados emitidos pela [Autoridade de Certificação AWS Privada](https://www.amazontrust.com/repository/) e pela [Lets Encrypt](https://letsencrypt.org/certificates/).
# AWS IoT Events
A ação AWS IoT Events (`iotEvents`) envia dados de uma mensagem MQTT para uma AWS IoT Events entrada.
**Importante**
Se a carga for enviada AWS IoT Core sem o`Input attribute Key`, ou se a chave não estiver no mesmo caminho JSON especificado na chave, isso fará com que a regra de IoT falhe com o erro. `Failed to send message to Iot Events`
## Requisitos
Esta ação de regra tem os seguintes requisitos:
+ Uma função do IAM que AWS IoT você pode assumir para realizar a `iotevents:BatchPutMessage` operação. Para obter mais informações, consulte [Conceder a uma AWS IoT regra o acesso que ela exige](iot-create-role.md).
No AWS IoT console, você pode escolher ou criar uma função para permitir AWS IoT a execução dessa ação de regra.
## Parâmetros
Ao criar uma AWS IoT regra com essa ação, você deve especificar as seguintes informações:
`batchMode`
(Opcional) Se as ações do evento devem ser processadas em lote. O valor padrão é `false`.
Quando `batchMode` é `true` e a regra a instrução SQL é avaliada como uma matriz, cada elemento da matriz é tratado como uma mensagem separada quando é enviado para AWS IoT Eventos por meio de uma chamada [https://docs.aws.amazon.com/iotevents/latest/apireference/API_iotevents-data_BatchPutMessage.html](https://docs.aws.amazon.com/iotevents/latest/apireference/API_iotevents-data_BatchPutMessage.html). A matriz resultante não pode ter mais de 10 mensagens.
Quando `batchMode` é `true`, não é possível especificar um `messageId`.
Compatível com [modelos de substituição](iot-substitution-templates.md): Não
`inputName`
O nome da AWS IoT Events entrada.
Suporta [modelos de substituição](iot-substitution-templates.md): API e somente AWS CLI
`messageId`
(Opcional) Use isso para verificar se somente uma entrada (mensagem) com uma determinada `messageId` é processada por um AWS IoT Events detector. Você pode usar o `${newuuid()}` modelo de substituição para gerar uma ID exclusiva para cada solicitação.
Quando `batchMode` estiver `true`, você não poderá especificar um `messageId`—um novo valor de UUID será atribuído.
Compatível com [modelos de substituição](iot-substitution-templates.md): Sim
`roleArn`
A função do IAM que AWS IoT permite enviar uma entrada para um AWS IoT Events detector. Para obter mais informações, consulte [Requisitos](#iotevents-rule-action-requirements).
Compatível com [modelos de substituição](iot-substitution-templates.md): Não
## Exemplos
O exemplo JSON a seguir define uma ação do IoT Events em uma AWS IoT regra.
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"iotEvents": {
"inputName": "MyIoTEventsInput",
"messageId": "${newuuid()}",
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_events"
}
}
]
}
}
```
## Consulte também
+ [O que AWS IoT Eventsé](https://docs.aws.amazon.com/iotevents/latest/developerguide/) no *Guia do AWS IoT Events desenvolvedor*
# AWS IoT SiteWise
A ação AWS IoT SiteWise (`iotSiteWise`) envia dados de uma mensagem MQTT para as propriedades do ativo em AWS IoT SiteWise.
Você pode seguir um tutorial que mostra como ingerir dados de AWS IoT coisas. Para obter mais informações, consulte o tutorial Como [ingerir dados a AWS IoT SiteWise partir de AWS IoT coisas](https://docs.aws.amazon.com/iot-sitewise/latest/userguide/ingest-data-from-iot-things.html) ou a seção Como [ingerir dados usando regras AWS IoT básicas](https://docs.aws.amazon.com/iot-sitewise/latest/userguide/iot-rules.html) no Guia do *AWS IoT SiteWise usuário*.
## Requisitos
Esta ação de regra tem os seguintes requisitos:
+ Uma função do IAM que AWS IoT você pode assumir para realizar a `iotsitewise:BatchPutAssetPropertyValue` operação. Para obter mais informações, consulte [Conceder a uma AWS IoT regra o acesso que ela exige](iot-create-role.md).
Você pode anexar o exemplo de política de confiança a seguir à função.
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "iotsitewise:BatchPutAssetPropertyValue",
"Resource": "*"
}
]
}
```
Para melhorar a segurança, você pode especificar um caminho AWS IoT SiteWise de hierarquia de ativos na `Condition` propriedade. O exemplo a seguir é uma política de confiança que especifica um caminho de hierarquia de ativos.
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "iotsitewise:BatchPutAssetPropertyValue",
"Resource": "*",
"Condition": {
"StringLike": {
"iotsitewise:assetHierarchyPath": [
"/root node asset ID",
"/root node asset ID/*"
]
}
}
}
]
}
```
+ Quando você envia dados para AWS IoT SiteWise com essa ação, seus dados devem atender aos requisitos da `BatchPutAssetPropertyValue` operação. Para obter mais informações, consulte [BatchPutAssetPropertyValue](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_BatchPutAssetPropertyValue.html) na *Referência de APIs do AWS IoT SiteWise *.
## Parâmetros
Ao criar uma AWS IoT regra com essa ação, você deve especificar as seguintes informações:
`putAssetPropertyValueEntries`
Uma lista de entradas de valor de propriedade de ativo, cada uma contendo as seguintes informações:
`propertyAlias`
(Opcional) O alias da propriedade associado à propriedade do seu ativo. É necessário especificar um `propertyAlias`, ou ambos um `assetId` e um `propertyId`. Para obter mais informações sobre alias de propriedade, consulte [Como realizar o mapeamento de fluxos de dados industriais para propriedades de ativos](https://docs.aws.amazon.com/iot-sitewise/latest/userguide/connect-data-streams.html) no *AWS IoT SiteWise Guia do usuário *.
Compatível com [modelos de substituição](iot-substitution-templates.md): Sim
`assetId`
(Opcional) O ID do AWS IoT SiteWise ativo. É necessário especificar um `propertyAlias`, ou ambos um `assetId` e um `propertyId`.
Compatível com [modelos de substituição](iot-substitution-templates.md): Sim
`propertyId`
(Opcional) A ID de uma propriedade de ativo. É necessário especificar um `propertyAlias`, ou ambos um `assetId` e um `propertyId`.
Compatível com [modelos de substituição](iot-substitution-templates.md): Sim
`entryId`
(Opcional) Um identificador exclusivo para essa entrada. Você pode definir o `entryId` para controlar melhor qual mensagem causou um erro em caso de falha. O padrão é um novo UUID.
Compatível com [modelos de substituição](iot-substitution-templates.md): Sim
`propertyValues`
Uma lista de valores de propriedade a serem inseridos, em que cada um contém carimbo de data/hora, qualidade e valor (TQV) no seguinte formato:
`timestamp`
Uma estrutura de carimbo de data/hora que contém as seguintes informações:
`timeInSeconds`
Uma string que contém o tempo em segundos no horário do Unix epoch. Se a carga de mensagem não tiver um carimbo de data/hora, você poderá usar [timestamp()](iot-sql-functions.md#iot-function-timestamp), que retorna a hora atual em milissegundos. Para converter essa hora em segundos, você pode usar o seguinte modelo de substituição: **\$1\$1floor(timestamp() / 1E3)\$1**.
Compatível com [modelos de substituição](iot-substitution-templates.md): Sim
`offsetInNanos`
(Opcional) Uma string que contém o deslocamento de tempo em nanossegundos da hora em segundos. Se a carga útil de mensagem não tiver um carimbo de data/hora, você poderá usar [timestamp()](iot-sql-functions.md#iot-function-timestamp), que retorna a hora atual em milissegundos. Para calcular o deslocamento em nanossegundos a partir dessa hora, é possível usar o seguinte modelo de substituição: **\$1\$1(timestamp() % 1E3) \$1 1E6\$1**.
Compatível com [modelos de substituição](iot-substitution-templates.md): Sim
Em relação ao Unix epoch time, AWS IoT SiteWise aceita somente entradas que tenham um timestamp de até 7 dias no passado e até 5 minutos no futuro.
`quality`
(Opcional) Uma string que descreve a qualidade do valor. Valores válidos: `GOOD`, `BAD`, `UNCERTAIN`.
Compatível com [modelos de substituição](iot-substitution-templates.md): Sim
`value`
Uma estrutura de valor que contém um dos seguintes campos de valor, dependendo do tipo de dados da propriedade do ativo:
`booleanValue`
(Opcional) Uma string que contém o valor booleano da entrada de valor.
Compatível com [modelos de substituição](iot-substitution-templates.md): Sim
`doubleValue`
(Opcional) Uma string que contém o valor duplo da entrada de valor.
Compatível com [modelos de substituição](iot-substitution-templates.md): Sim
`integerValue`
(Opcional) Uma string que contém o valor inteiro da entrada de valor.
Compatível com [modelos de substituição](iot-substitution-templates.md): Sim
`stringValue`
(Opcional) O valor da string da entrada do valor.
Compatível com [modelos de substituição](iot-substitution-templates.md): Sim
`roleArn`
O ARN da função do IAM que concede AWS IoT permissão para enviar um valor de propriedade do ativo para. AWS IoT SiteWise Para obter mais informações, consulte [Requisitos](#iotsitewise-rule-action-requirements).
Compatível com [modelos de substituição](iot-substitution-templates.md): Não
## Exemplos
O exemplo de JSON a seguir define uma ação básica de SiteWise IoT em AWS IoT uma regra.
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"iotSiteWise": {
"putAssetPropertyValueEntries": [
{
"propertyAlias": "/some/property/alias",
"propertyValues": [
{
"timestamp": {
"timeInSeconds": "${my.payload.timeInSeconds}"
},
"value": {
"integerValue": "${my.payload.value}"
}
}
]
}
],
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_sitewise"
}
}
]
}
}
```
O exemplo de JSON a seguir define uma ação de SiteWise IoT em AWS IoT uma regra. Esse exemplo usa o tópico como o alias da propriedade e a função `timestamp()`. Por exemplo, se você publicar dados em `/company/windfarm/3/turbine/7/rpm`, essa ação enviará os dados para a propriedade do ativo com um alias da propriedade igual ao tópico especificado.
```
{
"topicRulePayload": {
"sql": "SELECT * FROM '/company/windfarm/+/turbine/+/+'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"iotSiteWise": {
"putAssetPropertyValueEntries": [
{
"propertyAlias": "${topic()}",
"propertyValues": [
{
"timestamp": {
"timeInSeconds": "${floor(timestamp() / 1E3)}",
"offsetInNanos": "${(timestamp() % 1E3) * 1E6}"
},
"value": {
"doubleValue": "${my.payload.value}"
}
}
]
}
],
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_sitewise"
}
}
]
}
}
```
## Consulte também
+ [O que é o AWS IoT SiteWise?](https://docs.aws.amazon.com/iot-sitewise/latest/userguide/what-is-sitewise.html) no *AWS IoT SiteWise Guia do usuário*
+ [Ingestão de dados usando AWS IoT Core regras](https://docs.aws.amazon.com/iot-sitewise/latest/userguide/iot-rules.html) no Guia do *AWS IoT SiteWise usuário*
+ [Ingestão de dados AWS IoT SiteWise de AWS IoT itens](https://docs.aws.amazon.com/iot-sitewise/latest/userguide/ingest-data-from-iot-things.html) no Guia do *AWS IoT SiteWise usuário*
+ [Solução de problemas de uma ação de AWS IoT SiteWise regra](https://docs.aws.amazon.com/iot-sitewise/latest/userguide/troubleshoot-rule.html) no *Guia AWS IoT SiteWise do usuário*
# Firehose
A ação do Firehose (`firehose`) envia dados de uma mensagem MQTT para um stream do Amazon Data Firehose.
## Requisitos
Esta ação de regra tem os seguintes requisitos:
+ Uma função do IAM que AWS IoT você pode assumir para realizar a `firehose:PutRecord` operação. Para obter mais informações, consulte [Conceder a uma AWS IoT regra o acesso que ela exige](iot-create-role.md).
No AWS IoT console, você pode escolher ou criar uma função para permitir AWS IoT a execução dessa ação de regra.
+ Se você usa o Firehose para enviar dados para um bucket do Amazon S3 e usa AWS KMS um cliente AWS KMS key gerenciado para criptografar dados em repouso no Amazon S3, o Firehose deve ter acesso ao seu bucket e permissão para usá-lo em nome do chamador. AWS KMS key Para obter mais informações, consulte [Conceder ao Firehose acesso a um destino do Amazon S3](https://docs.aws.amazon.com/firehose/latest/dev/controlling-access.html#using-iam-s3) no *Guia do desenvolvedor do Amazon Data Firehose*.
## Parâmetros
Ao criar uma AWS IoT regra com essa ação, você deve especificar as seguintes informações:
`batchMode`
(Opcional) Especifica se o stream do Firehose deve ser entregue como um lote usando [https://docs.aws.amazon.com/firehose/latest/APIReference/API_PutRecordBatch.html](https://docs.aws.amazon.com/firehose/latest/APIReference/API_PutRecordBatch.html). O valor padrão é `false`.
Quando `batchMode` é `true` e a instrução SQL da regra é avaliada para uma matriz, cada elemento da matriz forma um registro na solicitação `PutRecordBatch`. A matriz resultante não pode ter mais de 500 registros.
Compatível com [modelos de substituição](iot-substitution-templates.md): Não
`deliveryStreamName`
O fluxo do Firehose no qual gravar os dados da mensagem.
Suporta [modelos de substituição](iot-substitution-templates.md): API e somente AWS CLI
`separator`
(Opcional) Um separador de caracteres usado para separar registros gravados no stream do Firehose. Se você omitir esse parâmetro, o fluxo não usará separador. Valores válidos: `,` (vírgula), `\t` (tab), `\n` (nova linha), `\r\n` (nova linha do Windows).
Compatível com [modelos de substituição](iot-substitution-templates.md): Não
`roleArn`
O perfil do IAM que concede acesso ao stream do Firehose. Para obter mais informações, consulte [Requisitos](#kinesis-firehose-rule-action-requirements).
Compatível com [modelos de substituição](iot-substitution-templates.md): Não
## Exemplos
O exemplo de JSON a seguir define uma ação Firehose em AWS IoT uma regra.
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"firehose": {
"deliveryStreamName": "my_firehose_stream",
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_firehose"
}
}
]
}
}
```
O exemplo de JSON a seguir define uma ação Firehose com modelos de substituição em uma regra. AWS IoT
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"firehose": {
"deliveryStreamName": "${topic()}",
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_firehose"
}
}
]
}
}
```
## Consulte também
+ [O que é o Amazon Data Firehose?](https://docs.aws.amazon.com/firehose/latest/dev/) no *Guia do desenvolvedor do Amazon Data Firehose*
# Kinesis Data Streams
A ação Kinesis Data Streams (`kinesis`) grava dados de uma mensagem MQTT no Amazon Kinesis Data Streams.
## Requisitos
Esta ação de regra tem os seguintes requisitos:
+ Uma função do IAM que AWS IoT você pode assumir para realizar a `kinesis:PutRecord` operação. Para obter mais informações, consulte [Conceder a uma AWS IoT regra o acesso que ela exige](iot-create-role.md).
No AWS IoT console, você pode escolher ou criar uma função para permitir AWS IoT a execução dessa ação de regra.
+ Se você usa uma chave AWS KMS gerenciada pelo cliente AWS KMS key (chave KMS) para criptografar dados em repouso no Kinesis Data Streams, o serviço deve ter permissão para usá-la em nome do chamador. AWS KMS key Para obter mais informações, consulte [Permissões de uso geradas pelo usuário AWS KMS keys](https://docs.aws.amazon.com/streams/latest/dev/permissions-user-key-KMS.html) no *Guia do desenvolvedor do Amazon Kinesis Data Streams*.
## Parâmetros
Ao criar uma AWS IoT regra com essa ação, você deve especificar as seguintes informações:
`stream`
O fluxo de dados do Kinesis no qual os dados serão gravados.
Suporta [modelos de substituição](iot-substitution-templates.md): API e somente AWS CLI
`partitionKey`
A chave de partição usada para determinar em qual fragmento os dados são gravados. A chave de partição geralmente é composta de uma expressão (por exemplo, `${topic()}` ou `${timestamp()}`).
Compatível com [modelos de substituição](iot-substitution-templates.md): Sim
`roleArn`
O ARN da função do IAM que concede AWS IoT permissão para acessar o stream de dados do Kinesis. Para obter mais informações, consulte [Requisitos](#kinesis-rule-action-requirements).
Compatível com [modelos de substituição](iot-substitution-templates.md): Não
## Exemplos
O exemplo de JSON a seguir define uma ação do Kinesis Data Streams em uma regra. AWS IoT
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"kinesis": {
"streamName": "my_kinesis_stream",
"partitionKey": "${topic()}",
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_kinesis"
}
}
]
}
}
```
O exemplo de JSON a seguir define uma ação do Kinesis com modelos de substituição em uma regra. AWS IoT
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"kinesis": {
"streamName": "${topic()}",
"partitionKey": "${timestamp()}",
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_kinesis"
}
}
]
}
}
```
## Consulte também
+ [O que são fluxos de dados do Amazon Kinesis?](https://docs.aws.amazon.com/streams/latest/dev/) no *Guia do desenvolvedor do Amazon Kinesis Data Streams*
# Lambda
Uma ação Lambda (`lambda`) invoca uma AWS Lambda função, transmitindo uma mensagem MQTT. AWS IoT invoca funções Lambda de forma assíncrona.
Você pode seguir um tutorial que mostra como criar e testar uma regra com uma ação do Lambda. Para obter mais informações, consulte [Tutorial: Formatando uma notificação usando uma função AWS Lambda](iot-lambda-rule.md).
## Requisitos
Esta ação de regra tem os seguintes requisitos:
+ AWS IoT Para invocar uma função Lambda, você deve configurar uma política que conceda `lambda:InvokeFunction` a permissão a. AWS IoT Você só pode invocar uma função do Lambda definida na Região da AWS mesma em que sua política do Lambda existe. As funções do Lambda usam políticas baseadas em recursos; por isso, você precisa anexar a política à própria função do Lambda.
Use o AWS CLI comando a seguir para anexar uma política que conceda a `lambda:InvokeFunction` permissão. Nesse comando, substitua:
+ *function\$1name*com o nome da função Lambda. Você adiciona uma nova permissão para atualizar a política de recursos da função.
+ *region*com o Região da AWS da função.
+ *account-id*com o Conta da AWS número em que a regra está definida.
+ *rule-name*com o nome da AWS IoT regra para a qual você está definindo a ação Lambda.
+ *unique\$1id*com um identificador de declaração exclusivo.
**Importante**
Se você adicionar uma permissão para um AWS IoT principal sem fornecer o `source-arn` ou`source-account`, qualquer um Conta da AWS que crie uma regra com sua ação do Lambda poderá ativar regras para invocar sua função do Lambda. AWS IoT
Para ter mais informações, consulte [AWS Lambda permissões](https://docs.aws.amazon.com/lambda/latest/dg/intro-permission-model.html).
```
aws lambda add-permission \
--function-name function_name \
--region region \
--principal iot.amazonaws.com \
--source-arn arn:aws:iot:region:account-id:rule/rule_name \
--source-account account-id
--statement-id unique_id
--action "lambda:InvokeFunction"
```
+ Se você usar o AWS IoT console para criar uma regra para a ação da regra Lambda, a função Lambda será acionada automaticamente. Se você usar AWS CloudFormation em vez disso com o [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-iot-topicrule-lambdaaction.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-iot-topicrule-lambdaaction.html), deverá adicionar um [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-lambda-permission.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-lambda-permission.html)recurso. O recurso então concede a você permissão para acionar a função do Lambda.
O código a seguir mostra um exemplo de como adicionar esse recurso. Neste exemplo, substitua:
+ *function\$1name*com o nome da função Lambda.
+ *region*com o Região da AWS da função.
+ *account-id*com o Conta da AWS número em que a regra está definida.
+ *rule-name*com o nome da AWS IoT regra para a qual você está definindo a ação Lambda.
```
Type: AWS::Lambda::Permission
Properties:
Action: lambda:InvokeFunction
FunctionName: !Ref function_name
Principal: "iot.amazonaws.com"
SourceAccount: account-id
SourceArn: arn:aws:iot:region:account-id:rule/rule_name
```
+ Se você usa um AWS KMS cliente que conseguiu AWS KMS key criptografar dados em repouso no Lambda, o serviço deve ter permissão para usar AWS KMS key o em nome do chamador. Para obter mais informações, consulte [Criptografia em repouso](https://docs.aws.amazon.com/lambda/latest/dg/security-dataprotection.html#security-privacy-atrest), no *AWS Lambda Guia do Desenvolvedor*.
## Parâmetros
Ao criar uma AWS IoT regra com essa ação, você deve especificar as seguintes informações:
`functionArn`
O ARN da função Lambda a ser invocada. AWS IoT deve ter permissão para invocar a função. Para obter mais informações, consulte [Requisitos](#lambda-rule-action-requirements).
Se você não especificar uma versão ou um alias para sua função do Lambda, a versão mais recente da função será encerrada. Você pode especificar uma versão ou um alias se quiser encerrar uma versão específica da função do Lambda. Para especificar uma versão ou alias, anexe a versão ou pseudônimo ao ARN da função do Lambda.
```
arn:aws:lambda:us-east-2:123456789012:function:myLambdaFunction:someAlias
```
Para obter mais informações sobre versionamento e aliases, consulte [AWS Lambda Versionamento e aliases da função](https://docs.aws.amazon.com/lambda/latest/dg/versioning-aliases.html).
Suporta [modelos de substituição](iot-substitution-templates.md): API e somente AWS CLI
## Exemplos
O exemplo de JSON a seguir define uma ação Lambda em AWS IoT uma regra.
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"lambda": {
"functionArn": "arn:aws:lambda:us-east-2:123456789012:function:myLambdaFunction"
}
}
]
}
}
```
O exemplo de JSON a seguir define uma ação Lambda com modelos de substituição em uma regra. AWS IoT
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"lambda": {
"functionArn": "arn:aws:lambda:us-east-1:123456789012:function:${topic()}"
}
}
]
}
}
```
## Consulte também
+ [O que AWS Lambdaé](https://docs.aws.amazon.com/lambda/latest/dg/) no *Guia do AWS Lambda desenvolvedor*
+ [Tutorial: Formatando uma notificação usando uma função AWS Lambda](iot-lambda-rule.md)
# Local
A ação Localização (`location`) envia seus dados de localização geográfica para o [Amazon Location Service](https://docs.aws.amazon.com//location/latest/developerguide/welcome.html).
## Requisitos
Esta ação de regra tem os seguintes requisitos:
+ Uma função do IAM que AWS IoT você pode assumir para realizar a `geo:BatchUpdateDevicePosition` operação. Para obter mais informações, consulte [Conceder a uma AWS IoT regra o acesso que ela exige](iot-create-role.md).
No AWS IoT console, você pode escolher ou criar uma função para permitir AWS IoT a execução dessa ação de regra.
## Parâmetros
Ao criar uma AWS IoT regra com essa ação, você deve especificar as seguintes informações:
`deviceId`
O ID exclusivo do dispositivo que fornece os dados de localização. Para obter mais informações, consulte [https://docs.aws.amazon.com//location/latest/APIReference/API_DevicePositionUpdate.html](https://docs.aws.amazon.com//location/latest/APIReference/API_DevicePositionUpdate.html) da *Referência de API do Amazon Location Service*.
Compatível com [modelos de substituição](iot-substitution-templates.md): Sim
`latitude`
Uma string que é avaliada como um valor duplo que representa a latitude da localização do dispositivo.
Compatível com [modelos de substituição](iot-substitution-templates.md): Sim
`longitude`
Uma string que é avaliada como um valor duplo que representa a longitude da localização do dispositivo.
Compatível com [modelos de substituição](iot-substitution-templates.md): Sim
`roleArn`
O perfil do IAM que permite acessar o domínio do Amazon Location Service. Para obter mais informações, consulte [Requisitos](#location-rule-action-requirements).
`timestamp`
A hora em que os dados de localização foram amostrados. O valor padrão é a hora que a mensagem MQTT foi processada.
O valor `timestamp` consiste nos dois valores a seguir:
+ `value`: Uma expressão que retorna um valor de horário epoch longo. Você pode usar a função [time\$1to\$1epoch(String, String)](iot-sql-functions.md#iot-sql-function-time-to-epoch) para criar um carimbo de data/hora válido a partir de um valor de data ou hora transmitido na carga da mensagem. Compatível com [modelos de substituição](iot-substitution-templates.md): Sim.
+ `unit`: (Opcional) A precisão do valor do carimbo de data/hora que resulta da expressão descrita em `value`. Valores válidos: `SECONDS` \$1 `MILLISECONDS` \$1 `MICROSECONDS` \$1 `NANOSECONDS`. O padrão é `MILLISECONDS`. Suporta [modelos de substituição](iot-substitution-templates.md): API e AWS CLI somente.
`trackerName`
O nome do recurso rastreador no Amazon Location no qual a localização é atualizada. Para acessar mais informações, consulte [Rastreador](https://docs.aws.amazon.com//location/latest/developerguide/geofence-tracker-concepts.html#tracking-overview) no *Guia do desenvolvedor do Amazon Location Service*.
Suporta [modelos de substituição](iot-substitution-templates.md): API e somente AWS CLI
## Exemplos
O exemplo de JSON a seguir define uma ação de localização em uma AWS IoT regra.
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"location": {
"roleArn": "arn:aws:iam::123454962127:role/service-role/ExampleRole",
"trackerName": "MyTracker",
"deviceId": "001",
"sampleTime": {
"value": "${timestamp()}",
"unit": "MILLISECONDS"
},
"latitude": "-12.3456",
"longitude": "65.4321"
}
}
]
}
}
```
O exemplo de JSON a seguir define uma ação Location com modelos de substituição em uma AWS IoT regra.
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"location": {
"roleArn": "arn:aws:iam::123456789012:role/service-role/ExampleRole",
"trackerName": "${TrackerName}",
"deviceId": "${DeviceID}",
"timestamp": {
"value": "${timestamp()}",
"unit": "MILLISECONDS"
},
"latitude": "${get(position, 0)}",
"longitude": "${get(position, 1)}"
}
}
]
}
}
```
O exemplo de carga útil do MQTT a seguir mostra como os modelos de substituição no exemplo anterior acessam os dados. Você pode usar o comando [https://docs.aws.amazon.com/cli/latest/reference/location/get-device-position-history.html](https://docs.aws.amazon.com/cli/latest/reference/location/get-device-position-history.html) CLI para verificar se os dados da carga útil do MQTT são entregues no seu rastreador de localização.
```
{
"TrackerName": "mytracker",
"DeviceID": "001",
"position": [
"-12.3456",
"65.4321"
]
}
```
```
aws location get-device-position-history --device-id 001 --tracker-name mytracker
```
```
{
"DevicePositions": [
{
"DeviceId": "001",
"Position": [
-12.3456,
65.4321
],
"ReceivedTime": "2022-11-11T01:31:54.464000+00:00",
"SampleTime": "2022-11-11T01:31:54.308000+00:00"
}
]
}
```
## Consulte também
+ [O que é o Amazon Location Service?](https://docs.aws.amazon.com//location/latest/developerguide/welcome.html) no *Guia do desenvolvedor do Amazon Location Service*.
# OpenSearch
A ação OpenSearch (`openSearch`) grava dados de mensagens MQTT em um domínio da Amazon OpenSearch Service. Em seguida, você pode usar ferramentas como OpenSearch painéis para consultar e visualizar dados no OpenSearch Service.
## Requisitos
Esta ação de regra tem os seguintes requisitos:
+ Uma função do IAM que AWS IoT você pode assumir para realizar a `es:ESHttpPut` operação. Para obter mais informações, consulte [Conceder a uma AWS IoT regra o acesso que ela exige](iot-create-role.md).
No AWS IoT console, você pode escolher ou criar uma função para permitir AWS IoT a execução dessa ação de regra.
+ Se você usa um cliente gerenciado AWS KMS key para criptografar dados em repouso no OpenSearch Service, o serviço deve ter permissão para usar a chave KMS em nome do chamador. Para obter mais informações, consulte [Criptografia de dados em repouso para o Amazon OpenSearch Service](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/encryption-at-rest.html) no *Amazon OpenSearch Service Developer Guide*.
## Parâmetros
Ao criar uma AWS IoT regra com essa ação, você deve especificar as seguintes informações:
`endpoint`
O endpoint do seu domínio do Amazon OpenSearch Service.
Suporta [modelos de substituição](iot-substitution-templates.md): API e somente AWS CLI
`index`
O OpenSearch índice em que você deseja armazenar seus dados.
Compatível com [modelos de substituição](iot-substitution-templates.md): Sim
`type`
O tipo de documento que você está armazenando.
Para OpenSearch versões posteriores à 1.0, o valor do `type` parâmetro deve ser`_doc`. Para obter mais informações, consulte a [documentação do OpenSearch ](https://opensearch.org/docs/1.0/opensearch/rest-api/document-apis/index-document/#response-body-fields).
Compatível com [modelos de substituição](iot-substitution-templates.md): Sim
`id`
O identificador exclusivo de cada documento.
Compatível com [modelos de substituição](iot-substitution-templates.md): Sim
`roleARN`
A função do IAM que permite acesso ao domínio do OpenSearch Serviço. Para obter mais informações, consulte [Requisitos](#opensearch-rule-action-requirements).
Compatível com [modelos de substituição](iot-substitution-templates.md): Não
## Limitações
A ação OpenSearch (`openSearch`) não pode ser usada para entregar dados aos clusters do VPC Elasticsearch.
## Exemplos
O exemplo de JSON a seguir define uma OpenSearch ação em uma AWS IoT regra e como você pode especificar os campos para a `OpenSearch` ação. Para obter mais informações, consulte [OpenSearchAction](https://docs.aws.amazon.com/iot/latest/apireference/API_OpenSearchAction.html).
```
{
"topicRulePayload": {
"sql": "SELECT *, timestamp() as timestamp FROM 'iot/test'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"openSearch": {
"endpoint": "https://my-endpoint",
"index": "my-index",
"type": "_doc",
"id": "${newuuid()}",
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_os"
}
}
]
}
}
```
O exemplo de JSON a seguir define uma OpenSearch ação com modelos de substituição em uma AWS IoT regra.
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"openSearch": {
"endpoint": "https://my-endpoint",
"index": "${topic()}",
"type": "${type}",
"id": "${newuuid()}",
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_os"
}
}
]
}
}
```
**nota**
O `type` campo substituído funciona para a OpenSearch versão 1.0. Para qualquer versão posterior à 1.0, o valor de `type` deve ser `_doc`.
## Consulte também
[O que é o Amazon OpenSearch Service?](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/) no *Amazon OpenSearch Service Developer Guide*
# Nova publicação
Use a ação (`republish`) publicar novamente publica novamente uma mensagem do MQTT para outro tópico do MQTT.
## Requisitos
Esta ação de regra tem os seguintes requisitos:
+ Uma função do IAM que AWS IoT você pode assumir para realizar a `iot:Publish` operação. Para obter mais informações, consulte [Conceder a uma AWS IoT regra o acesso que ela exige](iot-create-role.md).
No AWS IoT console, você pode escolher ou criar uma função para permitir AWS IoT a execução dessa ação de regra.
## Parâmetros
Ao criar uma AWS IoT regra com essa ação, você deve especificar as seguintes informações:
`headers`
Informações de cabeçalho do MQTT versão 5.0.
Para obter mais informações, consulte [RepublishAction](https://docs.aws.amazon.com//iot/latest/apireference/API_RepublishAction.html) e [MqttHeaders](https://docs.aws.amazon.com//iot/latest/apireference/API_MqttHeaders.html) na *Referência da API do AWS *.
`topic`
O tópico MQTT no qual publicar a mensagem novamente.
Para publicar novamente em um tópico reservado, que começa com `$`, use `$$` em vez disso. Por exemplo, para publicar novamente em um tópico de sombra do dispositivo `$aws/things/MyThing/shadow/update`, especifique o tópico como `$$aws/things/MyThing/shadow/update`.
A nova publicação em [tópicos de trabalho reservados](reserved-topics.md#reserved-topics-job) não é compatível.
AWS IoT Device Defender tópicos de reserva não oferecem suporte à publicação HTTP.
Compatível com [modelos de substituição](iot-substitution-templates.md): Sim
`qos`
(Opcional) O nível Quality of Service (QoS - Qualidade de serviço) a ser usado ao republicar mensagens. Valores válidos: `0`, `1`. O valor padrão é `0`. Para obter mais informações sobre QoS MQTT, consulte [MQTT](mqtt.md).
Compatível com [modelos de substituição](iot-substitution-templates.md): Não
`roleArn`
A função do IAM que permite AWS IoT publicar no tópico do MQTT. Para obter mais informações, consulte [Requisitos](#republish-rule-action-requirements).
Compatível com [modelos de substituição](iot-substitution-templates.md): Não
## Exemplos
O exemplo de JSON a seguir define uma ação de republicação em uma AWS IoT regra.
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"republish": {
"topic": "another/topic",
"qos": 1,
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_republish"
}
}
]
}
}
```
O exemplo de JSON a seguir define uma ação de republicação com modelos de substituição em uma regra. AWS IoT
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"republish": {
"topic": "${topic()}/republish",
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_republish"
}
}
]
}
}
```
O exemplo de JSON a seguir define uma ação de republicação com uma `headers` AWS IoT regra.
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"republish": {
"topic": "${topic()}/republish",
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_republish",
"headers": {
"payloadFormatIndicator": "UTF8_DATA",
"contentType": "rule/contentType",
"correlationData": "cnVsZSBjb3JyZWxhdGlvbiBkYXRh",
"userProperties": [
{
"key": "ruleKey1",
"value": "ruleValue1"
},
{
"key": "ruleKey2",
"value": "ruleValue2"
}
]
}
}
}
]
}
}
```
**nota**
O IP de origem original não será transmitido pela [ação Publicar novamente](#republish-rule-action).
# S3
A ação S3 (`s3`) grava os dados de uma mensagem MQTT em um bucket do Amazon Simple Storage Service (Amazon S3).
## Requisitos
Esta ação de regra tem os seguintes requisitos:
+ Uma função do IAM que AWS IoT você pode assumir para realizar a `s3:PutObject` operação. Para obter mais informações, consulte [Conceder a uma AWS IoT regra o acesso que ela exige](iot-create-role.md).
No AWS IoT console, você pode escolher ou criar uma função para permitir AWS IoT a execução dessa ação de regra.
+ Se você usa um AWS KMS cliente gerenciado AWS KMS key para criptografar dados em repouso no Amazon S3, o serviço deve ter permissão para usar o AWS KMS key em nome do chamador. Para obter mais informações, consulte [AWS gerenciado AWS KMS keys e gerenciado pelo cliente AWS KMS keys](https://docs.aws.amazon.com/AmazonS3/latest/userguide/UsingKMSEncryption.html#aws-managed-customer-managed-cmks) no *Guia do desenvolvedor do Amazon Simple Storage Service*.
## Parâmetros
Ao criar uma AWS IoT regra com essa ação, você deve especificar as seguintes informações:
`bucket`
O bucket do Amazon S3 no qual gravar dados.
Suporta [modelos de substituição](iot-substitution-templates.md): API e somente AWS CLI
`cannedacl`
(Opcional) A ACL predefinida do Amazon S3 que controla o acesso ao objeto identificado pela chave do objeto. Para obter mais informações, inclusive os valores permitidos, consulte [ACL predefinida](https://docs.aws.amazon.com/AmazonS3/latest/userguide/acl-overview.html#canned-acl).
Compatível com [modelos de substituição](iot-substitution-templates.md): Não
`key`
O caminho para o arquivo em que os dados são gravados.
Considere um exemplo em que esse parâmetro está `${topic()}/${timestamp()}` e a regra recebe uma mensagem em que o tópico está `some/topic`. Se o carimbo de data/hora atual for `1460685389`, essa ação grava os dados em um arquivo chamado `1460685389` na `some/topic` pasta do bucket do S3.
Se você usar uma chave estática, AWS IoT substituirá um único arquivo sempre que a regra for invocada. Recomendamos que você use o carimbo de data/hora da mensagem ou outro identificador exclusivo de mensagem para que um novo arquivo seja salvo no Amazon S3 para cada mensagem recebida.
Compatível com [modelos de substituição](iot-substitution-templates.md): Sim
`roleArn`
O perfil do IAM que permite o acesso ao bucket do Amazon S3. Para obter mais informações, consulte [Requisitos](#s3-rule-action-requirements).
Compatível com [modelos de substituição](iot-substitution-templates.md): Não
## Exemplos
O exemplo de JSON a seguir define uma ação do S3 em uma AWS IoT regra.
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"s3": {
"bucketName": "amzn-s3-demo-bucket",
"cannedacl": "public-read",
"key": "${topic()}/${timestamp()}",
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_s3"
}
}
]
}
}
```
## Consulte também
+ [O que é o Amazon S3?](https://docs.aws.amazon.com/AmazonS3/latest/userguide/) no *Guia do usuário do Amazon Simple Storage Service*
# IoT do Salesforce
Uma ação do IoT do Salesforce (`salesforce`) envia os dados da mensagem MQTT que acionou a regra para um stream de entrada do IoT do Salesforce.
## Parâmetros
Ao criar uma AWS IoT regra com essa ação, você deve especificar as seguintes informações:
`url`
O URL exposto pelo fluxo de entrada do IoT do Salesforce. O URL está disponível na plataforma do IoT do Salesforce ao criar um fluxo de entrada. Para obter mais informações, consulte a documentação do IoT do Salesforce.
Compatível com [modelos de substituição](iot-substitution-templates.md): Não
`token`
O token usado para autenticar o acesso ao fluxo de entrada do IoT do Salesforce especificado. O token está disponível na plataforma do IoT do Salesforce ao criar um fluxo de entrada. Para obter mais informações, consulte a documentação do IoT do Salesforce.
Compatível com [modelos de substituição](iot-substitution-templates.md): Não
## Exemplos
O exemplo JSON a seguir define uma ação do IoT do Salesforce em uma regra AWS IoT .
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic'",
"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"
}
}
]
}
}
```
# SNS
A ação SNS (`sns`) envia os dados de uma mensagem MQTT como uma notificação push do Amazon Simple Notification Service (Amazon SNS)
Você pode seguir um tutorial que mostra como criar e testar uma regra com uma ação do SNS. Para obter mais informações, consulte [Tutorial:r Como enviar uma notificação do Amazon SNS](iot-sns-rule.md).
**nota**
A ação do SNS não oferece suporte a [tópicos FIFO (First-In-First-Out) do Amazon SNS](https://docs.aws.amazon.com/sns/latest/dg/sns-fifo-topics.html). Como o mecanismo de regras é um serviço totalmente distribuído, não há garantia da ordem das mensagens quando a ação do SNS é invocada.
## Requisitos
Esta ação de regra tem os seguintes requisitos:
+ Uma função do IAM que AWS IoT você pode assumir para realizar a `sns:Publish` operação. Para obter mais informações, consulte [Conceder a uma AWS IoT regra o acesso que ela exige](iot-create-role.md).
No AWS IoT console, você pode escolher ou criar uma função para permitir AWS IoT a execução dessa ação de regra.
+ Se você usa um serviço gerenciado pelo AWS KMS cliente AWS KMS key para criptografar dados em repouso no Amazon SNS, o serviço deve ter permissão para usá-lo AWS KMS key em nome do chamador. Para obter mais informações, consulte [Gerenciamento de chaves](https://docs.aws.amazon.com/sns/latest/dg/sns-key-management.html) no *Guia do desenvolvedor do Amazon Simple Notification Service*.
## Parâmetros
Ao criar uma AWS IoT regra com essa ação, você deve especificar as seguintes informações:
`targetArn`
O tópico do SNS ou o dispositivo individual para o qual a notificação por push é enviada.
Suporta [modelos de substituição](iot-substitution-templates.md): API e somente AWS CLI
`messageFormat`
(Opcional) O formato da mensagem. O Amazon SNS usa essa configuração para determinar se a carga deve ser analisada e se partes relevantes específicas da plataforma da carga devem ser extraídas. Valores válidos: `JSON`, `RAW`. Padronizado como `RAW`.
Compatível com [modelos de substituição](iot-substitution-templates.md): Não
`roleArn`
O perfil do IAM; que permite o acesso ao SNS. Para obter mais informações, consulte [Requisitos](#sns-rule-action-requirements).
Compatível com [modelos de substituição](iot-substitution-templates.md): Não
## Exemplos
O exemplo de JSON a seguir define uma ação do SNS em uma AWS IoT regra.
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"sns": {
"targetArn": "arn:aws:sns:us-east-2:123456789012:my_sns_topic",
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_sns"
}
}
]
}
}
```
O exemplo de JSON a seguir define uma ação do SNS com modelos de substituição em uma regra. AWS IoT
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"sns": {
"targetArn": "arn:aws:sns:us-east-1:123456789012:${topic()}",
"messageFormat": "JSON",
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_sns"
}
}
]
}
}
```
## Consulte também
+ [O que é o Amazon Simple Notification Service?](https://docs.aws.amazon.com/sns/latest/dg/) no *Guia do desenvolvedor do Amazon Simple Notification Service*
+ [Tutorial:r Como enviar uma notificação do Amazon SNS](iot-sns-rule.md)
# SQS
A ação SQS (`sqs`) envia dados de uma mensagem MQTT para uma fila do Amazon Simple Queue Service (Amazon SQS).
**nota**
A ação do SQS não é compatível com as [filas do Amazon SQS FIFO (First-In-First-Out)](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/FIFO-queues.html). Como o mecanismo de regras é um serviço totalmente distribuído, não há garantia da ordem das mensagens quando a ação do SQS é acionada.
## Requisitos
Esta ação de regra tem os seguintes requisitos:
+ Uma função do IAM que AWS IoT você pode assumir para realizar a `sqs:SendMessage` operação. Para obter mais informações, consulte [Conceder a uma AWS IoT regra o acesso que ela exige](iot-create-role.md).
No AWS IoT console, você pode escolher ou criar uma função para permitir AWS IoT a execução dessa ação de regra.
+ Se você usa um AWS KMS cliente gerenciado AWS KMS key para criptografar dados em repouso no Amazon SQS, o serviço deve ter permissão para usar AWS KMS key o em nome do chamador. Para obter mais informações, consulte [Gerenciamento de chaves](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/sqs-key-management.html) no *Guia do desenvolvedor do Amazon Simple Queue Service*.
## Parâmetros
Ao criar uma AWS IoT regra com essa ação, você deve especificar as seguintes informações:
`queueUrl`
O URL da fila do Amazon SQS na qual os dados serão gravados. A região nesse URL não precisa ser a mesma da sua Região da AWS [AWS IoT regra](https://docs.aws.amazon.com/iot/latest/developerguide/iot-rules.html).
Pode haver cobranças adicionais pela transferência de dados entre Regiões da AWS usando a ação de regra SQS. Para obter mais informações, consulte [Preços do Amazon SQS](https://aws.amazon.com/sqs/pricing/).
Suporta [modelos de substituição](iot-substitution-templates.md): API e somente AWS CLI
`useBase64`
Defina esse parâmetro como `true` para configurar a ação da regra para codificar em base64 os dados da mensagem antes de gravar os dados na fila do Amazon SQS. Padronizado como `false`.
Compatível com [modelos de substituição](iot-substitution-templates.md): Não
`roleArn`
O perfil do IAM que permite o acesso à fila do Amazon SQS. Para obter mais informações, consulte [Requisitos](#sqs-rule-action-requirements).
Compatível com [modelos de substituição](iot-substitution-templates.md): Não
## Exemplos
O exemplo de JSON a seguir define uma ação SQS em uma AWS IoT regra.
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"sqs": {
"queueUrl": "https://sqs.us-east-2.amazonaws.com/123456789012/my_sqs_queue",
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_sqs"
}
}
]
}
}
```
O exemplo de JSON a seguir define uma ação SQS com modelos de substituição em uma regra. AWS IoT
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"sqs": {
"queueUrl": "https://sqs.us-east-2.amazonaws.com/123456789012/${topic()}",
"useBase64": true,
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_sqs"
}
}
]
}
}
```
## Consulte também
+ [O que é o Amazon Simple Queue Service?](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/) no *Guia do desenvolvedor do Amazon Simple Queue Service*
# Step Functions
A ação Step Functions (`stepFunctions`) inicia uma máquina de AWS Step Functions estado.
## Requisitos
Esta ação de regra tem os seguintes requisitos:
+ Uma função do IAM que AWS IoT você pode assumir para realizar a `states:StartExecution` operação. Para obter mais informações, consulte [Conceder a uma AWS IoT regra o acesso que ela exige](iot-create-role.md).
No AWS IoT console, você pode escolher ou criar uma função para permitir AWS IoT a execução dessa ação de regra.
## Parâmetros
Ao criar uma AWS IoT regra com essa ação, você deve especificar as seguintes informações:
`stateMachineName`
O nome da máquina de estados do Step Functions a ser iniciada.
Suporta [modelos de substituição](iot-substitution-templates.md): API e somente AWS CLI
`executionNamePrefix`
(Opcional) Um nome será atribuído à execução da máquina de estados composto por esse prefixo seguido por um UUID. O Step Functions cria automaticamente um nome exclusivo para cada execução da máquina de estados, caso um nome não seja fornecido.
Compatível com [modelos de substituição](iot-substitution-templates.md): Sim
`roleArn`
O ARN da função que concede AWS IoT permissão para iniciar a máquina de estado. Para obter mais informações, consulte [Requisitos](#stepfunctions-rule-action-requirements).
Compatível com [modelos de substituição](iot-substitution-templates.md): Não
## Exemplos
O exemplo de JSON a seguir define uma ação Step Functions em uma AWS IoT regra.
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"stepFunctions": {
"stateMachineName": "myStateMachine",
"executionNamePrefix": "myExecution",
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_step_functions"
}
}
]
}
}
```
## Consulte também
+ [O que AWS Step Functionsé](https://docs.aws.amazon.com/step-functions/latest/dg/) no *Guia do AWS Step Functions desenvolvedor*
# Timestream
A ação da regra Timestream grava atributos (medidas) de uma mensagem MQTT em uma tabela do Amazon Timestream. Para obter mais informações sobre o Amazon Timestream, consulte [O que é o Amazon Timestream?](https://docs.aws.amazon.com/timestream/latest/developerguide/what-is-timestream.html).
**nota**
O Amazon Timestream não está disponível em todos os s. Região da AWS Se o Amazon Timestream não estiver disponível em sua região, ele não aparecerá na lista de ações de regras.
Os atributos que essa regra armazena no banco de dados do Timestream são aqueles que resultam da instrução de consulta da regra. O valor de cada atributo no resultado da instrução de consulta é analisado para inferir seu tipo de dados (como em uma ação [Dínamo DBv2](dynamodb-v2-rule-action.md)). O valor de cada atributo é gravado em seu próprio registro na tabela do Timestream. Para especificar ou alterar o tipo de dados de um atributo, use a função [`cast()`](iot-sql-functions.md#iot-sql-function-cast) na instrução de consulta. Para obter mais informações sobre o conteúdo de cada registro do Timestream, consulte. [Conteúdo do registro do Timestream](#timestream-rule-action-data)
**nota**
Com o SQL V2 (23-03-2016), valores numéricos que são números inteiros, como `10.0`, são convertidos em sua representação inteira (`10`). Convertê-los explicitamente em um valor `Decimal`, como usar a função [cast()](iot-sql-functions.md#iot-sql-function-cast), não impede esse comportamento — o resultado ainda é um valor `Integer`. Isso pode causar erros de incompatibilidade de tipos que impedem que os dados sejam registrados no banco de dados do Timestream. Para processar valores numéricos inteiros como valores `Decimal`, use o SQL V1 (08/10/2015) para a instrução de consulta de regra.
**nota**
O número máximo de valores que uma ação de regra do Timestream pode gravar em uma tabela do Amazon Timestream é 100. Para obter mais informações, consulte a [Referência da cota do Amazon Timestream](https://docs.aws.amazon.com//timestream/latest/developerguide/ts-limits.html#limits.default).
## Requisitos
Esta ação de regra tem os seguintes requisitos:
+ Uma função do IAM que AWS IoT você pode assumir para realizar as `timestream:WriteRecords` operações `timestream:DescribeEndpoints` e. Para obter mais informações, consulte [Conceder a uma AWS IoT regra o acesso que ela exige](iot-create-role.md).
No AWS IoT console, você pode escolher, atualizar ou criar uma função para permitir AWS IoT a execução dessa ação de regra.
+ Se você usa um cliente AWS KMS para criptografar dados em repouso no Timestream, o serviço deve ter permissão para usar o AWS KMS key em nome do chamador. Para obter mais informações, consulte [Como AWS os serviços usam o AWS KMS.](https://docs.aws.amazon.com/kms/latest/developerguide/service-integration.html)
## Parâmetros
Ao criar uma AWS IoT regra com essa ação, você deve especificar as seguintes informações:
`databaseName`
O nome de um banco de dados do Amazon Timestream que tem a tabela para receber os registros que essa ação cria. Consulte também `tableName`.
Suporta [modelos de substituição](iot-substitution-templates.md): API e somente AWS CLI
`dimensions`
Atributos de metadados das séries temporais que são gravados em cada registro de medida. Por exemplo, o nome e a zona de disponibilidade de uma instância do EC2 ou o nome do fabricante de uma turbina eólica são dimensões.
`name`
O nome da dimensão de metadados. Este é o nome da coluna no registro da tabela do banco de dados.
As dimensões não podem ser nomeadas:`measure_name`, `measure_value`, ou `time`. Esses nomes são reservados. Os nomes das dimensões não podem começar com `ts_` ou `measure_value` e não podem conter o caractere de dois pontos (`:`).
Compatível com [modelos de substituição](iot-substitution-templates.md): Não
`value`
O valor a ser gravado nesta coluna do registro do banco de dados.
Compatível com [modelos de substituição](iot-substitution-templates.md): Sim
`roleArn`
O nome do recurso da Amazon (ARN) da função que concede permissão AWS IoT para gravar na tabela do banco de dados do Timestream. Para obter mais informações, consulte [Requisitos](#timestream-rule-action-requirements).
Compatível com [modelos de substituição](iot-substitution-templates.md): Não
`tableName`
O nome da tabela de banco de dados na qual gravar os registros de medida. Consulte também `databaseName`.
Suporta [modelos de substituição](iot-substitution-templates.md): API e somente AWS CLI
`timestamp`
O valor a ser usado para o carimbo e data/hora da entrada. Se estiver em branco, a hora em que a entrada foi processada será usada.
`unit`
A precisão do valor do carimbo de data/hora que resulta da expressão descrita em `value`.
Valores válidos: `SECONDS` \$1 `MILLISECONDS` \$1 `MICROSECONDS` \$1 `NANOSECONDS`. O padrão é `MILLISECONDS`.
`value`
Uma expressão que retorna um valor de tempo epoch longo.
Você pode usar a função [time\$1to\$1epoch(String, String)](iot-sql-functions.md#iot-sql-function-time-to-epoch) para criar um carimbo de data/hora válido a partir de um valor de data ou hora transmitido na carga da mensagem.
## Conteúdo do registro do Timestream
Os dados gravados na tabela do Amazon Timestream por essa ação incluem um carimbo de data e hora, metadados da ação da regra Timestream e o resultado da instrução de consulta da regra.
Para cada atributo (medida) no resultado da instrução de consulta, essa ação de regra grava um registro na tabela Timestream especificada com essas colunas.
| Nome da coluna | Tipo de atributo | Valor | Comentários |
| --- | --- | --- | --- |
| *dimension-name* | DIMENSÃO | O valor especificado na entrada de ação da regra Timestream. | Cada **Dimensão** especificada na entrada de ação da regra cria uma coluna no banco de dados do Timestream com o nome da dimensão. |
| nome\$1medida | NOME\$1MEDIDA | O nome do atributo | O nome do atributo no resultado da instrução de consulta cujo valor é especificado na coluna `measure_value::data-type`. |
| valor\$1de\$1medida:: *data-type* | VALOR\$1MEDIDA | O nome do atributo no resultado da instrução de consulta. O nome do atributo está na coluna `measure_name`. | O valor é interpretado\$1 e convertido como a combinação mais adequada de:`bigint`, `boolean`, `double`, ou `varchar`. O Amazon Timestream cria uma coluna separada para cada tipo de dados. O valor na mensagem pode ser convertido em outro tipo de dados usando a função [`cast()`](iot-sql-functions.md#iot-sql-function-cast) na instrução de consulta da regra. |
| tempo | TIMESTAMP | A data e a hora do registro no banco de dados. | Esse valor é atribuído pelo mecanismo de regras ou pela propriedade `timestamp`, se estiver definida. |
\$1 O valor do atributo lido da carga da mensagem é interpretado da seguinte forma. Consulte a [Exemplos](#timestream-rule-action-examples) para obter uma ilustração de cada um desses casos.
+ Um valor sem aspas de `true` ou `false` é interpretado como um tipo `boolean`.
+ Um numérico decimal é interpretado como um tipo `double`.
+ Um valor numérico sem ponto decimal é interpretado como um tipo `bigint`.
+ Uma string entre aspas é interpretada como um tipo `varchar`.
+ Objetos e valores de matriz são convertidos em strings JSON e armazenados como um tipo `varchar`.
## Exemplos
O exemplo de JSON a seguir define uma ação de regra Timestream com um modelo de substituição em uma regra. AWS IoT
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'iot/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"timestream": {
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_timestream",
"tableName": "devices_metrics",
"dimensions": [
{
"name": "device_id",
"value": "${clientId()}"
},
{
"name": "device_firmware_sku",
"value": "My Static Metadata"
}
],
"databaseName": "record_devices"
}
}
]
}
}
```
Usar a ação de regra de tópico Timestream definida no exemplo anterior com a carga útil da mensagem a seguir resulta nos registros do Amazon Timestream escritos na tabela a seguir.
```
{
"boolean_value": true,
"integer_value": 123456789012,
"double_value": 123.456789012,
"string_value": "String value",
"boolean_value_as_string": "true",
"integer_value_as_string": "123456789012",
"double_value_as_string": "123.456789012",
"array_of_integers": [23,36,56,72],
"array of strings": ["red", "green","blue"],
"complex_value": {
"simple_element": 42,
"array_of_integers": [23,36,56,72],
"array of strings": ["red", "green","blue"]
}
}
```
A tabela a seguir exibe as colunas e os registros do banco de dados que usam a ação de regra de tópico especificada para processar a carga útil da mensagem anterior criada. As colunas `device_firmware_sku` e `device_id` são as DIMENSÕES definidas na ação da regra de tópico. A ação de regra de tópico Timestream cria a coluna `time` e as colunas `measure_name` e `measure_value::*`, que ela preenche com os valores do resultado da instrução de consulta da ação de regra de tópico.
| device\$1firmware\$1sku | id\$1dispositivo | nome\$1medida | valor\$1medida::bigint | valor\$1medida::varchar | valor\$1medida::duplo | valor\$1medida::booleano | tempo |
| --- | --- | --- | --- | --- | --- | --- | --- |
| Meus metadados estáticos | console EXAMPLE738 iot-159 -0 | valor\$1complexo | - | \$1"elemento\$1simples":42,"matriz\$1de\$1inteiros":[23,36,56,72],"matriz de strings":["vermelho","verde","azul"]\$1 | - | - | 2020-08-26 22:42:16.423000000 |
| Meus metadados estáticos | console EXAMPLE738 iot-159 -0 | valor\$1inteiro\$1como\$1string | - | 123456789012 | - | - | 2020-08-26 22:42:16.423000000 |
| Meus metadados estáticos | console EXAMPLE738 iot-159 -0 | valor\$1booleano | - | - | - | VERDADEIRO | 2020-08-26 22:42:16.423000000 |
| Meus metadados estáticos | console EXAMPLE738 iot-159 -0 | valor\$1inteiro | 123456789012 | - | - | - | 2020-08-26 22:42:16.423000000 |
| Meus metadados estáticos | console EXAMPLE738 iot-159 -0 | valor\$1string | - | Valor da string | - | - | 2020-08-26 22:42:16.423000000 |
| Meus metadados estáticos | console EXAMPLE738 iot-159 -0 | matriz\$1de\$1inteiros | - | [23,36,56,72] | - | - | 2020-08-26 22:42:16.423000000 |
| Meus metadados estáticos | console EXAMPLE738 iot-159 -0 | matriz de strings | - | ["vermelho","verde","azul"] | - | - | 2020-08-26 22:42:16.423000000 |
| Meus metadados estáticos | console EXAMPLE738 iot-159 -0 | valor\$1booleano\$1como\$1string | - | VERDADEIRO | - | - | 2020-08-26 22:42:16.423000000 |
| Meus metadados estáticos | console EXAMPLE738 iot-159 -0 | valor\$1duplo | - | - | 123.456789012 | - | 2020-08-26 22:42:16.423000000 |
| Meus metadados estáticos | console EXAMPLE738 iot-159 -0 | valor\$1duplo\$1como\$1string | - | 123.45679 | - | - | 2020-08-26 22:42:16.423000000 |
## Solucionar problemas de uma regra
Se você tiver algum problema com suas regras, recomendamos que você ative o CloudWatch Logs. Você pode analisar seus logs para determinar se o problema é autorização ou se, por exemplo, uma condição de cláusula WHERE não foi correspondida. Para obter mais informações, consulte [Como configurar CloudWatch registros](https://docs.aws.amazon.com/iot/latest/developerguide/cloud-watch-logs.html).
# Acessando recursos entre contas usando regras AWS IoT
Você pode configurar AWS IoT regras para acesso entre contas para que os dados ingeridos nos tópicos do MQTT de uma conta possam ser roteados para os AWS serviços, como Amazon SQS e Lambda, de outra conta. A seguir, explicamos como configurar AWS IoT regras para a ingestão de dados entre contas, de um tópico do MQTT em uma conta até um destino em outra conta.
As regras entre contas podem ser configuradas usando [permissões baseadas em recursos](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_controlling.html#TypesPermissions) no recurso de destino. Portanto, somente destinos que oferecem suporte a permissões baseadas em recursos podem ser habilitados para o acesso entre contas com regras. AWS IoT Os destinos compatíveis incluem Amazon SQS, Amazon SNS, Amazon S3 e AWS Lambda.
**nota**
Para os destinos compatíveis, exceto o Amazon SQS, você deve definir a regra da mesma forma Região da AWS que o recurso de outro serviço para que a ação da regra possa interagir com esse recurso. Para obter mais informações sobre ações de AWS IoT regras, consulte [ações de AWS IoT regras](iot-rule-actions.md). Para obter mais informações sobre a ação de SQS da regra, consulte [SQS](sqs-rule-action.md).
## Pré-requisitos
+ Familiaridade com as [AWS IoT regras](https://docs.aws.amazon.com/iot/latest/developerguide/iot-rules.html)
+ Uma compreensão dos [usuários](https://docs.aws.amazon.com/IAM/latest/UserGuide/introduction_identity-management.html), [funções](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html) e [permissões baseadas em recursos](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_permissions.html#TypesPermissions) do IAM
+ Tendo [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-install.html) instalado
## Configuração entre contas para o Amazon SQS
Cenário: a conta A envia dados de uma mensagem MQTT para a fila do Amazon SQS da conta B.
| Conta da AWS | Conta referida como | Description |
| --- | --- | --- |
| 1111-1111-1111 | Conta A | Ação da regra: sqs:SendMessage |
| 2222-2222-2222 | Conta B | Fila do Amazon SQS [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/iot/latest/developerguide/accessing-cross-account-resources-using-rules.html) |
**nota**
[Sua fila de destino do Amazon SQS não precisa estar na mesma fila da sua Região da AWS regra.AWS IoT](https://docs.aws.amazon.com/iot/latest/developerguide/iot-rules.html) Para obter mais informações sobre a ação de SQS da regra, consulte [SQS](sqs-rule-action.md).
**Realizar as tarefas da Conta A**
**Observação**
Para executar os comandos a seguir, seu usuário do IAM deve ter permissões para `iot:CreateTopicRule` usar o nome do recurso da Amazon (ARN) da regra como um recurso e permissões para `iam:PassRole` agir com um recurso como o ARN da função.
1. [Configure AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-quickstart.html) usando o usuário do IAM da conta A.
1. Crie uma função do IAM que confie no mecanismo de AWS IoT regras e anexe uma política que permita acesso à fila do Amazon SQS da conta B. Veja exemplos de comandos e documentos de política em [Concedendo AWS IoT o acesso necessário](https://docs.aws.amazon.com/iot/latest/developerguide/iot-create-role.html).
1. Para criar uma regra anexada a um tópico, execute o [create-topic-rule comando](https://docs.aws.amazon.com/cli/latest/reference/iot/create-topic-rule.html).
```
aws iot create-topic-rule --rule-name myRule --topic-rule-payload file://./my-rule.json
```
Veja a seguir um exemplo de arquivo de carga útil com uma regra que insere todas as mensagens enviadas ao tópico `iot/test` na fila especificada do Amazon SQS. A instrução SQL filtra as mensagens e o ARN da função concede permissões AWS IoT para adicionar a mensagem à fila do Amazon SQS.
```
{
"sql": "SELECT * FROM 'iot/test'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"sqs": {
"queueUrl": "https://sqs.region.amazonaws.com/2222-2222-2222/ExampleQueue",
"roleArn": "arn:aws:iam::1111-1111-1111:role/my-iot-role",
"useBase64": false
}
}
]
}
```
Para obter mais informações sobre como definir uma ação do Amazon SQS em uma AWS IoT regra, consulte [ações de AWS IoT regras - Amazon SQS.](https://docs.aws.amazon.com/iot/latest/developerguide/sqs-rule-action.html)
**Realizar as tarefas da Conta B**
1. [Configure AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-quickstart.html) usando o usuário do IAM da conta B.
1. Para conceder permissões para o recurso de fila do Amazon SQS para a conta A, execute o [comando adicionar-permissão.](https://docs.aws.amazon.com/cli/latest/reference/sqs/add-permission.html)
```
aws sqs add-permission --queue-url https://sqs.region.amazonaws.com/2222-2222-2222/ExampleQueue --label SendMessagesToMyQueue --aws-account-ids 1111-1111-1111 --actions SendMessage
```
## Configuração entre contas para o Amazon SNS
Cenário: a conta A envia dados de uma mensagem MQTT para um tópico do Amazon SNS da conta B.
| Conta da AWS | Conta referida como | Description |
| --- | --- | --- |
| 1111-1111-1111 | Conta A | Ação da regra: sns:Publish |
| 2222-2222-2222 | Conta B | ARN do tópico do Amazon SNS: arn:aws:sns:region:2222-2222-2222:ExampleTopic |
**Realizar as tarefas da Conta A**
**Observações**
Para executar os comandos a seguir, seu usuário do IAM deve ter permissões para `iot:CreateTopicRule` usar o ARN da regra como recurso e permissões para a ação `iam:PassRole` com um recurso como ARN da função.
1. [Configure AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-quickstart.html) usando o usuário do IAM da conta A.
1. Crie uma função do IAM que confie no mecanismo de AWS IoT regras e anexe uma política que permita acesso ao tópico do Amazon SNS da conta B. Por exemplo, comandos e documentos de política, consulte [Concedendo AWS IoT o acesso necessário](https://docs.aws.amazon.com/iot/latest/developerguide/iot-create-role.html).
1. Para criar uma regra anexada a um tópico, execute o [create-topic-rule comando](https://docs.aws.amazon.com/cli/latest/reference/iot/create-topic-rule.html).
```
aws iot create-topic-rule --rule-name myRule --topic-rule-payload file://./my-rule.json
```
Veja a seguir um exemplo de arquivo de carga útil com uma regra que insere todas as mensagens enviadas ao tópico `iot/test` no tópico especificado do Amazon SNS. A instrução SQL filtra as mensagens e o ARN da função concede permissões AWS IoT para enviar a mensagem ao tópico do Amazon SNS.
```
{
"sql": "SELECT * FROM 'iot/test'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"sns": {
"targetArn": "arn:aws:sns:region:2222-2222-2222:ExampleTopic",
"roleArn": "arn:aws:iam::1111-1111-1111:role/my-iot-role"
}
}
]
}
```
Para obter mais informações sobre como definir uma ação do Amazon SNS em uma AWS IoT regra, consulte [Ações de AWS IoT regras - Amazon SNS](https://docs.aws.amazon.com/iot/latest/developerguide/sns-rule-action.html).
**Realizar as tarefas da Conta B**
1. [Configure AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-quickstart.html) usando o usuário do IAM da conta B.
1. Para conceder permissão no recurso de tópico do Amazon SNS à conta A, execute o [comando adicionar-permissão](https://docs.aws.amazon.com/cli/latest/reference/sns/add-permission.html).
```
aws sns add-permission --topic-arn arn:aws:sns:region:2222-2222-2222:ExampleTopic --label Publish-Permission --aws-account-id 1111-1111-1111 --action-name Publish
```
## Configuração entre contas para o Amazon S3
Cenário: a conta A envia dados de uma mensagem MQTT para um bucket do Amazon S3 da conta B.
| Conta da AWS | Conta referida como | Description |
| --- | --- | --- |
| 1111-1111-1111 | Conta A | Ação da regra: s3:PutObject |
| 2222-2222-2222 | Conta B | Bucket do Amazon S3: arn:aws:s3:::amzn-s3-demo-bucket |
**Realizar as tarefas da Conta A**
**Observação**
Para executar os comandos a seguir, seu usuário do IAM deve ter permissões para `iot:CreateTopicRule` usar o ARN da regra como um recurso e permissões para `iam:PassRole` agir com um recurso como ARN da função.
1. [Configure AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-quickstart.html) usando o usuário do IAM da conta A.
1. Crie uma função do IAM que confie no mecanismo de AWS IoT regras e anexe uma política que permita acesso ao bucket Amazon S3 da conta B. Por exemplo, comandos e documentos de política, consulte [Concedendo AWS IoT o acesso necessário](https://docs.aws.amazon.com/iot/latest/developerguide/iot-create-role.html).
1. Para criar uma regra anexada ao seu bucket do S3 de destino, execute o [create-topic-rule comando](https://docs.aws.amazon.com/cli/latest/reference/iot/create-topic-rule.html).
```
aws iot create-topic-rule --rule-name my-rule --topic-rule-payload file://./my-rule.json
```
Veja a seguir um exemplo de arquivo de carga útil com uma regra que insere todas as mensagens enviadas ao tópico `iot/test` no bucket do Amazon S3 especificado. A instrução SQL filtra as mensagens e o ARN da função concede permissões AWS IoT para adicionar a mensagem ao bucket do Amazon S3.
```
{
"sql": "SELECT * FROM 'iot/test'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"s3": {
"bucketName": "amzn-s3-demo-bucket",
"key": "${topic()}/${timestamp()}",
"roleArn": "arn:aws:iam::1111-1111-1111:role/my-iot-role"
}
}
]
}
```
Para obter mais informações sobre como definir uma ação do Amazon S3 em uma AWS IoT regra, consulte [Ações de AWS IoT regras - Amazon S3](https://docs.aws.amazon.com/iot/latest/developerguide/s3-rule-action.html).
**Realizar as tarefas da Conta B**
1. [Configure AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-quickstart.html) usando o usuário do IAM da conta B.
1. Crie uma política de bucket que confie na entidade principal da conta A.
Veja a seguir um exemplo de arquivo de carga útil que define uma política de bucket que confia na entidade principal de outra conta.
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "AddCannedAcl",
"Effect": "Allow",
"Principal": {
"AWS": [
"arn:aws:iam::123456789012:root"
]
},
"Action": "s3:PutObject",
"Resource": "arn:aws:s3:::amzn-s3-demo-bucket/*"
}
]
}
```
Para obter mais informações, consulte [Exemplos de políticas de bucket](https://docs.aws.amazon.com/AmazonS3/latest/userguide/example-bucket-policies.html#example-bucket-policies-use-case-1).
1. Para anexar a política do bucket ao bucket especificado, execute o [put-bucket-policy comando](https://docs.aws.amazon.com/cli/latest/reference/s3api/put-bucket-policy.html).
```
aws s3api put-bucket-policy --bucket amzn-s3-demo-bucket --policy file://./amzn-s3-demo-bucket-policy.json
```
1. Para fazer o acesso entre contas funcionar, certifique-se de ter as configurações corretas de **Bloquear todo o acesso público**. Para obter mais informações, consulte [Práticas recomendadas de segurança para o Amazon S3](https://docs.aws.amazon.com/AmazonS3/latest/userguide/security-best-practices.html).
## Configuração de várias contas para AWS Lambda
Cenário: a conta A invoca uma AWS Lambda função da conta B, transmitindo uma mensagem MQTT.
| Conta da AWS | Conta referida como | Description |
| --- | --- | --- |
| 1111-1111-1111 | Conta A | Ação da regra: lambda:InvokeFunction |
| 2222-2222-2222 | Conta B | ARN da função do Lambda: arn:aws:lambda:region:2222-2222-2222:function:example-function |
**Realizar as tarefas da Conta A**
**Observações**
Para executar os comandos a seguir, seu usuário do IAM deve ter permissões para `iot:CreateTopicRule` usar o ARN da regra como um recurso e permissões para `iam:PassRole` agir com o recurso como ARN da função.
1. [Configure AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-quickstart.html) usando o usuário do IAM da conta A.
1. Execute o [create-topic-rule comando](https://docs.aws.amazon.com/cli/latest/reference/iot/create-topic-rule.html) para criar uma regra que defina o acesso entre contas à função Lambda da conta B.
```
aws iot create-topic-rule --rule-name my-rule --topic-rule-payload file://./my-rule.json
```
Veja a seguir um exemplo de arquivo de carga útil com uma regra que insere todas as mensagens enviadas para o tópico `iot/test` em uma função do Lambda especificada. A instrução SQL filtra as mensagens e o ARN da função concede permissão AWS IoT para transmitir os dados para a função do Lambda.
```
{
"sql": "SELECT * FROM 'iot/test'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"lambda": {
"functionArn": "arn:aws:lambda:region:2222-2222-2222:function:example-function"
}
}
]
}
```
Para obter mais informações sobre como definir uma AWS Lambda ação em uma AWS IoT regra, leia [Ações de AWS IoT regras - Lambda](https://docs.aws.amazon.com/iot/latest/developerguide/lambda-rule-action.html).
**Realizar as tarefas da Conta B**
1. [Configure AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-quickstart.html) usando o usuário do IAM da conta B.
1. Execute o [comando add-permission do Lambda para dar permissão](https://docs.aws.amazon.com/cli/latest/reference/lambda/add-permission.html) às AWS IoT regras para ativar a função Lambda. Para executar o comando a seguir, seu usuário do IAM deve ter permissão para `lambda:AddPermission` agir.
```
aws lambda add-permission --function-name example-function --region us-east-1 --principal iot.amazonaws.com --source-arn arn:aws:iot:region:1111-1111-1111:rule/example-rule --source-account 1111-1111-1111 --statement-id "unique_id" --action "lambda:InvokeFunction"
```
**Opções:**
**--entidade principal**
Esse campo dá permissão para AWS IoT (representado por`iot.amazonaws.com`) chamar a função Lambda.
**--arn de origem**
Este campo confirma que apenas `arn:aws:iot:region:1111-1111-1111:rule/example-rule` nos acionadores AWS IoT esta função do Lambda e nenhuma outra regra na mesma conta ou em conta diferente pode ativar esta função do Lambda.
**--conta de origem**
Esse campo confirma que AWS IoT ativa essa função Lambda somente em nome da conta. `1111-1111-1111`
**Observações**
Se você vir uma mensagem de erro "A regra não foi encontrada" no console da sua AWS Lambda função em **Configuração**, ignore a mensagem de erro e prossiga para testar a conexão.
# Tratamento de erros (ação de erro)
Quando AWS IoT recebe uma mensagem de um dispositivo, o mecanismo de regras verifica se a mensagem corresponde a uma regra. Nesse caso, a instrução de consulta da regra é avaliada e as ações da regra são ativadas, transmitindo o resultado da instrução de consulta.
Se ocorrer um problema ao chamar uma ação, o mecanismo de regras ativará uma ação de erro, se uma ação estiver especificada para a regra. Isso pode acontecer quando:
+ Uma regra não tem permissão para acessar um bucket do Amazon S3.
+ Um erro do usuário faz com que o throughput provisionado do DynamoDB seja excedido.
**nota**
O tratamento de erros abordado neste tópico é para [ações de regras](iot-rule-actions.md). Para depurar problemas de SQL, incluindo funções externas, você pode configurar o AWS IoT registro em log. Para obter mais informações, consulte [Configurar o AWS IoT registro](configure-logging.md).
## Formato da mensagem de ação de erro
Uma única mensagem é gerada por regra e mensagem. Por exemplo, se houver uma falha em duas ações de regra na mesma regra, a ação de erro receberá uma mensagem contendo os dois erros.
O resultado é uma mensagem que parece com o exemplo a seguir.
```
{
"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
O nome da regra que acionou a ação de erro.
tópico
O tópico no qual a mensagem original foi recebida.
cloudwatchTraceId
Uma identidade exclusiva referente ao login de erro CloudWatch.
clientId
O ID do cliente do publicador da mensagem.
base 64 OriginalPayload
A carga da mensagem original codificada em Base64.
falhas
failedAction
O nome da ação que não foi concluída (por exemplo "S3Action").
failedResource
O nome do recurso (por exemplo, o nome de um bucket do S3).
errorMessage
A descrição e a explicação do erro.
## Exemplo de ação de erro
Este é um exemplo de uma regra com uma ação de erro adicional. A seguinte regra tem uma ação que grava dados de mensagens em uma tabela do DynamoDB e uma ação de erro que grava dados em um bucket do Amazon S3:
```
{
"sql" : "SELECT * FROM ..."
"actions" : [{
"dynamoDB" : {
"table" : "PoorlyConfiguredTable",
"hashKeyField" : "AConstantString",
"hashKeyValue" : "AHashKey"}}
],
"errorAction" : {
"s3" : {
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_s3",
"bucketName" : "message-processing-errors",
"key" : "${replace(topic(), '/', '-') + '-' + timestamp() + '-' + newuuid()}"
}
}
}
```
Você pode usar qualquer [função](iot-sql-functions.md) ou [modelo de substituição](https://docs.aws.amazon.com//iot/latest/developerguide/iot-substitution-templates.html) na instrução SQL de uma ação de erro, incluindo as funções externas: [https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-func-aws-lambda](https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-func-aws-lambda), [https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-sql-function-get-registry_data](https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-sql-function-get-registry_data), [https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-sql-function-get-thing-shadow](https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-sql-function-get-thing-shadow), [https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-sql-function-get-secret](https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-sql-function-get-secret), [https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-sql-function-machine-learning](https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-sql-function-machine-learning), e. [https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-sql-decode-base64](https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-sql-decode-base64) Se uma ação de erro exigir a chamada de uma função externa, a invocação da ação de erro poderá resultar em cobrança adicional para a função externa.
Para obter mais informações sobre regras e como especificar uma ação de erro, consulte [Criando uma AWS IoT regra](https://docs.aws.amazon.com//iot/latest/developerguide/iot-create-rule.html).
Para obter mais informações sobre como usar CloudWatch para monitorar o sucesso ou o fracasso das regras, consulte[AWS IoT métricas e dimensões](metrics_dimensions.md).
# Reduzir custos do sistema de mensagens com Ingestão básica
Você pode usar a Ingestão básica para enviar dados de dispositivos com segurança para os Serviços da AWS compatíveis com [AWS IoT ações de regras](iot-rule-actions.md) sem incorrer em [custos de mensagens](https://aws.amazon.com/iot-core/pricing/). A Ingestão básica otimiza o fluxo de dados removendo o agente de mensagens de publicação/assinatura do caminho da ingestão.
A Ingestão básica pode enviar mensagens de seus dispositivos ou aplicativos. As mensagens têm nomes de tópicos que começam com `$aws/rules/rule_name` para os três primeiros níveis, onde `rule_name` é o nome da regra de AWS IoT que você deseja invocar.
Você pode continuar a usar uma regra existente com a Ingestão básica adicionando o prefixo de Ingestão básica (`$aws/rules/rule_name`) ao tópico da mensagem com o qual você normalmente invoca a regra. Por exemplo, se você tiver uma regra chamada `BuildingManager` que é invocada por mensagens com tópicos, como `Buildings/Building5/Floor2/Room201/Lights` (`"sql": "SELECT * FROM 'Buildings/#'"`), você poderá invocar a mesma regra com a Ingestão básica enviando uma mensagem com o tópico `$aws/rules/BuildingManager/Buildings/Building5/Floor2/Room201/Lights`.
**nota**
Seus dispositivos e regras não podem se inscrever em tópicos reservados da Ingestão básica. Por exemplo, as métricas AWS IoT Device Defender e as métricas `num-messages-received` não são emitidas, pois não permitem a assinatura de tópicos. Para obter mais informações, consulte [Tópicos reservados](reserved-topics.md).
Se você precisar de um agente de publicação/assinatura para distribuir mensagens a vários assinantes (por exemplo, para entregar mensagens para outros dispositivos e para o mecanismo de regras), deverá continuar a usar o agente de mensagens do AWS IoT para lidar com a distribuição da mensagem. No entanto, certifique-se de publicar suas mensagens em tópicos que não sejam tópicos da Ingestão básica.
## Usar a Ingestão básica
Antes de usar a Ingestão básica, verifique se seu dispositivo ou aplicativo está usando uma [política](iot-policies.md) com permissões de publicação em `$aws/rules/*`. Você também pode especificar permissões para regras individuais com `$aws/rules/rule_name/*` na política. Caso contrário, seus dispositivos e aplicativos poderão continuar a usar suas conexões existentes com o AWS IoT Core.
Quando a mensagem atinge o mecanismo de regras, não há diferença na implementação ou no tratamento de erros entre as regras invocadas pela Ingestão básica e as invocadas pelas assinaturas de agentes de mensagens.
Você pode criar regras para uso com a Ingestão básica. Lembre-se do seguinte:
+ O prefixo inicial de um tópico de Ingestão básica (`$aws/rules/rule_name`) não está disponível na função [topic(Decimal)](iot-sql-functions.md#iot-function-topic).
+ Se você definir uma regra invocada apenas com a Ingestão básica, a cláusula `FROM` será opcional no campo `sql` da definição de `rule`. Ela ainda será necessária se a regra também for invocada por outras mensagens que devem ser enviadas por meio do agente de mensagens (por exemplo, porque essas outras mensagens devem ser distribuídas a vários assinantes). Para obter mais informações, consulte [AWS IoT Referência SQL](iot-sql-reference.md).
+ Os três primeiros níveis do tópico da Ingestão básica (`$aws/rules/rule_name`) não são inclusos no cálculo do tamanho máximo de 8 segmentos ou no limite total de 256 caracteres por tópico. Caso contrário, as mesmas restrições se aplicarão conforme documentado em [Limites de AWS IoT](https://docs.aws.amazon.com/general/latest/gr/iot-core.html#limits_iot).
+ Se uma mensagem for recebida com um tópico da Ingestão básica que especifica uma regra inativa ou uma regra que não existe, um log de erros será criado em um log do Amazon CloudWatch para ajudá-lo com a depuração. Para obter mais informações, consulte [Entradas de log do mecanismo de regras](cwl-format.md#rule-engine-logs). Uma métrica `RuleNotFound` é indicada e você pode criar alarmes nessa métrica. Para obter mais informações, consulte Métricas de regras em [Métricas de regra](metrics_dimensions.md#rulemetrics).
+ Você ainda poderá publicar com QoS 1 em tópicos de Ingestão básica. Você recebe uma PUBACK depois que a mensagem é entregue com êxito ao mecanismo de regras. O recebimento de uma PUBACK não indica que as ações da regra foram concluídas com êxito. Você pode configurar uma ação de erro para lidar com erros durante a execução de uma ação. Para obter mais informações, consulte [Tratamento de erros (ação de erro)](rule-error-handling.md).
# AWS IoT Referência SQL
Em AWS IoT, as regras são definidas usando uma sintaxe semelhante a SQL. As declarações do SQL são compostas por três tipos de cláusulas:
**SET**
(Opcional) Define variáveis que você pode reutilizar em todas as instruções SQL e modelos de substituição. Atribua valores às variáveis usando expressões. Faça referência a essas variáveis nas cláusulas SELECT e WHERE e nos modelos de substituição de ações.
A cláusula SET suporta [Tipos de dados](iot-sql-data-types.md)[Operadores](iot-sql-operators.md),[Funções](iot-sql-functions.md),[Literais](iot-sql-literals.md),[Declarações de caso](iot-sql-case.md),,[Extensões JSON](iot-sql-json.md), [Variáveis](iot-sql-set.md#iot-sql-set-usage) e. [Consultas de objeto aninhado](iot-sql-nested-queries.md)
**SELECT**
(Obrigatório) Extrai informações da carga útil da mensagem de entrada e executa transformações nas informações. As mensagens a serem usadas são identificadas pelo [filtro de tópico](topics.md#topicfilters) especificado na cláusula FROM.
A cláusula SELECT oferece suporte a [Tipos de dados](iot-sql-data-types.md) [Operadores](iot-sql-operators.md) [Funções](iot-sql-functions.md)[Literais](iot-sql-literals.md),[Declarações de caso](iot-sql-case.md),,[Extensões JSON](iot-sql-json.md),[Modelos de substituição](iot-substitution-templates.md),, [Variáveis](iot-sql-set.md#iot-sql-set-usage)[Consultas de objeto aninhado](iot-sql-nested-queries.md), e. [Cargas binárias](binary-payloads.md)
**FROM**
O [filtro de tópicos](topics.md#topicfilters) de mensagens do MQTT que identifica as mensagens das quais extrair dados. A regra é ativada para cada mensagem enviada para um tópico MQTT que corresponda ao filtro de tópico especificado aqui. Obrigatório para regras que são ativadas por mensagens que passam pelo agente de mensagens. Opcional para regras que só são ativadas usando o atributo [Ingestão básica](iot-basic-ingest.md).
**WHERE**
(Opcional) Adiciona lógica condicional que determina se as ações especificadas por uma regra são executadas.
A cláusula WHERE suporta [Tipos de dados](iot-sql-data-types.md)[Operadores](iot-sql-operators.md),[Funções](iot-sql-functions.md),[Literais](iot-sql-literals.md),[Declarações de caso](iot-sql-case.md),[Extensões JSON](iot-sql-json.md),, [Variáveis](iot-sql-set.md#iot-sql-set-usage) e. [Consultas de objeto aninhado](iot-sql-nested-queries.md)
Um exemplo de declaração do SQL é semelhante a:
```
SELECT color AS rgb FROM 'topic/subtopic' WHERE temperature > 50
```
Um exemplo de mensagem MQTT (também chamada de carga útil de entrada) é semelhante a:
```
{
"color":"red",
"temperature":100
}
```
Se essa mensagem for publicada no tópico `'topic/subtopic'`, a regra será acionada, e a declaração do SQL será avaliada. A declaração do SQL extrairá o valor da propriedade `color` se a propriedade `"temperature"` for superior a 50. A cláusula WHERE especifica a condição `temperature > 50`. A palavra-chave `AS` renomeia a propriedade `"color"` para `"rgb"`. O resultado (também chamado de *carga útil de saída*) é semelhante a:
```
{
"rgb":"red"
}
```
Esses dados são encaminhados para a ação da regra, que envia os dados para realizar mais processamento. Para saber mais sobre as ações de regra, consulte [AWS IoT ações de regras](iot-rule-actions.md).
**nota**
Atualmente, não há suporte para comentários na sintaxe AWS IoT SQL.
Nomes de atributos com espaços não podem ser usados como nomes de campo na instrução SQL. Embora a carga de entrada possa ter nomes de atributos com espaços, esses nomes não podem ser usados na instrução SQL. No entanto, eles serão passados para a carga de saída se você usar uma especificação de nome de campo curinga (\$1).
# Cláusula SELECT
A cláusula AWS IoT SELECT é essencialmente a mesma que a cláusula ANSI SQL SELECT, com algumas pequenas diferenças.
A cláusula SELECT suporta [Tipos de dados](iot-sql-data-types.md)[Operadores](iot-sql-operators.md),[Funções](iot-sql-functions.md),[Literais](iot-sql-literals.md),[Declarações de caso](iot-sql-case.md),[Extensões JSON](iot-sql-json.md),, [Variáveis](iot-sql-set.md#iot-sql-set-usage)[Consultas de objeto aninhado](iot-sql-nested-queries.md), e. [Cargas binárias](binary-payloads.md)
Você pode usar a cláusula SELECT para extrair informações das mensagens MQTT recebidas. Você também pode usar `SELECT *` para recuperar toda a carga útil da mensagem recebida. Por exemplo:
```
Incoming payload published on topic 'topic/subtopic': {"color":"red", "temperature":50}
SQL statement: SELECT * FROM 'topic/subtopic'
Outgoing payload: {"color":"red", "temperature":50}
```
Se a carga útil for um objeto JSON, você poderá fazer referência a chaves no objeto. A carga útil de saída contém o par de chave/valor. Por exemplo:
```
Incoming payload published on topic 'topic/subtopic': {"color":"red", "temperature":50}
SQL statement: SELECT color FROM 'topic/subtopic'
Outgoing payload: {"color":"red"}
```
Você pode usar o teclado AS para renomear chaves. Por exemplo:
```
Incoming payload published on topic 'topic/subtopic':{"color":"red", "temperature":50}
SQL:SELECT color AS my_color FROM 'topic/subtopic'
Outgoing payload: {"my_color":"red"}
```
Você pode selecionar vários itens ao separá-los com uma vírgula. Por exemplo:
```
Incoming payload published on topic 'topic/subtopic': {"color":"red", "temperature":50}
SQL: SELECT color as my_color, temperature as fahrenheit FROM 'topic/subtopic'
Outgoing payload: {"my_color":"red","fahrenheit":50}
```
Você pode selecionar vários itens incluindo '\$1' para adicionar itens à carga útil de entrada. Por exemplo:
```
Incoming payload published on topic 'topic/subtopic': {"color":"red", "temperature":50}
SQL: SELECT *, 15 as speed FROM 'topic/subtopic'
Outgoing payload: {"color":"red", "temperature":50, "speed":15}
```
Você pode usar a palavra-chave `"VALUE"` para produzir cargas úteis de saída que não são objetos JSON. Com a versão SQL `2015-10-08`, você pode selecionar apenas um item. Com a versão `2016-03-23` do SQL ou posterior, você também pode selecionar uma matriz para saída como um objeto de nível superior.
**Example**
```
Incoming payload published on topic 'topic/subtopic': {"color":"red", "temperature":50}
SQL: SELECT VALUE color FROM 'topic/subtopic'
Outgoing payload: "red"
```
Você pode usar a sintaxe `'.'` para analisar os objetos JSON aninhados na carga útil de entrada. Por exemplo:
```
Incoming payload published on topic 'topic/subtopic': {"color":{"red":255,"green":0,"blue":0}, "temperature":50}
SQL: SELECT color.red as red_value FROM 'topic/subtopic'
Outgoing payload: {"red_value":255}
```
Para obter informações sobre como usar nomes de objetos e propriedades JSON que incluem caracteres reservados, como números ou o caractere de hífen (menos), consulte [Extensões JSON](iot-sql-json.md)
Você pode usar funções (consulte [Funções](iot-sql-functions.md)) para transformar a carga útil de entrada. Você pode usar parênteses para agrupamento. Por exemplo:
```
Incoming payload published on topic 'topic/subtopic': {"color":"red", "temperature":50}
SQL: SELECT (temperature - 32) * 5 / 9 AS celsius, upper(color) as my_color FROM 'topic/subtopic'
Outgoing payload: {"celsius":10,"my_color":"RED"}
```
# Cláusula FROM
A cláusula FROM inscreve sua regra em um [tópico](topics.md#topicnames) ou [filtro de tópicos](topics.md#topicfilters). Coloque o filtro de tópicos ou tópico entre aspas simples ('). A regra é acionada para cada mensagem enviada para um tópico MQTT que corresponda ao filtro de tópico especificado aqui. Você pode permite se inscrever em um grupo de tópicos semelhantes usando um filtro de tópicos.
**Exemplo:**
Carga útil de entrada publicada no tópico `'topic/subtopic'`: `{temperature: 50}`
Carga útil de entrada publicada no tópico `'topic/subtopic-2'`: `{temperature: 50}`
SQL: `"SELECT temperature AS t FROM 'topic/subtopic'"`.
A regra é inscrita em `'topic/subtopic'`, de modo que a carga útil de entrada é passada para a regra. A carga útil de saída, passada para as ações da regra, é: `{t: 50}`. A regra não está inscrita em `'topic/subtopic-2'`; portanto, a regra não é acionada para a mensagem publicada em `'topic/subtopic-2'`.
**Exemplo de curinga \$1:**
Você pode usar o caractere curinga "\$1" (com vários níveis) para corresponder a um ou mais elementos de caminho específicos:
Carga útil de entrada publicada no tópico `'topic/subtopic'`: `{temperature: 50}`.
Carga útil de entrada publicada no tópico `'topic/subtopic-2'`: `{temperature: 60}`.
Carga útil de entrada publicada no tópico `'topic/subtopic-3/details'`: `{temperature: 70}`.
Carga útil de entrada publicada no tópico `'topic-2/subtopic-x'`: `{temperature: 80}`.
SQL: `"SELECT temperature AS t FROM 'topic/#'"`.
A regra está inscrita em qualquer tópico que comece com`'topic'`, então é executada três vezes, enviando cargas de saída de (para tópico/subtópico), `{t: 50}` (para tópico/subtópico-2) e `{t: 60}` (para) para suas ações. `{t: 70}` topic/subtopic-3/details Se não estiver inscrito em `'topic-2/subtopic-x'`, a regra não será acionada para a mensagem `{temperature: 80}`.
**Exemplo de curinga \$1:**
Você pode usar o caractere curinga "\$1" (com nível único) para corresponder a qualquer elemento de caminho específico:
Carga útil de entrada publicada no tópico `'topic/subtopic'`: `{temperature: 50}`.
Carga útil de entrada publicada no tópico `'topic/subtopic-2'`: `{temperature: 60}`.
Carga útil de entrada publicada no tópico `'topic/subtopic-3/details'`: `{temperature: 70}`.
Carga útil de entrada publicada no tópico `'topic-2/subtopic-x'`: `{temperature: 80}`.
SQL: `"SELECT temperature AS t FROM 'topic/+'"`.
A regra é inscrita em todos os tópicos com dois elementos de caminho, em que o primeiro elemento é `'topic'`. A regra é executada para as mensagens enviadas para `'topic/subtopic'` e `'topic/subtopic-2'`, mas não `'topic/subtopic-3/details'` (tem mais níveis do que o filtro de tópicos) ou `'topic-2/subtopic-x'` (não começa com `topic`).
# Cláusula SET
Use a cláusula SET para definir variáveis que armazenam resultados de expressões. Você pode reutilizar essas variáveis nas cláusulas SELECT e WHERE e em modelos de substituição. Isso ajuda a evitar a duplicação de expressões complexas e a reduzir o número de chamadas de função em sua instrução SQL.
A cláusula SET suporta [Tipos de dados](iot-sql-data-types.md)[Operadores](iot-sql-operators.md),[Funções](iot-sql-functions.md),[Literais](iot-sql-literals.md),[Declarações de caso](iot-sql-case.md),,[Extensões JSON](iot-sql-json.md), [Variáveis](#iot-sql-set-usage) e. [Consultas de objeto aninhado](iot-sql-nested-queries.md)
## Sintaxe da cláusula SET
A cláusula SET deve aparecer antes da cláusula SELECT em sua instrução SQL. Use a seguinte sintaxe:
```
SET @variable_name = expression [, @variable_name2 = expression2]
```
Regras de sintaxe:
+ Inicie os nomes das variáveis com `@`
+ Os nomes das variáveis podem conter letras, números e sublinhados
+ Os nomes das variáveis podem ter até 64 caracteres
+ Várias variáveis podem ser definidas em uma única cláusula SET, separadas por vírgulas
+ Cada variável só pode ser atribuída uma vez (as variáveis são imutáveis)
+ A palavra-chave SET só pode ser usada uma vez por instrução SQL
## Usando variáveis
Depois de definir as variáveis, você pode usá-las em:
+ Cláusulas SELECT
+ Cláusulas WHERE
+ Outras atribuições de variáveis SET
+ Modelos de substituição de ações
+ Modelos de substituição de ações de erro
+ Consultas SELECT aninhadas
+ Parâmetros de função (certos parâmetros, como parâmetros do RoLearn e parâmetros que alternam o modo de uma função semelhante a `transform("enrichArray", attributes, values)` que não suportam variáveis)
As variáveis são referenciadas usando a mesma `@variable_name` sintaxe usada na cláusula SET. Você também pode usar a sintaxe da extensão JSON para acessar propriedades de variáveis que contêm objetos, como. `@variable_name.property`
## Exemplos da cláusula SET
**Uso básico de variáveis**
O exemplo a seguir mostra uma carga publicada no tópico`device/data`: `{"temp_fahrenheit": 75, "humidity": 60}`
Declaração do SQL:
```
SET @temp_celsius = (temp_fahrenheit - 32) * 5 / 9
SELECT @temp_celsius AS celsius, humidity FROM 'device/data'
```
Carga útil de saída: `{"celsius": 23.89, "humidity": 60}`
**Acesse membros em objetos JSON incorporados**
O exemplo a seguir mostra uma carga publicada no tópico`device/data`: `{"device1": {"deviceId":"weather_sensor", "deviceData": {"sensors": {"temp_fahrenheit": 75, "humidity": 60}, "location": [47.606,-122.332]}}}`
Declaração do SQL:
```
SET @device_sensor_data = device1.deviceData.sensors
SELECT @device_sensor_data.temp_fahrenheit AS temp_fahrenheit, @device_sensor_data.humidity as humidity, device1.deviceId as deviceId FROM 'device/data'
```
Carga útil de saída: `{"temp_fahrenheit":75,"humidity":60,"deviceId":"weather_sensor"}`
para obter mais informações sobre como trabalhar com extensões JSON, consulte [Extensões JSON](iot-sql-json.md)
**Evitando chamadas de função duplicadas**
As variáveis SET ajudam a evitar a duplicação de operações complexas de decodificação:
```
SET @decoded_data = decode(encode(*, 'base64'), 'proto', 'schema', 'schema.desc', 'message.proto', 'Message')
SELECT @decoded_data.sensor_id, @decoded_data.reading FROM 'device/protobuf'
WHERE @decoded_data.reading > 100
```
Sem as variáveis SET, você precisaria repetir a função de decodificação três vezes, o que excede os limites de chamada da função.
**Várias variáveis**
Você pode definir várias variáveis em uma única cláusula SET separando-as com vírgulas:
```
SET @user_data = get_user_properties(device_id), @threshold = 50
SELECT @user_data.name, temp_fahrenheit FROM 'sensors/+'
WHERE temp_fahrenheit > @threshold AND @user_data.active = true
```
**Usando variáveis em modelos de substituição**
As variáveis também podem ser usadas em modelos de substituição de ações, permitindo que você reutilize valores computados nas ações da instrução SQL e da regra.
Declaração do SQL:
```
SET @temp_celsius = (temp_fahrenheit - 32) * 5 / 9
SELECT @temp_celsius AS celsius, humidity FROM 'device/data'
```
Configuração da ação:
```
{
"s3": {
"roleArn": "arn:aws:iam::123456789012:role/testRuleRole",
"bucketName": "bucket",
"key": "temperature-data/${device_id}/temp-${@temp_celsius}C.json"
}
}
```
Neste exemplo, a variável SET `@temp_celsius` é usada em um modelo de substituição para construir o campo chave da ação S3.
**Uso de carga útil não JSON**
As variáveis SET não oferecem suporte direto a cargas não JSON, portanto, a carga deve ser codificada ou decodificada primeiro:
```
SET @encoded_payload = encode(*, 'base64')
SELECT @encoded_payload AS raw_data FROM 'device/binary'
```
para obter mais informações sobre como trabalhar com cargas não JSON, consulte [Como trabalhar com cargas úteis binárias](binary-payloads.md)
## Limites da cláusula SET
Os limites a seguir se aplicam às variáveis SET:
+ Máximo de 10 variáveis exclusivas por instrução SQL
+ Tamanho máximo do valor variável de 128 KiB (string JSON UTF-8 minificada)
+ Tamanho máximo do valor total de 128 KiB para todas as variáveis
+ Nomes de variáveis limitados a 64 caracteres
+ As variáveis podem aceitar cargas JSON diretamente como estão (cargas não JSON devem primeiro ser codificadas/decodificadas)
# Cláusula WHERE
A cláusula WHERE determina se as ações especificadas por uma regra são executadas. Se a cláusula WHERE for avaliada como verdadeira, as ações da regra serão executadas. Caso contrário, as ações da regra não serão executadas.
A cláusula WHERE suporta [Tipos de dados](iot-sql-data-types.md)[Operadores](iot-sql-operators.md),[Funções](iot-sql-functions.md),[Literais](iot-sql-literals.md),[Declarações de caso](iot-sql-case.md),[Extensões JSON](iot-sql-json.md),, [Variáveis](iot-sql-set.md#iot-sql-set-usage) e. [Consultas de objeto aninhado](iot-sql-nested-queries.md)
**Exemplo:**
Carga útil de entrada publicada em `topic/subtopic`: `{"color":"red", "temperature":40}`.
SQL: `SELECT color AS my_color FROM 'topic/subtopic' WHERE temperature > 50 AND color <> 'red'`.
Nesse caso, a regra será acionada, mas as ações especificadas pela regra não serão executadas. Não haverá carga útil de saída.
Você pode usar funções e operadores na cláusula WHERE. No entanto, você não pode fazer referência a aliases criados com a palavra-chave AS no SELECT. A cláusula WHERE é avaliada primeiro para determinar se SELECT será avaliada.
**Exemplo com carga útil não JSON:**
Carga útil não JSON de entrada publicada em `tópico/subtópico`: `80`
SQL: ``SELECT decode(encode(*, 'base64'), 'base64') AS value FROM 'topic/subtopic' WHERE decode(encode(*, 'base64'), 'base64') > 50`
Nesse caso, a regra será acionada e as ações especificadas pela regra serão executadas. A carga útil de saída será transformada pela cláusula SELECT como uma carga JSON `{"value":80}`.
# Tipos de dados
O mecanismo de AWS IoT regras é compatível com todos os tipos de dados JSON.
**Tipos de dados compatíveis**
| Tipo | Significado |
| --- | --- |
| Int | Um discreto Int. 34 dígitos no máximo. |
| Decimal | Um `Decimal` com uma precisão de 34 dígitos, com um mínimo de magnitude não zero de 1E-999 e um máximo de magnitude de 9,999...E999. Algumas funções geram valores `Decimal` com precisão dupla em vez de precisão de 34 dígitos. Com o SQL V2 (23/03/2016), valores numéricos que são números inteiros, como `10.0`, são processados como um valor `Int` (`10`) em vez do valor `Decimal` esperado (`10.0`). Para processar de forma confiável valores numéricos inteiros como valores `Decimal`, use o SQL V1 (08/10/2015) para a instrução de consulta de regra. |
| Boolean | True ou False. |
| String | Uma string UTF-8. |
| Array | Uma série de valores que não precisam ter o mesmo tipo. |
| Object | Um valor JSON que consiste em uma chave e um valor. As chaves devem ser strings. Os valores podem ser de qualquer tipo. |
| Null | Null conforme definido pelo JSON. É um valor real que representa a ausência de um valor. Você pode criar explicitamente um valor Null usando a palavra-chave Null na declaração do SQL. Por exemplo: "SELECT NULL AS n FROM 'topic/subtopic'" |
| Undefined | Não é um valor. Não é explicitamente representável no JSON, exceto ao omitir o valor. Por exemplo, no objeto `{"foo": null}`, a chave "foo" gera NULL, mas a chave "bar" gera `Undefined`. Internamente, a linguagem SQL trata `Undefined` como um valor, mas não é representável no JSON; portanto, quando serializados para JSON, os resultados são `Undefined`. {"foo":null, "bar":undefined} é serializado para JSON como: {"foo":null} Da mesma forma, `Undefined` é convertido em uma string vazia quando serializado por conta própria. Funções chamadas com argumentos inválidos (por exemplo, tipos incorretos, número incorreto de argumentos, etc.) retornam `Undefined`. |
## Conversões
A tabela a seguir indica os resultados quando um valor de um tipo é convertido em outro tipo (quando um valor do tipo incorreto é dado a uma função). Por exemplo, se a função de valor absoluto "abs" (que espera um `Int` ou `Decimal`) for dado a `String`, ela tentará converter `String` em um `Decimal`, seguindo essas regras. Nesse caso, “abs ("-5,123")” é tratado como “abs(-5,123)”.
**nota**
Não há tentativa de conversões para `Array`, `Object`, `Null` ou `Undefined`.
**Para decimal**
| Tipo de argumento | Resultado |
| --- | --- |
| Int | Um Decimal sem ponto decimal. |
| Decimal | O valor de origem. |
| Boolean | Undefined. (Você pode explicitamente usar a função cast para transformar verdadeiro = 1,0, falso = 0,0.) |
| String | O mecanismo SQL tenta analisar a string como a. Decimal AWS IoT tenta analisar cadeias de caracteres que correspondam à expressão regular:. ^-?\$1d\$1(\$1.\$1d\$1)?((?i)E-?\$1d\$1)?\$1 "0", "-1,2" e "5E-12" são exemplos de strings que são automaticamente convertidas em Decimals. |
| Array | Undefined. |
| Objeto | Undefined. |
| Null | Null. |
| Não definido | Undefined. |
**Para int**
| Tipo de argumento | Resultado |
| --- | --- |
| Int | O valor de origem. |
| Decimal | O valor de origem arredondado para o Int mais próximo. |
| Boolean | Undefined. (Você pode explicitamente usar a função cast para transformar verdadeiro = 1,0, falso = 0,0.) |
| String | O mecanismo SQL tenta analisar a string como a. Decimal AWS IoT tenta analisar cadeias de caracteres que correspondam à expressão regular:. ^-?\$1d\$1(\$1.\$1d\$1)?((?i)E-?\$1d\$1)?\$1 “0", “-1.2", “5E-12" são todos exemplos de strings que são convertidas automaticamente em Decimal s. AWS IoT tenta converter o em a eDecimal, em seguida, trunca as casas decimais String para formar um. Decimal Int |
| Array | Undefined. |
| Objeto | Undefined. |
| Null | Null. |
| Não definido | Undefined. |
**Para Booleano**
| Tipo de argumento | Resultado |
| --- | --- |
| Int | Undefined. (Você pode explicitamente usar a função cast para transformar 0 = Falso, qualquer\$1valor\$1não\$1zero = Verdadeiro.) |
| Decimal | Undefined. (Você pode explicitamente usar a função cast para transformar 0 = Falso, qualquer\$1valor\$1não\$1zero = Verdadeiro.) |
| Boolean | O valor original. |
| String | "true" = Verdadeiro e "false" = Falso (não diferencia maiúsculas de minúsculas). Outros valores de string são Undefined. |
| Array | Undefined. |
| Objeto | Undefined. |
| Null | Undefined. |
| Não definido | Undefined. |
**Para string**
| Tipo de argumento | Resultado |
| --- | --- |
| Int | Uma representação de string do Int em notação padrão. |
| Decimal | Uma string representando o valor Decimal, possivelmente em notação científica. |
| Boolean | "true" ou "false". Todas as letras minúsculas. |
| String | O valor original. |
| Array | A Array serializada para JSON. A string resultante é uma lista separada por vírgulas, entre colchetes. A String tem aspas. Um Decimal, Int, Boolean e Null não. |
| Objeto | O objeto serializado para JSON. A string resultante é uma lista separada por vírgulas de pares de chave/valor e começa e termina com chaves. A String tem aspas. Um Decimal, Int, Boolean e Null não. |
| Null | Undefined. |
| Não definido | Indefinido. |
# Operadores
Os operadores a seguir podem ser usados nas cláusulas SELECT e WHERE.
## Operador AND
Gera um resultado `Boolean`. Realiza uma operação E lógica. Retornará verdadeiro se os operandos esquerdo e direito forem verdadeiros. Caso contrário, retorna false. Os operandos `Boolean` ou operandos de string "true" ou "false" que não diferenciam letras maiúsculas de minúsculas são necessários.
*Sintaxe:* ` expression AND expression`.
**Operador AND**
| Operando esquerdo | Operando direito | Output |
| --- | --- | --- |
| Boolean | Boolean | Boolean. Verdadeiro se ambos os operandos forem verdadeiros. Caso contrário, falso. |
| String/Boolean | String/Boolean | Se todas as strings forem "true" ou "false" (não diferencia letras maiúsculas de minúsculas), elas serão convertidas em Boolean e processadas normalmente como boolean AND boolean. |
| Outros valores | Outros valores | Undefined. |
## Operador OU
Gera um resultado `Boolean`. Executa uma operação OU lógica. Retornará verdadeiro se um dos operandos esquerdo ou direito for verdadeiro. Caso contrário, retorna false. Os operandos `Boolean` ou operandos de string "true" ou "false" que não diferenciam letras maiúsculas de minúsculas são necessários.
*Sintaxe:* ` expression OR expression`.
**Operador OU**
| Operando esquerdo | Operando direito | Output |
| --- | --- | --- |
| Boolean | Boolean | Boolean. Verdadeiro se um dos operandos for verdadeiro. Caso contrário, falso. |
| String/Boolean | String/Boolean | Se todas as strings forem "true" ou "false" (não diferencia letras maiúsculas de minúsculas), elas serão convertidas em booleanos e processadas normalmente como boolean OR boolean. |
| Outros valores | Outros valores | Undefined. |
## Operador NOT
Gera um resultado `Boolean`. Realiza uma operação NÃO lógica. Retornará verdadeiro se o operando for falso. Caso contrário, retornará verdadeiro. Um operando `Boolean` ou operando de string "true" ou "false" que não diferencia letras maiúsculas de minúsculas é necessário.
*Sintaxe:* `NOT expression`.
**Operador NOT**
| Operando | Output |
| --- | --- |
| Boolean | Boolean. Verdadeiro se o operando for falso. Caso contrário, verdadeiro. |
| String | Se a string for "true" ou "false" (não diferencia letras maiúsculas de minúsculas), ela será convertida no valor booliano correspondente, e o valor oposto será gerado. |
| Outros valores | Undefined. |
## Operador IN
Gera um resultado `Boolean`. Você pode usar o operador IN em uma cláusula WHERE para verificar se um valor corresponde a algum valor em uma matriz. Ele retornará verdadeiro se a correspondência for encontrada; caso contrário, retornará falso.
*Sintaxe:* ` expression IN expression`.
**Operador IN**
| Operando esquerdo | Operando direito | Output |
| --- | --- | --- |
| Int/Decimal/String/Array/Object | Array | Verdadeiro se o elemento Integer/Decimal/String/Array/Object for encontrado na matriz. Caso contrário, falso. |
*Exemplo:*
```
SQL: "select * from 'a/b' where 3 in arr"
JSON: {"arr":[1, 2, 3, "three", 5.7, null]}
```
Neste exemplo, a cláusula de condição `where 3 in arr` será avaliada como verdadeira porque 3 está presente na matriz chamada `arr`. Portanto, na instrução SQL, `select * from 'a/b'` será executado. Esse exemplo também mostra que a matriz pode ser heterogênea.
## Operador EXISTS
Gera um resultado `Boolean`. Você poderá usar o operador EXISTS em uma cláusula condicional para testar a existência de elementos em uma subconsulta. Ele retornará verdadeiro se a subconsulta retornar um ou mais elementos e falso se a subconsulta não retornar nenhum elemento.
*Sintaxe:* ` expression`.
*Exemplo:*
```
SQL: "select * from 'a/b' where exists (select * from arr as a where a = 3)"
JSON: {"arr":[1, 2, 3]}
```
Neste exemplo, a cláusula de condição `where exists (select * from arr as a where a = 3)` será avaliada como verdadeira porque 3 está presente na matriz chamada `arr`. Portanto, na instrução SQL, `select * from 'a/b'` será executado.
*Exemplo:*
```
SQL: select * from 'a/b' where exists (select * from e as e where foo = 2)
JSON: {"foo":4,"bar":5,"e":[{"foo":1},{"foo":2}]}
```
Neste exemplo, a cláusula de condição `where exists (select * from e as e where foo = 2)` será avaliada como verdadeira porque a matriz `e` dentro do objeto JSON contém o objeto `{"foo":2}`. Portanto, na instrução SQL, `select * from 'a/b'` será executado.
## > operador
Gera um resultado `Boolean`. Verdadeiro se o operando esquerdo for superior ao operando direito. Os dois operandos são convertidos em um `Decimal` e depois comparados.
*Sintaxe:* `expression > expression`.
**> operador**
| Operando esquerdo | Operando direito | Output |
| --- | --- | --- |
| Int/Decimal | Int/Decimal | Boolean. Verdadeiro se o operando esquerdo for superior ao operando direito. Caso contrário, falso. |
| String/Int/Decimal | String/Int/Decimal | Se todas as strings puderem ser convertidas em Decimal, então Boolean. Verdadeiro se o operando esquerdo for superior ao operando direito. Caso contrário, falso. |
| Outros valores | Undefined. | Undefined. |
## >= operador
Gera um resultado `Boolean`. Verdadeiro se o operando esquerdo for superior ou igual ao operando direito. Os dois operandos são convertidos em um `Decimal` e depois comparados.
*Sintaxe:* `expression >= expression`.
**>= operador**
| Operando esquerdo | Operando direito | Output |
| --- | --- | --- |
| Int/Decimal | Int/Decimal | Boolean. Verdadeiro se o operando esquerdo for igual ou superior ao operando direito. Caso contrário, falso. |
| String/Int/Decimal | String/Int/Decimal | Se todas as strings puderem ser convertidas em Decimal, então Boolean. Verdadeiro se o operando esquerdo for superior ou igual ao operando direito. Caso contrário, falso. |
| Outros valores | Undefined. | Undefined. |
## < operador
Gera um resultado `Boolean`. Verdadeiro se o operando esquerdo for inferior ao operando direito. Os dois operandos são convertidos em um `Decimal` e depois comparados.
*Sintaxe:* `expression < expression`.
**< operador**
| Operando esquerdo | Operando direito | Output |
| --- | --- | --- |
| Int/Decimal | Int/Decimal | Boolean. Verdadeiro se o operando esquerdo for inferior ao operando direito. Caso contrário, falso. |
| String/Int/Decimal | String/Int/Decimal | Se todas as strings puderem ser convertidas em Decimal, então Boolean. Verdadeiro se o operando esquerdo for inferior ao operando direito. Caso contrário, falso. |
| Outros valores | Undefined | Undefined |
## <= operador
Gera um resultado `Boolean`. Verdadeiro se o operando esquerdo for inferior ou igual ao operando direito. Os dois operandos são convertidos em um `Decimal` e depois comparados.
*Syntaxe:* `expression <= expression`.
**<= operador**
| Operando esquerdo | Operando direito | Output |
| --- | --- | --- |
| Int/Decimal | Int/Decimal | Boolean. Verdadeiro se o operando esquerdo for igual ou inferior ao operando direito. Caso contrário, falso. |
| String/Int/Decimal | String/Int/Decimal | Se todas as strings puderem ser convertidas em Decimal, então Boolean. Verdadeiro se o operando esquerdo for inferior ou igual ao operando direito. Caso contrário, falso. |
| Outros valores | Undefined | Undefined |
## <> operador
Gera um resultado `Boolean`. Retornará verdadeiro se os operandos esquerdo e direito forem diferentes. Caso contrário, retornará falso.
*Sintaxe:* ` expression <> expression`.
**<> operador**
| Operando esquerdo | Operando direito | Output |
| --- | --- | --- |
| Int | Int | Verdadeiro se o operando esquerdo não for igual ao operando direito. Caso contrário, falso. |
| Decimal | Decimal | Verdadeiro se o operando esquerdo não for igual ao operando direito. Caso contrário, falso. Int é convertido em Decimal antes de ser comparado. |
| String | String | Verdadeiro se o operando esquerdo não for igual ao operando direito. Caso contrário, falso. |
| Array | Array | Verdadeiro se os itens em cada operando não forem iguais e não estiverem na mesma ordem. Caso contrário, falso |
| Objeto | Objeto | Verdadeiro se as chaves e os valores de cada operando não forem iguais. Caso contrário, falso. A ordem de não keys/values é importante. |
| Null | Null | Falso. |
| Qualquer valor | Undefined | Indefinido. |
| Undefined | Qualquer valor | Indefinido. |
| Tipo não correspondente | Tipo não correspondente | Verdadeiro. |
## = operador
Gera um resultado `Boolean`. Retornará verdadeiro se os operandos esquerdo e direito forem iguais. Caso contrário, retornará falso.
*Sintaxe:* ` expression = expression`.
**= operador**
| Operando esquerdo | Operando direito | Output |
| --- | --- | --- |
| Int | Int | Verdadeiro se o operando esquerdo for igual ao operando direito. Caso contrário, falso. |
| Decimal | Decimal | Verdadeiro se o operando esquerdo for igual ao operando direito. Caso contrário, falso. Int é convertido em Decimal antes de ser comparado. |
| String | String | Verdadeiro se o operando esquerdo for igual ao operando direito. Caso contrário, falso. |
| Array | Array | Verdadeiro se os itens em cada operando forem iguais e estiverem na mesma ordem. Caso contrário, falso. |
| Objeto | Objeto | Verdadeiro se as chaves e os valores de cada operando forem iguais. Caso contrário, falso. A ordem de não keys/values é importante. |
| Qualquer valor | Undefined | Undefined. |
| Undefined | Qualquer valor | Undefined. |
| Tipo não correspondente | Tipo não correspondente | Falso. |
## \$1 operador
" \$1" é um operador sobrecarregado. Ele pode ser usado para concatenação ou adição de string.
*Sintaxe:* ` expression + expression`.
**\$1 operador**
| Operando esquerdo | Operando direito | Output |
| --- | --- | --- |
| String | Qualquer valor | Converte o operando direito em uma string e concatena-o ao final do operando esquerdo. |
| Qualquer valor | String | Converte o operando esquerdo em uma string e concatena o operando direito ao final do operando esquerdo convertido. |
| Int | Int | Int value. Adiciona operandos juntos. |
| Int/Decimal | Int/Decimal | Decimal value. Adiciona operandos juntos. |
| Outros valores | Outros valores | Undefined. |
## - operador
Subtrai o operando direito do operando esquerdo.
*Sintaxe:* ` expression - expression`.
**- operador**
| Operando esquerdo | Operando direito | Output |
| --- | --- | --- |
| Int | Int | Int value. Subtrai o operando direito do operando esquerdo. |
| Int/Decimal | Int/Decimal | Decimal value. Subtrai o operando direito do operando esquerdo. |
| String/Int/Decimal | String/Int/Decimal | Se todas as strings forem convertidas em decimais corretamente, um valor Decimal será gerado. Subtrai o operando direito do operando esquerdo. Caso contrário, gera Undefined. |
| Outros valores | Outros valores | Undefined. |
| Outros valores | Outros valores | Undefined. |
## \$1 operador
Multiplica o operando esquerdo pelo operando direito.
*Sintaxe:* ` expression * expression`.
**\$1 operador**
| Operando esquerdo | Operando direito | Output |
| --- | --- | --- |
| Int | Int | Int value. Multiplica o operando esquerdo pelo operando direito. |
| Int/Decimal | Int/Decimal | Decimal value. Multiplica o operando esquerdo pelo operando direito. |
| String/Int/Decimal | String/Int/Decimal | Se todas as strings forem convertidas em decimais corretamente, um valor Decimal será gerado. Multiplica o operando esquerdo pelo operando direito. Caso contrário, gera Undefined. |
| Outros valores | Outros valores | Undefined. |
## / operador
Divide o operando esquerdo pelo operando direito.
*Sintaxe:* ` expression / expression`.
**/ operador**
| Operando esquerdo | Operando direito | Output |
| --- | --- | --- |
| Int | Int | Int value. Divide o operando esquerdo pelo operando direito. |
| Int/Decimal | Int/Decimal | Decimal value. Divide o operando esquerdo pelo operando direito. |
| String/Int/Decimal | String/Int/Decimal | Se todas as strings forem convertidas em decimais corretamente, um valor Decimal será gerado. Divide o operando esquerdo pelo operando direito. Caso contrário, gera Undefined. |
| Outros valores | Outros valores | Undefined. |
## % operador
Gera o restante da divisão do operando esquerdo pelo operando direito.
*Sintaxe:* ` expression % expression`.
**% operador**
| Operando esquerdo | Operando direito | Output |
| --- | --- | --- |
| Int | Int | Int value. Gera o restante da divisão do operando esquerdo pelo operando direito. |
| String/Int/Decimal | String/Int/Decimal | Se todas as strings forem convertidas em decimais corretamente, um valor Decimal será gerado. Gera o restante da divisão do operando esquerdo pelo operando direito. Caso contrário, Undefined. |
| Outros valores | Outros valores | Undefined. |
# Funções
Você pode usar as seguintes funções integradas nas cláusulas SELECT ou WHERE das expressões do SQL.
As seguintes funções externas são cobradas de forma equivalente à de uma ação de regra: [https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-func-aws-lambda](https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-func-aws-lambda), [https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-sql-function-get-registry_data](https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-sql-function-get-registry_data), e. [https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-sql-function-get-thing-shadow](https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-sql-function-get-thing-shadow) Você também é cobrado pela função [https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-sql-decode-base64](https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-sql-decode-base64) apenas quando está [decodificando uma mensagem Protobuf para JSON](https://docs.aws.amazon.com//iot/latest/developerguide/binary-payloads.html#binary-payloads-protobuf). Para obter mais detalhes, consulte a [página de precificação do AWS IoT Core](https://aws.amazon.com/iot-core/pricing/).
## abs(Decimal)
Gera o valor absoluto de um número. Compatível com a versão de 08/10/2015 do SQL e posteriores.
Exemplo: `abs(-5)` gera 5.
****
| Tipo de argumento | Resultado |
| --- | --- |
| Int | Int, o valor absoluto do argumento. |
| Decimal | Decimal, o valor absoluto do argumento. |
| Boolean | Undefined. |
| String | Decimal. O resultado é o valor absoluto do argumento. Se a string não puder ser convertida, o resultado será Undefined. |
| Array | Undefined. |
| Objeto | Undefined. |
| Null | Undefined. |
| Não definido | Undefined. |
## accountid()
Gera o ID da conta que possui essa regra como uma `String`. Compatível com a versão de 08/10/2015 do SQL e posteriores.
Exemplo:
`accountid() ` = "123456789012"
## acos(Decimal)
Gera o cosseno inverso de um número em radianos. Argumentos `Decimal` são arredondados para dobrar a precisão antes da aplicação da função. Compatível com a versão de 08/10/2015 do SQL e posteriores.
Exemplo: `acos(0)` = 1,5707963267948966
****
| Tipo de argumento | Resultado |
| --- | --- |
| Int | Decimal (com precisão dupla), o cosseno inverso do argumento. Os resultados imaginários são gerados como Undefined. |
| Decimal | Decimal (com precisão dupla), o cosseno inverso do argumento. Os resultados imaginários são gerados como Undefined. |
| Boolean | Undefined. |
| String | Decimal, o cosseno inverso do argumento. Se a string não puder ser convertida, o resultado será Undefined. Os resultados imaginários são gerados como Undefined. |
| Array | Undefined. |
| Objeto | Undefined. |
| Null | Undefined. |
| Não definido | Undefined. |
## asin(Decimal)
Gera o seno inverso de um número em radianos. Argumentos `Decimal` são arredondados para dobrar a precisão antes da aplicação da função. Compatível com a versão de 08/10/2015 do SQL e posteriores.
Exemplo: `asin(0)` = 0,0
****
| Tipo de argumento | Resultado |
| --- | --- |
| Int | Decimal (com precisão dupla), o seno inverso do argumento. Os resultados imaginários são gerados como Undefined. |
| Decimal | Decimal (com precisão dupla), o seno inverso do argumento. Os resultados imaginários são gerados como Undefined. |
| Boolean | Undefined. |
| String | Decimal (com precisão dupla), o seno inverso do argumento. Se a string não puder ser convertida, o resultado será Undefined. Os resultados imaginários são gerados como Undefined. |
| Array | Undefined. |
| Objeto | Undefined. |
| Null | Undefined. |
| Não definido | Undefined. |
## atan(Decimal)
Gera a tangente inversa de um número em radianos. Argumentos `Decimal` são arredondados para dobrar a precisão antes da aplicação da função. Compatível com a versão de 08/10/2015 do SQL e posteriores.
Exemplo: `atan(0)` = 0,0
****
| Tipo de argumento | Resultado |
| --- | --- |
| Int | Decimal (com precisão dupla), a tangente inversa do argumento. Os resultados imaginários são gerados como Undefined. |
| Decimal | Decimal (com precisão dupla), a tangente inversa do argumento. Os resultados imaginários são gerados como Undefined. |
| Boolean | Undefined. |
| String | Decimal, a tangente inversa do argumento. Se a string não puder ser convertida, o resultado será Undefined. Os resultados imaginários são gerados como Undefined. |
| Array | Undefined. |
| Objeto | Undefined. |
| Null | Undefined. |
| Não definido | Undefined. |
## atan2(Decimal, Decimal)
Gera o ângulo, em radianos, entre o eixo X positivo e o ponto (x, y) definido nos dois argumentos. O ângulo é positivo para os ângulos em sentido anti-horário (metade superior, y > 0) e negativo para os ângulos em sentido horário (metade inferior, y < 0). Argumentos `Decimal` são arredondados para dobrar a precisão antes da aplicação da função. Compatível com a versão de 08/10/2015 do SQL e posteriores.
Exemplo: `atan2(1, 0)` = 1,5707963267948966
****
| Tipo de argumento | Tipo de argumento | Resultado |
| --- | --- | --- |
| Int/Decimal | Int/Decimal | Decimal (com precisão dupla), o ângulo entre o eixo x e o ponto (x, y) especificado. |
| Int/Decimal/String | Int/Decimal/String | Decimal, a tangente inversa do ponto descrito. Se uma string não puder ser convertida, o resultado será Undefined. |
| Outros valores | Outros valores | Undefined. |
## aws\$1lambda(functionArn, inputJson)
Chama a função do Lambda especificada passando `inputJson` para a função do Lambda e retorna o JSON gerado pela função do Lambda.
**Argumentos**
| Argumento | Description |
| --- | --- |
| functionArn | O ARN da função do Lambda a ser chamada. A função do Lambda deve retornar dados JSON. |
| inputJson | A entrada JSON passada para a função do Lambda. Para passar consultas e literais de objetos aninhados, você deve usar o SQL versão 23/03/2016. |
Você deve conceder AWS IoT `lambda:InvokeFunction` permissões para invocar a função Lambda especificada. O seguinte exemplo mostra como conceder a permissão `lambda:InvokeFunction` usando a AWS CLI:
```
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"
```
Veja os argumentos do comando **add-permission**:
--nome da função
Nome da função do Lambda. Você adiciona uma nova permissão para atualizar a política de recursos da função.
--region
O Região da AWS da sua conta.
--entidade principal
O principal que está recebendo a permissão. Isso deve permitir `iot.amazonaws.com` a AWS IoT permissão para chamar uma função Lambda.
--arn de origem
O ARN da regra. Você pode usar o **get-topic-rule** AWS CLI comando para obter o ARN de uma regra.
--conta de origem
O Conta da AWS local em que a regra é definida.
--id da declaração
Um identificador de declaração exclusivo.
--action
A ação do Lambda que você deseja permitir nesta declaração. Para permitir que o AWS IoT invoque uma função do Lambda, especifique `lambda:InvokeFunction`.
**Importante**
Se você adicionar uma permissão para um AWS IoT principal sem fornecer o `source-arn` ou`source-account`, qualquer uma Conta da AWS que crie uma regra com sua ação do Lambda poderá acionar regras para invocar sua função do Lambda. AWS IoT Para obter mais informações, consulte [Modelo de permissões do Lambda](https://docs.aws.amazon.com/lambda/latest/dg/intro-permission-model.html).
Dada uma carga da mensagem JSON como:
```
{
"attribute1": 21,
"attribute2": "value"
}
```
A função do `aws_lambda` pode ser usada para chamar a função do Lambda da seguinte forma.
```
SELECT
aws_lambda("arn:aws:lambda:us-east-1:account_id:function:lambda_function", {"payload":attribute1}) as output FROM 'topic-filter'
```
Se você deseja passar a carga da mensagem MQTT completa, especifique a carga JSON usando "\$1", como no exemplo a seguir.
```
SELECT
aws_lambda("arn:aws:lambda:us-east-1:account_id:function:lambda_function", *) as output FROM 'topic-filter'
```
`payload.inner.element` seleciona dados de mensagem publicada no tópico 'tópico/subtópico'.
`some.value` seleciona dados da saída gerada pela função do Lambda.
**nota**
O mecanismo de regras limita a duração da execução das funções do Lambda. As chamadas de função do Lambda em regras devem ser concluídas em 2.000 milissegundos.
## bitand(Int, Int)
Realiza um bitwise AND nas representações do bit dos dois argumentos `Int`(-convertido). Compatível com a versão de 08/10/2015 do SQL e posteriores.
Exemplo: `bitand(13, 5)` = 5
****
| Tipo de argumento | Tipo de argumento | Resultado |
| --- | --- | --- |
| Int | Int | Int, um bitwise AND dos dois argumentos. |
| Int/Decimal | Int/Decimal | Int, um bitwise AND dos dois argumentos. Todos os números não Int são arredondados para o Int mais próximo. Se qualquer um dos argumentos não puder ser convertido em um Int, o resultado será Undefined. |
| Int/Decimal/String | Int/Decimal/String | Int, um bitwise AND dos dois argumentos. Todas as strings são convertidas em decimais e são arredondadas para o Int mais próximo. Se não for possível converter, o resultado será Undefined. |
| Outros valores | Outros valores | Undefined. |
## bitor(Int, Int)
Executa um bitwise OU das representações de bit dos dois argumentos. Compatível com a versão de 08/10/2015 do SQL e posteriores.
Exemplo: `bitor(8, 5)` = 13
****
| Tipo de argumento | Tipo de argumento | Resultado |
| --- | --- | --- |
| Int | Int | Int, o bitwise OU dos dois argumentos. |
| Int/Decimal | Int/Decimal | Int, o bitwise OU dos dois argumentos. Todos os números não Int são arredondados para o Int mais próximo. Se não for possível converter, o resultado será Undefined. |
| Int/Decimal/String | Int/Decimal/String | Int, o bitwise OU nos dois argumentos. Todas as strings são convertidas em decimais e são arredondadas para o Int mais próximo. Se não for possível converter, o resultado será Undefined. |
| Outros valores | Outros valores | Undefined. |
## bitxor(Int, Int)
Realiza um bitwise XOR nas representações do bit dos dois argumentos `Int`(-convertido). Compatível com a versão de 08/10/2015 do SQL e posteriores.
Exemplo:`bitor(13, 5)` = 8
****
| Tipo de argumento | Tipo de argumento | Resultado |
| --- | --- | --- |
| Int | Int | Int, um bitwise XOR nos dois argumentos. |
| Int/Decimal | Int/Decimal | Int, um bitwise XOR nos dois argumentos. Os números não Int são arredondados para o Int mais próximo. |
| Int/Decimal/String | Int/Decimal/String | Int, um bitwise XOR nos dois argumentos. As strings são convertidas em decimais e são arredondadas para o Int mais próximo. Se não for possível converter, o resultado será Undefined. |
| Outros valores | Outros valores | Undefined. |
## bitnot(Int)
Realiza um bitwise NOT nas representações do bit do argumento `Int`(-convertido). Compatível com a versão de 08/10/2015 do SQL e posteriores.
Exemplo: `bitnot(13)` = 2
****
| Tipo de argumento | Resultado |
| --- | --- |
| Int | Int, um bitwise NOT do argumento. |
| Decimal | Int, um bitwise NOT do argumento. O valor Decimal é arredondado para o Int abaixo mais próximo. |
| String | Int, um bitwise NOT do argumento. As strings são convertidas em decimais e são arredondadas para o Int mais próximo. Se não for possível converter, o resultado será Undefined. |
| Outros valores | Outros valores. |
## cast()
Converte um valor de um tipo de dados para outro. O cast é muito parecido com as conversões padrão, com a adição da capacidade de converter números em ou de boolianos. Se AWS IoT não conseguir determinar como converter um tipo em outro, o resultado é`Undefined`. Compatível com a versão de 08/10/2015 do SQL e posteriores. Formato: cast (*value*as*type*).
Exemplo:
`cast(true as Int) ` = 1
As seguintes palavras-chave podem aparecer após "as" ao chamar `cast`:
**Para as versões do SQL de 08/10/2015 e 23/03/2016**
| Palavra-chave | Resultado |
| --- | --- |
| String | Aplica valor para String. |
| Nvarchar | Aplica valor para String. |
| Texto | Aplica valor para String. |
| Ntext | Aplica valor para String. |
| varchar | Aplica valor para String. |
| Int | Aplica valor para Int. |
| Inteiro | Aplica valor para Int. |
| Duplo | Converte o valor para Decimal (com precisão dupla). |
**Além disso, para as versões do SQL de 23/03/2016**
| Palavra-chave | Resultado |
| --- | --- |
| Decimal | Aplica valor para Decimal. |
| Bool | Aplica valor para Boolean. |
| Boolean | Aplica valor para Boolean. |
Regras de cast:
**Cast para decimal**
| Tipo de argumento | Resultado |
| --- | --- |
| Int | Um Decimal sem ponto decimal. |
| Decimal | O valor de origem. Com o SQL V2 (23/03/2016), valores numéricos que são números inteiros, como `10.0`, retornam um valor `Int` (`10`) em vez do valor `Decimal` esperado (`10.0`). Para converter de forma confiável valores numéricos inteiros como valores `Decimal`, use o SQL V1 (08/10/2015) para a instrução de consulta de regra. |
| Boolean | verdadeiro = 1,0, falso = 0,0. |
| String | Tenta analisar a string como um Decimal. A AWS IoT tenta analisar as strings correspondendo à regex: ^-?\$1d\$1(\$1.\$1d\$1)?((?i)E-?\$1d\$1)?\$1. "0", "-1,2" e "5E-12" são exemplos de strings que são automaticamente convertidas em decimais. |
| Array | Undefined. |
| Objeto | Undefined. |
| Null | Undefined. |
| Não definido | Undefined. |
**Cast para int**
| Tipo de argumento | Resultado |
| --- | --- |
| Int | O valor de origem. |
| Decimal | O valor de origem arredondado para o Int abaixo mais próximo. |
| Boolean | verdadeiro = 1,0, falso = 0,0. |
| String | Tenta analisar a string como um Decimal. A AWS IoT tenta analisar as strings correspondendo à regex: ^-?\$1d\$1(\$1.\$1d\$1)?((?i)E-?\$1d\$1)?\$1. "0", "-1,2", "5E-12" são exemplos de strings que são automaticamente convertidas em decimais. A AWS IoT tenta converter a string em Decimal e arredondar para o Int mais próximo. |
| Array | Undefined. |
| Objeto | Undefined. |
| Null | Undefined. |
| Não definido | Undefined. |
**Aplicar para `Boolean`**
| Tipo de argumento | Resultado |
| --- | --- |
| Int | 0 = Falso, qualquer\$1valor\$1não\$1zero = Verdadeiro. |
| Decimal | 0 = Falso, qualquer\$1valor\$1não\$1zero = Verdadeiro. |
| Boolean | O valor de origem. |
| String | "true" = Verdadeiro e "false" = Falso (não diferencia maiúsculas de minúsculas). Outros valores de string = Undefined. |
| Array | Undefined. |
| Objeto | Undefined. |
| Null | Undefined. |
| Não definido | Undefined. |
**Cast para string**
| Tipo de argumento | Resultado |
| --- | --- |
| Int | Uma representação de string do Int em notação padrão. |
| Decimal | Uma string representando o valor Decimal, possivelmente em notação científica. |
| Boolean | "verdadeiro" ou "falso", todas as letras minúsculas. |
| String | O valor de origem. |
| Array | A matriz serializada para JSON. A string resultante é uma lista separada por vírgulas, entre colchetes. String tem aspas. Decimals, Ints e Booleans não. |
| Objeto | O objeto serializado para JSON. A string JSON é uma lista separada por vírgulas de pares de chave/valor e começa e termina com chaves. String tem aspas. Decimals, Ints, Booleans e Null não. |
| Null | Undefined. |
| Não definido | Undefined. |
## ceil(Decimal)
Arredonda o `Decimal` fornecido para o `Int` acima mais próximo. Compatível com a versão de 08/10/2015 do SQL e posteriores.
Exemplos:
`ceil(1.2)` = 2
`ceil(-1.2)` = -1
****
| Tipo de argumento | Resultado |
| --- | --- |
| Int | Int, o valor do argumento. |
| Decimal | Int, o valor Decimal arredondado para o Int acima mais próximo. |
| String | Int. A string será convertida em Decimal e arredondada para o Int acima mais próximo. Se a string não puder ser convertida em um Decimal, o resultado será Undefined. |
| Outros valores | Undefined. |
## chr(String)
Gera o caractere ASCII que corresponde ao dado argumento `Int`. Compatível com a versão de 08/10/2015 do SQL e posteriores.
Exemplos:
`chr(65)` = "A".
`chr(49)` = "1".
****
| Tipo de argumento | Resultado |
| --- | --- |
| Int | O caractere correspondente ao valor ASCII especificado. Se o argumento não for um valor ASCII válido, o resultado será Undefined. |
| Decimal | O caractere correspondente ao valor ASCII especificado. O argumento Decimal é arredondado para o Int abaixo mais próximo. Se o argumento não for um valor ASCII válido, o resultado será Undefined. |
| Boolean | Undefined. |
| String | Se a String puder ser convertida em Decimal, ela será arredondada para o Int mais próximo. Se o argumento não for um valor ASCII válido, o resultado será Undefined. |
| Array | Undefined. |
| Objeto | Undefined. |
| Null | Undefined. |
| Outros valores | Undefined. |
## clientid()
Gera o ID do MQTT cliente que envia a mensagem ou `n/a` se a mensagem não foi enviada por MQTT. Compatível com a versão de 08/10/2015 do SQL e posteriores.
Exemplo:
`clientid() ` = "123456789012"
## concat()
Concatena as matrizes ou strings. Essa função aceita qualquer número de argumentos e gera uma `String` ou uma `Array`. Compatível com a versão de 08/10/2015 do SQL e posteriores.
Exemplos:
`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]
****
| Número de argumentos | Resultado |
| --- | --- |
| 0 | Undefined. |
| 1 | O argumento é gerado sem modificações. |
| 2\$1 | Se algum argumento for uma `Array`, o resultado será uma única matriz que contém todos os argumentos. Se não houver matrizes e pelo menos um argumento for uma `String`, o resultado será a concatenação das representações de `String` de todos os argumentos. Os argumentos são convertidos em strings usando as conversões padrão listadas anteriormente. |
## cos(Decimal)
Gera o cosseno de um número em radianos. Argumentos `Decimal` são arredondados para dobrar a precisão antes da aplicação da função. Compatível com a versão de 08/10/2015 do SQL e posteriores.
Exemplo:
`cos(0)` = 1.
****
| Tipo de argumento | Resultado |
| --- | --- |
| Int | Decimal (com precisão dupla), o cosseno do argumento. Os resultados imaginários são gerados como Undefined. |
| Decimal | Decimal (com precisão dupla), o cosseno do argumento. Os resultados imaginários são gerados como Undefined. |
| Boolean | Undefined. |
| String | Decimal (com precisão dupla), o cosseno do argumento. Se a string não puder ser convertida em um Decimal, o resultado será Undefined. Os resultados imaginários são gerados como Undefined. |
| Array | Undefined. |
| Objeto | Undefined. |
| Null | Undefined. |
| Não definido | Undefined. |
## cosh(Decimal)
Gera o cosseno hiperbólico de um número em radianos. Argumentos `Decimal` são arredondados para dobrar a precisão antes da aplicação da função. Compatível com a versão de 08/10/2015 do SQL e posteriores.
Exemplo: `cosh(2.3)` = 5,037220649268761.
****
| Tipo de argumento | Resultado |
| --- | --- |
| Int | Decimal (com precisão dupla), o cosseno hiperbólico do argumento. Os resultados imaginários são gerados como Undefined. |
| Decimal | Decimal (com precisão dupla), o cosseno hiperbólico do argumento. Os resultados imaginários são gerados como Undefined. |
| Boolean | Undefined. |
| String | Decimal (com precisão dupla), o cosseno hiperbólico do argumento. Se a string não puder ser convertida em um Decimal, o resultado será Undefined. Os resultados imaginários são gerados como Undefined. |
| Array | Undefined. |
| Objeto | Undefined. |
| Null | Undefined. |
| Não definido | Undefined. |
## decodificar (valor, esquema de decodificação)
Use a função `decode` para decodificar um valor codificado. Se a string decodificada for um documento JSON, um objeto endereçável será retornado. Caso contrário, a string decodificada será retornada como uma string. A função retornará NULL se a string não puder ser decodificada. Essa função é compatível com a decodificação de strings codificadas em base64 e o formato de mensagem Protocol Buffer (protobuf).
Compatível com a versão de 23/03/2016 do SQL e posteriores.
valor
Um valor de string ou qualquer uma das expressões válidas, conforme definido em [AWS IoT Referência SQL](iot-sql-reference.md), que retornam uma string.
decodingScheme
Uma string literal representando o esquema usado para decodificar o valor. Atualmente, apenas há suporte para `'base64'` e `'proto'`.
### Decodificação de strings codificadas em base64
Neste exemplo, a carga útil da mensagem inclui um valor codificado.
```
{
encoded_temp: "eyAidGVtcGVyYXR1cmUiOiAzMyB9Cg=="
}
```
A função `decode` nessa instrução SQL decodifica o valor na carga útil da mensagem.
```
SELECT decode(encoded_temp,"base64").temperature AS temp from 'topic/subtopic'
```
A decodificação do valor `encoded_temp` resulta no seguinte documento JSON válido, que permite que a instrução SELECT leia o valor da temperatura.
```
{ "temperature": 33 }
```
O resultado da instrução SELECT neste exemplo é mostrado aqui.
```
{ "temp": 33 }
```
Se o valor decodificado não fosse um documento JSON válido, o valor decodificado seria retornado como uma string.
### Decodificação da carga útil da mensagem protobuf
Você pode usar a função decodificar SQL para configurar uma regra que pode decodificar a carga útil da mensagem protobuf. Para obter mais informações, consulte [Decodificação de cargas úteis de mensagens protobuf](binary-payloads.md#binary-payloads-protobuf).
**Importante**
Se você omitir `source‐arn` ou `source‐account` ao definir permissões para um AWS IoT principal, qualquer um Conta da AWS poderá invocar sua função de decodificação por meio de outras regras. AWS IoT Para proteger sua função, consulte [Políticas de bucket](https://docs.aws.amazon.com/AmazonS3/latest/userguide/bucket-policies.html) no *Guia do usuário do Amazon Simple Storage Service*.
A assinatura da função tem a seguinte aparência:
```
decode(, 'proto', '', '', '', '')
```
`ENCODED DATA`
Especifica os dados codificados por protobuf a serem decodificados. Se toda a mensagem enviada para a regra for de dados codificados por protobuf, você poderá referenciar a carga útil de entrada binária bruta usando `*`. Caso contrário, esse campo deve ser uma string JSON codificada em base 64 e uma referência à string pode ser passada diretamente.
1) Para decodificar uma carga útil bruta de entrada de protobuf binário:
```
decode(*, 'proto', ...)
```
2) Para decodificar uma mensagem codificada por protobuf representada por uma string codificada em base64 'a.b':
```
decode(a.b, 'proto', ...)
```
`proto`
Especifica os dados a serem decodificados em um formato de mensagem protobuf. Se você especificar `base64` em vez de `proto`, essa função decodificará strings codificadas em base64 como JSON.
`S3 BUCKET NAME`
O nome do bucket do Amazon S3 onde você fez upload do arquivo `FileDescriptorSet`.
`S3 OBJECT KEY`
A chave de objeto que especifica o arquivo `FileDescriptorSet` dentro do bucket do Amazon S3.
`PROTO NAME`
O nome do arquivo `.proto` (excluindo a extensão) do qual o arquivo `FileDescriptorSet` foi gerado.
`MESSAGE TYPE`
O nome da estrutura da mensagem protobuf dentro do arquivo `FileDescriptorSet`, com a qual os dados a serem decodificados devem estar em conformidade.
Um exemplo de expressão SQL usando a função decodificar SQL pode ter a seguinte aparência:
```
SELECT VALUE decode(*, 'proto', 's3-bucket', 'messageformat.desc', 'myproto', 'messagetype') FROM 'some/topic'
```
+ `*`
Representa uma carga de entrada binária, que está em conformidade com o tipo de mensagem protobuf chamado `mymessagetype`.
+ `messageformat.desc`
O arquivo `FileDescriptorSet` armazenado em um bucket do Amazon S3 chamado `s3-bucket`.
+ `myproto`
O arquivo `.proto` original usado para gerar o arquivo `FileDescriptorSet` chamado `myproto.proto`.
+ `messagetype`
O tipo de mensagem chamado `messagetype` (junto com todas as dependências importadas) conforme definido em `myproto.proto`.
## encode(value, encodingScheme)
Use a função `encode` para codificar a carga útil, que provavelmente serão dados não JSON, em sua representação de string com base no esquema de codificação. Compatível com a versão de 23/03/2016 do SQL e posteriores.
valor
Qualquer uma das expressões válidas, conforme definido em [AWS IoT Referência SQL](iot-sql-reference.md). Você pode especificar \$1 para codificar toda a carga útil, independentemente de estar no formato JSON. Se você fornecer uma expressão, o resultado da avaliação será convertido em uma string antes de ser codificado.
encodingScheme
Uma string literal que representa o esquema de codificação que você deseja usar. No momento, só há compatibilidade com `'base64'`.
## endswith(String, String)
Gera um `Boolean` indicando se o primeiro argumento de `String` termina com o segundo argumento de `String`. Se um dos argumentos for `Null` ou `Undefined`, o resultado será `Undefined`. Compatível com a versão de 08/10/2015 do SQL e posteriores.
Exemplo: `endswith("cat","at")` = verdadeiro.
****
| Tipo de argumento 1 | Tipo de argumento 2 | Resultado |
| --- | --- | --- |
| String | String | Verdadeiro se o primeiro argumento terminar no segundo argumento. Caso contrário, falso. |
| Outros valores | Outros valores | Os dois argumentos são convertidos em strings usando as regras padrão de conversão. Verdadeiro se o primeiro argumento terminar no segundo argumento. Caso contrário, falso. Se um dos argumentos for Null ou Undefined, o resultado será Undefined. |
## exp(Decimal)
Gera e elevado ao argumento `Decimal`. Argumentos `Decimal` são arredondados para dobrar a precisão antes da aplicação da função. Compatível com a versão de 08/10/2015 do SQL e posteriores.
Exemplo: `exp(1)` = e.
****
| Tipo de argumento | Resultado |
| --- | --- |
| Int | Decimal (com precisão dupla), argumento e ^. |
| Decimal | Decimal (com precisão dupla), argumento e ^. |
| String | Decimal (com precisão dupla), argumento e ^. Se a String não puder ser convertida em um Decimal, o resultado será Undefined. |
| Outros valores | Undefined. |
## floor(Decimal)
Arredonda o `Decimal` fornecido para o `Int` abaixo mais próximo. Compatível com a versão de 08/10/2015 do SQL e posteriores.
Exemplos:
`floor(1.2)` = 1
`floor(-1.2)` = -2
****
| Tipo de argumento | Resultado |
| --- | --- |
| Int | Int, o valor do argumento. |
| Decimal | Int, o valor Decimal é arredondado para o Int abaixo mais próximo. |
| String | Int. A string será convertida em Decimal e arredondada para o Int abaixo mais próximo. Se a string não puder ser convertida em um Decimal, o resultado será Undefined. |
| Outros valores | Undefined. |
## obter
Extrai um valor de um tipo de coleção (Matriz, String, Objeto). Nenhuma conversão é aplicada ao primeiro argumento. A conversão se aplica como documentado na tabela ao segundo argumento. Compatível com a versão de 08/10/2015 do SQL e posteriores.
Exemplos:
`get(["a", "b", "c"], 1) ` = "b"
`get({"a":"b"}, "a")` = "b"
`get("abc", 0)` = "a"
****
| Tipo de argumento 1 | Tipo de argumento 2 | Resultado |
| --- | --- | --- |
| Array | Qualquer tipo (convertido em Int) | O item no índice com base 0 da Array fornecido pelo segundo argumento (convertido em Int). Se não for possível converter, o resultado será Undefined. Se o índice estiver fora dos limites da Array (negativo ou >= matriz.comprimento), o resultado será Undefined. |
| String | Qualquer tipo (convertido em Int) | O caractere no índice com base 0 da string fornecido pelo segundo argumento (convertido em Int). Se não for possível converter, o resultado será Undefined. Se o índice estiver fora dos limites da string (negativo ou >= string.comprimento), o resultado será Undefined. |
| Objeto | String (nenhuma conversão é aplicada) | O valor armazenado no primeiro objeto de argumento correspondente à chave de string fornecida como o segundo argumento. |
| Outros valores | Qualquer valor | Undefined. |
## get\$1dynamodb (nome da tabela,,,,, RoLearn partitionKeyName) partitionKeyValue sortKeyName sortKeyValue
Recupera dados de uma tabela do DynamoDB. `get_dynamodb()` permite consultar uma tabela do DynamoDB enquanto uma regra é avaliada. É possível filtrar ou aumentar cargas de mensagens usando dados recuperados do DynamoDB. Compatível com a versão de 23/03/2016 do SQL e posteriores.
`get_dynamodb()` utiliza os seguintes parâmetros:
tableName
O nome da tabela do DynamoDB a ser consultada.
partitionKeyName
O nome da chave da partição. Para obter mais informações, consulte [Chaves do DynamoDB](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/HowItWorks.CoreComponents.html#HowItWorks.CoreComponents.PrimaryKey).
partitionKeyValue
O valor da chave de partição usada para identificar um registro. Para obter mais informações, consulte [Chaves do DynamoDB](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/HowItWorks.CoreComponents.html#HowItWorks.CoreComponents.PrimaryKey).
sortKeyName
(Opcional) O nome da chave de classificação. Esse parâmetro será necessário somente se a tabela do DynamoDB consultada usar uma chave composta. Para obter mais informações, consulte [Chaves do DynamoDB](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/HowItWorks.CoreComponents.html#HowItWorks.CoreComponents.PrimaryKey).
sortKeyValue
(Opcional) O valor da chave de classificação. Esse parâmetro será necessário somente se a tabela do DynamoDB consultada usar uma chave composta. Para obter mais informações, consulte [Chaves do DynamoDB](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/HowItWorks.CoreComponents.html#HowItWorks.CoreComponents.PrimaryKey).
roleArn
O ARN do perfil do IAM que concede acesso à tabela do DynamoDB. O mecanismo de regras assume essa função para acessar a tabela do DynamoDB em seu nome. Evite usar uma função excessivamente permissiva. Conceda à função apenas as permissões necessárias para a regra. O exemplo de política a seguir concede acesso a uma tabela do DynamoDB.
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "dynamodb:GetItem",
"Resource": "arn:aws:dynamodb:us-east-1:123456789012:table/table-name"
}
]
}
```
Como um exemplo de como é possível usar `get_dynamodb()`, digamos que você tenha uma tabela do DynamoDB que contém o ID do dispositivo e as informações de localização para todos os dispositivos conectados ao AWS IoT. A instrução SELECT a seguir usa a função `get_dynamodb()` para recuperar o local para o ID do dispositivo especificado:
`SELECT *, get_dynamodb("InServiceDevices", "deviceId", id, "arn:aws:iam::12345678910:role/getdynamo").location AS location FROM 'some/topic' `
**nota**
É possível chamar `get_dynamodb()` no máximo uma vez por instrução SQL. Chamar `get_dynamodb()` várias vezes em uma única instrução SQL faz com que a regra seja encerrada sem chamar nenhuma ação.
## get\$1mqtt\$1property (nome)
Faz referência a qualquer um dos seguintes MQTT5 cabeçalhos: `contentType``payLoadFormatIndicator`,`responseTopic`, e. `correlationData` Essa função usa qualquer uma das seguintes strings literais como argumento: `content_type`, `format_indicator`, `response_topic` e `correlation_data`. Para obter mais informações, consulte a tabela de **Argumentos de função** a seguir.
contentType
String: Uma string codificada em UTF-8 que descreve o conteúdo da mensagem de publicação.
payLoadFormatIndicador
String: Um valor de string Enum que indica se a carga útil está formatada como UTF-8. Os valores válidos são `UNSPECIFIED_BYTES` e `UTF8_DATA`.
responseTopic
String: Uma string codificada em UTF-8 que é usada como nome de tópico para uma mensagem de resposta. O tópico da resposta é usado para descrever o tópico que o destinatário deve publicar como parte do fluxo solicitação-resposta. O tópico não deve conter caracteres curinga.
correlationData
String: Os dados binários codificados em base64 usados pelo remetente da mensagem de solicitação para identificar para qual solicitação é a mensagem de resposta.
A tabela a seguir mostra os argumentos de função aceitáveis e os tipos de retorno associados para a `get_mqtt_property` função:
**Argumentos de função**
| SQL | Tipo de dados retornado (se presente) | Tipo de dados retornado (se não presente) |
| --- | --- | --- |
| get\$1mqtt\$1property("format\$1indicator") | Cadeia de caracteres (UNSPECIFIED\$1BYTES ou \$1DATA) UTF8 | String (UNSPECIFIED\$1BYTES) |
| get\$1mqtt\$1property("content\$1type") | String | Não definido |
| get\$1mqtt\$1property("response\$1topic") | String | Não definido |
| get\$1mqtt\$1property("correlation\$1data") | String codificada em base64 | Não definido |
| get\$1mqtt\$1property("some\$1invalid\$1name") | Não definido | Não definido |
O exemplo a seguir Rules SQL faz referência a qualquer um dos seguintes MQTT5 cabeçalhos: `contentType``payLoadFormatIndicator`,`responseTopic`, e. `correlationData`
```
SELECT *, get_mqtt_property('content_type') as contentType,
get_mqtt_property('format_indicator') as payloadFormatIndicator,
get_mqtt_property('response_topic') as responseTopic,
get_mqtt_property('correlation_data') as correlationData
FROM 'some/topic'
```
## get\$1or\$1default (expressão, DefaultValue)
Retorna o valor padrão no segundo parâmetro, se especificado, ou então retorna indefinido, quando a expressão no primeiro parâmetro retorna nula, indefinida ou falha. Compatível com a versão de 23/03/2016 do SQL e posteriores.
**Importante**
`get_or_default`não oferece suporte a cargas não JSON diretamente como estão. Se você estiver usando uma carga não JSON, use as `encode` funções ou. `decode`
`get_or_default()` utiliza os seguintes parâmetros:
expressão
Qualquer expressão válida contendo[Tipos de dados](iot-sql-data-types.md), [Funções](#iot-sql-functions)[Literais](iot-sql-literals.md),[Consultas de objeto aninhado](iot-sql-nested-queries.md), [Variáveis](iot-sql-set.md#iot-sql-set-usage) ou[Extensões JSON](iot-sql-json.md).
defaultValue
(Opcional) Qualquer expressão válida contendo [Tipos de dados](iot-sql-data-types.md)[Funções](#iot-sql-functions),[Literais](iot-sql-literals.md),[Consultas de objeto aninhado](iot-sql-nested-queries.md), [Variáveis](iot-sql-set.md#iot-sql-set-usage) ou[Extensões JSON](iot-sql-json.md). Esse é o valor a ser retornado sempre que o primeiro argumento retornar nulo, indefinido ou falhar.
Funções que buscam dados de recursos de propriedade do cliente, como get\$1secret, get\$1dynamodb, aws\$1lambda, get\$1thing\$1shadow, decode-protobuf e machinelearning\$1predict, não são permitidas no parâmetro DefaultValue.
A tabela a seguir mostra argumentos de função aceitáveis para cada argumento e suas saídas associadas:
| Primeiro argumento | Segundo argumento | Output |
| --- | --- | --- |
| Avaliação bem-sucedida | Qualquer valor ou não especificado | O valor do primeiro argumento. |
| Indefinido, nulo ou falha | Qualquer valor, incluindo indefinido ou nulo | O valor do segundo argumento. |
| Indefinido, nulo ou falha | não especificado | Undefined |
**Exemplos:**
Exemplo 1:
O exemplo a seguir fornece um valor DefaultValue se uma tabela ou consulta do DynamoDB falhar:
```
SELECT
device_id,
get_or_default(
get_dynamodb("DeviceConfig", "deviceId", nonExistentId, "arn:aws:iam::123456789012:role/ROLE_NAME"),
{"mode": "standard", "timeout": 30, "enabled": true }
) as config
FROM 'device/telemetry'
```
Exemplo 2:
O exemplo a seguir fornece um valor padrão seguro “DESCONHECIDO” se o status for indefinido:
```
SELECT
get_or_default( CASE status
WHEN 'active' THEN 'GOOD'
WHEN 'inactive' THEN 'BAD'/
ELSE 'UNKNOWN'
END, 'UNKNOWN') as status_category
FROM 'topic/subtopic'
```
Exemplo 3:
O exemplo a seguir mostra como você também pode usar get\$1or\$1default com um único parâmetro. Isso é útil em cenários em que você pode não ter um valor padrão claro, mas não deseja que a execução da regra falhe.
```
SELECT
get_dynamodb("DeviceConfig", "deviceId", nonExistentId, "arn:aws:iam::123456789012:role/ROLE_NAME") as config
FROM 'device/telemetry'
```
Se a pesquisa do DynamoDB falhar, a execução da regra falhará e nenhuma ação será executada. Se o seguinte SQL for usado em vez disso:
```
SELECT
get_or_default(get_dynamodb("DeviceConfig", "deviceId", nonExistentId, "arn:aws:iam::123456789012:role/ROLE_NAME")) as config
FROM 'device/telemetry'
```
A instrução get\$1or\$1default será avaliada como`Undefined`, portanto, neste exemplo, a instrução SELECT em geral será avaliada `{}` e qualquer ação de regra será tentada.
**Importante**
Recomendamos seguir estas melhores práticas para manter a segurança ao usar essa função:
Evite usar segredos codificados em definições de regras, incluindo valores padrão
Use AWS Secrets Manager para gerenciar informações confidenciais
## get\$1registry\$1data (RegistryAPI, ThingName, RoLearn)
Recupera dados de registro de AWS IoT coisas em uma AWS IoT regra. Você pode ler dados do registro (como atributos, tipo de coisa e grupos de coisas aos quais um dispositivo pertence) e usar essas informações para filtrar, enriquecer ou rotear mensagens dinamicamente. Compatível com a versão de 23/03/2016 do SQL e posteriores.
`get_registry_data()` utiliza os seguintes parâmetros:
API de registro
A API de registro que está sendo chamada. Os valores válidos são `DescribeThing` e `ListThingGroupsForThing`. Esses valores devem ser cadeias de caracteres constantes.
thingName
Cadeia de caracteres: o nome da coisa cujos dados de registro você deseja recuperar.
roleArn
String: um ARN de função com permissão de `iot:DescribeThing` and/or `iot:ListThingGroupsForThing` permissão com base na API que está sendo chamada.
O formato de resposta da `get_registry_data` função é o mesmo da API de registro chamada. Para obter mais informações, consulte [DescribeThing](https://docs.aws.amazon.com//iot/latest/apireference/API_DescribeThing.html) e [ListThingGroupsForThing](https://docs.aws.amazon.com//iot/latest/apireference/API_ListThingGroupsForThing.html) APIs.
Exemplo:
Você pode recuperar informações do tipo de coisa para permitir a filtragem das mensagens de eventos do AWS IoT Core ciclo de vida das coisas (com o nome da coisa correspondendo ao ID do cliente MQTT) onde está o tipo da coisa. `testenv`
```
SELECT *
FROM '$aws/events/lifecycle/+'
WHERE
get_registry_data("DescribeThing",clientId,[roleArn]).thingTypeName='testenv'
```
Exemplo:
Você pode recuperar atributos de um dispositivo com nome de coisa `sensor1` para todas as mensagens enviadas por seu dispositivo `gateway1` de gateway.
```
SELECT *, get_registry_data("DescribeThing","sensor1",[roleArn]).attributes.temperature_threhold AS device1_tempthreshold
FROM home1/gateway1/sensor1/#
```
**nota**
Você pode chamar no máximo `get_registry_data()` uma vez por instrução SQL e modelos de substituição para ações e ações de erro.
## get\$1secret (secretId, secretType, chave, roleArn)
Recupera o valor do campo criptografado `SecretString` ou `SecretBinary` da versão atual de um segredo em [AWS Secrets Manager](https://docs.aws.amazon.com/secretsmanager/latest/userguide/). Para obter mais informações sobre como criar e manter segredos [CreateSecret[UpdateSecret](https://docs.aws.amazon.com/secretsmanager/latest/apireference/API_UpdateSecret.html)](https://docs.aws.amazon.com/secretsmanager/latest/apireference/API_CreateSecret.html), consulte, [PutSecretValue](https://docs.aws.amazon.com/secretsmanager/latest/apireference/API_PutSecretValue.html)e.
`get_secret()` utiliza os seguintes parâmetros:
secretId
String: O nome do recurso da Amazon (ARN) ou o nome amigável do segredo a ser recuperado.
secretType
String: O tipo de segredo. Valores válidos: `SecretString` \$1 `SecretBinary`.
SecretString
+ Para segredos que você cria como objetos JSON usando o APIs AWS CLI, o ou o AWS Secrets Manager console:
+ Se você especificar um valor para o parâmetro `key`, essa função retornará o valor da chave especificada.
+ Se você não especificar um valor para o parâmetro `key`, essa função retornará o objeto JSON inteiro.
+ Para segredos que você cria como objetos não JSON usando o APIs ou o: AWS CLI
+ Se você especificar um valor para o parâmetro `key`, essa função falhará com uma exceção.
+ Se você não especificar um valor para o parâmetro `key`, essa função retornará o conteúdo do segredo.
SecretBinary
+ Se você especificar um valor para o parâmetro `key`, essa função falhará com uma exceção.
+ Se você não especificar um valor para o parâmetro `key`, essa função retornará o valor secreto como uma string UTF-8 codificada em base64.
key
(Opcional) String: o nome da chave dentro de um objeto JSON armazenado no campo `SecretString` de um segredo. Use esse valor quando quiser recuperar somente o valor de uma chave armazenada em um segredo em vez do objeto JSON inteiro.
Se você especificar um valor para esse parâmetro e o segredo não contiver um objeto JSON dentro do campo `SecretString`, essa função falhará com uma exceção.
roleArn
String: um ARN de função com permissões `secretsmanager:GetSecretValue` e `secretsmanager:DescribeSecret`.
**nota**
Essa função sempre retorna a versão atual do segredo (a versão com a tag `AWSCURRENT`). O mecanismo de AWS IoT regras armazena cada segredo em cache por até 15 minutos. Como resultado, o mecanismo de regras pode levar até 15 minutos para atualizar um segredo. Isso significa que, se você recuperar um segredo até 15 minutos após uma atualização com AWS Secrets Manager, essa função poderá retornar a versão anterior.
Essa função não é medida, mas são cobradas AWS Secrets Manager taxas. Por causa do mecanismo secreto de armazenamento em cache, o mecanismo de regras chama AWS Secrets Manager ocasionalmente. Como o mecanismo de regras é um serviço totalmente distribuído, você pode ver várias chamadas de API do Secrets Manager do mecanismo de regras durante a janela de 15 minutos de armazenamento em cache.
Exemplos:
Você pode usar a função `get_secret` em um cabeçalho de autenticação em uma ação de regra HTTPS, como no exemplo de autenticação de chave de API a seguir.
```
"API_KEY": "${get_secret('API_KEY', 'SecretString', 'API_KEY_VALUE', 'arn:aws:iam::12345678910:role/getsecret')}"
```
Para obter mais informações sobre as ações de regra HTTPS, consulte [HTTP](https-rule-action.md).
## get\$1thing\$1shadow (ThingName, ShadoWName, RoLearn)
Retorna a sombra do objeto especificado. Compatível com a versão de 23/03/2016 do SQL e posteriores.
thingName
String: o nome do objeto que você quer recuperar a sombra.
shadowName
(Opcional) String: o nome da sombra. Esse parâmetro é necessário somente ao fazer referência a sombras nomeadas.
roleArn
String: um ARN de função com permissão `iot:GetThingShadow`.
Exemplos:
Quando usado com uma sombra nomeada, forneça o parâmetro `shadowName`.
```
SELECT * from 'topic/subtopic'
WHERE
get_thing_shadow("MyThing","MyThingShadow","arn:aws:iam::123456789012:role/AllowsThingShadowAccess")
.state.reported.alarm = 'ON'
```
Quando usado com uma sombra sem nome, omita o parâmetro `shadowName`.
```
SELECT * from 'topic/subtopic'
WHERE
get_thing_shadow("MyThing","arn:aws:iam::123456789012:role/AllowsThingShadowAccess")
.state.reported.alarm = 'ON'
```
## get\$1user\$1properties () userPropertyKey
Referencia as propriedades do usuário, que é um tipo de cabeçalho de propriedade suportado no MQTT5.
userProperty
String: Uma propriedade de usuário é um par de chave/valor. Essa função usa a chave como argumento e retorna uma matriz de todos os valores que correspondem à chave associada.
**Argumentos de função**
Para as seguintes propriedades do usuário nos cabeçalhos das mensagens:
| Chave | Valor |
| --- | --- |
| alguma chave | algum valor |
| uma chave diferente | um valor diferente |
| alguma chave | valor com chave duplicada |
A tabela a seguir mostra o comportamento esperado do SQL:
| SQL | Tipo de dados de retorno | Valor de dados de retorno |
| --- | --- | --- |
| get\$1user\$1properties('alguma chave') | Matriz de strings | ['some value', 'value with duplicate key'] |
| get\$1user\$1properties('outra chave') | Matriz de strings | ['a different value'] |
| get\$1user\$1properties( ) | Matriz de objetos de chave-valor | [\$1'"some key": "some value"'\$1, \$1"other key": "a different value"\$1, \$1"some key": "value with duplicate key"\$1] |
| get\$1user\$1properties('chave inexistente') | Não definido | |
O exemplo a seguir Rules SQL faz referência às propriedades do usuário (um tipo de cabeçalho de MQTT5 propriedade) na carga útil:
```
SELECT *, get_user_properties('user defined property key') as userProperty
FROM 'some/topic'
```
## Funções de hashing
AWS IoT fornece as seguintes funções de hashing:
+ md2
+ md5
+ sha1
+ sha224
+ sha256
+ sha384
+ sha512
Todas as funções de hash esperam um argumento de string. O resultado é o valor de hash da string em questão. Conversões de string padrão se aplicam a argumentos de não string. Todas as funções de hash são compatíveis com a versão de 08/10/2015 do SQL e posteriores.
Exemplos:
`md2("hello")` = "a9046c73e00331af68917d3804f70655"
`md5("hello")` = "5d41402abc4b2a76b9719d911017c592"
## indexof(String, String)
Apresenta o primeiro índice (base em 0) do segundo argumento como uma substring no primeiro argumento. Os dois argumentos são esperados como strings. Os argumentos que não são strings estão sujeitos às regras padrão de conversão de string. Essa função não se aplica a matrizes, apenas a strings. Compatível com a versão de 23/03/2016 do SQL e posteriores.
Exemplos:
`indexof("abcd", "bc") ` = 1
## isNull()
Retorna verdadeiro se o argumento é o valor `Null`. Compatível com a versão de 23/03/2016 do SQL e posteriores.
Exemplos:
`isNull(5) ` = false.
`isNull(Null) ` = true.
****
| Tipo de argumento | Resultado |
| --- | --- |
| Int | false |
| Decimal | false |
| Boolean | false |
| String | false |
| Array | false |
| Object | false |
| Null | verdadeiro |
| Undefined | false |
## isUndefined()
Retorna verdadeiro se o argumento for `Undefined`. Compatível com a versão de 23/03/2016 do SQL e posteriores.
Exemplos:
`isUndefined(5) ` = false.
`isUndefined(floor([1,2,3]))) ` = true.
****
| Tipo de argumento | Resultado |
| --- | --- |
| Int | false |
| Decimal | false |
| Boolean | false |
| String | false |
| Array | false |
| Object | false |
| Null | false |
| Undefined | verdadeiro |
## length(String)
Gera o número de caracteres na string fornecida. As regras padrão de conversão se aplicam a argumentos de não `String`. Compatível com a versão de 23/03/2016 do SQL e posteriores.
Exemplos:
`length("hi")` = 2
`length(false)` = 5
## ln(Decimal)
Gera o logaritmo natural do argumento. Argumentos `Decimal` são arredondados para dobrar a precisão antes da aplicação da função. Compatível com a versão de 08/10/2015 do SQL e posteriores.
Exemplo: `ln(e)` = 1.
****
| Tipo de argumento | Resultado |
| --- | --- |
| Int | Decimal (com precisão dupla), o log natural do argumento. |
| Decimal | Decimal (com precisão dupla), o log natural do argumento. |
| Boolean | Undefined. |
| String | Decimal (com precisão dupla), o log natural do argumento. Se a string não puder ser convertida em um Decimal, o resultado será Undefined. |
| Array | Undefined. |
| Objeto | Undefined. |
| Null | Undefined. |
| Não definido | Undefined. |
## log(Decimal)
Gera o logaritmo na base 10 do argumento. Argumentos `Decimal` são arredondados para dobrar a precisão antes da aplicação da função. Compatível com a versão de 08/10/2015 do SQL e posteriores.
Exemplo: `log(100)` = 2,0.
****
| Tipo de argumento | Resultado |
| --- | --- |
| Int | Decimal (com precisão dupla), o log de base 10 do argumento. |
| Decimal | Decimal (com precisão dupla), o log de base 10 do argumento. |
| Boolean | Undefined. |
| String | Decimal (com precisão dupla), o log de base 10 do argumento. Se a String não puder ser convertida em um Decimal, o resultado será Undefined. |
| Array | Undefined. |
| Objeto | Undefined. |
| Null | Undefined. |
| Não definido | Undefined. |
## lower(String)
Gera a versão em letra minúscula da `String` fornecida. Argumentos de não string são convertidos em strings usando as regras padrão de conversão. Compatível com a versão de 08/10/2015 do SQL e posteriores.
Exemplos:
`lower("HELLO")` = "hello".
`lower(["HELLO"])` = "[\$1"hello\$1"]".
## lpad(String, Int)
Gera o argumento de `String`, preenchido no lado esquerdo com o número de espaços especificado pelo segundo argumento. O argumento `Int` deve estar entre 0 e 1000. Se o valor fornecido estiver fora desse intervalo válido, o argumento será definido para o valor válido mais próximo (0 ou 1.000). Compatível com a versão de 08/10/2015 do SQL e posteriores.
Exemplos:
`lpad("hello", 2)` = "` hello`".
`lpad(1, 3)` = "` 1`"
****
| Tipo de argumento 1 | Tipo de argumento 2 | Resultado |
| --- | --- | --- |
| String | Int | String, a String preenchida fornecida no lado esquerdo com um número de espaços igual ao Int fornecido. |
| String | Decimal | O argumento Decimal será arredondado para o Int abaixo mais próximo, e a String será preenchida à esquerda com o número especificado de espaços. |
| String | String | O segundo argumento será convertido em um Decimal, que é arredondado para o Int abaixo mais próximo, e a String será preenchida com o número de espaços especificados à esquerda. Se o segundo argumento não puder ser convertido em um Int, o resultado será Undefined. |
| Outros valores | Int/Decimal/String | O primeiro valor será convertido em uma String usando as conversões padrão, e a função LPAD será aplicada nessa String. Se não for possível fazer a conversão, o resultado será Undefined. |
| Qualquer valor | Outros valores | Undefined. |
## ltrim(String)
Remove todos os espaços em branco iniciais (caracteres de tabulação e espaços) da `String` fornecida. Compatível com a versão de 08/10/2015 do SQL e posteriores.
Exemplo:
`Ltrim(" h i ")` = "hi ".
****
| Tipo de argumento | Resultado |
| --- | --- |
| Int | A representação de String do Int com todos os espaços em branco iniciais removidos. |
| Decimal | A representação de String do Decimal com todos os espaços em branco iniciais removidos. |
| Boolean | A representação de String do booliano ("verdadeiro" ou "falso") com todos os espaços em branco iniciais removidos. |
| String | O argumento com todos os espaços em branco iniciais removidos. |
| Array | A representação de String de Array (usando as regras padrão de conversão) com todos os espaços em branco iniciais removidos. |
| Objeto | A representação de String do objeto (usando as regras padrão de conversão) com todos os espaços em branco iniciais removidos. |
| Null | Undefined. |
| Não definido | Undefined. |
## machinelearning\$1predict(modelId, roleArn, registro)
Use a `machinelearning_predict` função para fazer previsões usando os dados de uma mensagem MQTT com base em um modelo de SageMaker IA da Amazon. Compatível com a versão de 08/10/2015 do SQL e posteriores. Os argumentos da função `machinelearning_predict` são:
modelId
O ID do modelo no qual executar a previsão. O endpoint em tempo real do modelo deve ser habilitado.
roleArn
O perfil do IAM; que tem uma política com as permissões `machinelearning:Predict` e `machinelearning:GetMLModel` e que permite acessar o modelo no qual a previsão é executada.
registro
Os dados a serem passados para a API SageMaker AI Predict. Isso deve ser representado como um único objeto JSON de camada. Se o registro for um objeto JSON de vários níveis, o registro será aplainado ao serializar seus valores. Por exemplo, o seguinte JSON:
```
{ "key1": {"innerKey1": "value1"}, "key2": 0}
```
se tornaria:
```
{ "key1": "{\"innerKey1\": \"value1\"}", "key2": 0}
```
A função gera um objeto JSON com os seguintes campos:
predictedLabel
A classificação da entrada com base no modelo.
detalhes
Contém os seguintes atributos:
PredictiveModelType
O tipo do modelo. Os valores válidos são REGRESSION, BINARY, MULTICLASS.
Algoritmo
O algoritmo usado pela SageMaker IA para fazer previsões. O valor deve ser SGD.
predictedScores
Contém a pontuação de classificação bruta correspondente a cada rótulo.
predictedValue
O valor previsto pela SageMaker IA.
## mod(Decimal, Decimal)
Gera o restante da divisão do primeiro argumento pelo segundo argumento. Equivale a [remainder(Decimal, Decimal)](#iot-func-remainder). Você também pode usar "%" como um operador infixo para a mesma funcionalidade do módulo. Compatível com a versão de 08/10/2015 do SQL e posteriores.
Exemplo: `mod(8, 3)` = 2.
****
| Operando esquerdo | Operando direito | Output |
| --- | --- | --- |
| Int | Int | Int, o primeiro argumento é módulo do segundo argumento. |
| Int/Decimal | Int/Decimal | Decimal, o primeiro argumento é módulo do segundo operando. |
| String/Int/Decimal | String/Int/Decimal | Se todas as strings forem convertidas em decimais, o resultado será o primeiro argumento como módulo do segundo argumento. Caso contrário, Undefined. |
| Outros valores | Outros valores | Undefined. |
## nanquim (,) AnyValue AnyValue
Gera o primeiro argumento se for um `Decimal` válido. Caso contrário, o segundo argumento é retornado. Compatível com a versão de 08/10/2015 do SQL e posteriores.
Exemplo: `Nanvl(8, 3)` = 8.
****
| Tipo de argumento 1 | Tipo de argumento 2 | Output |
| --- | --- | --- |
| Não definido | Qualquer valor | O segundo argumento. |
| Null | Qualquer valor | O segundo argumento. |
| Decimal (NaN) | Qualquer valor | O segundo argumento. |
| Decimal (não NaN) | Qualquer valor | O primeiro argumento. |
| Outros valores | Qualquer valor | O primeiro argumento. |
## newuuid()
Gera uma UUID aleatória de 16 bytes. Compatível com a versão de 08/10/2015 do SQL e posteriores.
Exemplo: `newuuid()` = `123a4567-b89c-12d3-e456-789012345000`
## numbytes(String)
Gera o número de bytes na codificação UTF-8 da string fornecida. As regras padrão de conversão se aplicam a argumentos de não `String`. Compatível com a versão de 23/03/2016 do SQL e posteriores.
Exemplos:
`numbytes("hi")` = 2
`numbytes("€") ` = 3
## parse\$1time(String, Long, [String])
Use a `parse_time` função para formatar um carimbo de data/hora em um formato legível por humanos date/time . Compatível com a versão de 23/03/2016 do SQL e posteriores. Para converter uma string de carimbo de data/hora em milissegundos, consulte [time\$1to\$1epoch(String, String)](#iot-sql-function-time-to-epoch).
A função `parse_time` espera os seguintes argumentos:
pattern
(String) Um date/time padrão que segue os formatos [Joda-Time.](http://www.joda.org/joda-time/apidocs/org/joda/time/format/DateTimeFormat.html)
timestamp
(Long) O tempo a ser formatado em milissegundos desde o epoch do Unix. Consulte a função [timestamp()](#iot-function-timestamp).
timezone
(String) O fuso horário da data/hora formatada. O padrão é "UTC". A função oferece suporte para [fusos horários Joda-Time](http://joda-time.sourceforge.net/timezones.html). Esse argumento é opcional.
Exemplos:
Quando essa mensagem for publicada no tópico "A/B", a carga útil `{"ts": "1970.01.01 AD at 21:46:40 CST"}` será enviada para o bucket do S3:
```
{
"ruleArn": "arn:aws:iot:us-east-2:ACCOUNT_ID:rule/RULE_NAME",
"topicRulePayload": {
"sql": "SELECT parse_time(\"yyyy.MM.dd G 'at' HH:mm:ss z\", 100000000, 'America/Belize' ) as ts FROM 'A/B'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"s3": {
"roleArn": "arn:aws:iam::ACCOUNT_ID:rule:role/ROLE_NAME",
"bucketName": "BUCKET_NAME",
"key": "KEY_NAME"
}
}
],
"ruleName": "RULE_NAME"
}
}
```
Quando essa mensagem for publicada no tópico 'A/B', uma carga útil semelhante a `{"ts": "2017.06.09 AD at 17:19:46 UTC"}` (mas com data/hora atual) será enviada para o bucket S3:
```
{
"ruleArn": "arn:aws:iot:us-east-2:ACCOUNT_ID:rule/RULE_NAME",
"topicRulePayload": {
"sql": "SELECT parse_time(\"yyyy.MM.dd G 'at' HH:mm:ss z\", timestamp() ) as ts FROM 'A/B'",
"awsIotSqlVersion": "2016-03-23",
"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()` também pode ser usado como um modelo de substituição. Por exemplo, quando esta mensagem for publicada no tópico "A/B", a carga útil será enviada para o bucket S3 com chave = "2017":
```
{
"ruleArn": "arn:aws:iot:us-east-2:ACCOUNT_ID:rule/RULE_NAME",
"topicRulePayload": {
"sql": "SELECT * FROM 'A/B'",
"awsIotSqlVersion": "2016-03-23",
"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)
Gera o primeiro argumento elevado ao segundo argumento. Argumentos `Decimal` são arredondados para dobrar a precisão antes da aplicação da função. Compatível com a versão de 08/10/2015 do SQL e posteriores. Compatível com a versão de 08/10/2015 do SQL e posteriores.
Exemplo: `power(2, 5)` = 32,0.
****
| Tipo de argumento 1 | Tipo de argumento 2 | Output |
| --- | --- | --- |
| Int/Decimal | Int/Decimal | Um Decimal (com precisão dupla), o primeiro argumento elevado para o poder do segundo argumento. |
| Int/Decimal/String | Int/Decimal/String | Um Decimal (com precisão dupla), o primeiro argumento elevado para o poder do segundo argumento. Quaisquer strings são convertidas em decimais. Se a conversão de alguma String em Decimal falhar, o resultado será Undefined. |
| Outros valores | Outros valores | Undefined. |
## principal()
Retorna a entidade principal que o dispositivo usa para autenticação, com base em como a mensagem acionadora foi publicada. A tabela a seguir descreve a entidade principal retornada para cada protocolo e método de publicação.
****
| Como a mensagem é publicada | Protocolo | Tipo de credencial | Entidade principal |
| --- | --- | --- | --- |
| Cliente MQTT | MQTT | Certificado de dispositivo X.509 | Thumbprint do certificado X.509 |
| AWS IoT cliente MQTT do console | MQTT | Usuário ou perfil do IAM | iam-role-id:session-name |
| AWS CLI | HTTP | Usuário ou perfil do IAM | userid |
| AWS IoT SDK do dispositivo | MQTT | Certificado de dispositivo X.509 | Thumbprint do certificado X.509 |
| AWS IoT SDK do dispositivo | Acabou o MQTT WebSocket | Usuário ou perfil do IAM | userid |
Os exemplos a seguir mostram os diferentes tipos de valores que `principal()` pode retornar:
+ Thumbprint do certificado X.509: `ba67293af50bf2506f5f93469686da660c7c844e7b3950bfb16813e0d31e9373`
+ ID do perfil do IAM e nome da sessão: `ABCD1EFG3HIJK2LMNOP5:my-session-name`
+ Retorna um ID de usuário: `ABCD1EFG3HIJK2LMNOP5`
## rand()
Gera um pseudoaleatório, uniformemente distribuído entre 0,0 e 1,0. Compatível com a versão de 08/10/2015 do SQL e posteriores.
Exemplo:
`rand()` = 0,8231909191640703
## regexp\$1matches(String, String)
Retorna verdadeiro se a string (primeiro argumento) contiver uma correspondência para a expressão regular (segundo argumento). Se você usar `|` na expressão regular, use-a com `()`.
Exemplos:
`regexp_matches("aaaa", "a{2,}") ` = true.
`regexp_matches("aaaa", "b")` = false.
`regexp_matches("aaa", "(aaa|bbb)") ` = true.
`regexp_matches("bbb", "(aaa|bbb)") ` = true.
`regexp_matches("ccc", "(aaa|bbb)") ` = false.
**Primeiro argumento:**
| Tipo de argumento | Resultado |
| --- | --- |
| Int | A representação da String do Int. |
| Decimal | A representação da String do Decimal. |
| Boolean | A representação da String do booleano ("verdadeiro" ou "falso"). |
| String | O String. |
| Array | A representação da String da Array (usando as regras padrão de conversão). |
| Objeto | A representação da String do Objeto (usando as regras padrão de conversão). |
| Null | Undefined. |
| Não definido | Undefined. |
*Segundo argumento:*
Deve ser uma expressão regex válida. Tipos de não string são convertidos em `String` usando as regras padrão de conversão. Dependendo do tipo, a string resultante pode não ser uma expressão regular válida. Se o argumento (convertido) não for uma regex válida, o resultado será `Undefined`.
## regexp\$1replace(String, String, String)
Substitui todas as ocorrências do segundo argumento (expressão regular) no primeiro argumento com o terceiro argumento. Faz referência a grupos de captura com "\$1". Compatível com a versão de 08/10/2015 do SQL e posteriores.
Exemplo:
`regexp_replace("abcd", "bc", "x")` = "axd".
`regexp_replace("abcd", "b(.*)d", "$1")` = "ac".
**Primeiro argumento:**
| Tipo de argumento | Resultado |
| --- | --- |
| Int | A representação da String do Int. |
| Decimal | A representação da String do Decimal. |
| Boolean | A representação da String do booleano ("verdadeiro" ou "falso"). |
| String | O valor de origem. |
| Array | A representação da String da Array (usando as regras padrão de conversão). |
| Objeto | A representação da String do Objeto (usando as regras padrão de conversão). |
| Null | Undefined. |
| Não definido | Undefined. |
*Segundo argumento:*
Deve ser uma expressão regex válida. Tipos de não string são convertidos em `String` usando as regras padrão de conversão. Dependendo do tipo, a string resultante pode não ser uma expressão regular válida. Se o argumento (convertido) não for uma expressão regex válida, o resultado será `Undefined`.
*Terceiro argumento:*
Deve ser uma string de substituição regex válida. (Pode fazer referência a grupos de captura.) Tipos de não string são convertidos em `String` usando as regras padrão de conversão. Se o argumento (convertido) não for uma string de substituição regex válida, o resultado será `Undefined`.
## regexp\$1substr(String, String)
Localiza a primeira correspondência do segundo parâmetro (regex) no primeiro parâmetro. Faz referência a grupos de captura com "\$1". Compatível com a versão de 08/10/2015 do SQL e posteriores.
Exemplo:
`regexp_substr("hihihello", "hi")` = "hi"
`regexp_substr("hihihello", "(hi)*")` = "hihi"
**Primeiro argumento:**
| Tipo de argumento | Resultado |
| --- | --- |
| Int | A representação da String do Int. |
| Decimal | A representação da String do Decimal. |
| Boolean | A representação da String do booleano ("verdadeiro" ou "falso"). |
| String | O argumento da String. |
| Array | A representação da String da Array (usando as regras padrão de conversão). |
| Objeto | A representação da String do Objeto (usando as regras padrão de conversão). |
| Null | Undefined. |
| Não definido | Undefined. |
*Segundo argumento:*
Deve ser uma expressão regex válida. Tipos de não string são convertidos em `String` usando as regras padrão de conversão. Dependendo do tipo, a string resultante pode não ser uma expressão regular válida. Se o argumento (convertido) não for uma expressão regex válida, o resultado será `Undefined`.
## remainder(Decimal, Decimal)
Gera o restante da divisão do primeiro argumento pelo segundo argumento. Equivale a [mod(Decimal, Decimal)](#iot-func-mod). Você também pode usar "%" como um operador infixo para a mesma funcionalidade do módulo. Compatível com a versão de 08/10/2015 do SQL e posteriores.
Exemplo: `remainder(8, 3)` = 2.
****
| Operando esquerdo | Operando direito | Output |
| --- | --- | --- |
| Int | Int | Int, o primeiro argumento é módulo do segundo argumento. |
| Int/Decimal | Int/Decimal | Decimal, o primeiro argumento é módulo do segundo operando. |
| String/Int/Decimal | String/Int/Decimal | Se todas as strings forem convertidas em decimais, o resultado será o primeiro argumento como módulo do segundo argumento. Caso contrário, Undefined. |
| Outros valores | Outros valores | Undefined. |
## replace(String, String, String)
Substitui todas as ocorrências do segundo argumento no primeiro argumento com o terceiro argumento. Compatível com a versão de 08/10/2015 do SQL e posteriores.
Exemplo:
`replace("abcd", "bc", "x")` = `"axd"`.
`replace("abcdabcd", "b", "x")` = `"axcdaxcd"`.
**Todos os argumentos**
| Tipo de argumento | Resultado |
| --- | --- |
| Int | A representação da String do Int. |
| Decimal | A representação da String do Decimal. |
| Boolean | A representação da String do booleano ("verdadeiro" ou "falso"). |
| String | O valor de origem. |
| Array | A representação da String da Array (usando as regras padrão de conversão). |
| Objeto | A representação da String do Objeto (usando as regras padrão de conversão). |
| Null | Undefined. |
| Não definido | Undefined. |
## rpad(String, Int)
Gera o argumento da string, preenchido no lado direito com o número de espaços especificado no segundo argumento. O argumento `Int` deve estar entre 0 e 1000. Se o valor fornecido estiver fora desse intervalo válido, o argumento será definido para o valor válido mais próximo (0 ou 1.000). Compatível com a versão de 08/10/2015 do SQL e posteriores.
Exemplos:
`rpad("hello", 2)` = "`hello `".
`rpad(1, 3)` = "`1 `".
****
| Tipo de argumento 1 | Tipo de argumento 2 | Resultado |
| --- | --- | --- |
| String | Int | A String é preenchida no lado direito com um número de espaços igual ao Int fornecido. |
| String | Decimal | O argumento Decimal será arredondado para o Int abaixo mais próximo, e a string será preenchida no lado direito com um número de espaços igual ao Int fornecido. |
| String | String | O segundo argumento é convertido em um Decimal, que é arredondado para o Int mais próximo. A String é preenchida no lado direito com um número de espaços igual ao valor Int. |
| Outros valores | Int/Decimal/String | O primeiro valor será convertido em uma String usando as conversões padrão, e a função rpad será aplicada nessa String. Se não for possível fazer a conversão, o resultado será Undefined. |
| Qualquer valor | Outros valores | Undefined. |
## round(Decimal)
Arredonda o `Decimal` fornecido para o `Int` mais próximo. Se o `Decimal` for equidistante de dois valores `Int` (por exemplo, 0,5), o `Decimal` será arredondado. Compatível com a versão de 08/10/2015 do SQL e posteriores.
Exemplo: `Round(1.2)` = 1.
`Round(1.5)` = 2.
`Round(1.7)` = 2.
`Round(-1.1)` = -1.
`Round(-1.5)` = -2.
****
| Tipo de argumento | Resultado |
| --- | --- |
| Int | O argumento. |
| Decimal | Decimal é arredondado para o Int abaixo mais próximo. |
| String | Decimal é arredondado para o Int abaixo mais próximo. Se a string não puder ser convertida em um Decimal, o resultado será Undefined. |
| Outros valores | Undefined. |
## rtrim(String)
Remove todos os espaços em branco finais (caracteres de tabulação e espaços) da `String` fornecida. Compatível com a versão de 08/10/2015 do SQL e posteriores.
Exemplos:
`rtrim(" h i ")` = " h i"
****
| Tipo de argumento | Resultado |
| --- | --- |
| Int | A representação da String do Int. |
| Decimal | A representação da String do Decimal. |
| Boolean | A representação da String do booleano ("verdadeiro" ou "falso"). |
| Array | A representação da String da Array (usando as regras padrão de conversão). |
| Objeto | A representação da String do Objeto (usando as regras padrão de conversão). |
| Null | Undefined. |
| Não definido | Undefined |
## sign(Decimal)
Gera o sinal do número fornecido. Quando o sinal do argumento for positivo, 1 será gerado. Quando o sinal do argumento for negativo, -1 será gerado. Se o argumento for 0, 0 será gerado. Compatível com a versão de 08/10/2015 do SQL e posteriores.
Exemplos:
`sign(-7)` = -1.
`sign(0)` = 0.
`sign(13)` = 1.
****
| Tipo de argumento | Resultado |
| --- | --- |
| Int | Int, o sinal do valor Int. |
| Decimal | Int, o sinal do valor Decimal. |
| String | Int, o sinal do valor Decimal. A string é convertida em um valor Decimal, e o sinal do valor Decimal é gerado. Se a String não puder ser convertida em um Decimal, o resultado será Undefined. Compatível com a versão de 08/10/2015 do SQL e posteriores. |
| Outros valores | Undefined. |
## sin(Decimal)
Gera o seno de um número em radianos. Argumentos `Decimal` são arredondados para dobrar a precisão antes da aplicação da função. Compatível com a versão de 08/10/2015 do SQL e posteriores.
Exemplo: `sin(0)` = 0,0
****
| Tipo de argumento | Resultado |
| --- | --- |
| Int | Decimal (com precisão dupla), o seno do argumento. |
| Decimal | Decimal (com precisão dupla), o seno do argumento. |
| Boolean | Undefined. |
| String | Decimal (com precisão dupla), o seno do argumento. Se a string não puder ser convertida em um Decimal, o resultado será Undefined. |
| Array | Undefined. |
| Objeto | Undefined. |
| Null | Undefined. |
| Undefined | Undefined. |
## sinh(Decimal)
Gera o seno hiperbólico de um número em radianos. Valores `Decimal` são arredondados para dobrar a precisão antes da aplicação da função. O resultado é um valor `Decimal` de precisão dupla. Compatível com a versão de 08/10/2015 do SQL e posteriores.
Exemplo: `sinh(2.3)` = 4,936961805545957
****
| Tipo de argumento | Resultado |
| --- | --- |
| Int | Decimal (com precisão dupla), o seno hiperbólico do argumento. |
| Decimal | Decimal (com precisão dupla), o seno hiperbólico do argumento. |
| Boolean | Undefined. |
| String | Decimal (com precisão dupla), o seno hiperbólico do argumento. Se a string não puder ser convertida em um Decimal, o resultado será Undefined. |
| Array | Undefined. |
| Objeto | Undefined. |
| Null | Undefined. |
| Não definido | Undefined. |
## sourceip()
Recupera o endereço IP de um dispositivo ou do roteador que se conecta a ele. Se o seu dispositivo estiver conectado diretamente à Internet, a função retornará o endereço IP de origem do dispositivo. Se o seu dispositivo estiver conectado a um roteador conectado à Internet, a função retornará o endereço IP de origem do dispositivo. Compatível com a versão SQL 23/03/2016. `sourceip()` não usa nenhum parâmetro.
**Importante**
O endereço IP de origem pública de um dispositivo geralmente é o endereço IP do último gateway de conversão de endereços de rede (NAT), como o roteador ou modem a cabo do seu provedor de serviços de Internet.
Exemplos:
`sourceip()="192.158.1.38"`
`sourceip()="1.102.103.104"`
`sourceip()="2001:db8:ff00::12ab:34cd"`
Exemplo de SQL:
`SELECT *, sourceip() as deviceIp FROM 'some/topic'`
Exemplos de como usar a função sourceip () em ações de AWS IoT Core regras:
**Exemplo 1**
O exemplo a seguir mostra como chamar a função () como [modelo de substituição](https://docs.aws.amazon.com//iot/latest/developerguide/iot-substitution-templates.html) em uma ação do [DynamoDB.](https://docs.aws.amazon.com//iot/latest/developerguide/dynamodb-rule-action.html)
```
{
"topicRulePayload": {
"sql": "SELECT * AS message FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"dynamoDB": {
"tableName": "my_ddb_table",
"hashKeyField": "key",
"hashKeyValue": "${sourceip()}",
"rangeKeyField": "timestamp",
"rangeKeyValue": "${timestamp()}",
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_dynamoDB"
}
}
]
}
}
```
**Exemplo 2**
O exemplo a seguir mostra como adicionar a função sourceip() como uma propriedade de usuário do MQTT usando [modelos de substituição](https://docs.aws.amazon.com//iot/latest/developerguide/iot-substitution-templates.html).
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"republish": {
"topic": "${topic()}/republish",
"roleArn": "arn:aws:iam::123456789012:role/aws_iot_republish",
"headers": {
"payloadFormatIndicator": "UTF8_DATA",
"contentType": "rule/contentType",
"correlationData": "cnVsZSBjb3JyZWxhdGlvbiBkYXRh",
"userProperties": [
{
"key": "ruleKey1",
"value": "ruleValue1"
},
{
"key": "sourceip",
"value": "${sourceip()}"
}
]
}
}
}
]
}
}
```
Você pode recuperar o endereço IP de origem das mensagens que passam para AWS IoT Core as regras dos caminhos do Message Broker e do [Basic Ingest](https://docs.aws.amazon.com//iot/latest/developerguide/iot-basic-ingest.html). Você também pode recuperar o IP de origem de ambos IPv4 e IPv6 das mensagens. O IP de origem será exibido da seguinte forma:
IPv6: `yyyy:yyyy:yyyy::yyyy:yyyy`
IPv4: `xxx.xxx.xxx.xxx`
**nota**
O IP de origem original não será transmitido pela [ação Republicar](republish-rule-action.md).
## substring(String, Int[, Int])
Espera uma `String` seguida de um ou dois valores `Int`. No caso de uma `String` e um único argumento `Int`, essa função gera a substring da `String` fornecida do índice `Int` fornecido (baseado em 0, inclusive) ao final da `String`. No caso de uma `String` e dois argumentos `Int`, essa função gera a substring da `String` fornecida no primeiro argumento de índice`Int` (baseado em 0, inclusive) para o segundo argumento de índice `Int` (baseado em 0, inclusive). Índices inferiores a zero são definidos como zero. Índices superiores ao comprimento da `String` são definidos para o comprimento da `String`. No caso da versão de argumento três, se o primeiro índice for superior ou igual ao segundo índice, o resultado será a `String` vazia.
Se os argumentos fornecidos não forem (*String*,*Int*) ou (*String*,*Int*,*Int*), as conversões padrão serão aplicadas aos argumentos para tentar convertê-los nos tipos corretos. Se os tipos não puderem ser convertidos, o resultado da função será `Undefined`. Compatível com a versão de 08/10/2015 do SQL e posteriores.
Exemplos:
`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)` = "".
## sql\$1version()
Retorna a versão SQL especificada nesta regra. Compatível com a versão de 08/10/2015 do SQL e posteriores.
Exemplo:
`sql_version()` = "23/03/2016"
## sqrt(Decimal)
Gera a raiz quadrada de um número. Argumentos `Decimal` são arredondados para dobrar a precisão antes da aplicação da função. Compatível com a versão de 08/10/2015 do SQL e posteriores.
Exemplo: `sqrt(9)` = 3,0.
****
| Tipo de argumento | Resultado |
| --- | --- |
| Int | A raiz quadrada do argumento. |
| Decimal | A raiz quadrada do argumento. |
| Boolean | Undefined. |
| String | A raiz quadrada do argumento. Se a string não puder ser convertida em um Decimal, o resultado será Undefined. |
| Array | Undefined. |
| Objeto | Undefined. |
| Null | Undefined. |
| Não definido | Undefined. |
## startswith(String, String)
Gera `Boolean`, independentemente de o primeiro argumento da string começar com o segundo argumento da string. Se um dos argumentos for `Null` ou `Undefined`, o resultado será `Undefined`. Compatível com a versão de 08/10/2015 do SQL e posteriores.
Exemplo:
`startswith("ranger","ran")` = true
****
| Tipo de argumento 1 | Tipo de argumento 2 | Resultado |
| --- | --- | --- |
| String | String | Independentemente de a primeira string começar com a segunda string. |
| Outros valores | Outros valores | Os dois argumentos são convertidos em strings usando as regras padrão de conversão. Retorna verdadeiro se independentemente de a primeira string começar com a segunda string. Se um dos argumentos for Null ou Undefined, o resultado será Undefined. |
## tan(Decimal)
Gera a tangente de um número em radianos. Valores `Decimal` são arredondados para dobrar a precisão antes da aplicação da função. Compatível com a versão de 08/10/2015 do SQL e posteriores.
Exemplo: `tan(3)` = -0,1425465430742778
****
| Tipo de argumento | Resultado |
| --- | --- |
| Int | Decimal (com precisão dupla), a tangente do argumento. |
| Decimal | Decimal (com precisão dupla), a tangente do argumento. |
| Boolean | Undefined. |
| String | Decimal (com precisão dupla), a tangente do argumento. Se a string não puder ser convertida em um Decimal, o resultado será Undefined. |
| Array | Undefined. |
| Objeto | Undefined. |
| Null | Undefined. |
| Não definido | Undefined. |
## tanh(Decimal)
Gera a tangente hiperbólica de um número em radianos. Valores `Decimal` são arredondados para dobrar a precisão antes da aplicação da função. Compatível com a versão de 08/10/2015 do SQL e posteriores.
Exemplo: `tanh(2.3)` = 0,9800963962661914
****
| Tipo de argumento | Resultado |
| --- | --- |
| Int | Decimal (com precisão dupla), a tangente hiperbólica do argumento. |
| Decimal | Decimal (com precisão dupla), a tangente hiperbólica do argumento. |
| Boolean | Undefined. |
| String | Decimal (com precisão dupla), a tangente hiperbólica do argumento. Se a string não puder ser convertida em um Decimal, o resultado será Undefined. |
| Array | Undefined. |
| Objeto | Undefined. |
| Null | Undefined. |
| Não definido | Undefined. |
## time\$1to\$1epoch(String, String)
Use a função `time_to_epoch` para converter uma string de timestamp em um número de milissegundos tempo de epoch do Unix. Compatível com a versão de 23/03/2016 do SQL e posteriores. Para converter milissegundos em uma string de carimbo de data/hora, consulte [parse\$1time(String, Long, [String])](#iot-sql-function-parse-time).
A função `time_to_epoch` espera os seguintes argumentos:
timestamp
(String) A string de carimbo de data/hora a ser convertida em milissegundos desde o epoch do Unix. Se a string do carimbo de data/hora não especificar um fuso horário, a função usará o fuso horário UTC.
pattern
(String) Um date/time padrão que segue [os formatos de JDK11 hora](http://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/time/format/DateTimeFormatter.html).
Exemplos:
`time_to_epoch("2020-04-03 09:45:18 UTC+01:00", "yyyy-MM-dd HH:mm:ss VV")` = 1585903518000
`time_to_epoch("18 December 2015", "dd MMMM yyyy")` = 1450396800000
`time_to_epoch("2007-12-03 10:15:30.592 America/Los_Angeles", "yyyy-MM-dd HH:mm:ss.SSS z")` = 1196705730592
## timestamp()
Retorna o timestamp atual em milissegundos a partir das 00:00:00 Horário Universal Coordenado (UTC), quinta-feira, 1º de janeiro de 1970, conforme observado pelo mecanismo de regras. AWS IoT Compatível com a versão de 08/10/2015 do SQL e posteriores.
Exemplo: `timestamp()` = `1481825251155`
## topic(Decimal)
Gera o tópico para o qual a mensagem que acionou a regra foi enviada. Se nenhum parâmetro for especificado, todo o tópico será gerado. O parâmetro `Decimal` é usado para especificar um segmento de tópico específico, com 1 designando o primeiro segmento. Para o tópico `foo/bar/baz`, topic(1) retornará `foo`, topic(2) retornará `bar`, e assim por diante. Compatível com a versão de 08/10/2015 do SQL e posteriores.
Exemplos:
`topic()` = "things/myThings/thingOne"
`topic(1)` = "objetos"
Quando a [Ingestão básica](iot-basic-ingest.md) for usada, o prefixo inicial do tópico (`$aws/rules/rule-name`) não estará disponível na função topic(). Por exemplo, considerando o tópico:
`$aws/rules/BuildingManager/Buildings/Building5/Floor2/Room201/Lights`
`topic()` = "Buildings/Building5/Floor2/Room201/Lights"
`topic(3)` = "Floor2"
## traceid()
Gera o ID de rastreamento (UUID) da mensagem MQTT ou `Undefined` caso a mensagem não tenha sido enviada por MQTT. Compatível com a versão de 08/10/2015 do SQL e posteriores.
Exemplo:
`traceid() ` = "12345678-1234-1234-1234-123456789012"
## transform(String, Objeto, Matriz)
Retorna uma matriz de objetos que contém o resultado da transformação especificada do parâmetro `Object` no parâmetro `Array`.
Compatível com a versão de 23/03/2016 do SQL e posteriores.
String
O modo de transformação a ser usado. Consulte a tabela a seguir para ver os modos de transformação compatíveis e como eles criam os `Result` a partir dos parâmetros `Object` e `Array`.
Objeto
Um objeto que contém os atributos a serem aplicados a cada elemento do `Array`.
Array
Uma matriz de objetos nos quais os atributos de `Object` são aplicados.
Cada objeto nessa matriz corresponde a um objeto na resposta da função. Cada objeto na resposta da função contém os atributos presentes no objeto original e os atributos fornecidos por `Object`, conforme determinado pelo modo de transformação especificado na `String`.
| Parâmetro `String` | Parâmetro `Object` | Parâmetro `Array` | Resultado |
| --- | --- | --- | --- |
| `enrichArray` | Objeto | Matriz de objetos | Uma matriz de objetos na qual cada objeto contém os atributos de um elemento do parâmetro `Array` e os atributos do parâmetro `Object`. |
| Qualquer outro valor | Qualquer valor | Qualquer valor | Não definido |
**nota**
A matriz retornada por essa função está limitada a 128 KiB.
### Exemplo 1 da função de transformação
Este exemplo mostra como a função **transform()** produz uma única matriz de objetos a partir de um objeto de dados e uma matriz.
Neste exemplo, a mensagem a seguir é publicada no tópico `A/B` do MQTT.
```
{
"attributes": {
"data1": 1,
"data2": 2
},
"values": [
{
"a": 3
},
{
"b": 4
},
{
"c": 5
}
]
}
```
Essa instrução SQL para uma ação de regra de tópico usa a função **transform()** com um valor de `String` de `enrichArray`. Neste exemplo, `Object` é a propriedade de `attributes` da carga da mensagem e `Array` é a matriz de `values`, que contém três objetos.
```
select value transform("enrichArray", attributes, values) from 'A/B'
```
Ao receber a carga útil da mensagem, a instrução SQL avalia a seguinte resposta.
```
[
{
"a": 3,
"data1": 1,
"data2": 2
},
{
"b": 4,
"data1": 1,
"data2": 2
},
{
"c": 5,
"data1": 1,
"data2": 2
}
]
```
### Exemplo 2 da função de transformação
Este exemplo mostra como a função **transform()** pode usar valores literais para incluir e renomear atributos individuais da carga útil da mensagem.
Neste exemplo, a mensagem a seguir é publicada no tópico `A/B` do MQTT. Essa é a mesma mensagem que foi usada em [Exemplo 1 da função de transformação](#iot-func-transform-example1).
```
{
"attributes": {
"data1": 1,
"data2": 2
},
"values": [
{
"a": 3
},
{
"b": 4
},
{
"c": 5
}
]
}
```
Essa instrução SQL para uma ação de regra de tópico usa a função **transform()** com um valor de `String` de `enrichArray`. O `Object` na função **transform()** tem um único atributo chamado `key` com o valor de `attributes.data1` na carga útil da mensagem e `Array` é a matriz de `values`, que contém os mesmos três objetos usados no exemplo anterior.
```
select value transform("enrichArray", {"key": attributes.data1}, values) from 'A/B'
```
Ao receber a carga útil da mensagem, esta instrução SQL avalia a seguinte resposta. Observe como a propriedade `data1` é nomeada `key` na resposta.
```
[
{
"a": 3,
"key": 1
},
{
"b": 4,
"key": 1
},
{
"c": 5,
"key": 1
}
]
```
### Exemplo 3 da função de transformação
Este exemplo mostra como a função **transform()** pode ser usada em cláusulas SELECT aninhadas para selecionar vários atributos e criar novos objetos para processamento posterior.
Neste exemplo, a mensagem a seguir é publicada no tópico `A/B` do MQTT.
```
{
"data1": "example",
"data2": {
"a": "first attribute",
"b": "second attribute",
"c": [
{
"x": {
"someInt": 5,
"someString": "hello"
},
"y": true
},
{
"x": {
"someInt": 10,
"someString": "world"
},
"y": false
}
]
}
}
```
O `Object` para esta função de transformação é o objeto retornado pela instrução SELECT, que contém os elementos `a` e `b` do objeto `data2` da mensagem. O parâmetro `Array` consiste nos dois objetos da matriz `data2.c` na mensagem original.
```
select value transform('enrichArray', (select a, b from data2), (select value c from data2)) from 'A/B'
```
Com a mensagem anterior, a instrução SQL avalia a seguinte resposta.
```
[
{
"x": {
"someInt": 5,
"someString": "hello"
},
"y": true,
"a": "first attribute",
"b": "second attribute"
},
{
"x": {
"someInt": 10,
"someString": "world"
},
"y": false,
"a": "first attribute",
"b": "second attribute"
}
]
```
A matriz retornada nessa resposta pode ser usada com ações de regras de tópico compatíveis com `batchMode`.
## trim(String)
Remove todos os espaços em branco iniciais e finais da `String` fornecida. Compatível com a versão de 08/10/2015 do SQL e posteriores.
Exemplo:
`Trim(" hi ") ` = "hi"
****
| Tipo de argumento | Resultado |
| --- | --- |
| Int | A representação de String de Int com todos os espaços em branco iniciais e finais removidos. |
| Decimal | A representação de String de Decimal com todos os espaços em branco iniciais e finais removidos. |
| Boolean | A representação de String de Boolean ("verdadeiro" ou "falso") com todos os espaços em branco iniciais e finais removidos. |
| String | A String com todos os espaços em branco iniciais e finais removidos. |
| Array | A representação da String da Array usando as regras padrão de conversão. |
| Objeto | A representação da String do Objeto usando as regras padrão de conversão. |
| Null | Undefined. |
| Não definido | Undefined. |
## trunc(Decimal, Int)
Trunca o primeiro argumento para o número de lugares `Decimal` especificado pelo segundo argumento. Se o segundo argumento for inferior a zero, ele será definido como zero. Se o segundo argumento for superior a 34, ele será definido como 34. Os zeros finais são removidos do resultado. Compatível com a versão de 08/10/2015 do SQL e posteriores.
Exemplos:
`trunc(2.3, 0)` = 2.
`trunc(2.3123, 2)` = 2,31.
`trunc(2.888, 2)` = 2,88.
`trunc(2.00, 5)` = 2.
****
| Tipo de argumento 1 | Tipo de argumento 2 | Resultado |
| --- | --- | --- |
| Int | Int | O valor de origem. |
| Int/Decimal | Int/Decimal | O primeiro argumento é truncado para o comprimento descrito pelo segundo argumento. O segundo argumento, se não for um Int, será arredondado para o Int abaixo mais próximo. |
| Int/Decimal/String | Int/Decimal | O primeiro argumento é truncado para o comprimento descrito pelo segundo argumento. O segundo argumento, se não for um Int, será arredondado para o Int abaixo mais próximo. A String é convertida em um valor Decimal. Se não for possível converter a string, o resultado será Undefined. |
| Outros valores | | Undefined. |
## upper(String)
Gera a versão em letra maiúscula da `String` fornecida. Os argumentos de não`String` são convertidos em `String` usando as regras de conversão padrão. Compatível com a versão de 08/10/2015 do SQL e posteriores.
Exemplos:
`upper("hello")` = "HELLO"
`upper(["hello"])` = "[\$1"HELLO\$1"]"
# Literais
Você pode especificar diretamente objetos literais nas cláusulas WHERE e SELECT da regra SQL, que pode ser útil para transmitir informações.
**nota**
Literais estão disponíveis somente ao usar a versão de 23/03/2016 do SQL ou posteriores.
A sintaxe de objeto JSON é usada (pares de chave-valor, separado por vírgula, em que as chaves são strings, e os valores são valores JSON, entre chaves \$1\$1). Por exemplo:
Carga útil de entrada publicada no tópico `topic/subtopic`: `{"lat_long": [47.606,-122.332]}`
Declaração do SQL: `SELECT {'latitude': get(lat_long, 0),'longitude':get(lat_long, 1)} as lat_long FROM 'topic/subtopic'`
A carga útil de saída resultante seria: `{"lat_long":{"latitude":47.606,"longitude":-122.332}}`.
Você também pode especificar diretamente matrizes nas cláusulas WHERE e SELECT da regra SQL, o que permite agrupar informações. A sintaxe JSON é usada (encapsular itens separados por vírgula entre colchetes [] para criar uma matriz literal). Por exemplo:
Carga útil de entrada publicada no tópico `topic/subtopic`: `{"lat": 47.696, "long": -122.332}`
Declaração do SQL: `SELECT [lat,long] as lat_long FROM 'topic/subtopic'`
A carga útil de saída resultante seria: `{"lat_long": [47.606,-122.332]}`.
# Declarações de caso
As declarações de caso podem ser usadas para execução de ramificação, como uma declaração de troca.
Sintaxe:
```
CASE v WHEN t[1] THEN r[1]
WHEN t[2] THEN r[2] ...
WHEN t[n] THEN r[n]
ELSE r[e] END
```
A expressão *`v`* é avaliada e comparada quanto à igualdade com o valor *`t[i]`* de cada cláusula `WHEN`. Se uma correspondência for encontrada, a expressão *`r[i]`* correspondente se tornará o resultado da declaração do `CASE`. As cláusulas `WHEN` são avaliadas em ordem para que, se houver mais de uma cláusula correspondente, o resultado da primeira cláusula correspondente se torne o resultado da declaração do `CASE`. Se não houver correspondências, *`r[e]`* da cláusula `ELSE` é o resultado. Se não houver correspondências e não houver cláusula `ELSE`, o resultado é `Undefined`.
As declarações de `CASE` exigem, pelo menos, uma cláusula `WHEN`. Qualquer cláusula `ELSE` é opcional.
Por exemplo:
Carga útil de entrada publicada no tópico `topic/subtopic`:
```
{
"color":"yellow"
}
```
Declaração do 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 instructions
FROM 'topic/subtopic'
```
A carga útil de saída resultante seria:
```
{
"instructions":"caution"
}
```
**nota**
Se *`v`* for `Undefined`, o resultado da declaração do caso será `Undefined`.
# Extensões JSON
Você pode usar as seguintes extensões para a sintaxe SQL padrão ANSI para facilitar o trabalho com objetos JSON aninhados.
Operador "."
Esse operador acessa membros em objetos JSON incorporados e funciona de forma idêntica ao ANSI SQL e. JavaScript Por exemplo:
```
SELECT foo.bar AS bar.baz FROM 'topic/subtopic'
```
seleciona o valor da propriedade `bar` no objeto `foo` a partir da seguinte carga útil de mensagem enviada ao tópico `topic/subtopic`.
```
{
"foo": {
"bar": "RED",
"bar1": "GREEN",
"bar2": "BLUE"
}
}
```
Se o nome de uma propriedade JSON incluir um caractere de hífen ou caracteres numéricos, a notação 'ponto' não funcionará. Em vez disso, você deve usar a [função get](iot-sql-functions.md#iot-sql-function-get) para extrair o valor da propriedade.
Neste exemplo, a mensagem a seguir é enviada ao tópico `iot/rules`.
```
{
"mydata": {
"item2": {
"0": {
"my-key": "myValue"
}
}
}
}
```
Normalmente, o valor de `my-key` seria identificado como nessa consulta.
```
SELECT * from iot/rules WHERE mydata.item2.0.my-key= "myValue"
```
No entanto, como o nome da propriedade `my-key` contém um hífen e `item2` contém um caractere numérico, a [função get](iot-sql-functions.md#iot-sql-function-get) deve ser usada conforme mostra a consulta a seguir.
```
SELECT * from 'iot/rules' WHERE get(get(get(mydata,"item2"),"0"),"my-key") = "myValue"
```
`*`Operador
Funciona da mesma maneira que o caractere curinga `*` em SQL padrão ANSI. É usado somente na cláusula SELECT e cria outro objeto JSON contendo os dados da mensagem. Se a carga útil da mensagem não estiver no formato JSON, `*` gerará toda a carga útil da mensagem como bytes brutos. Por exemplo:
```
SELECT * FROM 'topic/subtopic'
```
**Como aplicar uma função a um valor de atributo**
Veja a seguir um exemplo de carga útil JSON que pode ser publicada por um dispositivo:
```
{
"deviceid" : "iot123",
"temp" : 54.98,
"humidity" : 32.43,
"coords" : {
"latitude" : 47.615694,
"longitude" : -122.3359976
}
}
```
O exemplo a seguir aplica uma função a um valor de atributo em uma carga útil JSON:
```
SELECT temp, md5(deviceid) AS hashed_id FROM topic/#
```
O resultado dessa consulta é o seguinte objeto JSON:
```
{
"temp": 54.98,
"hashed_id": "e37f81fb397e595c4aeb5645b8cbbbd1"
}
```
# Modelos de substituição
Você pode usar um modelo de substituição para aumentar os dados JSON retornados quando uma regra é acionada e AWS IoT executa uma ação. A sintaxe de um modelo de substituição é `${` *expressão`}`, em que expressão* pode ser qualquer *expressão* suportada AWS IoT nas cláusulas SELECT, nas cláusulas WHERE e. [AWS IoT ações de regras](iot-rule-actions.md) Essa expressão pode ser conectada a um campo de ação em uma regra, permitindo que você configure dinamicamente uma ação. Na verdade, esse recurso substitui uma informação em uma ação. Isso inclui funções, operadores e informações presentes na carga da mensagem original.
**Importante**
Como uma expressão em um modelo de substituição é avaliada separadamente da instrução "SELECT...", você não pode fazer referência a um alias criado com a cláusula AS. Você pode fazer referência somente às informações presentes na carga original, além das [funções](iot-sql-functions.md) e dos [operadores](iot-sql-operators.md) compatíveis.
Para obter mais informações sobre as expressões compatíveis, consulte [AWS IoT Referência SQL](iot-sql-reference.md).
As ações de regra a seguir oferecem suporte a modelos de substituição. Cada ação oferece suporte a campos diferentes que podem ser substituídos.
+ [Apache Kafka](apache-kafka-rule-action.md)
+ [CloudWatch alarmes](cloudwatch-alarms-rule-action.md)
+ [CloudWatch Registros](cloudwatch-logs-rule-action.md)
+ [CloudWatch métricas](cloudwatch-metrics-rule-action.md)
+ [DynamoDB](dynamodb-rule-action.md)
+ [Dínamo DBv2](dynamodb-v2-rule-action.md)
+ [Elasticsearch](elasticsearch-rule-action.md)
+ [HTTP](https-rule-action.md)
+ [AWS IoT Events](iotevents-rule-action.md)
+ [AWS IoT SiteWise](iotsitewise-rule-action.md)
+ [Kinesis Data Streams](kinesis-rule-action.md)
+ [Firehose](kinesis-firehose-rule-action.md)
+ [Lambda](lambda-rule-action.md)
+ [Local](location-rule-action.md)
+ [OpenSearch](opensearch-rule-action.md)
+ [Nova publicação](republish-rule-action.md)
+ [S3](s3-rule-action.md)
+ [SNS](sns-rule-action.md)
+ [SQS](sqs-rule-action.md)
+ [Step Functions](stepfunctions-rule-action.md)
+ [Timestream](timestream-rule-action.md)
Os modelos de substituição aparecem nos parâmetros de ação dentro de uma regra:
```
{
"sql": "SELECT *, timestamp() AS timestamp FROM 'my/iot/topic'",
"ruleDisabled": false,
"actions": [{
"republish": {
"topic": "${topic()}/republish",
"roleArn": "arn:aws:iam::123456789012:role/my-iot-role"
}
}]
}
```
Se essa regra for acionada pelo JSON a seguir publicado em `my/iot/topic`:
```
{
"deviceid": "iot123",
"temp": 54.98,
"humidity": 32.43,
"coords": {
"latitude": 47.615694,
"longitude": -122.3359976
}
}
```
Em seguida, essa regra publica o seguinte JSON em`my/iot/topic/republish`, que AWS IoT substitui de: `${topic()}/republish`
```
{
"deviceid": "iot123",
"temp": 54.98,
"humidity": 32.43,
"coords": {
"latitude": 47.615694,
"longitude": -122.3359976
},
"timestamp": 1579637878451
}
```
# Consultas de objeto aninhado
Você pode usar cláusulas SELECT aninhadas para consultar atributos dentro de matrizes e objetos JSON internos. Compatível com a versão de 23/03/2016 do SQL e posteriores.
Considere a seguinte mensagem 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 }
]
}
```
**Example**
Você pode converter valores em uma nova matriz com a seguinte regra.
```
SELECT (SELECT VALUE n FROM e) as sensors FROM 'my/topic'
```
A regra gera a seguinte saída:
```
{
"sensors": [
"temperature",
"light",
"acidity"
]
}
```
**Example**
Usando a mesma mensagem MQTT, você também pode consultar um valor específico dentro de um objeto aninhado com a seguinte regra.
```
SELECT (SELECT v FROM e WHERE n = 'temperature') as temperature FROM 'my/topic'
```
A regra gera a seguinte saída:
```
{
"temperature": [
{
"v": 22.5
}
]
}
```
**Example**
Você também pode nivelar a saída com uma regra mais complicada.
```
SELECT get((SELECT v FROM e WHERE n = 'temperature'), 0).v as temperature FROM 'topic'
```
A regra gera a seguinte saída:
```
{
"temperature": 22.5
}
```
# Como trabalhar com cargas úteis binárias
Para tratar a carga da mensagem como dados binários brutos (em vez de um objeto JSON), você pode usar o operador \$1 para fazer referência a ela em uma cláusula SELECT.
**Topics**
+ [Exemplos de cargas úteis binárias](#binary-payloads-examples)
+ [Decodificar as cargas úteis da mensagem protobuf](#binary-payloads-protobuf)
## Exemplos de cargas úteis binárias
Ao usar \$1 para se referir à carga da mensagem como dados binários brutos, você pode adicionar dados à regra. Se você tiver uma carga vazia ou JSON, a carga resultante poderá ter dados adicionados usando a regra. Veja a seguir exemplos de cláusulas `SELECT` compatíveis.
+ Você pode usar as cláusulas `SELECT` a seguir com apenas um \$1 para cargas binárias.
+
```
SELECT * FROM 'topic/subtopic'
```
+
```
SELECT * FROM 'topic/subtopic' WHERE timestamp() % 12 = 0
```
+ Você também pode adicionar dados e usar as cláusulas `SELECT` a seguir.
+
```
SELECT *, principal() as principal, timestamp() as time FROM 'topic/subtopic'
```
+
```
SELECT encode(*, 'base64') AS data, timestamp() AS ts FROM 'topic/subtopic'
```
+ Você também pode usar essas cláusulas `SELECT` com cargas binárias.
+ O seguinte se refere ao `device_type` na cláusula WHERE.
```
SELECT * FROM 'topic/subtopic' WHERE device_type = 'thermostat'
```
+ Também há suporte para:
```
{
"sql": "SELECT * FROM 'topic/subtopic'",
"actions": [
{
"republish": {
"topic": "device/${device_id}"
}
}
]
}
```
As ações de regra a seguir não oferecem suporte a cargas binárias, portanto, você deve decodificá-las.
+ Algumas ações de regra não oferecem suporte a entrada de carga útil binária, como a [ação do Lambda](https://docs.aws.amazon.com/iot/latest/developerguide/iot-rule-actions.html#lambda-rule), então é necessário decodificar cargas úteis binárias. A ação de regra do Lambda poderá receber dados binários se estiverem codificados em base64 e em uma carga útil JSON. É possível fazer isso alterando a regra para a seguinte:
```
SELECT encode(*, 'base64') AS data FROM 'my_topic'
```
+ A instrução SQL não oferece suporte a string como entrada. Para converter uma entrada de string em JSON, é possível executar o seguinte comando.
```
SELECT decode(encode(*, 'base64'), 'base64') AS payload FROM 'topic'
```
## Decodificar as cargas úteis da mensagem protobuf
[Protocol Buffers (protobuf)](https://developers.google.com/protocol-buffers) é um formato de dados de código aberto usado para serializar dados estruturados em um formato binário compacto. É usado para transmitir dados por redes ou armazená-los em arquivos. O Protobuf permite que você envie dados em pacotes pequenos e em uma taxa mais rápida do que outros formatos de mensagens. AWS IoT Core As regras oferecem suporte ao protobuf fornecendo a função SQL [decode (value, decodingScheme)](iot-sql-functions.md#iot-sql-decode-base64), que permite decodificar cargas de mensagens codificadas por protobuf para o formato JSON e roteá-las para serviços downstream. Esta seção detalha o step-by-step processo para configurar a decodificação do protobuf em Regras. AWS IoT Core
**Topics**
+ [Pré-requisitos](#binary-payloads-protobuf-prerequisites)
+ [Criar arquivos descritores](#binary-payloads-protobuf-descriptor-steps)
+ [Upload de arquivos descritores em um bucket do S3](#binary-payloads-protobuf-s3-steps)
+ [Configurar a decodificação do protobuf em Regras](#binary-payloads-protobuf-steps)
+ [Limitações](#binary-payloads-protobuf-limitations)
+ [Práticas recomendadas](#binary-payloads-protobuf-bestpractices)
### Pré-requisitos
+ Uma compreensão básica dos [Protocol Buffers (protobuf)](https://developers.google.com/protocol-buffers)
+ Os [arquivos `.proto`](https://developers.google.com/protocol-buffers/docs/proto3) que definem os tipos de mensagens e dependências relacionadas
+ Instalação do [compilador Protobuf (protoc)](https://github.com/protocolbuffers/protobuf/releases) em seu sistema
### Criar arquivos descritores
Se já tiver arquivos de descrição, você poderá ignorar esta etapa. Um arquivo descritor (`.desc`) é uma versão compilada de um arquivo `.proto`, que é um arquivo de texto que define as estruturas de dados e os tipos de mensagens a serem usados em uma serialização do protobuf. Para gerar um arquivo descritor, você deve definir um arquivo `.proto` e usar o compilador [protoc](https://github.com/protocolbuffers/protobuf/releases) para compilá-lo.
1. Crie arquivos `.proto` que definam os tipos de mensagem. Um exemplo de arquivo `.proto` pode ser o seguinte:
```
syntax = "proto3";
message Person {
optional string name = 1;
optional int32 id = 2;
optional string email = 3;
}
```
Neste exemplo de arquivo `.proto`, você usa a sintaxe proto3 e define o tipo de mensagem `Person`. A definição da mensagem `Person` especifica três campos (nome, ID e e-mail). Para obter mais informações sobre formatos de mensagem de arquivo `.proto`, consulte o [Guia de idiomas (proto3)](https://developers.google.com/protocol-buffers/docs/proto3).
1. Use o compilador [protoc](https://github.com/protocolbuffers/protobuf/releases) para compilar os arquivos `.proto` e gerar um arquivo descritor. Um exemplo de comando para criar um arquivo descritor (`.desc`) pode ser o seguinte:
```
protoc --descriptor_set_out=.desc \
--proto_path= \
--include_imports \
.proto
```
Esse exemplo de comando gera um arquivo descritor`.desc`, que o AWS IoT Core Rules pode usar para decodificar cargas de protobuf que estejam em conformidade com a estrutura de dados definida em. `.proto`
+ `--descriptor_set_out`
Especifica o nome do arquivo descritor (`.desc`) que deve ser gerado.
+ `--proto_path`
Especifica os locais de todos os arquivos `.proto` importados referenciados pelo arquivo que está sendo compilado. Você pode especificar o sinalizador várias vezes se tiver vários arquivos `.proto` importados com locais diferentes.
+ `--include_imports`
Especifica que todos os arquivos `.proto` importados também devem ser compilados e incluídos no arquivo `.desc` descritor.
+ `.proto`
Especifica o nome do arquivo `.proto` que você deseja compilar.
Para obter mais informações sobre a referência protoc, consulte [Referência de API](https://developers.google.com/protocol-buffers/docs/reference/overview).
### Upload de arquivos descritores em um bucket do S3
Depois de criar seus arquivos descritores`.desc`, faça o upload dos arquivos `.desc` descritores em um bucket do Amazon S3 usando AWS a API AWS , o SDK ou o. Console de gerenciamento da AWS
**Considerações importantes**
+ Certifique-se de carregar os arquivos do descritor em um bucket do Amazon S3 no Região da AWS mesmo local em que você pretende configurar Conta da AWS suas regras.
+ Certifique-se de conceder AWS IoT Core acesso para ler o `FileDescriptorSet` do S3. Se o seu bucket do S3 tiver a criptografia do lado do servidor (SSE) desativada ou se o bucket do S3 estiver criptografado usando chaves gerenciadas pelo Amazon S3 (SSE-S3), nenhuma configuração adicional de política será necessária. Isso pode ser feito com o exemplo de política de bucket:
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "Statement1",
"Effect": "Allow",
"Principal": {
"Service": "iot.amazonaws.com"
},
"Action": "s3:Get*",
"Resource": "arn:aws:s3:::/.desc"
}
]
}
```
+ Se o bucket do S3 for criptografado usando uma AWS Key Management Service chave (SSE-KMS), certifique-se de conceder AWS IoT Core permissão para usar a chave ao acessar o bucket do S3. Você pode fazer isso adicionando esta declaração à sua política de chave:
```
{
"Sid": "Statement1",
"Effect": "Allow",
"Principal": {
"Service": "iot.amazonaws.com"
},
"Action": [
"kms:Decrypt",
"kms:GenerateDataKey*",
"kms:DescribeKey"
],
"Resource": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab"
}
```
### Configurar a decodificação do protobuf em Regras
Depois de fazer o upload dos arquivos do descritor no bucket do Amazon S3, configure uma [regra](https://docs.aws.amazon.com//iot/latest/developerguide/iot-create-rule.html) que possa decodificar o formato de carga útil da mensagem protobuf usando a função SQL [decode(value, decodingScheme)](iot-sql-functions.md#iot-sql-decode-base64). Uma assinatura de função detalhada e um exemplo podem ser encontrados na função SQL [decode(value, decodingScheme)](iot-sql-functions.md#iot-sql-decode-base64) da *referência SQL de AWS IoT *.
Veja a seguir um exemplo de expressão SQL usando a função [decode(value, decodingScheme)](iot-sql-functions.md#iot-sql-decode-base64):
```
SELECT VALUE decode(*, 'proto', '', '.desc', '', '') FROM ''
```
Neste exemplo de expressão:
+ Você usa a função SQL [decode(value, decodingScheme)](iot-sql-functions.md#iot-sql-decode-base64) para decodificar a carga útil da mensagem binária referenciada por `*`. Isso pode ser uma carga binária codificada por protobuf ou uma string JSON que representa uma carga útil protobuf codificada em base64.
+ A carga útil da mensagem fornecida é codificada usando o tipo de mensagem `Person` definido em `PROTO_FILENAME.proto`.
+ O bucket do Amazon S3 chamado `BUCKET NAME` contém o `FILENAME.desc` gerado de `PROTO_FILENAME.proto`.
Depois de concluir a configuração, publique uma mensagem no tópico AWS IoT Core no qual a Regra está inscrita.
### Limitações
AWS IoT Core As regras oferecem suporte ao protobuf com as seguintes limitações:
+ A decodificação de cargas de mensagens protobuf em [modelos de substituição](https://docs.aws.amazon.com//iot/latest/developerguide/iot-substitution-templates.html) não é suportada.
+ Ao decodificar cargas de mensagens protobuf, você pode usar a [função decodificar SQL](iot-sql-functions.md#iot-sql-decode-base64) em uma única expressão SQL até duas vezes.
+ O tamanho máximo da carga útil de entrada é 128 KiB (1 KiB = 1024 bytes), o tamanho máximo da carga de saída é 128 KiB e o tamanho máximo de um objeto `FileDescriptorSet` armazenado em um bucket do Amazon S3 é 32 KiB.
+ Não há suporte para buckets do Amazon S3 criptografados com a criptografia SSE-C.
### Práticas recomendadas
Veja a seguir algumas práticas recomendadas e dicas de solução de problemas.
+ Carregue seus arquivos proto no bucket no Amazon S3.
É uma prática recomendada fazer backup de seus arquivos proto caso algo dê errado. Por exemplo, se você modificar incorretamente os arquivos proto sem backups ao executar protoc, isso pode causar problemas em sua pilha de produção. Há várias maneiras de fazer backup de arquivos em um bucket do Amazon S3. Por exemplo, você pode [usar o versionamento em buckets do S3](https://docs.aws.amazon.com//AmazonS3/latest/userguide/Versioning.html). Para obter mais informações sobre como fazer backup de arquivos em buckets do Amazon S3, consulte o *[Guia do desenvolvedor do Amazon S3](https://docs.aws.amazon.com//aws-backup/latest/devguide/recovery-points.html)*.
+ Configure o AWS IoT registro para visualizar as entradas do registro.
É uma boa prática configurar o AWS IoT registro para que você possa verificar AWS IoT os registros da sua conta CloudWatch. Quando a consulta SQL de uma regra chama uma função externa, o AWS IoT Core Rules gera uma entrada de registro com um `eventType` de`FunctionExecution`, que contém o campo de motivo que o ajudará a solucionar falhas. Os possíveis erros incluem um objeto do Amazon S3 não encontrado ou um descritor de arquivo protobuf inválido. Para obter mais informações sobre como configurar o registro de AWS IoT e ver as entradas de log, consulte [Configurar o registro de AWS IoT](https://docs.aws.amazon.com//iot/latest/developerguide/configure-logging.html) e [Entradas de log do mecanismo de regras](https://docs.aws.amazon.com//iot/latest/developerguide/cwl-format.html#log-rules-fn-exec).
+ Atualize o `FileDescriptorSet` usando uma nova chave de objeto e atualize a chave de objeto em sua regra.
Você pode atualizar o `FileDescriptorSet` fazendo upload de um arquivo de descritor atualizado para o seu bucket do Amazon S3. Suas atualizações do `FileDescriptorSet` podem levar até 15 minutos para serem refletidas. Para evitar esse atraso, é uma prática recomendada carregar seu `FileDescriptorSet` atualizado usando uma nova chave de objeto e atualizar a chave de objeto em sua regra.
# Versões do SQL
O mecanismo de AWS IoT regras usa uma sintaxe semelhante ao SQL para selecionar dados das mensagens MQTT. As instruções SQL são interpretadas com base em uma versão do SQL especificada com a propriedade `awsIotSqlVersion` em um documento JSON que descreve a regra. Para obter mais informações sobre a estrutura de documentos de regra JSON, consulte [Como criar uma regra](iot-create-rule.md). A `awsIotSqlVersion` propriedade permite especificar qual versão do mecanismo de regras AWS IoT SQL você deseja usar. Quando uma nova versão é implantada, você pode continuar usando uma versão mais antiga ou alterar a regra para usar a nova versão. As regras atuais continuam a usar a versão com a qual foram criadas.
O seguinte exemplo de JSON mostra como especificar a versão do SQL usando a propriedade `awsIotSqlVersion`.
```
{
"sql": "expression",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [{
"republish": {
"topic": "my-mqtt-topic",
"roleArn": "arn:aws:iam::123456789012:role/my-iot-role"
}
}]
}
```
AWS IoT atualmente oferece suporte às seguintes versões do SQL:
+ `2016-03-23` – A versão SQL implantada em 23/03/2016 (recomendada).
+ `2015-10-08` – A versão original do SQL implantada em 08/10/2015.
+ `beta` – A versão beta mais recente do SQL. Essa versão pode causar alterações nas regras.
## Novidades da versão 23/03/2016 do mecanismo de regras SQL
+ Correções na seleção de objetos JSON aninhados.
+ Correções em consultas de matrizes.
+ Suporte para consulta entre objetos. Para obter mais informações, consulte [Consultas de objeto aninhado](iot-sql-nested-queries.md).
+ Suporte para emitir uma matriz como um objeto de nível superior.
+ Adição da função `encode(value, encodingScheme)`, que pode ser aplicada em dados em formato JSON e não JSON. Para obter mais informações, consulte a [função de codificação](iot-sql-functions.md#iot-sql-encode-payload).
### Resultado de uma `Array` como um objeto de nível superior
Esse recurso permite que uma regra gere uma matriz como um objeto de nível superior. Por exemplo, com base na seguinte mensagem MQTT:
```
{
"a": {"b":"c"},
"arr":[1,2,3,4]
}
```
E a seguinte regra:
```
SELECT VALUE arr FROM 'topic'
```
A regra gera a seguinte saída:
```
[1,2,3,4]
```