본문 바로가기
WIKI 기술 지식 베이스

Reporting API

원문 보기 위키 갱신

출처: 문서

본문

Reporting API

Reporting API를 사용하면 리포트 정의를 만들고 관리할 수 있고, 대시보드, 시각화, 저장된 검색, 노트북에서 리포트를 생성할 수 있어요. 리포트 정의는 캡처할 소스 오브젝트, 파일 형식, 시간 범위, 그리고 선택적인 스케줄을 지정해요. 정의에서 리포트를 생성하면 리포트 인스턴스가 만들어져요.

리포트 정의와 리포트 인스턴스는 OpenSearch를 통해 관리되지만, 파일 자체는 OpenSearch Dashboards가 렌더링해요. 정의를 생성하고 인스턴스를 조회할 때는 포트 9200의 OpenSearch 엔드포인트를 사용하고, 리포트 콘텐츠를 다운로드할 때는 포트 5601의 OpenSearch Dashboards 엔드포인트를 사용해요. 자세한 내용은 리포트 콘텐츠 다운로드를 참고하세요.

이 작업에 해당하는 OpenSearch Dashboards 인터페이스 방법은 OpenSearch Dashboards를 사용한 리포팅을 참고하세요.

리포트 소스 유형과 파일 형식

Csv와 Xlsx 파일 형식은 저장된 검색의 실제 데이터 행을 내보내요. 이 형식들은 렌더링된 이미지로 캡처되는 Visualization, Dashboard, Notebook 소스 유형에서는 지원되지 않아요. 시각화 뒤의 데이터를 CSV로 내보내려면 Discover에서 동일한 쿼리를 저장된 검색으로 저장한 다음, 그 저장된 검색을 리포트 소스로 사용하세요.

다음 표는 리포트 소스 유형별로 지원되는 파일 형식을 보여줘요.

소스 유형 지원되는 파일 형식
SavedSearch Csv, Xlsx
Visualization Pdf, Png
Dashboard Pdf, Png
Notebook Pdf, Png

OpenSearch는 Visualization에 Csv를 조합하는 것처럼 소스 유형과 지원되지 않는 파일 형식을 짝지은 리포트 정의도 받아들이지만, 그 리포트는 렌더링되지 않아요. 또한 지원되지 않는 조합을 가진 정의가 있으면 정의를 삭제하기 전까지 OpenSearch Dashboards의 Reporting 페이지가 리포트 정의 목록을 불러오지 못해요. {: .warning}

리포트 정의 생성 API

리포트 정의를 생성해요.

엔드포인트

POST _plugins/_reports/definition

요청 본문 필드

다음 표는 사용할 수 있는 요청 본문 필드를 보여줘요.

필드 데이터 타입 설명
reportDefinition Object 리포트 정의예요. 필수예요.
reportDefinition.name String 리포트 정의의 이름이에요. 필수예요.
reportDefinition.isEnabled Boolean 정의의 스케줄이 활성화되어 있는지 여부예요. 필수예요.
reportDefinition.source Object 캡처할 오브젝트예요. 필수예요.
reportDefinition.source.type String 소스 오브젝트의 유형이에요. 유효한 값은 Dashboard, Visualization, SavedSearch, Notebook이에요. 필수예요.
reportDefinition.source.id String 소스 오브젝트의 saved object ID예요. 필수예요.
reportDefinition.source.origin String 리포트를 렌더링하는 OpenSearch Dashboards 인스턴스의 베이스 URL이에요. 예를 들어 http://localhost:5601이 있어요. 필수예요.
reportDefinition.source.description String 소스 오브젝트에 대한 설명이에요. 선택 사항이에요.
reportDefinition.format Object 출력 형식이에요. 필수예요.
reportDefinition.format.fileFormat String 생성되는 리포트의 파일 형식이에요. 유효한 값은 Pdf, Png, Csv, Xlsx예요. 필수예요.
reportDefinition.format.duration String 캡처할 시간 범위예요. 리포트가 생성되는 시각을 끝으로 하며, PT30M이나 P60D 같은 ISO 8601 duration으로 표현해요. 필수예요.
reportDefinition.format.limit Integer Csv 또는 Xlsx 리포트에 포함할 최대 행 수예요. 선택 사항이에요.
reportDefinition.format.header String 리포트에 추가할 헤더예요. 선택 사항이에요.
reportDefinition.trigger Object 리포트를 언제 생성할지 지정해요. 필수예요.
reportDefinition.trigger.triggerType String 유효한 값은 OnDemand, Download, CronSchedule, IntervalSchedule이에요. 필수예요.
reportDefinition.trigger.schedule Object 리포트를 생성할 스케줄이에요. triggerType이 CronSchedule 또는 IntervalSchedule일 때 필수예요.
reportDefinition.delivery Object 생성된 리포트의 알림 설정이에요. 선택 사항이에요.

