스크립트 개발 / 커넥터 객체 `DFF.CONN` / DataKit, DataWay

DataKit, DataWay 커넥터 작업 객체는 주로 데이터 쓰기 메서드를 제공합니다.

DFF.CONN(...) 매개변수는 다음과 같습니다:

DataKitDataWay

매개변수	유형	필수 / 기본값	설명
`connector_id`	str	필수	커넥터 ID
`source`	str	`None`	커넥터 Source 재정의 혼동을 피하기 위해 `"mysql"` 등의 수집기 이름을 입력하지 마십시오
`timeout`	int/float	`10`	현재 작업 객체의 기본 HTTP 요청 타임아웃(초)
`split_size`	int	`100`	라인 프로토콜 일괄 쓰기 시 요청당 데이터 포인트 수

매개변수	유형	필수 / 기본값	설명
`connector_id`	str	필수	커넥터 ID
`token`	str	`None`	커넥터 Token 재정의
`timeout`	int/float	`10`	현재 작업 객체의 기본 HTTP 요청 타임아웃(초)
`split_size`	int	`100`	라인 프로토콜 일괄 쓰기 시 요청당 데이터 포인트 수

일반적인 데이터 보고에는 .write_by_category(...), .write_by_category_many(...) 메서드를 사용하십시오
일반적으로 DQL 문을 실행하려면 .query(...) 메서드를 사용하십시오
GET 요청을 직접 보내려면 .get(...) 메서드를 사용하십시오
POST 요청을 직접 보내려면 .post_json(...) 메서드를 사용하십시오
라인 프로토콜 데이터를 직접 보내려면 .post_line_protocol(...) 메서드를 사용하십시오

이 커넥터는 본질적으로 HTTP 요청의 캡슐화입니다

DataKit과 DataWay의 대부분의 인터페이스는 완전히 동일합니다.

DataKit, DataWay 인터페이스가 자주 변경되므로 본 커넥터는 모든 인터페이스를 일대일로 캡슐화하지 않습니다.

DataKit, DataWay의 서로 다른 버전에서는 보고 데이터에 대해 서로 다른 요구 사항이나 제약이 있을 수 있으므로 관련 문서를 읽은 후 본 커넥터를 사용하십시오.

자세한 문서는 다음을 참조하십시오:

TrueWatch 문서 / DataKit

`.write_by_category(...)`

DataKit, DataWay에 특정 유형의 데이터를 씁니다. 매개변수는 다음과 같습니다:

매개변수	유형	필수 / 기본값	설명
`category`	str	필수	데이터 유형. 자세한 내용은 TrueWatch 문서 / DataKit API 참조
`measurement`	str	필수	지표 세트 이름
`tags`	dict	`None`	태그. 키 이름과 키 값은 모두 문자열이어야 합니다
`fields`	dict	필수	지표. 키 이름은 반드시 문자열이어야 합니다. 값은 문자열, 정수, 부동소수점, 불리언 또는 요소 유형이 일치하는 위 유형들의 목록일 수 있습니다
`timestamp`	int/long/float	{현재 시간}	타임스탬프. 초/밀리초/마이크로초/나노초를 지원합니다
`headers`	dict	`None`	요청 Header 매개변수
`timeout`	int/float	`None`	이번 요청의 타임아웃 시간. 생략 시 작업 객체의 기본값을 사용합니다

headers 매개변수는 3.3.0에서 추가되었습니다

예시
tags   = { 'host': 'web-01' }
fields = { 'cpu' : 10 }
status_code, result = datakit.write_by_category(category='metric', measurement='호스트 모니터링', tags=tags, fields=fields)

`.write_by_category_many(...)`

write_by_category(...)의 일괄 버전입니다. 매개변수는 다음과 같습니다:

