개요: CMS API

이 항목에서는 CMS API에 대한 개요를 볼 수 있습니다. 는 데이터에 대한 캐시되지 않은 읽기 액세스를CMS API제공합니다. 이 작업은 를 사용하여 비디오 및 재생 목록을 변경하고 데이터를 빠르게 읽고 올바른지 확인하기 때문에 시간에 민감한 게시 워크플로에 중요합니다. CMS API

API 참조

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

일반 정보

기본 URL

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

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

계정 경로

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

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

인증

요청 인증에는 다음이 필요합니다Authorization header .

        Authorization: Bearer {access_token}

access_token는Brightcove OAuth서비스에서 가져와야 하는 임시 OAuth2 액세스 토큰입니다. 자세한 내용은브라이트코브 OAuth 개요를 참조하십시오 .

클라이언트 자격 증명을 만드는 가장 쉬운 방법은 Brightcove Studio 관리 페이지를 사용하는 것입니다. 자세한 지침은 API 인증 자격 증명관리를 참조하십시오.

운영

클라이언트 자격 증명을 요청할 때 원하는 계정 액세스 또는 작업 유형을 지정해야 합니다. 다음은 에 대해 현재 지원되는 작업 목록입니다CMS API .

  • 비디오 데이터:

    video-cloud/video/read
    video-cloud/video/create
    video-cloud/video/update
    video-cloud/video/delete
    또는
    video-cloud/video/all
    video-cloud/video/assets/delete (디지털 마스터를 삭제하려는 경우에만 필요합니다. 할 수 없다 Studio에서 자격 증명을 만들 때 이 권한을 얻습니다. OAuth API 또는 브라이트코브 학습 서비스에서 만든샘플 앱을 통해 수행해야합니다.)

  • 플레이리스트 데이터:

    video-cloud/playlist/read
    video-cloud/playlist/create
    video-cloud/playlist/update
    video-cloud/playlist/delete
    또는
    video-cloud/playlist/all

  • 알림:
    • video-cloud/notifications/all ( 알림용 )

속도 제한

이렇게 하면CMS API데이터에 대한 캐시되지 않은 읽기 액세스가 가능합니다. 이 작업은 를 사용하여 비디오 및 재생 목록을 변경하고 데이터를 빠르게 읽고 올바른지 확인하기 때문에 시간에 민감한 게시 워크플로에 중요합니다. CMS API

대규모 런타임 사용 (예: CMS API트래픽이 많은 공개 웹 페이지의 비디오 액세스) 에는 적합하지 않습니다. 트래픽이 많은 애플리케이션의 경우, 갤러리Playback API , 플레이어 또는 Native SDK와 같은 캐시된 인터페이스를 사용해야 합니다.

Video Cloud시스템 성능을 보장하기 위해 계정당 동시CMS API통화는 20개를 초과할 수 없습니다. 액세스 빈도는 초당 요청 10 개 미만이어야합니다.

여러 애플리케이션을 하나의 계정에 통합하려는 경우 이러한 애플리케이션에는 동시 실행 제한 또는 속도 제한에 도달한 인스턴스를 처리하기CMS API위한 백오프 및 재시도 로직이 있어야 합니다.

속도 또는 동시성 한도를 초과하면429 - TOO_MANY_REQUESTS오류가 반환됩니다.

참조 ID 충돌

참조 ID의 고유성을 보장하기 위해 는 할당된 비디오에서 작업을 수행한 후 최대 3분 동안 ID를CMS API잠급니다. 이렇게 하면 실패한 요청을 너무 빨리 다시 시도하거나 이전에 할당된 비디오를 삭제한 후 참조 ID를 너무 빨리 다시 사용하려고 할 때 409 오류가 반환될 수 있습니다. 참조오류 메시지 참조상세 사항은.

비디오 자산 한도

