개요 : 잠재 고객 API

제품 (들)
비디오 클라우드
역할
API 개발자
주제
API 개요
청중 / 마케팅 자동화
아피스)
잠재 고객 API

이 주제에서는 잠재 고객 API에 대해 알아 봅니다. 잠재 고객 API를 사용하면보기 이벤트 및 리드 데이터를 검색 할 수 있습니다.

기본 URL

잠재 고객 API의 기본 URL은 다음과 같습니다.

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

계정 경로

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

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

인증

잠재 고객 API는 Brightcove를 사용합니다. OAuth 서비스 호출을 인증합니다.

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

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

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

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

권한 부여 : 무기명 {access_token}

그만큼 access_token 5 분 후에 만료되므로 각 요청에 대해 하나를 얻거나 토큰이 유효한지 확인해야합니다. 만나다 액세스 토큰 얻기 코드 샘플을 포함하여 토큰에 액세스하는 방법에 대한 자세한 설명은

속도 제한

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

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

캐싱

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

HTTP / 1.1 200 OK 콘텐츠 유형 : application / json; charset = utf-8 날짜 : Wed, 29 Jun 2016 20 : 40 : 07 GMT X-Cache : MISS 콘텐츠 길이 : 8178 연결 : 연결 유지

오류 처리

오류가 발생하면 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": "권한이 거부되었습니다"}]

매개 변수

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

결과 필터링

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

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

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

기간

날짜 범위는에서 지정할 수 있습니다. 제품가격 그리고, to 매개 변수이며 뷰 이벤트가 마지막으로 업데이트 된 날짜 (updated_at 필드)에 적용됩니다. 날짜 범위는 다음 형식으로 표시 할 수 있습니다.

  • 텍스트 값 지금 현재 시간을 나타내는
  • 에포크 시간 값 (밀리 초 단위) 1377047323000
  • ISO 8601 표준 국제 날짜 형식으로 표현 된 날짜 : YYYY-MM-DD 형식 2013-09-12. 이 형식으로 표시된 날짜의 경우 :
    • 지정된 모든 날짜 범위는 UTC로 해석됩니다.
    • 날짜 부여 시간은 자정으로 해석됩니다 ( 00 : 00 : 00) 지정된 날짜에
  • 상대 날짜 : 귀하는 to 그리고, 제품가격 다른 값과 관련된 값 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

페이징 결과

그만큼 제한 반환 할 항목 수입니다 (기본값 : 25, 최대 : 100). 오프셋 건너 뛸 항목 수입니다 (기본값 : 0). 당신이 사용할 수있는 제한 그리고, 오프셋 함께 결과를 페이지로 표시하는 앱을 만듭니다. 각각은 제한, 오프셋카운트.전체 결과에 대해 반복을 설정하는 데 사용할 수 있습니다. 예를 들어 JavaScript에서는 다음과 같이 필요한 총 반복 횟수를 얻을 수 있습니다.

// response는 첫 번째 요청에서 JSON으로 파싱 된 응답입니다. var totalRequests = Math.ceil (response.count / response.limit)

뷰 이벤트 가져 오기

계정의보기 이벤트를 검색하려면 바로 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 "권한 부여 : 무기명 {토큰}"

응답은 다음과 같이 보입니다.

{ "개수": 27, "제한": 25, "오프셋": 0, "결과": [{ "created_at": "2016-04-25T18 : 30 : 21.651Z", "page_url": "http : // players.idx ","player_id ":"V1486906377s1NOwRx ","time_watched ": 6,"updated_at ":"4842718056001-1-6T2 : 2016 : 04Z ", players.brightcove.net/25/V18s30NOwRx_default/index.html?videoId=21.651" '4842718056001-19-2016T04 : 25 : 18Z', 'page_url': 'http : //www.windowsfiles.jpa "updated_at": "31-55.071-1486906377T4842718056001 : 15 : 2016Z", " , "video_id": "04", "video_name": "트랙으로 향하는 말", "봤다": 25}, ...}]

필터링 및 선택 필드

모든 매개 변수 와 함께 사용할 수 있습니다. 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 "권한 부여 : 무기명 {토큰}"

다음 필드가 지원됩니다. view_event 필터링 할 때 요청 어디에 절에서 선택하거나 분야 절:

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

리드 검색

계정의보기 이벤트를 검색하려면 바로 요청 view_events 의지:

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

샘플 응답 :

{ "개수": 2, "제한": 25, "오프셋": 0, "결과": [{ "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 "}]}

필터링 및 선택 필드

모든 매개 변수 와 함께 사용할 수 있습니다. 연결 요청.

다음은 매개 변수를 사용하는 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 "권한 부여 : 무기명 {토큰}"

다음 필드가 지원됩니다. 연결 필터링 할 때 요청 어디에 절에서 선택하거나 분야 절:

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