기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.
# AWS IoT SiteWise APIs로 데이터 수집
AWS IoT SiteWise APIs 사용하여 타임스탬프가 지정된 산업 데이터를 자산의 속성 및 측정 속성으로 전송합니다. APIs는 timestamp-quality-value(TQV) 구조를 포함하는 페이로드를 허용합니다.
# BatchPutAssetPropertyValue API
[BatchPutAssetPropertyValue](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_BatchPutAssetPropertyValue.html) 작업을 사용하여 데이터를 업로드할 수 있습니다. 이 작업을 사용하면 한 번에 여러 데이터 항목을 업로드할 수 있으므로, 여러 디바이스에서 데이터를 수집하여 단일 요청으로 모두 전송할 수 있습니다.
**중요**
[BatchPutAssetPropertyValue](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_BatchPutAssetPropertyValue.html) 작업에는 다음 할당량이 적용됩니다.
요청당 최대 10개 [항목](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_BatchPutAssetPropertyValue.html#API_BatchPutAssetPropertyValue_RequestSyntax).
항목당 최대 10개의 [속성 값](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_PutAssetPropertyValueEntry.html#iotsitewise-Type-PutAssetPropertyValueEntry-propertyValues)(TQV 데이터 포인트).
AWS IoT SiteWise 는 과거 7일 이상 또는 향후 10분 이상으로 날짜가 지정된 타임스탬프가 있는 모든 데이터를 거부합니다.
이러한 할당량에 대한 자세한 내용은 *AWS IoT SiteWise API 참조*의 [BatchPutAssetPropertyValue](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_BatchPutAssetPropertyValue.html)를 참조하세요.
자산 속성을 식별하려면 다음 중 하나를 지정합니다.
+ 데이터를 보낼 자산 속성의 `assetId` 및 `propertyId`
+ 데이터 스트림 별칭(예: `/company/windfarm/3/turbine/7/temperature`)인 `propertyAlias`. 이 옵션을 사용하려면 먼저 자산 속성의 별칭을 설정해야 합니다. 속성 별칭을 설정하려면 [에 대한 데이터 스트림 관리 AWS IoT SiteWise](manage-data-streams.md) 섹션을 참조하세요.
다음 예제는 JSON 파일에 저장된 페이로드로부터 풍력 터빈의 온도와 분당 회전 수(RPM) 판독값을 전송하는 방법을 보여줍니다.
```
aws iotsitewise batch-put-asset-property-value --cli-input-json file://batch-put-payload.json
```
의 예제 페이로드에는 다음과 같은 콘텐츠`batch-put-payload.json`가 있습니다.
```
{
"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"
}
]
}
]
}
```
`enablePartialEntryProcessing` 로 지정하면 실패를 초래하지 않는 모든 값을 `true` 수집할 수 있습니다. 기본값은 `false`입니다. 값이 유효하지 않으면 전체 항목이 수집에 실패합니다.
페이로드의 각 항목은 고유한 문자열로 정의할 수 있는 `entryId`를 포함합니다. 요청 항목이 실패하면 각 오류에 해당 요청의 `entryId`가 포함되므로 다시 시도할 요청을 알 수 있습니다.
`propertyValues` 목록에서 각 구조는 `value`, `timestamp` 및(`quality`선택 사항)를 포함하는 TQV(타임스탬프-품질-값) 구조입니다.
+ `value` - 설정되는 속성 유형에 따라 다음 필드 중 하나를 포함하는 구조입니다.
+ `booleanValue`
+ `doubleValue`
+ `integerValue`
+ `stringValue`
+ `nullValue`
+ `nullValue` - 값이 Null이고 품질이 `BAD` 또는 인 속성 값의 유형을 나타내는 다음 필드가 있는 구조입니다`UNCERTAIN`.
+ `valueType` - \$1"B", "D", "S", "I"\$1의 열거형
+ `timestamp` - 현재 Unix Epoch 시간(초) `timeInSeconds`를 포함하는 구조입니다. 시간적으로 정확한 데이터가 있는 경우 `timestamp` 구조에서 `offsetInNanos` 키를 설정할 수도 있습니다.는 타임스탬프가 과거 7일 이상 지난 데이터 포인트 또는 향후 10분 이상 지난 데이터 포인트를 AWS IoT SiteWise 거부합니다.
+ `quality` – (선택 사항) 다음 품질 문자열 중 하나입니다.
+ `GOOD` – (기본값) 데이터가 어떤 문제의 영향도 받지 않습니다.
+ `BAD` – 데이터가 센서 고장과 같은 문제의 영향을 받습니다.
+ `UNCERTAIN` – 데이터가 센서 부정확과 같은 문제의 영향을 받습니다.
가 계산에서 데이터 품질을 AWS IoT SiteWise 처리하는 방법에 대한 자세한 내용은 [공식 표현식의 데이터 품질을 참조하세요](expression-tutorials.md#data-quality).
# CreateBulkImportJob API
`CreateBulkImportJob` API를 사용하여 Amazon S3에서 대량의 데이터를 가져옵니다. Amazon S3에 데이터를 CSV 형식으로 저장해야 합니다. 데이터 파일에는 다음과 같은 열이 있을 수 있습니다.
**참고**
1970년 1월 1일 00:00:00 UTC보다 오래된 데이터는 지원되지 않습니다.
자산 속성을 식별하려면 다음 중 하나를 지정합니다.
데이터를 보낼 자산 속성의 `ASSET_ID` 및 `PROPERTY_ID`.
데이터 스트림 별칭(예: `/company/windfarm/3/turbine/7/temperature`)인 `ALIAS`. 이 옵션을 사용하려면 먼저 자산 속성의 별칭을 설정해야 합니다. 속성 별칭을 설정하는 방법에 대한 자세한 내용은 [에 대한 데이터 스트림 관리 AWS IoT SiteWise](manage-data-streams.md) 단원을 참조하세요.
+ `ALIAS` – OPC UA 서버 데이터 스트림 경로(예: `/company/windfarm/3/turbine/7/temperature`)와 같이 속성을 식별하는 속성 별칭입니다. 자세한 내용은 [에 대한 데이터 스트림 관리 AWS IoT SiteWise](manage-data-streams.md) 단원을 참조하십시오.
+ `ASSET_ID` – 자산의 ID입니다.
+ `PROPERTY_ID` – 자산 속성의 ID입니다.
+ `DATA_TYPE` – 속성의 데이터 형식입니다. 다음 중 하나일 수 있습니다.
+ `STRING` – 최대 1,024바이트의 문자열입니다.
+ `INTEGER` – 범위가 [-2,147,483,648, 2,147,483,647]인 부호 있는 32비트 정수입니다.
+ `DOUBLE` – 범위가 [-10^100, 10^100]이고 IEEE 754 배정밀도를 갖는 부동 소수점 숫자입니다.
+ `BOOLEAN` - `true` 또는 `false`입니다.
+ `TIMESTAMP_SECONDS` - Unix Epoch 시간으로 표시된 데이터 포인트의 타임스탬프입니다.
+ `TIMESTAMP_NANO_OFFSET` - `TIMESTAMP_SECONDS`에서 변환된 나노초의 오프셋입니다.
+ `QUALITY` - (선택 사항) 자산 속성 값의 품질입니다. 값은 다음 중 하나일 수 있습니다.
+ `GOOD` - (기본값) 데이터가 어떤 문제의 영향도 받지 않습니다.
+ `BAD` – 데이터가 센서 고장과 같은 문제의 영향을 받습니다.
+ `UNCERTAIN` – 데이터가 센서 부정확과 같은 문제의 영향을 받습니다.
가 계산에서 데이터 품질을 AWS IoT SiteWise 처리하는 방법에 대한 자세한 내용은 [공식 표현식의 데이터 품질을 참조하세요](expression-tutorials.md#data-quality).
+ `VALUE` - 자산 속성의 값입니다.
**Example .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 는 대량 가져오기 작업을 생성하고 기존 작업에 대한 정보를 가져오기 위해 다음과 같은 API 작업을 제공합니다.
+ [CreateBulkImportJob](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_CreateBulkImportJob.html) - 새 대량 가져오기 작업을 생성합니다.
+ [DescribeBulkImportJob](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_DescribeBulkImportJob.html) - 대량 가져오기 작업에 대한 정보를 검색합니다.
+ [ListBulkImportJob](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_ListBulkImportJobs.html) - 모든 대량 가져오기 작업의 요약 목록을 페이지별로 나누어 검색합니다.
# AWS IoT SiteWise 대량 가져오기 작업 생성(AWS CLI)
[CreateBulkImportJob](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_CreateBulkImportJob.html) API 작업을 사용하여 Amazon S3에서 AWS IoT SiteWise에 데이터를 전송할 수 있습니다. [CreateBulkImportJob](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_CreateBulkImportJob.html) API를 사용하면 대량의 기록 데이터를 수집하고 분석 데이터 스트림을 소규모 배치로 버퍼링된 수집할 수 있습니다. 데이터 수집을 위한 비용 효과적인 기본 원칙을 제공합니다. 다음 예제에서는 AWS CLI를 사용합니다.
**중요**
대량 가져오기 작업을 생성하기 전에 AWS IoT SiteWise 웜 티어 또는 AWS IoT SiteWise 콜드 티어를 활성화해야 합니다. 자세한 내용은 [에서 스토리지 설정 구성 AWS IoT SiteWise](configure-storage.md) 단원을 참조하십시오.
[CreateBulkImportJob](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_CreateBulkImportJob.html) API는 adaptive-ingestion-flag 파라미터를 설정하는 옵션을 AWS IoT SiteWise 사용하여 과거 데이터를에 수집할 수 있도록 지원합니다.
`false`로 설정하면 API는 계산 또는 알림을 트리거하지 않고 기록 데이터를 수집합니다.
`true`로 설정하면 API는 새 데이터를 수집하여 지표를 계산하고 데이터를 변환하여 7일 이내에 지속적인 분석 및 알림을 최적화합니다.
다음 명령을 실행합니다. *file-name*을 대량 가져오기 작업 구성이 포함된 파일의 이름으로 바꿉니다.
```
aws iotsitewise create-bulk-import-job --cli-input-json file://file-name.json
```
**Example 일괄 가져오기 작업 구성**
다음은 구성 설정의 예입니다.
+ *adaptive-ingestion-flag*를 `true` 또는 `false`로 바꿉니다.
+ `false`로 설정하면 일괄 가져오기 작업이 기록 데이터를 AWS IoT SiteWise로 수집합니다.
+ `true`로 설정하면 일괄 가져오기 작업은 다음을 수행합니다.
+ 새 데이터를에 수집합니다 AWS IoT SiteWise.
+ 지표를 계산하고 변환하며 7일 이내에 타임스탬프가 지정된 데이터에 대한 알림을 지원합니다.
+ *delete-files-after-import-flag*를 로 바꾸`true`어 AWS IoT SiteWise 웜 티어 스토리지에 수집한 후 Amazon S3 데이터 버킷에서 데이터를 삭제합니다.
+ amzn-s3-demo-bucket*-for-errors*를 이 일괄 가져오기 작업과 관련된 오류가 전송되는 Amazon S3 버킷의 이름으로 바꿉니다.
+ amzn-s3-demo-bucket*-for-errors-prefix*를 이 일괄 가져오기 작업과 관련된 오류가 전송되는 Amazon S3 버킷의 접두어로 바꿉니다.
Amazon S3에서는 접두사를 버킷의 폴더 이름으로 사용합니다. 각 Amazon S3 객체에는 버킷의 고유 식별자인 키가 있습니다. 버킷 내 각 객체는 정확히 하나의 키를 갖습니다. 접두사는 슬래시(/)로 끝나야 합니다. 자세한 내용을 알아보려면 *Amazon Simple Storage Service 사용 설명서*의 [접두어를 사용한 객체 구성](https://docs.aws.amazon.com/AmazonS3/latest/userguide/using-prefixes.html)을 참조하세요.
+ amzn-s3-demo-bucket*-data*를 데이터를 가져오는 Amazon S3 버킷의 이름으로 바꿉니다.
+ *data-bucket-key*를 데이터가 들어 있는 Amazon S3 객체의 키로 대체합니다. 각 객체에는 고유 식별자인 키가 있습니다. 각 객체에는 정확히 하나의 키가 있습니다.
+ *data-bucket-veron-id*를 버전 ID로 바꾸면 데이터가 들어 있는 Amazon S3 객체의 특정 버전을 식별할 수 있습니다. 이 파라미터는 선택 사항입니다.
+ *column-name*을 .csv 파일에 지정된 열 이름으로 대체하세요.
+ *job-name*을 대량 가져오기 작업을 식별하는 고유한 이름으로 대체하세요.
+ *job-role-arn*을 AWS IoT SiteWise 에서 Amazon S3 데이터를 읽을 수 있는 IAM 역할로 대체하세요.
역할에 다음 예에 표시된 것과 같은 권한이 있는지 확인합니다. amzn-s3-demo-bucket*-data*를 데이터가 포함된 Amazon S3 버킷의 이름으로 바꿉니다. 또한 *amzn-s3-demo-bucket-for-errors*를 이 일괄 가져오기 작업과 관련된 오류가 전송되는 Amazon S3 버킷의 이름으로 바꿉니다.
****
```
{
"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"
}
```
# AWS IoT SiteWise 대량 가져오기 작업 설명(AWS CLI)
[DescribeBulkImportJob](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_DescribeBulkImportJob.html) API 작업을 사용하여 AWS IoT SiteWise의 특정 일괄 가져오기 작업에 대한 정보를 검색할 수 있습니다. 이 작업은 작업의 상태, 만들어진 시간, 작업이 실패한 경우 오류 정보와 같은 세부 정보를 반환합니다. 이 작업을 사용하여 작업 진행 상황을 모니터링하고 문제를 해결할 수 있습니다. `DescribeBulkImportJob`을 사용하려면 `CreateBulkImportJob` 작업의 작업 ID가 필요합니다. API는 다음 정보를 반환합니다.
+ Amazon S3 버킷 위치 및 키를 포함하여 가져오는 파일 목록
+ 오류 보고서 위치(해당하는 경우)
+ 파일 형식 및 CSV 열 이름과 같은 작업 구성 세부 정보
+ 작업 생성 및 마지막 업데이트 타임스탬프
+ 현재 작업 상태(예: 작업이 진행 중인지, 완료되었는지 또는 실패했는지 여부)
+ 가져오기 작업에 사용되는 IAM 역할 ARN
완료된 작업의 경우 결과를 검토하여 성공적인 데이터 통합을 확인합니다. 작업이 실패하면 오류 세부 정보를 검사하여 문제를 진단하고 해결합니다.
*job-ID*를 검색하려는 대량 가져오기 작업의 ID로 대체하세요.
```
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"
}
```
# AWS IoT SiteWise 대량 가져오기 작업 나열(AWS CLI)
[ListBulkImportJobs](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_ListBulkImportJobss.html) API 작업을 사용하여 AWS IoT SiteWise의 일괄 가져오기 작업에 대한 요약 목록을 가져옵니다. 이 작업은 데이터 가져오기 프로세스를 모니터링하고 관리하는 효율적인 방법을 제공합니다. 각 작업에 대해 다음 키 정보를 반환합니다.
+ 작업 ID. 각 일괄 가져오기 작업에 대한 고유 식별자
+ 작업 이름. 생성 시 작업에 할당된 이름
+ 현재 상태. 작업의 현재 상태(예: 완료됨, 실행 중, 실패)
ListBulkImportJobs는 모든 일괄 가져오기 작업에 대한 포괄적인 개요를 가져오는 데 특히 유용합니다. 이를 통해 여러 데이터 가져오기를 추적하고, 주의가 필요한 작업을 식별하고, 구성된 워크플로를 유지할 수 있습니다. 이 작업은 페이지 매김을 지원하므로 많은 수의 작업 요약을 효율적으로 검색할 수 있습니다. [DescribeBulkImportJob](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_DescribeBulkImportJob.html) 작업과 함께 이 작업에서 반환된 작업 ID를 사용하여 특정 작업에 대한 자세한 정보를 검색할 수 있습니다. 이 2단계 프로세스를 통해 먼저 모든 작업을 개괄적으로 확인한 다음 관심 작업의 세부 정보를 심층 분석할 수 있습니다. `ListBulkImportJobs`를 사용할 때 필터를 적용하여 결과를 좁힐 수 있습니다. 예를 들어 상태를 기준으로 작업을 필터링하여 완료된 작업만 검색하거나 실행 중인 작업만 검색할 수 있습니다. 이 기능을 사용하면 현재 작업과 가장 관련성이 높은 정보에 집중할 수 있습니다. 사용 가능한 결과가 더 있는 경우에도 작업은 `nextToken`을 반환합니다. 후속 직접 호출에서 이 토큰을 사용하여 다음 작업 요약 세트를 검색할 수 있으므로 일괄 가져오기 작업이 많더라도 모든 작업을 반복할 수 있습니다. 다음 예제에서는와 `ListBulkImportJobs` 함께를 사용하여 완료된 작업 목록을 검색 AWS CLI 하는 방법을 보여줍니다.
```
aws iotsitewise list-bulk-import-jobs --filter COMPLETED
```
**Example 완료된 작업 필터에 대한 응답**
```
{
"jobSummaries":[
{
"id":"bdbbfa52-d775-4952-b816-13ba1c7cb9da",
"name":"myBulkImportJob",
"status":"COMPLETED"
},
{
"id":"15ffc641-dbd8-40c6-9983-5cb3b0bc3e6b",
"name":"myBulkImportJob2",
"status":"COMPLETED"
}
]
}
```
이 명령은 `ListBulkImportJobs`를 사용하여 실패로 완료된 작업 목록을 검색하는 방법을 보여 줍니다. 최댓값은 결과 50개로 설정되며 페이지 매김된 결과에 다음 토큰을 사용합니다.
```
aws iotsitewise list-bulk-import-jobs --filter COMPLETED_WITH_FAILURES --max-results 50 --next-token "string"
```