YouTube Reporting API - Get Bulk Data Reports

YouTube는 크리에이터 스튜디오에서 해당 보고서에 액세스할 수 있는 콘텐츠 소유자를 위해 시스템에서 관리하는 광고 수익 보고서를 자동으로 생성합니다. 이 보고서는 YouTube 크리에이터 스튜디오의 보고서 메뉴에서 액세스할 수 있는 수동 다운로드 가능 보고서에서도 제공되는 데이터에 프로그래매틱 방식으로 액세스할 수 있도록 설계되었습니다.

참고: API는 크리에이터 스튜디오와 다른 보고서 세트에 대한 액세스를 제공하지만 보고서에는 유사한 데이터가 포함됩니다. API 보고서에는 크리에이터 스튜디오 보고서와 다른 필드가 있을 수 있으며 필드 이름도 다를 수 있습니다.

YouTube는 시스템 관리 보고서를 자동으로 생성하므로 이러한 보고서를 가져오는 프로세스는 API를 통해 제공되는 YouTube 분석 대량 데이터 보고서와 다릅니다.

보고서 가져오기

다음 단계에서는 API를 통해 시스템 관리 보고서를 가져오는 방법을 설명합니다.

1단계: 승인 사용자 인증 정보 가져오기

모든 YouTube Reporting API 요청은 승인된 상태여야 합니다. 승인 가이드에서는 OAuth 2.0 프로토콜을 사용하여 승인 토큰을 가져오는 방법을 설명합니다.

YouTube Reporting API 요청은 다음 승인 범위를 사용합니다.

2단계: 원하는 보고서의 작업 ID 가져오기

jobs.list 메서드를 호출하여 시스템 관리 작업 목록을 가져옵니다. includeSystemManaged 매개변수를 true로 설정합니다.

반환된 각 Job 리소스의 reportTypeId 속성은 해당 작업과 연결된 시스템 관리 보고서의 유형을 식별합니다. 다음 단계에서 애플리케이션에 동일한 리소스의 id 속성 값이 필요합니다.

보고서 문서에는 사용 가능한 보고서, 보고서 유형 ID, 포함된 필드가 나열되어 있습니다. reportTypes.list 메서드를 사용하여 지원되는 보고서 유형 목록을 가져올 수도 있습니다.

3단계: 보고서의 다운로드 URL 가져오기

jobs.reports.list 메서드를 호출하여 작업에 대해 생성된 보고서 목록을 가져옵니다. 요청에서 jobId 매개변수를 가져오려는 보고서의 작업 ID로 설정합니다.

다음 매개변수 중 일부 또는 전부를 사용하여 보고서 목록을 필터링할 수 있습니다.

• createdAfter 매개변수를 사용하여 API가 지정된 시간 이후에 생성된 보고서만 반환하도록 지정합니다. 이 매개변수를 사용하면 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 매개변수를 생략합니다.)

    보고서를 가져와서 성공적으로 처리할 때마다 이러한 보고서 중 가장 최신 보고서가 생성된 날짜 및 시간에 해당하는 타임스탬프를 저장합니다. 그런 다음 reports.list 메서드를 연속으로 호출할 때마다 createdAfter 매개변수 값을 업데이트하여 API를 호출할 때마다 데이터가 채워진 새 보고서를 포함한 새 보고서만 가져오도록 합니다.

    안전 장치로 보고서를 가져오기 전에 보고서의 ID가 데이터베이스에 아직 나열되어 있지 않은지 확인하세요.

  • 다운로드하고 처리한 각 보고서의 ID를 저장합니다. 각 보고서가 생성된 날짜 및 시간 또는 보고서에 데이터가 포함된 기간을 함께 식별하는 보고서의 startTime 및 endTime와 같은 추가 정보를 저장할 수도 있습니다. YouTube 분석의 대량 데이터를 가져오는 보고서의 경우 각 보고서에 24시간 동안의 데이터가 포함되어 있으므로 각 작업에 많은 보고서가 있을 수 있습니다. 더 긴 기간을 포함하는 시스템 관리 작업에는 보고서가 더 적게 표시됩니다.

    보고서 ID를 사용하여 아직 다운로드하고 가져와야 하는 보고서를 식별합니다. 하지만 두 개의 새 보고서의 startTime 및 endTime 속성 값이 동일한 경우 createTime 값이 더 최신인 보고서만 가져옵니다.

보고서 특성

API 보고서는 다음과 같은 특징이 있는 버전이 지정된 .csv (쉼표로 구분된 값) 파일입니다.

• 각 보고서에는 보고서 시작일의 오전 12시(태평양 표준시)부터 보고서 종료일의 오후 11시 59분(태평양 표준시)까지의 고유한 기간에 대한 데이터가 포함됩니다.

• 보고서 데이터가 정렬되지 않았습니다.