지원 고객 지원 문의 | 시스템 상태 시스템 상태
페이지 내용

    개요: CMS API

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

    API 참조

    또한 참조 API 참조 .

    일반 정보

    기본 URL

    에 대한 기본 URL CMS API is :

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

    계정 경로

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

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

    인증

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

            Authorization: Bearer {access_token}

    access_tokenBrightcove OAuth서비스에서 가져와야 하는 임시 OAuth2 액세스 토큰입니다. 자세한 내용은 Brightcove 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 또는 Brightcove Learning Services에서 만든 샘플 앱 .)

    • 재생 목록 데이터 :

      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 , 갤러리, 플레이어 또는 네이티브 SDK.

    의 성능을 보장하기 위해Video Cloud시스템에 대한 동시 호출은 20 개 이하CMS API계정 당 허용됩니다. 액세스 빈도는 초당 요청 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내림차순. 다음 필드는 정렬에 유효합니다. name , reference_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 , name , description , 및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

    그만큼limitoffset매개 변수는 동영상과 재생 목록 모두에 사용할 수 있습니다.

    페이징 모범 사례

    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 . 그만큼POSTPATCH에 대한 작업CMS API/assets추가 및 업데이트에 사용할 수 있습니다. 원격 자산 . CMS API GET 작업은양자 모두수집 및 원격 자산.

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

    자산 운영에 대한 자세한 내용은 API 참조 .

    사용자 정의 필드 작업

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

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

    사용자 정의 필드 작업에 대한 자세한 내용은 API 참조 .

    폴더 작업

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

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

    폴더 작업에 대한 자세한 내용은 API 참조 .

    알림

    다음과 같은 경우 알림을받을 수 있습니다. video_change이벤트는 비디오 라이브러리에서 발생합니다. 알림은 지정한 URL로 전송되며 처리 할 수있는 응용 프로그램을 가리켜 야합니다. HTTP POST요청.

    알림 실패

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

    방화벽

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

    알림 작업

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

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

    알림 작업에 대한 자세한 내용은 API 참조 .