서문
Analytics API이를 통해 Video Cloud 계정에 대한 분석 데이터를 직접 얻을 수 있습니다. 또한 비디오 클라우드 스튜디오의 분석 모듈에서 내장 분석 보고서를 볼 수 있습니다. 프로그래밍 방식으로 데이터에 액세스하면 유연성을 높일 수 있습니다.
일반적인 용도
다음은 API의 몇 가지 일반적인 사용입니다.
- 사용자 정의 차트 및 디스플레이 만들기
- 여러 API를 함께 사용하기 (예: 지난 주에 조회수가 가장 많았던 동영상에CMS API대해 를 사용하여 동영상 데이터 가져오기)
- 비디오 분석 데이터를 다른 사이트 분석 데이터와 결합
- 샘플 솔루션은 다음을 참조하십시오.
기본 URL
의 기본Analytics API URL은 다음과 같습니다.
<code class = "language-http translate ="No "> https://analytics.api.brightcove.com/v1
헤더
인증 필요)
그만큼Analytics API브라이트코브 사용 OAuth 서비스호출을 인증합니다.
먼저 클라이언트 자격 증명 (a client_id및client_secret ) 을 받아야 합니다. 이 작업은 OAuth 자격 증명 UI를 사용하여 수행할 수 있는 일회성작업입니다. CURLPostman , 또는 를 사용하여 브라이트코브 OAuth 서비스에서 직접 클라이언트 자격 증명을 가져올 수Insomnia있습니다.
클라이언트 자격 증명에 대한 분석 읽기 및 비디오 읽기 권한이 모두 필요합니다.
OAuth API를 통해 직접 자격 증명을 만드는 경우 필요한 권한은 다음과 같습니다.
[
"video-cloud/analytics/read"
"video-cloud/video/read"
]
또한 및 를 사용하여access_token가져와서 API client_idclient_secret요청과 함께 Authorization 헤더에 전달한 도 필요합니다.
Authorization: Bearer {access_token}
5분이 지나면access_token만료되므로 요청마다 하나씩 받거나 토큰이 아직 유효한지 확인해야 합니다. 보다액세스 토큰 얻기코드 샘플을 포함하여 액세스 토큰을 얻는 방법에 대한 자세한 설명을 보려면
Accept-Encoding: gzip (optional)
이 헤더를 전달하면 응답이 압축 된 형식으로 반환됩니다. 이렇게하면 큰 보고서의 성능이 향상 될 수 있습니다.
캐싱
성능상의 이유로 API 응답은 약 5 분 동안 캐시되지만 정확한 시간은 여러 요인에 따라 달라질 수 있습니다. 모든Analytics API쿼리의 경우 응답 헤더에서 캐시에 대한 정보를 얻을 수 있습니다.
는 결과가 캐시되는 최대 시간을 초 단위로Cache-Control알려줍니다 (위 예에서는 24초). Last-Modified및Expires헤더는 현재 캐시가 생성된 시기와 만료일을 알려줍니다.
대부분의 경우 이것은 문제가되지 않지만 분석 데이터의 최신 성이 매우 중요한 경우 쿼리 실행 시간이 길수록 캐시되는 시간이 길어지고 실시간 (조정되지 않은 시간당) 데이터 만 가져 오는 보고서를 알고 있어야합니다. 조정 된 데이터를 가져 오는 동안 (실시간 데이터 만 또는 추가로) 캐시되지 않습니다. 을 찾다실시간 및 조정된 데이터에 대한 전체 설명당신이 좋아한다면; 짧은 버전은Analytics API두 개의 데이터 버킷에 의존:
- 즉시 사용 가능하고 32 일 동안 저장되는 실시간 또는 시간별 미 조정 데이터
- 영구적으로 저장되는 조정 된 데이터 실시간 데이터는 정확성을 높이기 위해 조정되고 조정 된 데이터 저장소에 24 시간마다 저장됩니다.
다음을 사용하여 조정된 데이터 또는 실시간 데이터로 결과를 제한할 수 있습니다. 화해매개변수.
캐싱을 최소화하려면:
reconciled=false파라미터를 사용하여 결과를 실시간 데이터로 제한합니다.- 작은날짜 범위를사용하고 전체 범위가 지난 32일 이내에 속하는지 확인하십시오.
타임 아웃
완료되지 않은 경우 Analytics API는 8 분 후에 시간 초과를 요청합니다. 8 분 미만에 시간 초과가 표시되는 경우 원인은 일부 클라이언트 측 제한입니다.
반품 할 수있는 최대 항목
반환 할 수있는 최대 항목 수는 백만 개입니다. 대부분의 경우 한도에 도달할 가능성은 낮지만, 예를 들어 장기간에 걸쳐date측정기준에 대한 보고서를 요청하는 경우 가능합니다. 백만 개의 항목 제한에 도달하면 반환되는 항목 수를 줄이기 위해 요청을 수정해야합니다. 일반적으로 가장 간단한 방법은 데이터 범위를 줄이는 것입니다 (나중에 설명하는from및to매개 변수 사용).
동시 요청
단일 계정은 한 번에 하나의 요청으로 제한됩니다. 여러 동시 요청이 연속적으로 실행됩니다.
예:
- API 요청 "A"를 시작하십시오.
- 동일한 계정에 대해 API 요청 "B"를 시작합니다.
- 요청 "B"는 "A"가 완료 될 때까지 완료되지 않습니다.
- 요청 "A"가 너무 오래 걸리는 경우 "A"요청은 "요청이 보류 중입니다. 다시 시도하십시오"라는 오류를 수신합니다.
- 요청 "A"가 너무 오래 걸리면 요청 "B"가 동일한 오류를 수신 할 수 있습니다. A + B를 완료하는 데 걸리는 시간이 타임 아웃 값보다 크면 요청 "B"에 오류가 발생합니다.
여러 개의 동시 요청을하는 경우 수신 된 순서대로 한 번에 하나씩 처리됩니다.
"보류중인 오류"와 함께 반환되는 요청은 결국 완료되어 캐시에 저장됩니다. 즉, 동일한 데이터에 대한 향후 요청은 거의 즉시 반환되지만 5분 캐시가 만료되기 전에 요청이 이루어진 경우에만 반환됩니다.
시스템은 2-4 분을 기다린 후 동일한 요청을 다시 작성하여 보류중인 오류를 처리해야합니다.
모범 사례
요청 유형
는 세 가지 요청 유형을Analytics API허용합니다.
- 데이터 (보고서라고도 함)
- 하나 이상에 대한dimensions보고서입니다. 보고서 요청의 끝점은 다음과 같습니다.
https://analytics.api.brightcove.com/v1/data?accounts={account_id(s)}&dimensions={dimensions} - 참여 보고서
- 지난 32 일 이내의 기간 동안 사용할 수있는 자세한 참여 데이터입니다. 보다약혼 섹션상세 사항은.
- 비디오 정보 엔드 포인트
- 최소한의 지연 시간으로 제공되는 특정 분석 데이터입니다. 자세한 내용은비디오 데이터 엔드포인트를참조하십시오.
보고서에 필터및날짜 범위를 적용할수 있는 위치. 보고서 요청에는이 문서에 자세히 설명된 추가 매개 변수가 있을 수있습니다.
차원 및 필드
차원 및 필드에 대한 자세한 정보는 이제 별도의 문서에 있습니다. 차원, 필드 및 매개변수 개요
매개변수
매개 변수에 대한 자세한 정보는 이제 별도의 문서에 있습니다. 차원, 필드 및 매개변수 개요
참여 보고서
지난 32일 이내의 기간에 대해 동영상의 100번째 부분별 조회수 (또는 계정 또는 플레이어의 전체 동영상 평균) 를 보여주는 상세한 참여 보고서를 확인할 수 있습니다. (지난 32 일 이외의 기간에 대한 요청은 오류를 반환합니다.)
계정 참여
본 동영상 참여에 대한 평균 값을 얻으려면 엔드 포인트를 사용하십시오.
https://analytics.api.brightcove.com/v1/engagement/accounts/:account_id
플레이어 참여
플레이어에서 본 모든 비디오의 평균 값을 얻으려면 다음과 같은 엔드 포인트를 사용하십시오.
https://analytics.api.brightcove.com/v1/engagement/accounts/:account_id/players/:player_id
비디오 참여
특정 비디오에 대한 참여 데이터를 얻으려면 엔드 포인트를 사용하십시오.
https://analytics.api.brightcove.com/v1/engagement/accounts/:account_id/videos/:video_id
라이브 분석
는 시계열 또는 이벤트별로 Brightcove Live 스트림에 대한 분석을 검색하기 위한 두 개의 엔드포인트를Analytics API제공합니다. 자세한Analytics API Reference내용은 를 참조하십시오.