매개변수	유형	필수 / 기본값	설명
`category`	str	필수	데이터 유형. 자세한 내용은 TrueWatch 문서 / DataKit API 참조
`data`	list	필수	데이터 포인트 목록
`data[#].measurement`	str	필수	지표 세트 이름
`data[#].tags`	dict	`None`	태그. 키 이름과 키 값은 모두 문자열이어야 합니다
`data[#].fields`	dict	필수	지표. 키 이름은 문자열이어야 하며, 값은 문자열, 정수, 부동소수점, 부울 값 또는 요소 유형이 일치하는 위 유형들의 리스트일 수 있습니다
`data[#].timestamp`	int/long/float	{현재 시간}	타임스탬프. 초/밀리초/마이크로초/나노초를 지원합니다
`headers`	dict	`None`	요청 Header 매개변수
`timeout`	int/float	`None`	이번 요청의 타임아웃 시간. 생략 시 작업 객체의 기본값을 사용합니다

headers 매개변수는 3.3.0에서 추가되었습니다

예시
data = [
    {
        'measurement': '호스트 모니터링',
        'tags'       : { 'host' : 'web-01' },
        'fields'     : { 'value': 10 }
    },
    {
        'measurement': '호스트 모니터링',
        'tags'       : { 'host' : 'web-02' },
        'fields'     : { 'value': 20 }
    }
]
status_code, result = datakit.write_by_category_many(category='metric', data=data)

`.write_metric(...)` / `.write_point(...)`

..write_metric(...)는 .write_by_category(category='metric', ...)와 동등합니다. .write_point(...)는 이전 버전 호환 별칭입니다.

예시
status_code, result = datakit.write_metric(measurement='호스트 모니터링', tags={'host': 'web-01'}, fields={'cpu': 10})

`.write_metric_many(...)` / `.write_metrics(...)` / `.write_points(...)`

..write_metric_many(...)는 .write_by_category_many(category='metric', ...)와 동등합니다. .write_metrics(...)와 .write_points(...)는 이전 버전 호환 별칭입니다.

예시
data = [
    {
        'measurement': '호스트 모니터링',
        'tags'       : { 'host' : 'web-01' },
        'fields'     : { 'value': 10 }
    },
    {
        'measurement': '호스트 모니터링',
        'tags'       : { 'host' : 'web-02' },
        'fields'     : { 'value': 20 }
    }
]
status_code, result = datakit.write_metrics(data=data)

`.write_logging(...)` / `.write_logging_many(...)`

.write_logging(...)는 .write_by_category(category='logging', ...)와 동등합니다. .write_logging_many(...)는 이에 대응하는 일괄 버전입니다.

`.query(...)`

이 메서드는 DataKit, DataWay API DQL 쿼리 인터페이스의 매개변수를 지원합니다

자세한 문서는 TrueWatch 문서 / DataKit API 문서에서 확인하세요.

이 메서드는 단지 HTTP 요청의 래퍼일 뿐입니다

이 메서드는 본질적으로 DataKit, DataWay에 HTTP 요청을 보낼 뿐이며, 반환 내용은 DataKit, DataWay 및 백엔드 데이터 소스에 따라 달라집니다.

반환 결과에 대해 의문이 있다면 requests를 사용하여 DataKit, DataWay에 직접 요청을 보내볼 수 있습니다:

requests를 사용한 API 호출
def query():
    domain = '<Domain>'
    token  = '<Token>'

    url = f'https://{domain}/v1/query/raw?token={token}'
    body = {
        'queries': [
            {
                # DQL 문
                'query': 'M::`cpu`:(`load5s`) BY `host`',

                # 최근 1시간
                'time_range': [
                    _DFF_TRIGGER_TIME_MS - 3600 * 1000,
                    _DFF_TRIGGER_TIME_MS,
                ],
            }
        ],
        'token': token
    }

    resp = requests.post(url, json=body)
    print(resp.status_code)
    print(resp.text)

DataKit, DataWay를 통해 DQL 문을 실행합니다. 매개변수는 다음과 같습니다.

