개요: 오디언스 API

API 참조

API 레퍼런스도 참조하십시오 .

기본 URL

대상 API의 기본 URL은 다음과 같습니다.

https://audience.api.brightcove.com/v1

계정 경로

모든 경우에 특정 Video Cloud 계정에 대한 요청이 이루어집니다. 항상 “계정”이라는 용어와 계정 ID를 기본 URL에 추가해야 합니다.

https://audience.api.brightcove.com/v1/accounts/{account_id} 

인증

Audience API는 브라이트코브 OAuth 서비스를사용하여 통화를 인증합니다.

먼저 클라이언트 자격 증명 (a client_id및client_secret ) 을 받아야 합니다. 이 작업은 OAuth 자격 증명 UI를 사용하여 수행할 수 있는 일회성작업입니다. 오디언스/읽기 작업에 대한 권한이 필요합니다.

cURL또는 Postman을 사용하여 브라이트코브 OAuth 서비스에서 직접 클라이언트 자격 증명을 가져올 수있습니다.

또한 및 를 사용하여access_token가져와서 API client_idclient_secret요청과 함께 Authorization 헤더에 전달한 도 필요합니다.

Authorization: Bearer {access_token}

5분이 지나면access_token만료되므로 요청마다 하나씩 받거나 토큰이 아직 유효한지 확인해야 합니다. 보다액세스 토큰 얻기코드 샘플을 포함하여 액세스 토큰을 얻는 방법에 대한 자세한 설명을 보려면

오류 처리

오류가 발생하면 API는 다음 상태 코드 중 하나와 응답 본문에 해당 오류 코드를 사용하여 응답합니다.

다음은 오류에 대한 샘플 응답 본문입니다.

[
	{
	"error_code": "UNAUTHORIZED_ERROR",
	"message": "Permission denied"
	}
]

매개변수

검색된 데이터를 제한하고 필터링하기 위해 요청에 추가할 수 있는 여러 매개 변수가 있습니다. 이는 다음 섹션에 설명된 모든 요청 유형에 적용됩니다.

결과 필터링

where파라미터를 사용하여 결과를 필터링할 수 있습니다. 필터의 구문은 다음과 같습니다.

where=field1==value1;field2==value2

예:

where=video_id==123456789;video_name==test

쉼표는 논리 OR로 취급되고 세미콜론은 논리 AND로 취급됩니다. 예를 들어, where=video_id==1234,5678;video_name=test는 “여기서 video_id = 1234 또는 5678이고 video_name = 테스트”로 해석됩니다.

반환할 필드 선택

필드의 하위 집합으로 결과를 제한하기 위해 요청에 필드 목록을 지정할 수 있습니다. 필드의 구문은 다음과 같습니다.

fields=field1,field4

예:

fields=video_id,video_name

필터링 및 정렬할 수 있는 필드는 다음 섹션에서 각 요청 유형에 대해 자세히 설명합니다.

날짜 범위

날짜 범위는from및to매개 변수로 지정할 수 있으며 뷰 이벤트가 마지막으로 업데이트된 날짜 (updated_at 필드) 에 적용됩니다. 날짜 범위는 다음 형식으로 나타낼 수 있습니다.

