Keyboard shortcuts

Press ← or → to navigate between chapters

Press ? to show this help

Press Esc to hide this help

객체 속성 집계(Aggregate Objects) (V1)

온톨로지 객체의 속성에 집계 함수를 적용합니다. 선택적인 검색 조건과 그룹화를 함께 지정할 수 있습니다.

위치이름자료형필수 여부의미
경로ontologyRidstring필수온톨로지 RID
경로objectTypestring필수집계할 객체 유형
본문aggregationlist<Aggregation>선택집계 함수 목록
본문querySearchJsonQuery선택집계할 객체를 고르는 조건
본문groupBylist<AggregationGroupBy>선택순서대로 적용할 그룹화 목록

쿼리 매개변수는 없고 AggregateObjectsRequest JSON 본문은 필수입니다. 집계 함수 및 그룹화 계약은 count, min, max, avg, sum, approximateDistinct와 네 가지 그룹 유형의 필수 필드, 기본값 및 null 처리를 설명합니다. query는 SearchJsonQuery를 사용합니다.

예시는 name이 john과 같지 않은 객체를 시작일 범위와 도시로 묶어 tenure의 최솟값과 평균을 계산합니다. 문자열 name 속성에는 전체 용어 일치에 필요한 Selectable 설정을 적용한 가상 구성을 사용합니다.

응답

AggregateObjectsResponse 필드자료형필수 여부의미
excludedItemsinteger선택집계 결과에서 제외된 객체 수
nextPageTokenstring선택페이지 토큰 필드
datalist<AggregateObjectsResponseItem>선택그룹별 결과

각 결과 항목에는 선택적 group: map<string, any>와 metrics: list<AggregationMetricResult>가 있습니다. group은 속성 참조를 그룹값으로 연결합니다. 각 지표의 name 문자열은 필수이며 value는 선택적인 double 수치입니다.

응답 자료형에는 nextPageToken이 있지만 이 V1 요청의 매개변수와 본문에는 pageToken이 정의되어 있지 않습니다. 객체 검색의 페이지 요청 형식을 집계 요청에 그대로 추가하지 않습니다. 그룹 수와 제외 항목은 집계 가이드에 따라 해석합니다.

HTTP 요청

POST /api/v1/ontologies/{ontologyRid}/objects/{objectType}/aggregate

작업 식별자는 v1.aggregateObjects입니다. Authorization: Bearer <접근 토큰> 헤더로 인증합니다. OAuth 클라이언트에는 api:ontologies-read 권한 범위가 필요합니다.

JSON 요청 예시

가상 객체 유형에 대한 요청 예시입니다.

{
  "aggregation": [
    {
      "type": "min",
      "field": "properties.tenure",
      "name": "min_tenure"
    },
    {
      "type": "avg",
      "field": "properties.tenure",
      "name": "avg_tenure"
    }
  ],
  "query": {
    "type": "not",
    "value": {
      "type": "eq",
      "field": "properties.name",
      "value": "john"
    }
  },
  "groupBy": [
    {
      "field": "properties.startDate",
      "type": "ranges",
      "ranges": [
        {
          "gte": "2020-01-01",
          "lt": "2020-06-01"
        }
      ]
    },
    {
      "field": "properties.city",
      "type": "exact"
    }
  ]
}

JSON 응답 예시

가상 객체 유형의 응답 예시입니다.

{
  "data": [
    {
      "metrics": [
        {
          "name": "min_tenure",
          "value": 1
        },
        {
          "name": "avg_tenure",
          "value": 3
        }
      ],
      "group": {
        "properties.startDate": {
          "gte": "2020-01-01",
          "lt": "2020-06-01"
        },
        "properties.city": "New York City"
      }
    },
    {
      "metrics": [
        {
          "name": "min_tenure",
          "value": 2
        },
        {
          "name": "avg_tenure",
          "value": 3
        }
      ],
      "group": {
        "properties.startDate": {
          "gte": "2020-01-01",
          "lt": "2020-06-01"
        },
        "properties.city": "San Francisco"
      }
    }
  ]
}

오류

실패 응답은 공통 API 오류의 형식으로 처리합니다.

요청 예제

FOUNDRY_HOST에는 https://를 제외한 Foundry 호스트를, FOUNDRY_TOKEN에는 유효한 토큰을 환경 변수로 제공합니다. 아래 식별자와 입력값은 예시이므로 실제 요청 대상에 맞게 지정합니다.

cURL

curl -X POST \
	-H "Content-type: application/json" \
	-H "Authorization: Bearer ${FOUNDRY_TOKEN}" \
	"https://${FOUNDRY_HOST}/api/v1/ontologies/ri.ontology.main.ontology.c61d9ab5-2919-4127-a0a1-ac64c0ce6367/objects/employee/aggregate" \
	-d '{"aggregation":[{"type":"min","field":"properties.tenure","name":"min_tenure"},{"type":"avg","field":"properties.tenure","name":"avg_tenure"}],"query":{"type":"not","value":{"type":"eq","field":"properties.name","value":"john"}},"groupBy":[{"field":"properties.startDate","type":"ranges","ranges":[{"gte":"2020-01-01","lt":"2020-06-01"}]},{"field":"properties.city","type":"exact"}]}'

Python

Requests 라이브러리가 설치된 Python 환경에서 사용합니다.

import os
import requests

