**지원 종료 공지:** 2026년 10월 30일에 Amazon Pinpoint에 대한 지원이 AWS 종료됩니다. 2026년 10월 30일 이후에는 Amazon Pinpoint 콘솔 또는 Amazon Pinpoint 리소스(엔드포인트, 세그먼트, 캠페인, 여정, 분석)에 더 이상 액세스할 수 없습니다. 자세한 내용은 [Amazon Pinpoint 지원 종료](https://docs.aws.amazon.com/console/pinpoint/migration-guide)를 참조하세요. **참고:** SMS, 음성, 모바일 푸시, OTP 및 전화번호 검증과 관련된 APIs는이 변경의 영향을 받지 않으며 AWS 최종 사용자 메시징에서 지원됩니다.
기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.
# Amazon Pinpoint 분석 JSON 쿼리 결과 사용
Amazon Pinpoint Analytics API를 사용하여 분석 데이터를 쿼리하면 Amazon Pinpoint는 결과를 JSON 응답으로 반환합니다. 애플리케이션 지표, 캠페인 지표 및 여정 참여 지표의 경우 응답의 데이터는 Amazon Pinpoint 분석 데이터 보고를 위한 표준 JSON 스키마를 준수합니다.
즉, 선택한 프로그래밍 언어나 도구를 사용하여 하나 이상의 지표에 대한 데이터를 쿼리하고 각 쿼리의 결과를 캡처한 다음 결과를 테이블, 객체 또는 기타 위치에 쓰는 사용자 지정 솔루션을 구현할 수 있습니다. 그런 다음 다른 서비스 또는 애플리케이션을 사용하여 해당 위치에서 쿼리 결과를 사용할 수 있습니다.
예를 들어, 다음을 수행할 수 있습니다.
+ 정기적으로 지표 집합을 쿼리하고 선호하는 데이터 시각화 프레임워크를 사용하여 결과를 표시하는 사용자 지정 대시보드를 빌드합니다.
+ 적절한 지표를 쿼리하고 차트 또는 사용자가 디자인한 다른 유형의 보고서에 결과를 표시하여 참여율을 추적하는 보고서를 만듭니다.
+ 분석 데이터를 구문 분석하여 특정 스토리지 형식으로 작성한 다음 결과를 장기 스토리지 솔루션으로 포트합니다.
Amazon Pinpoint Analytics API는 나중에 Amazon Pinpoint 프로젝트 또는 Amazon Pinpoint 계정에서 읽거나 사용할 수 있는 영구 객체를 만들거나 저장하도록 설계되지 않았습니다. 대신 API는 분석 데이터를 검색하고 추가 분석, 저장 또는 보고를 위해 해당 데이터를 다른 서비스 및 애플리케이션으로 전송할 수 있도록 설계되었습니다. 애플리케이션 지표, 캠페인 지표 및 여정 참여 지표에 대해 프로그래밍 방식으로 쿼리할 수 있는 모든 분석 데이터에 대해 동일한 JSON 응답 구조 및 스키마를 사용하여 이 작업을 부분적으로 수행합니다.
이 주제에서는 애플리케이션 지표, 캠페인 지표 또는 여정 참여 지표 쿼리에 대한 JSON 응답의 구조, 객체 및 필드에 대해 설명합니다. 여정 실행 지표 또는 여정 활동 실행 지표 쿼리에 대한 JSON 응답의 필드에 대한 자세한 내용은 [Amazon Pinpoint 프로젝트, 캠페인 및 여정에 적용되는 표준 지표](analytics-standard-metrics.md) 단원을 참조하십시오.
## JSON 구조
쿼리 결과를 구문 분석하고 사용하는 데 도움이 되도록 Amazon Pinpoint 분석 API는 애플리케이션 지표, 캠페인 지표 및 여정 참여 지표에 대해 프로그래밍 방식으로 쿼리할 수 있는 모든 Amazon Pinpoint 분석 데이터에 대해 동일한 JSON 응답 구조를 사용합니다. 각 JSON 응답은 프로젝트 ID(`ApplicationId`)와 같이 쿼리를 정의한 값을 지정합니다. 응답에는 단 하나의 `KpiResult` 객체도 포함됩니다. `KpiResult` 객체에는 쿼리에 대한 전체 결과 집합이 포함됩니다.
각 `KpiResult` 객체에는 `Rows` 객체가 포함됩니다. 이는 쿼리 결과 및 해당 결과의 값에 대한 관련 메타데이터가 포함된 객체 배열입니다. `Rows` 객체의 구조와 내용에는 다음과 같은 일반적인 특성이 있습니다.
+ 쿼리 결과의 각 행은 객체에서 이름이 지정된 `Values`, 별도의 JSON `Rows` 객체입니다. 예를 들어 쿼리가 세 개의 값을 반환하는 경우 `Rows` 객체에는 세 개의 `Values` 객체가 포함됩니다. 각 `Values` 객체에는 쿼리에 대한 개별 결과가 포함되어 있습니다.
+ 쿼리 결과의 각 열은 적용되는 `Values` 객체의 속성입니다. 열 이름은 `Values` 객체의 `Key` 필드에 저장됩니다.
+ 그룹화된 쿼리 결과의 경우 각 `Values` 객체에는 연관된 `GroupedBys` 객체가 있습니다. `GroupedBys` 객체는 결과를 그룹화하는 데 사용된 필드를 나타냅니다. 또한 연관된 `Values` 객체의 그룹화 값을 제공합니다.
+ 지표에 대한 쿼리 결과가 null이면 `Rows` 객체는 비어 있습니다.
이러한 일반적인 특성 외에도 `Rows` 객체의 구조와 내용은 지표에 따라 다릅니다. Amazon Pinpoint는 *단일 값 지표*와 *다중 값 지표*라는 두 가지 종류의 지표를 지원하기 때문입니다.
*단일 값 지표*는 하나의 누적 값만 제공합니다. 이러한 예로는 캠페인의 모든 실행에 의해 수신자에게 배달된 메시지의 비율을 들 수 있습니다. *다중 값 지표*는 둘 이상의 값을 제공하고 해당 값을 관련 필드별로 그룹화합니다. 예를 들어 캠페인 실행마다 수신자에게 배달된 메시지의 비율이 캠페인 실행별로 그룹화되어 있습니다.
지표의 이름을 참조하여 지표가 단일 값 지표인지 또는 다중 값 지표인지 신속하게 확인할 수 있습니다. 이름에 `grouped-by`가 포함되어 있지 않으면 단일 값 지표입니다. 포함한다면 다중 값 지표입니다. 프로그래밍 방식으로 쿼리할 수 있는 지표의 전체 목록은 [Amazon Pinpoint 프로젝트, 캠페인 및 여정에 적용되는 표준 지표](analytics-standard-metrics.md) 단원을 참조하십시오.
### 단일 값 지표
단일 값 지표의 경우 `Rows` 객체는 다음과 같은 `Values` 객체를 포함합니다.
+ 쿼리된 지표의 이름을 지정합니다.
+ 쿼리된 지표에 대한 값을 제공합니다.
+ 반환된 값의 데이터 유형을 식별합니다.
예를 들어 다음 JSON 응답에는 단일 값 지표에 대한 쿼리 결과가 포함되어 있습니다. 이 지표는 2019년 8월 1일부터 2019년 8월 31일까지 프로젝트와 연결된 모든 캠페인에 의해 메시지가 배달된 고유한 엔드포인트 수를 보고합니다.
```
{
"ApplicationDateRangeKpiResponse":{
"ApplicationId":"1234567890123456789012345example",
"EndTime":"2019-08-31T23:59:59Z",
"KpiName":"unique-deliveries",
"KpiResult":{
"Rows":[
{
"Values":[
{
"Key":"UniqueDeliveries",
"Type":"Double",
"Value":"1368.0"
}
]
}
]
},
"StartTime":"2019-08-01T00:00:00Z"
}
}
```
이 예에서 응답은 모든 프로젝트의 캠페인이 2019년 8월 1일부터 2019년 8월 31일까지 1,368개의 고유한 엔드포인트에 메시지를 배달했음을 나타냅니다.
+ `Key`는 `Value` 필드(`UniqueDeliveries`)에 값이 지정된 지표의 친숙한 이름입니다.
+ `Type`은 `Value` 필드(`Double`) 에 지정된 값의 데이터 유형입니다.
+ `Value`는 적용된 필터를 포함하여 쿼리된 지표의 실제 값입니다(`1368.0`).
단일 값 지표에 대한 쿼리 결과가 null(0보다 크거나 같지 않음)인 경우 `Rows` 객체는 비어 있습니다. Amazon Pinpoint는 어떤 지표에 대해 반환할 데이터가 없을 경우, 해당 지표에 대해 null 값을 반환합니다. 예제:
```
{
"ApplicationDateRangeKpiResponse":{
"ApplicationId":"2345678901234567890123456example",
"EndTime":"2019-08-31T23:59:59Z",
"KpiName":"unique-deliveries",
"KpiResult":{
"Rows":[
]
},
"StartTime":"2019-08-01T00:00:00Z"
}
}
```
### 다중 값 지표
다중 값 지표에 대한 `Rows` 객체의 구조 및 내용은 대부분 단일 값 지표와 동일합니다. 다중 값 지표에 대한 `Rows` 객체에는 `Values` 객체도 포함되어 있습니다. `Values` 객체는 쿼리된 지표의 친숙한 이름을 지정하고 해당 지표에 대한 값을 제공하고 해당 값의 데이터 유형을 식별합니다.
그러나 다중 값 지표에 대한 `Rows` 객체에는 하나 이상의 `GroupedBy` 객체도 포함됩니다. 쿼리 결과에는 각 `Values` 객체에 대해 하나의 `GroupedBy` 객체가 있습니다. `GroupedBy` 객체는 결과의 데이터를 그룹화하는 데 사용된 필드와 해당 필드의 데이터 유형을 나타냅니다. 또한 연관된 `Values` 객체의 해당 필드에 대한 그룹화 값을 나타냅니다.
예를 들어 다음 JSON 응답에는 2019년 8월 1일부터 2019년 8월 31일까지 프로젝트와 연결된 각 캠페인에 대해 메시지가 배달된 고유한 엔드포인트 수를 보고하는 다중 값 지표에 대한 쿼리 결과가 포함되어 있습니다.
```
{
"ApplicationDateRangeKpiResponse":{
"ApplicationId":"1234567890123456789012345example",
"EndTime":"2019-08-31T23:59:59Z",
"KpiName":"unique-deliveries-grouped-by-campaign",
"KpiResult":{
"Rows":[
{
"GroupedBys":[
{
"Key":"CampaignId",
"Type":"String",
"Value":"80b8efd84042ff8d9c96ce2f8example"
}
],
"Values":[
{
"Key":"UniqueDeliveries",
"Type":"Double",
"Value":"123.0"
}
]
},
{
"GroupedBys":[
{
"Key":"CampaignId",
"Type":"String",
"Value":"810c7aab86d42fb2b56c8c966example"
}
],
"Values":[
{
"Key":"UniqueDeliveries",
"Type":"Double",
"Value":"456.0"
}
]
},
{
"GroupedBys":[
{
"Key":"CampaignId",
"Type":"String",
"Value":"42d8c7eb0990a57ba1d5476a3example"
}
],
"Values":[
{
"Key":"UniqueDeliveries",
"Type":"Double",
"Value":"789.0"
}
]
}
]
},
"StartTime":"2019-08-01T00:00:00Z"
}
}
```
이 예에서 응답은 프로젝트 캠페인 중 세 개가 2019년 8월 1일부터 2019년 8월 31일까지 고유한 엔드포인트로 메시지를 배달했음을 나타냅니다. 각 캠페인의 제공 건수 분석은 다음과 같습니다.
+ `80b8efd84042ff8d9c96ce2f8example` 캠페인은 123개의 고유한 엔드포인트에 메시지를 배달했습니다.
+ `810c7aab86d42fb2b56c8c966example` 캠페인은 456개의 고유한 엔드포인트로 메시지를 배달했습니다.
+ `42d8c7eb0990a57ba1d5476a3example` 캠페인은 789개의 고유한 엔드포인트로 메시지를 배달했습니다.
객체 및 필드의 일반적인 구조는 다음과 같습니다.
+ `GroupedBys.Key` - `GroupedBys.Value` 필드(`CampaignId`)에 지정된 그룹화 값을 저장하는 속성 또는 필드의 이름입니다.
+ `GroupedBys.Type` - `GroupedBys.Value` 필드(`String`)에 지정된 값의 데이터 유형입니다.
+ `GroupedBys.Value` - `GroupedBys.Key` 필드(캠페인 ID)에 지정된 대로 데이터를 그룹화하는 데 사용된 필드의 실제 값입니다.
+ `Values.Key` - `Values.Value` 필드(`UniqueDeliveries`)에 값이 지정된 지표의 친숙한 이름입니다.
+ `Values.Type` - `Values.Value` 필드(`Double`)에 지정된 값의 데이터 유형입니다.
+ `Values.Value` - 적용된 필터를 포함하여 쿼리된 지표의 실제 값입니다.
다중 값 지표에 대한 쿼리 결과가 특정 프로젝트, 캠페인 또는 기타 리소스에 대해 null(0보다 크거나 같지 않음)인 경우 Amazon Pinpoint는 리소스에 대한 객체나 필드를 반환하지 않습니다. 다중 값 지표에 대한 쿼리 결과가 모든 리소스에 대해 null인 경우 Amazon Pinpoint는 빈 `Rows` 객체를 반환합니다.
## JSON 객체 및 필드
프로젝트 ID(`ApplicationId`)와 같이 쿼리를 정의한 값을 지정하는 것 외에도 애플리케이션 지표, 캠페인 지표 또는 여정 참여 지표 쿼리에 대한 각 JSON 응답에는 `KpiResult` 객체가 포함됩니다. 이 객체에는 쿼리에 대한 전체 결과 집합이 포함되어 있습니다. 이 결과 집합을 구문 분석하여 분석 데이터를 다른 서비스 또는 애플리케이션으로 보낼 수 있습니다. 각 `KpiResult` 객체에는 지표에 따라 다음과 같은 표준 객체 및 필드 중 일부 또는 전체가 포함됩니다.
| 객체 또는 필드 | 설명 |
| --- | --- |
| Rows | 쿼리에 대한 결과 집합을 포함하는 객체의 배열입니다. |
| Rows.GroupedBys | 다중 값 지표의 경우 쿼리 결과에서 데이터를 그룹화하는 데 사용된 필드 및 값을 정의하는 필드 배열입니다. |
| Rows.GroupedBys.Key | 다중 값 지표의 경우 필드에 지정된 값을 저장하는 속성 또는 GroupedBys.Value 필드의 이름입니다. |
| Rows.GroupedBys.Type | 다중 값 지표의 경우 GroupedBys.Value 필드에 지정된 값의 데이터 유형입니다. |
| Rows.GroupedBys.Value | 다중 값 지표의 경우 쿼리 결과에서 데이터를 그룹화하는 데 사용된 필드의 실제 값입니다. 이 값은 연결된 Values 객체와 연관됩니다. |
| Rows.Values | 쿼리 결과를 포함하는 필드의 배열입니다. |
| Rows.Values.Key | 쿼리된 지표의 이름입니다. 지표의 값은 Values.Value 필드에서 지정됩니다. |
| Rows.Values.Type | Values.Value 필드에 지정된 값의 데이터 유형입니다. |
| Rows.Values.Value | 적용된 필터를 포함하여 쿼리된 지표의 실제 값입니다. |
여정 실행 지표 또는 여정 활동 실행 지표 쿼리에 대한 JSON 응답의 필드에 대한 자세한 내용은 [Amazon Pinpoint 프로젝트, 캠페인 및 여정에 적용되는 표준 지표](analytics-standard-metrics.md) 단원을 참조하십시오.