Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.
# Règles pour AWS IoT
Les règles permettent à vos appareils d'interagir avec Services AWS. Les règles sont analysées et les actions exécutées en fonction du flux de rubrique MQTT. Vous pouvez utiliser des règles pour effectuer les tâches suivantes :
+ Augmenter ou filtrer les données reçues d'un appareil.
+ Écrire les données reçues d'un appareil dans une base de données Amazon DynamoDB.
+ Enregistrer un fichier dans Amazon S3.
+ Envoyer une notification push à tous les utilisateurs qui utilisent Amazon SNS
+ Publier des donnés dans une file d'attente Amazon SQS.
+ Invoquer une fonction Lambda pour extraire des données.
+ Traiter les messages provenant d'un grand nombre d'appareils à l'aide de Amazon Kinesis.
+ Envoyez des données à Amazon OpenSearch Service.
+ Capturez une CloudWatch métrique.
+ Changez une CloudWatch alarme.
+ Envoyez les données d'un message MQTT à Amazon SageMaker AI pour établir des prédictions basées sur un modèle d'apprentissage automatique (ML).
+ Envoyer un message à un flux d'entrée Salesforce IoT
+ Processus de démarrage d'un automate à fonctions par étapes.
+ Envoyer les données du message à une AWS IoT Events entrée.
+ Envoyer des données de message à une propriété de l'actif dans AWS IoT SiteWise.
+ Envoyer des données de message à une application web ou à un service.
Vos règles peuvent utiliser des messages MQTT qui passent par le publish/subscribe protocole pris en charge par le[Protocoles de communication des appareils](protocols.md). [Vous pouvez également utiliser la fonction [Basic Ingest](iot-basic-ingest.md) pour envoyer en toute sécurité les données de l'appareil aux adresses Services AWS répertoriées précédemment, sans frais de messagerie.](https://aws.amazon.com/iot-core/pricing/) La fonction [d'ingestion de base](iot-basic-ingest.md) optimise le flux de données en supprimant le courtier de publish/subscribe messages du chemin d'ingestion. Cela le rend rentable tout en conservant les fonctionnalités de sécurité et de traitement des données de AWS IoT.
Avant de AWS IoT pouvoir effectuer ces actions, vous devez lui accorder l'autorisation d'accéder à vos AWS ressources en votre nom. Lorsque les actions sont effectuées, vous devez payer les frais standard pour celles Services AWS que vous utilisez.
**Topics**
+ [Accorder à une AWS IoT règle l'accès dont elle a besoin](iot-create-role.md)
+ [Transmission des autorisations de rôle](pass-role.md)
+ [Création d'une AWS IoT règle](iot-create-rule.md)
+ [Gérer une AWS IoT règle](iot-managae-rule.md)
+ [AWS IoT actions liées aux règles](iot-rule-actions.md)
+ [Résolution des problèmes d'une règle](#iot-troubleshoot-rule)
+ [Accès aux ressources entre comptes à l'aide AWS IoT de règles](accessing-cross-account-resources-using-rules.md)
+ [Gestion des erreurs (action d'erreur)](rule-error-handling.md)
+ [Réduction des coûts de messagerie avec Basic Ingest](iot-basic-ingest.md)
+ [AWS IoT Référence SQL](iot-sql-reference.md)
# Accorder à une AWS IoT règle l'accès dont elle a besoin
Utilisez les rôles IAM pour contrôler les AWS ressources auxquelles chaque règle a accès. Avant de créer une règle, vous devez créer un rôle IAM avec une politique qui autorise l'accès aux AWS ressources requises. AWS IoT assume ce rôle lors de la mise en œuvre d'une règle.
**Procédez comme suit pour créer le rôle et la AWS IoT politique IAM qui accordent à une AWS IoT règle l'accès dont elle a besoin (AWS CLI).**
1. Enregistrez le document de politique de confiance suivant, qui accorde AWS IoT l'autorisation d'assumer le rôle, dans un fichier nommé`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"
}
}
}
]
}
```
Utilisez la commande [create-role](https://docs.aws.amazon.com/cli/latest/reference/iam/create-role.html) pour créer un rôle IAM spécifiant le fichier `iot-role-trust.json` :
```
aws iam create-role --role-name my-iot-role --assume-role-policy-document file://iot-role-trust.json
```
La sortie de cette commande ressemble à ce qui suit :
```
{
"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. Enregistrez le code JSON suivant dans un fichier nommé `my-iot-policy.json`.
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "dynamodb:*",
"Resource": "*"
}
]
}
```
Ce JSON est un exemple de document de politique qui accorde à AWS IoT l'administrateur l'accès à DynamoDB.
Utilisez la commande [create-policy](https://docs.aws.amazon.com/cli/latest/reference/iam/create-policy.html) pour autoriser l' AWS IoT accès à vos AWS ressources lorsque vous assumez le rôle, en transmettant le `my-iot-policy.json` fichier :
```
aws iam create-policy --policy-name my-iot-policy --policy-document file://my-iot-policy.json
```
Pour plus d'informations sur la manière d'accorder l'accès à Services AWS dans les politiques pour AWS IoT, voir[Création d'une AWS IoT règle](iot-create-rule.md).
La sortie de la commande [create-policy](https://docs.aws.amazon.com/cli/latest/reference/iam/create-policy.html) contient l'ARN de la stratégie. Attacher la politique à un rôle.
```
{
"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. Utilisez la [attach-role-policy](https://docs.aws.amazon.com/cli/latest/reference/iam/attach-role-policy.html)commande pour associer votre politique à votre rôle :
```
aws iam attach-role-policy --role-name my-iot-role --policy-arn "arn:aws:iam::123456789012:policy/my-iot-policy"
```
## Révoquer l'accès au moteur de règles
Pour révoquer immédiatement l'accès au moteur de règles, procédez comme suit
1. [Supprimer iot.amazonaws.com de la politique de confiance](https://docs.aws.amazon.com/iot/latest/developerguide/iot-create-role.html)
1. Suivez les étapes pour [révoquer les sessions IoT Role](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use_revoke-sessions.html)
# Transmission des autorisations de rôle
Une définition de règle comporte un rôle IAM qui accorde l'autorisation d'accéder aux ressources spécifiées dans l'action de la règle. Le moteur de règles assume ce rôle lorsque l'action de la règle est invoquée.. Le rôle doit être défini de la même manière Compte AWS que la règle.
Lorsque vous créez ou remplacez une règle, vous transférez en fait un rôle au moteur de règles. L’`iam:PassRole`autorisation est requise pour effectuer cette opération. Pour vous assurer que vous disposez de cette autorisation, créez une politique qui accorde `iam:PassRole` l'autorisation et attachez-la à votre utilisateur IAM. La stratégie suivante montre comment accorder l'autorisation `iam:PassRole` pour un rôle.
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "Stmt1",
"Effect": "Allow",
"Action": [
"iam:PassRole"
],
"Resource": [
"arn:aws:iam::123456789012:role/myRole"
]
}
]
}
```
Dans cet exemple de politique, `iam:PassRole` l'autorisation est accordée pour le rôle `myRole`. Le rôle a été spécifié à l'aide de son ARN. Attacher cette politique à votre utilisateur IAM ou au rôle auquel appartient votre utilisateur. Pour plus d'informations, consultez [Utilisation des politiques gérées](https://docs.aws.amazon.com/service-authorization/latest/reference/access_policies_managed-using.html).
**Note**
Les fonctions Lambda utilisent des politiques basées sur des ressources, où la politique est attachée directement à la fonction Lambda. Lorsque vous créez une règle qui appelle une fonction Lambda, vous ne transmettez pas de rôle, et l'utilisateur qui crée la règle n'a donc pas besoin de `iam:PassRole` l'autorisation. Pour plus d'informations sur l'autorisation de fonctions , consultez [Octroi de permissions à l'aide d'une politique de ressources](https://docs.aws.amazon.com/lambda/latest/dg/intro-permission-model.html#intro-permission-model-access-policy).
# Création d'une AWS IoT règle
Vous pouvez créer des AWS IoT règles pour acheminer les données de vos objets connectés afin d'interagir avec d'autres AWS services. Une AWS IoT règle comprend les éléments suivants :
**Composantes d'une règle**
| Composant | Description | Obligatoire ou facultatif |
| --- | --- | --- |
| Nom de la règle | Le nom de la règle . Notez que nous ne recommandons pas l'utilisation d'informations personnellement identifiables dans les noms de vos règles. | Obligatoire. |
| Description de la règle | Description textuelle de la règle. Notez que nous ne recommandons pas l'utilisation d'informations personnellement identifiables dans les descriptions de vos règles. | Facultatif. |
| Instruction SQL | Syntaxe SQL simplifiée pour filtrer les messages reçus dans une rubrique MQTT et pousser les données ailleurs. Pour de plus amples informations, veuillez consulter [AWS IoT Référence SQL](iot-sql-reference.md). | Obligatoire. |
| Version de SQL | Version du moteur de règles SQL à utiliser lors de l'évaluation de la règle. Bien que cette propriété soit facultative, nous vous recommandons vivement de spécifier la version SQL. La AWS IoT Core console définit cette propriété sur `2016-03-23` par défaut. Si cette propriété n'est pas définie, par exemple dans une AWS CLI commande ou un CloudFormation modèle, elle `2015-10-08` est utilisée. Pour de plus amples informations, veuillez consulter [Versions de SQL](iot-rule-sql-version.md). | Obligatoire. |
| Une ou plusieurs actions | Les actions sont effectuées AWS IoT lors de la mise en œuvre de la règle. Par exemple, vous pouvez insérer des données dans un tableau DynamoDB, écrire des données dans un compartiment Amazon S3, publier dans une rubrique Amazon SNS ou appeler une fonction Lambda. | Obligatoire. |
| Une action d'erreur | L'action est AWS IoT exécutée lorsqu'elle n'est pas en mesure d'exécuter l'action d'une règle. | Facultatif. |
Avant de créer une AWS IoT règle, vous devez créer un rôle IAM avec une politique qui autorise l'accès aux AWS ressources requises. AWS IoT assume ce rôle lors de la mise en œuvre d'une règle. Pour plus d'informations, consultez les sections [Accorder à une AWS IoT règle l'accès dont elle a besoin](https://docs.aws.amazon.com//iot/latest/developerguide/iot-create-role.html) et [Transmission des autorisations de rôle](https://docs.aws.amazon.com//iot/latest/developerguide/pass-role.html).
Lorsque vous créez une règle, soyez conscient de la quantité de données que vous publiez sur les sujets. Si vous créez des règles qui incluent un modèle de sujet générique, elles peuvent correspondre à un pourcentage important de vos messages. Dans ce cas, vous devrez peut-être augmenter la capacité des AWS ressources utilisées par les actions cibles. Nous recommandons d'éviter les modèles de sujets génériques dans les règles de republication afin d'éviter le double traitement et de réduire les coûts.
**Note**
La création et la mise à jour de règles sont des actions de niveau administrateur. Tout utilisateur détenant des autorisations de création ou de mise à jour de règles peut accéder aux données traitées par les règles.
## Création d'une règle (console)
**Pour créer une règle (AWS Management Console)**
Utilisez la [AWS Management Console](https://console.aws.amazon.com//iot/home#/home)commande pour créer une règle :
1. Ouvrez la [AWS IoT console](https://console.aws.amazon.com//iot/home#/home).
1. Dans le volet de navigation de gauche, choisissez **Routage des messages** dans la section **Gérer**. Choisissez ensuite **Règles**.
1. Sur la page **Règles**, choisissez **Créer une règle**.
1. Sur la page **Spécifier les propriétés de la règle**, entrez le nom de votre règle. **La description des règles** et les **balises** sont facultatives. Choisissez **Suivant**.
1. Sur la page **Configurer l'instruction SQL**, choisissez une version SQL et entrez une instruction SQL. Un exemple d'instruction SQL peut être`SELECT temperature FROM 'iot/topic' WHERE temperature > 50`. Pour plus d'informations, voir [Versions SQL](https://docs.aws.amazon.com//iot/latest/developerguide/iot-rule-sql-version.html) et [références AWS IoT SQL](https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-reference.html).
1. Sur la page **Joindre des actions de règle**, ajoutez des actions de règle pour acheminer les données vers d'autres AWS services.
1. Dans **Actions de règle**, sélectionnez une action de règle dans la liste déroulante. Par exemple, vous pouvez choisir **Kinesis** Stream. Pour plus d'informations sur les actions des règles, consultez la section [Actions des AWS IoT règles](https://docs.aws.amazon.com//iot/latest/developerguide/iot-rule-actions.html).
1. En fonction de l'action de règle que vous choisissez, entrez les détails de configuration associés. Par exemple, si vous choisissez **Kinesis Stream**, vous devrez choisir ou créer une ressource de flux de données, et éventuellement saisir les détails de configuration tels que la **clé de partition**, qui est utilisée pour regrouper les données par partition dans un Steam.
1. Dans le **rôle IAM**, choisissez ou créez un rôle pour accorder l' AWS IoT accès à votre point de terminaison. Notez que cela AWS IoT créera automatiquement une politique avec le préfixe « `aws-iot-rule` sous le rôle IAM sélectionné ». Vous pouvez choisir **Afficher** pour afficher votre rôle IAM et la politique depuis la console IAM. **L'action en cas d'erreur** est facultative. Vous trouverez plus d'informations dans [Gestion des erreurs (action en cas d'erreur)](https://docs.aws.amazon.com//iot/latest/developerguide/rule-error-handling.html). Pour plus d'informations sur la création d'un rôle IAM pour votre règle, voir [Accorder à une règle l'accès dont elle a besoin](https://docs.aws.amazon.com//iot/latest/developerguide/iot-create-role.html). Choisissez **Suivant**.
1. Sur la page **Réviser et créer**, passez en revue l'ensemble de la configuration et apportez des modifications si nécessaire. Choisissez **Créer**.
Une fois que vous avez créé une règle avec succès, elle apparaît sur la page **Règles**. Vous pouvez sélectionner une règle pour ouvrir la page **Détails** où vous pouvez afficher une règle, modifier une règle, désactiver une règle et supprimer une règle.
## Création d'une règle (CLI)
**Pour créer une règle (AWS CLI)**
Utilisez la [create-topic-rule](https://docs.aws.amazon.com/cli/latest/reference/iot/create-topic-rule.html)commande pour créer une règle :
```
aws iot create-topic-rule --rule-name myrule --topic-rule-payload file://myrule.json
```
Voici un exemple de fichier de charge utile avec une règle qui insère tous les messages envoyés à la `iot/test` rubrique dans le tableau DynamoDB spécifiée. L'instruction SQL filtre les messages et le rôle ARN AWS IoT autorise l'écriture dans la table 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()}"
}
}
]
}
```
Voici un exemple de fichier de charge utile avec une règle qui insère tous les messages envoyés à la rubrique `iot/test` dans le compartiment S3 spécifié. L'instruction SQL filtre les messages, et l'ARN du rôle accorde AWS IoT l'autorisation d'écrire dans le compartiment 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"
}
}
]
}
```
Voici un exemple de fichier de charge utile avec une règle qui envoie des données vers 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()}"
}
}
]
}
```
Voici un exemple de fichier de charge avec une règle qui appelle une fonction Lambda :
```
{
"sql": "expression",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"lambda": {
"functionArn": "arn:aws:lambda:us-west-2:123456789012:function:my-lambda-function"
}
}
]
}
```
Voici un exemple de fichier de charge utile avec une règle qui publie dans une rubrique Amazon SNS :
```
{
"sql": "expression",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"sns": {
"targetArn": "arn:aws:sns:us-west-2:123456789012:my-sns-topic",
"roleArn": "arn:aws:iam::123456789012:role/my-iot-role"
}
}
]
}
```
Voici un exemple de fichier de charge utile avec une règle qui permet de republier dans une autre rubrique MQTT :
```
{
"sql": "expression",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"republish": {
"topic": "my-mqtt-topic",
"roleArn": "arn:aws:iam::123456789012:role/my-iot-role"
}
}
]
}
```
Voici un exemple de fichier de charge utile avec une règle qui envoie des données vers un flux 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"
}
}
]
}
```
Voici un exemple de fichier de charge utile avec une règle qui utilise la `machinelearning_predict` fonction Amazon SageMaker AI pour republier dans une rubrique si les données de la charge utile MQTT sont classées comme 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"
}
}
]
}
```
Voici un exemple de fichier de charge utile assorti d'une règle qui publie des messages dans un flux d'entrée 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"
}
}
]
}
```
L'exemple suivant illustre un fichier de charge utile avec une règle lançant l'exécution d'une machine d'état 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"
}
}
]
}
```
# Gérer une AWS IoT règle
Vous pouvez utiliser les actions suivantes pour gérer vos AWS IoT règles.
**Topics**
+ [Marquer une règle](#iot-create-rule-tagging)
+ [Afficher une règle](#iot-view-rules)
+ [Suppression d'une règle](#iot-delete-rule)
## Marquer une règle
Pour ajouter un niveau de spécificité à vos règles nouvelles ou existantes, vous pouvez appliquer le balisage. Le balisage utilise des paires clé-valeur dans vos règles pour vous permettre de mieux contrôler comment et où vos règles sont appliquées à vos AWS IoT ressources et services. Par exemple, vous pouvez limiter le champ d'application de votre règle pour qu'elle s'applique uniquement à votre environnement bêta pour les tests préliminaires (`Key=environment, Value=beta`) ou pour capturer tous les messages envoyés au `iot/test` sujet depuis un point de terminaison spécifique uniquement et les stocker dans un compartiment Amazon S3.
### Exemple de politique IAM
Pour un exemple qui montre comment accorder des autorisations de balisage pour une règle, imaginez un utilisateur qui exécute la commande suivante pour créer une règle et la baliser afin qu'elle ne s'applique qu'à son environnement bêta.
Dans l'exemple, remplacez :
+ *MyTopicRuleName*avec le nom de la règle.
+ *myrule.json*avec le nom du document de politique.
```
aws iot create-topic-rule
--rule-name MyTopicRuleName
--topic-rule-payload file://myrule.json
--tags "environment=beta"
```
Pour cet exemple, vous devez utiliser la politique IAM suivante :
****
```
{
"Version":"2012-10-17",
"Statement":
{
"Action": [ "iot:CreateTopicRule", "iot:TagResource" ],
"Effect": "Allow",
"Resource": [
"arn:aws:iot:us-east-1:123456789012:rule/MyTopicRuleName"
]
}
}
```
L'exemple ci-dessus montre une nouvelle règle appelée `MyTopicRuleName` qui s'applique uniquement à votre environnement bêta. La `iot:TagResource` dans la déclaration de politique avec `MyTopicRuleName` spécifiquement appelé permet le marquage lors de la création ou de la mise à jour `MyTopicRuleName`. Le paramètre `--tags "environment=beta"` utilisé lors de la création de la règle limite le champ d'application `MyTopicRuleName` à votre environnement bêta uniquement. Si vous supprimez le paramètre `--tags "environment=beta"`, ensuite `MyTopicRuleName` s'appliquera à tous les environnements.
Pour plus d'informations sur la création de rôles et de politiques IAM spécifiques à une AWS IoT règle, voir [Accorder à une AWS IoT règle l'accès dont elle a besoin](iot-create-role.md)
Pour obtenir des informations générales sur le balisage des ressources, veuillez consulter . [Marquer vos ressources AWS IoT](tagging-iot.md).
## Afficher une règle
Utilisez la [list-topic-rules](https://docs.aws.amazon.com/cli/latest/reference/iot/list-topic-rules.html)commande pour répertorier vos règles :
```
aws iot list-topic-rules
```
Utilisez la [get-topic-rule](https://docs.aws.amazon.com/cli/latest/reference/iot/get-topic-rule.html)commande pour obtenir des informations sur une règle :
```
aws iot get-topic-rule --rule-name myrule
```
## Suppression d'une règle
Lorsque vous avez terminé avec une règle, vous pouvez la supprimer.
**Pour supprimer une règle (AWS CLI)**
Utilisez la [delete-topic-rule](https://docs.aws.amazon.com/cli/latest/reference/iot/delete-topic-rule.html)commande pour supprimer une règle :
```
aws iot delete-topic-rule --rule-name myrule
```
# AWS IoT actions liées aux règles
AWS IoT les actions de règle spécifient ce qu'il faut faire lorsqu'une règle est invoquée. Vous pouvez définir des actions pour envoyer des données vers une base de données Amazon DynamoDB, envoyer des données vers Amazon Kinesis Data Streams, AWS Lambda invoquer une fonction, etc. AWS IoT prend en charge les actions suivantes Régions AWS lorsque le service de l'action est disponible.
| Action de règle | Description | Nom dans l'API |
| --- | --- | --- |
| [Apache Kafka](apache-kafka-rule-action.md) | Envoie un message à un cluster Apache Kafka. | kafka |
| [CloudWatch alarmes](cloudwatch-alarms-rule-action.md) | Modifie l'état d'une CloudWatch alarme Amazon. | cloudwatchAlarm |
| [CloudWatch Journaux](cloudwatch-logs-rule-action.md) | Envoie un message à Amazon CloudWatch Logs. | cloudwatchLogs |
| [CloudWatch métriques](cloudwatch-metrics-rule-action.md) | Envoie un message à une CloudWatch métrique. | cloudwatchMetric |
| [DynamoDB](dynamodb-rule-action.md) | Envoie un message à une table DynamoDB. | dynamoDB |
| [Dynamo DBv2](dynamodb-v2-rule-action.md) | Envoie les données des messages à plusieurs colonnes d'une table DynamoDB. | dynamoDBv2 |
| [Elasticsearch](elasticsearch-rule-action.md) | Envoie un message à un OpenSearch point de terminaison. | OpenSearch |
| [HTTP](https-rule-action.md) | Publie un message sur un point de terminaison HTTPS. | http |
| [AWS IoT Events](iotevents-rule-action.md) | Envoie un message à une AWS IoT Events entrée. | iotEvents |
| [AWS IoT SiteWise](iotsitewise-rule-action.md) | Envoie les données des messages aux propriétés des AWS IoT SiteWise actifs. | iotSiteWise |
| [Firehose](kinesis-firehose-rule-action.md) | Envoie un message à un flux de diffusion Firehose. | firehose |
| [Kinesis Data Streams](kinesis-rule-action.md) | Envoie un message à un flux de données Kinesis. | kinesis |
| [Lambda](lambda-rule-action.md) | Invoque une fonction Lambda avec des données de message en entrée. | lambda |
| [Location](location-rule-action.md) | Envoie les données de localisation au service de localisation d'Amazon. | location |
| [OpenSearch](opensearch-rule-action.md) | Envoie un message à un point de terminaison Amazon OpenSearch Service. | OpenSearch |
| [Republier](republish-rule-action.md) | Republie un message vers un autre sujet MQTT. | republish |
| [S3](s3-rule-action.md) | Stocke un message dans un panier Amazon Simple Storage Service (Amazon S3). | s3 |
| [IoT Salesforce](salesforce-iot-rule-action.md) | Envoie un message à un flux d'entrée Salesforce IoT. | salesforce |
| [SNS](sns-rule-action.md) | Publie un message sous la forme d'une notification push Amazon Simple Notification Service (Amazon SNS). | sns |
| [SQS](sqs-rule-action.md) | Envoie un message à une file d'attente Amazon Simple Queue Service (Amazon SQS). | sqs |
| [Step Functions](stepfunctions-rule-action.md) | Démarre une machine à AWS Step Functions états. | stepFunctions |
| [Timestream](timestream-rule-action.md) | Envoie un message à une table de base de données Amazon Timestream. | timestream |
**Remarques**
Définissez la règle de la même manière Région AWS que la ressource d'un autre service afin que l'action de la règle puisse interagir avec cette ressource.
Le moteur de AWS IoT règles peut effectuer plusieurs tentatives pour exécuter une action si des erreurs intermittentes se produisent. Si toutes les tentatives échouent, le message est ignoré et l'erreur est répertoriée dans vos CloudWatch journaux. Vous pouvez spécifier une action en cas d’erreur pour chaque règle invoquée après une défaillance. Pour de plus amples informations, veuillez consulter [Gestion des erreurs (action d'erreur)](rule-error-handling.md).
Certaines actions de règles activent des actions dans des services qui s'intègrent à AWS Key Management Service (AWS KMS) pour prendre en charge le cryptage des données au repos. Si vous utilisez une clé KMS gérée par le client AWS KMS key pour chiffrer les données au repos, le service doit être autorisé à utiliser la clé KMS au nom de l'appelant. Pour savoir comment gérer les autorisations pour votre clé KMS gérée par le client, consultez les rubriques relatives au cryptage des données dans le guide de service approprié. Pour de plus amples informations sur les clés KMS gérées par le client, consultez la section [AWS Key Management Service concepts](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html) dans le *AWS Key Management Service Guide du développeur*.
Vous pouvez utiliser n'importe quelle [fonction](iot-sql-functions.md) ou [modèle de substitution](https://docs.aws.amazon.com//iot/latest/developerguide/iot-substitution-templates.html) dans l'instruction SQL d'une action d'erreur, y compris les fonctions externes : [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-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), et [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). Si une action d'erreur nécessite l'appel d'une fonction externe, l'invocation de l'action d'erreur peut entraîner une facture supplémentaire pour la fonction externe.
# Apache Kafka
L'action Apache Kafka (Kafka) envoie des messages directement à votre [Amazon Managed Streaming for Apache](https://docs.aws.amazon.com//msk/latest/developerguide/what-is-msk.html) Kafka (Amazon MSK), aux clusters Apache Kafka gérés par des fournisseurs tiers [tels que](https://www.confluent.io/) Confluent Cloud ou aux clusters Apache Kafka autogérés. Grâce à l'action des règles de Kafka, vous pouvez acheminer vos données IoT vers des clusters Kafka. Cela vous permet de créer des pipelines de données à hautes performances à diverses fins, telles que l'analyse en continu, l'intégration des données, la visualisation et les applications professionnelles critiques.
**Note**
Cette rubrique suppose une bonne connaissance de la plateforme Apache Kafka et des concepts associés. Pour de plus amples informations sur Apache Kafka, veuillez consulter [Apache Kafka](https://kafka.apache.org/). [MSK Serverless](https://docs.aws.amazon.com//msk/latest/developerguide/serverless.html) n'est pas pris en charge. Les clusters MSK Serverless ne peuvent être créés que via l'authentification IAM, que l'action des règles d'Apache Kafka ne prend pas en charge actuellement. Pour plus d'informations sur la façon de configurer AWS IoT Core avec Confluent, voir [Tirer parti de Confluent et résoudre les problèmes de gestion des appareils et des données liés AWS à l'IoT](https://aws.amazon.com/blogs/apn/leveraging-confluent-and-aws-to-solve-iot-device-and-data-management-challenges/).
## Exigences
Cette action réglementaire est assortie des exigences suivantes :
+ Rôle IAM qui AWS IoT peut assumer d'exécuter les `ec2:DescribeSecurityGroups` opérations `ec2:CreateNetworkInterface``ec2:DescribeNetworkInterfaces`,`ec2:CreateNetworkInterfacePermission`,`ec2:DeleteNetworkInterface`,`ec2:DescribeSubnets`,`ec2:DescribeVpcs`,`ec2:DescribeVpcAttribute`, et. Ce rôle crée et gère des interfaces réseau élastiques vers votre Amazon Virtual Private Cloud afin d'atteindre votre courtier Kafka. Pour de plus amples informations, veuillez consulter [Accorder à une AWS IoT règle l'accès dont elle a besoin](iot-create-role.md).
Dans la AWS IoT console, vous pouvez choisir ou créer un rôle pour autoriser l'exécution AWS IoT Core de cette action de règle.
Pour plus d'informations sur les interfaces réseau, consultez [Elastic network interfaces](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-eni.html) dans le *Guide de l'utilisateur Amazon EC2*.
La stratégie associée au rôle que vous spécifiez doit ressembler à l'exemple suivant.
****
```
{
"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": "*"
}
]
}
```
+ Si vous stockez AWS Secrets Manager les informations d'identification requises pour vous connecter à votre courtier Kafka, vous devez créer un rôle IAM AWS IoT Core capable d'effectuer les opérations `secretsmanager:GetSecretValue` et`secretsmanager:DescribeSecret`.
La stratégie associée au rôle que vous spécifiez doit ressembler à l'exemple suivant.
****
```
{
"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-*"
]
}
]
}
```
+ Vous pouvez exécuter vos clusters Apache Kafka dans Amazon Virtual Private Cloud (Amazon VPC). Vous devez créer une destination Apache Kafka Virtual Private Cloud (VPC) et utiliser une passerelle NAT dans vos sous-réseaux pour transférer les messages depuis AWS IoT un cluster Kafka public. Le moteur de AWS IoT règles crée une interface réseau dans chacun des sous-réseaux répertoriés dans la destination pour acheminer le trafic directement vers le VPC. Lorsque vous êtes à destination, le moteur de AWS IoT règles crée automatiquement une action de règle VPC. Pour plus d'informations sur les actions de règle VPC, consultez [Destinations du cloud privé virtuel (VPC) Apache Kafka](kafka-vpc-destination.md).
+ Si vous utilisez une clé KMS gérée par AWS KMS key le client pour chiffrer les données au repos, le service doit être autorisé à utiliser la clé KMS au nom de l'appelant. Pour plus d'informations, consultez [Actions Amazon MSK Kafka](https://docs.aws.amazon.com/msk/latest/developerguide/msk-encryption.html) dans le *Guide du développeur Amazon Managed Streaming for Apache Kafka*.
## Parameters
Lorsque vous créez une AWS IoT règle avec cette action, vous devez spécifier les informations suivantes :
DestinationArn
Le nom de ressource Amazon (ARN) de la destination du cloud privé virtuel (VPC) Apache Kafka. Pour plus d'informations sur la création d'une destination, consultez[Destinations du cloud privé virtuel (VPC) Apache Kafka](kafka-vpc-destination.md).
topic
La rubrique Kafka pour les messages à envoyer à l'agent Kafka.
Vous pouvez remplacer ce champ à l'aide d'un modèle de substitution. Pour de plus amples informations, veuillez consulter [Modèles de substitution](iot-substitution-templates.md).
clé (facultatif)
La clé de message Kafka.
Vous pouvez remplacer ce champ à l'aide d'un modèle de substitution. Pour de plus amples informations, veuillez consulter [Modèles de substitution](iot-substitution-templates.md).
en-têtes (facultatif)
La liste des en-têtes Kafka que vous spécifiez. Chaque en-tête est une paire clé-valeur que vous pouvez spécifier lors de la création d'une action Kafka. Vous pouvez utiliser ces en-têtes pour acheminer les données des clients IoT vers les clusters Kafka en aval sans modifier la charge utile de vos messages.
Vous pouvez remplacer ce champ à l'aide d'un modèle de substitution. [Pour comprendre comment transmettre la fonction d'une règle intégrée en tant que modèle de substitution dans l'en-tête de Kafka Action, consultez les exemples.](#apache-kafka-rule-action-examples) Pour de plus amples informations, veuillez consulter [Modèles de substitution](iot-substitution-templates.md).
Les en-têtes au format binaire ne sont pas pris en charge.
partition (facultatif)
La partition de message Kafka.
Vous pouvez remplacer ce champ à l'aide d'un modèle de substitution. Pour de plus amples informations, veuillez consulter [Modèles de substitution](iot-substitution-templates.md).
ClientProperties
Un objet qui définit les propriétés du client producteur Apache Kafka.
Packs (facultatif)
Le nombre d'accusés de réception que le producteur demande au serveur de recevoir avant de considérer qu'une demande est complète.
Si vous spécifiez 0 comme valeur, le producteur n'attendra aucun accusé de réception du serveur. Si le serveur ne reçoit pas le message, le producteur ne réessaiera pas de l'envoyer.
Valeurs valides: `-1`, `0`, `1`, `all`. La valeur par défaut est `1`.
serveurs bootstrap
Liste des paires d'hôtes et de ports (par exemple`host1:port1`,`host2:port2`) utilisées pour établir la connexion initiale à votre cluster Kafka.
compression.type (facultatif)
Type de compression pour toutes les données générées par le producteur.
Valeurs valides: `none`, `gzip`, `snappy`, `lz4`, `zstd`. La valeur par défaut est `none`.
security.protocol
Le protocole de sécurité utilisé pour vous connecter à votre courtier Kafka.
Valeurs valides : `SSL`, `SASL_SSL`. La valeur par défaut est `SSL`.
key.serializer
Spécifie comment transformer en octets les objets clés que vous fournissez avec le`ProducerRecord`.
Valeur valide : `StringSerializer`.
value.serializer
Spécifie comment transformer en octets les objets de valeur que vous fournissez avec le`ProducerRecord`.
Valeur valide : `ByteBufferSerializer`.
ssl.truststore
Le fichier truststore au format base64 ou l'emplacement du fichier truststore dans. [AWS Secrets Manager](https://docs.aws.amazon.com/secretsmanager/latest/userguide/) Cette valeur n'est pas obligatoire si votre truststore est approuvé par les autorités de certification Amazon (CA).
Ce champ prend en charge les modèles de substitution. Si vous utilisez Secrets Manager pour stocker les informations d'identification requises pour vous connecter à votre broker Kafka, vous pouvez utiliser la fonction `get_secret` SQL pour récupérer la valeur de ce champ. Pour de plus amples informations sur les modèles de substitution, veuillez consulter [Modèles de substitution](iot-substitution-templates.md). Pour plus d'informations sur la `get_secret` fonction SQL, veillez consultez [get\$1secret (SecreTid, SecretType, clé, roLearn)](iot-sql-functions.md#iot-sql-function-get-secret). Si le truststore se présente sous la forme d'un fichier, utilisez le `SecretBinary` paramètre. Si le truststore se présente sous la forme d'une chaîne, utilisez le `SecretString` paramètre.
La taille maximale de cette valeur est de 65 Ko.
ssl.truststore.password
Le mot de passe du référentiel d'approbations. Cette valeur n'est requise que si vous avez créé un mot de passe pour le référentiel d'approbations.
ssl.keystore
Le fichier keystore. Cette valeur est obligatoire lorsque vous spécifiez `SSL` comme valeur pour`security.protocol`.
Ce champ prend en charge les modèles de substitution. Utilisez Secrets Manager pour stocker les informations d'identification requises pour vous connecter à votre courtier Kafka. Pour récupérer la valeur de ce champ, utilisez la fonction `get_secret` SQL. Pour de plus amples informations sur les modèles de substitution, veuillez consulter [Modèles de substitution](iot-substitution-templates.md). Pour plus d'informations sur la fonction `get_secret` SQL, consultez [get\$1secret (SecreTid, SecretType, clé, roLearn)](iot-sql-functions.md#iot-sql-function-get-secret). Utilisez le `SecretBinary` paramètre.
ssl.keystore.password
Le mot de passe du fichier keystore. Cette valeur est requise si vous spécifiez une valeur pour `ssl.keystore`.
La valeur de ce champ peut être en texte brut. Ce champ prend également en charge les modèles de substitution. Utilisez Secrets Manager pour stocker les informations d'identification requises pour vous connecter à votre courtier Kafka. Pour récupérer la valeur de ce champ, utilisez la fonction `get_secret` SQL. Pour de plus amples informations sur les modèles de substitution, veuillez consulter [Modèles de substitution](iot-substitution-templates.md). Pour plus d'informations sur la fonction `get_secret` SQL, consultez [get\$1secret (SecreTid, SecretType, clé, roLearn)](iot-sql-functions.md#iot-sql-function-get-secret). Utilisez le `SecretString` paramètre.
clé ssl.mot de passe
Le mot de passe de la clé privée dans votre fichier keystore.
Ce champ prend en charge les modèles de substitution. Utilisez Secrets Manager pour stocker les informations d'identification requises pour vous connecter à votre courtier Kafka. Pour récupérer la valeur de ce champ, utilisez la fonction `get_secret` SQL. Pour de plus amples informations sur les modèles de substitution, veuillez consulter [Modèles de substitution](iot-substitution-templates.md). Pour plus d'informations sur la fonction `get_secret` SQL, consultez [get\$1secret (SecreTid, SecretType, clé, roLearn)](iot-sql-functions.md#iot-sql-function-get-secret). Utilisez le `SecretString` paramètre.
sasl.mechanism
Le mécanisme de sécurité utilisé pour se connecter à votre courtier Kafka. Cette valeur est obligatoire lorsque vous spécifiez `SASL_SSL` pour`security.protocol`.
Valeurs valides : `PLAIN`, `SCRAM-SHA-512`, `GSSAPI`.
`SCRAM-SHA-512`est le seul mécanisme de sécurité pris en charge dans les régions cn-north-1, cn-northwest-1, -1 et -1. us-gov-east us-gov-west
sasl.plain.username
Le nom d'utilisateur utilisé pour récupérer la chaîne secrète depuis Secrets Manager. Cette valeur est obligatoire lorsque vous spécifiez `SASL_SSL` pour `security.protocol` et `PLAIN` pour `sasl.mechanism`.
sasl.plain.password
Mot de passe utilisé pour récupérer la chaîne secrète depuis Secrets Manager. Cette valeur est obligatoire lorsque vous spécifiez `SASL_SSL` pour `security.protocol` et `PLAIN` pour `sasl.mechanism`.
sasl.scram.nom d'utilisateur
Le nom d'utilisateur utilisé pour récupérer la chaîne secrète depuis Secrets Manager. Cette valeur est obligatoire lorsque vous spécifiez `SASL_SSL` pour `security.protocol` et `SCRAM-SHA-512` pour `sasl.mechanism`.
sasl.scram.password
Mot de passe utilisé pour récupérer la chaîne secrète depuis Secrets Manager. Cette valeur est obligatoire lorsque vous spécifiez `SASL_SSL` pour `security.protocol` et `SCRAM-SHA-512` pour`sasl.mechanism`.
sasl.kerberos.keytab
Le fichier keytab pour l'authentification Kerberos dans Secrets Manager. Cette valeur est obligatoire lorsque vous spécifiez `SASL_SSL` pour `security.protocol` et `GSSAPI` pour`sasl.mechanism`.
Ce champ prend en charge les modèles de substitution. Utilisez Secrets Manager pour stocker les informations d'identification requises pour vous connecter à votre courtier Kafka. Pour récupérer la valeur de ce champ, utilisez la fonction `get_secret` SQL. Pour de plus amples informations sur les modèles de substitution, veuillez consulter [Modèles de substitution](iot-substitution-templates.md). Pour plus d'informations sur la fonction `get_secret` SQL, consultez [get\$1secret (SecreTid, SecretType, clé, roLearn)](iot-sql-functions.md#iot-sql-function-get-secret). Utilisez le `SecretBinary` paramètre.
sasl.kerberos.service.name
Nom principal Kerberos sous lequel Apache Kafka s'exécute. Cette valeur est obligatoire lorsque vous spécifiez `SASL_SSL` pour `security.protocol` et `GSSAPI` pour `sasl.mechanism`.
sasl.kerberos.krb5.kdc
Le nom d'hôte du centre de distribution de clés (KDC) auquel votre client producteur Apache Kafka se connecte. Cette valeur est obligatoire lorsque vous spécifiez `SASL_SSL` pour `security.protocol` et `GSSAPI` pour `sasl.mechanism`.
sasl.kerberos.krb5.realm
Domaine auquel votre client producteur Apache Kafka se connecte. Cette valeur est obligatoire lorsque vous spécifiez `SASL_SSL` pour `security.protocol` et `GSSAPI` pour `sasl.mechanism`.
sasl.kerberos.principal
Identité Kerberos unique à laquelle Kerberos peut attribuer des tickets pour accéder aux services compatibles Kerberos. Cette valeur est obligatoire lorsque vous spécifiez `SASL_SSL` pour `security.protocol` et `GSSAPI` pour `sasl.mechanism`.
## Exemples
L'exemple JSON suivant définit une action Apache Kafka dans une AWS IoT règle. L'exemple suivant transmet la fonction en ligne [SourceIP ()](iot-sql-functions.md#iot-function-sourceip) comme [modèle de substitution](https://docs.aws.amazon.com//iot/latest/developerguide/iot-substitution-templates.html) dans l'en-tête 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()}"
}
]
}
}
]
}
}
```
**Remarques importantes concernant votre configuration Kerberos**
+ Votre centre de distribution de clés (KDC) doit pouvoir être résolu via un système de noms de domaine (DNS) privé au sein de votre VPC cible. Une approche possible consiste à ajouter l'entrée DNS du KDC à une zone hébergée privée. Pour plus d'informations sur cette approche, veuillez consulter [Utilisation des zones hébergées privées](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/hosted-zones-private.html).
+ Chaque VPC doit avoir la résolution DNS activée. Pour plus d'informations, consultez [Utilisation de DNS avec votre VPC](https://docs.aws.amazon.com/vpc/latest/userguide/vpc-dns.html).
+ Les groupes de sécurité de l'interface réseau et les groupes de sécurité au niveau de l'instance de destination du VPC doivent autoriser le trafic provenant de votre VPC sur les ports suivants.
+ Trafic TCP sur le port d'écoute du broker bootstrap (souvent 9092, mais doit être compris entre 9000 et 9100)
+ Trafic TCP et UDP sur le port 88 pour le KDC
+ `SCRAM-SHA-512`est le seul mécanisme de sécurité pris en charge dans les régions cn-north-1, cn-northwest-1, -1 et -1. us-gov-east us-gov-west
# Destinations du cloud privé virtuel (VPC) Apache Kafka
L'action Apache Kafka achemine les données vers un cluster Apache Kafka dans un Amazon Virtual Private Cloud (Amazon VPC). La configuration VPC utilisée par l'action de règle Apache Kafka est automatiquement activée lorsque vous spécifiez la destination VPC pour votre action de règle.
Une destination Virtual Private Cloud (VPC) d'Apache Kafka contient une liste de sous-réseaux au sein du VPC. Le moteur de règles crée une interface Elastic Network dans chaque sous-réseau que vous spécifiez dans cette liste. Pour plus d'informations sur les interfaces réseau, consultez [Elastic network interfaces](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-eni.html) dans le Guide de l'utilisateur Amazon EC2.
## Exigences et considérations
+ Si vous utilisez un cluster Apache Kafka autogéré accessible via un point de terminaison public sur Internet :
+ Créez une passerelle NAT pour les instances de vos sous-réseaux. La passerelle NAT possède une adresse IP publique qui peut se connecter à Internet, ce qui permet au moteur de règles de transférer vos messages au cluster Kafka public.
+ Allouez une adresse IP élastique avec les interfaces réseau élastiques (ENIs) créées par la destination Virtual Private Cloud (VPC) d'Apache Kafka. Les groupes de sécurité que vous utilisez doivent être configurés pour bloquer le trafic entrant.
**Note**
Si la destination Virtual Private Cloud (VPC) d'Apache Kafka est désactivée puis réactivée, vous devez réassocier l'Elastic à la nouvelle destination. IPs ENIs
+ Si une destination Apache Kafka Virtual Private Cloud (VPC) ne reçoit aucun trafic pendant 30 jours consécutifs, elle sera désactivée.
+ Si l'une des ressources utilisées par la destination VPC (Virtual Private Cloud) d'Apache Kafka change, la destination sera désactivée et ne pourra pas être utilisée.
+ Parmi les modifications susceptibles de désactiver une destination VPC (Virtual Private Cloud) Apache Kafka, citons :
+ Suppression du VPC, des sous-réseaux, des groupes de sécurité ou du rôle utilisé.
+ Modifier le rôle pour ne plus disposer des autorisations nécessaires.
+ Nous atteignons presque la capacité du sous-réseau, ce qui nous empêche d'appliquer les correctifs [FedRAMP.](https://aws.amazon.com/compliance/fedramp/)
+ Désactivation de la destination.
## Tarification
À des fins de tarification, une action de règle VPC est mesurée en plus de l'action qui envoie un message à une ressource lorsque celle-ci se trouve dans votre VPC. Pour en savoir plus sur la tarification, consultez [Tarification AWS IoT Core](https://aws.amazon.com/iot-core/pricing/).
## Création de destinations pour le cloud privé virtuel (VPC) Apache Kafka
Vous créez une destination Apache Kafka Virtual Private Cloud (VPC) à l'aide de l'API ou de la [CreateTopicRuleDestination](https://docs.aws.amazon.com/iot/latest/apireference/API_CreateTopicRuleDestination.html)console. AWS IoT Core
Lorsque vous créez une destination, vous devez spécifier les informations suivantes.
vpcId
L'ID unique de l'Amazon VPC.
subnetIds
Liste de sous-réseaux dans lesquels le moteur de règles crée des interfaces réseau élastiques. Le moteur de règles alloue une interface réseau unique pour chaque sous-réseau de la liste.
SecurityGroups (facultatif)
Liste de groupes de sécurité à appliquer aux interfaces réseau.
roleArn
L'Amazon Resource Name (ARN) d'un rôle qui est autorisé à créer des interfaces réseau en votre nom.
Cet ARN doit être associé à une stratégie qui ressemble à l'exemple suivant.
****
```
{
"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"
}
}
}
]
}
```
### Création d'une destination VPC (Virtual Private Cloud) Apache Kafka à l'aide de AWS CLI
L'exemple suivant montre comment créer une destination à l'aide de AWS CLI.
```
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"}'
```
Après avoir exécuté cette commande, le statut de destination sera`IN_PROGRESS`. Après quelques minutes, son statut passera à `ERROR` (si la commande échoue) ou `ENABLED`. Lorsque le statut de destination est `ENABLED` défini, il est prêt à être utilisé.
Vous pouvez utiliser la commande suivante pour obtenir le statut de votre destination Apache Kafka Virtual Private Cloud (VPC).
```
aws --region region iot get-topic-rule-destination --arn "VPCDestinationARN"
```
### Création d'une destination VPC (Virtual Private Cloud) Apache Kafka à l'aide de la console AWS IoT Core
Les étapes suivantes décrivent comment créer une destination à l'aide de la AWS IoT Core console.
1. Accédez à la AWS IoT Core console. Dans le volet de gauche, sous l'onglet **Agir**, sélectionnez **Destinations**.
1. Saisissez des valeurs pour les champs suivants.
+ **ID du VPC**
+ **Sous-réseau IDs**
+ **Security Group**
1. Sélectionnez un rôle qui dispose des autorisations nécessaires pour créer des interfaces réseau. L'exemple de politique précédent contient ces autorisations.
Lorsque le statut de destination d'Apache Kafka Virtual Private Cloud (VPC) est **ACTIVÉ**, il est prêt à être utilisé.
# CloudWatch alarmes
L'action CloudWatch alarm (`cloudWatchAlarm`) modifie l'état d'une CloudWatch alarme Amazon. Vous pouvez spécifier la raison du changement d'état et la valeur dans cet appel.
## Exigences
Cette action réglementaire est assortie des exigences suivantes :
+ Rôle IAM qui AWS IoT peut assumer la réalisation de l'`cloudwatch:SetAlarmState`opération. Pour de plus amples informations, veuillez consulter [Accorder à une AWS IoT règle l'accès dont elle a besoin](iot-create-role.md).
Dans la AWS IoT console, vous pouvez choisir ou créer un rôle pour autoriser l'exécution AWS IoT de cette action de règle.
## Parameters
Lorsque vous créez une AWS IoT règle avec cette action, vous devez spécifier les informations suivantes :
`alarmName`
Le nom de l' CloudWatch alarme.
Supporte les [modèles de substitution](iot-substitution-templates.md) : API et AWS CLI uniquement
`stateReason`
Raisons de la modification de l'alarme.
Prend en charge [modèles de substitution](iot-substitution-templates.md) : Non
`stateValue`
Valeur de l'état de l'alarme. Valeurs valides : `OK`, `ALARM`, `INSUFFICIENT_DATA`.
Prend en charge les [modèles de substitution](iot-substitution-templates.md) : Oui
`roleArn`
Rôle IAM qui permet d'accéder à l' CloudWatch alarme. Pour de plus amples informations, veuillez consulter [Exigences](#cloudwatch-alarms-rule-action-requirements).
Prend en charge les [modèles de substitution](iot-substitution-templates.md) : Non
## Exemples
L'exemple JSON suivant définit une action d' CloudWatch alarme dans une AWS IoT règle.
```
{
"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"
}
}
]
}
}
```
## Consultez aussi
+ [Qu'est-ce qu'Amazon CloudWatch ?](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/) dans le *guide de CloudWatch l'utilisateur Amazon*
+ [Utilisation des CloudWatch alarmes Amazon](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/AlarmThatSendsEmail.html) dans le *guide de CloudWatch l'utilisateur Amazon*
# CloudWatch Journaux
L'action CloudWatch Logs (`cloudwatchLogs`) envoie des données à Amazon CloudWatch Logs. Vous pouvez l'utiliser `batchMode` pour télécharger et horodater plusieurs enregistrements du journal de l'appareil dans un seul message. Vous pouvez spécifier le groupe de journaux auquel l'action envoie des données.
## Exigences
Cette action réglementaire est assortie des exigences suivantes :
+ Rôle IAM qui AWS IoT peut assumer d'exécuter les `logs:PutLogEvents` opérations `logs:CreateLogStream``logs:DescribeLogStreams`, et. Pour de plus amples informations, veuillez consulter [Accorder à une AWS IoT règle l'accès dont elle a besoin](iot-create-role.md).
Dans la AWS IoT console, vous pouvez choisir ou créer un rôle pour autoriser l'exécution AWS IoT de cette action de règle.
+ Si vous utilisez une clé KMS gérée par AWS KMS key le client pour chiffrer les données du journal dans CloudWatch Logs, le service doit être autorisé à utiliser la clé KMS au nom de l'appelant. Pour plus d'informations, consultez la section [Chiffrer les données des CloudWatch journaux dans les journaux à l'aide AWS KMS](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/encrypt-log-data-kms.html) du *guide de l'utilisateur Amazon CloudWatch Logs*.
## Exigences relatives au format de message MQTT pour `batchMode`
Si vous utilisez l'action Règle CloudWatch Logs en `batchMode` désactivant, aucune exigence de formatage des messages MQTT n'est requise. (Remarque : la valeur par défaut du paramètre `batchMode` est `false`.) Toutefois, si vous utilisez l'action Règle CloudWatch Logs en activant `batchMode` (la valeur du paramètre est`true`), les messages MQTT contenant des journaux côté appareil doivent être formatés pour contenir un horodatage et une charge utile de message. **Remarque:** `timestamp` représente l’heure à laquelle l'événement s'est produit, exprimée en nombre de millisecondes après le 1er janvier 1970 00:00:00 UTC.
Voici un exemple de format de publication :
```
[
{"timestamp": 1673520691093, "message": "Test message 1"},
{"timestamp": 1673520692879, "message": "Test message 2"},
{"timestamp": 1673520693442, "message": "Test message 3"}
]
```
Selon la façon dont les journaux côté appareil sont générés, il peut être nécessaire de les filtrer et de les reformater avant d'être envoyés afin de respecter cette exigence. Pour plus d'informations, consultez [MQTT Message payload](https://docs.aws.amazon.com/iot/latest/developerguide/topicdata.html)
Quel que soit le `batchMode` paramètre, `message` le contenu doit respecter les limites de taille des AWS IoT messages. Pour plus d’informations, consultez [Points de terminaison et quotas AWS IoT Core](https://docs.aws.amazon.com/general/latest/gr/iot-core.html).
## Parameters
Lorsque vous créez une AWS IoT règle avec cette action, vous devez spécifier les informations suivantes :
`logGroupName`
Le groupe de CloudWatch journaux dans lequel l'action envoie des données.
Supporte les [modèles de substitution](iot-substitution-templates.md) : API et AWS CLI uniquement
`roleArn`
Rôle IAM qui autorise l'accès au groupe de CloudWatch journaux. Pour de plus amples informations, veuillez consulter [Exigences](#cloudwatch-logs-rule-action-requirements).
Prend en charge les [modèles de substitution](iot-substitution-templates.md) : Non
(facultatif) `batchMode`
Indique si des lots d'enregistrements de journal seront extraits et chargés dans CloudWatch. Les valeurs incluent `true` ou `false` (par défaut). Pour de plus amples informations, veuillez consulter [Exigences](#cloudwatch-logs-rule-action-requirements).
Prend en charge les [modèles de substitution](iot-substitution-templates.md) : Non
## Exemples
L'exemple JSON suivant définit une action CloudWatch Logs dans une AWS IoT règle.
```
{
"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
}
}
]
}
}
```
## Consultez aussi
+ [Qu'est-ce qu'Amazon CloudWatch Logs ?](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/) dans le *guide de l'utilisateur d'Amazon CloudWatch Logs*
# CloudWatch métriques
L'action CloudWatch metric (`cloudwatchMetric`) capture une CloudWatch métrique Amazon. Vous pouvez spécifier le namespace, le nom, la valeur, l'unité et l'horodatage de la métrique.
## Exigences
Cette action réglementaire est assortie des exigences suivantes :
+ Rôle IAM qui AWS IoT peut assumer la réalisation de l'`cloudwatch:PutMetricData`opération. Pour de plus amples informations, veuillez consulter [Accorder à une AWS IoT règle l'accès dont elle a besoin](iot-create-role.md).
Dans la AWS IoT console, vous pouvez choisir ou créer un rôle pour autoriser l'exécution AWS IoT de cette action de règle.
## Parameters
Lorsque vous créez une AWS IoT règle avec cette action, vous devez spécifier les informations suivantes :
`metricName`
Le nom CloudWatch de la métrique.
Prend en charge les [modèles de substitution](iot-substitution-templates.md) : Oui
`metricNamespace`
Le nom de l'espace de noms de la CloudWatch métrique.
Prend en charge les [modèles de substitution](iot-substitution-templates.md) : Oui
`metricUnit`
L'unité métrique prise en charge par CloudWatch.
Prend en charge les [modèles de substitution](iot-substitution-templates.md) : Oui
`metricValue`
Chaîne contenant la valeur de la CloudWatch métrique.
Prend en charge les [modèles de substitution](iot-substitution-templates.md) : Oui
`metricTimestamp`
(Facultatif) Chaîne de caractères contenant l'horodatage, exprimé en secondes dans l'heure Unix. La valeur par défaut est l'époque Unix actuelle.
Prend en charge les [modèles de substitution](iot-substitution-templates.md) : Non
`roleArn`
Rôle IAM qui permet d'accéder à la CloudWatch métrique. Pour de plus amples informations, veuillez consulter [Exigences](#cloudwatch-metrics-rule-action-requirements).
Prend en charge les [modèles de substitution](iot-substitution-templates.md) : Non
## Exemples
L'exemple JSON suivant définit une action CloudWatch métrique dans une AWS IoT règle.
```
{
"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"
}
}
]
}
}
```
L'exemple JSON suivant définit une action CloudWatch métrique avec des modèles de substitution dans une AWS IoT règle.
```
{
"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"
}
}
]
}
}
```
## Consultez aussi
+ [Qu'est-ce qu'Amazon CloudWatch ?](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/) dans le *guide de CloudWatch l'utilisateur Amazon*
+ [Utilisation des CloudWatch métriques Amazon](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/working_with_metrics.html) dans le *guide de CloudWatch l'utilisateur Amazon*
# DynamoDB
L'action DynamoDB `dynamoDB` () écrit tout ou partie d'un message MQTT dans une table Amazon DynamoDB.
Vous pouvez suivre un didacticiel qui explique comment créer et tester une règle avec une action DynamoDB. Pour de plus amples informations, veuillez consulter [Tutoriel : Stockage des données de l'appareil dans une table DynamoDB](iot-ddb-rule.md).
**Note**
Cette règle écrit des données non JSON dans DynamoDB en tant que données binaires. La console DynamoDB affiche les données sous la forme de texte base64-encode.
## Exigences
Cette action réglementaire est assortie des exigences suivantes :
+ Rôle IAM qui AWS IoT peut assumer la réalisation de l'`dynamodb:PutItem`opération. Pour de plus amples informations, veuillez consulter [Accorder à une AWS IoT règle l'accès dont elle a besoin](iot-create-role.md).
Dans la AWS IoT console, vous pouvez choisir ou créer un rôle pour autoriser l'exécution AWS IoT de cette action de règle.
+ Si vous utilisez une clé KMS gérée par AWS KMS key le client pour chiffrer des données inactives dans DynamoDB, le service doit être autorisé à utiliser la clé KMS au nom de l'appelant. Pour plus d'informations, consultez la section [Clé KMS gérée par le client](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/encryption.howitworks.html#managed-cmk-customer-managed) dans le *guide de démarrage Amazon DynamoDB*.
## Parameters
Lorsque vous créez une AWS IoT règle avec cette action, vous devez spécifier les informations suivantes :
`tableName`
Le nom de la table DynamoDB.
Supporte les [modèles de substitution](iot-substitution-templates.md) : API et AWS CLI uniquement
`hashKeyField`
Nom de la clé de hachage (également appelée clé de partition).
Supporte les [modèles de substitution](iot-substitution-templates.md) : API et AWS CLI uniquement
`hashKeyType`
Type de données de la clé de hachage (également appelée clé de partition). Valeurs valides : `STRING`, `NUMBER`.
Supporte les [modèles de substitution](iot-substitution-templates.md) : API et AWS CLI uniquement
`hashKeyValue`
Valeur de la clé de hachage. Envisagez d'utiliser un modèle de substitution tel que `${topic()}` ou`${timestamp()}`.
Prend en charge les [modèles de substitution](iot-substitution-templates.md) : Oui
`rangeKeyField`
(Facultatif) Nom de la clé de plage (également appelée clé de tri).
Supporte les [modèles de substitution](iot-substitution-templates.md) : API et AWS CLI uniquement
`rangeKeyType`
(Facultatif) Type de données de la clé de plage (également appelée clé de tri). Valeurs valides : `STRING`, `NUMBER`.
Supporte les [modèles de substitution](iot-substitution-templates.md) : API et AWS CLI uniquement
`rangeKeyValue`
(Facultatif) Valeur de la clé de plage. Envisagez d'utiliser un modèle de substitution tel que `${topic()}` ou`${timestamp()}`.
Prend en charge les [modèles de substitution](iot-substitution-templates.md) : Oui
`payloadField`
(Facultatif) Nom du champ où la charge utile est écrite. Si vous omettez cette valeur, la charge utile est écrite dans la colonne nommée `payload`.
Prend en charge les [modèles de substitution](iot-substitution-templates.md) : Non
`operation`
(Facultatif) Type d'opération à effectuer. Valeurs valides : `INSERT`, `UPDATE`, `DELETE`.
Prend en charge les [modèles de substitution](iot-substitution-templates.md) : Non
`roleARN`
Rôle IAM qui autorise l'accès à la table DynamoDB. Pour de plus amples informations, veuillez consulter [Exigences](#dynamodb-rule-action-requirements).
Prend en charge les [modèles de substitution](iot-substitution-templates.md) : Non
Les données écrites dans la table DynamoDB sont le résultat de l'instruction SQL de la règle.
## Exemples
L'exemple JSON suivant définit une action DynamoDB dans une règle. 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"
}
}
]
}
}
```
## Consultez aussi
+ [Qu'est-ce qu'Amazon DynamoDB ?](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/) dans le Manuel du *développeur Amazon DynamoDB*
+ [Commencer à utiliser DynamoDB](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/GettingStartedDynamoDB.html) dans le manuel du développeur Amazon *DynamoDB*
+ [Tutoriel : Stockage des données de l'appareil dans une table DynamoDB](iot-ddb-rule.md)
# Dynamo DBv2
L'action Dynamo DBv2 (`dynamoDBv2`) écrit tout ou partie d'un message MQTT dans une table Amazon DynamoDB. Chaque attribut de la charge utile est écrit dans une colonne distincte de la base de données DynamoDB.
## Exigences
Cette action réglementaire est assortie des exigences suivantes :
+ Rôle IAM qui AWS IoT peut assumer la réalisation de l'`dynamodb:PutItem`opération. Pour de plus amples informations, veuillez consulter [Accorder à une AWS IoT règle l'accès dont elle a besoin](iot-create-role.md).
Dans la AWS IoT console, vous pouvez choisir ou créer un rôle pour autoriser l'exécution AWS IoT de cette action de règle.
+ La charge du message MQTT doit contenir une clé de niveau racine qui correspond à la clé de partition primaire de la table et une clé de niveau racine qui correspond à la clé de tri primaire de la table, si elle est définie.
+ Si vous utilisez une clé KMS gérée par AWS KMS key le client pour chiffrer des données inactives dans DynamoDB, le service doit être autorisé à utiliser la clé KMS au nom de l'appelant. Pour plus d'informations, consultez la section [Clé KMS gérée par le client](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/encryption.howitworks.html#managed-cmk-customer-managed) dans le *guide de démarrage Amazon DynamoDB*.
## Parameters
Lorsque vous créez une AWS IoT règle avec cette action, vous devez spécifier les informations suivantes :
`putItem`
Un objet qui indique la table DynamoDB dans laquelle les données de message seront écrites. Cet objet doit contient les informations suivantes :
`tableName`
Le nom de la table DynamoDB.
Supporte les [modèles de substitution](iot-substitution-templates.md) : API et AWS CLI uniquement
`roleARN`
Rôle IAM qui autorise l'accès à la table DynamoDB. Pour de plus amples informations, veuillez consulter [Exigences](#dynamodb-v2-rule-action-requirements).
Prend en charge les [modèles de substitution](iot-substitution-templates.md) : Non
Les données écrites dans la table DynamoDB sont le résultat de l'instruction SQL de la règle.
## Exemples
L'exemple JSON suivant définit une DBv2 action Dynamo dans une AWS IoT règle.
```
{
"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",
}
}
]
}
}
```
L'exemple JSON suivant définit une action DynamoDB avec des modèles de substitution dans une règle. 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"
}
}
]
}
}
```
## Consultez aussi
+ [Qu'est-ce qu'Amazon DynamoDB ?](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/) dans le Manuel du *développeur Amazon DynamoDB*
+ [Commencer à utiliser DynamoDB](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/GettingStartedDynamoDB.html) dans le manuel du développeur Amazon *DynamoDB*
# Elasticsearch
L'action Elasticsearch (`elasticsearch`) écrit les données des messages MQTT dans un domaine Amazon OpenSearch Service. Vous pouvez ensuite utiliser des outils tels que OpenSearch les tableaux de bord pour interroger et visualiser les données dans OpenSearch Service.
**Avertissement**
L'action `Elasticsearch` ne peut être utilisée que par les actions de règle existantes. Pour créer une nouvelle action de règle ou pour mettre à jour une action de règle existante, utilisez l'action de règle `OpenSearch` à la place. Pour de plus amples informations, veuillez consulter [OpenSearch](opensearch-rule-action.md).
## Prérequis
Cette action réglementaire est assortie des exigences suivantes :
+ Rôle IAM qui AWS IoT peut assumer la réalisation de l'`es:ESHttpPut`opération. Pour de plus amples informations, veuillez consulter [Accorder à une AWS IoT règle l'accès dont elle a besoin](iot-create-role.md).
Dans la AWS IoT console, vous pouvez choisir ou créer un rôle pour autoriser l'exécution AWS IoT de cette action de règle.
+ Si vous utilisez une clé KMS gérée par AWS KMS key le client pour chiffrer les données au repos OpenSearch, le service doit être autorisé à utiliser la clé KMS au nom de l'appelant. Pour plus d'informations, consultez la section [Chiffrement des données au repos pour Amazon OpenSearch Service](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/encryption-at-rest.html) dans le manuel *Amazon OpenSearch Service Developer Guide*.
## Parameters
Lorsque vous créez une AWS IoT règle avec cette action, vous devez spécifier les informations suivantes :
`endpoint`
Point de terminaison de votre domaine de service.
Supporte les [modèles de substitution](iot-substitution-templates.md) : API et AWS CLI uniquement
`index`
Index dans lequel vous souhaitez stocker vos données.
Prend en charge les [modèles de substitution](iot-substitution-templates.md) : Oui
`type`
Type de document que vous stockez.
Prend en charge les [modèles de substitution](iot-substitution-templates.md) : Oui
`id`
Identifiant unique de chaque document.
Prend en charge les [modèles de substitution](iot-substitution-templates.md) : Oui
`roleARN`
Rôle IAM qui permet d'accéder au domaine de OpenSearch service. Pour de plus amples informations, veuillez consulter [Prérequis](#elasticsearch-rule-action-requirements).
Prend en charge les [modèles de substitution](iot-substitution-templates.md) : Non
## Exemples
L'exemple JSON suivant définit une action Elasticsearch dans une AWS IoT règle et indique comment vous pouvez spécifier les champs de cette action. `elasticsearch` Pour de plus amples informations, veuillez consulter [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"
}
}
]
}
}
```
L'exemple JSON suivant définit une action Elasticsearch avec des modèles de substitution dans une AWS IoT règle.
```
{
"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"
}
}
]
}
}
```
## Consultez aussi
+ [OpenSearch](opensearch-rule-action.md)
+ [Qu'est-ce qu'Amazon OpenSearch Service ?](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/)
# HTTP
L'action HTTPS (`http`) envoie les données d'un message MQTT à un point de terminaison HTTPS, qui peut pointer vers une application ou un service Web.
## Exigences
Ce rôle d’action possède les critères suivants :
+ Vous devez confirmer et activer les points de terminaison HTTPS avant que le moteur de règles puisse les utiliser. Pour de plus amples informations, veuillez consulter [Destinations d'action HTTP](http-action-destination.md).
## Parameters
Lorsque vous créez une AWS IoT règle avec cette action, vous devez spécifier les informations suivantes :
`url`
Point de terminaison HTTPS à l'endroit où le message est envoyé à l'aide de la méthode HTTP POST. Si vous utilisez une adresse IP à la place d'un nom d'hôte, il doit s'agir d'une IPv4 adresse. IPv6 les adresses ne sont pas prises en charge.
Prend en charge les [modèles de substitution](iot-substitution-templates.md) : Oui
`confirmationUrl`
(Facultatif) Si cela est spécifié, AWS IoT utilise l'URL de confirmation pour créer une destination de règle de sujet correspondante. Vous devez activer la destination de l'action HTTP avant de l'utiliser dans une action HTTP. Pour de plus amples informations, veuillez consulter [Destinations d'action HTTP](http-action-destination.md). Si vous utilisez des modèles de substitution, vous devez créer manuellement une destination d'action HTTP avant de pouvoir utiliser l'`http`action. `confirmationUrl`doit être un préfixe de. `url`
La relation entre `url` et `confirmationUrl` est décrite par les éléments suivants :
+ S'il `url` est codé en dur et n'`confirmationUrl`est pas fourni, nous traitons implicitement le `url` champ comme le. `confirmationUrl` AWS IoT crée une destination de règle de sujet pour`url`.
+ Si `url` et `confirmationUrl` sont codés en dur, cela `url` doit commencer `confirmationUrl` par. AWS IoT crée une destination de règle de sujet pour`confirmationUrl`.
+ Si `url` contient un modèle de substitution, vous devez spécifier `confirmationUrl` et `url` doit commencer par `confirmationUrl`. S'il `confirmationUrl` contient des modèles de substitution, vous devez créer manuellement une destination d'action HTTP avant de pouvoir utiliser l'`http`action. S'il `confirmationUrl` ne contient pas de modèles de substitution, AWS IoT crée une destination de règle de sujet pour`confirmationUrl`.
Prend en charge les [modèles de substitution](iot-substitution-templates.md) : Oui
`headers`
(Facultatif) La liste des en-têtes à inclure dans les requêtes HTTP adressées au point de terminaison. Chaque entête doit contenir les informations suivantes.
`key`
La clé de l'en-tête.
Prend en charge les [modèles de substitution](iot-substitution-templates.md): Non
`value`
Valeur de l'en-tête.
Prend en charge les [modèles de substitution](iot-substitution-templates.md): Oui
Le type de contenu par défaut est application/json lorsque la charge utile est au format JSON. Sinon, il s'agit de application/octet-stream. Vous pouvez le remplacer en spécifiant le type de contenu exact dans l'en-tête avec le type de contenu clé (insensible à la casse).
`auth`
(Facultatif) L'authentification utilisée par le moteur de règles pour se connecter à l'URL du point final spécifié dans `url` l'argument. Actuellement, Signature Version 4 est le seul type d'authentification pris en charge. Pour de plus amples informations, veuillez consulter [Autorisation HTTP](https://docs.aws.amazon.com/iot/latest/apireference/API_HttpAuthorization.html).
Prend en charge les [modèles de substitution](iot-substitution-templates.md) : Non
`enableBatching`
(Facultatif) S'il faut traiter les messages d'action HTTP en une seule demande pour une URL donnée. La valeur peut être vraie ou fausse. Pour plus d'informations sur le traitement par lots, consultez la section Traitement par [lots des messages d'action HTTP](http_batching.md).
Valeur booléenne
Prend en charge les [modèles de substitution](iot-substitution-templates.md) : Non
`batchConfig`
(Facultatif) Paramètres de configuration pour le traitement par lots. Une fois activé, `batchConfig` les paramètres doivent être spécifiés. Si aucun `batchConfig` paramètre n'est spécifié, les valeurs par défaut seront utilisées.
`maxBatchOpenMs`
Durée maximale (en millisecondes) pendant laquelle un message sortant attend que d'autres messages créent le lot. Plus le paramètre est élevé, plus la latence de l'action HTTP par lots est longue.
Valeur minimale : 5 ms. Valeur maximale : 200 ms.
Valeur par défaut : 20 ms
Prend en charge les [modèles de substitution](iot-substitution-templates.md) : Non
`maxBatchSize`
Le nombre maximal de messages qui sont regroupés par lots lors de l'exécution d'une seule action.
Prend en charge les [modèles de substitution](iot-substitution-templates.md) : Non
Valeur minimale : 2 messages. Valeur maximale : 10 messages
Valeur par défaut : 10 messages
`maxBatchSizeBytes`
Taille maximale d'un lot de messages, en octets.
Valeur minimale : 100 octets. Valeur maximale : 131 072 octets
Valeur par défaut : 5 120 octets
Prend en charge les [modèles de substitution](iot-substitution-templates.md) : Non
Le type de contenu par défaut est application/json lorsque la charge utile est au format JSON. Sinon, il s'agit de application/octet-stream. Vous pouvez le remplacer en spécifiant le type de contenu exact dans l'en-tête avec le type de contenu clé (insensible à la casse).
## Exemples
L'exemple JSON suivant définit une AWS IoT règle avec une action 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
}
}
```
## Logique de nouvelle tentative d'action HTTP
Le moteur de AWS IoT règles tente à nouveau l'action HTTP conformément aux règles suivantes :
+ Le moteur de règles essaie d'envoyer un message au moins une fois.
+ Le moteur de règles effectue au plus deux nouvelles tentatives. Le nombre maximum de nouvelles tentatives est trois.
+ Le moteur de règles n'effectue pas de nouvelle tentative si :
+ L'essai précédent a fourni une réponse de plus de 16 384 octets.
+ Le service web ou l'application en aval ferme la connexion TCP après la tentative.
+ Le temps total d'exécution d'une demande avec tentatives a dépassé la limite de temporisation de la demande.
+ La requête renvoie un code d'état HTTP autre que 429, 500-599.
**Note**
[Les coûts standard de transfert de données](https://aws.amazon.com/ec2/pricing/on-demand/) s'appliquent aux nouvelles tentatives.
## Consultez aussi
+ [Traitement par lots de messages d’action HTTP](http_batching.md)
+ [Destinations d'action HTTP](http-action-destination.md)
+ [Acheminez les données directement depuis AWS IoT Core vos services Web](https://aws.amazon.com/blogs/iot/route-data-directly-from-iot-core-to-your-web-services/) dans l'*Internet des objets sur le AWS* blog
# Traitement par lots de messages d’action HTTP
Vous pouvez utiliser le traitement par lots pour envoyer plusieurs messages d'action HTTP en une seule demande.
## Présentation de
Le traitement par lots vous permet d'envoyer des messages par lots depuis AWS IoT Core Rules Engine à vos points de terminaison HTTP. Cette fonctionnalité peut vous aider à réduire vos coûts en réduisant le nombre d'exécutions d'actions HTTP et en améliorant l'efficacité en réduisant les frais associés à l'établissement de nouvelles connexions.
**Note**
L'action HTTP par lots est mesurée comme une action unique. Vous êtes mesuré par incréments de 5 Ko, en fonction de la taille de la charge utile sortante par lots émise par le moteur de AWS IoT Core règles vers le service en aval. Pour plus d'informations, consultez la page de tarification [AWS IoT Core](https://aws.amazon.com/iot-core/pricing/).
Lorsque vous activez le traitement par lots dans la définition de votre action de règle IoT, les paramètres suivants seront disponibles pour la configuration :
`maxBatchOpenMs`
Durée maximale (en millisecondes) pendant laquelle un message sortant attend que d'autres messages créent le lot. Plus le paramètre est élevé, plus la latence de l'action HTTP par lots est longue.
Valeur minimale : 5 ms. Valeur maximale : 200 ms.
Valeur par défaut : 20 ms
Prend en charge les [modèles de substitution](iot-substitution-templates.md) : Non
`maxBatchSize`
Nombre maximal de messages regroupés lors de l'exécution d'une seule action de règle IoT.
Valeur minimale : 2 messages. Valeur maximale : 10 messages
Valeur par défaut : 10 messages
Prend en charge les [modèles de substitution](iot-substitution-templates.md) : Non
`maxBatchSizeBytes`
Taille maximale d'un lot de messages, en octets.
Valeur minimale : 100 octets. Valeur maximale : 131 072 octets
Valeur par défaut : 5120 octets
Prend en charge les [modèles de substitution](iot-substitution-templates.md) : Non
**Important**
Lorsque vous spécifiez plusieurs paramètres de lot, le traitement par lots est terminé lorsque la première limite est atteinte. Par exemple, si vous spécifiez 100 ms comme durée maximale d'ouverture du lot et 5 Ko comme taille de lot maximale, et que Rules Engine ne traite que 2 Ko dans un délai de 100 ms, un lot de 2 Ko sera créé et envoyé.
## Utilisation d'en-têtes HTTP dans un lot
Lorsque vous utilisez des en-têtes dans votre action HTTP, la requête groupée utilise la valeur d'en-tête du dernier message ajouté au lot (pas nécessairement le dernier message que vous avez publié). Nous vous recommandons d'utiliser des valeurs d'en-tête qui sont soit :
+ Identique pour tous les messages du lot
+ Applicable à tous les messages (par exemple, les informations d'authentification)
Les en-têtes sont envoyés avec la requête HTTP et ne font pas partie du corps du message.
**Note**
Lorsque le traitement par lots est activé :
La demande groupée inclut automatiquement l'`Content-Type: application/json`en-tête, car le lot est envoyé sous forme de tableau JSON.
Nous ne pouvons pas garantir que le dernier message du lot soit le dernier que vous avez publié. C'est le dernier message qui a été inclus dans le lot.
## Exemple de charge utile
L'exemple suivant montre la structure d'une charge utile de message par lots envoyée à votre point de terminaison HTTP :
```
[
{
"user_id": "user1",
"steps_today": 1000
},
{
"user_id": "user2",
"steps_today": 21000
},
{
"user_id": "user8",
"steps_today": 1500
},
...
]
```
## Limitations
Les restrictions relatives au traitement par lots sont les suivantes :
+ AWS IoT Core ne garantit pas l'ordre général des messages. Le traitement par lots est effectué localement sur chaque hôte, ce qui peut entraîner le traitement des messages d'un lot dans un ordre différent de celui dans lequel ils ont été reçus.
+ AWS IoT Core ne fournit pas de support pour le traitement des messages du côté du récepteur. Il vous incombe de vous assurer que votre service en aval est configuré pour accepter et traiter les données par lots.
+ Le traitement par lots entre comptes n'est pas pris en charge, même si les messages sont destinés au même identifiant de ressource (URL HTTP ou ARN de ressource).
+ AWS IoT Core ne garantit pas que la taille du lot correspondra à la configuration que vous avez spécifiée. Les lots peuvent être inférieurs aux limites que vous avez configurées en fonction du calendrier et du flux de messages.
+ Lorsque le traitement par lots est activé, les charges utiles binaires (données non UTF-8) ne sont pas prises en charge. Seules les charges utiles de texte UTF-8 (telles que JSON) sont acceptées. Pour envoyer des données binaires, codez-les en base64 avant de les envoyer à l'action HTTP, puis décodez-les sur votre point de terminaison de réception. Par exemple, vous pouvez utiliser la [fonction d'encodage](iot-sql-functions.html#iot-function-encode) dans les règles de l'IoT pour coder la charge utile binaire. Vous pouvez également encoder la charge utile binaire dans votre appareil IoT et la publier sur. AWS IoT Core
## Actions d'erreur liées au traitement par lots
Vous ne serez pas en mesure de définir une logique de traitement par lots distincte dans votre définition d'action d'erreur. Toutefois, votre action d'erreur prendra en charge le traitement par lots si vous avez défini une logique de traitement par lots dans votre action principale.
Lorsqu'une demande par lots échoue, le moteur de AWS IoT Core règles suit la [logique de nouvelle tentative d'action HTTP](https-rule-action.md#https-rule-action-retry-logic). Après la dernière tentative, une action d'erreur sera invoquée pour l'ensemble du lot ayant échoué.
Voici un exemple de message d'action d'erreur lorsque le traitement par lots est activé :
```
{
"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"
}
]
}
```
**Note**
Les échecs d'action par lots génèrent également des charges utiles d'actions d'erreur plus importantes, ce qui peut augmenter la probabilité d'échec des actions d'erreur en raison de leur taille. Vous pouvez surveiller les échecs liés aux actions d'erreur à l'aide de la `ErrorActionFailure` métrique. Pour plus d’informations, consultez [Métriques d'action de règle](metrics_dimensions.md#rule-action-metrics).
## Regrouper les messages d'action HTTP à l'aide du AWS CLI
### Création ou mise à jour d'une action de règle avec traitement par lots
1. Utilisez la AWS CLI commande appropriée pour créer ou mettre à jour une règle :
+ Pour créer une nouvelle règle, utilisez la [create-topic-rule](https://docs.aws.amazon.com/cli/latest/reference/iot/create-topic-rule.html)commande :
```
aws iot create-topic-rule --rule-name myrule --topic-rule-payload file://myrule.json
```
+ Pour mettre à jour une règle existante, utilisez la [replace-topic-rule](https://docs.aws.amazon.com/cli/latest/reference/iot/replace-topic-rule.html)commande :
```
aws iot replace-topic-rule --rule-name myrule --topic-rule-payload file://myrule.json
```
1. Activez les fonctionnalités de traitement par lots en définissant le paramètre EnableBatching sur true dans la charge utile de votre règle de sujet :
```
{
"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. Configurez les paramètres de traitement par lots. Il n'est pas nécessaire de spécifier tous les paramètres du lot. Vous pouvez choisir de spécifier 1, 2 ou les 3 paramètres de lot. Si vous ne spécifiez aucun paramètre de lot, Rules Engine met à jour ce paramètre avec les valeurs par défaut. Pour plus d'informations sur les paramètres de traitement par lots et leurs valeurs par défaut, consultez la section [Paramètres HTTP](https-rule-action.md#https-rule-action-parameters).
# Destinations d'action HTTP
Une destination d'action HTTP est un service Web vers lequel le moteur de règles peut acheminer les données d'une règle de rubrique. Une AWS IoT Core ressource décrit le service Web pour AWS IoT. Les ressources de destination peuvent être partagées selon différentes règles.
Avant de AWS IoT Core pouvoir envoyer des données à un autre service Web, celui-ci doit confirmer qu'il peut accéder au point de terminaison du service.
## Présentation de
Une destination d'action HTTP fait référence à un service Web qui prend en charge une URL de confirmation et une ou plusieurs collectes de données URLs. La ressource de destination contient l'URL de confirmation de votre service Web. Lorsque vous configurez une action HTTP, vous spécifiez l'URL réelle du point de terminaison qui doit recevoir les données ainsi que l'URL de confirmation du service Web. Une fois votre destination confirmée, la règle du sujet envoie le résultat de l'instruction SQL au point de terminaison HTTPS (et non à l'URL de confirmation).
Une destination d'action HTTP peut se trouver dans l'un des états suivants :
ENABLED
La destination a été confirmée et peut être utilisée par une action de règle. L'état d'une destination doit être `ENABLED` (ACTIVÉ) pour qu'elle soit utilisée dans une règle. Vous pouvez uniquement activer une destination dont l'état est DISABLED (DÉSACTIVÉ).
DISABLED
La destination a été confirmée mais elle ne peut pas être utilisée par une action de règle. Cet état est utile si vous souhaitez empêcher temporairement le trafic vers votre point de terminaison sans avoir à passer à nouveau par le processus de confirmation. Vous pouvez uniquement désactiver une destination dont l'état est ENABLED (ACTIVÉ).
EN\$1COURS
La confirmation de la destination est en cours.
ERROR
La confirmation de la destination a expiré.
Une fois qu'une destination d'action HTTP a été confirmée et activée, elle peut être utilisée avec n'importe quelle règle de votre compte.
## Gestion des destinations d'action HTTP
Vous pouvez utiliser les opérations suivantes pour gérer vos destinations d'actions HTTP.
### Création de destinations d'action HTTP
Vous créez une destination d'action HTTP en appelant l'`CreateTopicRuleDestination`opération ou en utilisant la AWS IoT console.
Après avoir créé une destination, AWS IoT envoie une demande de confirmation à l'URL de confirmation. Le format de la demande de confirmation est le suivant :
```
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"
}
```
Le contenu de la demande de confirmation comprend les informations suivantes :
arn
Le nom de ressource Amazon (ARN) pour la destination de l'action HTTP à confirmer.
confirmationToken
Le jeton de confirmation envoyé par AWS IoT Core. Dans l'exemple, le jeton est tronqué. Votre jeton sera plus long. Vous aurez besoin de ce jeton pour confirmer votre destination AWS IoT Core.
enableUrl
L'URL à laquelle vous accédez pour confirmer la destination d'une règle de rubrique.
messageType
Type du message.
### Confirmation des destinations d'action HTTP
Pour terminer le processus de confirmation du point de terminaison, si vous utilisez le AWS CLI, vous devez effectuer les étapes suivantes une fois que votre URL de confirmation a reçu la demande de confirmation.
1.
**Vérifiez que la destination est prête à recevoir des messages**
Pour confirmer que la destination de l'action HTTP est prête à recevoir des messages IoT, appelez-la `enableUrl` dans la demande de confirmation ou effectuez l'opération `ConfirmTopicRuleDestination` API et transmettez le contenu `confirmationToken` de la demande de confirmation.
1.
**Définir le statut des règles du sujet sur Activé**
Après avoir confirmé que la destination peut recevoir des messages, vous devez exécuter l'opération d'`UpdateTopicRuleDestination`API pour définir le statut de la règle du sujet sur`ENABLED`.
Si vous utilisez la AWS IoT console, copiez-la `confirmationToken` et collez-la dans la boîte de dialogue de confirmation de la destination dans la AWS IoT console. Vous pouvez ensuite activer la règle du sujet.
### Envoi d'une nouvelle demande de confirmation
Pour activer un nouveau message de confirmation pour une destination, appelez `UpdateTopicRuleDestination` et réglez le statut de la règle de thème destination sur `IN_PROGRESS`.
Répétez le processus de confirmation après avoir envoyé une nouvelle demande de confirmation.
### Désactivation et suppression d'une destination d'action HTTP
Pour désactiver une destination, appelez `UpdateTopicRuleDestination` et définissez l'état de la destination de règle de rubrique sur `DISABLED`. Une règle de rubrique à l'état DÉSACTIVÉ peut être réactivée sans qu'il soit nécessaire d'envoyer une nouvelle demande de confirmation.
Pour supprimer une destination d'action HTTP, appelez`DeleteTopicRuleDestination`.
## Support aux autorités de certification
**Note**
Les certificats auto-signés ne sont pas pris en charge.
Les points de terminaison HTTPS d'une destination d'action HTTP prennent en charge les certificats émis à la fois par [AWS Private Certificate Authority](https://www.amazontrust.com/repository/) et par [Lets Encrypt](https://letsencrypt.org/certificates/).
# AWS IoT Events
L'action AWS IoT Events (`iotEvents`) envoie les données d'un message MQTT à une AWS IoT Events entrée.
**Important**
Si la charge utile est envoyée AWS IoT Core sans le`Input attribute Key`, ou si la clé ne se trouve pas dans le même chemin JSON spécifié dans la clé, la règle IoT échouera avec l'erreur`Failed to send message to Iot Events`.
## Exigences
Cette action réglementaire est assortie des exigences suivantes :
+ Rôle IAM qui AWS IoT peut assumer la réalisation de l'`iotevents:BatchPutMessage`opération. Pour de plus amples informations, veuillez consulter [Accorder à une AWS IoT règle l'accès dont elle a besoin](iot-create-role.md).
Dans la AWS IoT console, vous pouvez choisir ou créer un rôle pour autoriser l'exécution AWS IoT de cette action de règle.
## Parameters
Lorsque vous créez une AWS IoT règle avec cette action, vous devez spécifier les informations suivantes :
`batchMode`
(Optionnal) traiter ou non l'action d'événement en tant que lot. La valeur par défaut est `false`.
Lorsque `batchMode` c'est le cas `true` et que l'instruction SQL rule est évaluée à un tableau, chaque élément du tableau est traité comme un message distinct lorsqu'il est envoyé à AWS IoT Events par appel [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). Le tableau résultant ne peut pas contenir plus de 10 messages.
Quand `batchMode` est `true`, vous ne pouvez pas spécifier un `messageId`.
Prend en charge les [modèles de substitution](iot-substitution-templates.md) : Non
`inputName`
Le nom de l' AWS IoT Events entrée.
Supporte les [modèles de substitution](iot-substitution-templates.md) : API et AWS CLI uniquement
`messageId`
(Facultatif) Utilisez-le pour vérifier qu'une seule entrée (message) contenant une donnée `messageId` est traitée par un AWS IoT Events détecteur. Vous pouvez utiliser le modèle de `${newuuid()}` substitution pour générer un identifiant unique pour chaque demande.
Quand `batchMode` équivaut à `true`, vous ne pouvez pas spécifier de valeur `messageId` ; une nouvelle valeur UUID sera attribuée.
Prend en charge les [modèles de substitution](iot-substitution-templates.md) : Oui
`roleArn`
Rôle IAM qui permet d' AWS IoT envoyer une entrée à un AWS IoT Events détecteur. Pour de plus amples informations, veuillez consulter [Exigences](#iotevents-rule-action-requirements).
Prend en charge les [modèles de substitution](iot-substitution-templates.md) : Non
## Exemples
L'exemple JSON suivant montre comment définir une action IoT Events dans une AWS IoT règle :
```
{
"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"
}
}
]
}
}
```
## Consultez aussi
+ [Qu'est-ce que c'est AWS IoT Events ?](https://docs.aws.amazon.com/iotevents/latest/developerguide/) dans le *guide AWS IoT Events du développeur*
# AWS IoT SiteWise
L'action AWS IoT SiteWise (`iotSiteWise`) envoie les données d'un message MQTT aux propriétés des actifs dans AWS IoT SiteWise.
Vous pouvez suivre un didacticiel qui explique comment ingérer des données provenant d' AWS IoT objets. Pour plus d'informations, consultez le didacticiel [Ingestion de données vers AWS IoT SiteWise des AWS IoT objets](https://docs.aws.amazon.com/iot-sitewise/latest/userguide/ingest-data-from-iot-things.html) ou la section [Ingestion de données à l'aide des règles de AWS IoT base](https://docs.aws.amazon.com/iot-sitewise/latest/userguide/iot-rules.html) du guide de l'*AWS IoT SiteWise utilisateur*.
## Exigences
Cette action réglementaire est assortie des exigences suivantes :
+ Rôle IAM qui AWS IoT peut assumer la réalisation de l'`iotsitewise:BatchPutAssetPropertyValue`opération. Pour de plus amples informations, veuillez consulter [Accorder à une AWS IoT règle l'accès dont elle a besoin](iot-create-role.md).
Vous pouvez attacher l'exemple suivant de politique de confiance au rôle.
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "iotsitewise:BatchPutAssetPropertyValue",
"Resource": "*"
}
]
}
```
Pour améliorer la sécurité, vous pouvez spécifier un chemin hiérarchique des AWS IoT SiteWise actifs dans la `Condition` propriété. L'exemple suivant est une stratégie d'approbation qui spécifie un chemin de hiérarchie de ressource.
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "iotsitewise:BatchPutAssetPropertyValue",
"Resource": "*",
"Condition": {
"StringLike": {
"iotsitewise:assetHierarchyPath": [
"/root node asset ID",
"/root node asset ID/*"
]
}
}
}
]
}
```
+ Lorsque vous envoyez des données à AWS IoT SiteWise avec cette action, celles-ci doivent répondre aux exigences de l'`BatchPutAssetPropertyValue`opération. Pour plus d’informations, consultez [BatchPutAssetPropertyValue](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_BatchPutAssetPropertyValue.html) dans la *Référence d’API AWS IoT SiteWise *.
## Parameters
Lorsque vous créez une AWS IoT règle avec cette action, vous devez spécifier les informations suivantes :
`putAssetPropertyValueEntries`
Une liste d'entrées de valeurs de propriétés de ressources dont chaque entrée contient les informations suivantes :
`propertyAlias`
(Facultatif) l'alias de propriété associé à votre propriété de ressources. Vous devez spécifier un `propertyAlias` ou à la fois un `assetId` et un `propertyId`. Pour plus d'informations sur les alias de propriété, veuillez consulter [Mappage de flux de données industrielles en propriétés de ressource](https://docs.aws.amazon.com/iot-sitewise/latest/userguide/connect-data-streams.html) dans le *Guide de l'utilisateur AWS IoT SiteWise *.
Prend en charge les [modèles de substitution](iot-substitution-templates.md) : Oui
`assetId`
(Facultatif) L'ID de l' AWS IoT SiteWise actif. Vous devez spécifier un `propertyAlias` ou à la fois un `assetId` et un `propertyId`.
Prend en charge les [modèles de substitution](iot-substitution-templates.md): Oui
`propertyId`
(Facultatif) ID d'une propriété d'actif. Vous devez spécifier un `propertyAlias` ou à la fois un `assetId` et un `propertyId`.
Prend en charge les [modèles de substitution](iot-substitution-templates.md): Oui
`entryId`
(Facultatif) Un identifiant unique pour cette entrée. Définir le `entryId` pour mieux savoir quel message a provoqué une erreur en cas de défaillance. La valeur par défaut est un nouvel UUID.
Prend en charge les [modèles de substitution](iot-substitution-templates.md) : Oui
`propertyValues`
Liste des valeurs de propriété à insérer, contenant chacune l'horodatage, la qualité et la valeur (TQV) au format suivant :
`timestamp`
Structure d'horodatage contenant les informations suivantes :
`timeInSeconds`
Chaîne contenant l’heure en secondes au format d'heure Unix epoch. Si votre charge utile de message n'a pas d'horodatage, vous pouvez utiliser [timestamp()](iot-sql-functions.md#iot-function-timestamp), qui renvoie l'heure actuelle en millisecondes. Pour convertir cette heure en secondes, vous pouvez utiliser le modèle de substitution suivant : **\$1\$1floor(timestamp() / 1E3)\$1**.
Prend en charge les [modèles de substitution](iot-substitution-templates.md) : Oui
`offsetInNanos`
(Facultatif) Chaîne contenant le décalage de nanoseconde par rapport à l’heure en secondes. Si votre charge utile de message n'a pas d'horodatage, vous pouvez utiliser [timestamp()](iot-sql-functions.md#iot-function-timestamp), qui renvoie l'heure actuelle en millisecondes. Pour calculer le décalage de nanosecondes à partir de cette heure, vous pouvez utiliser le modèle de substitution suivant : **\$1\$1(timestamp() % 1E3) \$1 1E6\$1**.
Prend en charge les [modèles de substitution](iot-substitution-templates.md) : Oui
En ce qui concerne Unix Epoch Time, n' AWS IoT SiteWise accepte que les entrées dont l'horodatage est compris entre 7 jours et 5 minutes dans le futur.
`quality`
(Facultatif) Chaîne qui décrit la qualité de la valeur. Valeurs valides : `GOOD`, `BAD`, `UNCERTAIN`.
Prend en charge les [modèles de substitution](iot-substitution-templates.md) : Oui
`value`
Structure de valeur qui contient l'un des champs de valeur suivants, en fonction du type de données de la propriété de la ressource :
`booleanValue`
(Facultatif) Chaîne qui contient la valeur booléenne de l'entrée de valeur.
Prend en charge les [modèles de substitution](iot-substitution-templates.md) : Oui
`doubleValue`
(Facultatif) Chaîne qui contient la valeur double de l'entrée de valeur.
Prend en charge les [modèles de substitution](iot-substitution-templates.md) : Oui
`integerValue`
(Facultatif) Chaîne qui contient la valeur d'entier de l'entrée de valeur.
Prend en charge les [modèles de substitution](iot-substitution-templates.md) : Oui
`stringValue`
(Facultatif) Valeur de chaîne de l'entrée de valeur.
Prend en charge les [modèles de substitution](iot-substitution-templates.md) : Oui
`roleArn`
L'ARN du rôle IAM qui AWS IoT autorise l'envoi d'une valeur de propriété d'actif à AWS IoT SiteWise. Pour de plus amples informations, veuillez consulter [Exigences](#iotsitewise-rule-action-requirements).
Prend en charge les [modèles de substitution](iot-substitution-templates.md) : Non
## Exemples
L'exemple JSON suivant définit une SiteWise action IoT de base dans une AWS IoT règle.
```
{
"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"
}
}
]
}
}
```
L'exemple JSON suivant définit une SiteWise action IoT dans une AWS IoT règle. Cet exemple utilise la rubrique comme alias de propriété et la fonction `timestamp()`. Par exemple, si vous publiez des données vers `/company/windfarm/3/turbine/7/rpm`, cette action envoie les données à la propriété de ressource avec un alias de propriété identique à la rubrique que vous avez spécifiée.
```
{
"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"
}
}
]
}
}
```
## Consultez aussi
+ [Qu'est-ce que AWS IoT SiteWise ?](https://docs.aws.amazon.com/iot-sitewise/latest/userguide/what-is-sitewise.html) dans le *Guide de l'utilisateur AWS IoT SiteWise *
+ [Ingestion de données à l'aide AWS IoT Core des règles](https://docs.aws.amazon.com/iot-sitewise/latest/userguide/iot-rules.html) du guide de l'*AWS IoT SiteWise utilisateur*
+ [Ingestion de données vers AWS IoT SiteWise des AWS IoT objets figurant](https://docs.aws.amazon.com/iot-sitewise/latest/userguide/ingest-data-from-iot-things.html) dans le guide de l'*AWS IoT SiteWise utilisateur*
+ [Résolution des problèmes liés à une action de AWS IoT SiteWise règle](https://docs.aws.amazon.com/iot-sitewise/latest/userguide/troubleshoot-rule.html) dans le *guide de AWS IoT SiteWise l'utilisateur*
# Firehose
L'action Firehose (`firehose`) envoie les données d'un message MQTT vers un flux Amazon Data Firehose.
## Exigences
Cette action réglementaire est assortie des exigences suivantes :
+ Rôle IAM qui AWS IoT peut assumer la réalisation de l'`firehose:PutRecord`opération. Pour de plus amples informations, veuillez consulter [Accorder à une AWS IoT règle l'accès dont elle a besoin](iot-create-role.md).
Dans la AWS IoT console, vous pouvez choisir ou créer un rôle pour autoriser l'exécution AWS IoT de cette action de règle.
+ Si vous utilisez Firehose pour envoyer des données vers un compartiment Amazon S3 et que vous utilisez un AWS KMS client géré AWS KMS key pour chiffrer les données au repos dans Amazon S3, Firehose doit avoir accès à votre compartiment et être autorisé à l'utiliser au nom de l'appelant AWS KMS key . Pour plus d'informations, consultez [Accorder à Firehose l'accès à une destination Amazon S3](https://docs.aws.amazon.com/firehose/latest/dev/controlling-access.html#using-iam-s3) dans le manuel *Amazon Data Firehose* Developer Guide.
## Parameters
Lorsque vous créez une AWS IoT règle avec cette action, vous devez spécifier les informations suivantes :
`batchMode`
(Facultatif) S'il faut fournir le flux Firehose sous forme de lot en utilisant. [https://docs.aws.amazon.com/firehose/latest/APIReference/API_PutRecordBatch.html](https://docs.aws.amazon.com/firehose/latest/APIReference/API_PutRecordBatch.html) La valeur par défaut est `false`.
Quand `batchMode` est `true` et que l'instruction SQL de la règle est évaluée dans un tableau, chaque élément du tableau forme un enregistrement dans la demande `PutRecordBatch`. Le tableau résultant ne peut pas contenir plus de 500 enregistrements.
Prend en charge les [modèles de substitution](iot-substitution-templates.md) : Non
`deliveryStreamName`
Le flux Firehose dans lequel les données du message doivent être écrites.
Supporte les [modèles de substitution](iot-substitution-templates.md) : API et AWS CLI uniquement
`separator`
(Facultatif) Séparateur de caractères utilisé pour séparer les enregistrements écrits dans le flux Firehose. Si vous omettez ce paramètre, le flux n'utilise aucun séparateur. Valeurs valides : `,` (virgule), `\t` (tab), `\n` (nouvelle ligne), `\r\n` (nouvelle ligne Windows).
Prend en charge les [modèles de substitution](iot-substitution-templates.md) : Non
`roleArn`
Rôle IAM qui permet d'accéder au flux Firehose. Pour de plus amples informations, veuillez consulter [Exigences](#kinesis-firehose-rule-action-requirements).
Prend en charge les [modèles de substitution](iot-substitution-templates.md) : Non
## Exemples
L'exemple JSON suivant définit une action Firehose dans une AWS IoT règle.
```
{
"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"
}
}
]
}
}
```
L'exemple JSON suivant définit une action Firehose avec des modèles de substitution dans une AWS IoT règle.
```
{
"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"
}
}
]
}
}
```
## Consultez aussi
+ [Qu'est-ce qu'Amazon Data Firehose ?](https://docs.aws.amazon.com/firehose/latest/dev/) dans le guide du *développeur Amazon Data Firehose*
# Kinesis Data Streams
L'action Kinesis Data Streams `kinesis` () écrit les données d'un message MQTT dans Amazon Kinesis Data Streams.
## Exigences
Cette action réglementaire est assortie des exigences suivantes :
+ Rôle IAM qui AWS IoT peut assumer la réalisation de l'`kinesis:PutRecord`opération. Pour de plus amples informations, veuillez consulter [Accorder à une AWS IoT règle l'accès dont elle a besoin](iot-create-role.md).
Dans la AWS IoT console, vous pouvez choisir ou créer un rôle pour autoriser l'exécution AWS IoT de cette action de règle.
+ Si vous utilisez une clé KMS AWS KMS gérée par le client AWS KMS key pour chiffrer des données inactives dans Kinesis Data Streams, le service doit être autorisé à l'utiliser au nom de AWS KMS key l'appelant. Pour de plus amples informations, veuillez consulter [Permissions to use user-generated AWS KMS keys](https://docs.aws.amazon.com/streams/latest/dev/permissions-user-key-KMS.html) dans le Amazon Kinesis Data Streams Developer Guide.
## Parameters
Lorsque vous créez une AWS IoT règle avec cette action, vous devez spécifier les informations suivantes :
`stream`
Le Flux de donnees Kinesis dans lequel écrire les données.
Supporte les [modèles de substitution](iot-substitution-templates.md) : API et AWS CLI uniquement
`partitionKey`
Clé de partition utilisée pour déterminer dans quelle partition les données sont écrites. La clé de partition est généralement composée d'une expression (par exemple, `${topic()}` ou `${timestamp()}`).
Prend en charge les [modèles de substitution](iot-substitution-templates.md) : Oui
`roleArn`
L'ARN du rôle IAM qui accorde l' AWS IoT autorisation d'accéder au flux de données Kinesis. Pour de plus amples informations, veuillez consulter [Exigences](#kinesis-rule-action-requirements).
Prend en charge les [modèles de substitution](iot-substitution-templates.md) : Non
## Exemples
L'exemple JSON suivant définit une action Kinesis Data Streams dans AWS IoT une règle.
```
{
"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"
}
}
]
}
}
```
L'exemple JSON suivant définit une action Kinesis avec des modèles de substitution dans une AWS IoT règle.
```
{
"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"
}
}
]
}
}
```
## Consultez aussi
+ [Qu'est-ce que Amazon Kinesis Data Streams ?](https://docs.aws.amazon.com/streams/latest/dev/) dans le *Guide du développeur Amazon Kinesis Data Streams*
# Lambda
Une action Lambda (`lambda`) appelle une AWS Lambda fonction en transmettant un message MQTT. AWS IoT invoque les fonctions Lambda de manière asynchrone.
Vous pouvez suivre un didacticiel qui vous montre comment créer et tester une règle avec une action Lambda. Pour de plus amples informations, veuillez consulter [Tutoriel : Formatage d'une notification à l'aide d'une AWS Lambda fonction](iot-lambda-rule.md).
## Prérequis
Cette action réglementaire est assortie des exigences suivantes :
+ AWS IoT Pour appeler une fonction Lambda, vous devez configurer une politique qui accorde l'`lambda:InvokeFunction`autorisation de. AWS IoT Vous ne pouvez invoquer une fonction Lambda définie dans la même fonction que Région AWS lorsque votre politique Lambda existe. Les fonctions Lambda utilisent des politiques basées sur les ressources, vous devez donc attacher la politique à la fonction Lambda elle-même.
Utilisez la AWS CLI commande suivante pour joindre une politique qui accorde l'`lambda:InvokeFunction`autorisation. Dans cette commande, remplacez :
+ *function\$1name*avec le nom de la fonction Lambda. Vous ajoutez une nouvelle autorisation pour mettre à jour la politique de ressources de la fonction.
+ *region*avec le Région AWS de la fonction.
+ *account-id*avec le Compte AWS numéro où la règle est définie.
+ *rule-name*avec le nom de la AWS IoT règle pour laquelle vous définissez l'action Lambda.
+ *unique\$1id*avec un identifiant de relevé unique.
**Important**
Si vous ajoutez une autorisation pour un AWS IoT principal sans fournir le `source-arn` ou`source-account`, toute autorisation Compte AWS qui crée une règle avec votre action Lambda peut activer des règles à partir desquelles appeler votre fonction Lambda. AWS IoT
Pour plus d’informations, consultez [Autorisations AWS Lambda](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"
```
+ Si vous utilisez la AWS IoT console pour créer une règle pour l'action de règle Lambda, la fonction Lambda est déclenchée automatiquement. Si vous utilisez AWS CloudFormation plutôt avec le [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), vous devez ajouter une [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)ressource. La ressource vous autorise ensuite à déclencher la fonction Lambda.
Le code suivant montre un exemple d'ajout de cette ressource. Dans cet exemple, remplacez :
+ *function\$1name*avec le nom de la fonction Lambda.
+ *region*avec le Région AWS de la fonction.
+ *account-id*avec le Compte AWS numéro où la règle est définie.
+ *rule-name*avec le nom de la AWS IoT règle pour laquelle vous définissez l'action 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
```
+ Si vous utilisez un AWS KMS client géré AWS KMS key pour chiffrer des données au repos dans Lambda, le service doit être autorisé à l'utiliser au nom AWS KMS key de l'appelant. Pour plus d'informations, veuillez consulter la rubrique [Chiffrement au repos](https://docs.aws.amazon.com/lambda/latest/dg/security-dataprotection.html#security-privacy-atrest) dans le *Guide du développeur AWS Lambda *.
## Parameters
Lorsque vous créez une AWS IoT règle avec cette action, vous devez spécifier les informations suivantes :
`functionArn`
L'ARN de la fonction Lambda à invoquer. AWS IoT doit être autorisé à invoquer la fonction. Pour de plus amples informations, veuillez consulter [Prérequis](#lambda-rule-action-requirements).
Si vous ne spécifiez pas de version ou d'alias pour votre fonction Lambda, c'est la version la plus récente de la fonction qui est arrêtée. Vous pouvez spécifier une version ou un alias si vous souhaitez arrêter une version spécifique de votre fonction Lambda. Pour spécifier une version ou un alias, ajoutez la version ou l'alias à l'ARN de la fonction Lambda.
```
arn:aws:lambda:us-east-2:123456789012:function:myLambdaFunction:someAlias
```
Pour plus d'informations sur le versionnage et les alias, consultez [AWS Lambda la fonction versionnage et alias](https://docs.aws.amazon.com/lambda/latest/dg/versioning-aliases.html).
Supporte les [modèles de substitution](iot-substitution-templates.md) : API et AWS CLI uniquement
## Exemples
L'exemple JSON suivant définit une action Lambda dans une AWS IoT règle.
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"lambda": {
"functionArn": "arn:aws:lambda:us-east-2:123456789012:function:myLambdaFunction"
}
}
]
}
}
```
L'exemple JSON suivant définit une action Lambda avec des modèles de substitution dans une AWS IoT règle.
```
{
"topicRulePayload": {
"sql": "SELECT * FROM 'some/topic'",
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23",
"actions": [
{
"lambda": {
"functionArn": "arn:aws:lambda:us-east-1:123456789012:function:${topic()}"
}
}
]
}
}
```
## Consultez aussi
+ [Qu'est-ce que c'est AWS Lambda ?](https://docs.aws.amazon.com/lambda/latest/dg/) dans le *guide AWS Lambda du développeur*
+ [Tutoriel : Formatage d'une notification à l'aide d'une AWS Lambda fonction](iot-lambda-rule.md)
# Location
L'action Location (`location`) envoie vos données de localisation géographique à [Amazon Location Service](https://docs.aws.amazon.com//location/latest/developerguide/welcome.html).
## Exigences
Cette action réglementaire est assortie des exigences suivantes :
+ Rôle IAM qui AWS IoT peut assumer la réalisation de l'`geo:BatchUpdateDevicePosition`opération. Pour de plus amples informations, veuillez consulter [Accorder à une AWS IoT règle l'accès dont elle a besoin](iot-create-role.md).
Dans la AWS IoT console, vous pouvez choisir ou créer un rôle pour autoriser l'exécution AWS IoT de cette action de règle.
## Parameters
Lorsque vous créez une AWS IoT règle avec cette action, vous devez spécifier les informations suivantes :
`deviceId`
ID unique de l'appareil fournissant les données de localisation. Pour plus d'informations, veuillez consulter la [https://docs.aws.amazon.com//location/latest/APIReference/API_DevicePositionUpdate.html](https://docs.aws.amazon.com//location/latest/APIReference/API_DevicePositionUpdate.html) de l’ *Amazon Location Service API Reference*.
Prend en charge les [modèles de substitution](iot-substitution-templates.md) : Oui
`latitude`
Chaîne qui correspond à une valeur double représentant la latitude de l'emplacement de l'appareil.
Prend en charge les [modèles de substitution](iot-substitution-templates.md) : Oui
`longitude`
Chaîne qui correspond à une valeur double représentant la longitude de l'emplacement de l'appareil.
Prend en charge les [modèles de substitution](iot-substitution-templates.md) : Oui
`roleArn`
Rôle IAM qui autorise l'accès au domaine Amazon Location Service. Pour de plus amples informations, veuillez consulter [Exigences](#location-rule-action-requirements).
`timestamp`
Heure à laquelle les données de localisation ont été échantillonnées. La valeur par défaut est l'heure à laquelle le message MQTT a été traité.
La `timestamp` valeur se compose des deux valeurs suivantes :
+ `value`: Expression qui renvoie une valeur temporelle de longue époque. Vous pouvez utiliser cette [time\$1to\$1epoch (Chaîne, Chaîne)](iot-sql-functions.md#iot-sql-function-time-to-epoch) fonction pour créer un horodatage valide à partir d'une valeur de date ou d'heure transmise dans la charge utile du message. Prend en charge les [modèles de substitution](iot-substitution-templates.md) : Oui
+ `unit`: (Facultatif) La précision de la valeur d'horodatage résultant de l'expression décrite à la section `value`. Valeurs valides: `SECONDS` \$1 `MILLISECONDS` \$1 `MICROSECONDS` \$1 `NANOSECONDS` La valeur par défaut est `MILLISECONDS`. Supporte les [modèles de substitution](iot-substitution-templates.md) : API et AWS CLI uniquement.
`trackerName`
Nom de la ressource de suivi Amazon Location dans laquelle l'emplacement est mis à jour. Pour plus d'informations, consultez [Tracker](https://docs.aws.amazon.com//location/latest/developerguide/geofence-tracker-concepts.html#tracking-overview) dans le *guide du développeur d'Amazon Location Service*.
Supporte les [modèles de substitution](iot-substitution-templates.md) : API et AWS CLI uniquement
## Exemples
L'exemple JSON suivant définit une action de localisation dans une AWS IoT règle.
```
{
"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"
}
}
]
}
}
```
L'exemple JSON suivant définit une action de localisation avec des modèles de substitution dans une AWS IoT règle.
```
{
"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)}"
}
}
]
}
}
```
L'exemple de charge utile MQTT suivant montre comment les modèles de substitution de l'exemple précédent accèdent aux données. Vous pouvez utiliser la commande [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 pour vérifier que les données de charge utile MQTT sont fournies dans votre outil de localisation.
```
{
"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"
}
]
}
```
## Consultez aussi
+ [Qu'est-ce qu'Amazon Location Service ?](https://docs.aws.amazon.com//location/latest/developerguide/welcome.html) dans le *guide du développeur d'Amazon Location Service*.
# OpenSearch
L'action OpenSearch (`openSearch`) écrit les données des messages MQTT dans un domaine Amazon OpenSearch Service. Vous pouvez ensuite utiliser des outils tels que OpenSearch les tableaux de bord pour interroger et visualiser les données dans OpenSearch Service.
## Exigences
Cette action réglementaire est assortie des exigences suivantes :
+ Rôle IAM qui AWS IoT peut assumer la réalisation de l'`es:ESHttpPut`opération. Pour de plus amples informations, veuillez consulter [Accorder à une AWS IoT règle l'accès dont elle a besoin](iot-create-role.md).
Dans la AWS IoT console, vous pouvez choisir ou créer un rôle pour autoriser l'exécution AWS IoT de cette action de règle.
+ Si vous utilisez un client géré AWS KMS key pour chiffrer les données au repos dans le OpenSearch Service, le service doit être autorisé à utiliser la clé KMS au nom de l'appelant. Pour plus d'informations, consultez la section [Chiffrement des données au repos pour Amazon OpenSearch Service](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/encryption-at-rest.html) dans le manuel *Amazon OpenSearch Service Developer Guide*.
## Parameters
Lorsque vous créez une AWS IoT règle avec cette action, vous devez spécifier les informations suivantes :
`endpoint`
Le point de terminaison de votre domaine Amazon OpenSearch Service.
Supporte les [modèles de substitution](iot-substitution-templates.md) : API et AWS CLI uniquement
`index`
L' OpenSearch index dans lequel vous souhaitez stocker vos données.
Prend en charge les [modèles de substitution](iot-substitution-templates.md) : Oui
`type`
Type de document que vous stockez.
Pour OpenSearch les versions ultérieures à 1.0, la valeur du `type` paramètre doit être`_doc`. Pour plus d’informations, consultez la [documentation OpenSearch ](https://opensearch.org/docs/1.0/opensearch/rest-api/document-apis/index-document/#response-body-fields).
Prend en charge les [modèles de substitution](iot-substitution-templates.md) : Oui
`id`
Identifiant unique de chaque document.
Prend en charge les [modèles de substitution](iot-substitution-templates.md) : Oui
`roleARN`
Rôle IAM qui permet d'accéder au domaine de OpenSearch service. Pour de plus amples informations, veuillez consulter [Exigences](#opensearch-rule-action-requirements).
Prend en charge les [modèles de substitution](iot-substitution-templates.md) : Non
## Limitations
L'action OpenSearch (`openSearch`) ne peut pas être utilisée pour fournir des données aux clusters VPC Elasticsearch.
## Exemples
L'exemple JSON suivant définit une OpenSearch action dans une AWS IoT règle et indique comment vous pouvez spécifier les champs de cette `OpenSearch` action. Pour de plus amples informations, veuillez consulter [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"
}
}
]
}
}
```
L'exemple JSON suivant définit une OpenSearch action avec des modèles de substitution dans une AWS IoT règle.
```
{
"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"
}
}
]
}
}
```
**Note**
Le `type` champ substitué fonctionne pour OpenSearch la version 1.0. Pour toutes les versions ultérieures à 1.0, la valeur de `type` doit être`_doc`.
## Consultez aussi
[Qu'est-ce qu'Amazon OpenSearch Service ?](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/) dans le *Amazon OpenSearch Service Developer Guide*
# Republier
L'action republish (`republish`) republie un message MQTT dans un autre sujet MQTT.
## Exigences
Cette action réglementaire est assortie des exigences suivantes :
+ Rôle IAM qui AWS IoT peut assumer la réalisation de l'`iot:Publish`opération. Pour de plus amples informations, veuillez consulter [Accorder à une AWS IoT règle l'accès dont elle a besoin](iot-create-role.md).
Dans la AWS IoT console, vous pouvez choisir ou créer un rôle pour autoriser l'exécution AWS IoT de cette action de règle.
## Parameters
Lorsque vous créez une AWS IoT règle avec cette action, vous devez spécifier les informations suivantes :
`headers`
Informations sur les en-têtes MQTT version 5.0.
Pour plus d'informations, veuillez consulter les sections [RepublishAction](https://docs.aws.amazon.com//iot/latest/apireference/API_RepublishAction.html) et [MqttHeaders](https://docs.aws.amazon.com//iot/latest/apireference/API_MqttHeaders.html) (français non garanti) de la *Référence d'API AWS *.
`topic`
Rubrique MQTT dans laquelle republier le message.
Pour republier dans un sujet réservé, qui commence par`$`, utilisez `$$` plutôt. Par exemple, si vous republiez sur un device shadow une rubrique du type `$aws/things/MyThing/shadow/update`, spécifiez la rubrique comme `$$aws/things/MyThing/shadow/update`.
La republication vers des [thèmes de la tâche réservés](reserved-topics.md#reserved-topics-job) n'est pas prise en charge.
AWS IoT Device Defender les rubriques réservées ne prennent pas en charge la publication HTTP.
Prend en charge les [modèles de substitution](iot-substitution-templates.md) : Oui
`qos`
(facultatif) Le niveau de qualité de service (QoS) à utiliser pour republier des messages. Valeurs valides : `0`, `1`. La valeur par défaut est `0`. Pour plus d'informations sur MQTT QoS, consultez [MQTT](mqtt.md).
Prend en charge les [modèles de substitution](iot-substitution-templates.md) : Non
`roleArn`
Rôle IAM qui permet de AWS IoT publier sur le sujet MQTT. Pour de plus amples informations, veuillez consulter [Exigences](#republish-rule-action-requirements).
Prend en charge les [modèles de substitution](iot-substitution-templates.md) : Non
## Exemples
L'exemple JSON suivant définit une action de republication dans une AWS IoT règle.
```
{
"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"
}
}
]
}
}
```
L'exemple JSON suivant définit une action de republication avec des modèles de substitution dans une AWS IoT règle.
```
{
"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"
}
}
]
}
}
```
L'exemple JSON suivant définit une action de republication `headers` dans une AWS IoT règle.
```
{
"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"
}
]
}
}
}
]
}
}
```
**Note**
L'adresse IP source d'origine ne sera pas transmise par le biais de [Republier l’action](#republish-rule-action).
# S3
L'action S3 (`s3`) écrit les données d'un message MQTT dans un compartiment Amazon Simple Storage Service (Amazon S3).
## Exigences
Cette action réglementaire est assortie des exigences suivantes :
+ Rôle IAM qui AWS IoT peut assumer la réalisation de l'`s3:PutObject`opération. Pour de plus amples informations, veuillez consulter [Accorder à une AWS IoT règle l'accès dont elle a besoin](iot-create-role.md).
Dans la AWS IoT console, vous pouvez choisir ou créer un rôle pour autoriser l'exécution AWS IoT de cette action de règle.
+ Si vous utilisez un service AWS KMS géré par le client AWS KMS key pour chiffrer des données au repos dans Amazon S3, le service doit être autorisé à l'utiliser au nom AWS KMS key de l'appelant. Pour plus d'informations, consultez les sections « [AWS géré » AWS KMS keys et « géré par le client](https://docs.aws.amazon.com/AmazonS3/latest/userguide/UsingKMSEncryption.html#aws-managed-customer-managed-cmks) » AWS KMS keys dans le manuel *Amazon Simple Storage Service Developer Guide*.
## Parameters
Lorsque vous créez une AWS IoT règle avec cette action, vous devez spécifier les informations suivantes :
`bucket`
Compartiment Amazon S3 dans lequel écrire les données..
Supporte les [modèles de substitution](iot-substitution-templates.md) : API et AWS CLI uniquement
`cannedacl`
Liste ACL prédéfinie Amazon S3 qui contrôle l'accès à l'objet identifié par la clé d'objet. Pour plus d'informations, y compris les valeurs autorisées, voir [Canned ACL](https://docs.aws.amazon.com/AmazonS3/latest/userguide/acl-overview.html#canned-acl).
Prend en charge les [modèles de substitution](iot-substitution-templates.md) :Non
`key`
Chemin d'accès au fichier dans lequel les données sont écrites.
Prenons un exemple où ce paramètre se trouve `${topic()}/${timestamp()}` et où la règle reçoit un message contenant le sujet `some/topic`. Si l'horodatage actuel est le cas`1460685389`, cette action écrit les données dans un fichier appelé `1460685389` dans le `some/topic` dossier du compartiment S3.
Si vous utilisez une clé statique, elle AWS IoT remplace un seul fichier à chaque fois que la règle est invoquée. Nous vous recommandons d'utiliser l'horodatage du message ou un autre identifiant de message unique afin qu'un nouveau fichier soit enregistré dans Amazon S3 pour chaque message reçu.
Prend en charge les [modèles de substitution](iot-substitution-templates.md) : Oui
`roleArn`
Rôle IAM qui autorise l'accès au compartiment Amazon S3. Pour de plus amples informations, veuillez consulter [Exigences](#s3-rule-action-requirements).
Prend en charge les [modèles de substitution](iot-substitution-templates.md) : Non
## Exemples
L'exemple JSON suivant définit une action S3 dans une AWS IoT règle.
```
{
"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"
}
}
]
}
}
```
## Consultez aussi
+ [Qu’est-ce qu'Amazon S3](https://docs.aws.amazon.com/AmazonS3/latest/userguide/) dans le *Guide de l'utilisateur Amazon Simple Storage Service*.
# IoT Salesforce
Une action Salesforce IoT (`salesforce`) envoie les données du message MQTT qui a déclenché la règle pour un flux d'entrée Salesforce IoT.
## Parameters
Lorsque vous créez une AWS IoT règle avec cette action, vous devez spécifier les informations suivantes :
`url`
URL exposée par le flux d'entrée Salesforce IoT. L'URL est disponible depuis la plateforme Salesforce IoT au moment où vous créez un flux d'entrée. Pour plus d'informations, consultez la documentation Salesforce IoT.
Prend en charge les [modèles de substitution](iot-substitution-templates.md) : Non
`token`
Jeton utilisé pour authentifier l'accès au flux d'entrée Salesforce IoT spécifié. Le jeton est disponible depuis la plateforme Salesforce IoT au moment où vous créez un flux d'entrée. Pour plus d'informations, consultez la documentation Salesforce IoT.
Prend en charge les [modèles de substitution](iot-substitution-templates.md) : Non
## Exemples
L'exemple JSON suivant définit une action Salesforce IoT dans une AWS IoT règle.
```
{
"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
L'action SNS (`sns`) envoie les données d'un message MQTT sous la forme d'une notification push Amazon Simple Notification Service (Amazon SNS).
Vous pouvez suivre un didacticiel qui vous montre comment créer et tester une règle avec une action SNS. Pour de plus amples informations, veuillez consulter [Tutoriel : envoi d'une notification Amazon SNS](iot-sns-rule.md).
**Note**
L'action SNS ne prend pas en charge les rubriques [Amazon SNS FIFO (premier entré, premier sorti)](https://docs.aws.amazon.com/sns/latest/dg/sns-fifo-topics.html). Le moteur de règles étant un service entièrement distribué, l'ordre des messages n'est pas garanti lorsque l'action SNS est invoquée.
## Exigences
Cette action réglementaire est assortie des exigences suivantes :
+ Rôle IAM qui AWS IoT peut assumer la réalisation de l'`sns:Publish`opération. Pour de plus amples informations, veuillez consulter [Accorder à une AWS IoT règle l'accès dont elle a besoin](iot-create-role.md).
Dans la AWS IoT console, vous pouvez choisir ou créer un rôle pour autoriser l'exécution AWS IoT de cette action de règle.
+ Si vous utilisez un AWS KMS service géré par le client AWS KMS key pour chiffrer des données au repos sur Amazon SNS, le service doit être autorisé à l'utiliser au nom de l'appelant AWS KMS key . Pour en savoir plus, veuillez consulter Key management dans le *Guide du développeur Amazon Simple Notification Service*.
## Parameters
Lorsque vous créez une AWS IoT règle avec cette action, vous devez spécifier les informations suivantes :
`targetArn`
Rubrique SNS ou appareil individuel auxquels les notifications push sont envoyées.
Supporte les [modèles de substitution](iot-substitution-templates.md) : API et AWS CLI uniquement
`messageFormat`
(Facultatif) Format du message. Amazon SNS utilise ce paramètre pour déterminer si la charge utile doit être analysée et si les parties de la charge utile spécifiques à la plate-forme doivent être extraites. Valeurs valides : `JSON`, `RAW`. La valeur par défaut est `RAW` .
Prend en charge les [modèles de substitution](iot-substitution-templates.md) : Non
`roleArn`
Rôle IAM qui autorise l'accès à SNS. Pour de plus amples informations, veuillez consulter [Exigences](#sns-rule-action-requirements).
Prend en charge les [modèles de substitution](iot-substitution-templates.md) : Non
## Exemples
L'exemple JSON suivant définit une action SNS dans une AWS IoT règle.
```
{
"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"
}
}
]
}
}
```
L'exemple JSON suivant définit une action SNS avec des modèles de substitution dans une AWS IoT règle.
```
{
"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"
}
}
]
}
}
```
## Consultez aussi
+ [Qu'est-ce qu'Amazon Simple Notification Service ?](https://docs.aws.amazon.com/sns/latest/dg/) dans le *Guide du développeur Amazon Simple Notification Service*
+ [Tutoriel : envoi d'une notification Amazon SNS](iot-sns-rule.md)
# SQS
L'action SQS (`sqs`) envoie les données d'un message MQTT à une file d'attente Amazon Simple Queue Service (Amazon SQS).
**Note**
L'action SQS ne prend pas en charge les files d'attente [Amazon SQS FIFO (premier entré, premier sorti)](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/FIFO-queues.html). Le moteur de règles étant un service entièrement distribué, l'ordre des messages n'est pas garanti lorsque l'action SQS est déclenchée.
## Exigences
Cette action réglementaire est assortie des exigences suivantes :
+ Rôle IAM qui AWS IoT peut assumer la réalisation de l'`sqs:SendMessage`opération. Pour de plus amples informations, veuillez consulter [Accorder à une AWS IoT règle l'accès dont elle a besoin](iot-create-role.md).
Dans la AWS IoT console, vous pouvez choisir ou créer un rôle pour autoriser l'exécution AWS IoT de cette action de règle.
+ Si vous utilisez un AWS KMS client géré AWS KMS key pour chiffrer des données au repos dans Amazon SQS, le service doit être autorisé à l'utiliser au nom AWS KMS key de l'appelant. Pour de plus amples informations, veuillez consulter [Key management](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/sqs-key-management.html) dans le *Guide du développeur Amazon Simple Storage Service*.
## Parameters
Lorsque vous créez une AWS IoT règle avec cette action, vous devez spécifier les informations suivantes :
`queueUrl`
URL de la file d'attente Amazon SQS dans laquelle les données doivent être écrites. La région indiquée dans cette URL ne doit pas nécessairement être identique à celle de votre Région AWS [AWS IoT règle](https://docs.aws.amazon.com/iot/latest/developerguide/iot-rules.html).
Des frais supplémentaires peuvent être facturés pour le transfert de données croisé Régions AWS à l'aide de l'action de règle SQS. Pour plus d'informations, consultez la [tarification d'Amazon SQS.](https://aws.amazon.com/sqs/pricing/)
Supporte les [modèles de substitution](iot-substitution-templates.md) : API et AWS CLI uniquement
`useBase64`
Définissez ce paramètre sur `true` pour configurer l'action de la règle afin de coder les données du message en base64 avant de les écrire dans la file d'attente Amazon SQS. La valeur par défaut est `false` .
Prend en charge les [modèles de substitution](iot-substitution-templates.md) : Non
`roleArn`
Le rôle IAM qui autorise l'accès à la file d'attente Amazon SQS. Pour de plus amples informations, veuillez consulter [Exigences](#sqs-rule-action-requirements).
Prend en charge les [modèles de substitution](iot-substitution-templates.md) : Non
## Exemples
L'exemple JSON suivant définit une action SQS dans une AWS IoT règle.
```
{
"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"
}
}
]
}
}
```
L'exemple JSON suivant définit une action SQS avec des modèles de substitution dans une AWS IoT règle.
```
{
"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"
}
}
]
}
}
```
## Consultez aussi
+ [Présentation d'Amazon Simple Queue Service](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/) dans le *Manuel du développeur Amazon Simple Queue Service*
# Step Functions
L'action Step Functions (`stepFunctions`) démarre une machine à AWS Step Functions états.
## Exigences
Cette action réglementaire est assortie des exigences suivantes :
+ Rôle IAM qui AWS IoT peut assumer la réalisation de l'`states:StartExecution`opération. Pour de plus amples informations, veuillez consulter [Accorder à une AWS IoT règle l'accès dont elle a besoin](iot-create-role.md).
Dans la AWS IoT console, vous pouvez choisir ou créer un rôle pour autoriser l'exécution AWS IoT de cette action de règle.
## Parameters
Lorsque vous créez une AWS IoT règle avec cette action, vous devez spécifier les informations suivantes :
`stateMachineName`
Le nom de la machine d'état Fonctions d'étape à démarrer.
Supporte les [modèles de substitution](iot-substitution-templates.md) : API et AWS CLI uniquement
`executionNamePrefix`
(Facultatif) Le nom donné à l'exécution de la machine d'état se compose de ce préfixe suivi d'un UUID. L'étape Fonctions crée un nom unique pour l'exécution de chaque machine d'état s'il n'y en a pas.
Prend en charge les [modèles de substitution](iot-substitution-templates.md) : Oui
`roleArn`
L'ARN du rôle qui AWS IoT autorise le démarrage de la machine à états. Pour de plus amples informations, veuillez consulter [Exigences](#stepfunctions-rule-action-requirements).
Prend en charge les [modèles de substitution](iot-substitution-templates.md) : Non
## Exemples
L'exemple JSON suivant définit une action Step Functions dans une AWS IoT règle.
```
{
"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"
}
}
]
}
}
```
## Consultez aussi
+ [Qu'est-ce que c'est AWS Step Functions ?](https://docs.aws.amazon.com/step-functions/latest/dg/) dans le *guide AWS Step Functions du développeur*
# Timestream
L'action de règle Timestream écrit les attributs (mesures) d'un message MQTT dans une table Amazon Timestream. Pour plus d'informations sur Amazon Timestream, veuillez consulter [Qu'est-ce qu'Amazon Timestream ?](https://docs.aws.amazon.com/timestream/latest/developerguide/what-is-timestream.html).
**Note**
Amazon Timestream n'est pas disponible dans tous les s. Région AWS Si Amazon Timestream n'est pas disponible dans votre région, il n'apparaîtra pas dans la liste des actions relatives aux règles.
Les attributs que cette règle stocke dans la base de données Timestream sont ceux qui résultent de l'instruction de requête de la règle. La valeur de chaque attribut dans le résultat de l'instruction de requête est analysée pour en déduire le type de données (comme dans le cas d'une [Dynamo DBv2](dynamodb-v2-rule-action.md) action). La valeur de chaque attribut est écrite dans son propre enregistrement dans la table Timestream. Pour spécifier ou modifier le type de données d'un attribut, utilisez la [`cast()`](iot-sql-functions.md#iot-sql-function-cast)fonction contenue dans l'instruction de requête. Pour de plus amples informations sur le contenu de chaque enregistrement Timestream, veuillez consulter. [Contenu d'un enregistrement Timestream](#timestream-rule-action-data)
**Note**
Avec SQL V2 (2016-03-23), les valeurs numériques qui sont des nombres entiers, telles que`10.0`, sont converties en leur représentation entière (). `10` Leur conversion explicite en une `Decimal` valeur, par exemple en utilisant la fonction [cast ()](iot-sql-functions.md#iot-sql-function-cast), n'empêche pas ce comportement : le résultat reste une `Integer` valeur. Cela peut provoquer des erreurs de non-concordance de type qui empêchent l'enregistrement des données dans la base de données Timestream. Pour traiter des valeurs numériques entières en tant que `Decimal` valeurs, utilisez SQL V1 (08/10/2015) pour l'instruction de requête de règle.
**Note**
Le nombre maximum de valeurs qu'une action de règle Timestream peut écrire dans une table Amazon Timestream est de 100. Pour de plus amples informations, veuillez consulter la [Référence d'Amazon Timestream Quota](https://docs.aws.amazon.com//timestream/latest/developerguide/ts-limits.html#limits.default).
## Exigences
Cette action réglementaire est assortie des exigences suivantes :
+ Rôle IAM qui AWS IoT peut assumer l'exécution des `timestream:WriteRecords` opérations `timestream:DescribeEndpoints` et. Pour de plus amples informations, veuillez consulter [Accorder à une AWS IoT règle l'accès dont elle a besoin](iot-create-role.md).
Dans la AWS IoT console, vous pouvez choisir, mettre à jour ou créer un rôle AWS IoT pour autoriser l'exécution de cette action de règle.
+ Si vous utilisez un client AWS KMS pour chiffrer des données inactives dans Timestream, le service doit être autorisé à les utiliser au nom de l'appelant. AWS KMS key Pour plus d'informations, consultez [Comment les AWS services utilisent AWS KMS](https://docs.aws.amazon.com/kms/latest/developerguide/service-integration.html).
## Parameters
Lorsque vous créez une AWS IoT règle avec cette action, vous devez spécifier les informations suivantes :
`databaseName`
Nom d'une base de données Amazon Timestream qui possède la table destinée à recevoir les enregistrements créés par cette action. Consultez également `tableName`.
Supporte les [modèles de substitution](iot-substitution-templates.md) : API et AWS CLI uniquement
`dimensions`
Attributs de métadonnées de la série chronologique qui sont écrits dans chaque enregistrement de mesure. Par exemple, le nom et la zone de disponibilité d'une instance EC2 ou le nom du fabricant d'une éolienne sont des dimensions.
`name`
Nom de la dimension de métadonnées. Il s'agit du nom de la colonne dans l'enregistrement de table de base de données.
Les dimensions ne peuvent pas être nommées : `measure_name``measure_value`, ou`time`. Ces alias sont réservés. Les noms de dimension ne peuvent pas commencer par `ts_` ou `measure_value` ne peuvent pas contenir le caractère deux-points (`:`).
Prend en charge les [modèles de substitution](iot-substitution-templates.md) : Non
`value`
Valeur à écrire dans cette colonne de l'enregistrement de base de données.
Prend en charge les [modèles de substitution](iot-substitution-templates.md) : Oui
`roleArn`
L'Amazon Resource Name (ARN) du rôle qui accorde à AWS IoT l'autorisation d'écrire dans la table de la base de données Timestream. Pour de plus amples informations, veuillez consulter [Exigences](#timestream-rule-action-requirements).
Prend en charge les [modèles de substitution](iot-substitution-templates.md) : Non
`tableName`
Nom de la table de la base de données dans laquelle les enregistrements de la mesure doivent être inscrits. Consultez également `databaseName`.
Supporte les [modèles de substitution](iot-substitution-templates.md) : API et AWS CLI uniquement
`timestamp`
Valeur à utiliser pour l'horodatage de l'entrée. Si le champ est vide, l'heure à laquelle l'entrée a été traitée est utilisée.
`unit`
Précision de la valeur d'horodatage résultant de l'expression décrite à la section `value`.
Valeurs valides: `SECONDS` \$1 `MILLISECONDS` \$1 `MICROSECONDS` \$1 `NANOSECONDS` La valeur par défaut est `MILLISECONDS`.
`value`
Expression qui renvoie une valeur temporelle de longue époque.
Vous pouvez utiliser cette [time\$1to\$1epoch (Chaîne, Chaîne)](iot-sql-functions.md#iot-sql-function-time-to-epoch) fonction pour créer un horodatage valide à partir d'une valeur de date ou d'heure transmise dans la charge utile du message.
## Contenu d'un enregistrement Timestream
Les données écrites dans la table Amazon Timestream par cette action incluent un horodatage, les métadonnées de l'action de règle Timestream et le résultat de l'instruction de requête de la règle.
Pour chaque attribut (mesure) du résultat de l'instruction de requête, cette action de règle écrit un enregistrement dans la table Timestream spécifiée avec ces colonnes.
| Nom de la colonne | Type d’attribut | Value | Commentaires |
| --- | --- | --- | --- |
| *dimension-name* | DIMENSION | La valeur spécifiée dans l'entrée d'action de la règle Timestream. | Chaque **dimension** spécifiée dans l'entrée d'action de règle crée une colonne dans la base de données Timestream avec le nom de la dimension. |
| nom\$1mesure | NOM\$1MESURE | Le nom de l'attribut | Nom de l'attribut figurant dans le résultat de l'instruction de requête dont la valeur est spécifiée dans la `measure_value::data-type` colonne. |
| valeur\$1mesure : *data-type* | VALEUR\$1MESURE | La valeur de l'attribut dans le résultat de l'instruction de requête. Le nom de l'attribut figure dans la `measure_name` colonne. | La valeur est interprétée\$1 et définie comme la correspondance la plus appropriée entre :`bigint`, `boolean``double`, ou. `varchar` Amazon Timestream crée une colonne distincte pour chaque type de données. La valeur du message peut être convertie en un autre type de données à l'aide de la [`cast()`](iot-sql-functions.md#iot-sql-function-cast)fonction contenue dans l'instruction de requête de la règle. |
| time | TIMESTAMP | Date et heure de l'enregistrement dans la base de données. | Cette valeur est attribuée par le moteur de règles ou par la `timestamp` propriété, si elle est définie. |
\$1 La valeur d'attribut lue à partir de la charge utile du message est interprétée comme suit. Voir le [Exemples](#timestream-rule-action-examples) pour une illustration de chacun de ces cas.
+ Une valeur sans guillemets de `true` ou `false` est interprétée comme un `boolean` type.
+ Un nombre décimal est interprété comme un `double` type.
+ Une valeur numérique sans point décimal est interprétée comme un `bigint` type.
+ Une chaîne entre guillemets est interprétée comme un `varchar` type.
+ Les objets et les valeurs des tableaux sont convertis en chaînes JSON et stockés sous forme `varchar` de type.
## Exemples
L'exemple JSON suivant définit une action de règle Timestream avec un modèle de substitution dans une AWS IoT règle.
```
{
"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"
}
}
]
}
}
```
L'utilisation de l'action de règle de rubrique Timestream définie dans l'exemple précédent avec la charge utile des messages suivante entraîne l'écriture des enregistrements Amazon Timestream dans le tableau ci-dessous.
```
{
"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"]
}
}
```
Le tableau suivant affiche les colonnes et les enregistrements de base de données créés à l'aide de l'action de règle de rubrique spécifiée pour traiter la charge utile du message précédent. Les `device_id` colonnes `device_firmware_sku` et sont les DIMENSIONS définies dans l'action de règle du sujet. L'action de règle de sujet Timestream crée la `time` colonne et les `measure_value::*` colonnes `measure_name` et, qu'elle remplit avec les valeurs issues du résultat de l'instruction de requête de l'action de règle de sujet.
| device\$1firmware\$1sku | device\$1id | nom\$1mesure | value\$1mesure : :bigint | valeur\$1mesure : varchar | valeur\$1mesure : double | value\$1mesure : :booléen | time |
| --- | --- | --- | --- | --- | --- | --- | --- |
| Mes métadonnées statiques | console IoT 159 -0 EXAMPLE738 | valeur\$1complexe | - | \$1"simple\$1element » :42, « array\$1of\$1integers » : [23,36,56,72], « tableau de chaînes » : ["rouge », « vert », « bleu"]\$1 | - | - | 26-08-2020- 22:42:16.423000000 |
| Mes métadonnées statiques | console IoT 159 -0 EXAMPLE738 | valeur\$1entière en tant que chaîne | - | 123456789012 | - | - | 26-08-2020- 22:42:16.423000000 |
| Mes métadonnées statiques | console IoT 159 -0 EXAMPLE738 | valeur\$1booléenne | - | - | - | TRUE | 26-08-2020- 22:42:16.423000000 |
| Mes métadonnées statiques | console IoT 159 -0 EXAMPLE738 | valeur\$1entière | 123456789012 | - | - | - | 26-08-2020- 22:42:16.423000000 |
| Mes métadonnées statiques | console IoT 159 -0 EXAMPLE738 | valeur\$1chaîne | - | Valeur de chaîne | - | - | 26-08-2020- 22:42:16.423000000 |
| Mes métadonnées statiques | console IoT 159 -0 EXAMPLE738 | tableau d'entiers | - | [23,36,56,72] | - | - | 26-08-2020- 22:42:16.423000000 |
| Mes métadonnées statiques | console IoT 159 -0 EXAMPLE738 | tableau de chaînes | - | ["rouge », « vert », « bleu"] | - | - | 26-08-2020- 22:42:16.423000000 |
| Mes métadonnées statiques | console IoT 159 -0 EXAMPLE738 | valeur\$1booléenne en tant que chaîne | - | TRUE | - | - | 26-08-2020- 22:42:16.423000000 |
| Mes métadonnées statiques | console IoT 159 -0 EXAMPLE738 | valeur\$1double | - | - | 123,456789012 | - | 26-08-2020- 22:42:16.423000000 |
| Mes métadonnées statiques | Iotconsole-159 -0 EXAMPLE738 | double\$1value\$1as\$1string | - | 123,45679 | - | - | 26-08-2020- 22:42:16.423000000 |
## Résolution des problèmes d'une règle
Si vous rencontrez un problème avec vos règles, nous vous recommandons d'activer CloudWatch Logs. Vous pouvez analyser vos journaux pour déterminer s'il s'agit d'un problème d'autorisation ou si, par exemple, une condition de la clause WHERE n'a pas été respectée. Pour plus d'informations, voir [Configuration CloudWatch des journaux](https://docs.aws.amazon.com/iot/latest/developerguide/cloud-watch-logs.html).
# Accès aux ressources entre comptes à l'aide AWS IoT de règles
Vous pouvez configurer des AWS IoT règles d'accès entre comptes afin que les données ingérées sur les sujets MQTT d'un compte puissent être acheminées vers les AWS services, tels qu'Amazon SQS et Lambda, d'un autre compte. Ce qui suit explique comment configurer des AWS IoT règles pour l'ingestion de données entre comptes, qu'il s'agisse d'un sujet MQTT dans un compte ou d'une destination dans un autre compte.
Les règles entre comptes peuvent être configurées à l'aide d'[autorisations basées sur les ressources](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_controlling.html#TypesPermissions) sur la ressource de destination. Par conséquent, seules les destinations qui prennent en charge les autorisations basées sur les ressources peuvent être activées pour l'accès entre comptes avec des règles. AWS IoT Les destinations prises en charge incluent Amazon SQS, Amazon SNS, Amazon S3 et. AWS Lambda
**Note**
Pour les destinations prises en charge, à l'exception d'Amazon SQS, vous devez définir la règle de la même manière Région AWS que la ressource d'un autre service afin que l'action de la règle puisse interagir avec cette ressource. Pour plus d'informations sur les actions des AWS IoT règles, consultez la section [Actions des AWS IoT règles](iot-rule-actions.md). Pour plus d'informations sur l'action SQS de la règle, consultez[SQS](sqs-rule-action.md).
## Conditions préalables
+ [Connaissance des règles AWS IoT](https://docs.aws.amazon.com/iot/latest/developerguide/iot-rules.html)
+ Compréhension des [utilisateurs, des [rôles](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html) et des autorisations basées sur les [ressources](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_permissions.html#TypesPermissions) IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/introduction_identity-management.html)
+ Après avoir [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-install.html)installé
## Configuration entre comptes pour Amazon SQS
Scénario : le compte A envoie les données d'un message MQTT à la file d'attente Amazon SQS du compte B.
| Compte AWS | Compte désigné comme | Description |
| --- | --- | --- |
| 1111-1111-1111 | Compte A | Action de la règle sqs:SendMessage |
| 2222-2222-2222 | Compte B | File d’attente Amazon SQS [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/fr_fr/iot/latest/developerguide/accessing-cross-account-resources-using-rules.html) |
**Note**
[Il n'est pas nécessaire que votre file d'attente Amazon SQS de destination se trouve dans la même zone Région AWS que votre AWS IoT règle.](https://docs.aws.amazon.com/iot/latest/developerguide/iot-rules.html) Pour plus d'informations sur l'action SQS de la règle, consultez[SQS](sqs-rule-action.md).
**Faire la tâches du compte A**
**Remarque**
Pour exécuter les commandes suivantes, votre utilisateur IAM doit être autorisé `iot:CreateTopicRule` à utiliser le nom de ressource Amazon (ARN) de la règle comme ressource et à `iam:PassRole` agir avec une ressource comme ARN du rôle.
1. [Configurez AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-quickstart.html) à l'aide de l'utilisateur IAM du compte A.
1. Créez un rôle IAM qui fait confiance au moteur de AWS IoT règles et qui associe une politique autorisant l'accès à la file d'attente Amazon SQS du compte B. Consultez des exemples de commandes et de documents de politique dans la section [Octroi AWS IoT de l'accès requis](https://docs.aws.amazon.com/iot/latest/developerguide/iot-create-role.html).
1. Pour créer une règle attachée à une rubrique, exécutez la [create-topic-rule commande](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
```
Voici un exemple de fichier de données utiles avec une règle qui insère tous les messages envoyés au `iot/test`sujet dans la file d'attente Amazon SQS spécifiée. L'instruction SQL filtre les messages et le rôle ARN AWS IoT accorde des permissions d'ajouter le message à la file d'attente 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
}
}
]
}
```
Pour plus d'informations sur la définition d'une action Amazon SQS dans une AWS IoT règle, consultez [Actions de AWS IoT règles - Amazon SQS.](https://docs.aws.amazon.com/iot/latest/developerguide/sqs-rule-action.html)
**Faire la tâches du compte B**
1. [Configurez AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-quickstart.html) à l'aide de l'utilisateur IAM du compte B.
1. Pour autoriser le compte A à accéder à la ressource de file d'attente Amazon SQS, exécutez la [commande](https://docs.aws.amazon.com/cli/latest/reference/sqs/add-permission.html) add permission.
```
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
```
## Configuration de comptes croisés pour Amazon SNS
Scénario : Le compte A envoie des données d'un message MQTT à une rubrique Amazon SNS du compte B.
| Compte AWS | Compte désigné comme | Description |
| --- | --- | --- |
| 1111-1111-1111 | Compte A | Action de la règle sns:Publish |
| 2222-2222-2222 | Compte B | ARN de rubrique Amazon SNS : arn:aws:sns:region:2222-2222-2222:ExampleTopic |
**Faire la tâches du compte A**
**Remarques**
Pour exécuter les commandes suivantes, votre utilisateur IAM doit être autorisé à utiliser `iot:CreateTopicRule` la règle ARN comme ressource et à effectuer l'`iam:PassRole`action avec une ressource comme ARN de rôle.
1. [Configurez AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-quickstart.html) à l'aide de l'utilisateur IAM du compte A.
1. Créez un rôle IAM qui fait confiance au moteur de AWS IoT règles et qui associe une politique autorisant l'accès à la rubrique Amazon SNS du compte B. Pour des exemples de commandes et de documents de politique, consultez la section [Octroi AWS IoT de l'accès requis](https://docs.aws.amazon.com/iot/latest/developerguide/iot-create-role.html).
1. Pour créer une règle attachée à une rubrique, exécutez la [create-topic-rule commande](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
```
Voici un exemple de fichier de données utiles avec une règle qui insère tous les messages envoyés au `iot/test` sujet dans le sujet Amazon SNS spécifié. L'instruction SQL filtre les messages et le rôle ARN accorde les AWS IoT autorisations nécessaires pour envoyer le message au sujet 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"
}
}
]
}
```
Pour plus d'informations sur la définition d'une action Amazon SNS dans une AWS IoT règle, consultez [Actions de AWS IoT règle - Amazon SNS](https://docs.aws.amazon.com/iot/latest/developerguide/sns-rule-action.html).
**Faire la tâches du compte B**
1. [Configurez AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-quickstart.html) à l'aide de l'utilisateur IAM du compte B.
1. Pour autoriser le compte A à accéder à la ressource thématique Amazon SNS, exécutez la [commande](https://docs.aws.amazon.com/cli/latest/reference/sns/add-permission.html) add permission.
```
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
```
## Configuration entre comptes pour Amazon S3
Scénario : Le compte A envoie des données d'un message MQTT vers un compartiment Amazon S3 du compte B.
| Compte AWS | Compte désigné comme | Description |
| --- | --- | --- |
| 1111-1111-1111 | Compte A | Action de la règle s3:PutObject |
| 2222-2222-2222 | Compte B | Compartiments Amazon S3 : arn:aws:s3:::amzn-s3-demo-bucket |
**Faire la tâches du compte A**
**Remarque**
Pour exécuter les commandes suivantes, votre utilisateur IAM doit être autorisé à `iot:CreateTopicRule` utiliser la règle ARN comme ressource et à `iam:PassRole` agir avec une ressource comme ARN de rôle.
1. [Configurez AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-quickstart.html) à l'aide de l'utilisateur IAM du compte A.
1. Créez un rôle IAM qui fait confiance au moteur de AWS IoT règles et qui associe une politique autorisant l'accès au compartiment Amazon S3 du compte B. Pour des exemples de commandes et de documents de politique, consultez la section [Octroi AWS IoT de l'accès requis](https://docs.aws.amazon.com/iot/latest/developerguide/iot-create-role.html).
1. Pour créer une règle attachée à votre compartiment S3 cible, exécutez la [create-topic-rule commande](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
```
Voici un exemple de fichier de données utiles avec une règle qui insère tous les messages envoyés au `iot/test` sujet dans le compartiment Amazon S3 spécifié. L'instruction SQL filtre les messages et le rôle ARN accorde les AWS IoT autorisations nécessaires pour ajouter le message au compartiment 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"
}
}
]
}
```
Pour plus d'informations sur la façon de définir une action Amazon S3 dans une AWS IoT règle, consultez [Actions de AWS IoT règle - Amazon S3](https://docs.aws.amazon.com/iot/latest/developerguide/s3-rule-action.html).
**Faire la tâches du compte B**
1. [Configurez AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-quickstart.html) à l'aide de l'utilisateur IAM du compte B.
1. Créez une politique de compartiment qui fait confiance au principal du compte A.
Voici un exemple de fichier de charge utile qui définit une politique de compartiment qui fait confiance au principal d'un autre compte.
****
```
{
"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/*"
}
]
}
```
Pour plus d'informations, veuillez consulter [bucket policy examples](https://docs.aws.amazon.com/AmazonS3/latest/userguide/example-bucket-policies.html#example-bucket-policies-use-case-1).
1. Pour associer la politique de compartiment au compartiment spécifié, exécutez la [put-bucket-policy commande](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. Pour que l'accès entre comptes fonctionne, assurez-vous que les paramètres **Bloquer tout accès public** sont corrects. Pour plus d'informations, consultez [Security Best Practices for Amazon S3](https://docs.aws.amazon.com/AmazonS3/latest/userguide/security-best-practices.html).
## Configuration de comptes multiples pour AWS Lambda
Scénario : le compte A invoque une AWS Lambda fonction du compte B en transmettant un message MQTT.
| Compte AWS | Compte désigné comme | Description |
| --- | --- | --- |
| 1111-1111-1111 | Compte A | Action de la règle lambda:InvokeFunction |
| 2222-2222-2222 | Compte B | ARN de fonction Lambda : arn:aws:lambda:region:2222-2222-2222:function:example-function |
**Faire la tâches du compte A**
**Remarques**
Pour exécuter les commandes suivantes, votre utilisateur IAM doit être autorisé à `iot:CreateTopicRule` utiliser la règle ARN comme ressource et à `iam:PassRole` agir avec la ressource comme ARN de rôle.
1. [Configurez AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-quickstart.html) à l'aide de l'utilisateur IAM du compte A.
1. Exécutez la [create-topic-rule commande](https://docs.aws.amazon.com/cli/latest/reference/iot/create-topic-rule.html) pour créer une règle qui définit l'accès entre comptes à la fonction Lambda du compte B.
```
aws iot create-topic-rule --rule-name my-rule --topic-rule-payload file://./my-rule.json
```
Voici un exemple de fichier de charge utile avec une règle qui insère tous les messages envoyés au `iot/test` sujet dans la fonction Lambda spécifiée. L'instruction SQL filtre les messages et l'ARN du rôle accorde AWS IoT l'autorisation de transmettre les données à la fonction 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"
}
}
]
}
```
Pour plus d'informations sur la définition d'une AWS Lambda action dans une AWS IoT règle, consultez la section [Actions de AWS IoT règles - Lambda](https://docs.aws.amazon.com/iot/latest/developerguide/lambda-rule-action.html).
**Faire la tâches du compte B**
1. [Configurez AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-quickstart.html) à l'aide de l'utilisateur IAM du compte B.
1. Exécutez la [commande add permission de Lambda](https://docs.aws.amazon.com/cli/latest/reference/lambda/add-permission.html) pour autoriser les AWS IoT règles à activer la fonction Lambda. Pour exécuter la commande suivante, votre utilisateur IAM doit être autorisé à `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"
```
**Options :**
**--principal**
Ce champ autorise AWS IoT (représenté par`iot.amazonaws.com`) à appeler la fonction Lambda.
**--source-arn**
Ce champ confirme que cette fonction Lambda ne peut être activée que `arn:aws:iot:region:1111-1111-1111:rule/example-rule` dans les AWS IoT déclencheurs et qu'aucune autre règle du même compte ou d'un compte différent ne peut activer cette fonction Lambda.
**--source-account**
Ce champ confirme que AWS IoT cette fonction Lambda est activée uniquement pour le `1111-1111-1111` compte.
**Remarques**
Si le message d'erreur « La règle est introuvable » s'affiche sur la console de votre AWS Lambda fonction sous **Configuration**, ignorez le message d'erreur et testez la connexion.
# Gestion des erreurs (action d'erreur)
Lorsqu'il AWS IoT reçoit un message d'un appareil, le moteur de règles vérifie si le message correspond à une règle. Si c'est le cas, l'instruction de requête de la règle est évaluée et les actions de la règle sont activées, en transmettant le résultat de l'instruction de requête.
Si un problème survient lors de l'activation d'une action, le moteur de règles active une action d'erreur, si une telle action est spécifiée pour la règle. Cela peut se produire dans les cas suivants :
+ Une règle n'a pas l'autorisation d'accéder à un compartiment Amazon S3.
+ Une erreur de l'utilisateur entraîne un dépassement du DynamoDB provisioned throughput
**Note**
La gestion des erreurs abordée dans cette rubrique concerne les [actions relatives aux règles](iot-rule-actions.md). Pour résoudre les problèmes SQL, y compris les fonctions externes, vous pouvez configurer la AWS IoT journalisation. Pour de plus amples informations, veuillez consulter [Configuration de la AWS IoT journalisation](configure-logging.md).
## Format du message d'action d'erreur
Un seul message est généré par la règle et par message. Par exemple, si deux actions de règle échouent dans une même règle, l'action d'erreur reçoit un message contenant les deux erreurs.
Par exemple, le message d'erreur ressemble à ce qui suit :
```
{
"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
Nom de la règle qui a déclenché l'action d'erreur.
topic
Rubrique dans laquelle le message d'origine a été reçu.
cloudwatchTraceId
Une identité unique faisant référence à l'erreur se connecte CloudWatch.
clientId
ID client de l'éditeur du message.
base 64 OriginalPayload
Charge utile du message d'origine codée en base64.
échecs
failedAction
Nom de l'action qui a échoué, par exemple « S3Action ».
failedResource
Nom de la ressource. Par exemple, le nom d'un compartiment S3.
errorMessage
Description et explication de l'erreur.
## Exemple d'action d'erreur
Voici un exemple de règle à laquelle a été ajoutée une action d'erreur. La règle suivante comporte une action qui écrit les données du message dans une table DynamoDB et une action d'erreur qui écrit les données dans un panier 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()}"
}
}
}
```
Vous pouvez utiliser n'importe quelle [fonction](iot-sql-functions.md) ou [modèle de substitution](https://docs.aws.amazon.com//iot/latest/developerguide/iot-substitution-templates.html) dans l'instruction SQL d'une action d'erreur, y compris les fonctions externes : [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-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), et [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). Si une action d'erreur nécessite l'appel d'une fonction externe, l'invocation de l'action d'erreur peut entraîner une facture supplémentaire pour la fonction externe.
Pour plus d'informations sur les règles et sur la manière de spécifier une action d'erreur, consultez la section [Création d'une AWS IoT règle](https://docs.aws.amazon.com//iot/latest/developerguide/iot-create-rule.html).
Pour plus d'informations sur l'utilisation CloudWatch pour surveiller le succès ou l'échec des règles, consultez[AWS IoT métriques et dimensions](metrics_dimensions.md).
# Réduction des coûts de messagerie avec Basic Ingest
[Vous pouvez utiliser Basic Ingest pour envoyer en toute sécurité les données de l'appareil aux personnes Services AWS prises en charge par[AWS IoT actions liées aux règles](iot-rule-actions.md), sans frais de messagerie.](https://aws.amazon.com/iot-core/pricing/) Basic Ingest optimise le flux de données en supprimant l’agent de messages de publication/abonnement du chemin d'ingestion.
Basic Ingest peut envoyer des messages depuis vos appareils ou applications. Les messages ont des noms de rubrique qui commencent par `$aws/rules/rule_name` les trois premiers niveaux, où `rule_name` est le nom de la AWS IoT règle que vous souhaitez invoquer.
Vous pouvez utiliser une règle existante avec Basic Ingest en ajoutant simplement le préfixe Basic Ingest (`$aws/rules/rule_name`) à la rubrique du message par lequel vous invoquez normalement la règle. Par exemple, si vous avez une règle nommée `BuildingManager` qui est invoquée par des messages avec des sujets tels que `Buildings/Building5/Floor2/Room201/Lights` (`"sql": "SELECT * FROM 'Buildings/#'"`), vous pouvez invoquer la même règle avec Basic Ingest en envoyant un message avec le sujet `$aws/rules/BuildingManager/Buildings/Building5/Floor2/Room201/Lights`.
**Note**
Vos appareils et vos règles ne peuvent pas s'abonner aux rubriques réservées Basic Ingest. Par exemple, les AWS IoT Device Defender `num-messages-received` métriques ne sont pas émises car elles ne permettent pas de s'abonner à des sujets. Pour de plus amples informations, veuillez consulter [Rubriques réservées](reserved-topics.md).
Si vous avez besoin d'un courtier de publication/d'abonnement pour distribuer des messages à plusieurs abonnés (par exemple, pour envoyer des messages à d'autres appareils et au moteur de règles), vous devez continuer à utiliser le courtier de AWS IoT messages pour gérer la distribution des messages. Cependant, il suffit de publier vos messages dans des rubriques autres que les rubriques Basic Ingest.
## Utilisation de Basic Ingest
Avant d'utiliser Basic Ingest, vérifiez que votre appareil ou application utilise une [politique](iot-policies.md) sur laquelle des autorisations de publication sont activées `$aws/rules/*`. Vous pouvez également spécifier des autorisations pour des règles individuelles `$aws/rules/rule_name/*` dans la politique. Sinon, vos appareils et applications peuvent continuer à utiliser leurs connexions existantes avec AWS IoT Core.
Lorsque le message atteint le moteur de règles, il n'existe pas de différence dans l'exécution ou la gestion des erreurs entre les règles invoquées à partir de Basic Ingest et celles invoquées via des abonnements d'agent de messages.
Vous pouvez créer des règles à utiliser avec Basic Ingest. Gardez à l’esprit les points suivants :
+ Le préfixe initial d'une rubrique Basic Ingest (`$aws/rules/rule_name`) n'est pas disponible pour la fonction [topic(Decimal)](iot-sql-functions.md#iot-function-topic).
+ Si vous définissez une règle qui est invoquée uniquement avec Basic Ingest, la clause `FROM` est facultative dans le champ `sql` de la définition `rule`. Elle est encore requise si la règle est également invoquée par d'autres messages qui doivent être envoyés via l'agent de messages (par exemple, parce que ces autres messages doivent être distribués à plusieurs abonnés). Pour de plus amples informations, veuillez consulter [AWS IoT Référence SQL](iot-sql-reference.md).
+ Les trois premiers niveaux de la rubrique Basic Ingest (`$aws/rules/rule_name`) ne sont pas comptabilisés dans la limite de longueur des 8 segments ou des 256 caractères maximum pour une rubrique. Sinon, les mêmes restrictions que celles documentées dans [AWS IoT Limites](https://docs.aws.amazon.com/general/latest/gr/iot-core.html#limits_iot) s'appliquent.
+ Si un message contenant une rubrique Basic Ingest spécifiant une règle inactive ou inexistante est reçu, un journal des erreurs est créé dans un CloudWatch journal Amazon pour vous aider à effectuer le débogage. Pour de plus amples informations, veuillez consulter [Entrées de journal du moteur de règles](cwl-format.md#rule-engine-logs). Une métrique `RuleNotFound` est indiquée et vous pouvez créer des alarmes sur cette métrique. Pour de plus amples informations, veuillez consulter Métriques dans [Métriques de règle](metrics_dimensions.md#rulemetrics).
+ Vous pouvez toujours publier avec QoS 1 dans des rubriques Basic Ingest. Vous recevez un message une PUBACK fois que le message a été envoyé avec succès au moteur de règles. Le fait de recevoir un PUBACK ne signifie pas que vos actions relatives aux règles ont été effectuées avec succès. Vous pouvez configurer une action d'erreur pour gérer les erreurs lors de l'exécution de l'action. Pour de plus amples informations, veuillez consulter [Gestion des erreurs (action d'erreur)](rule-error-handling.md).
# AWS IoT Référence SQL
Dans AWS IoT, les règles sont définies à l'aide d'une syntaxe de type SQL. Les instructions SQL se composent de trois types de clauses :
**SET**
(Facultatif) Définit les variables que vous pouvez réutiliser dans les instructions SQL et les modèles de substitution. Attribuez des valeurs aux variables à l'aide d'expressions. Référencez ces variables dans les clauses SELECT et WHERE, ainsi que dans les modèles de substitution d'actions.
La clause SET prend en charge les [variables [Types de données](iot-sql-data-types.md)[Opérateurs](iot-sql-operators.md)[Fonctions](iot-sql-functions.md)[Littéraux](iot-sql-literals.md)](iot-sql-set.md#iot-sql-set-usage),[Instructions Case](iot-sql-case.md),[Extensions JSON](iot-sql-json.md),,, et[Requêtes d'objets imbriqués](iot-sql-nested-queries.md).
**SELECT**
(Obligatoire) Extrait des informations de la charge utile d’un message entrant et effectue des transformations sur ces informations. Les messages à utiliser sont identifiés par le [filtre de rubrique](topics.md#topicfilters) spécifié dans la clause FROM.
La clause SELECT prend en charge les [variables [Types de données](iot-sql-data-types.md)[Opérateurs](iot-sql-operators.md)[Fonctions](iot-sql-functions.md)[Littéraux](iot-sql-literals.md)[Instructions Case](iot-sql-case.md)[Extensions JSON](iot-sql-json.md)](iot-sql-set.md#iot-sql-set-usage),[Modèles de substitution](iot-substitution-templates.md),,,,[Requêtes d'objets imbriqués](iot-sql-nested-queries.md), et[Charges utiles binaires](binary-payloads.md).
**FROM**
Le [filtre de sujet](topics.md#topicfilters) des messages MQTT qui identifie les messages dont les données doivent être extraites. La règle est activée pour chaque message envoyé à une rubrique MQTT qui correspond au filtre de rubrique défini ici. Requis pour les règles qui sont activées par les messages qui passent par l’agent de messages. Facultatif pour les règles qui sont activées uniquement à l’aide de la fonctionnalité [Basic Ingest](iot-basic-ingest.md).
**WHERE**
(Facultatif) Ajoute une logique conditionnelle qui détermine si les actions spécifiées par une règle sont exécutées.
La clause WHERE prend en charge les [variables [Types de données](iot-sql-data-types.md)[Opérateurs](iot-sql-operators.md)[Fonctions](iot-sql-functions.md)[Littéraux](iot-sql-literals.md)[Instructions Case](iot-sql-case.md)](iot-sql-set.md#iot-sql-set-usage),[Extensions JSON](iot-sql-json.md),,,, et[Requêtes d'objets imbriqués](iot-sql-nested-queries.md).
Un exemple d'instruction SQL se présente sous la forme suivante :
```
SELECT color AS rgb FROM 'topic/subtopic' WHERE temperature > 50
```
Un exemple de message MQTT (également appelé charge entrante) se présente sous la forme suivante :
```
{
"color":"red",
"temperature":100
}
```
Si ce message est publié dans la rubrique `'topic/subtopic'`, la règle est déclenchée et l'instruction SQL est évaluée. L'instruction SQL extrait la valeur de la propriété `color` si la propriété `"temperature"` est supérieure à 50. La clause WHERE spécifie la condition `temperature > 50`. Le mot-clé `AS` change le nom de la propriété `"color"` en `"rgb"`. Le résultat (également appelé *charge sortante*) se présente sous la forme suivante :
```
{
"rgb":"red"
}
```
Ces données sont alors transférées vers l'action de la règle qui envoie les données pour traitement supplémentaire. Pour plus d'informations sur les actions de règle, consultez [AWS IoT actions liées aux règles](iot-rule-actions.md).
**Note**
Les commentaires ne sont actuellement pas pris en charge dans la syntaxe AWS IoT SQL.
Les noms d’attributs contenant des espaces ne peuvent pas être utilisés comme noms de champs dans l’instruction SQL. Bien que la charge utile entrante puisse comporter des noms d’attributs contenant des espaces, ces noms ne peuvent pas être utilisés dans l’instruction SQL. Ils seront toutefois transmis à la charge utile sortante si vous utilisez une spécification de nom de champ générique (\$1).
# Clause SELECT
La clause AWS IoT SELECT est essentiellement identique à la clause ANSI SQL SELECT, avec quelques différences mineures.
La clause SELECT prend en charge [Types de données](iot-sql-data-types.md) les [variables [Opérateurs](iot-sql-operators.md)[Fonctions](iot-sql-functions.md)[Littéraux](iot-sql-literals.md)[Instructions Case](iot-sql-case.md)[Extensions JSON](iot-sql-json.md)](iot-sql-set.md#iot-sql-set-usage),,,,[Requêtes d'objets imbriqués](iot-sql-nested-queries.md), et[Charges utiles binaires](binary-payloads.md).
Vous pouvez utiliser la clause SELECT pour extraire les informations des messages entrants MQTT. Une clause `SELECT *` peut être utilisée pour récupérer toute la charge utile du message entrant. Par exemple :
```
Incoming payload published on topic 'topic/subtopic': {"color":"red", "temperature":50}
SQL statement: SELECT * FROM 'topic/subtopic'
Outgoing payload: {"color":"red", "temperature":50}
```
Si la charge utile est un objet JSON, vous pouvez référencer des clés dans l'objet. Votre charge utile sortante contient la paire clé-valeur. Par exemple :
```
Incoming payload published on topic 'topic/subtopic': {"color":"red", "temperature":50}
SQL statement: SELECT color FROM 'topic/subtopic'
Outgoing payload: {"color":"red"}
```
Vous pouvez utiliser le même mot-clé AS pour renommer des clés. Par exemple :
```
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"}
```
Vous pouvez sélectionner plusieurs éléments en les séparant par une virgule. Par exemple :
```
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}
```
Vous pouvez sélectionner plusieurs éléments comprenant « \$1 » pour ajouter des éléments dans la charge utile entrante. Par exemple :
```
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}
```
Vous pouvez utiliser le mot-clé `"VALUE"` pour produire les charges utiles sortantes qui ne sont pas des objets JSON. Avec la version SQL `2015-10-08`, vous ne pouvez sélectionner qu'un seul élément. Avec la version SQL `2016-03-23` ou une version ultérieure, vous pouvez également sélectionner un tableau à afficher en tant qu'objet de niveau supérieur.
**Example**
```
Incoming payload published on topic 'topic/subtopic': {"color":"red", "temperature":50}
SQL: SELECT VALUE color FROM 'topic/subtopic'
Outgoing payload: "red"
```
Vous pouvez utiliser une syntaxe `'.'` pour explorer des objets JSON imbriqués dans la charge utile entrante. Par exemple :
```
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}
```
Pour plus d’informations sur l’utilisation des noms d’objets et de propriétés JSON qui incluent des caractères réservés, tels que des chiffres ou le trait d’union (moins), veuillez consulter [Extensions JSON](iot-sql-json.md)
Vous pouvez utiliser des fonctions (voir [Fonctions](iot-sql-functions.md)) pour transformer la charge utile entrante. Vous pouvez utiliser des parenthèses pour le regroupement. Par exemple :
```
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"}
```
# Clause FROM
La clause FROM abonne votre règle à une [rubrique](topics.md#topicnames) ou à un [filtre de rubriques](topics.md#topicfilters). Mettez le sujet ou le filtre du sujet entre guillemets simples ('). La règle est déclenchée pour chaque message envoyé à une rubrique MQTT qui correspond au filtre de rubrique défini ici. Vous pouvez vous abonner à un groupe de sujets similaires à l’aide d’un filtre de sujet.
**Exemple :**
Charge utile entrante publiée dans une rubrique `'topic/subtopic'` : `{temperature: 50}`
Charge utile entrante publiée dans une rubrique `'topic/subtopic-2'` : `{temperature: 50}`
SQL : `"SELECT temperature AS t FROM 'topic/subtopic'"`.
`'topic/subtopic'` est abonné à la règle, de sorte que la charge utile entrante soit transmise à la règle. La charge utile sortante, transmise aux actions de règle, est : `{t: 50}`. La règle n'est pas abonnée à `'topic/subtopic-2'`, donc la règle n'est pas déclenchée pour le message publié sur `'topic/subtopic-2'`.
**Exemple de caractère générique \$1 :**
Vous pouvez utiliser le caractère générique « \$1 » (multiniveau) pour correspondre à un ou plusieurs éléments de chemin particuliers :
Charge utile entrante publiée dans une rubrique `'topic/subtopic'` : `{temperature: 50}`.
Charge utile entrante publiée dans une rubrique `'topic/subtopic-2'` : `{temperature: 60}`.
Charge utile entrante publiée dans une rubrique `'topic/subtopic-3/details'` : `{temperature: 70}`.
Charge utile entrante publiée dans une rubrique `'topic-2/subtopic-x'` : `{temperature: 80}`.
SQL : `"SELECT temperature AS t FROM 'topic/#'"`.
La règle est abonnée à n'importe quel sujet commençant par. Elle est donc exécutée trois fois`'topic'`, envoyant des charges utiles sortantes de `{t: 50}` (pour le sujet/sous-sujet), (pour le sujet/sous-thème 2) et `{t: 60}` (pour) à ses actions. `{t: 70}` topic/subtopic-3/details Il n’y a pas d’abonnement à `'topic-2/subtopic-x'`, la règle n’est donc pas déclenchée pour le message `{temperature: 80}`.
**Exemple de caractère générique \$1 :**
Vous pouvez utiliser le caractère générique « \$1 » (un seul niveau) pour correspondre à tout élément de chemin particulier :
Charge utile entrante publiée dans une rubrique `'topic/subtopic'` : `{temperature: 50}`.
Charge utile entrante publiée dans une rubrique `'topic/subtopic-2'` : `{temperature: 60}`.
Charge utile entrante publiée dans une rubrique `'topic/subtopic-3/details'` : `{temperature: 70}`.
Charge utile entrante publiée dans une rubrique `'topic-2/subtopic-x'` : `{temperature: 80}`.
SQL : `"SELECT temperature AS t FROM 'topic/+'"`.
La règle est abonnée à toutes les rubriques avec deux éléments de chemin où le premier élément est `'topic'`. La règle est exécutée pour les messages envoyés à `'topic/subtopic'` e t`'topic/subtopic-2'`, mais pas `'topic/subtopic-3/details'` (elle comporte plus de niveaux que le filtre de rubrique) ou `'topic-2/subtopic-x'` (elle ne commence pas par `topic`).
# Clause SET
Utilisez la clause SET pour définir les variables qui stockent les résultats des expressions. Vous pouvez réutiliser ces variables dans les clauses SELECT et WHERE, ainsi que dans les modèles de substitution. Cela vous permet d'éviter de dupliquer des expressions complexes et de réduire le nombre d'appels de fonction dans votre instruction SQL.
La clause SET prend en charge les [variables [Types de données](iot-sql-data-types.md)[Opérateurs](iot-sql-operators.md)[Fonctions](iot-sql-functions.md)[Littéraux](iot-sql-literals.md)](#iot-sql-set-usage),[Instructions Case](iot-sql-case.md),[Extensions JSON](iot-sql-json.md),,, et[Requêtes d'objets imbriqués](iot-sql-nested-queries.md).
## Syntaxe de la clause SET
La clause SET doit apparaître avant la clause SELECT dans votre instruction SQL. Utilisez la syntaxe suivante :
```
SET @variable_name = expression [, @variable_name2 = expression2]
```
Règles de syntaxe :
+ Commencez les noms de variables par `@`
+ Les noms de variables peuvent contenir des lettres, des chiffres et des traits de soulignement
+ Les noms de variables peuvent comporter jusqu'à 64 caractères
+ Plusieurs variables peuvent être définies dans une seule clause SET, séparées par des virgules
+ Chaque variable ne peut être affectée qu'une seule fois (les variables sont immuables)
+ Le mot clé SET ne peut être utilisé qu'une seule fois par instruction SQL
## Utilisation de variables
Après avoir défini les variables, vous pouvez les utiliser dans :
+ CLAUSES SELECT
+ clauses WHERE
+ Autres assignations de variables SET
+ Modèles de substitution d'actions
+ Modèles de substitution d'actions en cas d'erreur
+ Requêtes SELECT imbriquées
+ Paramètres de fonction (certains paramètres tels que les paramètres ROLearn et les paramètres qui changent le mode d'une fonction de manière similaire à ceux qui `transform("enrichArray", attributes, values)` ne prennent pas en charge les variables)
Les variables sont référencées selon la même `@variable_name` syntaxe que celle utilisée dans la clause SET. Vous pouvez également utiliser la syntaxe d'extension JSON pour accéder aux propriétés des variables contenant des objets, telles que`@variable_name.property`.
## Exemples de clauses SET
**Utilisation des variables de base**
L'exemple suivant montre une charge utile publiée sur le sujet `device/data` : `{"temp_fahrenheit": 75, "humidity": 60}`
Instruction SQL :
```
SET @temp_celsius = (temp_fahrenheit - 32) * 5 / 9
SELECT @temp_celsius AS celsius, humidity FROM 'device/data'
```
Charge utile sortante : `{"celsius": 23.89, "humidity": 60}`
**Accès aux membres dans les objets JSON intégrés**
L'exemple suivant montre une charge utile publiée sur le sujet `device/data` : `{"device1": {"deviceId":"weather_sensor", "deviceData": {"sensors": {"temp_fahrenheit": 75, "humidity": 60}, "location": [47.606,-122.332]}}}`
Instruction 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'
```
Charge utile sortante : `{"temp_fahrenheit":75,"humidity":60,"deviceId":"weather_sensor"}`
pour plus d'informations sur l'utilisation des extensions JSON, consultez [Extensions JSON](iot-sql-json.md)
**Éviter les appels de fonction dupliqués**
Les variables SET permettent d'éviter de dupliquer des opérations de décodage complexes :
```
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
```
Sans les variables SET, vous devrez répéter la fonction de décodage trois fois, ce qui dépasse les limites d'appels de fonction.
**Variables multiples**
Vous pouvez définir plusieurs variables dans une seule clause SET en les séparant par des virgules :
```
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
```
**Utilisation de variables dans les modèles de substitution**
Les variables peuvent également être utilisées dans les modèles de substitution d'actions, ce qui vous permet de réutiliser les valeurs calculées à la fois dans l'instruction SQL et dans les actions de règle.
Instruction SQL :
```
SET @temp_celsius = (temp_fahrenheit - 32) * 5 / 9
SELECT @temp_celsius AS celsius, humidity FROM 'device/data'
```
Configuration de l'action :
```
{
"s3": {
"roleArn": "arn:aws:iam::123456789012:role/testRuleRole",
"bucketName": "bucket",
"key": "temperature-data/${device_id}/temp-${@temp_celsius}C.json"
}
}
```
Dans cet exemple, la variable SET `@temp_celsius` est utilisée dans un modèle de substitution pour construire le champ clé de l'action S3.
**Utilisation de charges utiles non JSON**
Les variables SET ne prennent pas directement en charge les charges utiles non JSON. Par conséquent, la charge utile doit d'abord être codée ou décodée :
```
SET @encoded_payload = encode(*, 'base64')
SELECT @encoded_payload AS raw_data FROM 'device/binary'
```
pour plus d'informations sur la façon de travailler avec des charges utiles non JSON, reportez-vous à [Utilisation des charges utiles binaires](binary-payloads.md)
## Limites de la clause SET
Les limites suivantes s'appliquent aux variables SET :
+ Maximum de 10 variables uniques par instruction SQL
+ Taille de valeur variable maximale de 128 KiB (chaîne UTF-8 JSON minifiée)
+ Valeur totale maximale de 128 KiB pour toutes les variables
+ Noms de variables limités à 64 caractères
+ Les variables peuvent accepter les charges utiles JSON directement telles quelles (les charges utiles non JSON doivent d'abord être encodées/décodées)
# Clause WHERE
La clause WHERE détermine si les actions spécifiées par une règle sont exécutées. Si la clause WHERE évalue sur true, les actions de règle sont exécutées. Sinon, les actions de règle ne sont pas exécutées.
La clause WHERE prend en charge les [variables [Types de données](iot-sql-data-types.md)[Opérateurs](iot-sql-operators.md)[Fonctions](iot-sql-functions.md)[Littéraux](iot-sql-literals.md)[Instructions Case](iot-sql-case.md)](iot-sql-set.md#iot-sql-set-usage),[Extensions JSON](iot-sql-json.md),,,, et[Requêtes d'objets imbriqués](iot-sql-nested-queries.md).
**Exemple :**
Charge utile entrante publiée dans `topic/subtopic` : `{"color":"red", "temperature":40}`.
SQL : `SELECT color AS my_color FROM 'topic/subtopic' WHERE temperature > 50 AND color <> 'red'`.
Dans ce cas, la règle sera déclenchée mais les actions spécifiées par cette règle ne seront pas exécutées. Il n’y aura aucune charge utile sortante.
Vous pouvez utiliser des fonctions et des opérateurs dans une clause WHERE. Toutefois, vous ne pouvez pas faire référence à des alias créés avec le mot-clé AS dans la clause SELECT. (La clause WHERE est évaluée en premier pour déterminer si la clause SELECT doit être évaluée.)
**Exemple avec une charge utile non JSON :**
Charge utile non JSON entrante publiée sur « rubrique/sous-rubrique » : « 80 »
SQL : ``SELECT decode(encode(*, 'base64'), 'base64') AS value FROM 'topic/subtopic' WHERE decode(encode(*, 'base64'), 'base64') > 50`
Dans ce cas, la règle sera déclenchée mais les actions spécifiées par cette règle ne seront pas exécutées. La charge utile sortante sera transformée par la clause SELECT en charge utile JSON `{"value":80}`.
# Types de données
Le moteur de AWS IoT règles prend en charge tous les types de données JSON.
**Types de données pris en charge**
| Type | Signification |
| --- | --- |
| Int | Un Int discret. 34 chiffres maximum. |
| Decimal | Une valeur `Decimal` avec une précision de 34 chiffres, avec une magnitude non nulle de 1E-999 et une magnitude maximale de 9.999…E999. Certaines fonctions renvoient des valeurs `Decimal` avec double précision plutôt qu’avec une précision de 34 chiffres. Avec SQL V2 (2016-03-23), les valeurs numériques qui sont des nombres entiers, telles que `10.0`, sont traitées comme une valeur `Int` (`10`) au lieu de la valeur `Decimal` attendue (`10.0`). Pour traiter de manière fiable des valeurs numériques entières en tant que `Decimal` valeurs, utilisez SQL V1 (2015-10-08) pour l’instruction de requête de règle. |
| Boolean | True ou False. |
| String | Une chaîne UTF-8. |
| Array | Une série de valeurs qui ne sont pas nécessairement du même type. |
| Object | Une valeur JSON composée d'une clé et d'une valeur. Les clés doivent être des chaînes. Les valeurs peuvent être de n'importe quel type. |
| Null | Null comme défini par JSON. C'est une valeur réelle qui représente l'absence d'une valeur. Vous pouvez créer une valeur Null en utilisant le mot-clé Null dans votre instruction SQL. Par exemple : "SELECT NULL AS n FROM 'topic/subtopic'" |
| Undefined | Ce n'est pas une valeur. Non représenté dans JSON, sauf en omettant la valeur. Par exemple, dans l'objet `{"foo": null}`, la clé « foo » renvoie NULL, mais la clé « bar » renvoie `Undefined`. En interne, le langage SQL traite `Undefined` comme une valeur, mais il ne peut pas être représenté dans JSON, donc quand il est sérialisé au format JSON, les résultats sont `Undefined`. {"foo":null, "bar":undefined} est sérialisé au format JSON comme suit : {"foo":null} De même, `Undefined` est converti en chaîne vide lorsqu'il est sérialisé par lui-même. Les fonctions appelées avec des arguments non valides (par exemple, des types incorrects, un nombre d'arguments incorrect, etc.) renvoient `Undefined`. |
## Conversions
Le tableau suivant répertorie les résultats lorsqu'une valeur d'un type est convertie dans un autre type (lorsqu'une valeur d'un type incorrect est transmise à une fonction). Par exemple, si la fonction de valeur absolue « abs » (qui prévoit une valeur `Int` ou `Decimal`) reçoit une valeur `String`, elle tente de convertir la valeur `String` en `Decimal`, en respectant ces règles. Dans ce cas, « abs("-5.123") » est traité comme « abs(-5.123) ».
**Note**
Il n'y a aucune tentative de conversion en `Array`, `Object`, `Null` ou `Undefined`.
**En valeur décimale**
| Type d’argument | Résultat |
| --- | --- |
| Int | Un chiffre Decimal sans virgule décimale. |
| Decimal | La valeur source. |
| Boolean | Undefined. (Vous pouvez explicitement utiliser la fonction cast pour transformer true = 1.0, false = 0.0.) |
| String | Le moteur SQL essaie d'analyser la chaîne en tant Decimal que. AWS IoT tente d'analyser les chaînes correspondant à l'expression régulière :^-?\$1d\$1(\$1.\$1d\$1)?((?i)E-?\$1d\$1)?\$1. « 0 », « -1.2 », « 5E-12 » sont des exemples de chaînes qui sont automatiquement converties en valeurs Decimal. |
| Tableau | Undefined. |
| Objet | Undefined. |
| Null | Null. |
| Non défini | Undefined. |
**En Entier**
| Type d’argument | Résultat |
| --- | --- |
| Int | La valeur source. |
| Decimal | La valeur source arrondie à la valeur Int la plus proche. |
| Boolean | Undefined. (Vous pouvez explicitement utiliser la fonction cast pour transformer true = 1.0, false = 0.0.) |
| String | Le moteur SQL essaie d'analyser la chaîne en tant Decimal que. AWS IoT tente d'analyser les chaînes correspondant à l'expression régulière :^-?\$1d\$1(\$1.\$1d\$1)?((?i)E-?\$1d\$1)?\$1. « 0 », « -1,2 », « 5E-12 » sont tous des exemples de chaînes converties automatiquement en Decimal s. AWS IoT tente de convertir le en aDecimal, puis en tronque les décimales String pour en faire un. Decimal Int |
| Tableau | Undefined. |
| Objet | Undefined. |
| Null | Null. |
| Non défini | Undefined. |
**En valeur booléenne**
| Type d’argument | Résultat |
| --- | --- |
| Int | Undefined. (Vous pouvez explicitement utiliser la fonction cast pour transformer 0 = False, any\$1nonzero\$1value = True.) |
| Decimal | Undefined. (Vous pouvez explicitement utiliser la fonction cast pour transformer 0 = False, any\$1nonzero\$1value = True.) |
| Boolean | La valeur d'origine. |
| String | « true »=True et « false »=False (insensible à la casse). Les autres valeurs de chaînes sont : Undefined. |
| Tableau | Undefined. |
| Objet | Undefined. |
| Null | Undefined. |
| Non défini | Undefined. |
**En chaîne**
| Type d’argument | Résultat |
| --- | --- |
| Int | Une représentation de chaîne de la valeur Int en notation standard. |
| Decimal | Une chaîne représentant la valeur Decimal, probablement en notation scientifique. |
| Boolean | « true » ou « false ». Tout en minuscules. |
| String | La valeur d'origine. |
| Tableau | Le Array sérialisé au format JSON. La chaîne résultante est une liste de valeurs séparées par des virgules, délimitées par des crochets. Une valeur String est indiquée entre guillemets. Pas les valeurs Decimal, Int, Boolean et Null. |
| Objet | L'objet sérialisé au format JSON. La chaîne résultante est une liste de paires clé-valeur séparées par des virgules, qui commence et se termine par des accolades. Une valeur String est indiquée entre guillemets. Pas les valeurs Decimal, Int, Boolean et Null. |
| Null | Undefined. |
| Non défini | Non défini. |
# Opérateurs
Les opérateurs suivants peuvent être utilisés dans les clauses SELECT et WHERE.
## Opérateur AND
Il renvoie une valeur `Boolean`. Il effectue une opération AND logique. Il renvoie la valeur true si les opérandes gauche et droit sont vrais. Sinon, il renvoie la valeur « false ». Des opérandes `Boolean` ou de chaînes « true » ou « false » sensibles à la casse sont requis.
*Syntaxe :* ` expression AND expression`.
**Opérateur AND**
| Opérande gauche | Opérande droit | Output |
| --- | --- | --- |
| Boolean | Boolean | Boolean. Vrai si les deux opérandes sont vrais. Sinon, la valeur renvoyée est Faux. |
| String/Boolean | String/Boolean | Si toutes les chaînes sont « true » ou « false » (insensibles à la casse), elles sont converties en valeurs Boolean et traitées normalement en tant que valeurs boolean AND boolean. |
| Autre valeur | Autre valeur | Undefined. |
## Opérateur OR
Il renvoie une valeur `Boolean`. Il effectue une opération OR logique. Il renvoie la valeur true si les opérandes gauche ou droit sont vrais. Sinon, il renvoie la valeur « false ». Des opérandes `Boolean` ou de chaînes « true » ou « false » sensibles à la casse sont requis.
*Syntaxe :* ` expression OR expression`.
**Opérateur OR**
| Opérande gauche | Opérande droit | Output |
| --- | --- | --- |
| Boolean | Boolean | Boolean. Vrai si l’un des deux opérandes est vrai. Sinon, la valeur renvoyée est Faux. Sinon, la valeur renvoyée est Faux. |
| String/Boolean | String/Boolean | Si toutes les chaînes sont « true » ou « false » (insensibles à la casse), elles sont converties en valeurs booléennes et traitées normalement en tant que valeurs boolean OR boolean. |
| Autre valeur | Autre valeur | Undefined. |
## Opérateur NOT
Il renvoie une valeur `Boolean`. Il effectue une opération NOT logique. Il renvoie true si l'opérande est faux. Sinon, la valeur renvoyée est true. Un opérande `Boolean` ou un opérande de chaîne « true » ou « false » insensible à la casse est requis.
*Syntaxe :* `NOT expression`.
**Opérateur NOT**
| Opérande | Output |
| --- | --- |
| Boolean | Boolean. Vrai si l’opérande est Faux. Sinon, la valeur renvoyée est Vrai. |
| String | Si une chaîne est « true » ou « false » (insensible à la casse), elle est convertie dans la valeur booléenne correspondante, et la valeur opposée est renvoyée. |
| Autre valeur | Undefined. |
## Opérateur IN
Il renvoie une valeur `Boolean`. Vous pouvez utiliser l'opérateur IN dans une clause WHERE pour vérifier si une valeur correspond à une valeur d'un tableau. Elle renvoie vrai si la correspondance est trouvée, et faux dans le cas contraire.
*Syntaxe :* ` expression IN expression`.
**Opérateur IN**
| Opérande gauche | Opérande droit | Output |
| --- | --- | --- |
| Int/Decimal/String/Array/Object | Array | Vrai si l'Objectélément Integer DecimalString/Array///se trouve dans le tableau. Sinon, la valeur renvoyée est Faux. |
*Exemple :*
```
SQL: "select * from 'a/b' where 3 in arr"
JSON: {"arr":[1, 2, 3, "three", 5.7, null]}
```
Dans cet exemple, la clause condition `where 3 in arr` sera évaluée à true car 3 est présent dans le tableau nommé`arr`. Par conséquent, dans l'instruction SQL, `select * from 'a/b'` sera exécuté. Cet exemple montre également que le tableau peut être hétérogène.
## opérateur EXISTS
Il renvoie une valeur `Boolean`. Vous pouvez utiliser l'opérateur EXISTS dans une clause conditionnelle pour tester l'existence d'éléments dans une sous-requête. Elle renvoie true si la sous-requête renvoie un ou plusieurs éléments et false si la sous-requête ne renvoie aucun élément.
*Syntaxe :* ` expression`.
*Exemple :*
```
SQL: "select * from 'a/b' where exists (select * from arr as a where a = 3)"
JSON: {"arr":[1, 2, 3]}
```
Dans cet exemple, la clause condition `where exists (select * from arr as a where a = 3)` sera évaluée à true car 3 est présent dans le tableau nommé`arr`. Par conséquent, dans l'instruction SQL, `select * from 'a/b'` sera exécuté.
*Exemple :*
```
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}]}
```
Dans cet exemple, la clause de condition `where exists (select * from e as e where foo = 2)` sera évaluée à true car le tableau `e` de l'objet JSON contient l'objet`{"foo":2}`. Par conséquent, dans l'instruction SQL, `select * from 'a/b'` sera exécuté.
## > opérateur
Il renvoie une valeur `Boolean`. Il renvoie la valeur true si l'opérande gauche est supérieur à l'opérande droit. Les deux opérandes sont convertis en valeur `Decimal`, puis comparés.
*Syntaxe :* `expression > expression`.
**> opérateur**
| Opérande gauche | Opérande droit | Output |
| --- | --- | --- |
| Int/Decimal | Int/Decimal | Boolean. Vrai si l’opérande gauche est supérieur à l’opérande droit. Sinon, la valeur renvoyée est Faux. |
| String/Int/Decimal | String/Int/Decimal | Si toutes les chaînes peuvent être converties en valeurs Decimal, puis en valeurs Boolean. Il renvoie la valeur true si l'opérande gauche est supérieur à l'opérande droit. Sinon, la valeur renvoyée est Faux. |
| Autre valeur | Undefined. | Undefined. |
## >= opérateur
Il renvoie une valeur `Boolean`. Il renvoie la valeur true si l'opérande gauche est supérieur ou égal à l'opérande droit. Les deux opérandes sont convertis en valeur `Decimal`, puis comparés.
*Syntaxe :* `expression >= expression`.
**>= opérateur**
| Opérande gauche | Opérande droit | Output |
| --- | --- | --- |
| Int/Decimal | Int/Decimal | Boolean.Vrai si l’opérande gauche est supérieur ou égal à l’opérande droit. Sinon, la valeur renvoyée est Faux. |
| String/Int/Decimal | String/Int/Decimal | Si toutes les chaînes peuvent être converties en valeurs Decimal, puis en valeurs Boolean. Il renvoie la valeur true si l'opérande gauche est supérieur ou égal à l'opérande droit. Sinon, la valeur renvoyée est Faux. |
| Autre valeur | Undefined. | Undefined. |
## < opérateur
Il renvoie une valeur `Boolean`. Il renvoie la valeur true si l'opérande gauche est inférieur à l'opérande droit. Les deux opérandes sont convertis en valeur `Decimal`, puis comparés.
*Syntaxe :* `expression < expression`.
**< opérateur**
| Opérande gauche | Opérande droit | Output |
| --- | --- | --- |
| Int/Decimal | Int/Decimal | Boolean. Vrai si l’opérande gauche est inférieur à l’opérande droit. Sinon, la valeur renvoyée est Faux. |
| String/Int/Decimal | String/Int/Decimal | Si toutes les chaînes peuvent être converties en valeurs Decimal, puis en valeurs Boolean. Il renvoie la valeur true si l'opérande gauche est inférieur à l'opérande droit. Sinon, la valeur renvoyée est Faux. |
| Autre valeur | Undefined | Undefined |
## <= opérateur
Il renvoie une valeur `Boolean`. Il renvoie la valeur true si l'opérande gauche est inférieur ou égal à l'opérande droit. Les deux opérandes sont convertis en valeur `Decimal`, puis comparés.
*Syntaxe:* `expression <= expression`.
**<= opérateur**
| Opérande gauche | Opérande droit | Output |
| --- | --- | --- |
| Int/Decimal | Int/Decimal | Boolean. Vrai si l’opérande gauche est inférieur ou égal à l’opérande droit. Sinon, la valeur renvoyée est Faux. |
| String/Int/Decimal | String/Int/Decimal | Si toutes les chaînes peuvent être converties en valeurs Decimal, puis en valeurs Boolean. Il renvoie la valeur true si l'opérande gauche est inférieur ou égal à l'opérande droit. Sinon, la valeur renvoyée est Faux. |
| Autre valeur | Undefined | Undefined |
## <> opérateur
Il renvoie une valeur `Boolean`. Il renvoie la valeur true si les opérandes gauche et droit ne sont pas égaux. Sinon, la valeur renvoyée est false.
*Syntaxe :* ` expression <> expression`.
**<> opérateur**
| Opérande gauche | Opérande droit | Output |
| --- | --- | --- |
| Int | Int | Vrai si l'opérande gauche est différent de l'opérande droit. Sinon, la valeur renvoyée est Faux. |
| Decimal | Decimal | Vrai si l'opérande gauche est différent de l'opérande droit. Sinon, la valeur renvoyée est Faux. Int est convertie en valeur Decimal avant d'être comparée. |
| String | String | Vrai si l'opérande gauche est différent de l'opérande droit. Sinon, la valeur renvoyée est Faux. |
| Tableau | Tableau | Vrai si les éléments de chaque opérande sont différents et ne sont pas dans le même ordre. Sinon, la valeur renvoyée est Faux |
| Objet | Objet | Vrai si les clés et les valeurs de chaque opérande sont différentes. Sinon, la valeur renvoyée est Faux. L'ordre de keys/values n'a pas d'importance. |
| Null | Null | Faux. |
| N'importe quelle valeur | Undefined | Non défini. |
| Undefined | N'importe quelle valeur | Non défini. |
| Type non compatible | Type non compatible | Vrai. |
## = opérateur
Il renvoie une valeur `Boolean`. Il renvoie la valeur true si les opérandes gauche et droit sont égaux. Sinon, la valeur renvoyée est false.
*Syntaxe :* ` expression = expression`.
**= opérateur**
| Opérande gauche | Opérande droit | Output |
| --- | --- | --- |
| Int | Int | Vrai si l'opérande gauche est identique à l'opérande droit. Sinon, la valeur renvoyée est Faux. |
| Decimal | Decimal | Vrai si l'opérande gauche est identique à l'opérande droit. Sinon, la valeur renvoyée est Faux. Int est convertie en valeur Decimal avant d'être comparée. |
| String | String | Vrai si l'opérande gauche est identique à l'opérande droit. Sinon, la valeur renvoyée est Faux. |
| Tableau | Tableau | Vrai si les éléments de chaque opérande sont égaux et sont dans le même ordre. Sinon, la valeur renvoyée est Faux. |
| Objet | Objet | Vrai si les clés et valeurs de chaque opérande sont identiques. Sinon, la valeur renvoyée est Faux. L'ordre de keys/values n'a pas d'importance. |
| N'importe quelle valeur | Undefined | Undefined. |
| Undefined | N'importe quelle valeur | Undefined. |
| Type non compatible | Type non compatible | Faux. |
## \$1 opérateur
Le signe « \$1 » est un opérateur surchargé. Il peut être utilisé pour l'addition ou la concaténation de chaines.
*Syntaxe :* ` expression + expression`.
**\$1 opérateur**
| Opérande gauche | Opérande droit | Output |
| --- | --- | --- |
| String | N'importe quelle valeur | Il convertit l'opérande droit en chaîne et l'ajoute à la fin de l'opérande gauche. |
| N'importe quelle valeur | String | Il convertit l'opérande gauche en chaîne et ajoute l'opérande droit à la fin de l'opérande gauche converti. |
| Int | Int | Valeur Int. Il ajoute les opérandes ensemble. |
| Int/Decimal | Int/Decimal | Valeur Decimal. Il ajoute les opérandes ensemble. |
| Autre valeur | Autre valeur | Undefined. |
## - opérateur
Il soustrait l'opérande droit de l'opérande gauche.
*Syntaxe :* ` expression - expression`.
**- opérateur**
| Opérande gauche | Opérande droit | Output |
| --- | --- | --- |
| Int | Int | Valeur Int. Il soustrait l'opérande droit de l'opérande gauche. |
| Int/Decimal | Int/Decimal | Valeur Decimal. Il soustrait l'opérande droit de l'opérande gauche. |
| String/Int/Decimal | String/Int/Decimal | Si toutes les chaînes sont correctement converties en valeurs décimales, une valeur Decimal est renvoyée. Il soustrait l'opérande droit de l'opérande gauche. Sinon, la valeur renvoyée est Undefined. |
| Autre valeur | Autre valeur | Undefined. |
| Autre valeur | Autre valeur | Undefined. |
## \$1 opérateur
Il multiplie l'opérande gauche par l'opérande droit.
*Syntaxe :* ` expression * expression`.
**\$1 opérateur**
| Opérande gauche | Opérande droit | Output |
| --- | --- | --- |
| Int | Int | Valeur Int. Il multiplie l'opérande gauche par l'opérande droit. |
| Int/Decimal | Int/Decimal | Valeur Decimal. Il multiplie l'opérande gauche par l'opérande droit. |
| String/Int/Decimal | String/Int/Decimal | Si toutes les chaînes sont correctement converties en valeurs décimales, une valeur Decimal est renvoyée. Il multiplie l'opérande gauche par l'opérande droit. Sinon, la valeur renvoyée est Undefined. |
| Autre valeur | Autre valeur | Undefined. |
## / opérateur
Il divise l'opérande gauche par l'opérande droit.
*Syntaxe :* ` expression / expression`.
**/ opérateur**
| Opérande gauche | Opérande droit | Output |
| --- | --- | --- |
| Int | Int | Valeur Int. Il divise l'opérande gauche par l'opérande droit. |
| Int/Decimal | Int/Decimal | Valeur Decimal. Il divise l'opérande gauche par l'opérande droit. |
| String/Int/Decimal | String/Int/Decimal | Si toutes les chaînes sont correctement converties en valeurs décimales, une valeur Decimal est renvoyée. Il divise l'opérande gauche par l'opérande droit. Sinon, la valeur renvoyée est Undefined. |
| Autre valeur | Autre valeur | Undefined. |
## % opérateur
Il renvoie le reste résultant de la division de l'opérande gauche par l'opérande droit.
*Syntaxe :* ` expression % expression`.
**% opérateur**
| Opérande gauche | Opérande droit | Output |
| --- | --- | --- |
| Int | Int | Valeur Int. Il renvoie le reste résultant de la division de l'opérande gauche par l'opérande droit. |
| String/Int/Decimal | String/Int/Decimal | Si toutes les chaînes sont correctement converties en valeurs décimales, une valeur Decimal est renvoyée. Il renvoie le reste résultant de la division de l'opérande gauche par l'opérande droit. Sinon la valeur est renvoy, Undefined. |
| Autre valeur | Autre valeur | Undefined. |
# Fonctions
Vous pouvez utiliser les fonctions intégrées suivantes dans les clauses SELECT ou WHERE de vos expressions SQL.
Les fonctions externes suivantes sont facturées de manière équivalente à celle d'une action de règle : [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-dynamodb](https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-sql-function-get-dynamodb), et [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). La [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)fonction ne vous est également facturée que lorsque vous [décodez un message Protobuf](https://docs.aws.amazon.com//iot/latest/developerguide/binary-payloads.html#binary-payloads-protobuf) en JSON. Pour plus de détails, consultez la [page de AWS IoT Core tarification](https://aws.amazon.com/iot-core/pricing/).
## abs(Decimal)
Il renvoie la valeur absolue d'un nombre. Prise en charge par SQL 2015-10-08 et versions ultérieures.
Par exemple, `abs(-5)` renvoie 5.
****
| Type d’argument | Résultat |
| --- | --- |
| Int | Int, la valeur absolue de l'argument. |
| Decimal | Decimal, la valeur absolue de l'argument. |
| Boolean | Undefined. |
| String | Decimal. Le résultat est la valeur absolue de l’argument. Si la chaîne ne peut être pas convertie, le résultat est Undefined. |
| Tableau | Undefined. |
| Objet | Undefined. |
| Null | Undefined. |
| Non défini | Undefined. |
## accountid()
Renvoie l'ID du compte qui possède la règle comme une valeur `String`. Prise en charge par SQL 2015-10-08 et versions ultérieures.
Exemple :
`accountid() ` = "123456789012"
## acos(Decimal)
Renvoie le cosinus inverse d'un nombre en radians. Les arguments `Decimal` sont arrondis pour une meilleure prévision avant l'application de la fonction. Prise en charge par SQL 2015-10-08 et versions ultérieures.
Exemple : `acos(0)` = 1,5707963267948966
****
| Type d’argument | Résultat |
| --- | --- |
| Int | Decimal (avec double précision), le cosinus inverse de l'argument. Des résultats imaginaires sont retournés sous la forme Undefined. |
| Decimal | Decimal (avec double précision), le cosinus inverse de l'argument. Des résultats imaginaires sont retournés sous la forme Undefined. |
| Boolean | Undefined. |
| String | Decimal, le cosinus inverse de l'argument. Si la chaîne ne peut être pas convertie, le résultat est Undefined. Des résultats imaginaires sont retournés sous la forme Undefined. |
| Tableau | Undefined. |
| Objet | Undefined. |
| Null | Undefined. |
| Non défini | Undefined. |
## asin(Decimal)
Renvoie le sinus inverse d'un nombre en radians. Les arguments `Decimal` sont arrondis pour une meilleure prévision avant l'application de la fonction. Prise en charge par SQL 2015-10-08 et versions ultérieures.
Exemple : `asin(0)` = 0,0
****
| Type d’argument | Résultat |
| --- | --- |
| Int | Decimal (avec double précision), le sinus inverse de l'argument. Des résultats imaginaires sont retournés sous la forme Undefined. |
| Decimal | Decimal (avec double précision), le sinus inverse de l'argument. Des résultats imaginaires sont retournés sous la forme Undefined. |
| Boolean | Undefined. |
| String | Decimal (avec double précision), le sinus inverse de l'argument. Si la chaîne ne peut être pas convertie, le résultat est Undefined. Des résultats imaginaires sont retournés sous la forme Undefined. |
| Tableau | Undefined. |
| Objet | Undefined. |
| Null | Undefined. |
| Non défini | Undefined. |
## atan(Decimal)
Renvoie la tangente inverse d'un nombre en radians. Les arguments `Decimal` sont arrondis pour une meilleure prévision avant l'application de la fonction. Prise en charge par SQL 2015-10-08 et versions ultérieures.
Exemple : `atan(0)` = 0,0
****
| Type d’argument | Résultat |
| --- | --- |
| Int | Decimal (avec double précision), la tangente inverse de l'argument. Des résultats imaginaires sont retournés sous la forme Undefined. |
| Decimal | Decimal (avec double précision), la tangente inverse de l'argument. Des résultats imaginaires sont retournés sous la forme Undefined. |
| Boolean | Undefined. |
| String | Decimal, la tangente inverse de l'argument. Si la chaîne ne peut être pas convertie, le résultat est Undefined. Des résultats imaginaires sont retournés sous la forme Undefined. |
| Tableau | Undefined. |
| Objet | Undefined. |
| Null | Undefined. |
| Non défini | Undefined. |
## atan2(Decimal, Decimal)
Il renvoie l'angle en radians, entre l'axe des X positifs et le point (x, y) défini dans les deux arguments. L'angle est positif pour les angles sans le sens contraire des aiguilles d'une montre (moitié supérieure du plan, y > 0) et négatif pour les angles dans le sens des aiguilles d'une montre (moitié inférieure du plan, y < 0). Les arguments `Decimal` sont arrondis pour une meilleure précision avant l'application de la fonction. Prise en charge par SQL 2015-10-08 et versions ultérieures.
Exemple : `atan2(1, 0)` = 1,5707963267948966
****
| Type d’argument | Type d’argument | Résultat |
| --- | --- | --- |
| Int/Decimal | Int/Decimal | Decimal (avec double précision), l'angle entre l'axe des X et le point (x, y) spécifié. |
| Int/Decimal/String | Int/Decimal/String | Decimal, la tangente inverse du point décrit. Si une chaîne ne peut pas être convertie, le résultat est Undefined. |
| Autre valeur | Autre valeur | Undefined. |
## aws\$1lambda(functionArn, inputJson)
Appelle la fonction Lambda spécifiée en transmettant le paramètre `inputJson` à la fonction Lambda et renvoie les données JSON générées par la fonction Lambda.
**Arguments**
| Argument | Description |
| --- | --- |
| functionArn | ARN de la fonction Lambda à appeler. La fonction Lambda doit renvoyer des données JSON. |
| inputJson | Données JSON en entrée transmises à la fonction Lambda. Pour transmettre des requêtes d’objets imbriqués et des littéraux, vous devez utiliser la version SQL 2016-03-23. |
Vous devez accorder AWS IoT `lambda:InvokeFunction` des autorisations pour appeler la fonction Lambda spécifiée. L'exemple suivant montre comment accorder l'autorisation `lambda:InvokeFunction` à l'aide de l' 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"
```
Les arguments de la commande **add-permission** sont les suivants :
--function-name
Nom de la fonction Lambda. Vous ajoutez une nouvelle autorisation pour mettre à jour la politique de ressources de la fonction.
--région
Celui Région AWS de votre compte.
--principal
Mandataire qui obtient l'autorisation. Cela devrait être `iot.amazonaws.com` pour AWS IoT autoriser l'appel d'une fonction Lambda.
--source-arn
ARN de la règle. Vous pouvez utiliser la **get-topic-rule** AWS CLI commande pour obtenir l'ARN d'une règle.
--source-account
L' Compte AWS endroit où la règle est définie.
--statement-id
Identifiant unique de l'instruction.
--action
L’action Lambda que vous souhaitez autoriser dans cette déclaration. Pour autoriser AWS IoT à invoquer une fonction,Lambda spécifiez `lambda:InvokeFunction`.
**Important**
Si vous ajoutez une autorisation pour un AWS IoT principal sans fournir le `source-arn` ou`source-account`, toute autorisation Compte AWS qui crée une règle avec votre action Lambda peut déclencher des règles à partir desquelles appeler votre fonction Lambda. AWS IoT Pour plus d’informations, veuillez consulter [Modèle d’autorisation Lambda](https://docs.aws.amazon.com/lambda/latest/dg/intro-permission-model.html).
Soit une charge utile de message JSON comme suit :
```
{
"attribute1": 21,
"attribute2": "value"
}
```
La fonction `aws_lambda` peut être utilisée pour appeler la fonction Lambda, comme suit :
```
SELECT
aws_lambda("arn:aws:lambda:us-east-1:account_id:function:lambda_function", {"payload":attribute1}) as output FROM 'topic-filter'
```
Si vous souhaitez transmettre l’intégralité de la charge utile des messages MQTT, vous pouvez spécifier la charge utile JSON en utilisant « \$1 », comme dans l’exemple suivant.
```
SELECT
aws_lambda("arn:aws:lambda:us-east-1:account_id:function:lambda_function", *) as output FROM 'topic-filter'
```
`payload.inner.element` sélectionne les données à partir des messages publiés dans la rubrique « rubrique/sous-rubrique ».
`some.value` sélectionne les données à partir de la sortie générée par la fonction Lambda.
**Note**
Le moteur de règles limite la durée d'exécution des fonctions Lambda. Les appels de fonction Lambda provenant de règles doivent être terminés en moins de 2 000 millisecondes.
## bitand(Int, Int)
Il effectue une opération AND au niveau du bit sur des représentations binaires des deux arguments `Int`(-convertis). Prise en charge par SQL 2015-10-08 et versions ultérieures.
Exemple : `bitand(13, 5)` = 5
****
| Type d’argument | Type d’argument | Résultat |
| --- | --- | --- |
| Int | Int | Int, une opération AND au niveau du bit des deux arguments. |
| Int/Decimal | Int/Decimal | Int, une opération AND au niveau du bit des deux arguments. Tous les nombres non-Int sont arrondis à la valeur Int inférieure la plus proche. Si l'un des arguments ne peut pas être converti en une valeur Int, le résultat Undefined. |
| Int/Decimal/String | Int/Decimal/String | Int, une opération AND au niveau du bit des deux arguments. Toutes les chaînes sont converties en valeurs décimales et arrondies à la valeur Int inférieure la plus proche. Si la conversion échoue, le résultat est Undefined. |
| Autre valeur | Autre valeur | Undefined. |
## bitor(Int, Int)
Il effectue une opération OR au niveau du bit des représentations binaires des deux arguments. Prise en charge par SQL 2015-10-08 et versions ultérieures.
Exemple : `bitor(8, 5)` = 13
****
| Type d’argument | Type d’argument | Résultat |
| --- | --- | --- |
| Int | Int | Int, une opération OR au niveau du bit des deux arguments. |
| Int/Decimal | Int/Decimal | Int, une opération OR au niveau du bit des deux arguments. Tous les nombres non-Int sont arrondis à la valeur Int inférieure la plus proche. Si la conversion échoue, le résultat est Undefined. |
| Int/Decimal/String | Int/Decimal/String | Int, une opération OR au niveau du bit sur les deux arguments. Toutes les chaînes sont converties en valeurs décimales et arrondies à la valeur Int inférieure la plus proche. Si la conversion échoue, le résultat est Undefined. |
| Autre valeur | Autre valeur | Undefined. |
## bitxor(Int, Int)
Il effectue une opération XOR au niveau du bit sur des représentations binaires des deux arguments `Int`(-convertis). Prise en charge par SQL 2015-10-08 et versions ultérieures.
Exemple : `bitor(13, 5)` = 8
****
| Type d’argument | Type d’argument | Résultat |
| --- | --- | --- |
| Int | Int | Int, une opération XOR au niveau du bit sur les deux arguments. |
| Int/Decimal | Int/Decimal | Int, une opération XOR au niveau du bit sur les deux arguments. Les nombres non-Int sont arrondis à la valeur Int inférieure la plus proche. |
| Int/Decimal/String | Int/Decimal/String | Int, un XOR au niveau du bit sur les deux arguments. Les chaînes sont converties en décimales et arrondies à la valeur Int inférieure la plus proche. Si une conversion échoue, le résultat est Undefined. |
| Autre valeur | Autre valeur | Undefined. |
## bitnot(Int)
Il effectue une opération NOT au niveau du bit sur des représentations binaires de l'argument `Int`(-converti). Prise en charge par SQL 2015-10-08 et versions ultérieures.
Exemple : `bitnot(13)` = 2
****
| Type d’argument | Résultat |
| --- | --- |
| Int | Int, une opération NOT au niveau du bit de l'argument. |
| Decimal | Int, une opération NOT au niveau du bit de l'argument. La valeur Decimal est arrondie à la valeur Int inférieure la plus proche. |
| String | Int, une opération NOT au niveau du bit de l'argument. Les chaînes sont converties en valeurs décimales et arrondies à la valeur Int inférieure la plus proche. Si une conversion échoue, le résultat est Undefined. |
| Autre valeur | Autre valeur. |
## cast()
Convertit une valeur d'un type de données en un autre. La conversion se comporte principalement comme les conversions standard, avec en outre la capacité de convertir des chiffres vers/depuis des valeurs booléennes. Si vous AWS IoT ne pouvez pas déterminer comment convertir un type en un autre, le résultat est`Undefined`. Prise en charge par SQL 2015-10-08 et versions ultérieures. Format : fonte (*value*s*type*).
Exemple :
`cast(true as Int) ` = 1
Les mots-clés suivants peuvent apparaître après « as » lors de l'appel de `cast` :
**Pour SQL versions 2015-10-08 et 2016-03-23**
| Mot clé | Résultat |
| --- | --- |
| String | Il convertit une valeur en String. |
| Nvarchar | Il convertit une valeur en String. |
| Texte | Il convertit une valeur en String. |
| Ntext | Il convertit une valeur en String. |
| varchar | Il convertit une valeur en String. |
| Int | Il convertit une valeur en Int. |
| Entier | Il convertit une valeur en Int. |
| Double | Transforme la valeur en Decimal (avec une double précision). |
**En outre, pour SQL version 2016-03-23**
| Mot clé | Résultat |
| --- | --- |
| Decimal | Il convertit une valeur en Decimal. |
| Booléen | Il convertit une valeur en Boolean. |
| Boolean | Il convertit une valeur en Boolean. |
Règles de conversion de types :
**Conversion en décimal**
| Type d’argument | Résultat |
| --- | --- |
| Int | Un chiffre Decimal sans virgule décimale. |
| Decimal | La valeur source. Avec SQL V2 (2016-03-23), les valeurs numériques qui sont des nombres entiers, telles que `10.0`, renvoient une valeur `Int` (`10`) au lieu de la valeur `Decimal` attendue (`10.0`). Pour convertir de manière fiable des valeurs numériques entières en tant que valeurs `Decimal`, utilisez SQL V1 (2015-10-08) pour l’instruction de requête de règle. |
| Boolean | true = 1.0, false = 0.0. |
| String | Tente d'analyser la chaîne en tant que Decimal. AWS IoT tente d'analyser les chaînes correspondant à l'expression regex : ^-?\$1d\$1(\$1.\$1d\$1)?((?i)E-?\$1d\$1)?\$1. « 0 », « -1.2 », « 5E-12 » sont des exemples de chaînes qui sont automatiquement converties en valeurs décimales. |
| Tableau | Undefined. |
| Objet | Undefined. |
| Null | Undefined. |
| Non défini | Undefined. |
**Conversion en entier**
| Type d’argument | Résultat |
| --- | --- |
| Int | La valeur source. |
| Decimal | La valeur source arrondie à la valeur Int inférieure la plus proche. |
| Boolean | true = 1.0, false = 0.0. |
| String | Tente d'analyser la chaîne en tant que Decimal. AWS IoT tente d'analyser les chaînes correspondant à l'expression regex : ^-?\$1d\$1(\$1.\$1d\$1)?((?i)E-?\$1d\$1)?\$1. « 0 », « -1.2 », « 5E-12 » sont des exemples de chaînes qui sont automatiquement converties en valeurs décimales. AWS IoT tente de convertir la chaîne en valeur Decimal, puis de l'arrondir à la valeur Int inférieure la plus proche. |
| Tableau | Undefined. |
| Objet | Undefined. |
| Null | Undefined. |
| Non défini | Undefined. |
**Conversion en valeur `Boolean`**
| Type d’argument | Résultat |
| --- | --- |
| Int | 0 = False, any\$1nonzero\$1value = True. |
| Decimal | 0 = False, any\$1nonzero\$1value = True. |
| Boolean | La valeur source. |
| String | « true »=True et « false »=False (insensible à la casse). Autres valeurs de chaînes = Undefined. |
| Tableau | Undefined. |
| Objet | Undefined. |
| Null | Undefined. |
| Non défini | Undefined. |
**Conversion en chaîne**
| Type d’argument | Résultat |
| --- | --- |
| Int | Une représentation de chaîne de la valeur Int en notation standard. |
| Decimal | Une chaîne représentant la valeur Decimal, probablement en notation scientifique. |
| Boolean | « true » ou « false », tout en minuscules. |
| String | La valeur source. |
| Tableau | Le tableau sérialisé au format JSON. La chaîne résultante consiste en une liste séparée par des virgules et délimitée par des crochets. String est entre guillemets, à l'inverse de Decimal, Int et Boolean. |
| Objet | L'objet sérialisé au format JSON. La chaîne JSON est une liste de paires clé-valeur séparées par des virgules, délimitées par des accolades. String est entre guillemets, à l'inverse de Decimal, Int, Boolean et Null. |
| Null | Undefined. |
| Non défini | Undefined. |
## ceil(Decimal)
Arrondit la valeur `Decimal` donnée à la valeur `Int` supérieure la plus proche. Prise en charge par SQL 2015-10-08 et versions ultérieures.
Exemples :
`ceil(1.2)` = 2
`ceil(-1.2)` = -1
****
| Type d’argument | Résultat |
| --- | --- |
| Int | Int, la valeur d'argument. |
| Decimal | Int, la valeur Decimal arrondie à la valeur Int supérieure la plus proche. |
| String | Int. La chaîne est convertie en valeur Decimal et arrondie à la valeur Int supérieure la plus proche. Si la chaîne ne peut pas être convertie en une valeur Decimal, le résultat est Undefined. |
| Autre valeur | Undefined. |
## chr(String)
Renvoie le caractère ASCII qui correspond à l'argument `Int` donné. Prise en charge par SQL 2015-10-08 et versions ultérieures.
Exemples :
`chr(65)` = "A".
`chr(49)` = "1".
****
| Type d’argument | Résultat |
| --- | --- |
| Int | Le caractère correspondant à la valeur ASCII spécifiée. Si l'argument n'est pas une valeur ASCII valide, le résultat est Undefined. |
| Decimal | Le caractère correspondant à la valeur ASCII spécifiée. L'argument Decimal est arrondi à la valeur Int inférieure la plus proche. Si l'argument n'est pas une valeur ASCII valide, le résultat est Undefined. |
| Boolean | Undefined. |
| String | Si la valeur String peut être convertie en valeur Decimal, elle est arrondie à la valeur Int inférieure la plus proche. Si l'argument n'est pas une valeur ASCII valide, le résultat est Undefined. |
| Tableau | Undefined. |
| Objet | Undefined. |
| Null | Undefined. |
| Autre valeur | Undefined. |
## clientid()
Retourne l'ID du client MQTT en envoyant le message, ou une valeur `n/a` si le message n'a pas été pas envoyé via MQTT. Prise en charge par SQL 2015-10-08 et versions ultérieures.
Exemple :
`clientid() ` = "123456789012"
## concat()
Concatène des tableaux ou des chaînes. Cette fonction accepte n'importe quel nombre d'arguments et renvoie une valeur `String` ou `Array`. Prise en charge par SQL 2015-10-08 et versions ultérieures.
Exemples :
`concat() ` = `Undefined`.
`concat(1) ` = "1".
`concat([1, 2, 3], 4)` = [1, 2, 3, 4].
`concat([1, 2, 3], "hello")` = [1, 2, 3, "bonjour"]
`concat("con", "cat")` = "concat"
`concat(1, "hello")` = "bonjour1"
`concat("he","is","man")` = "heisman"
`concat([1, 2, 3], "hello", [4, 5, 6])` = [1, 2, 3, "bonjour", 4, 5, 6]
****
| Nombre d'arguments | Résultat |
| --- | --- |
| 0 | Undefined. |
| 1 | L'argument est renvoyé non modifié. |
| 2\$1 | Si un argument est une valeur `Array`, le résultat est un seul tableau contenant l'ensemble des arguments. Si aucun argument n'est une valeur de tableau, et qu'un argument au moins est une valeur `String`, le résultat est la concaténation des représentations de `String` de tous les arguments. Des arguments sont convertis en chaînes à l’aide des conversions standard précédemment répertoriées. |
## cos(Decimal)
Renvoie le cosinus d'un nombre en radians. Les arguments `Decimal` sont arrondis pour une meilleure prévision avant l'application de la fonction. Prise en charge par SQL 2015-10-08 et versions ultérieures.
Exemple :
`cos(0)` = 1.
****
| Type d’argument | Résultat |
| --- | --- |
| Int | Decimal (avec double précision), le cosinus de l'argument. Des résultats imaginaires sont retournés sous la forme Undefined. |
| Decimal | Decimal (avec double précision), le cosinus de l'argument. Des résultats imaginaires sont retournés sous la forme Undefined. |
| Boolean | Undefined. |
| String | Decimal (avec double précision), le cosinus de l'argument. Si la chaîne ne peut pas être convertie en une valeur Decimal, le résultat est Undefined. Des résultats imaginaires sont retournés sous la forme Undefined. |
| Tableau | Undefined. |
| Objet | Undefined. |
| Null | Undefined. |
| Non défini | Undefined. |
## cosh(Decimal)
Renvoie le cosinus hyperbolique d'un nombre en radians. Les arguments `Decimal` sont arrondis pour une meilleure prévision avant l'application de la fonction. Prise en charge par SQL 2015-10-08 et versions ultérieures.
Exemple : `cosh(2.3)` = 5.037220649268761.
****
| Type d’argument | Résultat |
| --- | --- |
| Int | Decimal (avec double précision), le cosinus hyperbolique de l'argument. Des résultats imaginaires sont retournés sous la forme Undefined. |
| Decimal | Decimal (avec double précision), le cosinus hyperbolique de l'argument. Des résultats imaginaires sont retournés sous la forme Undefined. |
| Boolean | Undefined. |
| String | Decimal (avec double précision), le cosinus hyperbolique de l'argument. Si la chaîne ne peut pas être convertie en une valeur Decimal, le résultat est Undefined. Des résultats imaginaires sont retournés sous la forme Undefined. |
| Tableau | Undefined. |
| Objet | Undefined. |
| Null | Undefined. |
| Non défini | Undefined. |
## décoder (valeur, schéma de décodage)
Utilisez la fonction `decode` pour décoder une valeur codée. Si la chaîne décodée est un document JSON, un objet adressable est renvoyé. Sinon, la chaîne décodée est renvoyée sous forme de chaîne. La fonction renvoie NULL si la chaîne ne peut pas être décodée. Cette fonction prend en charge le décodage des chaînes codées en base64 et du format de message Protocol Buffer (protobuf).
Pris en charge par SQL 2016-03-23 et versions ultérieures.
value
Une valeur de chaîne ou l’une des expressions valides, telles que définies dans [AWS IoT Référence SQL](iot-sql-reference.md), qui renvoie une chaîne.
decodingScheme
Chaîne littérale représentant le schéma utilisé pour décoder la valeur. À l’heure actuelle, uniquement `'base64'` et `'proto'` sont pris en charge.
### Décodage de chaînes codées en base64
Dans cet exemple, la charge utile du message inclut une valeur codée.
```
{
encoded_temp: "eyAidGVtcGVyYXR1cmUiOiAzMyB9Cg=="
}
```
La fonction `decode` de cette instruction SQL décode la valeur de la charge utile du message.
```
SELECT decode(encoded_temp,"base64").temperature AS temp from 'topic/subtopic'
```
Le décodage de la valeur `encoded_temp` permet d’obtenir le document JSON valide suivant, qui permet à l’instruction SELECT de lire la valeur de température.
```
{ "temperature": 33 }
```
Le résultat de l’instruction SELECT dans cet exemple est affiché ici.
```
{ "temp": 33 }
```
Si la valeur décodée n’était pas un document JSON valide, la valeur décodée serait renvoyée sous forme de chaîne.
### Décodage de la charge utile des messages protobuf
Vous pouvez utiliser la fonction SQL de décodage pour configurer une règle capable de décoder la charge utile de votre message protobuf. Pour plus d’informations, veuillez consulter la section [Décodage des charges utiles des messages protobuf.](binary-payloads.md#binary-payloads-protobuf)
**Important**
Si vous omettez `source‐arn` ou `source‐account` si vous définissez des autorisations pour un AWS IoT principal, n'importe qui Compte AWS peut invoquer votre fonction de décodage par le biais d'autres AWS IoT règles. Pour sécuriser votre fonction, consultez les [politiques relatives aux compartiments](https://docs.aws.amazon.com/AmazonS3/latest/userguide/bucket-policies.html) dans le *guide de l'utilisateur d'Amazon Simple Storage Service*.
La signature de la fonction ressemble à ce qui suit :
```
decode(, 'proto', '', '', '', '')
```
`ENCODED DATA`
Spécifie les données codées en protobuf à décoder. Si l’intégralité du message envoyé à la règle est constituée de données codées en protobuf, vous pouvez référencer la charge utile binaire entrante brute à l’aide de `*` Sinon, ce champ doit être une chaîne JSON codée en base-64 et une référence à la chaîne peut être transmise directement.
1) Pour décoder une charge utile entrante protobuf binaire brute :
```
decode(*, 'proto', ...)
```
2) Pour décoder un message codé en protobuf représenté par une chaîne codée en base64 « a.b » :
```
decode(a.b, 'proto', ...)
```
`proto`
Spécifie les données à décoder dans un format de message protobuf. Si vous spécifiez `base64` au lieu de `proto`, cette fonction décodera les chaînes codées en base64 au format JSON.
`S3 BUCKET NAME`
Le nom du compartiment Amazon S3 dans lequel vous avez chargé votre fichier `FileDescriptorSet`.
`S3 OBJECT KEY`
Clé d’objet qui spécifie le fichier `FileDescriptorSet` dans le compartiment Amazon S3.
`PROTO NAME`
Le nom du fichier `.proto` (à l’exception de l’extension) à partir duquel le fichier `FileDescriptorSet` a été généré.
`MESSAGE TYPE`
Nom de la structure du message protobuf dans le fichier `FileDescriptorSet`, à laquelle les données à décoder doivent être conformes.
Voici un exemple d’expression SQL utilisant la fonction SQL de décodage :
```
SELECT VALUE decode(*, 'proto', 's3-bucket', 'messageformat.desc', 'myproto', 'messagetype') FROM 'some/topic'
```
+ `*`
Représente une charge utile binaire entrante, conforme au type de message protobuf appelé `mymessagetype`
+ `messageformat.desc`
Le fichier `FileDescriptorSet` stocké dans un compartiment Amazon S3 nommé `s3-bucket`.
+ `myproto`
Le fichier `.proto` d’origine utilisé pour générer le fichier `FileDescriptorSet` nommé `myproto.proto`.
+ `messagetype`
Le type de message appelé `messagetype` (ainsi que toutes les dépendances importées) tel que défini dans `myproto.proto`.
## encode(value, encodingScheme)
Utilisez la fonction `encode` pour encoder la charge utile, qui peut être constituée de données non-JSON, dans sa représentation de chaîne basée sur le schéma d'encodage. Pris en charge par SQL 2016-03-23 et versions ultérieures.
value
Une des expressions valides, telles que définies dans la [AWS IoT Référence SQL](iot-sql-reference.md). Vous pouvez spécifier \$1 pour encoder la charge utile dans son ensemble, qu'elle soit ou non au format JSON. Si vous fournissez une expression, le résultat de l'évaluation est converti en une chaîne avant d'être codé.
encodingScheme
Chaîne littérale qui représente le schéma de codage à utiliser. Actuellement, seul `'base64'` est pris en charge.
## endswith(String, String)
Renvoie une valeur `Boolean` indiquant si le premier argument `String` se termine par le deuxième argument `String`. Si l'un des arguments est `Null` ou `Undefined`, le résultat a la valeur `Undefined`. Prise en charge par SQL 2015-10-08 et versions ultérieures.
Par exemple : `endswith("cat","at")` = true.
****
| Type d'argument 1 | Type d'argument 2 | Résultat |
| --- | --- | --- |
| String | String | Vrai si le premier argument se termine dans le second argument. Sinon, la valeur renvoyée est Faux. |
| Autre valeur | Autre valeur | Les deux arguments sont convertis en chaînes à l'aide des règles de conversion standard. Vrai si le premier argument se termine dans le second argument. Sinon, la valeur renvoyée est Faux. Si l'un des arguments est Null ou Undefined, le résultat a la valeur Undefined. |
## exp(Decimal)
Renvoie la valeur augmentée vers l'argument `Decimal`. Les arguments `Decimal` sont arrondis pour une meilleure prévision avant l'application de la fonction. Prise en charge par SQL 2015-10-08 et versions ultérieures.
Exemple : `exp(1)` = e.
****
| Type d’argument | Résultat |
| --- | --- |
| Int | Decimal (avec double précision), argument puissance e. |
| Decimal | Decimal (avec double précision), argument puissance e. |
| String | Decimal (avec double précision), argument puissance e. Si la valeur String ne peut pas être convertie en une valeur Decimal, le résultat est Undefined. |
| Autre valeur | Undefined. |
## floor(Decimal)
Arrondit la valeur `Decimal` donnée à la valeur `Int` inférieure la plus proche. Prise en charge par SQL 2015-10-08 et versions ultérieures.
Exemples :
`floor(1.2)` = 1
`floor(-1.2)` = -2
****
| Type d’argument | Résultat |
| --- | --- |
| Int | Int, la valeur d'argument. |
| Decimal | Int, la valeur Decimal arrondie à la valeur Int inférieure la plus proche. |
| String | Int. La chaîne est convertie en valeur Decimal et arrondie à la valeur Int inférieure la plus proche. Si la chaîne ne peut pas être convertie en une valeur Decimal, le résultat est Undefined. |
| Autre valeur | Undefined. |
## get
Extrait une valeur à partir d'un type de collection (tableau, chaîne, objet). Aucune conversion n'est appliquée au premier argument. Une conversion s'applique comme documenté dans le tableau au deuxième argument. Prise en charge par SQL 2015-10-08 et versions ultérieures.
Exemples :
`get(["a", "b", "c"], 1) ` = "b"
`get({"a":"b"}, "a")` = "b"
`get("abc", 0)` = « a ».
****
| Type d'argument 1 | Type d'argument 2 | Résultat |
| --- | --- | --- |
| Tableau | Tout type (converti valeur Int) | L'élément à l'index de base zéro de la valeur Array fourni par le deuxième argument (converti en Int). Si la conversion échoue, le résultat est Undefined. Si l'index est en dehors des limites de la valeur Array (négatif ou >= array.length), le résultat est Undefined. |
| String | Tout type (converti valeur Int) | Le caractère est à l'index de base zéro de la chaîne fournie par le deuxième argument (converti en Int). Si la conversion échoue, le résultat est Undefined. Si l'index est en dehors des limites de la chaîne (négatif ou >= string.length), le résultat est Undefined. |
| Objet | String (aucune conversion appliquée) | La valeur stockée dans le premier argument (l'objet) correspondant à la clé de chaîne fournie comme deuxième argument. |
| Autre valeur | N'importe quelle valeur | Undefined. |
## get\$1dynamodb (TableName,,,,, partitionKeyName ROLearn) partitionKeyValue sortKeyName sortKeyValue
Récupère des données d’une table DynamoDB. `get_dynamodb()` vous permet d’interroger une table DynamoDB pendant l’évaluation d’une règle. Vous pouvez filtrer ou augmenter les charges utiles des messages à l’aide des données extraites de DynamoDB. Pris en charge par SQL 2016-03-23 et versions ultérieures.
`get_dynamodb()` accepte les paramètres suivants :
tableName
Nom de la table DynamoDB à interroger.
partitionKeyName
Nom de la clé de partition. Pour plus d’informations, veuillez consulter [Clés DynamoDB](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/HowItWorks.CoreComponents.html#HowItWorks.CoreComponents.PrimaryKey).
partitionKeyValue
Valeur de la clé de partition utilisée pour identifier un enregistrement. Pour plus d’informations, veuillez consulter [Clés DynamoDB](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/HowItWorks.CoreComponents.html#HowItWorks.CoreComponents.PrimaryKey).
sortKeyName
(Facultatif) Nom de la clé de tri. Ce paramètre n’est requis que si la table DynamoDB interrogée utilise une clé composite. Pour plus d’informations, veuillez consulter [Clés DynamoDB](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/HowItWorks.CoreComponents.html#HowItWorks.CoreComponents.PrimaryKey).
sortKeyValue
(Facultatif) Valeur de la clé de tri. Ce paramètre n’est requis que si la table DynamoDB interrogée utilise une clé composite. Pour plus d’informations, veuillez consulter [Clés DynamoDB](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/HowItWorks.CoreComponents.html#HowItWorks.CoreComponents.PrimaryKey).
roleArn
ARN d’un rôle IAM qui accorde l’accès à la table DynamoDB. Le moteur de règles assume ce rôle pour accéder à la table DynamoDB en votre nom. Évitez d'utiliser un rôle trop permissif. Accordez au rôle uniquement les autorisations requises par la règle. L’exemple de stratégie suivant accorde l’accès à une table DynamoDB.
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "dynamodb:GetItem",
"Resource": "arn:aws:dynamodb:us-east-1:123456789012:table/table-name"
}
]
}
```
À titre d’exemple d’utilisation de `get_dynamodb()`, supposons que vous disposez d’une table DynamoDB contenant l’ID d’appareil et les informations d’emplacement de tous vos appareils connectés à AWS IoT. L'instruction SELECT suivante utilise la fonction `get_dynamodb()` pour récupérer l'emplacement de l'ID d'appareil spécifié :
`SELECT *, get_dynamodb("InServiceDevices", "deviceId", id, "arn:aws:iam::12345678910:role/getdynamo").location AS location FROM 'some/topic' `
**Note**
Vous pouvez appeler `get_dynamodb()` une fois au maximum par instruction SQL. L'appel de `get_dynamodb()` plusieurs fois dans une même instruction SQL entraîne la fin de la règle sans invoquer aucune action.
## get\$1mqtt\$1property (nom)
Fait référence à l'un MQTT5 des en-têtes suivants :`contentType`, `payLoadFormatIndicator``responseTopic`, et`correlationData`. Cette fonction prend l’une des chaînes littérales suivantes comme argument :`content_type`, `format_indicator` `response_topic`, et`correlation_data`. Pour plus d’informations, veuillez consulter la table des **arguments de fonction** suivante.
contentType
Chaîne : codée en UTF-8 qui décrit le contenu du message de publication.
payLoadFormatIndicateur
Chaîne : une valeur de chaîne qui indique si la charge utile est formatée en UTF-8. Les valeurs valides sont `UNSPECIFIED_BYTES` et `UTF8_DATA`.
Rubrique de réponse
Chaîne : Chaîne codée en UTF-8 utilisée comme nom de rubrique pour un message de réponse. La rubrique de réponse permet de décrire la rubrique dans laquelle le récepteur doit effectuer la publication dans le cadre du flux demande-réponse. Le sujet ne doit pas contenir de caractères génériques.
Données de corrélation
Chaîne : Les données binaires codées en base64 utilisées par l’expéditeur du message de demande pour identifier la demande à laquelle le message de réponse correspond lorsqu’il est reçu.
Le tableau suivant indique les arguments de fonction acceptables et les types de retour associés pour la fonction `get_mqtt_property` :
**Arguments de la fonction**
| SQL | Type de données renvoyé (le cas échéant) | Type de données renvoyé (s’il n’est pas présent) |
| --- | --- | --- |
| get\$1mqtt\$1property("format\$1indicator") | Chaîne (UNSPECIFIED\$1BYTES ou \$1DATA) UTF8 | Chaîne (UNSPECIFIED\$1BYTES) |
| get\$1mqtt\$1property("content\$1type") | String | Non défini |
| get\$1mqtt\$1property("response\$1topic") | String | Non défini |
| get\$1mqtt\$1property("correlation\$1data") | Chaîne codée en base64 | Non défini |
| get\$1mqtt\$1property("some\$1invalid\$1name") | Non défini | Non défini |
L'exemple de règles SQL suivant fait référence à l'un MQTT5 des en-têtes suivants :`contentType`, `payLoadFormatIndicator``responseTopic`, et`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 (expression, DefaultValue)
Renvoie la valeur par défaut dans le deuxième paramètre s'il est spécifié ou renvoie undefined, lorsque l'expression du premier paramètre renvoie null, undefined ou échoue. Pris en charge par SQL 2016-03-23 et versions ultérieures.
**Important**
`get_or_default`ne prend pas en charge les charges utiles non JSON directement telles quelles. Si vous utilisez une charge utile autre que JSON, utilisez les fonctions `encode` or`decode`.
`get_or_default()` accepte les paramètres suivants :
expression
Toute expression valide contenant[Types de données](iot-sql-data-types.md),[Fonctions](#iot-sql-functions),[Littéraux](iot-sql-literals.md), [Variables](iot-sql-set.md#iot-sql-set-usage)[Requêtes d'objets imbriqués](iot-sql-nested-queries.md), ou[Extensions JSON](iot-sql-json.md).
defaultValue
(Facultatif) Toute expression valide contenant [Types de données](iot-sql-data-types.md)[Fonctions](#iot-sql-functions),[Littéraux](iot-sql-literals.md),[Requêtes d'objets imbriqués](iot-sql-nested-queries.md), [des variables](iot-sql-set.md#iot-sql-set-usage) ou[Extensions JSON](iot-sql-json.md). Il s'agit de la valeur à renvoyer chaque fois que le premier argument renvoie null, undefined ou échoue.
Les fonctions qui extraient des données à partir de ressources appartenant au client, telles que get\$1secret, get\$1dynamodb, aws\$1lambda, get\$1thing\$1shadow, decode-protobuf et machinelearning\$1predict, ne sont pas autorisées pour le paramètre DefaultValue.
Le tableau suivant indique les arguments de fonction acceptables pour chaque argument et leurs sorties associées :
| Premier argument | Deuxième argument | Output |
| --- | --- | --- |
| Évaluation réussie | N'importe quelle valeur ou non spécifiée | La valeur du premier argument. |
| Non défini, nul ou échec | Toute valeur, y compris Undefined ou Null | La valeur du deuxième argument. |
| Non défini, nul ou échec | non précisé | Undefined |
**Exemples :**
Exemple 1 :
L'exemple suivant fournit une valeur DefaultValue en cas d'échec d'une table ou d'une requête DynamoDB :
```
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'
```
Exemple 2 :
L'exemple suivant fournit une valeur par défaut sûre « UNKNOWN » si le statut n'est pas défini :
```
SELECT
get_or_default( CASE status
WHEN 'active' THEN 'GOOD'
WHEN 'inactive' THEN 'BAD'/
ELSE 'UNKNOWN'
END, 'UNKNOWN') as status_category
FROM 'topic/subtopic'
```
Exemple 3 :
L'exemple suivant montre comment vous pouvez également utiliser get\$1or\$1default avec un seul paramètre. Cela est utile dans les scénarios où vous n'avez peut-être pas de valeur par défaut claire, mais où vous ne voulez pas que l'exécution de votre règle échoue.
```
SELECT
get_dynamodb("DeviceConfig", "deviceId", nonExistentId, "arn:aws:iam::123456789012:role/ROLE_NAME") as config
FROM 'device/telemetry'
```
Si la recherche DynamoDB échoue, l'exécution de la règle échouera et aucune action ne sera exécutée. Si le code SQL suivant est utilisé à la place :
```
SELECT
get_or_default(get_dynamodb("DeviceConfig", "deviceId", nonExistentId, "arn:aws:iam::123456789012:role/ROLE_NAME")) as config
FROM 'device/telemetry'
```
L'instruction get\$1or\$1default sera évaluée à. Dans cet exemple`Undefined`, l'instruction SELECT sera globalement évaluée à `{}` et toutes les actions relatives aux règles seront tentées.
**Important**
Nous vous recommandons de suivre les meilleures pratiques suivantes pour garantir la sécurité lors de l'utilisation de cette fonction :
Évitez d'utiliser des secrets codés en dur dans les définitions de règles, y compris les valeurs par défaut
Utilisation AWS Secrets Manager pour gérer des informations sensibles
## get\$1registry\$1data (RegistryAPI, ThingName, ROLearn)
Récupère les AWS IoT données du registre des objets dans une AWS IoT règle. Vous pouvez lire les données du registre (telles que les attributs, le type d'objet et les groupes d'objets auxquels appartient un appareil) et utiliser ces informations pour filtrer, enrichir ou acheminer les messages de manière dynamique. Pris en charge par SQL 2016-03-23 et versions ultérieures.
`get_registry_data()` accepte les paramètres suivants :
API de registre
L'API de registre appelée. Les valeurs valides sont `DescribeThing` et `ListThingGroupsForThing`. Ces valeurs doivent être des chaînes constantes.
thingName
Chaîne : nom de l'objet dont vous souhaitez récupérer les données de registre.
roleArn
Chaîne : un ARN de rôle avec une `iot:DescribeThing` and/or `iot:ListThingGroupsForThing` autorisation d'autorisation basée sur l'API appelée.
Le format de réponse de la `get_registry_data` fonction est le même que celui de l'API de registre appelée. Pour en savoir plus, veuillez consulter [DescribeThing](https://docs.aws.amazon.com//iot/latest/apireference/API_DescribeThing.html) et [ListThingGroupsForThing](https://docs.aws.amazon.com//iot/latest/apireference/API_ListThingGroupsForThing.html) APIs.
Exemple :
Vous pouvez récupérer des informations sur le type d'objet pour filtrer les messages d'événements du AWS IoT Core cycle de vie pour les objets (le nom de l'objet correspondant à l'identifiant du client MQTT) où se trouve le type d'objet. `testenv`
```
SELECT *
FROM '$aws/events/lifecycle/+'
WHERE
get_registry_data("DescribeThing",clientId,[roleArn]).thingTypeName='testenv'
```
Exemple :
Vous pouvez récupérer les attributs d'objet d'un appareil avec un nom d'objet `sensor1` pour tous les messages envoyés par son périphérique passerelle`gateway1`.
```
SELECT *, get_registry_data("DescribeThing","sensor1",[roleArn]).attributes.temperature_threhold AS device1_tempthreshold
FROM home1/gateway1/sensor1/#
```
**Note**
Vous pouvez appeler `get_registry_data()` un maximum d'une fois par instruction SQL et par modèle de substitution pour les actions et les actions d'erreur.
## get\$1secret (SecreTid, SecretType, clé, roLearn)
Récupère la valeur du champ chiffré `SecretString` ou `SecretBinary` de la version actuelle d’un secret dans [AWS Secrets Manager](https://docs.aws.amazon.com/secretsmanager/latest/userguide/). Pour plus d'informations sur la création et la gestion de secrets [CreateSecret](https://docs.aws.amazon.com/secretsmanager/latest/apireference/API_CreateSecret.html), consultez les [UpdateSecret](https://docs.aws.amazon.com/secretsmanager/latest/apireference/API_UpdateSecret.html)sections, et [PutSecretValue](https://docs.aws.amazon.com/secretsmanager/latest/apireference/API_PutSecretValue.html).
`get_secret()` accepte les paramètres suivants :
secretId
Chaîne : Amazon Resource Name (ARN) ou nom convivial du secret à récupérer.
Type de secret
Chaîne : type secret. Valeurs valides : `SecretString` \$1 `SecretBinary`.
SecretString
+ Pour les secrets que vous créez sous forme d'objets JSON à l'aide de APIs, de AWS CLI, ou de la AWS Secrets Manager console :
+ Si vous spécifiez une valeur pour le paramètre `key`, cette fonction renvoie la valeur de la clé spécifiée.
+ Si vous ne spécifiez pas de valeur pour le paramètre `key`, cette fonction renvoie l’objet JSON complet.
+ Pour les secrets que vous créez en tant qu'objets non JSON en utilisant le APIs ou le AWS CLI :
+ Si vous spécifiez une valeur pour le paramètre `key`, cette fonction échoue avec une exception.
+ Si vous ne spécifiez pas de valeur pour le paramètre `key`, cette fonction renvoie le contenu du secret.
SecretBinary
+ Si vous spécifiez une valeur pour le paramètre `key`, cette fonction échoue avec une exception.
+ Si vous ne spécifiez aucune valeur du paramètre `key`, cette fonction renvoie la valeur secrète sous forme de chaîne UTF-8 codée en base64.
clé
(Facultatif) Chaîne : nom de la clé à l’intérieur d’un objet JSON stocké dans le champ `SecretString` d’un secret. Utilisez cette valeur lorsque vous souhaitez récupérer uniquement la valeur d’une clé stockée dans un secret au lieu de récupérer l’intégralité de l’objet JSON.
Si vous spécifiez une valeur pour ce paramètre et que le secret ne contient aucun objet JSON dans son champ `SecretString`, cette fonction échoue avec une exception.
roleArn
Chaîne : un ARN de rôle avec des autorisations `secretsmanager:GetSecretValue` et `secretsmanager:DescribeSecret`.
**Note**
Cette fonction renvoie toujours la version actuelle du secret (la version avec la balise `AWSCURRENT`). Le moteur de AWS IoT règles met en cache chaque secret pendant 15 minutes maximum. Par conséquent, le moteur de règles peut prendre jusqu’à 15 minutes pour mettre à jour un secret. Cela signifie que si vous récupérez un secret jusqu'à 15 minutes après une mise à jour avec AWS Secrets Manager, cette fonction peut renvoyer la version précédente.
Cette fonction n'est pas mesurée, mais des AWS Secrets Manager frais s'appliquent. En raison du mécanisme de mise en cache secret, le moteur de règles appelle AWS Secrets Manager occasionnellement. Le moteur de règles étant un service entièrement distribué, il est possible que vous receviez plusieurs appels d’API Secrets Manager depuis le moteur de règles pendant la fenêtre de mise en cache de 15 minutes.
Exemples :
Vous pouvez utiliser la fonction `get_secret` dans un en-tête d’authentification dans le cadre d’une action de règle HTTPS, comme dans l’exemple d’authentification par clé d’API suivant.
```
"API_KEY": "${get_secret('API_KEY', 'SecretString', 'API_KEY_VALUE', 'arn:aws:iam::12345678910:role/getsecret')}"
```
Pour plus d’informations sur l’action de règle HTTPS, veuillez consulter [HTTP](https-rule-action.md).
## get\$1thing\$1shadow (ThingName, ShadowName, RolEARN)
Renvoie le shadow spécifié de l'objet spécifié. Pris en charge par SQL 2016-03-23 et versions ultérieures.
thingName
Chaîne : nom de l'objet dont vous souhaitez récupérer le shadow.
shadowName
(Facultatif) Chaîne : nom du shadow. Ce paramètre est requis uniquement quand vous référencez des shadows nommés.
roleArn
Chaîne : un ARN de rôle avec une autorisation `iot:GetThingShadow`.
Exemples :
Lorsqu'elle est utilisée avec un shadow nommé, fournissez le paramètre `shadowName`.
```
SELECT * from 'topic/subtopic'
WHERE
get_thing_shadow("MyThing","MyThingShadow","arn:aws:iam::123456789012:role/AllowsThingShadowAccess")
.state.reported.alarm = 'ON'
```
Lorsqu'elle est utilisée avec un shadow non nommé, omettez le paramètre `shadowName`.
```
SELECT * from 'topic/subtopic'
WHERE
get_thing_shadow("MyThing","arn:aws:iam::123456789012:role/AllowsThingShadowAccess")
.state.reported.alarm = 'ON'
```
## get\$1user\$1properties () userPropertyKey
Références aux propriétés utilisateur, qui est un type d'en-tête de propriété pris en charge dans MQTT5.
UserProperty
Chaîne : une propriété utilisateur est une paire clé-valeur. Cette fonction prend la clé comme argument et renvoie un tableau de toutes les valeurs correspondant à la clé associée.
**Arguments de la fonction**
Pour les propriétés utilisateur suivantes dans les en-têtes des messages :
| Clé | Valeur |
| --- | --- |
| une clé | une valeur |
| une clé différente | une valeur différente |
| une clé | valeur avec clé dupliquée |
Le tableau suivant présente le comportement SQL attendu :
| SQL | Type de données de retour | Valeur de données de retour |
| --- | --- | --- |
| get\$1user\$1properties (« une clé ») | Tableau de chaînes | ['some value', 'value with duplicate key'] |
| get\$1user\$1properties (« une clé ») | Tableau de chaînes | ['a different value'] |
| get\$1user\$1properties ( ) | Tableau d’objets de paire clé-valeur | [\$1'"some key": "some value"'\$1, \$1"other key": "a different value"\$1, \$1"some key": "value with duplicate key"\$1] |
| get\$1user\$1properties (« clé inexistante ») | Non défini | |
L'exemple de règles SQL suivant fait référence aux propriétés utilisateur (un type d'en-tête de MQTT5 propriété) dans la charge utile :
```
SELECT *, get_user_properties('user defined property key') as userProperty
FROM 'some/topic'
```
## Fonctions de hachage
AWS IoT fournit les fonctions de hachage suivantes :
+ md2
+ md5
+ sha1
+ sha224
+ sha256
+ sha384
+ sha512
Toutes les fonctions de hachage prévoit un argument de type chaîne. Le résultat est la valeur hachée de cette chaîne. Les conversions de chaîne standard s'appliquent aux arguments non-chaîne. Toutes les fonctions de hachage sont prises en charge par SQL 2015-10-08 et versions ultérieures.
Exemples :
`md2("hello")` = "a9046c73e00331af68917d3804f70655"
`md5("hello")` = "5d41402abc4b2a76b9719d911017c592"
## indexof(String, String)
Renvoie le premier index (de base 0) du deuxième argument comme une sous-chaîne dans le premier argument. Les deux arguments doivent être des chaînes. Les arguments qui ne sont pas des chaînes sont soumis aux règles de conversion de chaînes standard. Cette fonction ne s'applique pas aux tableaux, uniquement aux chaînes. Pris en charge par SQL 2016-03-23 et versions ultérieures.
Exemples :
`indexof("abcd", "bc") ` = 1
## isNull()
Retourne la valeur true si la valeur de l'argument est `Null`. Pris en charge par SQL 2016-03-23 et versions ultérieures.
Exemples :
`isNull(5) ` = false.
`isNull(Null) ` = vrai.
****
| Type d’argument | Résultat |
| --- | --- |
| Int | false |
| Decimal | false |
| Boolean | false |
| String | false |
| Array | false |
| Object | false |
| Null | vrai |
| Undefined | false |
## isUndefined()
Retourne la valeur true si l'argument est `Undefined`. Pris en charge par SQL 2016-03-23 et versions ultérieures.
Exemples :
`isUndefined(5) ` = false.
`isUndefined(floor([1,2,3]))) ` = vrai.
****
| Type d’argument | Résultat |
| --- | --- |
| Int | false |
| Decimal | false |
| Boolean | false |
| String | false |
| Array | false |
| Object | false |
| Null | false |
| Undefined | true |
## length(String)
Renvoie le nombre de caractères dans la chaîne fournie. Les règles de conversion standard s'appliquent aux arguments non-`String`. Pris en charge par SQL 2016-03-23 et versions ultérieures.
Exemples :
`length("hi")` = 2
`length(false)` = 5
## ln(Decimal)
Renvoie le logarithme naturel de l'argument Les arguments `Decimal` sont arrondis pour une meilleure prévision avant l'application de la fonction. Prise en charge par SQL 2015-10-08 et versions ultérieures.
Exemple : `ln(e)` = 1.
****
| Type d’argument | Résultat |
| --- | --- |
| Int | Decimal (avec double précision), le logarithme naturel de l'argument. |
| Decimal | Decimal (avec double précision), le logarithme naturel de l'argument. |
| Boolean | Undefined. |
| String | Decimal (avec double précision), le logarithme naturel de l'argument. Si la chaîne ne peut pas être convertie en une valeur Decimal, le résultat est Undefined. |
| Tableau | Undefined. |
| Objet | Undefined. |
| Null | Undefined. |
| Non défini | Undefined. |
## log(Decimal)
Renvoie le logarithme 10 de base de l'argument Les arguments `Decimal` sont arrondis pour une meilleure prévision avant l'application de la fonction. Prise en charge par SQL 2015-10-08 et versions ultérieures.
Exemple : `log(100)` = 2.0.
****
| Type d’argument | Résultat |
| --- | --- |
| Int | Decimal (avec double précision), le logarithme de base 10 de l'argument. |
| Decimal | Decimal (avec double précision), le logarithme de base 10 de l'argument. |
| Boolean | Undefined. |
| String | Decimal (avec double précision), le logarithme de base 10 de l'argument. Si la valeur String ne peut pas être convertie en une valeur Decimal, le résultat est Undefined. |
| Tableau | Undefined. |
| Objet | Undefined. |
| Null | Undefined. |
| Non défini | Undefined. |
## lower(String)
Renvoie la version en minuscules de la valeur de `String` donnée. Les arguments non-chaîne sont convertis en chaînes à l'aide des règles de conversion standard. Prise en charge par SQL 2015-10-08 et versions ultérieures.
Exemples :
`lower("HELLO")` = "bonjour".
`lower(["HELLO"])` = "[\$1"bonjour\$1"]".
## lpad(String, Int)
Renvoie l'argument `String`, complété à gauche par le nombre d'espaces spécifié par le deuxième argument. L'argument `Int` doit être compris entre 0 et 1000. Si la valeur fournie se situe en dehors de cette plage valide, l'argument est défini sur la valeur valide la plus proche (0 ou 1 000). Prise en charge par SQL 2015-10-08 et versions ultérieures.
Exemples :
`lpad("hello", 2)` = "` hello`".
`lpad(1, 3)` = "` 1`"
****
| Type d'argument 1 | Type d'argument 2 | Résultat |
| --- | --- | --- |
| String | Int | String, l'argument String fourni, complété à gauche par un nombre d'espaces égal à la valeur Int. |
| String | Decimal | L'argument Decimal est arrondi à la valeur Int inférieure la plus proche, et l'argument String est complété à gauche par le nombre d'espaces spécifié. |
| String | String | Le deuxième argument est converti en valeur Decimal, qui est arrondie à la valeur Int inférieure la plus proche, et l'argument String est complété à gauche par le nombre d'espaces spécifié. Si le deuxième argument ne peut pas être converti en une valeur Int, le résultat Undefined. |
| Autre valeur | Int/Decimal/String | La première valeur est convertie en une valeur String à l'aide des conversions standard, puis la fonction LPAD est appliquée sur cette valeur String. Si elle ne peut pas être convertie, le résultat est Undefined. |
| N'importe quelle valeur | Autre valeur | Undefined. |
## ltrim(String)
Supprime tous les espaces de début (tabulations et espaces) de la valeur `String` fournie. Prise en charge par SQL 2015-10-08 et versions ultérieures.
Exemple :
`Ltrim(" h i ")` = "bonjour".
****
| Type d’argument | Résultat |
| --- | --- |
| Int | La représentation String de Int avec tous les espaces de début supprimés. |
| Decimal | La représentation String de Decimal avec tous les espaces de début supprimés. |
| Boolean | La représentation String de la valeur booléenne (« true » ou « false ») avec tous les espaces de début supprimés. |
| String | L'argument avec tous les espaces de début supprimés. |
| Tableau | La représentation String de Array (à l'aide des règles de conversion standard) avec tous les espaces de début supprimés. |
| Objet | La représentation String de l'objet (à l'aide des règles de conversion standard) avec tous les espaces de début supprimés. |
| Null | Undefined. |
| Non défini | Undefined. |
## machinelearning\$1predict(modelId, roleArn, record)
Utilisez cette `machinelearning_predict` fonction pour faire des prédictions en utilisant les données d'un message MQTT basé sur un modèle Amazon SageMaker AI. Prise en charge par SQL 2015-10-08 et versions ultérieures. Les arguments de la fonction `machinelearning_predict` sont :
modelId
L'ID du modèle sur lequel doit être réalisée la prévision. Le point de terminaison en temps réel du modèle doit être activé.
roleArn
Le rôle IAM qui dispose d’une stratégie avec les autorisations `machinelearning:Predict` et `machinelearning:GetMLModel` permet d’accéder au modèle par rapport auquel la prévision doit être réalisée.
record
Les données à transmettre à l'API SageMaker AI Predict. Elles doivent être représentées sous la forme d'un objet JSON à couche unique. Si l'enregistrement est un objet JSON multiniveau, il est mis à plat en sérialisant ses valeurs. Par exemple, le code JSON suivant :
```
{ "key1": {"innerKey1": "value1"}, "key2": 0}
```
deviendrait :
```
{ "key1": "{\"innerKey1\": \"value1\"}", "key2": 0}
```
La fonction renvoie un objet JSON dans les champs suivants :
predictedLabel
Classification de l'entrée basée sur le modèle.
détails
Contient les attributs suivants :
PredictiveModelType
Type de modèle. Les valeurs valides sont REGRESSION, BINARY, MULTICLASS.
Algorithm
Algorithme utilisé par l' SageMaker IA pour faire des prédictions. La valeur doit être SGD.
predictedScores
Contient le score de classification brut correspondant à chaque étiquette.
predictedValue
La valeur prédite par l' SageMaker IA.
## mod(Decimal, Decimal)
Renvoie le reste résultant de la division du premier argument par le deuxième argument. Équivalent à [remainder(Decimal, Decimal)](#iot-func-remainder). Vous pouvez également utiliser « % » comme opérateur infixe pour la même fonctionnalité modulo. Prise en charge par SQL 2015-10-08 et versions ultérieures.
Exemple : `mod(8, 3)` = 2.
****
| Opérande gauche | Opérande droit | Output |
| --- | --- | --- |
| Int | Int | Int, les premier et deuxième arguments pour lesquels vous voulez exécuter la fonctionnalité Modulo. |
| Int/Decimal | Int/Decimal | Decimal, le premier argument et le deuxième opérande pour lesquels vous voulez exécuter la fonctionnalité Modulo. |
| String/Int/Decimal | String/Int/Decimal | Si toutes les chaînes sont converties en décimales, le résultat est le premier argument divisé par le deuxième argument. Sinon la valeur est renvoy, Undefined. |
| Autre valeur | Autre valeur | Undefined. |
## nanol (,) AnyValue AnyValue
Renvoie le premier argument s'il s'agit d'une valeur `Decimal` valide. Sinon, le deuxième argument est renvoyé. Prise en charge par SQL 2015-10-08 et versions ultérieures.
Exemple : `Nanvl(8, 3)` = 8.
****
| Type d'argument 1 | Type d'argument 2 | Output |
| --- | --- | --- |
| Non défini | N'importe quelle valeur | Le deuxième argument. |
| Null | N'importe quelle valeur | Le deuxième argument. |
| Decimal (NaN) | N'importe quelle valeur | Le deuxième argument. |
| Decimal (non-NaN) | N'importe quelle valeur | Le premier argument. |
| Autre valeur | N'importe quelle valeur | Le premier argument. |
## newuuid()
Retourne un UUID aléatoire de 16 octets. Prise en charge par SQL 2015-10-08 et versions ultérieures.
Exemple: `newuuid()` = `123a4567-b89c-12d3-e456-789012345000`
## numbytes(String)
Renvoie le nombre d'octets dans l'encodage UTF-8 de la chaîne fournie. Les règles de conversion standard s'appliquent aux arguments non-`String`. Pris en charge par SQL 2016-03-23 et versions ultérieures.
Exemples :
`numbytes("hi")` = 2
`numbytes("€") ` = 3
## parse\$1time(String, Long[, String])
Utilisez cette `parse_time` fonction pour formater un horodatage dans un format lisible par l'homme date/time . Pris en charge par SQL 2016-03-23 et versions ultérieures. Pour convertir une chaîne d’horodatage en millisecondes, veuillez consulter [time\$1to\$1epoch (Chaîne, Chaîne)](#iot-sql-function-time-to-epoch).
La fonction `parse_time` attend les arguments suivants :
pattern
(String) Un date/time modèle qui suit les formats [Joda-Time](http://www.joda.org/joda-time/apidocs/org/joda/time/format/DateTimeFormat.html).
timestamp
(Long) Heure à formater en millisecondes depuis l'époque Unix. Voir la fonction [timestamp()](#iot-function-timestamp).
timezone
(Chaîne) Fuseau horaire de la date/heure mise en forme. La valeur par défaut est « UTC ». La fonction prend en charge les [fuseaux horaires Joda-Time](http://joda-time.sourceforge.net/timezones.html). Cet argument est facultatif.
Exemples :
Lorsque ce message est publié dans la rubrique « A/B », la charge utile `{"ts": "1970.01.01 AD at 21:46:40 CST"}` est envoyée au compartiment 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"
}
}
```
Lorsque ce message est publié dans la rubrique « A/B », une charge utile similaire à `{"ts": "2017.06.09 AD at 17:19:46 UTC"}` (mais avec la date et l'heure du moment) est envoyée au compartiment 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()` peut également servir de modèle de substitution. Par exemple, lorsque ce message est publié dans la rubrique « A/B », la charge utile est envoyée au compartiment S3 avec la clé = « 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)
Renvoie le premier argument augmenté vers le deuxième argument. Les arguments `Decimal` sont arrondis pour une meilleure prévision avant l'application de la fonction. Prise en charge par SQL 2015-10-08 et versions ultérieures. Prise en charge par SQL 2015-10-08 et versions ultérieures.
Exemple : `power(2, 5)` = 32.0.
****
| Type d'argument 1 | Type d'argument 2 | Output |
| --- | --- | --- |
| Int/Decimal | Int/Decimal | Une valeur Decimal (avec double précision), le premier argument renvoyé à la puissance du deuxième argument. |
| Int/Decimal/String | Int/Decimal/String | Une valeur Decimal (avec double précision), le premier argument renvoyé à la puissance du deuxième argument. Toutes les chaînes sont converties en décimales. Si tout valeur String échoue à être convertie en Decimal, le résultat est Undefined. |
| Autre valeur | Autre valeur | Undefined. |
## principal()
Renvoie le principal utilisé par le terminal pour l’authentification, en fonction de la manière dont le message déclencheur a été publié. Le tableau suivant décrit le mandataire renvoyé pour chaque méthode et protocole de publication.
****
| Méthode de publication du message | Protocole | Type d’informations d’identification | Principal |
| --- | --- | --- | --- |
| Client MQTT | MQTT | Certificat d'appareil X.509 | Empreinte du certificat X.509 |
| AWS IoT client MQTT pour console | MQTT | Utilisateur ou rôle IAM | iam-role-id:session-name |
| AWS CLI | HTTP | Utilisateur ou rôle IAM | userid |
| AWS IoT SDK de l'appareil | MQTT | Certificat d'appareil X.509 | Empreinte du certificat X.509 |
| AWS IoT SDK de l'appareil | MQTT terminé WebSocket | Utilisateur ou rôle IAM | userid |
Les exemples suivants illustrent les différents types de valeurs qui peuvent être renvoyés par `principal()` :
+ Empreinte du certificat X.509 : `ba67293af50bf2506f5f93469686da660c7c844e7b3950bfb16813e0d31e9373`
+ ID de rôle IAM et nom de session : `ABCD1EFG3HIJK2LMNOP5:my-session-name`
+ Renvoie un ID utilisateur : `ABCD1EFG3HIJK2LMNOP5`
## rand()
Renvoie une valeur pseudo aléatoire, uniformément distribuée en double entre 0,0 et 1,0. Prise en charge par SQL 2015-10-08 et versions ultérieures.
Exemple :
`rand()` = 0.8231909191640703
## regexp\$1matches(String, String)
Renvoie la valeur true si la chaîne (le premier argument) contient un élément correspondant à l'expression régulière (le deuxième argument). Si vous l’utilisez `|` dans l’expression régulière, utilisez-la avec `()`.
Exemples :
`regexp_matches("aaaa", "a{2,}") ` = vrai.
`regexp_matches("aaaa", "b")` = false.
`regexp_matches("aaa", "(aaa|bbb)") ` = vrai.
`regexp_matches("bbb", "(aaa|bbb)") ` = vrai.
`regexp_matches("ccc", "(aaa|bbb)") ` = false.
**Premier argument :**
| Type d’argument | Résultat |
| --- | --- |
| Int | La représentation String de la valeur Int. |
| Decimal | La représentation String de la valeur Decimal. |
| Boolean | La représentation String de la valeur booléenne (« vrai » ou « faux »). |
| String | La valeur String. |
| Tableau | La représentation String de la valeur Array (à l'aide des règles de conversion standard). |
| Objet | La représentation String de l'objet (à l'aide des règles de conversion standard). |
| Null | Undefined. |
| Non défini | Undefined. |
*Deuxième argument :*
Il doit s'agir d'une expression regex valide. Les types non-chaîne sont convertis en valeurs `String` à l'aide des règles de conversion standard. Selon le type, la chaîne résultante peut ne pas être une expression régulière valide. Si l'argument (converti) n'est pas un regex valide, le résultat est `Undefined`.
## regexp\$1replace(String, String, String)
Remplace toutes les occurrences du deuxième argument (expression régulière) figurant dans le premier argument par le troisième argument. Fait référence aux groupes de capture avec « \$1 ». Prise en charge par SQL 2015-10-08 et versions ultérieures.
Exemple :
`regexp_replace("abcd", "bc", "x")` = "axd".
`regexp_replace("abcd", "b(.*)d", "$1")` = "ac".
**Premier argument :**
| Type d’argument | Résultat |
| --- | --- |
| Int | La représentation String de la valeur Int. |
| Decimal | La représentation String de la valeur Decimal. |
| Boolean | La représentation String de la valeur booléenne (« vrai » ou « faux »). |
| String | La valeur source. |
| Tableau | La représentation String de la valeur Array (à l'aide des règles de conversion standard). |
| Objet | La représentation String de l'objet (à l'aide des règles de conversion standard). |
| Null | Undefined. |
| Non défini | Undefined. |
*Deuxième argument :*
Il doit s'agir d'une expression regex valide. Les types non-chaîne sont convertis en valeurs `String` à l'aide des règles de conversion standard. Selon le type, la chaîne résultante peut ne pas être une expression régulière valide. Si l'argument (converti) n'est pas une expression regex valide, le résultat est `Undefined`.
*Troisième argument :*
Il doit s'agir d'une chaîne de remplacement regex valide. (Peut faire référence à d'autres groupes de capture.) Les types non-chaîne sont convertis en valeurs `String` à l'aide des règles de conversion standard. Si l'argument (converti) n'est pas une chaîne de remplacement regex valide, le résultat est `Undefined`.
## regexp\$1substr(String, String)
Recherche la première correspondance du deuxième paramètre (regex) dans le premier paramètre. Fait référence aux groupes de capture avec « \$1 ». Prise en charge par SQL 2015-10-08 et versions ultérieures.
Exemple :
`regexp_substr("hihihello", "hi")` = "bonjour"
`regexp_substr("hihihello", "(hi)*")` = "hihi"
**Premier argument :**
| Type d’argument | Résultat |
| --- | --- |
| Int | La représentation String de la valeur Int. |
| Decimal | La représentation String de la valeur Decimal. |
| Boolean | La représentation String de la valeur booléenne (« vrai » ou « faux »). |
| String | L'argument String. |
| Tableau | La représentation String de la valeur Array (à l'aide des règles de conversion standard). |
| Objet | La représentation String de l'objet (à l'aide des règles de conversion standard). |
| Null | Undefined. |
| Non défini | Undefined. |
*Deuxième argument :*
Il doit s'agir d'une expression regex valide. Les types non-chaîne sont convertis en valeurs `String` à l'aide des règles de conversion standard. Selon le type, la chaîne résultante peut ne pas être une expression régulière valide. Si l'argument (converti) n'est pas une expression regex valide, le résultat est `Undefined`.
## remainder(Decimal, Decimal)
Renvoie le reste résultant de la division du premier argument par le deuxième argument. Équivalent à [mod(Decimal, Decimal)](#iot-func-mod). Vous pouvez également utiliser « % » comme opérateur infixe pour la même fonctionnalité modulo. Prise en charge par SQL 2015-10-08 et versions ultérieures.
Exemple : `remainder(8, 3)` = 2.
****
| Opérande gauche | Opérande droit | Output |
| --- | --- | --- |
| Int | Int | Int, les premier et deuxième arguments pour lesquels vous voulez exécuter la fonctionnalité Modulo. |
| Int/Decimal | Int/Decimal | Decimal, le premier argument et le deuxième opérande pour lesquels vous voulez exécuter la fonctionnalité Modulo. |
| String/Int/Decimal | String/Int/Decimal | Si toutes les chaînes sont converties en décimales, le résultat est le premier argument divisé par le deuxième argument. Sinon la valeur est renvoy, Undefined. |
| Autre valeur | Autre valeur | Undefined. |
## replace(String, String, String)
Remplace toutes les occurrences du deuxième argument par le troisième argument dans le premier argument. Prise en charge par SQL 2015-10-08 et versions ultérieures.
Exemple :
`replace("abcd", "bc", "x")` = `"axd"`.
`replace("abcdabcd", "b", "x")` = `"axcdaxcd"`.
**Tous les arguments**
| Type d’argument | Résultat |
| --- | --- |
| Int | La représentation String de la valeur Int. |
| Decimal | La représentation String de la valeur Decimal. |
| Boolean | La représentation String de la valeur booléenne (« vrai » ou « faux »). |
| String | La valeur source. |
| Tableau | La représentation String de la valeur Array (à l'aide des règles de conversion standard). |
| Objet | La représentation String de l'objet (à l'aide des règles de conversion standard). |
| Null | Undefined. |
| Non défini | Undefined. |
## rpad(String, Int)
Renvoie l'argument chaîne, complété à droite par le nombre d'espaces spécifié dans le deuxième argument. L'argument `Int` doit être compris entre 0 et 1000. Si la valeur fournie se situe en dehors de cette plage valide, l'argument est défini sur la valeur valide la plus proche (0 ou 1 000). Prise en charge par SQL 2015-10-08 et versions ultérieures.
Exemples :
`rpad("hello", 2)` = "`hello `".
`rpad(1, 3)` = "`1 `".
****
| Type d'argument 1 | Type d'argument 2 | Résultat |
| --- | --- | --- |
| String | Int | L'argument String est complété à droite par un nombre d'espaces égal à la valeur Int fournie. |
| String | Decimal | L'argument Decimal est arrondi à la valeur Int inférieure la plus proche, et la chaîne est complétée à droite par un nombre d'espaces égal à la valeur Int fournie. |
| String | String | Le deuxième argument est converti en une valeur Decimal, qui est arrondie à la valeur Int inférieure la plus proche. L'argument String est complété à droite par un nombre d'espaces égal à la valeur Int fournie. |
| Autre valeur | Int/Decimal/String | La première valeur est convertie en une valeur String à l'aide des conversions standard, puis la fonction RPAD est appliquée sur cette valeur String. Si elle ne peut pas être convertie, le résultat est Undefined. |
| N'importe quelle valeur | Autre valeur | Undefined. |
## round(Decimal)
Arrondit la valeur `Decimal` donnée à la valeur `Int` la plus proche. Si la valeur `Decimal` se situe à équidistance entre deux valeurs `Int` (par exemple, 0,5), la valeur `Decimal` est arrondie à la valeur supérieure. Prise en charge par SQL 2015-10-08 et versions ultérieures.
Exemple : `Round(1.2)` = 1.
`Round(1.5)` = 2.
`Round(1.7)` = 2.
`Round(-1.1)` = -1.
`Round(-1.5)` = -2.
****
| Type d’argument | Résultat |
| --- | --- |
| Int | L'argument. |
| Decimal | La valeur Decimal est arrondie à la valeur Int inférieure la plus proche. |
| String | La valeur Decimal est arrondie à la valeur Int inférieure la plus proche. Si la chaîne ne peut pas être convertie en une valeur Decimal, le résultat est Undefined. |
| Autre valeur | Undefined. |
## rtrim(String)
Supprime tous les espaces de fin (tabulations et espaces) de la valeur `String` fournie. Prise en charge par SQL 2015-10-08 et versions ultérieures.
Exemples :
`rtrim(" h i ")` = " sa lut "
****
| Type d’argument | Résultat |
| --- | --- |
| Int | La représentation String de la valeur Int. |
| Decimal | La représentation String de la valeur Decimal. |
| Boolean | La représentation String de la valeur booléenne (« vrai » ou « faux »). |
| Tableau | La représentation String de la valeur Array (à l'aide des règles de conversion standard). |
| Objet | La représentation String de l'objet (à l'aide des règles de conversion standard). |
| Null | Undefined. |
| Non défini | Undefined |
## sign(Decimal)
Renvoie le signe d'un chiffre donné. Lorsque le signe de l'argument est positif, la valeur 1 et renvoyée. Lorsque le signe de l'argument est négatif, la valeur -1 et renvoyée. Si l'argument est 0, la valeur 0 est renvoyée. Prise en charge par SQL 2015-10-08 et versions ultérieures.
Exemples :
`sign(-7)` = -1.
`sign(0)` = 0.
`sign(13)` = 1.
****
| Type d’argument | Résultat |
| --- | --- |
| Int | Int, le signe de la valeur Int. |
| Decimal | Int, le signe de la valeur Decimal. |
| String | Int, le signe de la valeur Decimal. La chaîne est convertie en une valeur Decimal, et le signe de la valeur Decimal est renvoyée. Si la valeur String ne peut pas être convertie en une valeur Decimal, le résultat est Undefined. Prise en charge par SQL 2015-10-08 et versions ultérieures. |
| Autre valeur | Undefined. |
## sin(Decimal)
Renvoie le sinus d'un nombre en radians. Les arguments `Decimal` sont arrondis pour une meilleure prévision avant l'application de la fonction. Prise en charge par SQL 2015-10-08 et versions ultérieures.
Exemple : `sin(0)` = 0,0
****
| Type d’argument | Résultat |
| --- | --- |
| Int | Decimal (avec double précision), le sinus de l'argument. |
| Decimal | Decimal (avec double précision), le sinus de l'argument. |
| Boolean | Undefined. |
| String | Decimal (avec double précision), le sinus de l'argument. Si la chaîne ne peut pas être convertie en une valeur Decimal, le résultat est Undefined. |
| Tableau | Undefined. |
| Objet | Undefined. |
| Null | Undefined. |
| Undefined | Undefined. |
## sinh(Decimal)
Renvoie le sinus hyperbolique d'un nombre. Les valeurs `Decimal` sont arrondis pour une meilleure prévision avant l'application de la fonction. Le résultat est une valeur `Decimal` de double précision. Prise en charge par SQL 2015-10-08 et versions ultérieures.
Exemple : `sinh(2.3)` = 4,936961805545957
****
| Type d’argument | Résultat |
| --- | --- |
| Int | Decimal (avec double précision), le sinus hyperbolique de l'argument. |
| Decimal | Decimal (avec double précision), le sinus hyperbolique de l'argument. |
| Boolean | Undefined. |
| String | Decimal (avec double précision), le sinus hyperbolique de l'argument. Si la chaîne ne peut pas être convertie en une valeur Decimal, le résultat est Undefined. |
| Tableau | Undefined. |
| Objet | Undefined. |
| Null | Undefined. |
| Non défini | Undefined. |
## sourceip()
Récupère l’adresse IP d’un appareil ou du routeur qui s’y connecte. Si votre appareil est connecté directement à Internet, la fonction renvoie l’adresse IP source de l’appareil. Si votre appareil est connecté à un routeur connecté à Internet, la fonction renvoie l’adresse IP source du routeur. Prise en charge par SQL version 23/03/2016. `sourceip()` ne prend aucun paramètre.
**Important**
L’adresse IP source publique d’un appareil est souvent l’adresse IP de la dernière passerelle de traduction d’adresses réseau (NAT), telle que le routeur ou le modem câble de votre fournisseur d’accès Internet.
Exemples :
`sourceip()="192.158.1.38"`
`sourceip()="1.102.103.104"`
`sourceip()="2001:db8:ff00::12ab:34cd"`
Exemple SQL :
`SELECT *, sourceip() as deviceIp FROM 'some/topic'`
Exemples d'utilisation de la fonction sourceip () dans les actions de AWS IoT Core règles :
**Exemple 1**
L’exemple suivant montre comment appeler la fonction () en tant que [modèle de substitution](https://docs.aws.amazon.com//iot/latest/developerguide/iot-substitution-templates.html) dans une action [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"
}
}
]
}
}
```
**Exemple 2**
L’exemple suivant illustre comment ajouter la fonction sourceip () en tant que propriété utilisateur MQTT à l’aide de modèles de [substitution](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()}"
}
]
}
}
}
]
}
}
```
Vous pouvez récupérer l'adresse IP source à partir des messages transmis aux AWS IoT Core règles depuis les chemins Message Broker et [Basic Ingest](https://docs.aws.amazon.com//iot/latest/developerguide/iot-basic-ingest.html). Vous pouvez également récupérer l'adresse IP source pour IPv4 les deux IPv6 messages. L’adresse IP source sera affichée comme suit :
IPv6: `yyyy:yyyy:yyyy::yyyy:yyyy`
IPv4: `xxx.xxx.xxx.xxx`
**Note**
L’adresse IP source d’origine ne sera pas transmise par le[biais de Republier l’action.](republish-rule-action.md).
## substring(String, Int[, Int])
Prévoit un argument `String` suivi par une ou deux valeurs `Int`. Pour un argument `String` et un seul argument `Int`, cette fonction renvoie la sous-chaîne de l'argument `String` fourni provenant de l'index (de base 0, inclus) `Int` fourni à la fin de l'argument `String`. Pour un argument `String` et deux arguments `Int`, cette fonction renvoie la sous-chaîne de l'argument `String` fourni provenant du premier argument d'index `Int` (de base 0, inclus) dans le deuxième argument d'index `Int` (de base 0, inclus). Les index qui sont inférieurs à zéro sont définis sur zéro. Les index qui sont supérieurs à la longueur de `String` sont définis sur la longueur de `String`. Pour la version des trois arguments, si le premier index est supérieur (ou égale) au deuxième index, le résultat et vide `String`.
Si les arguments fournis ne sont pas (*String*,*Int*) ou (*String*,*Int*,*Int*), les conversions standard sont appliquées aux arguments pour tenter de les convertir dans les types corrects. Si les types ne peuvent pas être convertis, le résultat de la fonction est `Undefined`. Prise en charge par SQL 2015-10-08 et versions ultérieures.
Exemples :
`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)` = "true".
`substring(false, -2.411E247)` = "false".
`substring("012345", 1, 3)` = "12".
`substring("012345", -50, 50)` = "012345".
`substring("012345", 3, 1)` = "".
## sql\$1version()
Renvoie la version SQL spécifiée dans cette règle. Prise en charge par SQL 2015-10-08 et versions ultérieures.
Exemple :
`sql_version()` = "2016-03-23"
## sqrt(Decimal)
Renvoie la racine carrée d'un nombre en radians. Les arguments `Decimal` sont arrondis pour une meilleure prévision avant l'application de la fonction. Prise en charge par SQL 2015-10-08 et versions ultérieures.
Exemple : `sqrt(9)` = 3.0.
****
| Type d’argument | Résultat |
| --- | --- |
| Int | La racine carrée de l'argument. |
| Decimal | La racine carrée de l'argument. |
| Boolean | Undefined. |
| String | La racine carrée de l'argument. Si la chaîne ne peut pas être convertie en une valeur Decimal, le résultat est Undefined. |
| Tableau | Undefined. |
| Objet | Undefined. |
| Null | Undefined. |
| Non défini | Undefined. |
## startswith(String, String)
Renvoie une valeur `Boolean` si le premier argument de type chaîne commence par le deuxième argument de type chaîne. Si l'un des arguments est `Null` ou `Undefined`, le résultat a la valeur `Undefined`. Prise en charge par SQL 2015-10-08 et versions ultérieures.
Exemple :
`startswith("ranger","ran")` = true
****
| Type d'argument 1 | Type d'argument 2 | Résultat |
| --- | --- | --- |
| String | String | Si la première chaîne commence par la deuxième chaîne. |
| Autre valeur | Autre valeur | Les deux arguments sont convertis en chaînes à l'aide des règles de conversion standard. Renvoie la valeur true si la première chaîne commence par la deuxième chaîne. Si l'un des arguments est Null ou Undefined, le résultat a la valeur Undefined. |
## tan(Decimal)
Renvoie la tangente d'un nombre en radians. Les valeurs `Decimal` sont arrondis pour une meilleure prévision avant l'application de la fonction. Prise en charge par SQL 2015-10-08 et versions ultérieures.
Exemple : `tan(3)` = -0.1425465430742778
****
| Type d’argument | Résultat |
| --- | --- |
| Int | Decimal (avec double précision), la tangente de l'argument. |
| Decimal | Decimal (avec double précision), la tangente de l'argument. |
| Boolean | Undefined. |
| String | Decimal (avec double précision), la tangente de l'argument. Si la chaîne ne peut pas être convertie en une valeur Decimal, le résultat est Undefined. |
| Tableau | Undefined. |
| Objet | Undefined. |
| Null | Undefined. |
| Non défini | Undefined. |
## tanh(Decimal)
Renvoie la tangente hyperbolique d'un nombre en radians. Les valeurs `Decimal` sont arrondis pour une meilleure prévision avant l'application de la fonction. Prise en charge par SQL 2015-10-08 et versions ultérieures.
Exemple : `tanh(2.3)` = 0,9800963962661914
****
| Type d’argument | Résultat |
| --- | --- |
| Int | Decimal (avec double précision), la tangente hyperbolique de l'argument. |
| Decimal | Decimal (avec double précision), la tangente hyperbolique de l'argument. |
| Boolean | Undefined. |
| String | Decimal (avec double précision), la tangente hyperbolique de l'argument. Si la chaîne ne peut pas être convertie en une valeur Decimal, le résultat est Undefined. |
| Tableau | Undefined. |
| Objet | Undefined. |
| Null | Undefined. |
| Non défini | Undefined. |
## time\$1to\$1epoch (Chaîne, Chaîne)
Utilisez cette fonction `time_to_epoch` pour convertir une chaîne d’horodatage en un nombre de millisecondes en temps d’époque Unix. Pris en charge par SQL 2016-03-23 et versions ultérieures. Pour convertir des millisecondes en une chaîne d’horodatage formatée, veuillez consulter [parse\$1time(String, Long[, String])](#iot-sql-function-parse-time).
La fonction `time_to_epoch` attend les arguments suivants :
timestamp
(Chaîne) Chaîne d’horodatage à convertir en millisecondes depuis l’ère Unix. Si la chaîne d’horodatage ne spécifie pas de fuseau horaire, la fonction utilise le fuseau horaire UTC.
pattern
(Chaîne) Un date/time modèle qui suit les [formats JDK11 temporels](http://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/time/format/DateTimeFormatter.html).
Exemples :
`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()
Renvoie l'horodatage actuel en millisecondes à partir de 00:00:00 Temps universel coordonné (UTC), jeudi 1er janvier 1970, tel qu'observé par le moteur de règles. AWS IoT Prise en charge par SQL 2015-10-08 et versions ultérieures.
Exemple: `timestamp()` = `1481825251155`
## topic(Decimal)
Il renvoie la rubrique vers laquelle le message qui a déclenché la règle a été envoyé. Si aucun paramètre n'est indiqué, la rubrique entière est renvoyée. Le paramètre `Decimal` est utilisé pour spécifier un segment de rubrique spécifique, avec le chiffre 1 désignant le premier segment. Pour la rubrique `foo/bar/baz`, topic(1) renvoie `foo`, topic(2) renvoie `bar`, et ainsi de suite. Prise en charge par SQL 2015-10-08 et versions ultérieures.
Exemples :
`topic()` = "things/myThings/thingOne"
`topic(1)` = "things"
Lorsque [Basic Ingest](iot-basic-ingest.md) est utilisé, le préfixe initial de la rubrique (`$aws/rules/rule-name`) n'est pas disponible pour la fonction topic(). Prenons l'exemple de la rubrique suivante :
`$aws/rules/BuildingManager/Buildings/Building5/Floor2/Room201/Lights`
`topic()` = "Buildings/Building5/Floor2/Room201/Lights"
`topic(3)` = "Floor2"
## traceid()
Renvoie l'ID de suivi (UUID) du message MQTT ou une valeur `Undefined` si le message n'a pas été pas envoyé via MQTT. Prise en charge par SQL 2015-10-08 et versions ultérieures.
Exemple :
`traceid() ` = "12345678-1234-1234-1234-123456789012"
## transformation (chaîne, objet, tableau)
Renvoie un tableau d’objets contenant le résultat de la transformation spécifiée du paramètre `Object` sur le paramètre `Array`.
Pris en charge par SQL 2016-03-23 et versions ultérieures.
String
Le mode de transformation à utiliser. Reportez-vous au tableau suivant pour connaître les modes de transformation pris en charge et la manière dont ils créent le `Result` à partir des paramètres `Object` et `Array`.
Objet
Un objet qui contient les attributs à appliquer à chaque élément du `Array`.
Tableau
Tableau d’objets auxquels les attributs de `Object` sont appliqués.
Chaque objet de ce tableau correspond à un objet dans la réponse de la fonction. Chaque objet de la réponse de la fonction contient les attributs présents dans l’objet d’origine et les attributs fournis par `Object` tels que déterminés par le mode de transformation spécifié dans `String`.
| `String` paramètre | `Object` paramètre | `Array` paramètre | Résultat |
| --- | --- | --- | --- |
| `enrichArray` | Objet | Tableau d’objets | Tableau d’objets dans lequel chaque objet contient les attributs d’un élément du paramètre `Array` et les attributs du paramètre `Object`. |
| Toute autre valeur | N'importe quelle valeur | N'importe quelle valeur | Non défini |
**Note**
Le tableau renvoyé par cette fonction est limité à 128 KiB.
### Exemple 1 de fonction de transformation
Cet exemple montre comment la fonction **transform()** produit un tableau unique d’objets à partir d’un objet de données et d’un tableau.
Dans cet exemple, le message suivant est publié dans la rubrique MQTT `A/B`.
```
{
"attributes": {
"data1": 1,
"data2": 2
},
"values": [
{
"a": 3
},
{
"b": 4
},
{
"c": 5
}
]
}
```
Cette instruction SQL pour une action de règle de rubrique utilise la fonction **transform()** avec une valeur `String` de `enrichArray`. Dans cet exemple, `Object` est la propriété `attributes` de la charge utile du message et `Array` est le tableau `values`, qui contient trois objets.
```
select value transform("enrichArray", attributes, values) from 'A/B'
```
À la réception de la charge utile du message, l’instruction SQL donne la réponse suivante.
```
[
{
"a": 3,
"data1": 1,
"data2": 2
},
{
"b": 4,
"data1": 1,
"data2": 2
},
{
"c": 5,
"data1": 1,
"data2": 2
}
]
```
### Exemple 2 de fonction de transformation
Cet exemple montre comment la fonction **transform()** peut utiliser des valeurs littérales pour inclure et renommer des attributs individuels à partir de la charge utile du message.
Dans cet exemple, le message suivant est publié dans la rubrique MQTT `A/B`. Il s’agit du même message que celui utilisé dans [Exemple 1 de fonction de transformation](#iot-func-transform-example1).
```
{
"attributes": {
"data1": 1,
"data2": 2
},
"values": [
{
"a": 3
},
{
"b": 4
},
{
"c": 5
}
]
}
```
Cette instruction SQL pour une action de règle de rubrique utilise la fonction **transform()** avec une valeur `String` de `enrichArray`. Le `Object` dans la fonction **transform()** possède un seul attribut nommé `key` avec la valeur de `attributes.data1` dans la charge utile du message et `Array` est le tableau `values` qui contient les trois mêmes objets que ceux utilisés dans l’exemple précédent.
```
select value transform("enrichArray", {"key": attributes.data1}, values) from 'A/B'
```
À la réception de la charge utile du message, cette instruction SQL donne la réponse suivante. Notez comment la propriété `data1` est nommée `key` dans la réponse.
```
[
{
"a": 3,
"key": 1
},
{
"b": 4,
"key": 1
},
{
"c": 5,
"key": 1
}
]
```
### Exemple 3 de fonction de transformation
Cet exemple montre comment la fonction **transform()** peut être utilisée dans des clauses SELECT imbriquées pour sélectionner plusieurs attributs et créer de nouveaux objets pour un traitement ultérieur.
Dans cet exemple, le message suivant est publié dans la rubrique MQTT `A/B`.
```
{
"data1": "example",
"data2": {
"a": "first attribute",
"b": "second attribute",
"c": [
{
"x": {
"someInt": 5,
"someString": "hello"
},
"y": true
},
{
"x": {
"someInt": 10,
"someString": "world"
},
"y": false
}
]
}
}
```
Le `Object` pour cette fonction de transformation est l’objet renvoyé par l’instruction SELECT, qui contient les éléments `a` et `b` de l’objet `data2` du message. Le paramètre `Array` comprend les deux objets du tableau `data2.c` figurant dans le message d’origine.
```
select value transform('enrichArray', (select a, b from data2), (select value c from data2)) from 'A/B'
```
Avec le message précédent, l’instruction SQL donne la réponse suivante.
```
[
{
"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"
}
]
```
Le tableau renvoyé dans cette réponse peut être utilisé avec des actions de règles de rubrique qui prennent en charge `batchMode`.
## trim(String)
Supprime tous les espaces de début et de fin de la valeur `String` fournie. Prise en charge par SQL 2015-10-08 et versions ultérieures.
Exemple :
`Trim(" hi ") ` = "bonjour"
****
| Type d’argument | Résultat |
| --- | --- |
| Int | La représentation String de Int avec tous les espaces de début et de fin supprimés. |
| Decimal | La représentation String de Decimal avec tous les espaces de début et de fin supprimés. |
| Boolean | La représentation String de la valeur Boolean (« vrai » ou « faux ») avec tous les espaces de début et de fin supprimés. |
| String | L'argument String avec tous les espaces de début et de fin supprimés. |
| Tableau | La représentation String de la valeur Array à l'aide des règles de conversion standard. |
| Objet | La représentation String de l'objet à l'aide des règles de conversion standard. |
| Null | Undefined. |
| Non défini | Undefined. |
## trunc(Decimal, Int)
Tronque le premier argument du nombre de `Decimal`, spécifié par le deuxième argument. Si le deuxième argument est inférieur à zéro, il est défini sur zéro. Si le deuxième argument est supérieur à 34, il est défini sur 34. Les zéros de fin sont supprimés du résultat. Prise en charge par SQL 2015-10-08 et versions ultérieures.
Exemples :
`trunc(2.3, 0)` = 2.
`trunc(2.3123, 2)` = 2.31.
`trunc(2.888, 2)` = 2.88.
`trunc(2.00, 5)` = 2.
****
| Type d'argument 1 | Type d'argument 2 | Résultat |
| --- | --- | --- |
| Int | Int | La valeur source. |
| Int/Decimal | Int/Decimal | Le premier argument est tronqué jusqu'à la longueur décrite par le deuxième argument. Le deuxième argument, s'il ne s'agit pas d'un Int, est arrondi à la valeur Int inférieure la plus proche. |
| Int/Decimal/String | Int/Decimal | Le premier argument est tronqué jusqu'à la longueur décrite par le deuxième argument. Le deuxième argument, s'il ne s'agit pas d'un Int, est arrondi à la valeur Int inférieure la plus proche. Une valeur String est convertie en une valeur Decimal. Si la chaîne ne peut être pas convertie, le résultat est Undefined. |
| Autre valeur | | Undefined. |
## upper(String)
Renvoie la version en majuscules de la valeur `String` donnée. Les arguments non-`String` sont convertis en valeurs `String` à l'aide des règles de conversion standard. Prise en charge par SQL 2015-10-08 et versions ultérieures.
Exemples :
`upper("hello")` = "BONJOUR"
`upper(["hello"])` = "[\$1"BONJOUR\$1"]"
# Littéraux
Vous pouvez spécifier directement des objets littéraux dans les clauses SELECT et WHERE de votre règle SQL, qui permet de transmettre des informations.
**Note**
Les littéraux sont disponibles uniquement lors de l'utilisation de SQL 2016-03-23 ou versions ultérieures.
Une syntaxe d'objet JSON est utilisée (paires clé-valeur, séparées par des virgules, où les clés sont des chaînes, et les valeurs des valeurs JSON, entourées d'accolades \$1\$1). Par exemple :
Charge utile entrante publiée dans une rubrique `topic/subtopic` : `{"lat_long": [47.606,-122.332]}`
Instruction SQL : `SELECT {'latitude': get(lat_long, 0),'longitude':get(lat_long, 1)} as lat_long FROM 'topic/subtopic'`
La charge utile sortante résultante serait : `{"lat_long":{"latitude":47.606,"longitude":-122.332}}`.
Vous pouvez également spécifier des tableaux dans des clauses SELECT et WHERE de votre règle SQL, qui vous permet de regrouper des informations. Une syntaxe JSON est utilisée (éléments séparés par des virgules entre crochets [] pour créer un littéral de tableau). Par exemple :
Charge utile entrante publiée dans une rubrique `topic/subtopic` : `{"lat": 47.696, "long": -122.332}`
Instruction SQL : `SELECT [lat,long] as lat_long FROM 'topic/subtopic'`
La charge utile de sortie serait : `{"lat_long": [47.606,-122.332]}`.
# Instructions Case
Les instructions case peuvent être utilisées pour l’exécution de branche, comme une instruction switch.
Syntaxe :
```
CASE v WHEN t[1] THEN r[1]
WHEN t[2] THEN r[2] ...
WHEN t[n] THEN r[n]
ELSE r[e] END
```
L’expression *`v`* est évaluée et fait l’objet d’une comparaison d’égalité avec la valeur *`t[i]`* de chaque clause `WHEN`. Si une correspondance est trouvée, l’expression *`r[i]`* correspondante devient le résultat de l’instruction `CASE`. Les clauses `WHEN` sont évaluées de telle sorte que s’il existe plusieurs clauses correspondantes, le résultat de la première clause correspondante devient le résultat de l’instruction `CASE`. S’il n’y a aucune correspondance, le résultat *`r[e]`* de la clause `ELSE` est le résultat. S’il n’y a ni correspondance ni clause `ELSE`, le résultat est `Undefined`.
Les instructions `CASE` requièrent au moins une clause `WHEN`. Une clause `ELSE` est facultative.
Par exemple :
Charge utile entrante publiée dans une rubrique `topic/subtopic` :
```
{
"color":"yellow"
}
```
Instruction 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'
```
La charge utile de sortie serait :
```
{
"instructions":"caution"
}
```
**Note**
Si *`v`* est `Undefined`, le résultat de l’instruction case est `Undefined`.
# Extensions JSON
Vous pouvez utiliser les extensions suivantes de la syntaxe SQL ANSI pour faciliter l’utilisation d’objets JSON imbriqués.
« . » Opérateur
Cet opérateur accède aux membres dans les objets JSON intégrés et fonctionne de la même manière que le SQL ANSI et. JavaScript Par exemple :
```
SELECT foo.bar AS bar.baz FROM 'topic/subtopic'
```
sélectionne la valeur de la propriété `bar` dans l’objet `foo` à partir de la charge utile du message suivant envoyé à la rubrique `topic/subtopic`.
```
{
"foo": {
"bar": "RED",
"bar1": "GREEN",
"bar2": "BLUE"
}
}
```
Si le nom d’une propriété JSON inclut un trait d’union ou des caractères numériques, la notation « point » ne fonctionnera pas. Vous devez plutôt utiliser la [fonction get](iot-sql-functions.md#iot-sql-function-get) pour extraire la valeur de la propriété.
Dans cet exemple, le message suivant est envoyé dans la rubrique `iot/rules`.
```
{
"mydata": {
"item2": {
"0": {
"my-key": "myValue"
}
}
}
}
```
Normalement, la valeur de `my-key` serait identifiée comme dans cette requête.
```
SELECT * from iot/rules WHERE mydata.item2.0.my-key= "myValue"
```
Toutefois, étant donné que le nom de la propriété `my-key` contient un trait d’union et `item2` un caractère numérique, la [fonction get](iot-sql-functions.md#iot-sql-function-get) doit être utilisée comme le montre la requête suivante.
```
SELECT * from 'iot/rules' WHERE get(get(get(mydata,"item2"),"0"),"my-key") = "myValue"
```
`*` Opérateur
Cela fonctionne de la même manière que le caractère générique `*` dans SQL ANSI. Il est utilisé dans la clause SELECT uniquement et crée un nouvel objet JSON contenant les données du message. Si la charge utile du message n'est pas au format JSON, `*` renvoie la charge utile du message entier sous la forme d'octets bruts. Par exemple :
```
SELECT * FROM 'topic/subtopic'
```
**Appliquer une fonction à une valeur d'attribut**
Voici un exemple de charge utile JSON qui peut être publiée par un appareil :
```
{
"deviceid" : "iot123",
"temp" : 54.98,
"humidity" : 32.43,
"coords" : {
"latitude" : 47.615694,
"longitude" : -122.3359976
}
}
```
L'exemple suivant applique une fonction à une valeur d'attribut dans une charge utile JSON :
```
SELECT temp, md5(deviceid) AS hashed_id FROM topic/#
```
Le résultat de cette requête est l'objet JSON suivant :
```
{
"temp": 54.98,
"hashed_id": "e37f81fb397e595c4aeb5645b8cbbbd1"
}
```
# Modèles de substitution
Vous pouvez utiliser un modèle de substitution pour augmenter les données JSON renvoyées lorsqu'une règle est déclenchée et AWS IoT exécute une action. La syntaxe d'un modèle de substitution est `${` *expression*`}`, où l'*expression* peut être n'importe quelle expression prise AWS IoT en charge par les clauses SELECT, WHERE et[AWS IoT actions liées aux règles](iot-rule-actions.md). Cette expression peut être connectée à un champ d'action d'une règle, ce qui vous permet de configurer dynamiquement une action. En effet, cette fonctionnalité remplace un élément d'information dans une action. Cela inclut les fonctions, les opérateurs et les informations présents dans la charge utile du message d'origine.
**Important**
Puisqu’une expression dans un modèle de substitution est évaluée séparément de l’instruction « SELECT... », vous ne pouvez pas référencer un alias créé à l’aide de la clause AS. Vous pouvez référencer uniquement les informations présentes dans la charge utile d’origine, [fonctions](iot-sql-functions.md) et [opérateurs](iot-sql-operators.md).
Pour plus d'informations concernant les expressions prises en charge, consultez la page [AWS IoT Référence SQL](iot-sql-reference.md).
Les actions de règle suivantes prennent en charge les modèles de substitution. Chaque action prend en charge différents champs qui peuvent être substitués.
+ [Apache Kafka](apache-kafka-rule-action.md)
+ [CloudWatch alarmes](cloudwatch-alarms-rule-action.md)
+ [CloudWatch Journaux](cloudwatch-logs-rule-action.md)
+ [CloudWatch métriques](cloudwatch-metrics-rule-action.md)
+ [DynamoDB](dynamodb-rule-action.md)
+ [Dynamo 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)
+ [Location](location-rule-action.md)
+ [OpenSearch](opensearch-rule-action.md)
+ [Republier](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)
Les modèles de substitution apparaissent dans les paramètres d'action au sein d'une règle :
```
{
"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"
}
}]
}
```
Si cette règle est déclenchée par le code JSON suivant publié dans `my/iot/topic` :
```
{
"deviceid": "iot123",
"temp": 54.98,
"humidity": 32.43,
"coords": {
"latitude": 47.615694,
"longitude": -122.3359976
}
}
```
Cette règle publie ensuite le code JSON suivant sur`my/iot/topic/republish`, qui AWS IoT remplace : `${topic()}/republish`
```
{
"deviceid": "iot123",
"temp": 54.98,
"humidity": 32.43,
"coords": {
"latitude": 47.615694,
"longitude": -122.3359976
},
"timestamp": 1579637878451
}
```
# Requêtes d'objets imbriqués
Vous pouvez utiliser des clauses SELECT imbriquées pour interroger les attributs dans les tableaux et les objets JSON internes. Pris en charge par SQL 2016-03-23 et versions ultérieures.
Examinez le message MQTT suivant :
```
{
"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**
Vous pouvez convertir des valeurs en un nouveau tableau avec la règle suivante.
```
SELECT (SELECT VALUE n FROM e) as sensors FROM 'my/topic'
```
La règle génère le résultat suivant.
```
{
"sensors": [
"temperature",
"light",
"acidity"
]
}
```
**Example**
En utilisant le même message MQTT, vous pouvez également interroger une valeur spécifique dans un objet imbriqué avec la règle suivante.
```
SELECT (SELECT v FROM e WHERE n = 'temperature') as temperature FROM 'my/topic'
```
La règle génère le résultat suivant.
```
{
"temperature": [
{
"v": 22.5
}
]
}
```
**Example**
Vous pouvez également aplatir la sortie avec une règle plus compliquée.
```
SELECT get((SELECT v FROM e WHERE n = 'temperature'), 0).v as temperature FROM 'topic'
```
La règle génère le résultat suivant.
```
{
"temperature": 22.5
}
```
# Utilisation des charges utiles binaires
Pour traiter la charge utile de votre message comme des données binaires brutes (plutôt que comme un objet JSON), vous pouvez utiliser l’opérateur \$1 pour y faire référence dans une clause SELECT.
**Topics**
+ [Exemples de charge utile binaire](#binary-payloads-examples)
+ [Décodage des charges utiles des messages protobuf](#binary-payloads-protobuf)
## Exemples de charge utile binaire
Lorsque vous utilisez \$1 pour désigner la charge utile du message sous forme de données binaires brutes, vous pouvez ajouter des données à la règle. Si vous avez une charge utile vide ou une charge utile JSON, des données peuvent être ajoutées à la charge utile résultante à l’aide de la règle. Vous trouverez ci-dessous des exemples de clauses `SELECT` prises en charge.
+ Vous pouvez utiliser les clauses `SELECT` suivantes avec uniquement un \$1 pour les charges utiles binaires.
+
```
SELECT * FROM 'topic/subtopic'
```
+
```
SELECT * FROM 'topic/subtopic' WHERE timestamp() % 12 = 0
```
+ Vous pouvez également ajouter des données et utiliser les clauses `SELECT` suivantes.
+
```
SELECT *, principal() as principal, timestamp() as time FROM 'topic/subtopic'
```
+
```
SELECT encode(*, 'base64') AS data, timestamp() AS ts FROM 'topic/subtopic'
```
+ Vous pouvez également utiliser ces clauses `SELECT` avec des charges utiles binaires.
+ Ce qui suit fait référence à `device_type` dans la clause WHERE.
```
SELECT * FROM 'topic/subtopic' WHERE device_type = 'thermostat'
```
+ Les éléments suivants sont pris en charge.
```
{
"sql": "SELECT * FROM 'topic/subtopic'",
"actions": [
{
"republish": {
"topic": "device/${device_id}"
}
}
]
}
```
Les actions de règles suivantes ne prennent pas en charge les charges utiles binaires. Vous devez donc les décoder.
+ Certaines actions de règles ne prennent pas en charge les données utiles binaires, comme les [actions Lambda](https://docs.aws.amazon.com/iot/latest/developerguide/iot-rule-actions.html#lambda-rule), et vous devez donc décoder les données utiles binaires. L’action de la règle Lambda peut recevoir des données binaires si elles sont codées en base64 et placées dans une charge utile JSON. Pour cela, apportez les modifications suivantes à la règle :
```
SELECT encode(*, 'base64') AS data FROM 'my_topic'
```
+ L’instruction SQL ne prend pas en charge les chaînes en entrée. Pour convertir une chaîne en JSON, vous pouvez exécuter la commande suivante.
```
SELECT decode(encode(*, 'base64'), 'base64') AS payload FROM 'topic'
```
## Décodage des charges utiles des messages protobuf
[Protocol Buffers (protobuf)](https://developers.google.com/protocol-buffers) est un format de données open source utilisé pour sérialiser des données structurées sous une forme binaire compacte. Il est utilisé pour transmettre des données sur des réseaux ou pour les stocker dans des fichiers. Protobuf vous permet d'envoyer des données sous forme de petits paquets et à un rythme plus rapide que les autres formats de messagerie. AWS IoT Core Les règles prennent en charge protobuf en fournissant la fonction SQL [decode (value, decodingScheme),](iot-sql-functions.md#iot-sql-decode-base64) qui permet de décoder les charges utiles des messages codés par protobuf au format JSON et de les acheminer vers les services en aval. Cette section détaille le step-by-step processus de configuration du décodage protobuf dans Rules. AWS IoT Core
**Topics**
+ [Conditions préalables](#binary-payloads-protobuf-prerequisites)
+ [Création de fichiers descripteurs](#binary-payloads-protobuf-descriptor-steps)
+ [Charger les fichiers descripteurs dans un compartiment S3](#binary-payloads-protobuf-s3-steps)
+ [Configurer le décodage protobuf dans Règles](#binary-payloads-protobuf-steps)
+ [Limitations](#binary-payloads-protobuf-limitations)
+ [Bonnes pratiques](#binary-payloads-protobuf-bestpractices)
### Conditions préalables
+ Compréhension de base de [Protocol Buffers (protobuf)](https://developers.google.com/protocol-buffers)
+ Les [`.proto`fichiers](https://developers.google.com/protocol-buffers/docs/proto3) qui définissent les types de messages et les dépendances associées
+ Installation de [Protobuf Compiler (protoc)](https://github.com/protocolbuffers/protobuf/releases) sur votre système
### Création de fichiers descripteurs
Si vous disposez déjà de fichiers descripteurs, vous pouvez ignorer cette étape. Un fichier descripteur (`.desc`) est une version compilée d’un fichier `.proto`, qui est un fichier texte qui définit les structures de données et les types de messages à utiliser dans une sérialisation protobuf. Pour générer un fichier descripteur, vous devez définir un fichier `.proto` et utiliser le compilateur [protoc](https://github.com/protocolbuffers/protobuf/releases) pour le compiler.
1. Créez des fichiers `.proto` qui définissent les types de messages. Un fichier `.proto` manifeste peut ressembler à l’exemple suivant :
```
syntax = "proto3";
message Person {
optional string name = 1;
optional int32 id = 2;
optional string email = 3;
}
```
Dans cet exemple de fichier `.proto`, vous utilisez la syntaxe proto3 et définissez le type de message `Person`. La définition du message `Person` spécifie trois champs (nom, identifiant et e-mail). Pour plus d’informations sur les formats de message de fichier `.proto`, veuillez consulter le [Guide des langues (proto3).](https://developers.google.com/protocol-buffers/docs/proto3)
1. Utilisez le compilateur [protoc](https://github.com/protocolbuffers/protobuf/releases) pour compiler les fichiers`.proto` et générer un fichier de descripteurs. La création d’un fichier (`.desc`) descripteur est illustrée ci-dessous :
```
protoc --descriptor_set_out=.desc \
--proto_path= \
--include_imports \
.proto
```
Cet exemple de commande génère un fichier descripteur que `.desc` AWS IoT Core Rules peut utiliser pour décoder les charges utiles protobuf conformes à la structure de données définie dans. `.proto`
+ `--descriptor_set_out`
Spécifie le nom du fichier (`.desc`) descripteur qui doit être généré.
+ `--proto_path`
Spécifie l’emplacement de tous les fichiers `.proto` importés référencés par le fichier en cours de compilation. Vous pouvez spécifier l’indicateur plusieurs fois si vous avez plusieurs fichiers `.proto` importés avec des emplacements différents.
+ `--include_imports`
Spécifie que tous les fichiers `.proto` importés doivent également être compilés et inclus dans le fichier `.desc` descripteur.
+ `.proto`
Spécifie le nom du fichier `.proto` que vous souhaitez compiler.
Pour de plus amples informations sur la référence protoc, veuillez consulter [Référence de l’API](https://developers.google.com/protocol-buffers/docs/reference/overview).
### Charger les fichiers descripteurs dans un compartiment S3
Après avoir créé vos fichiers descripteurs`.desc`, chargez-les dans un compartiment Amazon S3 `.desc` à l'aide de l' AWS API, du AWS SDK ou du. AWS Management Console
**Considérations Importantes**
+ Assurez-vous de télécharger les fichiers descripteurs dans un compartiment Amazon S3 situé dans le même compartiment que celui Compte AWS dans Région AWS lequel vous souhaitez configurer vos règles.
+ Assurez-vous d'autoriser l' AWS IoT Core accès pour lire le contenu `FileDescriptorSet` de S3. Si le chiffrement côté serveur (SSE) est désactivé dans votre compartiment S3 ou s’il est chiffré à l’aide de clés gérées par Amazon S3 (SSE-S3), aucune configuration de stratégie supplémentaire n’est requise. Cela peut être accompli à l’aide de l’exemple de politique de compartiment :
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "Statement1",
"Effect": "Allow",
"Principal": {
"Service": "iot.amazonaws.com"
},
"Action": "s3:Get*",
"Resource": "arn:aws:s3:::/.desc"
}
]
}
```
+ Si votre compartiment S3 est chiffré à l'aide d'une AWS Key Management Service clé (SSE-KMS), assurez-vous d' AWS IoT Core autoriser l'utilisation de la clé lors de l'accès à votre compartiment S3. Pour ce faire, vous pouvez ajouter cette déclaration à votre stratégie de clé :
```
{
"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"
}
```
### Configurer le décodage protobuf dans Règles
Après avoir chargé les fichiers descripteurs dans votre compartiment Amazon S3, configurez une [Règle](https://docs.aws.amazon.com//iot/latest/developerguide/iot-create-rule.html) capable de décoder le format de charge utile de votre message protobuf à l’aide de la fonction SQL [decode (value, decodingScheme](iot-sql-functions.md#iot-sql-decode-base64)). Une signature de fonction détaillée et un exemple se trouvent dans la fonction SQL [decode(value, decodingScheme)](iot-sql-functions.md#iot-sql-decode-base64) de la *AWS IoT référence SQL.*
Voici un exemple d’expression SQL utilisant la fonction [decode (value, decodingScheme](iot-sql-functions.md#iot-sql-decode-base64)) :
```
SELECT VALUE decode(*, 'proto', '', '.desc', '', '') FROM ''
```
Dans cet exemple d’expression :
+ Vous utilisez la fonction SQL [decode (value, decodingScheme)](iot-sql-functions.md#iot-sql-decode-base64) pour décoder la charge utile du message binaire référencée par `*`. Il peut s’agir d’une charge utile binaire codée en protobuf ou d’une chaîne JSON représentant une charge utile protobuf codée en base64.
+ La charge utile du message fournie est codée à l’aide du type de message `Person` défini dans `PROTO_FILENAME.proto`.
+ Le compartiment Amazon S3 nommé `BUCKET NAME` contient le `FILENAME.desc` généré à partir de `PROTO_FILENAME.proto`.
Une fois la configuration terminée, publiez un message AWS IoT Core sur le sujet auquel la règle est abonnée.
### Limitations
AWS IoT Core Les règles prennent en charge protobuf avec les limitations suivantes :
+ Le décodage des charges utiles des messages protobuf dans les [modèles de substitution](https://docs.aws.amazon.com//iot/latest/developerguide/iot-substitution-templates.html) n’est pas pris en charge.
+ Lorsque vous décodez les charges utiles des messages protobuf, vous pouvez utiliser la [fonction SQL](iot-sql-functions.md#iot-sql-decode-base64) de décodage dans une seule expression SQL jusqu’à deux fois.
+ La taille maximale de la charge utile entrante est de 128 KiB (1 KiB = 1024 octets), la taille maximale de la charge utile sortante est de 128 KiB et la taille maximale d’un objet `FileDescriptorSet` stocké dans un compartiment Amazon S3 est de 32 KiB.
+ Les compartiments Amazon S3 chiffrés avec le chiffrement SSE-C ne sont pas pris en charge.
### Bonnes pratiques
Voici quelques bonnes pratiques et des conseils de dépannage.
+ Sauvegardez vos fichiers proto dans le compartiment Amazon S3.
Il est recommandé de sauvegarder vos fichiers proto en cas de problème. Par exemple, si vous modifiez incorrectement les fichiers proto sans sauvegarde lors de l’exécution de protoc, cela peut entraîner des problèmes dans votre stack de production. Il existe plusieurs méthodes pour sauvegarder vos fichiers dans un compartiment Amazon S3. Par exemple, vous pouvez [utiliser la gestion des versions dans les compartiments S3](https://docs.aws.amazon.com//AmazonS3/latest/userguide/Versioning.html). Pour plus d’informations sur la sauvegarde de fichiers dans des compartiments Amazon S3, veuillez consulter le *[manuel du développeur Amazon S3](https://docs.aws.amazon.com//aws-backup/latest/devguide/recovery-points.html)*.
+ Configurez la AWS IoT journalisation pour afficher les entrées du journal.
Il est recommandé de configurer la AWS IoT journalisation de manière à pouvoir consulter AWS IoT les journaux de votre compte CloudWatch. Lorsque la requête SQL d'une règle appelle une fonction externe, AWS IoT Core Rules génère une entrée de journal avec un `eventType` de`FunctionExecution`, qui contient le champ motif qui vous aidera à résoudre les problèmes d'échec. Les erreurs possibles incluent un objet Amazon S3 introuvable ou un descripteur de fichier protobuf non valide. Pour plus d’informations sur la façon de configurer la journalisation AWS IoT et de consulter les entrées du journal, veuillez consulter [Configurer la AWS IoT journalisation](https://docs.aws.amazon.com//iot/latest/developerguide/configure-logging.html) et [les entrées du journal du moteur de règles](https://docs.aws.amazon.com//iot/latest/developerguide/cwl-format.html#log-rules-fn-exec).
+ Effectuez la mise à jour de `FileDescriptorSet` à l’aide d’une nouvelle clé d’objet et mettez à jour la clé d’objet dans votre règle.
Vous pouvez effectuer une mise à jour de `FileDescriptorSet` en chargeant un fichier descripteur mis à jour dans votre compartiment Amazon S3. Vos mises à jour de `FileDescriptorSet` peuvent prendre jusqu’à 15 minutes pour être prises en compte. Pour éviter ce retard, il est recommandé de télécharger votre `FileDescriptorSet` mis à jour à l’aide d’une nouvelle clé d’objet et de mettre à jour la clé d’objet dans votre Règle.
# Versions de SQL
Le moteur de AWS IoT règles utilise une syntaxe de type SQL pour sélectionner les données des messages MQTT. Les instructions SQL sont interprétées en fonction d'une version SQL spécifiée avec la propriété `awsIotSqlVersion` dans un document JSON qui décrit la règle. Pour plus d'informations sur la structure des documents de règle JSON, consultez [Création d'une règle](iot-create-rule.md). La `awsIotSqlVersion` propriété vous permet de spécifier la version du moteur de règles AWS IoT SQL que vous souhaitez utiliser. Lorsqu'une nouvelle version est déployée, vous pouvez continuer à utiliser une version antérieure ou modifier votre règle pour utiliser la nouvelle version. Vos règles actuelles continuent d'utiliser la version avec laquelle elles ont été créées.
L'exemple de code JSON suivant montre comment spécifier la version SQL à l'aide la propriété `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 prend actuellement en charge les versions SQL suivantes :
+ `2016-03-23` – La version SQL construite le 23/03/2016 (recommandée).
+ `2015-10-08` – La version de SQL d’origine créée le 08-10-2015.
+ `beta` – La version bêta de SQM la plus récente. Cette version pourrait introduire des modifications radicales dans vos règles.
## Nouveautés de la version 2016-03-23 du moteur de règles SQL
+ Correctifs pour sélectionner les objets JSON imbriqués.
+ Correctifs pour les requêtes de tableaux.
+ Prise en charge des requêtes inter-objet. Pour de plus amples informations, veuillez consulter [Requêtes d'objets imbriqués](iot-sql-nested-queries.md).
+ Prise en charge de la génération en sortie d'un tableau comme un objet de niveau supérieur.
+ Ajout de la fonction `encode(value, encodingScheme)`, qui peut être appliquée sur les données de format JSON et non-JSON. Pour plus d'informations, consultez la [fonction d'encodage](iot-sql-functions.md#iot-sql-encode-payload).
### Générer un `Array` en sortie comme un objet de niveau supérieur
Cette fonction permet à une règle de retourner un tableau comme un objet de niveau supérieur. Par exemple, avec le message MQTT suivant :
```
{
"a": {"b":"c"},
"arr":[1,2,3,4]
}
```
Et la règle suivante :
```
SELECT VALUE arr FROM 'topic'
```
La règle génère le résultat suivant.
```
[1,2,3,4]
```