요청 예시

다음 요청은 저장된 검색의 최근 60일 데이터를 CSV로 내보내는 온디맨드 정의를 생성해요:

POST _plugins/_reports/definition
{
  "reportDefinition": {
    "name": "Orders CSV",
    "isEnabled": true,
    "source": {
      "description": "CSV of all orders",
      "type": "SavedSearch",
      "origin": "http://localhost:5601",
      "id": "<saved_search_id>"
    },
    "format": {
      "duration": "P60D",
      "fileFormat": "Csv",
      "limit": 1000,
      "header": ""
    },
    "trigger": {
      "triggerType": "OnDemand"
    },
    "delivery": {
      "configIds": [],
      "title": "",
      "textDescription": "",
      "htmlDescription": ""
    },
    "status": "ACTIVE"
  }
}

{% include copy-curl.html %}

응답 예시

{
  "reportDefinitionId": "7f6fY6ABLgrkzSeVjlGr"
}

요청 예시: 예약 리포트

반복 스케줄로 리포트를 생성하려면 triggerType을 CronSchedule로 설정하고 schedule 오브젝트를 제공하세요. 다음 요청은 매일 오전 6시에 같은 CSV 리포트를 생성해요:

POST _plugins/_reports/definition
{
  "reportDefinition": {
    "name": "Daily orders CSV",
    "isEnabled": true,
    "source": {
      "description": "CSV of all orders",
      "type": "SavedSearch",
      "origin": "http://localhost:5601",
      "id": "<saved_search_id>"
    },
    "format": {
      "duration": "P1D",
      "fileFormat": "Csv",
      "limit": 10000,
      "header": ""
    },
    "trigger": {
      "triggerType": "CronSchedule",
      "schedule": {
        "cron": {
          "expression": "0 6 * * *",
          "timezone": "America/Los_Angeles"
        }
      }
    },
    "status": "ACTIVE"
  }
}

{% include copy-curl.html %}

cron 표현식에 대한 자세한 내용은 cron 표현식을 참고하세요.

리포트 정의 목록 조회 API

모든 리포트 정의를 조회해요.

엔드포인트

GET _plugins/_reports/definitions

쿼리 파라미터

다음 표는 사용할 수 있는 쿼리 파라미터를 보여줘요. 모든 쿼리 파라미터는 선택 사항이에요.

파라미터 데이터 타입 설명
fromIndex Integer 반환할 첫 번째 정의의 인덱스예요. 기본값은 0이에요.
maxItems Integer 반환할 정의의 최대 개수예요.

요청 예시

GET _plugins/_reports/definitions

{% include copy-curl.html %}

응답 예시

{
  "startIndex": 0,
  "totalHits": 1,
  "totalHitRelation": "eq",
  "reportDefinitionDetailsList": [
    {
      "id": "7f6fY6ABLgrkzSeVjlGr",
      "lastUpdatedTimeMs": 1788377796262,
      "createdTimeMs": 1788377796262,
      "tenant": "",
      "reportDefinition": {
        "name": "Orders CSV",
        "isEnabled": true,
        "source": {
          "description": "CSV of all orders",
          "type": "SavedSearch",
          "origin": "http://localhost:5601",
          "id": "test-search"
        },
        "format": {
          "duration": "PT1440H",
          "fileFormat": "Csv",
          "limit": 1000,
          "header": "",
          "timeFrom": null,
          "timeTo": null
        },
        "trigger": {
          "triggerType": "OnDemand"
        },
        "delivery": {
          "title": "",
          "textDescription": "",
          "htmlDescription": "",
          "configIds": []
        }
      }
    }
  ]
}

리포트 정의 조회 API

단일 리포트 정의를 조회해요.

엔드포인트

GET _plugins/_reports/definition/{report_definition_id}

요청 예시

GET _plugins/_reports/definition/7f6fY6ABLgrkzSeVjlGr

{% include copy-curl.html %}

응답 예시