매개변수	유형	필수 / 기본값	설명
`dql`	str	필수	DQL 문
`dict_output`	bool	`False`	데이터를 `dict`로 자동 변환할지 여부.
`raw`	bool	`False`	원시 응답을 반환할지 여부. 활성화하면 `dict_output` 매개변수가 무효화됩니다.
`all_series`	bool	`False`	`slimit` 및 `soffset`를 사용하여 자동으로 페이지를 넘겨 전체 타임라인을 가져올지 여부.
`token`	str	`None`	DataKit에서만 사용되는 작업 공간 Token이며, DataWay는 작업 객체를 가져올 때 Token을 설정해야 합니다
`timeout`	int/float	`None`	이번 요청의 타임아웃 시간. 생략 시 작업 객체의 기본값을 사용합니다
`{DataKit, DataWay 네이티브 매개변수}`	-	-	`queries[0].{DataKit, DataWay 네이티브 매개변수}`로 전달됩니다

all_series를 활성화하면 페이지당 고정적으로 500개의 타임라인을 쿼리합니다. 메트릭 쿼리는 최대 20페이지, 다른 쿼리는 최대 5페이지를 요청할 수 있습니다.

DataWay는 쿼리를 실행하기 전에 반드시 Token이 있어야 합니다. 커넥터 구성 또는 DFF.CONN(..., token='...')에서 설정해야 하며, .query(...)에 token을 중복으로 전달하지 마세요.

예시
import time
import json

@DFF.API('Run DQL via DataKit')
def run_dql_via_datakit():
    datakit = DFF.CONN('datakit')

    # DataKit 네이티브 매개변수 `time_range`를 사용하여 최근 1시간 데이터로 제한
    time_range = [
        int(time.time() - 3600) * 1000,
        int(time.time()) * 1000,
    ]

    # 쿼리하고 dict 형태로 데이터 반환
    status_code, result = datakit.query(dql='O::HOST:(host,load,create_time)', dict_output=True, time_range=time_range)
    print(json.dumps(result))

출력 예시
{
  "series": [
    [
      {
        "time": 1622463105293,
        "host": "iZbp152ke14timzud0du15Z",
        "load": 2.18,
        "create_time": 1622429576363,
        "tags": {}
      },
      {
        "time": 1622462905921,
        "host": "ubuntu18-base",
        "load": 0.08,
        "create_time": 1622268259114,
        "tags": {}
      },
      {
        "time": 1622461264175,
        "host": "shenrongMacBook.local",
        "load": 2.395508,
        "create_time": 1622427320834,
        "tags": {}
      }
    ]
  ]
}

예시
import time
import json

@DFF.API('Run DQL via DataKit')
def run_dql_via_datakit():
    datakit = DFF.CONN('datakit')

    # raw 매개변수를 추가하여 DQL 쿼리 원시 값을 가져옵니다
    time_range = [
        int(time.time() - 3600) * 1000,
        int(time.time()) * 1000,
    ]

    # 쿼리하고 DataKit 원시 반환 값 형식으로 데이터를 반환합니다
    status_code, result = datakit.query(dql='O::HOST:(host,load,create_time)', raw=True, time_range=time_range)
    print(json.dumps(result, indent=2))

출력 예시
{
  "content": [
    {
      "series": [
        {
          "name": "HOST",
          "columns": [
            "time",
            "host",
            "load",
            "create_time"
          ],
          "values": [
            [
              1622463165152,
              "iZbp152ke14timzud0du15Z",
              1.92,
              1622429576363
            ],
            [
              1622462905921,
              "ubuntu18-base",
              0.08,
              1622268259114
            ],
            [
              1622461264175,
              "shenrongMacBook.local",
              2.395508,
              1622427320834
            ]
          ]
        }
      ],
      "cost": "1ms",
      "total_hits": 3
    }
  ]
}

`.get(...)`

이 방법은 일반적인 처리 방법입니다

구체적인 매개변수 형식, 내용 등은 TrueWatch 문서 / DataKit API를 참조하세요

DataKit, DataWay에 GET 요청을 보냅니다. 매개변수는 다음과 같습니다.

