V1 Reporting API에서 Export API 마이그레이션 가이드

수명 종료 (End of life)

V1 Reporting API는 지원 종료(deprecated)될 예정이며, 향후 개발 및 지원은 데이터 세트 내보내기(Dataset Export) API 및 Issues REST API에 집중될 예정입니다. Snyk은 새로운 Export API로 마이그레이션할 것을 권장합니다.

이 가이드는 레거시 V1 Reporting API의 모든 라우트에 대한 마이그레이션 경로를 설명합니다.

V1 Reporting 레거시 API에서 새로운 Export API로의 마이그레이션 가이드

가장 큰 변화는 직접적인 동기식(synchronous) 요청/응답 모델(v1)에서 비동기식(asynchronous) 작업 기반 모델(Export API)로의 전환입니다.

기능 (Feature)	레거시 V1 Reporting API	새로운 Export API
엔드포인트 구조	직접적인 리소스 엔드포인트 (/v1/reporting/issues)	범위(Scoped) 작업 엔드포인트. 새로운 API는 조직(Organization) 또는 그룹(Group) 범위에 집중하며, 조직 ID 또는 그룹 ID를 경로 매개변수로 사용합니다.
응답 형식	응답 본문에 JSON 포함	서명된 URL을 사용한 CSV 파일
데이터 검색	동기식, 즉각적인 응답	Export API는 데이터 내보내기를 위한 견고하고 확장 가능한 솔루션을 제공하며, 보안상 안전하게 저장되고 자체 서명 링크를 사용하여 접근 가능한 CSV 파일로 결과를 제공합니다. 대규모 데이터 세트를 위해 비동기식 작업 패턴(시작, 상태 확인, 결과 가져오기)을 사용하며, 대량의 데이터에 대해 직접적이고 동기적인 POST 요청을 대체합니다.
속도 제한	사용자당 분당 70회 요청	시간당 20회의 내보내기 POST 요청 (상태/결과 확인은 무제한)
필수 헤더	Authorization	Authorization, Version (예: 2024-10-15)

새로운 내보내기 워크플로우

모든 V1 Reporting API 호출을 대체하려면 다음 단계를 따르십시오.

1. 내보내기 시작 (Initiate the Export):

   1. 필터가 포함된 POST 요청을 보내 내보내기 작업을 생성합니다. export_id를 받게 됩니다.

   2. 엔드포인트: POST /groups/{group_id}/export

   3. 필수 매개변수: 본문(Body)에는 필터(최소 하나 이상의 날짜 필터: introduced 또는 updated 포함)가 포함되어야 하며, 요청 헤더에 데이터 세트(issues 또는 usage)를 지정해야 합니다.

2. 내보내기 상태 확인 (Validate the Export Status):

   1. 상태가 FINISHED가 될 때까지 export_id를 사용하여 상태 엔드포인트를 폴링합니다.

   2. 엔드포인트: GET /groups/{group_id}/jobs/export/{export_id}

   3. 상태 값: PENDING, STARTED, FINISHED, ERROR.

3. CSV 결과 가져오기 (Fetch Results in a CSV):

   1. 상태가 FINISHED가 되면 결과를 가져옵니다. CSV 파일로 연결되는 자체 서명 URL이 반환됩니다.

   2. 엔드포인트: GET /groups/{group_id}/export/{export_id}

자체 서명 링크는 기본적으로 60분 동안 유효하며, 0분에서 60분 사이로 구성할 수 있습니다.

라우트별 마이그레이션

문제 및 프로젝트 수에 대한 v1 라우트는 이제 주로 Export API의 issues 데이터 세트에 매핑되며, 테스트 수(test counts)는 usage 데이터 세트에 매핑됩니다.

레거시 V1 라우트	목적 (Purpose)	새로운 Export API 매핑	참고 (Notes)
POST /v1/reporting/issues	기간 내 문제 목록 가져오기	Dataset: issues	타임프레임 로직을 재현하기 위해 introduced (from/to) 및/또는 updated (from/to) 필터를 사용하십시오.
POST /v1/reporting/issues/latest	최신 문제 목록 가져오기	Dataset: issues	특정 시점 이후에 업데이트된 문제가 필요한 경우 최근 날짜와 함께 updated (from) 필터만 사용하십시오.
POST /v1/reporting/counts/issues	기간 내 문제 수 가져오기	Dataset: issues	계산 로직은 이제 내보낸 전체 CSV 파일을 처리하여 수행됩니다. 타임프레임을 재현하기 위해 introduced 및/또는 updated 필터를 사용하십시오.
POST /v1/reporting/counts/issues/latest	최신 문제 수 가져오기	Dataset: issues	계산 로직은 이제 내보낸 전체 CSV 파일을 처리하여 수행됩니다.
POST /v1/reporting/counts/projects	기간 내 프로젝트 수 가져오기	Dataset: issues	계산 로직은 이제 내보낸 전체 CSV 파일을 처리하여 수행됩니다. 프로젝트 식별을 위해 CSV의 project_public_id 또는 project_name 열을 사용하십시오.
POST /v1/reporting/counts/projects/latest	최신 프로젝트 수 가져오기	Dataset: issues	계산 로직은 이제 내보낸 전체 CSV 파일을 처리하여 수행됩니다.
POST /v1/reporting/counts/tests	기간 내 테스트 횟수 가져오기	Dataset: usage	계산 로직은 내보낸 전체 CSV 파일을 처리하고 interaction_type: "Scan done"으로 필터링하여 수행됩니다. 타임프레임 관리를 위해 updated (from/to)를 사용하십시오.