{
  "reportDefinitionDetails": {
    "id": "7f6fY6ABLgrkzSeVjlGr",
    "lastUpdatedTimeMs": 1788377796434,
    "createdTimeMs": 1788377796262,
    "tenant": "",
    "reportDefinition": {
      "name": "Orders CSV",
      "isEnabled": true,
      "source": {
        "description": "CSV of all orders",
        "type": "SavedSearch",
        "origin": "http://localhost:5601",
        "id": "test-search"
      },
      "format": {
        "duration": "PT1440H",
        "fileFormat": "Csv",
        "limit": 1000,
        "header": "",
        "timeFrom": null,
        "timeTo": null
      },
      "trigger": {
        "triggerType": "OnDemand"
      },
      "delivery": {
        "title": "",
        "textDescription": "",
        "htmlDescription": "",
        "configIds": []
      }
    }
  }
}

리포트 정의 수정 API

기존 리포트 정의를 교체해요. 생략한 필드는 유지되지 않기 때문에 완전한 정의를 제공해야 해요.

엔드포인트

PUT _plugins/_reports/definition/{report_definition_id}

요청 예시

PUT _plugins/_reports/definition/7f6fY6ABLgrkzSeVjlGr
{
  "reportDefinition": {
    "name": "Orders CSV",
    "isEnabled": true,
    "source": {
      "description": "CSV of all orders",
      "type": "SavedSearch",
      "origin": "http://localhost:5601",
      "id": "<saved_search_id>"
    },
    "format": {
      "duration": "P90D",
      "fileFormat": "Csv",
      "limit": 5000,
      "header": ""
    },
    "trigger": {
      "triggerType": "OnDemand"
    },
    "status": "ACTIVE"
  }
}

{% include copy-curl.html %}

응답 예시

{
  "reportDefinitionId": "7f6fY6ABLgrkzSeVjlGr"
}

리포트 정의 삭제 API

리포트 정의를 삭제해요. 정의를 삭제해도 이미 그 정의로 생성된 리포트는 삭제되지 않아요.

엔드포인트

DELETE _plugins/_reports/definition/{report_definition_id}

요청 예시

DELETE _plugins/_reports/definition/7f6fY6ABLgrkzSeVjlGr

{% include copy-curl.html %}

응답 예시

{
  "reportDefinitionId": "7f6fY6ABLgrkzSeVjlGr"
}

온디맨드 리포트 생성 API

기존 리포트 정의로부터 리포트 인스턴스를 생성해요. 응답에는 사용된 정의와 캡처된 시간 범위가 기록돼요. 파일 콘텐츠를 가져오는 방법은 리포트 콘텐츠 다운로드를 참고하세요.

엔드포인트

POST _plugins/_reports/on_demand/{report_definition_id}

요청 예시

POST _plugins/_reports/on_demand/7f6fY6ABLgrkzSeVjlGr
{}

{% include copy-curl.html %}

응답 예시

{
  "reportInstance": {
    "id": "7v6fY6ABLgrkzSeVpVGM",
    "lastUpdatedTimeMs": 1788377802121,
    "createdTimeMs": 1788377802121,
    "beginTimeMs": 1780601802121,
    "endTimeMs": 1788377802121,
    "tenant": "",
    "reportDefinitionDetails": {
      "id": "7f6fY6ABLgrkzSeVjlGr",
      "reportDefinition": {
        "name": "Orders CSV",
        "isEnabled": true,
        "source": {
          "description": "CSV of all orders",
          "type": "SavedSearch",
          "origin": "http://localhost:5601",
          "id": "test-search"
        },
        "format": {
          "duration": "PT1440H",
          "fileFormat": "Csv",
          "limit": 5000,
          "header": "",
          "timeFrom": null,
          "timeTo": null
        },
        "trigger": {
          "triggerType": "OnDemand"
        }
      }
    },
    "status": "Success"
  }
}

응답 본문 필드

다음 표는 응답 본문 필드를 보여줘요.

필드 데이터 타입 설명
reportInstance.id String 리포트 인스턴스의 ID예요.
reportInstance.beginTimeMs Integer 캡처된 시간 범위의 시작 시각이에요. epoch 이후 밀리초 단위예요.
reportInstance.endTimeMs Integer 캡처된 시간 범위의 끝 시각이에요. epoch 이후 밀리초 단위예요.
reportInstance.reportDefinitionDetails Object 인스턴스를 생성하는 데 사용된 리포트 정의예요.
reportInstance.status String 리포트 인스턴스의 상태예요. 예를 들면 Success가 있어요.

리포트 인스턴스 목록 조회 API