매개변수	유형	필수 / 기본값	설명
`path`	str	필수	요청 경로
`query`	dict	`None`	요청 URL 매개변수
`headers`	dict	`None`	요청 Header 매개변수
`timeout`	int/float	`None`	이번 요청의 타임아웃 시간. 생략 시 작업 객체의 기본값을 사용합니다

(status_code, result)를 반환합니다. 응답 본문이 JSON으로 파싱 가능한 경우 result는 해당 객체이고, 그렇지 않으면 텍스트 또는 원시 내용입니다.

`.post_json(...)`

이 방법은 일반적인 처리 방법입니다

구체적인 매개변수 형식, 내용 등은 TrueWatch 문서 / DataKit API를 참조하세요

DataKit, DataWay에 JSON 형식으로 POST 요청을 보냅니다. 매개변수는 다음과 같습니다.

매개변수	유형	필수 / 기본값	설명
`path`	str	필수	요청 경로
`json_obj`	dict/list	필수	보내야 하는 JSON 객체
`query`	dict	`None`	요청 URL 매개변수
`headers`	dict	`None`	요청 Header 매개변수
`timeout`	int/float	`None`	이번 요청의 타임아웃 시간. 생략 시 작업 객체의 기본값을 사용합니다

path 매개변수는 1.6.8 버전에서 첫 번째 매개변수로 조정되었습니다.

(status_code, result)를 반환합니다.

`.post_line_protocol(...)`

이 방법은 일반적인 처리 방법입니다

구체적인 매개변수 형식, 내용 등은 TrueWatch 문서 / DataKit API를 참조하세요

DataKit, DataWay에 line protocol 형식으로 POST 요청을 보냅니다. 매개변수는 다음과 같습니다.

매개변수	유형	필수 / 기본값	설명
`path`	str	필수	요청 경로
`points`	dict/list	필수	단일 데이터 포인트 또는 데이터 포인트 목록
`points[#].measurement`	str	필수	메트릭 집합 이름
`points[#].tags`	dict	`None`	태그. 키 이름과 키 값은 모두 문자열이어야 합니다
`points[#].fields`	dict	필수	메트릭. 키 이름은 반드시 문자열이어야 합니다. 값은 문자열, 정수, 부동소수점, 불리언 또는 요소 유형이 일치하는 위 유형들의 목록일 수 있습니다
`points[#].timestamp`	int/long/float	{현재 시간}	타임스탬프, 초/밀리초/마이크로초/나노초 지원
`query`	dict	`None`	요청 URL 매개변수
`headers`	dict	`None`	요청 Header 매개변수
`timeout`	int/float	`None`	이번 요청의 타임아웃 시간. 생략 시 작업 객체의 기본값을 사용합니다

path 매개변수는 1.6.8 버전에서 첫 번째 매개변수로 조정되었습니다.

배치 데이터는 split_size 단위로 분할 전송됩니다. 이 메서드는 마지막 분할 요청의 (status_code, result)를 반환합니다. 분할 요청 중 하나라도 실패하면 예외를 발생시키고 이후 전송을 중지합니다.

스크립트 개발 / 커넥터 객체 DFF.CONN / DataKit, DataWay

.write_by_category(...)

.write_by_category_many(...)

.write_metric(...) / .write_point(...)

.write_metric_many(...) / .write_metrics(...) / .write_points(...)

.write_logging(...) / .write_logging_many(...)

.query(...)

.get(...)

.post_json(...)

.post_line_protocol(...)

스크립트 개발 / 커넥터 객체 `DFF.CONN` / DataKit, DataWay

`.write_by_category(...)`

`.write_by_category_many(...)`

`.write_metric(...)` / `.write_point(...)`

`.write_metric_many(...)` / `.write_metrics(...)` / `.write_points(...)`

`.write_logging(...)` / `.write_logging_many(...)`

`.query(...)`

`.get(...)`

`.post_json(...)`

`.post_line_protocol(...)`