유튜브 API - 17. Bulk Report
유튜브 Analytics API
지난 글에서 Analytics API의 개요에 대해 알아봤다. 이번 글에서는 Analytics API 중 대량의 데이터를 조회하는 Bulk Report(Reporting API)에 대해서 살펴보도록 한다.
Bulk Report는 reporting API를 사용해서 조회하는 분석 데이터(보고서)를 말한다. 채널 또는 콘텐츠 소유자는 다양한 분석 데이터를 사전 정의 보고서(Report) 형식으로 조회할 수 있다.
이러한 보고서에는 YouTube 스튜디오의 분석 메뉴에서 보여주는 데이터도 포함된다.
백견이 불여일타. 자, 그럼 Reporting API를 사용해서 간단한 분석 데이터 보고서를 받아보자.
일별로 채널에서 조회수가 가장 많은 동영상 10개를 조회하기 위해 사용자 활동 보고서를 다운로드하는 작업을 아래의 순서대로 진행해 보자.
1. OAuth2 인증
API를 사용하기 위해 Data API에서 사용하던 스코프 외에 아래의 스코프가 더 필요하다.
https://www.googleapis.com/auth/yt-analytics.readonly
- YouTube 콘텐츠에 대한 YouTube 분석 보고서를 조회
- 조회수 및 평점과 같은 사용자 활동 측정 항목에 대한 액세스를 제공함
https://www.googleapis.com/auth/yt-analytics-monetary.readonly
- YouTube 콘텐츠에 대한 YouTube 분석 수익 보고서를 조회
- 사용자 활동 측정 항목과 예상 수익 및 광고 실적 측정 항목에 대한 액세스를 제공함
채널 또는 콘텐츠 소유자의 권한이 있는 계정으로 Refresh token 받아서 저장한 뒤 API 호출 시 사용한다.
(인증 관련 자세한 내용은 “유튜브(Youtube) API — 5.인증받고 사용하기” 글을 참고한다.)
2. 다운로드 대상 보고서 타입 조회
지난번 개요글에서 언급한 대로 Analytics API를 통해 생성할 수 있는 보고서는 템플릿처럼 정의되어 있다. 보고서를 다운로드하려면 타입 정보를 API의 인자로 넘겨줘야 한다. SDK를 통해서 다운로드 가능한 타입 목록을 조회할 수 있다.
reportTypes.list() 메서드의 인자로 includeSystemManaged, onBehalfOfContentOwner 값을 설정할 수 있다.
- includeSystemManaged : 유튜브 스튜디오 분석 메뉴에서 제공하는 시스템 관리 보고서 조회 여부
- onBehalfOfContentOwner : 콘텐츠 소유자 아이디값(지정하지 않으면 소유한 채널 정보만 조회함)
reportTypes.list() 호출 결과에서 id 속성의 값이 타입이다.
다운로드 가능한 보고서는 아래의 개발자 가이드 페이지에서 확인 가능하다.
- 채널 보고서
https://developers.google.com/youtube/reporting/v1/reports/channel_reports
- 콘텐츠 소유자 보고서
https://developers.google.com/youtube/reporting/v1/reports/content_owner_reports
YouTube API(for nodejs) 문서는 아래와 같이 Data API(Live Streams 포함), Analytics API, Reporting API로 웹페이지가 구분되어 있다.
- Data API : googleapis.dev/nodejs/googleapis/latest/youtube/index.html
- Analytics API : googleapis.dev/nodejs/googleapis/latest/youtubeAnalytics/index.html
- Reporting API : googleapis.dev/nodejs/googleapis/latest/youtubereporting/index.html
본 글에서는 Reporting API를 사용하기 때문에, 3번째 링크를 통해 API 정보를 확인할 수 있다.
유튜브 개발자 가이드에는 REST API로 설명하고, Java/PHP/Python SDK 샘플만 보여준다.(필자도 Java 언어가 더 익숙하지만, 그래도 요즘 세상에 NodeJs 페이지가 없는 건… -0-;)
게다가 google-api-nodejs-client sample repository에 Analytics 샘플은 없다.(analytics 라고 나와 있는 코드는 구글 Analytics API이니 시간낭비 말자) Client JavaScript code sample을 봤지만 여기도 제대로 안 나와 있다. -_ -;
제일 좋은 방법은 위 API 문서에서 해당 클래스의 메서드를 찾아보면 샘플 코드가 HTML(인코딩 안된 채로 ㄷㄷㄷ) 형식으로 나와있다. NodeJs SDK를 사용하는 개발자 입장에서는 그나마 제일 참고하기 좋다.
3. 보고서를 생성하는 작업(Job) 만들기
유튜브는 보고서를 미리 만들어 놓지 않는다. 즉, 채널 소유자나 콘텐츠 소유자가 보고서를 만들겠다고 요청하기 전에 미리 만들어진 보고서 따위는 없다는 거다.(API 호출하면 데이터가 뿅~ 하고 나오는 구조가 아니라는 게다. 유튜브 입장에서는 대량의 데이터가 정리된 보고서를 위해서 가공한 중간 데이터가 필요할 텐데, 그 많은 통계 데이터를 어떻게 다 저장하고 있겠는가. 이해가 간다. 구글 포토의 유료화도 같은 맥락일 텐데.. 이건 이해하고 싶지 않다 ㅠㅠ)
여하튼, 보고서 다운로드하고 싶다면 보고서를 생성하는 작업(Job)을 먼저 만들어야 한다. 이를 위해서 jobs.create() 메서드를 호출하면 되며, 인자로 2번에서 조회한 보고서 타입 값과 리포트명을 넘겨준다.
사용자 활동 보고서 생성을 위해 아래와 같이 타입(channel_basic_a2)과 리포트명(사용자 활동 보고서)을 인자로 jobs.create() 메서드를 아래와 같이 호출한다.
API 호출이 성공하면 생성된 작업 아이디와 생성일시 정보를 반환한다. 기존에 동일한 아이디로 생성한 작업이 있다면, 이미 생성된 작업이 있다고 에러를 발생시킨다.
이렇게 작업이 생성되면 48시간 후에 보고서를 다운로드할 수 있다. 예를 들어, 보고서 작업을 9월 1일에 생성하면 9월 1일에 대한 보고서가 9월 3일에 준비된다. 즉, 9월 2일에 대한 보고서는 9월 4일에 다운로드할 수 있다.
때문에 Reporting API는 바로 테스트하기가 쉽지 않다. 이틀이나 기다려야 한다 -0-;;; 그러니 미리미리 만들어 놓자. 그래야 이틀 뒤에 테스트할 수 있다.
4. 3번에서 만든 보고서 작업 정보(아이디) 조회
보고서를 생성하는 작업이 정상적으로 등록됐는지 확인하기 위해서 아래와 같이 jobs.list() 메서드를 호출한다.
보고서가 이틀 뒤 정확히 언제 만들어지는지 모르는 상황이니 주기적인 확인이 필요하고, 이를 위해서는 작업 정보 아이디를 조회해야 한다.(물론, 3번에서 생성한 정보를 따로 저장하고 있으면 상관없음)
5. 보고서 다운로드 URL 검색
작업을 등록하면 이틀 뒤부터 보고서가 생성된다. 이 보고서는 내용이 많기 때문에 API 호출의 결괏값이 아닌, 보고서의 URL을 통해 다운로드하는 방식으로 제공된다.
jobs.reports.list() 메서드를 사용하여 작업이 만들어 낸 보고서 정보(보고서 기준 기간<시작/종료>, 보고서 아이디, 작업 아이디, 보고서 생성 시간, 다운로드 URL)를 조회해 보자.(3번의 작업 생성 후 이틀이 지나지 않으면 생성된 보고서가 존재하지 않음)
위 코드는 생성된 작업이 하나라는 가정하에 작업 아이디를 조회하여 보고서 정보 조회 인자로 사용했다. 보고서 아이디를 포함해서 다운로드 URL 정보 등이 반환된다. 특정 보고서를 조회하고 싶다면 jobs.reports.get() 메서드에 보고서 아이디를 인자로 넘겨주면 정보를 반환한다.
6. 생성된 보고서 다운로드
자, 이제 보고서가 만들어졌으니 다운로드할 일만 남았다. HTTP GET 타입으로 5번에서 조회된 downloadUrl을 호출한다.
권한 확인을 위해 Access Token 설정을 아래와 같이 추가한다.
headers: {
'Authorization': 'Bearer ' + accessToken
}
Report URL이 gzip을 기본으로 하고 있지 않기 때문에, gzip은 반드시 활성화한다. Bulk 데이터이기 때문에 생각했던 것보다 데이터가 크다.
gzip: true
결과는 아래와 같이 헤더 행을 가지고 있는 csv 형식의 데이터다.
date,channel_id,video_id,live_or_on_demand,subscribed_status,country_code,views,comments,likes,dislikes,shares,watch_time_minutes,average_view_duration_seconds,average_view_duration_percentage,annotation_impressions,annotation_clickable_impressions,annotation_clicks,annotation_click_through_rate,annotation_closable_impressions,annotation_closes,annotation_close_rate,card_teaser_impressions,card_teaser_clicks,card_teaser_click_rate,card_impressions,card_clicks,card_click_rate,subscribers_gained,subscribers_lost,videos_added_to_playlists,videos_removed_from_playlists,red_views,red_watch_time_minutes
20200918,UCF4Wxdo3inmxP-Y59wXDsFw,xyLOJ7rT9N8,on_demand,not_subscribed,ZZ,0,0,-1,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0
20200918,UCF4Wxdo3inmxP-Y59wXDsFw,yuyuyyiZLLc,on_demand,not_subscribed,ZZ,0,2,0,4,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0
20200918,UCF4Wxdo3inmxP-Y59wXDsFw,yf2txREk7Ks,on_demand,not_subscribed,ZZ,0,0,-1,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0
...
지금까지 Reporting API를 통해서 대량 데이터를 포함하는 보고서를 다운로드하는 방법을 알아봤다.
얻고자 하는 정보를 가지고 있는 보고서 타입을 선택하고 보고서를 생성하는 작업을 등록한 뒤, 작업이 생성한 보고서의 정보(URL)를 통해서 해당 보고서를 다운로드하였다.
Reporting API는 기존에 사용하던 Data API와 다르게, 개발 전 보고서의 타입과 생성 주기를 고려하여 설계를 진행해야 한다. 본글 2번에서 언급한 보고서 종류 페이지에서 자신이 원하는 데이터가 어떤 보고서에 해당하는지 반드시 확인해 보기 바란다.
