기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.
# 위치 데이터 인덱싱
[AWS IoT 플릿 인덱싱](https://docs.aws.amazon.com//iot/latest/developerguide/iot-indexing.html)을 사용하여 디바이스의 마지막 전송 위치 데이터를 인덱싱하고 지오쿼리를 사용하여 디바이스를 검색할 수 있습니다. 이 기능은 위치 추적 및 근접 검색과 같은 디바이스 모니터링 및 관리 사용 사례를 해결합니다. 위치 인덱싱은 다른 플릿 인덱싱 기능과 비슷하게 작동하며 [사물 인덱싱](managing-fleet-index.md)에 지정할 추가 구성과 함께 작동합니다.
일반적인 사용 사례는 다음과 같습니다. 원하는 지리적 경계 내에 위치한 디바이스를 검색하고 집계합니다. 인덱싱된 데이터 소스에서 디바이스 메타데이터 및 상태와 관련된 쿼리 용어를 사용하여 위치별 인사이트 가져오기, 플릿 모니터링 맵 내에서 렌더링 지연을 줄이고 마지막으로 보고된 디바이스 위치를 추적하기 위해 특정 지리적 영역에 결과를 필터링하는 등의 세분화된 보기를 제공하고, 원하는 경계 한도를 벗어나는 디바이스를 식별하고 [플릿 지표](iot-fleet-metrics.md)를 사용하여 경보를 생성합니다. 위치 인덱싱 및 지오쿼리를 시작하려면 [시작하기 자습서](location-indexing-tutorial.md) 섹션을 참조하세요.
## 지원되는 데이터 형식
AWS IoT 플릿 인덱싱은 다음 위치 데이터 형식을 지원합니다.
1.
**좌표 참조 시스템의 잘 알려진 텍스트 표현**
[지리적 정보 - 좌표 참조 시스템 형식의 잘 알려진 텍스트 표현](https://docs.ogc.org/is/12-063r5/12-063r5.html) 뒤에 오는 문자열입니다. 예시는 `"POINT(long lat)"`가 될 수 있습니다.
1.
**좌표를 나타내는 문자열**
`"latitude, longitude"` 또는 `"longitude, latitude"` 형식의 문자열입니다. `"longitude, latitude"`을 사용하면 `geoLocations`의 `order`도 함께 지정해야 합니다. 예시는 `"41.12,-71.34"`가 될 수 있습니다.
1.
**lat(위도), lon(경도) 키의 객체**
이 형식은 클래식 섀도와 명명된 섀도 모두에 적용됩니다. 지원되는 키: `lat`, `latitude`, `lon`, `long`, `longitude`. 예시는 `{"lat": 41.12, "lon": -71.34}`가 될 수 있습니다.
1.
**좌표를 나타내는 배열**
`[lat,lon]` 또는 `[lon,lat]` 형식의 배열입니다. [GeoJSON](https://geojson.org/)의 좌표와 동일한 `[lon,lat]` 형식(클래식 섀도우 및 명명된 섀도에 적용 가능)을 사용하는 경우 `geoLocations`에서도 `order`를 지정해야 합니다.
예시는 다음과 같습니다.
```
{
"location": {
"coordinates": [
**Longitude**,
**Latitude**
],
"type": "Point",
"properties": {
"country": "United States",
"city": "New York",
"postalCode": "*****",
"horizontalAccuracy": 20,
"horizontalConfidenceLevel": 0.67,
"state": "New York",
"timestamp": "2023-01-04T20:59:13.024Z"
}
}
}
```
## 위치 데이터를 인덱싱하는 방법
다음 단계에서는 위치 데이터에 대한 인덱싱 구성을 업데이트하고 지오쿼리를 사용하여 디바이스를 검색하는 방법을 보여줍니다.
1.
**위치 데이터가 저장되는 위치 파악**
플릿 인덱싱은 현재 클래식 섀도 또는 명명된 섀도우에 저장된 위치 데이터 인덱싱을 지원합니다.
1.
**지원되는 위치 데이터 형식 사용**
위치 데이터 형식이 [지원되는 데이터 형식](#location-indexing-format) 중 하나를 따르는지 확인합니다.
1.
**인덱싱 구성 업데이트**
최소한 사물(등록) 인덱싱 구성을 활성화해야 합니다. 또한 위치 데이터가 포함된 클래식 섀도 또는 명명된 섀도에서 인덱싱을 활성화해야 합니다. 사물 인덱싱을 업데이트할 때는 인덱싱 구성에 위치 데이터를 포함해야 합니다.
1.
**지오쿼리 생성 및 실행**
사용 사례에 따라 지오쿼리를 생성하고 실행하여 디바이스를 검색합니다. 구성한 지오쿼리는 [쿼리 구문](https://docs.aws.amazon.com//iot/latest/developerguide/query-syntax.html)을 따라야 합니다. [지오쿼리 예시](#location-indexing-geoqueries)에서 몇 가지 예제를 찾아볼 수 있습니다.
## 사물 인덱싱 구성 업데이트
위치 데이터를 인덱싱하려면 인덱싱 구성을 업데이트하고 위치 데이터를 포함해야 합니다. 위치 데이터가 저장되는 위치에 따라 다음 단계에 따라 인덱싱 구성을 업데이트합니다.
### 클래식 섀도에 저장된 위치 데이터
위치 데이터가 클래식 섀도에 저장되는 경우 `thingIndexingMode`를 `REGISTRY_AND_SHADOW`로 설정하고 [https://docs.aws.amazon.com//iot/latest/apireference/API_IndexingFilter.html](https://docs.aws.amazon.com//iot/latest/apireference/API_IndexingFilter.html)의 `geoLocations` 필드(`name` 및 `order`)에 위치 데이터를 지정해야 합니다.
다음 사물 인덱싱 구성 예제에서는 위치 데이터 경로`shadow.reported.coordinates`를 `name` 및 `LonLat`를 `order`로 지정합니다.
```
{
"thingIndexingMode": "REGISTRY_AND_SHADOW",
"filter": {
"geoLocations": [
{
"name": "shadow.reported.coordinates",
"order": "LonLat"
}
]
}
}
```
+ `thingIndexingMode`
인덱싱 모드는 레지스트리 또는 섀도가 인덱싱되는지 여부를 제어합니다. `thingIndexingMode` 이 `OFF`로 설정되면 사물 인덱싱이 비활성화됩니다.
클래식 섀도에 저장된 위치 데이터를 인덱싱하려면 `thingIndexingMode`를 `REGISTRY_AND_SHADOW`로 설정해야 합니다. 자세한 내용은 [사물 인덱싱 모드](managing-index.md#index-mode) 단원을 참조하십시오.
+ `filter`
인덱싱 필터는 명명된 섀도 및 지리적 위치 데이터에 대한 추가 선택을 제공합니다. 자세한 내용은 [인덱싱 필터](managing-index.md#thing-indexing-filter) 단원을 참조하십시오.
+ `geoLocations`
인덱싱할 지리적 위치 대상 목록입니다. 인덱싱을 위한 기본 최대 지리적 위치 대상 수는 `1`입니다. 제한 증가를 요청하려면 [AWS IoT Device Management 할당량](https://docs.aws.amazon.com//general/latest/gr/iot_device_management.html#fleet-indexing-limits) 섹션을 참조하세요.
+ `name`
지리적 위치 대상 필드의 이름입니다. `name`의 예제 값은 섀도의 위치 데이터 경로인 `shadow.reported.coordinates`가 될 수 있습니다.
+ `order`
지리적 위치 대상 필드의 순서입니다. 유효한 값: `LatLon` 및 `LonLat`. `LatLon`은 위도 및 경도를 의미하고, `LonLat`는 경도 및 위도를 의미합니다. 이 필드는 선택 사항입니다. 기본값은 `LatLon`입니다.
### 명명된 섀도에 저장된 위치 데이터
위치 데이터가 명명된 섀도에 저장되는 경우 `namedShadowIndexingMode`를 `ON`로 설정하고 [https://docs.aws.amazon.com//iot/latest/apireference/API_IndexingFilter.html](https://docs.aws.amazon.com//iot/latest/apireference/API_IndexingFilter.html)의 `namedShadowNames` 필드에 명명된 섀도 이름을 추가하고 [https://docs.aws.amazon.com//iot/latest/apireference/API_IndexingFilter.html](https://docs.aws.amazon.com//iot/latest/apireference/API_IndexingFilter.html)의 `geoLocations` 필드에 위치 데이터 경로를 지정합니다.
다음 사물 인덱싱 구성 예제에서는 위치 데이터 경로`shadow.name.namedShadow1.reported.coordinates`를 `name` 및 `LonLat`를 `order`로 지정합니다.
```
{
"thingIndexingMode": "REGISTRY",
"namedShadowIndexingMode": "ON",
"filter": {
"namedShadowNames": [
"namedShadow1"
],
"geoLocations": [
{
"name": "shadow.name.namedShadow1.reported.coordinates",
"order": "LonLat"
}
]
}
}
```
+ `thingIndexingMode`
인덱싱 모드는 레지스트리 또는 섀도가 인덱싱되는지 여부를 제어합니다. `thingIndexingMode` 이 `OFF`로 설정되면 사물 인덱싱이 비활성화됩니다.
명명된 섀도에 저장된 위치 데이터를 인덱싱하려면 `thingIndexingMode`를 `REGISTRY`(또는 `REGISTRY_AND_SHADOW`)로 설정해야 합니다. 자세한 내용은 [사물 인덱싱 모드](managing-index.md#index-mode) 단원을 참조하십시오.
+ `filter`
인덱싱 필터는 명명된 섀도 및 지리적 위치 데이터에 대한 추가 선택을 제공합니다. 자세한 내용은 [인덱싱 필터](managing-index.md#thing-indexing-filter) 단원을 참조하십시오.
+ `geoLocations`
인덱싱할 지리적 위치 대상 목록입니다. 인덱싱을 위한 기본 최대 지리적 위치 대상 수는 `1`입니다. 제한 증가를 요청하려면 [AWS IoT Device Management 할당량](https://docs.aws.amazon.com//general/latest/gr/iot_device_management.html#fleet-indexing-limits) 섹션을 참조하세요.
+ `name`
지리적 위치 대상 필드의 이름입니다. `name`의 예제 값은 섀도의 위치 데이터 경로인 `shadow.name.namedShadow1.reported.coordinates`가 될 수 있습니다.
+ `order`
지리적 위치 대상 필드의 순서입니다. 유효한 값: `LatLon` 및 `LonLat`. `LatLon`은 위도 및 경도를 의미하고, `LonLat`는 경도 및 위도를 의미합니다. 이 필드는 선택 사항입니다. 기본값은 `LatLon`입니다.
## 지오쿼리 예시
위치 데이터에 대한 인덱싱 구성을 완료한 후 지오쿼리를 실행하여 디바이스를 검색합니다. 지오쿼리를 다른 쿼리 문자열과 결합할 수도 있습니다. 자세한 내용은 [쿼리 구문](query-syntax.md) 및 [사물 쿼리 예](example-queries.md) 섹션을 참조하세요.
**쿼리 예시 1**
이 예시에서는 위치 데이터가 명명된 섀도 `gps-tracker`에 저장된다고 가정합니다. 이 명령의 출력은 좌표(47.6204,-122.3491)가 있는 중심점에서 15.5km의 반경 거리 내에 있는 디바이스 목록입니다.
```
aws iot search-index --query-string \
"shadow.name.gps-tracker.reported.coordinates:geo_distance,47.6204,-122.3491,15.5km"
```
**쿼리 예시 2**
이 예제에서는 위치 데이터가 클래식 섀도에 저장된다고 가정합니다. 이 명령의 출력은 좌표(47.6204,-122.3491)가 있는 중심점에서 15.5km의 반경 거리 내에 있는 디바이스 목록입니다.
```
aws iot search-index --query-string \
"shadow.reported.coordinates:geo_distance,47.6204,-122.3491,15.5km"
```
**쿼리 예시 3**
이 예제에서는 위치 데이터가 클래식 섀도에 저장된다고 가정합니다. 이 명령의 출력은 연결되지 않고 좌표(47.6204,-122.3491)가 있는 중심점에서 15.5km의 방사상 거리를 벗어나는 디바이스 목록입니다.
```
aws iot search-index --query-string \
"connectivity.connected:false AND (NOT shadow.reported.coordinates:geo_distance,47.6204,-122.3491,15.5km)"
```
# 시작하기 자습서
이 자습서에서는 [플릿 인덱싱](iot-indexing.md)을 사용하여 [위치 데이터를 인덱싱](location-indexing-geoquery.md)하는 방법을 보여줍니다. 간소화를 위해 디바이스를 나타내는 사물을 생성하고 위치 데이터를 명명된 섀도에 저장하고, 위치 인덱싱을 위한 사물 인덱싱 구성을 업데이트하고, 예시 지오쿼리를 실행하여 방사형 경계 내의 디바이스를 검색합니다.
이 자습서는 완료하는 데 약 15분이 소요됩니다.
**Topics**
+ [
## 사전 조건
](#location-indexing-tutorial-prerequisites)
+ [
## 사물 및 섀도 생성
](#location-indexing-create-resources)
+ [
## 사물 인덱싱 구성 업데이트
](#location-indexing-update-configuration)
+ [
## 지오쿼리 실행
](#location-indexing-run-geoquery)
## 사전 조건
+ [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-install.html)의 최신 버전을 설치합니다.
+ [위치 인덱싱 및 지오쿼리](https://docs.aws.amazon.com/iot/latest/developerguide/location-indexing-geoquery.html) , [사물 인덱싱 관리](https://docs.aws.amazon.com/iot/latest/developerguide/managing-index.html) 및 [쿼리 구문](https://docs.aws.amazon.com/iot/latest/developerguide/query-syntax.html)을 숙지합니다.
## 사물 및 섀도 생성
디바이스를 나타내는 사물과 위치 데이터를 저장할 명명된 섀도를 생성합니다(협정 47.61564, -122.33584).
1. 다음 명령을 실행하여 Bike-1이라는 자전거를 나타내는 사물을 생성합니다. 를 사용하여 사물을 생성하는 방법에 대한 자세한 AWS CLI내용은 *AWS CLI** 참조*의 [create-thing](https://docs.aws.amazon.com//cli/latest/reference/iot/create-thing.html)을 참조하세요.
```
aws iot create-thing --thing-name "Bike-1" \
--attribute-payload '{"attributes": {"model":"OEM-2302-12", "battery":"35", "acqDate":"06/09/23"}}'
```
이 명령의 출력은 다음과 같을 수 있습니다.
```
{
"thingName": "Bike-1",
"thingArn": "arn:aws:iot:us-east-1:123456789012:thing/Bike-1",
"thingId": "df9cf01d-b0c8-48fe-a2e2-e16cff6b23df"
}
```
1. 다음 명령을 실행하여 Bike-1의 위치 데이터를 저장할 명명된 섀도를 생성합니다(협정 47.61564, -122.33584). 를 사용하여 명명된 섀도우를 생성하는 방법에 대한 자세한 AWS CLI내용은 *AWS CLI** 참조*의 [update-thing-shadow](https://docs.aws.amazon.com//cli/latest/reference/iot-data/update-thing-shadow.html)를 참조하세요.
```
aws iot-data update-thing-shadow \
--thing-name Bike-1 \
--shadow-name Bike1-shadow \
--cli-binary-format raw-in-base64-out \
--payload '{"state":{"reported":{"coordinates":{"lat": 47.6153, "lon": -122.3333}}}}' \
"output.txt" \
```
이 명령은 출력을 생성하지 않습니다. 생성한 명명된 섀도를 보려면 [list-named-shadows-for-thing](https://docs.aws.amazon.com//cli/latest/reference/iot-data/list-named-shadows-for-thing.html) CLI 명령을 실행할 수 있습니다.
```
aws iot-data list-named-shadows-for-thing --thing-name Bike-1
```
이 명령의 출력은 다음과 같을 수 있습니다.
```
{
"results": [
"Bike1-shadow"
],
"timestamp": 1699574309
}
```
## 사물 인덱싱 구성 업데이트
위치 데이터를 인덱싱하려면 사물 인덱싱 구성을 업데이트하여 위치 데이터를 포함해야 합니다. 위치 데이터는 이 자습서의 명명된 섀도에 저장되므로 `thingIndexingMode`를 `REGISTRY`(최소 요구 사항에서)로 설정하고 `namedShadowIndexingMode`를 `ON`으로 설정하고 위치 데이터를 구성에 추가합니다. 이 예시에서는 명명된 섀도의 이름과 섀도의 위치 데이터 경로를 `filter`에 추가해야 합니다.
1. 명령을 실행하여 위치 인덱싱에 대한 인덱싱 구성을 업데이트합니다.
```
aws iot update-indexing-configuration --cli-input-json '{
"thingIndexingConfiguration": { "thingIndexingMode": "REGISTRY",
"thingConnectivityIndexingMode": "OFF",
"deviceDefenderIndexingMode": "OFF",
"namedShadowIndexingMode": "ON",
"filter": {
"namedShadowNames": ["Bike1-shadow"],
"geoLocations":[{
"name":"shadow.name.Bike1-shadow.reported.coordinates"
}]
},
"customFields": [
{ "name":"attributes.battery",
"type":"Number"}] } }'
```
명령은 출력을 생성하지 않습니다. 업데이트가 완료될 때까지 잠시 기다려야 할 수 있습니다. 사물 인덱스 상태를 확인하려면 [describe-index](https://docs.aws.amazon.com//cli/latest/reference/iot/describe-index.html) CLI 명령을 실행합니다. `indexStatus` 가 `ACTIVE`로 표시되면 사물 인덱싱 업데이트가 완료된 것입니다.
1. 명령을 실행하여 인덱싱 구성을 확인합니다. 이 단계는 선택 사항입니다.
```
aws iot get-indexing-configuration
```
출력은 다음과 같습니다.
```
{
"thingIndexingConfiguration": {
"thingIndexingMode": "REGISTRY",
"thingConnectivityIndexingMode": "OFF",
"deviceDefenderIndexingMode": "OFF",
"namedShadowIndexingMode": "ON",
"managedFields": [
{
"name": "shadow.name.*.hasDelta",
"type": "Boolean"
},
{
"name": "registry.version",
"type": "Number"
},
{
"name": "registry.thingTypeName",
"type": "String"
},
{
"name": "registry.thingGroupNames",
"type": "String"
},
{
"name": "shadow.name.*.version",
"type": "Number"
},
{
"name": "thingName",
"type": "String"
},
{
"name": "thingId",
"type": "String"
}
],
"customFields": [
{
"name": "attributes.battery",
"type": "Number"
}
],
"filter": {
"namedShadowNames": [
"Bike1-shadow"
],
"geoLocations": [
{
"name": "shadow.name.Bike1-shadow.reported.coordinates",
"order": "LatLon"
}
]
}
},
"thingGroupIndexingConfiguration": {
"thingGroupIndexingMode": "OFF"
}
}
```
## 지오쿼리 실행
이제 위치 데이터를 포함하도록 사물 인덱싱 구성을 업데이트했습니다. 몇 가지 지오쿼리를 생성하고 실행하여 원하는 검색 결과를 얻을 수 있는지 확인합니다. 지오쿼리는 [쿼리 구문](query-syntax.md)을 따라야 합니다. [지오쿼리 예시](location-indexing-geoquery.md#location-indexing-geoqueries)에서 몇 가지 유용한 예제 지오쿼리를 찾을 수 있습니다.
다음 예제 명령에서는 지오쿼리 `shadow.name.Bike1-shadow.reported.coordinates:geo_distance,47.6204,-122.3491,15.5km`를 사용하여 좌표(47.6204,-122.3491)를 사용하여 중심점에서 15.5km의 반경 거리 내에 있는 디바이스를 검색합니다.
```
aws iot search-index --query-string "shadow.name.Bike1-shadow.reported.coordinates:geo_distance,47.6204,-122.3491,15.5km"
```
좌표 ‘lat’: 47.6153, ‘lon’: -122.3333에 중심점에서 15.5km 거리 내에 있는 디바이스가 있으므로 출력에서 이 디바이스(Bike-1)를 볼 수 있습니다. 출력은 다음과 같습니다.
```
{
"things": [
{
"thingName": "Bike-1",
"thingId": "df9cf01d-b0c8-48fe-a2e2-e16cff6b23df",
"attributes": {
"acqDate": "06/09/23",
"battery": "35",
"model": "OEM-2302-12"
},
"shadow": "{\"reported\":{\"coordinates\":{\"lat\":47.6153,\"lon\":-122.3333}},\"metadata\":{\"reported\":{\"coordinates\":{\"lat\":{\"timestamp\":1699572906},\"lon\":{\"timestamp\":1699572906}}}},\"hasDelta\":false,\"version\":1}"
}
]
}
```
자세한 내용은 [위치 데이터 인덱싱](location-indexing-geoquery.md) 단원을 참조하십시오.