HOSTNAME = os.environ["FOUNDRY_HOST"]
TOKEN = os.environ["FOUNDRY_TOKEN"]
headers = {
    "content-type": "application/json",
    "authorization": "Bearer {}".format(TOKEN)
}
request_body = {'aggregation': [{'type': 'min', 'field': 'properties.tenure', 'name': 'min_tenure'},
                 {'type': 'avg', 'field': 'properties.tenure', 'name': 'avg_tenure'}],
 'query': {'type': 'not',
           'value': {'type': 'eq', 'field': 'properties.name', 'value': 'john'}},
 'groupBy': [{'field': 'properties.startDate',
              'type': 'ranges',
              'ranges': [{'gte': '2020-01-01', 'lt': '2020-06-01'}]},
             {'field': 'properties.city', 'type': 'exact'}]}

response = requests.post('https://{}/api/v1/ontologies/ri.ontology.main.ontology.c61d9ab5-2919-4127-a0a1-ac64c0ce6367/objects/employee/aggregate'.format(HOSTNAME), headers=headers, json=request_body)
print(response)

Java

Apache HttpClient 4.5 API와 try-with-resources를 사용하는 예제입니다. 클래스 이름에 맞는 AggregateObjectsExample.java 파일에서 사용합니다.

import org.apache.http.client.methods.CloseableHttpResponse;
import org.apache.http.client.methods.HttpPost;
import org.apache.http.impl.client.CloseableHttpClient;
import org.apache.http.impl.client.HttpClientBuilder;
import org.apache.http.entity.ContentType;
import org.apache.http.entity.StringEntity;

public class AggregateObjectsExample {
    public static void main(String[] args) throws Exception {
        String HOSTNAME = System.getenv("FOUNDRY_HOST");
        String TOKEN = System.getenv("FOUNDRY_TOKEN");

        try (CloseableHttpClient httpClient = HttpClientBuilder.create().build()) {
            HttpPost request = new HttpPost("https://" + HOSTNAME + "/api/v1/ontologies/ri.ontology.main.ontology.c61d9ab5-2919-4127-a0a1-ac64c0ce6367/objects/employee/aggregate");
            request.addHeader("content-type", "application/json");
            request.addHeader("authorization", String.format("Bearer %s", TOKEN));
            request.setEntity(new StringEntity("{\"aggregation\":[{\"type\":\"min\",\"field\":\"properties.tenure\",\"name\":\"min_tenure\"},{\"type\":\"avg\",\"field\":\"properties.tenure\",\"name\":\"avg_tenure\"}],\"query\":{\"type\":\"not\",\"value\":{\"type\":\"eq\",\"field\":\"properties.name\",\"value\":\"john\"}},\"groupBy\":[{\"field\":\"properties.startDate\",\"type\":\"ranges\",\"ranges\":[{\"gte\":\"2020-01-01\",\"lt\":\"2020-06-01\"}]},{\"field\":\"properties.city\",\"type\":\"exact\"}]}", ContentType.APPLICATION_JSON));
            try (CloseableHttpResponse response = httpClient.execute(request)) {
                System.out.println(response);
            }
        }
    }
}

JavaScript

fetch를 제공하는 Node.js 환경에서 사용합니다. 서비스 사용자 토큰을 브라우저로 전달하지 않습니다.

const HOSTNAME = process.env.FOUNDRY_HOST;
const TOKEN = process.env.FOUNDRY_TOKEN;

fetch(`https://${HOSTNAME}/api/v1/ontologies/ri.ontology.main.ontology.c61d9ab5-2919-4127-a0a1-ac64c0ce6367/objects/employee/aggregate`, {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${TOKEN}`,
    },
    body: JSON.stringify({
    "aggregation": [
        {
            "type": "min",
            "field": "properties.tenure",
            "name": "min_tenure"
        },
        {
            "type": "avg",
            "field": "properties.tenure",
            "name": "avg_tenure"
        }
    ],
    "query": {
        "type": "not",
        "value": {
            "type": "eq",
            "field": "properties.name",
            "value": "john"
        }
    },
    "groupBy": [
        {
            "field": "properties.startDate",
            "type": "ranges",
            "ranges": [
                {
                    "gte": "2020-01-01",
                    "lt": "2020-06-01"
                }
            ]
        },
        {
            "field": "properties.city",
            "type": "exact"
        }
    ]
})
}).then((response) => {
    console.log(response)
});

PowerShell

$TOKEN = $env:FOUNDRY_TOKEN
$HOSTNAME = $env:FOUNDRY_HOST

$headers = @{
    "authorization" = "Bearer $TOKEN"
}

$response = Invoke-WebRequest -Uri "https://$HOSTNAME/api/v1/ontologies/ri.ontology.main.ontology.c61d9ab5-2919-4127-a0a1-ac64c0ce6367/objects/employee/aggregate" `
	-Method Post `
	-Headers $headers `
	-ContentType application/json `
	-Body '{"aggregation":[{"type":"min","field":"properties.tenure","name":"min_tenure"},{"type":"avg","field":"properties.tenure","name":"avg_tenure"}],"query":{"type":"not","value":{"type":"eq","field":"properties.name","value":"john"}},"groupBy":[{"field":"properties.startDate","type":"ranges","ranges":[{"gte":"2020-01-01","lt":"2020-06-01"}]},{"field":"properties.city","type":"exact"}]}'

$response.content