동영상 당 저작물은 1,000 개로 제한됩니다. 자산에는 변환, 오디오 트랙, 텍스트 트랙 및 이미지와 디지털 마스터가 포함됩니다. 변환 및 이미지의 총 자산이 총 10-15 개를 초과하는 경우는 거의 없으므로 150 개 언어에 대한 별도의 오디오 트랙과 텍스트 트랙이 있어도 여전히 350 개 미만의 자산이있을 것입니다.

사용법에 대한 참고 사항

방법

현재 API는 다음 요청 유형을 지원합니다.

  • GET
  • POST
  • PATCH
  • PUT
  • DELETE

매개변수

모든 매개 변수는선택 사항이라는 점에유의하십시오. 별도로 명시된 경우를 제외하고 동영상 및 재생목록GET요청에는 적용됩니다.

GET 요청 매개 변수
매개 변수 설명
q 검색용 쿼리 문자열 - 자세한 내용은검색 구문을참조하십시오.
limit 반환할 동영상 수 - 1에서 100 사이의 정수여야 합니다. 기본값: 20
offset 건너뛸 동영상 수 (페이징 결과의 경우) 양의 정수여야 합니다. 기본값: 0
sort 정렬 기준이 되는 필드를 지정하는 문자열입니다. 내림차순으로-정렬하려면 부터 시작하십시오. 값이 제공된 경우 기본q정렬은 “점수" (검색 결과와 원래 쿼리의 관련성) 를 기준으로 합니다. 에q값을 지정하지 않은 경우 기본 정렬은updated_at내림차순입니다. 다음 필드는 정렬에 유효합니다. namereference_id , created_at , published_at , updated_at , schedule_starts_at , schedule_ends_at , state , plays_total , 및plays_trailing_week

브라이트코브CMS API에서 비디오를 검색하는 프로그래밍 방식을 제공합니다. Video Cloud 도서관.

비디오 데이터에 대한 기본 및 복합 검색을 수행하려면 다음q매개 변수를 사용합니다.

        https://cms.api.brightcove.com/v1/accounts/921483702001/videos?q={search terms}

비디오 검색 방법에 대한 자세한 내용은 비디오검색문서를 참조하십시오.

재생 목록의 경우 검색 문자열에 지원되는 값이 더 제한됩니다. 현재type , namedescription , 및 기준으로 검색할 수reference_id있습니다. 다음은 유효한 검색의 몇 가지 예입니다.

  • q=type:EXPLICIT
  • q=type:ACTIVATED_OLDEST_TO_NEWEST
  • q=type:ALPHABETICAL
  • q=bears+otters (이름, 설명 또는 참조 ID는 "곰"또는 "수달"을 포함해야 함)
  • q=%2Bname:bears+type:EXPLICIT (이름은 "곰"을 포함해야 함)

보다재생 목록 검색상세 사항은.

페이징 결과

limit 매개 변수를 사용하여 요청당 반환할 항목 수 (최대 100개) 를 지정합니다. 그런 다음 offset 매개 변수를 사용하여 보다 큰 결과 집합을 페이지로 이동할 수limit있습니다. offset는 건너뛸 항목 수입니다.

예를 들어 다음 검색에서는 총 결과 집합에 75개 이상의 비디오가 있다고 가정하고 전체 결과 집합의 비디오 51-75를 반환합니다.

        /videos?q=updated_at:2014-01-01..2014-06-30&limit=25&offset=50

limit및offset매개변수는 동영상과 재생목록 모두에 사용할 수 있습니다.

페이징 모범 사례

CMS API와 함께 진행되는 동시 수정 작업이있을 수 있으므로 결과 집합을 페이징 할 때 다음 단계를 따르는 것이 좋습니다.

  1. 검색결과 세트에 포함된 총 동영상 수를 count 요청하세요. 
          /accounts/578380111111/counts/videos?q=tags:nature
  2. limit 및 offset 매개 변수를 사용하여 결과 집합에서 데이터 그룹을 반환할 수 있습니다. 
          /accounts/578380111111/videos?q=tags:nature&limit=20&offset=50
  3. 일부 페이지에는 동영상이 20 개 미만일 수 있습니다. 첫 번째count요청에서와 같이 많은 동영상을 요청하면 결과 집합의 끝에 도달했음을 알 수 있습니다.

