개요: 오디언스 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 , 이는client_id과client_secret API 요청과 함께 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는 “비디오 ID = 1234 또는 5678, 비디오 이름 = 테스트”로 해석됩니다.

반환할 필드 선택

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

fields=field1,field4

예:

fields=video_id,video_name

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

날짜 범위

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

• 현재 시간을now나타내는 텍스트 값
• 밀리초 단위의 에포크 시간 값 (예: 1377047323000
• ISO 8601 표준 국제 날짜 형식으로 표현된 날짜YYYY-MM-DD형식 (예2013-09-12 : 형식) 이 형식으로 표현된 날짜의 경우:
  • 지정된 날짜 범위는 UTC로 해석됩니다.
  • 날짜 제공 시간은 지정된 날짜에 자정 ( 00:00:00 ) 로 해석됩니다
• 상대 날짜: to및from값 중 하나를d (일), h (시간) 에 다른 값을 기준으로 표현할 수 있습니다., m (분) 또는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, 최대: 100). offset은 건너 뛸 항목 수입니다 (기본값: 0). limit및 를offset함께 사용하여 결과를 페이지하는 앱을 만들 수 있습니다. 각각은limit , offset , 및count.전체 결과에 대한 반복을 설정하는 데 사용할 수 있습니다. 예를 들어 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": "http://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": "http://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절 또는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": "http://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": "http://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절 또는fields절: