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.
# Ingérez des données avec AWS IoT SiteWise APIs
Utilisez-le AWS IoT SiteWise APIs pour envoyer des données industrielles horodatées vers les attributs et les propriétés de mesure de vos actifs. APIs Accepte les structures contenant de la charge utile timestamp-quality-value (TQV).
# BatchPutAssetPropertyValue API
Utilisez l'opération [BatchPutAssetPropertyValue](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_BatchPutAssetPropertyValue.html) pour charger vos données. Grâce à cette opération, vous pouvez télécharger plusieurs entrées de données à la fois pour collecter des données provenant de plusieurs appareils et les envoyer en une seule demande.
**Important**
L'[BatchPutAssetPropertyValue](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_BatchPutAssetPropertyValue.html)opération est soumise aux quotas suivants :
Jusqu'à 10 [entrées](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_BatchPutAssetPropertyValue.html#API_BatchPutAssetPropertyValue_RequestSyntax) par demande.
Jusqu'à 10 [valeurs de propriété](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_PutAssetPropertyValueEntry.html#iotsitewise-Type-PutAssetPropertyValueEntry-propertyValues) (points de données TQV) par entrée.
AWS IoT SiteWise rejette toutes les données dont l'horodatage date de plus de 7 jours dans le passé ou de plus de 10 minutes dans le futur.
Pour de plus amples informations sur ces quotas, veuillez consulter [BatchPutAssetPropertyValue](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_BatchPutAssetPropertyValue.html) dans la *Référence de l'API AWS IoT SiteWise *.
Pour identifier une propriété d'actif, spécifiez l'une des options suivantes :
+ La `assetId` fin `propertyId` de la propriété de l'actif à laquelle les données sont envoyées.
+ Le`propertyAlias`, qui est un alias de flux de données (par exemple,`/company/windfarm/3/turbine/7/temperature`). Pour utiliser cette option, vous devez d'abord définir l'alias de votre propriété de ressource. Pour définir des alias de propriété, consultez[Gérez les flux de données pour AWS IoT SiteWise](manage-data-streams.md).
L'exemple suivant montre comment envoyer des lectures de température et de rotations par minute (RPM) d'une éolienne à partir d'une charge utile stockée dans un fichier JSON.
```
aws iotsitewise batch-put-asset-property-value --cli-input-json file://batch-put-payload.json
```
L'exemple de charge utile `batch-put-payload.json` contient le contenu suivant.
```
{
"enablePartialEntryProcessing": true,
"entries": [
{
"entryId": "unique entry ID",
"propertyAlias": "/company/windfarm/3/turbine/7/temperature",
"propertyValues": [
{
"value": {
"integerValue": 38
},
"timestamp": {
"timeInSeconds": 1575691200
}
}
]
},
{
"entryId": "unique entry ID",
"propertyAlias": "/company/windfarm/3/turbine/7/rpm",
"propertyValues": [
{
"value": {
"doubleValue": 15.09
},
"timestamp": {
"timeInSeconds": 1575691200
},
"quality": "GOOD"
}
]
},
{
"entryId": "unique entry ID",
"propertyAlias": "/company/windfarm/3/turbine/7/rpm",
"propertyValues": [
{
"value": {
"nullValue":{"valueType": "D"}
},
"timestamp": {
"timeInSeconds": 1575691200
},
"quality": "BAD"
}
]
}
]
}
```
La spécification « `enablePartialEntryProcessing` as » `true` permet l'ingestion de toutes les valeurs qui n'entraînent pas de défaillance. Le comportement par défaut est `false`. Si une valeur n'est pas valide, l'entrée entière échoue à être ingérée.
Chaque entrée de la charge utile contient un `entryId` que vous pouvez définir sous la forme d'une chaîne unique. Si des entrées de demande échouent, chaque erreur contiendra l'`entryId` de la demande correspondante afin que vous sachiez quelles demandes réessayer.
Chaque structure de la liste des `propertyValues` est une structure timestamp-quality-value (TQV) qui contient a `value``timestamp`, a et éventuellement a. `quality`
+ `value`— Structure contenant l'un des champs suivants, en fonction du type de propriété défini :
+ `booleanValue`
+ `doubleValue`
+ `integerValue`
+ `stringValue`
+ `nullValue`
+ `nullValue`— Une structure dont le champ suivant indique le type de la valeur de propriété avec la valeur Null et la qualité de `BAD` ou`UNCERTAIN`.
+ `valueType`— Enum de \$1"B », « D », « S », « I"\$1
+ `timestamp`— Une structure qui contient l'heure actuelle d'Unix en secondes,. `timeInSeconds` Vous pouvez également définir la `offsetInNanos` clé dans la `timestamp` structure si vous disposez de données temporellement précises. AWS IoT SiteWise rejette tous les points de données dont l'horodatage date de plus de 7 jours dans le passé ou de moins de 10 minutes dans le futur.
+ `quality`— (Facultatif) L'une des chaînes de qualité suivantes :
+ `GOOD`— (Par défaut) Les données ne sont affectées par aucun problème.
+ `BAD`— Les données sont affectées par un problème tel qu'une défaillance du capteur.
+ `UNCERTAIN`— Les données sont affectées par un problème tel que l'imprécision du capteur.
Pour plus d'informations sur la gestion de AWS IoT SiteWise la qualité des données dans les calculs, consultez la section [Qualité des données dans les expressions de formule](expression-tutorials.md#data-quality).
# CreateBulkImportJob API
Utilisez l'`CreateBulkImportJob`API pour importer de grandes quantités de données depuis Amazon S3. Vos données doivent être enregistrées au format CSV dans Amazon S3. Les fichiers de données peuvent comporter les colonnes suivantes.
**Note**
Les données antérieures au 1er janvier 1970 00:00:00 UTC ne sont pas prises en charge.
Pour identifier une propriété d'actif, spécifiez l'une des options suivantes.
La `ASSET_ID` fin `PROPERTY_ID` de la propriété de l'actif à laquelle vous envoyez des données.
Le`ALIAS`, qui est un alias de flux de données (par exemple,`/company/windfarm/3/turbine/7/temperature`). Pour utiliser cette option, vous devez d'abord définir l'alias de votre propriété de ressource. Pour découvrir comment définir des alias de propriété de ressource, consultez [Gérez les flux de données pour AWS IoT SiteWise](manage-data-streams.md).
+ `ALIAS`— L'alias qui identifie la propriété, tel que le chemin de flux de données d'un serveur OPC UA (par exemple,`/company/windfarm/3/turbine/7/temperature`). Pour de plus amples informations, veuillez consulter [Gérez les flux de données pour AWS IoT SiteWise](manage-data-streams.md).
+ `ASSET_ID`— L'ID de l'actif.
+ `PROPERTY_ID`— L'ID de la propriété de l'actif.
+ `DATA_TYPE`— Le type de données de la propriété peut être l'un des suivants.
+ `STRING`— Chaîne de 1024 octets maximum.
+ `INTEGER`— Un entier signé de 32 bits avec une plage de [-2 147 483 648, 2 147 483 647].
+ `DOUBLE`— Un nombre à virgule flottante avec une plage [-10^100, 10^100] et une double précision IEEE 754.
+ `BOOLEAN`— `true` ou`false`.
+ `TIMESTAMP_SECONDS`— L'horodatage du point de données, à l'époque Unix.
+ `TIMESTAMP_NANO_OFFSET`— Le décalage en nanosecondes converti à partir de. `TIMESTAMP_SECONDS`
+ `QUALITY`— (Facultatif) La qualité de la valeur de la propriété de l'actif. La valeur peut être l'une des suivantes.
+ `GOOD`— (Par défaut) Les données ne sont affectées par aucun problème.
+ `BAD`— Les données sont affectées par un problème tel qu'une défaillance du capteur.
+ `UNCERTAIN`— Les données sont affectées par un problème tel que l'imprécision du capteur.
Pour plus d'informations sur la gestion de AWS IoT SiteWise la qualité des données dans les calculs, consultez la section [Qualité des données dans les expressions de formule](expression-tutorials.md#data-quality).
+ `VALUE`— La valeur de la propriété de l'actif.
**Example fichier (s) de données au format .csv**
```
asset_id,property_id,DOUBLE,1635201373,0,GOOD,1.0
asset_id,property_id,DOUBLE,1635201374,0,GOOD,2.0
asset_id,property_id,DOUBLE,1635201375,0,GOOD,3.0
```
```
unmodeled_alias1,DOUBLE,1635201373,0,GOOD,1.0
unmodeled_alias1,DOUBLE,1635201374,0,GOOD,2.0
unmodeled_alias1,DOUBLE,1635201375,0,GOOD,3.0
unmodeled_alias1,DOUBLE,1635201376,0,GOOD,4.0
unmodeled_alias1,DOUBLE,1635201377,0,GOOD,5.0
unmodeled_alias1,DOUBLE,1635201378,0,GOOD,6.0
unmodeled_alias1,DOUBLE,1635201379,0,GOOD,7.0
unmodeled_alias1,DOUBLE,1635201380,0,GOOD,8.0
unmodeled_alias1,DOUBLE,1635201381,0,GOOD,9.0
unmodeled_alias1,DOUBLE,1635201382,0,GOOD,10.0
```
AWS IoT SiteWise fournit les opérations d'API suivantes pour créer une tâche d'importation en bloc et obtenir des informations sur une tâche existante.
+ [CreateBulkImportJob](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_CreateBulkImportJob.html)— Crée une nouvelle tâche d'importation en bloc.
+ [DescribeBulkImportJob](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_DescribeBulkImportJob.html)— Récupère les informations relatives à une tâche d'importation groupée.
+ [ListBulkImportJob](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_ListBulkImportJobs.html)— Récupère une liste paginée de résumés de toutes les tâches d'importation en bloc.
# Création d'une tâche d'importation AWS IoT SiteWise en bloc (AWS CLI)
Utilisez l'opération [CreateBulkImportJob](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_CreateBulkImportJob.html)d'API pour transférer des données d'Amazon S3 vers AWS IoT SiteWise. L'[CreateBulkImportJob](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_CreateBulkImportJob.html)API permet l'ingestion de gros volumes de données historiques et l'ingestion en mémoire tampon de flux de données analytiques par petits lots. Il fournit une primitive rentable pour l'ingestion de données. L'exemple suivant repose sur AWS CLI.
**Important**
Avant de créer une tâche d'importation en bloc, vous devez activer le niveau AWS IoT SiteWise chaud ou le niveau AWS IoT SiteWise froid. Pour de plus amples informations, veuillez consulter [Configurer les paramètres de stockage dans AWS IoT SiteWise](configure-storage.md).
L'[CreateBulkImportJob](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_CreateBulkImportJob.html)API prend en charge l'ingestion de données historiques AWS IoT SiteWise avec la possibilité de définir le adaptive-ingestion-flag paramètre.
Lorsqu'elle est définie sur`false`, l'API ingère les données historiques sans déclencher de calculs ni de notifications.
Lorsqu'elle est définie sur`true`, l'API ingère de nouvelles données, calcule des métriques et transforme les données afin d'optimiser les analyses et les notifications continues dans un délai de sept jours.
Exécutez la commande suivante. Remplacez *file-name* par le nom du fichier contenant la configuration de la tâche d'importation en bloc.
```
aws iotsitewise create-bulk-import-job --cli-input-json file://file-name.json
```
**Example Configuration des tâches d'importation en bloc**
Voici des exemples de paramètres de configuration :
+ Remplacez *adaptive-ingestion-flag* par `true` ou `false`.
+ Si cette valeur est définie sur`false`, la tâche d'importation en bloc ingère les données historiques dans AWS IoT SiteWise.
+ Si cette valeur est définie sur`true`, la tâche d'importation en bloc effectue les opérations suivantes :
+ Ingère de nouvelles données dans. AWS IoT SiteWise
+ Calcule les métriques et les transforme, et prend en charge les notifications pour les données dont l'horodatage est établi dans les sept jours.
+ Remplacez *delete-files-after-import-flag* par `true` pour supprimer les données du compartiment de données Amazon S3 après les avoir ingérées dans un système de stockage à AWS IoT SiteWise chaud.
+ Remplacez amzn-s3-demo-bucket par le *-for-errors* nom du compartiment Amazon S3 auquel les erreurs associées à cette tâche d'importation en masse sont envoyées.
+ Remplacez amzn-s3-demo-bucket par le *-for-errors-prefix* préfixe du compartiment Amazon S3 auquel les erreurs associées à cette tâche d'importation en masse sont envoyées.
Amazon S3 utilise le préfixe comme nom de dossier pour organiser les données dans le compartiment. Chaque objet Amazon S3 possède une clé qui constitue son identifiant unique dans le compartiment. Chaque objet d'un compartiment possède une clé et une seule. Le préfixe doit se terminer par une barre oblique (/). Pour plus d'informations, consultez la section [Organisation des objets à l'aide de préfixes](https://docs.aws.amazon.com/AmazonS3/latest/userguide/using-prefixes.html) dans le *guide de l'utilisateur d'Amazon Simple Storage Service*.
+ Remplacez amzn-s3-demo-bucket par le *-data* nom du compartiment Amazon S3 à partir duquel les données sont importées.
+ *data-bucket-key*Remplacez-la par la clé de l'objet Amazon S3 qui contient vos données. Chaque objet a une clé qui est un identifiant unique. Chaque objet a exactement une clé.
+ *data-bucket-version-id*Remplacez-le par l'ID de version pour identifier une version spécifique de l'objet Amazon S3 contenant vos données. Ce paramètre est facultatif.
+ Remplacez *column-name* par le nom de colonne spécifié dans le fichier .csv.
+ *job-name*Remplacez-le par un nom unique identifiant la tâche d'importation en bloc.
+ Remplacez *job-role-arn* par le rôle IAM qui permet AWS IoT SiteWise de lire les données Amazon S3.
Assurez-vous que votre rôle dispose des autorisations indiquées dans l'exemple suivant. Remplacez amzn-s3-demo-bucket par le *-data* nom du compartiment Amazon S3 qui contient vos données. Remplacez-le également *amzn-s3-demo-bucket-for-errors* par le nom du compartiment Amazon S3 auquel les erreurs associées à cette tâche d'importation en masse sont envoyées.
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Action": [
"s3:GetObject",
"s3:GetBucketLocation"
],
"Resource": [
"arn:aws:s3:::amzn-s3-demo-bucket-data",
"arn:aws:s3:::amzn-s3-demo-bucket-data/*"
],
"Effect": "Allow"
},
{
"Action": [
"s3:PutObject",
"s3:GetObject",
"s3:GetBucketLocation"
],
"Resource": [
"arn:aws:s3:::amzn-s3-demo-bucket-for-errors",
"arn:aws:s3:::amzn-s3-demo-bucket-for-errors/*"
],
"Effect": "Allow"
}
]
}
```
```
{
"adaptiveIngestion": adaptive-ingestion-flag,
"deleteFilesAfterImport": delete-files-after-import-flag,
"errorReportLocation": {
"bucket": "amzn-s3-demo-bucket-for-errors",
"prefix": "amzn-s3-demo-bucket-for-errors-prefix"
},
"files": [
{
"bucket": "amzn-s3-demo-bucket-data",
"key": "data-bucket-key",
"versionId": "data-bucket-version-id"
}
],
"jobConfiguration": {
"fileFormat": {
"csv": {
"columnNames": [ "column-name" ]
}
}
},
"jobName": "job-name",
"jobRoleArn": "job-role-arn"
}
```
**Example response**
```
{
"jobId":"f8c031d0-01d1-4b94-90b1-afe8bb93b7e5",
"jobStatus":"PENDING",
"jobName":"myBulkImportJob"
}
```
# Décrire une tâche d'importation AWS IoT SiteWise en masse (AWS CLI)
Utilisez l'opération [DescribeBulkImportJob](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_DescribeBulkImportJob.html)API pour récupérer des informations sur une tâche d'importation en bloc spécifique dans AWS IoT SiteWise. Cette opération renvoie des informations telles que le statut de la tâche, l'heure de création et les informations d'erreur en cas d'échec de la tâche. Vous pouvez utiliser cette opération pour suivre l'avancement des tâches et résoudre les problèmes. Pour l'utiliser`DescribeBulkImportJob`, vous avez besoin de l'ID de tâche de l'`CreateBulkImportJob`opération. L’API renvoie les informations suivantes :
+ Liste des fichiers en cours d'importation, y compris l'emplacement et les clés de leur compartiment Amazon S3
+ Emplacement du rapport d'erreur (le cas échéant)
+ Détails de configuration des tâches, tels que le format de fichier et les noms de colonnes CSV
+ Horodatage de la création d'un job et de la dernière mise à jour
+ État actuel de la tâche (par exemple, si la tâche est en cours, terminée ou échouée)
+ ARN du rôle IAM utilisé pour la tâche d'importation
Pour les tâches terminées, passez en revue les résultats pour confirmer que l'intégration des données est réussie. Si une tâche échoue, examinez les détails de l'erreur pour diagnostiquer et résoudre les problèmes.
*job-ID*Remplacez-le par l'ID de la tâche d'importation en bloc que vous souhaitez récupérer.
```
aws iotsitewise describe-bulk-import-job --job-id job-ID
```
**Example response**
```
{
"files":[
{
"bucket":"amzn-s3-demo-bucket1",
"key":"100Tags12Hours.csv"
},
{
"bucket":"amzn-s3-demo-bucket2",
"key":"BulkImportData1MB.csv"
},
{
"bucket":" amzn-s3-demo-bucket3",
"key":"UnmodeledBulkImportData1MB.csv"
}
],
"errorReportLocation":{
"prefix":"errors/",
"bucket":"amzn-s3-demo-bucket-for-errors"
},
"jobConfiguration":{
"fileFormat":{
"csv":{
"columnNames":[
"ALIAS",
"DATA_TYPE",
"TIMESTAMP_SECONDS",
"TIMESTAMP_NANO_OFFSET",
"QUALITY",
"VALUE"
]
}
}
},
"jobCreationDate":1645745176.498,
"jobStatus":"COMPLETED",
"jobName":"myBulkImportJob",
"jobLastUpdateDate":1645745279.968,
"jobRoleArn":"arn:aws:iam::123456789012:role/DemoRole",
"jobId":"f8c031d0-01d1-4b94-90b1-afe8bb93b7e5"
}
```
# Répertorier les tâches d'importation AWS IoT SiteWise en bloc (AWS CLI)
Utilisez l'opération [ListBulkImportJobs](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_ListBulkImportJobss.html)API pour récupérer une liste de résumés pour les tâches d'importation en bloc dans AWS IoT SiteWise. Cette opération constitue un moyen efficace de surveiller et de gérer vos processus d'importation de données. Il renvoie les informations clés suivantes pour chaque tâche :
+ Identifiant du poste. Un identifiant unique pour chaque tâche d'importation en masse
+ Nom du job. Le nom que vous avez attribué à la tâche lors de sa création
+ État actuel. État actuel de la tâche (par exemple, COMPLETED, RUNNING, FAILED)
ListBulkImportJobs est particulièrement utile pour obtenir une vue d'ensemble complète de toutes vos tâches d'importation en vrac. Cela peut vous aider à suivre plusieurs importations de données, à identifier les tâches nécessitant une attention particulière et à maintenir un flux de travail organisé. L'opération prend en charge la pagination, ce qui vous permet de récupérer efficacement un grand nombre de résumés de tâches. Vous pouvez utiliser la tâche IDs renvoyée par cette opération avec l'[DescribeBulkImportJob](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_DescribeBulkImportJob.html)opération pour récupérer des informations plus détaillées sur des tâches spécifiques. Ce processus en deux étapes vous permet d'abord d'obtenir une vue d'ensemble de tous les emplois, puis d'approfondir les détails des emplois qui vous intéressent. Lors de l'utilisation`ListBulkImportJobs`, vous pouvez appliquer des filtres pour affiner les résultats. Par exemple, vous pouvez filtrer les tâches en fonction de leur statut pour récupérer uniquement les tâches terminées ou uniquement les tâches en cours d'exécution. Cette fonctionnalité vous permet de vous concentrer sur les informations les plus pertinentes pour votre tâche en cours. L'opération renvoie également un `nextToken` si d'autres résultats sont disponibles. Vous pouvez utiliser ce jeton lors des appels suivants pour récupérer le prochain ensemble de résumés de tâches, ce qui vous permet de parcourir toutes vos tâches d'importation groupée, même si vous en avez un grand nombre. L'exemple suivant montre comment utiliser `ListBulkImportJobs` le AWS CLI pour récupérer une liste des tâches terminées.
```
aws iotsitewise list-bulk-import-jobs --filter COMPLETED
```
**Example Filtre de réponse pour les tâches terminées**
```
{
"jobSummaries":[
{
"id":"bdbbfa52-d775-4952-b816-13ba1c7cb9da",
"name":"myBulkImportJob",
"status":"COMPLETED"
},
{
"id":"15ffc641-dbd8-40c6-9983-5cb3b0bc3e6b",
"name":"myBulkImportJob2",
"status":"COMPLETED"
}
]
}
```
Cette commande montre comment récupérer une `ListBulkImportJobs` liste de tâches qui se sont terminées par des échecs. Le maximum est fixé à 50 résultats et nous utilisons le jeton suivant pour les résultats paginés.
```
aws iotsitewise list-bulk-import-jobs --filter COMPLETED_WITH_FAILURES --max-results 50 --next-token "string"
```