요약하자면 원래count요청한 것과 동일한 비디오 수를 얻을 때까지 페이지를 계속 검색하세요. 이 숫자는 과대평가된 편일 수 있기 때문입니다. 다음 사항을 요청하세요:

      count / page-size + 1 page

비디오 결과 정렬

매개 변수를 사용하여 결과 정렬sort=field_name방법을 지정합니다. 동영상과 재생목록을 모두 정렬할 수 있습니다. 다음 비디오 필드를 기준으로 정렬할 수 있습니다. [1-1]

  • name
  • reference_id
  • created_at
  • published_at
  • updated_at
  • schedule_starts_at (참고: 이 필드는정렬필드이고검색 필드는schedule.starts_at
  • schedule_ends_at (참고: 이 필드는정렬필드이고검색 필드는schedule.ends_at
  • state
  • plays_total[1-2]
  • plays_trailing_week[1-2]

참고 사항

  • [1-1] 비디오 검색 통화에 정렬 값을 제공하지않으면 결과가 관련성에 따라 정렬됩니다. 정렬 값을 제공하지 않으면GET화상 통화 결과는 다음을 기준으로 정렬됩니다. updated_at내림차순.
  • [1-2]정렬할 수 있습니다. plays_total또는plays_trailing_week , 그러나 이러한 필드는 결과에 포함되지 않습니다.

재생 목록 결과 정렬

다음 필드에서 재생 목록을 정렬 할 수 있습니다.

  • name
  • updated_at (기본)

모든 비디오 및 대용량 데이터 세트

계정의 모든 동영상 또는 많은 수의 동영상을 검색하는 경우 다음 사항에 유의해야 할 사항이 있습니다.

  1. 허용된 최대 값limit (100개) 을 사용하고 싶을 수도 있지만 API 요청 시간 초과 가능성을 최소화하려면 25개 이하로 동영상을 일괄적으로 검색하는 것이 좋습니다.
  2. 대용량 데이터 세트를 통해 페이징할 때 작업 중에 비디오 데이터가 업데이트되어 항목이 응답으로 이동될 수 있습니다.
    • 연속된 페이지에서 항목이 반복되는 것을 볼 수 있습니다.
    • 항목이 이전 응답 집합으로 이동함에 따라 누락되었을 수 있습니다.

    첫 번째 가능성을 설명하기 위해 동영상 검색을 완료한 후 앱에서 전체 항목 목록의 중복을 제거해야 합니다. 두 번째 가능성을 처리하려면 검색된 총 항목 수 (중복 제거 후) 를 예상 수와 비교 한 다음 요청을 다시 실행하여 last_modified_date (내림차순) 로 결과를 정렬해야합니다. 누락 된 항목을 선택하기 위해 둘 이상의 배치를 검색 할 필요가 없습니다.

  3. 반환된 결과를 적절하게 정렬하여 이전 항목에서 시나리오의 가능성을 줄일 수 있습니다. 검색관련성에따른 기본 정렬은 키워드, 태그 및 사용자 지정 필드 값의 조합을 찾는 복잡한 알고리즘을 기반으로 합니다. 여러 키워드, 태그 및/또는 사용자 정의 필드를 기반으로 비디오를 검색하는 경우 관련성을 기준으로 정렬하면 원하는 대로 정확하게 정렬할 수 있습니다. 하지만 동영상 전체를 검색하거나 대량의 동영상을 검색하려는 경우sort매개변수를 명시적으로 설정하면 반환되는 항목의 순서를 더 잘 제어할 수 있습니다.

비디오 작업

비디오 작업에는 다음이 포함됩니다.

  • 동영상 수 또는 검색 결과 가져 오기
  • 모든 비디오 가져 오기
  • ID 또는 참조 ID로 하나 이상의 동영상 가져 오기
  • 비디오 생성, 검색, 업데이트 및 삭제
  • 비디오 검색
  • 비디오 소스, 이미지 및 디지털 마스터 정보 얻기
  • 비디오가 속한 재생 목록 가져 오기
  • 모든 재생 목록에서 비디오 제거

비디오 작업에 대한 자세한 내용은 API 참조에서 확인할 수있습니다.

재생 목록 작업

재생 목록 작업에는 다음이 포함됩니다.

  • 재생 목록 수 얻기
  • 모든 재생 목록 가져 오기
  • 재생 목록 생성, 업데이트 및 삭제
  • 재생 목록의 동영상 개수 가져 오기
  • 재생 목록에서 비디오 가져 오기

재생 목록 작업에 대한 세부 정보는 API 참조에서 확인할 수있습니다.

자산

자산 작업을 통해 변환, 매니페스트, 이미지 및 텍스트 트랙을 포함한 자산을 관리 할 수 있습니다. 에셋을 인제스트하려면 를 사용해야 합니다Dynamic Ingest API . 그만큼POST그리고PATCH에 대한 작업CMS API/assets추가 및 업데이트에 사용할 수 있습니다. 원격 자산 . CMS API GET 작업은둘 다수집 및 원격 자산.

  • 변환 추가, 업데이트 또는 삭제
  • 디지털 마스터에 대한 메타 데이터 추가, 업데이트 또는 삭제
  • HLS와 같은 세그먼트 화 된 비디오 유형에 대한 매니페스트 추가, 업데이트 또는 삭제
  • 포스터 및 축소판 이미지 추가, 업데이트 또는 제거
  • WebVTT 텍스트 트랙 또는 DFXP 캡션 추가, 업데이트 또는 제거

자산 작업에 대한 세부 정보는 API 참조에서 확인할 수있습니다.

사용자 정의 필드 작업

현재 하나의 사용자 정의 필드 작업이 있습니다.

  • 계정에 대한 모든 사용자 정의 필드 가져 오기

사용자 지정 필드 작업에 대한 세부 정보는 API 참조에서 확인할 수있습니다.

폴더 작업

폴더 작업을 통해 다음을 수행 할 수 있습니다.

  • 폴더 목록 가져 오기
  • 폴더 생성, 업데이트 및 삭제
  • 폴더에있는 비디오 목록 가져 오기
  • 폴더에 비디오 추가
  • 폴더에서 비디오 제거

폴더 작업에 대한 세부 정보는 API 참조에서 확인할 수있습니다.

알림

비디오 라이브러리에서video-change이벤트가 발생할 때 알림을 받거나 마스터 비디오가 업데이트된 후 공유 비디오가 자산을 자동으로 업데이트하면master-video-change알림을 받을 수 있습니다. HTTP POST 요청을 처리할 수 있는 애플리케이션을 가리키는 URL로 알림이 전송됩니다.

알림 실패

알림 시스템은 고객 서버의 4xx 또는 5xx 반환을 재시도 가능한 오류로 처리합니다. 실패한 콜백은 최대 20 회까지 다시 시도되며 후속 콜백 간의 지연이 기하 급수적으로 증가합니다. 처음 몇 번의 재시도는 초기 콜백 시도 후 몇 분 이내에 발생합니다. 콜백이 계속 실패하고 20 번째 재시도로 나아갈 경우 재시도 지연은 며칠이 걸릴 것입니다.

방화벽

조직에 방화벽을 통해 들어오는 트래픽 소스에 대한 엄격한 정책이있는 경우 모든 AWS East 지역 IP를 허용합니다. 이는 변경될 수 있으므로 모든 AWS IP를 허용 목록에 추가해야 합니다. 보다 https://docs.aws.amazon.com/general/latest/gr/aws-ip-ranges.html자세한 내용은.

알림 작업

현재 알림에 사용할 수있는 작업은 다음과 같습니다.

  • 구독 생성
  • 하나 또는 모든 구독 받기
  • 구독 삭제

알림 작업에 대한 세부 정보는 API 참조에서 확인할 수있습니다.