시계열 지점 스트리밍(Stream Points) (V2)

객체 시계열 속성의 지점을 스트리밍합니다. 절대 또는 상대 시간 범위를 지정하고 필요하면 집계를 적용합니다.

출력 형식의 기본값은 JSON입니다. 큰 응답을 스트리밍할 때는 format=ARROW가 더 효율적입니다. 요청 본문은 출력 형식과 관계없이 JSON을 사용합니다.

HTTP 요청

POST /api/v2/ontologies/{ontology}/objects/{objectType}/{primaryKey}/timeseries/{property}/streamPoints

작업 식별자는 v2.streamPoints입니다. OAuth2로 호출하는 타사 애플리케이션에는 api:ontologies-read 권한 범위가 필요합니다. 각 요청에 Authorization: Bearer <접근 토큰>을 전달합니다.

경로 매개변수

쿼리 매개변수

요청 본문

본문 형식은 StreamTimeSeriesPointsRequest이며 필수입니다.

range의 구조

시간 범위의 형식을 사용합니다.

aggregate의 구조

집계 설정의 함수와 전략을 지정합니다.

현재 시각을 기준으로 5개월 전부터 1개월 전까지 조회하는 요청 본문입니다.

{
  "range": {
    "type": "relative",
    "startTime": {
      "when": "BEFORE",
      "value": 5,
      "unit": "MONTHS"
    },
    "endTime": {
      "when": "BEFORE",
      "value": 1,
      "unit": "MONTHS"
    }
  }
}

응답

응답은 선택한 JSON 또는 ARROW 형식의 바이너리 스트림입니다. 예제는 본문을 바이트 그대로 파일에 기록합니다.

개별 오류

오류 응답 처리는 공통 API 오류 계약을 따릅니다.

요청 예제

FOUNDRY_HOST에는 https://를 제외한 호스트, FOUNDRY_TOKEN에는 유효한 토큰을 제공합니다. 예시 객체와 performance 속성은 실제 조회 대상에 맞춰 바꿉니다. SERIES_OUTPUT_FILE은 응답 바이트를 저장할 파일 경로입니다. 기존 파일을 덮어씁니다.

Stream Points의 format을 생략하면 JSON입니다. ARROW가 필요하면 해당 요청 URL에 ?format=ARROW를 지정합니다.

cURL

curl --fail --output "${SERIES_OUTPUT_FILE}" -X POST \
	-H "Content-type: application/json" \
	-H "Authorization: Bearer ${FOUNDRY_TOKEN}" \
	"https://${FOUNDRY_HOST}/api/v2/ontologies/palantir/objects/employee/50030/timeseries/performance/streamPoints" \
	-d '{"range":{"type":"relative","startTime":{"when":"BEFORE","value":5,"unit":"MONTHS"},"endTime":{"when":"BEFORE","value":1,"unit":"MONTHS"}}}'

Python

Requests 라이브러리가 필요합니다.

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 = {
    "range": {
        "type": "relative",
        "startTime": {
            "when": "BEFORE",
            "value": 5,
            "unit": "MONTHS"
        },
        "endTime": {
            "when": "BEFORE",
            "value": 1,
            "unit": "MONTHS"
        }
    }
}

with requests.post('https://{}/api/v2/ontologies/palantir/objects/employee/50030/timeseries/performance/streamPoints'.format(HOSTNAME), headers=headers, json=request_body, stream=True) as response:
    response.raise_for_status()
    with open(os.environ["SERIES_OUTPUT_FILE"], "wb") as output:
        for chunk in response.iter_content(chunk_size=1024 * 1024):
            output.write(chunk)

Java

Apache HttpClient 4.5 API를 사용하는 StreamPointsExample.java 예제입니다.

import java.io.IOException;
import java.io.OutputStream;
import java.nio.file.Files;
import java.nio.file.Paths;
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 StreamPointsExample {
    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/v2/ontologies/palantir/objects/employee/50030/timeseries/performance/streamPoints");
            request.addHeader("content-type", "application/json");
            request.addHeader("authorization", String.format("Bearer %s", TOKEN));
            request.setEntity(new StringEntity("{\"range\":{\"type\":\"relative\",\"startTime\":{\"when\":\"BEFORE\",\"value\":5,\"unit\":\"MONTHS\"},\"endTime\":{\"when\":\"BEFORE\",\"value\":1,\"unit\":\"MONTHS\"}}}", ContentType.APPLICATION_JSON));
            try (CloseableHttpResponse response = httpClient.execute(request)) {
                int status = response.getStatusLine().getStatusCode();
                if (status < 200 || status >= 300) throw new IOException("HTTP " + status);
                try (OutputStream output = Files.newOutputStream(Paths.get(System.getenv("SERIES_OUTPUT_FILE")))) {
                    response.getEntity().writeTo(output);
                }
            }
        }
    }
}

JavaScript

fetch와 Web Streams를 지원하는 Node.js에서 ES 모듈(.mjs)로 실행합니다.

import { createWriteStream } from "node:fs";
import { Readable } from "node:stream";
import { pipeline } from "node:stream/promises";

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

const response = await fetch(`https://${HOSTNAME}/api/v2/ontologies/palantir/objects/employee/50030/timeseries/performance/streamPoints`, {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${TOKEN}`,
    },
    body: '{"range":{"type":"relative","startTime":{"when":"BEFORE","value":5,"unit":"MONTHS"},"endTime":{"when":"BEFORE","value":1,"unit":"MONTHS"}}}'
 });
if (!response.ok) {
    await response.body?.cancel();
    throw new Error(`HTTP ${response.status}`);
}
await pipeline(Readable.fromWeb(response.body), createWriteStream(process.env.SERIES_OUTPUT_FILE));

PowerShell

$ErrorActionPreference = 'Stop'
$TOKEN = $env:FOUNDRY_TOKEN
$HOSTNAME = $env:FOUNDRY_HOST

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

Invoke-WebRequest -Uri "https://$HOSTNAME/api/v2/ontologies/palantir/objects/employee/50030/timeseries/performance/streamPoints" `
	-Method Post `
	-Headers $headers `
	-ContentType application/json `
	-Body "{`"range`":{`"type`":`"relative`",`"startTime`":{`"when`":`"BEFORE`",`"value`":5,`"unit`":`"MONTHS`"},`"endTime`":{`"when`":`"BEFORE`",`"value`":1,`"unit`":`"MONTHS`"}}}" `
    -OutFile $env:SERIES_OUTPUT_FILE