YouTube에서는 크리에이터 스튜디오에서 관련 보고서에 액세스할 수 있는 콘텐츠 소유자를 위해 시스템 관리 광고 수익 보고서 모음을 자동으로 생성합니다. 이러한 보고서는 데이터에 프로그래매틱 방식으로 액세스할 수 있도록 설계되었으며, YouTube 크리에이터 스튜디오의 보고서 메뉴에서 수동으로 다운로드 가능한 보고서를 통해서도 이용할 수 있습니다.
참고: API를 사용하면 크리에이터 스튜디오와는 다른 보고서 세트에 액세스할 수 있지만, 보고서에 유사한 데이터가 포함되어 있습니다. API 보고서는 필드가 다를 수 있으며 크리에이터 스튜디오 보고서와 다른 필드 이름을 사용하기도 합니다.
YouTube에서는 시스템 관리 보고서를 자동으로 생성하므로 이러한 보고서를 가져오는 절차는 API를 통해 제공되는 YouTube 분석 일괄 데이터 보고서와는 다릅니다.
보고서 가져오기
다음 단계에서는 API를 통해 시스템 관리 보고서를 검색하는 방법을 설명합니다.
1단계: 승인 사용자 인증 정보 검색
모든 YouTube Reporting API 요청은 승인을 받아야 합니다. 승인 가이드에서는 OAuth 2.0 프로토콜을 사용하여 인증 토큰을 검색하는 방법을 설명합니다.
YouTube Reporting API 요청은 다음 승인 범위를 사용합니다.
| 범위 | |
|---|---|
| https://www.googleapis.com/auth/yt-analytics.readonly | YouTube 콘텐츠에 관한 YouTube 분석 보고서를 봅니다. 이 범위를 사용하여 사용자 활동 측정항목(예: 조회수, 평가 횟수)을 조회할 수 있습니다. |
| https://www.googleapis.com/auth/yt-analytics-monetary.readonly | YouTube 콘텐츠에 대한 YouTube 분석 수익 보고서를 확인합니다. 이 범위를 사용하여 사용자 활동 측정항목과 예상 수익 및 광고 실적 측정항목에 액세스할 수 있습니다. |
2단계: 원하는 보고서의 작업 ID 검색
jobs.list 메서드를 호출하여 시스템 관리 작업 목록을 가져옵니다. includeSystemManaged 매개변수를 true로 설정합니다.
반환된 각 Job 리소스의 reportTypeId 속성은 해당 작업과 연결된 시스템 관리 보고서의 유형을 식별합니다. 애플리케이션에는 다음 단계에서 동일한 리소스의 id 속성 값이 필요합니다.
보고서 문서에는 사용 가능한 보고서, 보고서 유형 ID, 보고서에 포함된 필드가 표시됩니다. reportTypes.list 메서드를 사용하여 지원되는 보고서 유형 목록을 검색할 수도 있습니다.
3단계: 보고서의 다운로드 URL 검색
jobs.reports.list 메서드를 호출하여 작업에 대해 생성된 보고서 목록을 검색합니다. 요청에서 jobId 매개변수를 검색하려는 보고서의 작업 ID로 설정합니다.
다음 매개변수 중 일부 또는 전부를 사용하여 보고서 목록을 필터링할 수 있습니다.
-
API가 지정된 시간 이후에 생성된 보고서만 반환해야 함을 나타내려면
createdAfter매개변수를 사용합니다. 이 매개변수를 사용하면 API가 아직 처리하지 않은 보고서만 반환하도록 할 수 있습니다. -
startTimeBefore매개변수를 사용하여 API 응답에 보고서의 가장 빠른 데이터가 지정된 날짜 이전인 경우에만 보고서를 포함해야 함을 나타냅니다.createdAfter매개변수는 보고서가 생성된 시간과 관련이 있지만 이 날짜는 보고서의 데이터와 관련이 있습니다. -
startTimeAtOrAfter매개변수를 사용하여 API 응답에 보고서의 가장 오래된 데이터가 지정된 날짜 또는 그 이후인 경우에만 보고서를 포함해야 함을 나타냅니다.startTimeBefore매개변수와 마찬가지로 이 매개변수 값은 보고서 생성 시간이 아니라 보고서의 데이터에 해당합니다.
API 응답에는 해당 작업의 Report 리소스 목록이 포함됩니다. 각 리소스는 고유한 기간에 대한 데이터가 포함된 보고서를 가리킵니다.
- 리소스의
startTime및endTime속성은 보고서 데이터에 포함된 기간을 식별합니다. - 리소스의
downloadUrl속성은 보고서를 가져올 수 있는 URL을 식별합니다. - 리소스의
createTime속성은 보고서가 생성된 날짜와 시간을 지정합니다. 애플리케이션은 이 값을 저장하고 이전에 다운로드한 보고서가 변경되었는지 여부를 확인하는 데 사용해야 합니다.
4단계: 보고서 다운로드
4단계에서 가져온 downloadUrl에 HTTP GET 요청을 전송하여 보고서를 검색합니다.
처리 보고서
권장사항
YouTube Reporting API를 사용하는 애플리케이션은 항상 다음 권장사항을 따라야 합니다.
-
보고서의 헤더 행을 사용하여 보고서 열의 순서를 결정합니다. 예를 들어 조회수가 보고서 설명에 나열된 첫 번째 측정항목이라는 이유만으로 보고서에서 반환되는 첫 번째 측정항목이라고 가정해서는 안 됩니다. 대신 보고서의 헤더 행을 사용하여 해당 데이터가 포함된 열을 결정할 수 있습니다.
-
동일한 보고서가 반복적으로 처리되지 않도록 다운로드한 보고서를 기록해 둡니다. 다음 목록은 이를 위한 몇 가지 방법을 제안합니다.
-
reports.list메서드를 호출할 때 createdAfter 매개변수를 사용하여 특정 날짜 이후에 생성된 보고서만 검색할 수 있습니다. 보고서를 처음 검색할 때는createdAfter매개변수를 생략합니다.보고서를 검색하여 성공적으로 처리할 때마다 최신 보고서가 생성된 날짜 및 시간에 해당하는 타임스탬프를 저장하세요. 그런 다음 API를 호출할 때마다 백필된 데이터가 있는 새 보고서를 비롯하여 새 보고서만 가져오도록
reports.list메서드를 연속으로 호출할 때마다createdAfter매개변수 값을 업데이트합니다.보호 조치로, 보고서를 검색하기 전에 보고서의 ID가 데이터베이스에 이미 나열되어 있지 않은지 확인하세요.
-
다운로드하여 처리한 각 보고서의 ID를 저장합니다. 또한 각 보고서가 생성된 날짜 및 시간이나 보고서의
startTime및endTime와 같은 추가 정보를 저장할 수 있습니다. 이러한 정보는 보고서에 데이터가 포함된 기간을 함께 나타냅니다. YouTube 분석에 대한 일괄 데이터를 검색하는 보고서의 경우 각 보고서에 24시간 동안의 데이터가 포함되므로 각 작업에 보고서가 많이 있을 수 있습니다. 더 긴 기간을 다루는 시스템 관리 작업은 보고서 수가 적습니다.보고서 ID를 사용하면 다운로드하고 가져와야 하는 보고서를 식별할 수 있습니다. 그러나 두 개의 새 보고서의
startTime및endTime속성 값이 동일한 경우 최신createTime값이 포함된 보고서만 가져옵니다.
-
보고서 특성
API 보고서는 버전이 지정된 .csv (쉼표로 구분된 값) 파일로서 다음과 같은 특성을 가집니다.
-
각 보고서에는 보고서 시작일 오전 12시(태평양 표준시)부터 보고서 종료일 오후 11시 59분(태평양 표준시)까지의 고유 기간에 대한 데이터가 포함됩니다.
-
보고서 데이터가 정렬되지 않았습니다.