• 현재 시간을now나타내는 텍스트 값입니다.
• 밀리초 단위의 에포크 시간 값 (예: 1377047323000
• ISO 8601 표준 국제 날짜 형식으로 표시된 날짜: YYYY-MM-DD형식 등2013-09-12 . 이 형식으로 표현된 날짜의 경우:
  • 지정된 날짜 범위는 UTC로 해석됩니다.
  • 주어진 날짜의 시간은 지정된 날짜의 자정 ( 00:00:00 ) 으로 해석됩니다.
• 기준 날짜: to및from값 중 하나를 다른 값과 비교하여d (일), (시간), hm (분) 또는 로 표현할 수 있습니다. s (초). 예:
  • from=2015-01-01&to=31d
  • from=-48h&to=now
  • from=-2d&to=now (이전 예제와 동일한 결과를 제공합니다)
  • from=-365d&to=2015-12-31
  • from=-10m&to=now

페이징 결과

limit는 반환할 항목 수입니다 (기본값: 25, 최대: 200). offset건너뛸 항목 수입니다 (기본값: 0). limit및 를offset함께 사용하여 결과를 단계별로 보여주는 앱을 만들 수 있습니다. 각 항목에는 전체 결과에 대한 반복을 설정하는 데 사용할 수 있는limitoffsetcount. , 및 가 포함됩니다. 예를 들어 JavaScript에서는 다음과 같이 필요한 총 반복을 얻을 수 있습니다.

// response is the JSON-parsed response from the first request
var totalRequests = Math.ceil(response.count / response.limit)

보기 이벤트 검색

계정에서 뷰 이벤트를 검색하려면 view_events 리소스에GET요청을 수행하십시오.

https://audience.api.brightcove.com/v1/accounts/{account_id}/view_events

다음은 cURL의 샘플 요청입니다.

curl -i https://audience.api.brightcove.com/v1/accounts/{account_id}/view_events?where=video_id==123&from=-5d&to=now&sort=-created_at \
  -H "Authorization: Bearer {token}"

{
"count": 27,
"limit": 25,
"offset": 0,
"result": [
		{
				"created_at": "2016-04-25T18:30:21.651Z",
				"page_url": "https://players.brightcove.net/1486906377/V1s6NOwRx_default/index.html?videoId=4842718056001",
				"player_id": "V1s6NOwRx",
				"time_watched": 2,
				"updated_at": "2016-04-25T18:30:21.651Z",
				"video_id": "4842718056001",
				"video_name": "Horses Heading to the Track",
				"watched": 19
		},
		{
				"created_at": "2016-04-25T18:31:55.071Z",
				"page_url": "https://players.brightcove.net/1486906377/BkgFuzyhg_default/index.html?videoId=4842718056001",
				"player_id": "BkgFuzyhg",
				"time_watched": 15,
				"updated_at": "2016-04-25T18:32:00.879Z",
				"video_id": "4842718056001",
				"video_name": "Horses Heading to the Track",
				"watched": 99
		}, ...
}
]

필터링 및 선택 필드

모든매개변수함께 사용할 수 있습니다view_event요청합니다.

다음은 매개 변수를 사용하는 cURL의 샘플 요청입니다.

curl -i https://audience.api.brightcove.com/v1/accounts/{account_id}/view_events?where=video_id==123&from=-5d&to=now&sort=-created_at \
  -H "Authorization: Bearer {token}"

다음 필드가 지원됩니다. view_event필터링 시 요청where절 또는 a 중에 선택할 때fields절:

가망 고객 검색

계정에서 보기 이벤트를 검색하려면 다음을 수행하십시오. GET에 요청view_events자원:

https://audience.api.brightcove.com/v1/accounts/{account_id}/leads

{
"count": 2,
"limit": 25,
"offset": 0,
"result": [
		{
				"created_at": "2016-06-30T12:57:11.283Z",
				"email_address": "bbailey@brightcove.com",
				"first_name": "Bob",
				"last_name": "Bailey",
				"page_url": "https://players.brightcove.net/1486906377/Hk4TBqzL_default/index.html?videoId=4997275041001",
				"player_id": "Hk4TBqzL",
				"video_id": "4997275041001"
		},
		{
				"created_at": "2016-06-30T12:57:33.301Z",
				"email_address": "rcrooks@brightcove.com",
				"first_name": "Robert",
				"last_name": "Crooks",
				"page_url": "https://players.brightcove.net/1486906377/Hk4TBqzL_default/index.html?videoId=4997275041001",
				"player_id": "Hk4TBqzL",
				"video_id": "4997275041001"
		}
]
}

필터링 및 선택 필드

모든매개변수함께 사용할 수 있습니다leads요청합니다.

다음은 매개 변수를 사용하는 cURL의 샘플 요청입니다.

curl -i https://audience.api.brightcove.com/v1/accounts/{account_id}/leads?where=video_id==123&from=-5d&to=now&sort=-created_at \
  -H "Authorization: Bearer {token}"

다음 필드가 지원됩니다. leads필터링 시 요청where절 또는 a 중에 선택할 때fields절: