개요 : Audience API

제품 (들)
Video Cloud
역할
API 개발자
주제
API 개요
Audience/ 마케팅 자동화
아피스)
Audience API

이 항목에서는 Audience API. 그만큼 Audience API 보기 이벤트 및 리드 데이터를 검색 할 수 있습니다.

API 참조

또한 API 참조.

기본 URL

의 기본 URL Audience API 입니다

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

계정 경로

모든 경우에있어 요청은 특정 Video Cloud 계정. 기본 URL에 항상 "계정"다음에 계정 ID를 추가해야합니다.

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

인증

고더드 우주 비행 센터 (Goddard Space Flight Center)에서 선택한 Audience API 를 사용하여 Brightcove OAuth 서비스 호출을 인증합니다.

먼저 클라이언트 자격 증명 (a client_id 그리고, client_secret). 이 작업은 일회성 작업으로 OAuth 자격증 명 UI. 에 대한 권한이 필요합니다. Audience/ 읽기 작업 :

필요한 사용 권한
필요한 사용 권한

클라이언트 자격 증명은에서 직접 얻을 수 있습니다. Brightcove OAuth 서비스 사용 or 우편 집배원.

또한 access_token, client_id 그리고, client_secret 귀하의 API 요청과 함께 Authorization 헤더가 전달되었습니다.

Authorization: Bearer {access_token}

고더드 우주 비행 센터 (Goddard Space Flight Center)에서 선택한 access_token 5 분 후에 만료되므로 각 요청에 대해 하나를 얻거나 토큰이 유효한지 확인해야합니다. 만나다 액세스 토큰 얻기 코드 샘플을 포함하여 토큰에 액세스하는 방법에 대한 자세한 설명은

속도 제한

API 사용은 다음으로 제한됩니다.

  • 계정 당 초당 50 개 요청
  • IP 주소 당 초당 50 개 요청

캐싱

API 응답은 대략 5 분 동안 캐시됩니다. 캐시에서 응답을 검색했는지 여부를 식별하려면 X-Cache 동등한 헤더 HIT 응답이 캐시 된 경우 또는 MISS 캐시되지 않은 경우.

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Date: Wed, 29 Jun 2016 20:40:07 GMT
X-Cache: MISS
Content-Length: 8178
Connection: keep-alive

오류 처리

오류가 발생하면 API는 다음 상태 코드 중 하나와 응답 본문의 해당 오류 코드 중 하나로 응답합니다.

상태 코드 에러 코드 설명
400 BAD_REQUEST_ERROR 검색어 매개 변수가 잘못되었습니다.
401 UNAUTHORIZED_ERROR 액세스 토큰이 없거나 만료되었거나 유효하지 않습니다.
404 RESOURCE_NOT_FOUND URL이 존재하지 않습니다.
429 REQUEST_THROTTLED_ERROR 사용자가 속도 제한 정책을 초과했습니다.
500 INTERNAL_ERROR 내부 오류가 발생했습니다.
504 GATEWAY_TIMEOUT_ERROR 요청을 수행하는 동안 서버 시간이 초과되었습니다.

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

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

매개 변수

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

결과 필터링

다음을 사용하여 결과를 필터링 할 수 있습니다. where 매개 변수. 필터 구문은 다음과 같습니다.

where=field1==value1;field2==value2

예 :

where=video_id==123456789;video_name==test

쉼표는 논리적 AND 및 세미콜론으로 논리적 AND로 처리됩니다. 예를 들어, where=video_id==1234,5678;video_name=test "video_id = 1234 또는 5678, video_name = test"로 해석됩니다.

반환 할 필드 선택

요청의 필드 목록은 결과를 필드의 서브 세트로 제한 할 수 있습니다. 필드 구문은 다음과 같습니다.

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 (일), 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

페이징 결과

고더드 우주 비행 센터 (Goddard Space Flight Center)에서 선택한 limit 반환 할 항목 수입니다 (기본값 : 25, 최대 : 100). offset 건너 뛸 항목 수입니다 (기본값 : 0). 당신이 사용할 수있는 limit 그리고, offset 함께 결과를 페이지로 표시하는 앱을 만듭니다. 각각은 limit, offsetcount.전체 결과에 대해 반복을 설정하는 데 사용할 수 있습니다. 예를 들어 JavaScript에서는 다음과 같이 필요한 총 반복 횟수를 얻을 수 있습니다.

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

뷰 이벤트 가져 오기

계정의보기 이벤트를 검색하려면 GET view_events 자원에 대한 요청 :

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 절:

분야 설명
VIDEO_ID Brightcove 동영상 ID
video_name Brightcove 동영상 이름
추적 ID 맞춤 추적 ID
external_id Marketo, Eloqua 또는 사용자 정의 GUID
player_id ID Brightcove 뷰 이벤트를 만든 플레이어
page_url 뷰 이벤트가 작성된 페이지의 URL
보았다 시청률
time_watched 시청 된 동영상의 초
created_at 작성 날짜
updated_at 최종 업데이트 날짜
is_synced 뷰 이벤트가 동기되고 있는지 어떤지를 나타내는 boolean 치
event_1 맞춤 이벤트
event_2
event_3
metric_1 맞춤 측정 항목
metric_2
metric_3

리드 검색

계정의보기 이벤트를 검색하려면 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 절:

분야 설명
VIDEO_ID Brightcove 동영상 ID
external_id Marketo, Eloqua 또는 사용자 정의 GUID
player_id ID Brightcove 뷰 이벤트를 만든 플레이어
page_url 뷰 이벤트가 작성된 페이지의 URL
created_at 작성 날짜
이메일 주소 납의 이메일 주소
이름 제공된 경우 납의 이름
LAST_NAME 제공된 경우 납의 성
비즈니스 용 폰 제공되는 경우 전화 번호
국가 제공된 경우 납의 나라
회사 이름 제공되는 경우 리드의 회사
산업 리드가 제공된 경우 해당 산업이 속합니다.