수(count) 엔드포인트에 대한 중요 고려 사항

v1 문제 수 엔드포인트(/v1/reporting/counts/issues 및 /latest)는 레거시 데이터 모델을 기반으로 하며 모든 Snyk 제품의 현실을 정확하게 반영하지 못합니다.

주요 문제:

• 레거시 v1 문제 수 엔드포인트에는 Snyk Code의 문제가 포함되지 않으며, 최신 Snyk Infrastructure as Code (IaC) 엔진에서 생성된 문제도 포함되지 않습니다.

• 조치: issues 데이터 세트를 사용하는 Export API로 마이그레이션하면 IaC를 포함한 모든 Snyk 제품의 모든 문제에 대해 보다 완전하고 정확한 수를 제공받을 수 있습니다. 모든 수(count) 마이그레이션 시, 새로운 수치가 더 높을 가능성이 크며 이는 전체 문제 현황을 더 잘 나타내는 것임을 인지해야 합니다.

필터 매개변수 마이그레이션

Export API는 초기 POST /export 요청 본문에서 필터를 사용합니다.

필터 값은 대소문자를 구분합니다.

필터 (Filter)	적용 가능한 데이터 세트	설명 (Description)
updated (from 및 to)	issues, usage	데이터 세트의 속성에 영향을 준 마지막 업데이트 날짜와 시간입니다. 필수 사항입니다(또는 introduced 사용).
introduced (from 및 to)	issues	문제가 도입된 날짜와 시간입니다. 필수 사항입니다(또는 updated 사용).
orgs	issues, usage	Snyk 조직 ID 목록. 그룹 엔드포인트에서만 사용 가능합니다.
environment	issues	프로젝트의 환경(예: external).
lifecycle	issues	프로젝트의 수명 주기(예: production).
product_name	issues	문제를 생성한 Snyk 제품의 이름(예: Snyk IaC).
project_type	issues	프로젝트에 사용된 스캔 방법(예: npm, maven). 대소문자를 구분하는 값입니다.
project_tags	issues	key:value 쌍 형태의 프로젝트 태그. 대소문자를 구분하는 값입니다.

위에 나열되지 않은 v1 필터(예: severity, fixable, languages)의 경우, 새로운 프로세스는 전체 CSV를 다운로드하고 해당 열을 사용하여 애플리케이션 또는 데이터 웨어하우스에서 필요한 필터링 로직을 적용하는 것입니다.

V1 필터 이름	Export API 열 (사후 필터링용)
severity	issue_severity
languages	project_type
ignored, isFixed, status	issue_status
fixable, isUpgradable 등	computed_fixability
projects	project_public_id

CSV-JSON 변환 도구

Export API는 데이터를 CSV로 반환하고 레거시 API는 JSON을 반환했으므로, 애플리케이션에서 구조화된 데이터를 소비하기 위해 내보낸 파일을 변환해야 할 수도 있습니다.

네이티브 JSON 출력

Snyk은 데이터를 JSON 형식으로 직접 내보낼 수 있는 기능을 추가하는 것을 우선순위로 두고 있습니다. 11월 초에 출시될 예정입니다. 이 기능은 v1 API에서 마이그레이션하는 사용자의 데이터 소비를 단순화할 것입니다.

현재 해결 방법 스크립트

서명된 URL에서 CSV를 다운로드하고, JSON으로 변환하고, 선택적으로 명령줄 도구인 jq를 사용하여 형식을 지정하는 것을 자동화하는 Python 스크립트 예제 csv_to_json_tool.py를 제공합니다.

스크립트 사전 준비 사항:

• Python: 이 스크립트는 Python 3.x가 필요합니다.

• 라이브러리: requests (pip install requests).

최종 JSON 파일을 예쁘게 출력(pretty-printing)하기 위해 명령줄 도구인 jq를 사용할 것을 권장합니다.

대안: 트랜잭션 데이터를 위한 Issues REST API

Export API가 v1 보고의 직접적인 대체제이지만, 대량의 CSV 보고서 대신 통합 목적을 위해 문제에 대한 실시간 트랜잭션 액세스(JSON 응답)가 필요한 개발자는 새로운 Issues REST API를 사용할 수 있습니다.

엔드포인트 (Endpoint)	메서드	목적 (Purpose)
/rest/orgs/{org_id}/issues	GET	조직의 모든 문제에 대한 페이지네이션된 목록을 가져옵니다.
/groups/{group_id}/issues	GET	그룹의 모든 문제에 대한 페이지네이션된 목록을 가져옵니다.
/rest/orgs/{org_id}/issues/{issue_id}	GET	단일 문제에 대한 세부 정보를 가져옵니다.
/orgs/{org_id}/packages/{purl}/issues	GET	패키지 URL(purl)로 식별된 특정 패키지 버전에 대한 문제를 쿼리합니다. (직접 취약점만 반환합니다.)
/orgs/{org_id}/packages/issues	POST	purl을 통해 패키지 묶음에 대한 문제를 쿼리합니다. (모든 고객이 사용할 수 있는 것은 아닙니다.)

이러한 엔드포인트는 필터링을 위한 다양한 쿼리 매개변수(예: effective_severity_level, type, status, updated_after와 같은 날짜 범위)를 지원하고, 커서 기반 페이지네이션(starting_after, ending_before)을 사용하며, 구조화된 JSON 형식으로 데이터를 반환합니다.