비동기 커스텀 보고서 API 사용

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. 쿼리를 제출합니다.

2. 쿼리 상태를 가져옵니다.

3. 쿼리 결과를 검색합니다.

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":[  
  {  
    "name":"response_processing_latency",
    "function":"avg",
    "alias":"average_response_time_in_seconds",
    "operator":"/",
    "value":"1000"
  }
]

"timeRange": {
    "start": "2018-07-29T00:13:00Z",
    "end": "2018-08-01T00:18:00Z"
}

필터 표현식 구문

이 참조 섹션에서는 요청 본문에서 필터 표현식을 작성하는 데 사용할 수 있는 토큰을 설명합니다. 예를 들어 다음 표현식에서는 'ge' 토큰(크거나 같음)을 사용합니다.

"filter":"(message_count ge 0)"

(apiproxy in 'ethorapi','weather-api')

(apiproxy in 'ethorapi')

(apiproxy in 'Search','ViewItem')

(response_status_code in 400,401,500,501)

(response_status_code notin 400,401,500,501)

(response_status_code eq 504)

(apiproxy eq 'non-prod')

(response_status_code ne 500)

(apiproxy ne 'non-prod')

(response_status_code gt 500)

(response_status_code lt 500)

(target_response_code ge 400)

(target_response_code le 300)

(apiproxy like '%buy%')

(apiproxy like '%item')

(apiproxy like 'Prod%')

(apiproxy not like '%buy%')

(apiproxy not like '%item')

(apiproxy not like 'Prod%')

(target_response_code gt 399) and (response_status_code ge 400)

(response_size ge 1000) or (response_status_code eq 500)

제약조건 및 기본값

다음은 비동기식 쿼리 처리 기능에 대한 제약조건 및 기본값 목록입니다.

쿼리 결과 정보

다음은 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

요청 본문에서 다음 검색 기준을 지정합니다.

"devCriteria":[{
    "id":"RtHAeZ6LtkSbEH56",
    "orgId":"my_org"}
]

예를 들어 다음 요청은 지정된 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