Apigee Edge 문서입니다.
Apigee X 문서로 이동 정보
Edge 애널리틱스는 풍부한 대화형 대시보드, 맞춤 보고서 생성기, 관련 기능을 제공합니다. 하지만 이러한 기능은 대화형입니다. 즉, API 또는 UI 요청을 제출하면 애널리틱스 서버가 응답을 제공할 때까지 요청이 차단됩니다.
하지만 분석 요청은 완료하는 데 시간이 너무 오래 걸릴 수 있습니다. 쿼리 요청이 많은 양의 데이터 (예: 100GB)를 처리해야 하는 경우 타임아웃으로 인해 작업이 실패할 수 있습니다.
비동기식 쿼리 처리를 사용하면 매우 큰 데이터 세트를 쿼리하고 나중에 결과를 검색할 수 있습니다. 양방향 쿼리가 시간 초과되면 오프라인 쿼리를 사용해 보세요. 다음은 비동기식 쿼리 처리가 좋은 대안이 될 수 있는 경우입니다.
- 여러 시간 간격에 걸친 보고서를 분석하고 만드는 경우
- 쿼리를 복잡하게 만드는 다양한 그룹화 측정기준과 기타 제약조건으로 데이터를 분석하는 경우
- 일부 사용자 또는 조직에 대한 데이터 볼륨이 현저히 높아진 때 쿼리를 관리하는 경우
이 문서에서는 API를 사용하여 비동기 쿼리를 시작하는 방법에 대해 설명합니다. 커스텀 보고서 실행에 설명된 대로 UI를 사용할 수도 있습니다.
보고서 API와 UI 비교
커스텀 보고서 만들기 및 관리는 Edge UI를 사용하여 커스텀 보고서를 만들고 실행하는 방법을 자세히 설명합니다. 이러한 보고서를 동기식 또는 비동기식으로 실행할 수 있습니다.
UI를 사용하여 커스텀 보고서를 생성하는 대부분의 개념은 API를 사용하는 데 적용됩니다. 즉, API를 사용하여 커스텀 보고서를 만들 때 Edge에 내장된 측정항목, 측정기준, 필터와 StatisticsCollector 정책을 사용하여 만든 커스텀 측정항목을 지정합니다.
UI에서 생성된 보고서와 API에서 생성된 보고서 간의 주요 차이는, API로 생성된 보고서는 UI에 표시된 시각적 보고서 대신 CSV 또는 JSON(줄바꿈으로 구분됨) 파일에 기록된다는 점입니다.
Apigee Hybrid 제한사항
Apigee Hybrid는 결과 데이터 세트에 30MB 크기 제한을 적용합니다.
비동기 분석 쿼리를 실행하는 방법
다음 세 단계로 비동기 분석 쿼리를 수행합니다.
1단계: 쿼리 제출
/queries API에 POST 요청을 보냅니다. 이 API는 Edge에 백그라운드에서 요청을 처리하도록 지시합니다. 쿼리 제출이 성공하면 API는 201 상태 및 이후 단계에서 쿼리를 참조하는 데 사용할 ID를 반환합니다.
예를 들면 다음과 같습니다.
curl -X POST -H "Content-Type:application/json" https://api.enterprise.apigee.com/v1/organizations/myorg/environments/myenv/queries -d @json-query-file -u orgAdminEmail:password
요청 본문은 쿼리의 JSON 설명입니다. JSON 본문에서 보고서를 정의하는 측정항목, 측정기준, 필터를 지정합니다.
다음은 json-query-file 파일의 예시입니다.
{
"metrics": [
{
"name": "message_count",
"function": "sum",
"alias": "sum_txn"
}
],
"dimensions": ["apiproxy"],
"timeRange": "last24hours",
"limit": 14400,
"filter":"(message_count ge 0)"
}
요청 본문 구문에 대한 자세한 설명은 아래의 요청 본문 정보를 참조하세요.
샘플 응답:
9cfc0d85-0f30-46d6-ae6f-318d0cb961bd 쿼리 ID가 응답에 포함됩니다. HTTP 상태 201 외에도 enqueued의 state는 요청이 성공했음을 나타냅니다.
HTTP/1.1 201 Created
{
"self":"/organizations/myorg/environments/myenv/queries/9cfc0d85-0f30-46d6-ae6f-318d0cb961bd",
"created":"2018-05-10T07:11:10Z",
"state":"enqueued",
"error":"false",
}
2단계: 쿼리 상태 가져오기
GET 호출을 실행하여 쿼리의 상태를 요청합니다. POST 호출에서 반환된 쿼리 ID를 제공합니다. 예를 들면 다음과 같습니다.
curl -X GET -H "Content-Type:application/json" https://api.enterprise.apigee.com/v1/organizations/myorg/environments/myenv/queries/9cfc0d85-0f30-46d6-ae6f-318d0cb961bd -u email:password
샘플 응답:
쿼리가 아직 진행 중이면 state가 running인 다음과 같은 응답이 반환됩니다.
{
"self": "/organizations/myorg/environments/myenv/queries/1577884c-4f48-4735-9728-5da4b05876ab",
"state": "running",
"created": "2018-02-23T14:07:27Z",
"updated": "2018-02-23T14:07:54Z"
}
쿼리가 완료되면 다음과 같은 응답이 표시됩니다. 여기서 state가 completed로 설정됩니다.
{
"self": "/organizations/myorg/environments/myenv/queries/9cfc0d85-0f30-46d6-ae6f-318d0cb961bd",
"state": "completed",
"result": {
"self": "/organizations/myorg/environments/myenv/queries/9cfc0d85-0f30-46d6-ae6f-318d0cb961bd/result",
"expires": "2017-05-22T14:56:31Z"
},
"resultRows": 1,
"resultFileSize": "922KB",
"executionTime": "11 sec",
"created": "2018-05-10T07:11:10Z",
"updated": "2018-05-10T07:13:22Z"
}
3단계: 쿼리 결과 검색
쿼리 상태가 completed 상태가 되면 결과 가져오기 API를 사용하여 결과를 검색할 수 있습니다. 여기서 쿼리 ID는 다시 9cfc0d85-0f30-46d6-ae6f-318d0cb961bd입니다.
curl -X GET -H "Content-Type:application/json" -O -J https://api.enterprise.apigee.com/v1/organizations/myorg/environments/myenv/queries/9cfc0d85-0f30-46d6-ae6f-318d0cb961bd/result -u email:password
다운로드한 파일을 검색하려면 다운로드한 파일을 시스템에 저장하도록 사용 도구를 구성해야 합니다. 예를 들면 다음과 같습니다.
cURL을 사용하는 경우 위에 표시된 대로
-O -J옵션을 사용할 수 있습니다.Postman을 사용하는 경우 저장 및 다운로드 버튼을 선택해야 합니다. 이 경우
response라는 ZIP 파일이 다운로드됩니다.Chrome 브라우저를 사용하는 경우 자동으로 다운로드가 허용됩니다.
요청이 성공하고 0이 아닌 결과 집합이 있으면 결과가 압축된 JSON(줄바꿈으로 구분됨) 파일로 클라이언트에 다운로드됩니다. 다운로드한 파일의 이름은 다음과 같습니다.
OfflineQueryResult-<query-id>.zip
예를 들면 다음과 같습니다.
OfflineQueryResult-9cfc0d85-0f30-46d6-ae6f-318d0cb961bd.zip
zip 파일에는 JSON 결과의 .gz 보관 파일이 들어 있습니다. JSON 파일에 액세스하려면 다운로드 파일의 압축을 푼 다음 gzip 명령어를 사용하여 JSON 파일을 추출합니다.
unzip OfflineQueryResult-9cfc0d85-0f30-46d6-ae6f-318d0cb961bd.zip
gzip -d QueryResult-9cfc0d85-0f30-46d6-ae6f-318d0cb961bd-000000000000.json.gz요청 본문 정보
이 섹션에서는 쿼리의 JSON 요청 본문에서 사용할 수 있는 각 매개변수를 설명합니다. 쿼리에서 사용할 수 있는 측정항목 및 측정기준에 대한 자세한 내용은 분석 참조를 확인하세요.
{ "metrics":[ { "name":"metric_name", "function":"aggregation_function", "alias":"metric_dispaly_name_in_results", "operator":"post_processing_operator", "value":"post_processing_operand" }, ... ], "dimensions":[ "dimension_name", ... ], "timeRange":"time_range", "limit":results_limit, "filter":"filter", "groupByTimeUnit": "grouping", "outputFormat": "format", "csvDelimiter": "delimiter" }
| 속성 | 설명 | 필수 여부 |
|---|---|---|
metrics
|
측정항목의 배열입니다. 각 측정항목이 포함된 쿼리에 측정항목을 하나 이상 지정할 수 있습니다. 측정항목 이름만 필요합니다.
"metrics":[
{
"name":"response_processing_latency",
"function":"avg",
"alias":"average_response_time_in_seconds",
"operator":"/",
"value":"1000"
}
]자세한 내용은 애널리틱스 측정항목, 측정기준, 필터 참조를 참조하세요. |
아니요 |
dimensions
|
측정항목을 그룹화하는 측정기준의 배열입니다. 자세한 내용은 지원되는 측정기준 목록을 참조하세요. 여러 측정기준을 지정할 수 있습니다. | N |
timeRange
|
쿼리의 시간 범위입니다.
다음과 같은 사전 정의된 문자열을 사용하여 시간 범위를 지정할 수 있습니다.
또는 "timeRange": {
"start": "2018-07-29T00:13:00Z",
"end": "2018-08-01T00:18:00Z"
} |
예 |
limit
|
결과에서 반환될 수 있는 최대 행 수입니다. | 아니요 |
filter
|
데이터를 필터링하는 데 사용할 수 있는 부울 표현식입니다. 필터 표현식은 AND/OR 용어를 사용하여 결합될 수 있으며 모호성을 피하기 위해 완전히 괄호로 묶어야 합니다. 필터링할 수 있는 필드에 대한 자세한 내용은 애널리틱스 측정항목, 측정기준, 필터 참조를 확인하세요. 필터 표현식을 작성하는 데 사용하는 토큰에 대한 자세한 내용은 필터 표현식 구문을 참조하세요. | 아니요 |
groupByTimeUnit
|
결과 집합을 그룹화하는 데 사용되는 시간 단위입니다. 유효한 값은 second, minute, hour, day, week 또는 month입니다.
쿼리에 |
아니요 |
outputFormat
|
출력 형식이며, 유효한 값은 csv 또는 json입니다. 줄바꿈으로 구분된 JSON에 해당하는 기본값은 json입니다.
참고: |
아니요 |
csvDelimiter
|
outputFormat이 csv로 설정된 경우 CSV 파일에 사용되는 구분 기호입니다. 기본값은 쉼표(,) 문자입니다. 지원되는 구분 기호 문자는 쉼표(,), 파이프(|), 탭(\t)입니다.
|
아니요 |
필터 표현식 구문
이 참조 섹션에서는 요청 본문에서 필터 표현식을 작성하는 데 사용할 수 있는 토큰을 설명합니다. 예를 들어 다음 표현식에서는 'ge' 토큰(크거나 같음)을 사용합니다.
"filter":"(message_count ge 0)"
| 토큰 | 설명 | 예 |
|---|---|---|
in
|
목록에 포함 | (apiproxy in 'ethorapi','weather-api') (apiproxy in 'ethorapi') (apiproxy in 'Search','ViewItem') (response_status_code in 400,401,500,501) 참고: 문자열은 따옴표로 묶어야 합니다. |
notin
|
목록에서 제외 | (response_status_code notin 400,401,500,501) |
eq
|
다음과 같음 (==)
|
(response_status_code eq 504) (apiproxy eq 'non-prod') |
ne
|
같지 않음 (!=)
|
(response_status_code ne 500) (apiproxy ne 'non-prod') |
gt
|
보다 큼 (>)
|
(response_status_code gt 500) |
lt
|
보다 작음 (<)
|
(response_status_code lt 500) |
ge
|
이상 (>=)
|
(target_response_code ge 400) |
le
|
작거나 같음 (<=)
|
(target_response_code le 300) |
like
|
문자열 패턴이 제공된 패턴과 일치하면 true를 반환합니다.
오른쪽의 예시는 다음과 같습니다. - 'buy'라는 단어가 포함된 모든 값 - 'item'으로 끝나는 모든 값 - 'Prod'로 시작하는 모든 값 - 4로 시작하는 모든 값(response_status_code는 숫자)
|
(apiproxy like '%buy%') (apiproxy like '%item') (apiproxy like 'Prod%') |
not like
|
문자열 패턴이 제공된 패턴과 일치하면 false를 반환합니다. | (apiproxy not like '%buy%') (apiproxy not like '%item') (apiproxy not like 'Prod%') |
and
|
'and' 논리를 사용하여 두 개 이상의 필터 표현식을 포함할 수 있습니다. 필터에는 모든 조건을 충족하는 데이터가 포함됩니다. | (target_response_code gt 399) and (response_status_code ge 400) |
or
|
'or' 논리를 사용하여 가능한 여러 필터 표현식을 평가할 수 있습니다. 필터에는 조건 중 하나 이상을 충족하는 데이터가 포함됩니다. | (response_size ge 1000) or (response_status_code eq 500) |
제약조건 및 기본값
다음은 비동기식 쿼리 처리 기능에 대한 제약조건 및 기본값 목록입니다.
| 제약조건 | 기본값 | 설명 |
|---|---|---|
| 쿼리 호출 한도 | 설명 참조 | /queries 관리 API를 시간당 최대 7번 호출하여 비동기 보고서를 시작할 수 있습니다. 호출 할당량을 초과하면 API는 HTTP 429 응답을 반환합니다. |
| 활성 쿼리 한도 | 10 | 조직/환경의 활성 쿼리는 최대 10개까지 가능합니다. |
| 쿼리 실행 시간 기준 | 6시간 | 6시간보다 오래 걸리는 쿼리는 종료됩니다. |
| 쿼리 시간 범위 | 설명 참조 | 쿼리에 허용되는 최대 시간 범위는 365일입니다. |
| 측정기준 및 측정항목 제한 | 25 | 쿼리 페이로드에 지정할 수 있는 측정기준 및 측정항목의 최대 수입니다. |
쿼리 결과 정보
다음은 JSON 형식의 예시입니다. 출력은 새 줄 구분 기호로 구분된 JSON 행으로 구성됩니다.
{"message_count":"10209","apiproxy":"guest-auth-v3","hour":"2018-08-07 19:26:00 UTC"}
{"message_count":"2462","apiproxy":"carts-v2","hour":"2018-08-06 13:16:00 UTC"}
…
저장소의 데이터가 만료될 때까지 URL에서 결과를 가져올 수 있습니다. 제약조건 및 기본값을 참조하세요.
예
예시 1: 메시지 수 합계
지난 60분 동안의 메시지 수 합계를 쿼리합니다.
쿼리
curl -X POST -H "Content-Type: application/json" -H "Accept: application/json" https://api.enterprise.apigee.com/v1/organizations/myorg/environments/test/queries" -d @last60minutes.json -u orgAdminEmail:password
last60minutes.json의 요청 본문
{
"metrics":[
{
"name":"message_count",
"function":"sum"
}
],
"dimensions":[
"apiproxy"
],
"groupByTimeUnit":"minute",
"limit":1000,
"timeRange":"last60minutes"
}
예시 2: 커스텀 기간
커스텀 기간을 사용하여 쿼리합니다.
쿼리
curl -X POST -H "Content-Type: application/json" -H "Accept: application/json" https://api.enterprise.apigee.com/v1 /organizations/myorg/environments/test/queries" -d @last60minutes.json -u orgAdminEmail:password
last60minutes.json의 요청 본문
{
"metrics":[
{
"name":"message_count",
"function":"sum"
},
{
"name":"total_response_time",
"function":"avg",
"alias":"average_response_time"
}
],
"dimensions":[
"apiproxy"
],
"groupByTimeUnit":"minute",
"limit":1000,
"timeRange":{
"start":"2018-11-01T11:00:00Z",
"end":"2018-11-30T11:00:00Z"
}
}
예시 3: 분당 트랜잭션
분당 트랜잭션(tpm)의 측정항목에 대한 쿼리입니다.
쿼리
curl -X POST -H "Content-Type: application/json" -H "Accept: application/json" https://api.enterprise.apigee.com/v1/organizations/myorg/environments/test/queries" -d @tpm.json -u orgAdminEmail:password
tpm.json의 요청 본문
{
"metrics":[
{
"name":"tpm"
}
],
"dimensions":[
"apiproxy"
],
"groupByTimeUnit":"minute",
"limit":1000,
"timeRange":{
"start":"2018-07-01T11:00:00Z",
"end":"2018-07-30T11:00:00Z"
}
}
샘플 결과
결과 파일에서 발췌:
{"tpm":149995.0,"apiproxy":"proxy_1","minute":"2018-07-06 12:16:00 UTC"}
{"tpm":149998.0,"apiproxy":"proxy_1","minute":"2018-07-09 15:12:00 UTC"}
{"tpm":3.0,"apiproxy":"proxy_2","minute":"2018-07-11 16:18:00 UTC"}
{"tpm":148916.0,"apiproxy":"proxy_1","minute":"2018-07-15 17:14:00 UTC"}
{"tpm":150002.0,"apiproxy":"proxy_1","minute":"2018-07-18 18:11:00 UTC"}
...예시 4: 필터 표현식 사용
부울 연산자를 사용하는 필터 표현식을 사용하여 쿼리합니다.
쿼리
curl -X POST -H "Content-Type:application/json" https://api.enterprise.apigee.com/v1/organizations/myorg/environments/test/queries" -d @filterCombo.json -u orgAdminEmail:password
filterCombo.json의 요청 본문
{
"metrics":[
{
"name":"message_count",
"function":"sum"
},
{
"name":"total_response_time",
"function":"avg",
"alias":"average_response_time"
}
],
"filter":"(apiproxy ne \u0027proxy_1\u0027) and (apiproxy ne \u0027proxy_2\u0027)",
"dimensions":[
"apiproxy"
],
"groupByTimeUnit":"minute",
"limit":1000,
"timeRange":{
"start":"2018-11-01T11:00:00Z",
"end":"2018-11-30T11:00:00Z"
}
}
예시 5: 측정항목 매개변수에서 표현식 전달
측정항목 매개변수의 일부로 전달되는 표현식을 사용하여 쿼리합니다. 간단한 단일 연산자 표현식만 사용할 수 있습니다.
쿼리
curl -X POST -H "Content-Type:application/json" https://api.enterprise.apigee.com/v1/organizations/myorg/environments/test/queries" -d @metricsExpression.json -u orgAdminEmail:password
metricsExpression.json의 요청 본문
{
"metrics":[
{
"name":"message_count",
"function":"sum",
"operator":"/",
"value":"7"
}
],
"dimensions":[
"apiproxy"
],
"groupByTimeUnit":"minute",
"limit":10,
"timeRange":"last60minutes"
}
비동기 수익 창출 보고서 쿼리 작성 방법
이 섹션에 설명된 단계에 따라 특정 기준에 따라 지정된 기간 내에 성공적으로 이루어진 모든 수익 창출 거래를 캡처할 수 있습니다.
비동기 분석 쿼리와 마찬가지로 3단계, 즉 (1) 쿼리를 제출하고 (2) 쿼리 상태를 가져오고 (3) 쿼리 결과를 검색하여 비동기 수익 창출 보고서 쿼리를 만듭니다.
1단계인 쿼리 제출은 아래에 설명되어 있습니다.
2단계와 3단계는 비동기 분석 쿼리의 경우와 정확히 동일합니다. 자세한 내용은 비동기 분석 쿼리를 실행하는 방법을 참고하세요.
비동기 수익 창출 보고서에 대한 쿼리를 제출하려면 /mint/organizations/org_id/async-reports에 POST 요청을 실행합니다.
원하는 경우 environment 쿼리 매개변수를 전달하여 환경을 지정할 수 있습니다. 지정되지 않은 경우 쿼리 매개변수의 기본값은 prod입니다. 예를 들면 다음과 같습니다.
/mint/organizations/org_id/async-reports?environment=prod
요청 본문에서 다음 검색 기준을 지정합니다.
| Name | 설명 | 기본 | 필수 여부 |
appCriteria |
보고서에 포함할 특정 애플리케이션의 ID 및 조직입니다. 이 속성을 지정하지 않으면 모든 애플리케이션이 보고서에 포함됩니다. | 해당 없음 | N |
billingMonth |
보고서의 결제 월(예: 7월). | 해당 없음 | 예 |
billingYear |
보고서의 결제 연도(예: 2015년). | 해당 없음 | 예 |
currencyOption |
보고서의 통화입니다. 유효한 값은 다음과 같습니다.
EUR, GBP 또는 USD를 선택하면 거래 날짜에 적용된 환율을 기준으로 해당 통화를 사용하는 모든 거래가 보고서에 표시됩니다. |
해당 없음 | N |
devCriteria
|
보고서에 포함할 특정 개발자의 개발자 ID 또는 이메일 주소, 조직 이름 이 속성을 지정하지 않으면 모든 개발자가 보고서에 포함됩니다. 예: "devCriteria":[{
"id":"RtHAeZ6LtkSbEH56",
"orgId":"my_org"}
] |
해당 없음 | N |
fromDate
|
보고서의 시작 날짜(UTC)입니다. | 해당 없음 | 예 |
monetizationPakageIds |
보고서에 포함할 API 패키지의 ID입니다. 이 속성을 지정하지 않으면 모든 API 패키지가 보고서에 포함됩니다. | 해당 없음 | N |
productIds
|
보고서에 포함할 하나 이상의 API 제품의 ID입니다. 이 속성을 지정하지 않으면 모든 API 제품이 보고서에 포함됩니다. | 해당 없음 | N |
ratePlanLevels |
보고서에 포함할 요금제 유형입니다. 유효한 값으로 다음이 포함되어 있습니다.
이 속성을 지정하지 않으면 개발자별 요금제와 표준 요금제가 모두 보고서에 포함됩니다. |
해당 없음 | N |
toDate
|
보고서의 종료일(UTC)입니다. | 해당 사항 없음 | 예 |
예를 들어 다음 요청은 지정된 API 제품 및 개발자 ID에 대한 2017년 6월의 비동기 수익 창출 보고서를 생성합니다. 보고서 fromDate, toDate 날짜 및 시간은 UTC/GMT 기준이며 시간을 포함할 수 있습니다.
curl -H "Content-Type:application/json" -X POST -d \
'{
"fromDate":"2017-06-01 00:00:00",
"toDate":"2017-06-30 00:00:00",
"productIds": [
"a_product"
],
"devCriteria": [{
"id": "AbstTzpnZZMEDwjc",
"orgId": "myorg"
}]
}' \
"https://api.enterprise.apigee.com/v1/mint/organizations/myorg/async-reports?environment=prod" \
-u orgAdminEmail:password