클러스터에서 생성된 리포트 인스턴스를 조회해요.

엔드포인트

GET _plugins/_reports/instances

쿼리 파라미터

다음 표는 사용할 수 있는 쿼리 파라미터를 보여줘요. 모든 쿼리 파라미터는 선택 사항이에요.

파라미터 데이터 타입 설명
fromIndex Integer 반환할 첫 번째 인스턴스의 인덱스예요. 기본값은 0이에요.
maxItems Integer 반환할 인스턴스의 최대 개수예요.

요청 예시

GET _plugins/_reports/instances?fromIndex=0&maxItems=2

{% include copy-curl.html %}

응답 예시

{
  "startIndex": 0,
  "totalHits": 5,
  "totalHitRelation": "eq",
  "reportInstanceList": [
    {
      "id": "7v6fY6ABLgrkzSeVpVGM",
      "lastUpdatedTimeMs": 1788377802121,
      "createdTimeMs": 1788377802121,
      "beginTimeMs": 1780601802121,
      "endTimeMs": 1788377802121,
      "tenant": "",
      "status": "Success"
    }
  ]
}

리포트 인스턴스 조회 API

단일 리포트 인스턴스를 조회해요.

엔드포인트

GET _plugins/_reports/instance/{report_instance_id}

요청 예시

GET _plugins/_reports/instance/7v6fY6ABLgrkzSeVpVGM

{% include copy-curl.html %}

리포트 콘텐츠 다운로드

OpenSearch 엔드포인트는 리포트 메타데이터를 관리할 뿐 리포트 파일을 반환하지는 않아요. 콘텐츠를 가져오려면 리포트 정의의 ID를 넣어 OpenSearch Dashboards reporting 엔드포인트를 호출하세요:

POST {osd_host}:{port}/api/reporting/generateReport/{report_definition_id}

이 엔드포인트에는 osd-xsrf: true 헤더와 다음 쿼리 파라미터가 필요해요.

파라미터 데이터 타입 설명
timezone String 리포트 시간 범위를 해석하는 데 사용되는 시간대예요. 예를 들면 UTC가 있어요. 필수예요.
dateFormat String 출력의 날짜 필드에 적용되는 형식이에요. 예를 들면 MMM D, YYYY @ HH:mm:ss.SSS가 있어요. 필수예요.
csvSeparator String Csv 출력에서 값을 구분하는 데 사용되는 문자예요. 필수예요.
allowLeadingWildcards Boolean 저장된 검색 쿼리가 와일드카드로 시작할 수 있는지 여부예요. 필수예요.

요청 예시

다음 요청은 리포트 정의의 CSV 콘텐츠를 다운로드해요:

curl -X POST \
  -H 'osd-xsrf: true' \
  -H 'Content-Type: application/json' \
  'http://localhost:5601/api/reporting/generateReport/7f6fY6ABLgrkzSeVjlGr?timezone=UTC&dateFormat=MMM%20D,%20YYYY%20@%20HH:mm:ss.SSS&csvSeparator=,&allowLeadingWildcards=true' \
  -d '{}'

{% include copy.html %}

응답 예시

Csv 리포트라면 data 필드에 파일 콘텐츠가 텍스트로 담겨요:

{
  "data": "order_date,customer_name,price\n\"Aug 1, 2026 @ 10:00:00.000\",Alice,24.99\n\"Aug 2, 2026 @ 11:00:00.000\",Bob,13.5\n\"Aug 3, 2026 @ 12:00:00.000\",Carla,99",
  "filename": "Orders CSV_2026-09-02T19:34:25.546Z_4e4bc6a0-a705-11f1-b9f2-73596a0bfb5c.csv"
}

Xlsx 리포트라면 data 필드에 텍스트 대신 Base64로 인코딩된 data URL이 담겨요.

data가 빈 문자열이라면 리포트 정의의 duration이 어떤 문서와도 겹치지 않았다는 뜻이에요. 현재 시각을 끝으로 하는 시간 범위가 데이터를 포함하도록 duration을 늘리세요. {: .tip}

OpenSearch 버전 2.16 이하에서는 CSV 리포트에 설정할 수 없는 10,000행 제한이 있어요. 버전 2.17부터는 리포트 정의의 limit 필드로 제한을 설정할 수 있어요. {: .note}

관련 문서

더 알아보기 (Learn more)

함께 읽는 실무 이야기

우리 조직에도 적용하고 싶다면, AI 시스템 구축 서비스를 살펴보세요.