YouTube Data API 개요

소개

이 문서는 YouTube와 상호작용하는 애플리케이션을 작성하려는 개발자를 위해 작성되었습니다. YouTube와 API의 기본 개념을 설명합니다. 또한 API가 지원하는 다양한 기능에 대한 개요를 제공합니다.

시작하기 전에

  1. Google API 콘솔에 액세스하고 API 키를 요청하고 애플리케이션을 등록하려면 Google 계정이 필요합니다.

  2. 애플리케이션에서 API 요청을 제출할 수 있도록 Google Developers Console에서 프로젝트를 만들고 인증 사용자 인증 정보를 가져옵니다.

  3. 프로젝트를 만든 후 YouTube Data API가 애플리케이션에서 사용하도록 등록된 서비스 중 하나인지 확인하세요.

    1. API 콘솔로 이동하여 방금 등록한 프로젝트를 선택합니다.
    2. 사용 설정된 API 페이지로 이동합니다. API 목록에서 YouTube Data API v3의 상태가 사용인지 확인합니다.

  4. 애플리케이션이 사용자 인증을 필요로 하는 API 메소드를 사용하는 경우 인증 가이드를 참조하여 OAuth 2.0 인증 구현 방법에 대해 알아보세요.

  5. 클라이언트 라이브러리를 선택하여 간편하게 API를 구현하세요.

  6. JSON (JavaScript Object Notation) 데이터 형식의 핵심 개념을 익힙니다. JSON은 임의의 데이터 구조를 간단한 텍스트로 표현하는 언어에 독립적인 일반적인 데이터 형식입니다. 자세한 내용은 json.org를 참조하세요.

리소스 및 리소스 유형

리소스는 고유 식별자를 갖는 개별 데이터 항목입니다. 아래 표는 API를 사용하여 상호작용할 수 있는 다양한 리소스 유형에 대해 설명합니다.

리소스
activity 특정 사용자가 YouTube 사이트에서 취한 행동에 대한 정보를 포함합니다. 활동 피드에 보고되는 사용자 작업에는 동영상 평가, 동영상 공유, 동영상을 즐겨찾기에 추가, 채널 게시판에 게시 등이 포함됩니다.
channel 단일 YouTube 채널에 대한 정보를 포함합니다.
channelBanner 새로 업로드한 이미지를 채널의 배너 이미지로 설정하는 데 사용할 URL을 식별합니다.
channelSection 채널에서 추천하기로 선택한 동영상 모음에 대한 정보를 포함합니다. 예를 들어 섹션에 채널의 최신 업로드 동영상, 가장 인기 있는 업로드 동영상 또는 하나 이상의 재생목록의 동영상을 표시할 수 있습니다.
guideCategory YouTube가 채널의 콘텐츠 또는 기타 지표(예: 인기도)를 기준으로 채널에 연결하는 카테고리를 식별합니다. 가이드 카테고리는 YouTube 사용자가 원하는 콘텐츠를 더 쉽게 찾을 수 있도록 채널을 구성하는 데 목적이 있습니다. 채널은 한 개 이상의 가이드 카테고리에 연결될 수 있지만 가이드 카테고리에 모두 포함된다고는 할 수 없습니다.
i18nLanguage YouTube 웹사이트에서 지원하는 애플리케이션 언어를 식별합니다. 애플리케이션 언어를 UI 언어라고도 합니다.
i18nRegion YouTube 사용자가 기본 콘텐츠 지역으로 선택할 수 있는 지역을 식별합니다. 콘텐츠 지역을 콘텐츠 언어라고도 합니다.
playlist 단일 YouTube 재생목록을 나타냅니다. 재생목록은 순서대로 감상하거나 다른 사용자와 공유할 수 있는 동영상의 모음입니다.
playlistItem 재생목록에 포함된 동영상과 같은 리소스를 식별합니다. playlistItem 리소스에는 포함된 리소스가 재생목록에서 사용되는 방식을 설명하는 세부정보도 포함되어 있습니다.
search result API 요청에 지정된 검색 매개변수와 일치하는 YouTube 동영상, 채널 또는 재생목록의 정보를 포함합니다. 검색 결과는 동영상과 같이 고유하게 식별할 수 있는 리소스를 보여주지만, 자체적으로는 영구적인 데이터를 가지지 않습니다.
subscription YouTube 사용자 구독 정보가 포함됩니다. 구독정보는 채널에 새 동영상이 추가되거나 다른 사용자가 YouTube에서 동영상 업로드, 동영상 평가 또는 동영상 추천 등의 작업 중 하나를 수행할 때 이를 알려줍니다.
thumbnail 하나의 리소스에 연결된 미리보기 이미지를 식별합니다.
video 단일 YouTube 동영상을 표시합.
videoCategory 업로드된 동영상과 연결되었거나 연결할 수 있는 카테고리를 식별합니다.
watermark 지정된 채널의 동영상을 재생하는 동안 표시되는 이미지를 식별합니다. 또한 채널 소유자는 이미지가 연결되는 대상 채널과 동영상 재생 중 워터마크가 표시되는 시점과 워터마크가 표시되는 시간을 결정하는 타이밍 세부정보를 지정할 수도 있습니다.

대부분의 경우 리소스에는 다른 리소스에 대한 참조가 포함되어 있습니다. 예를 들어 playlistItem 리소스의 snippet.resourceId.videoId 속성은 결과적으로 동영상에 대한 전체 정보를 포함하는 동영상 리소스를 식별합니다. 또 다른 예로 검색 결과에는 특정 동영상, 재생목록, 채널 리소스를 식별하는 videoId, playlistId, channelId 속성이 포함됩니다.

지원되는 작업

다음 표는 API가 지원하는 가장 일반적인 메서드를 보여줍니다. 일부 리소스는 해당 리소스에 보다 특정한 기능을 수행하는 다른 메서드도 지원합니다. 예를 들어 videos.rate 메서드는 사용자 평가를 동영상에 연결하고 thumbnails.set 메서드는 YouTube에 동영상 썸네일 이미지를 업로드하여 동영상에 연결합니다.

운영
list 0개 이상의 리소스 목록을 검색(GET)합니다.
insert 새 리소스를 만듭니다(POST).
update 요청에 포함된 데이터를 반영하도록 기존 리소스를 수정(PUT)합니다.
delete 특정 리소스를 삭제(DELETE)합니다.

현재 API는 지원되는 각각의 리소스 유형을 나열하는 메소드를 지원하며 여러 리소스에 대한 쓰기 작업도 지원합니다.

아래 표에는 다양한 유형의 리소스에 지원되는 작업이 나와 있습니다. 리소스를 삽입, 업데이트, 삭제하는 작업에는 항상 사용자 승인이 필요합니다. 경우에 따라 list 메서드가 승인된 요청과 승인되지 않은 요청을 모두 지원합니다. 승인되지 않은 요청은 공개 데이터만 검색하는 반면 인증된 요청은 현재 인증된 사용자에 관한 정보를 검색하거나 이 사용자에게만 정보를 제공할 수도 있습니다.

지원되는 작업
list insert update delete
activity
caption
channel
channelBanner
channelSection
comment
commentThread
guideCategory
i18nLanguage
i18nRegion
playlist
playlistItem
search result
subscription
thumbnail
video
videoCategory
watermark

할당량 사용

YouTube Data API는 할당량을 사용하여 개발자가 의도한 대로 서비스를 사용하고 서비스 품질을 부당하게 낮추거나 다른 사용자의 액세스를 제한하는 애플리케이션을 만들지 않도록 합니다. 잘못된 요청을 포함한 모든 API 요청에는 최소한 1포인트 할당량 비용이 발생합니다. API Console에서 애플리케이션에서 사용할 수 있는 할당량을 확인할 수 있습니다.

YouTube Data API를 사용 설정하는 프로젝트에는 일일 10,000단위의 기본 할당량이 할당되며, 이는 대다수의 API 사용자에게 충분한 용량입니다. 기본 할당량은 변경될 수 있으며, 할당량 할당을 최적화하고 API 사용자에게 보다 의미 있는 방식으로 인프라를 확장하는 데 도움이 됩니다. API 콘솔의 할당량 페이지에서 할당량 사용량을 확인할 수 있습니다.

참고: 할당량 한도에 도달하면 할당량 확장을 완료하면 요청 양식을 작성해 주세요.

할당량 사용 계산

Google에서는 각 요청에 비용을 할당하여 할당량 사용을 계산합니다. 다양한 유형의 할당량 비용이 다릅니다 예를 들면 다음과 같습니다.

  • 채널, 동영상, 재생목록 등 일반적으로 리소스 목록을 검색하는 읽기 작업입니다. 1단위입니다.
  • 리소스를 생성, 업데이트 또는 삭제하는 쓰기 작업에는 일반적으로 비용이 듭니다. 50개 단위.
  • 검색 요청에는 100단위가 사용됩니다.
  • 동영상 업로드 가격은 1600단위입니다.

API 요청의 할당량 비용 표에는 할당량 비용입니다. 이러한 규칙을 염두에 두고 애플리케이션이 할당량을 초과하지 않고 하루에 전송할 수 있는 전송량을 확인할 수 있습니다

부분 리소스

API는 애플리케이션이 불필요한 데이터를 전송, 파싱, 저장하는 것을 방지하기 위해 부분 리소스 검색을 허용하며 실제로 필요로 합니다. 이 방법을 통해 API가 네트워크, CPU, 메모리 리소스를 더 효율적으로 사용할 수도 있습니다.

API는 다음 섹션에서 설명하는 두 개의 요청 매개변수를 지원합니다. 이를 통해 API 응답에 포함되어야 하는 리소스 속성을 식별할 수 있습니다.

  • part 매개변수는 리소스에 대해 반환해야 하는 속성 그룹을 식별합니다.
  • fields 매개변수는 요청된 리소스 부분 내에서 특정 속성만 반환하도록 API 응답을 필터링합니다.

part 매개변수 사용 방법

part 매개변수는 리소스를 검색하거나 반환하는 모든 API 요청의 필수 매개변수입니다. 매개변수는 API 응답에 포함되어야 하는 하나 이상의 최상위 수준 (비중첩) 리소스 속성을 식별합니다. 예를 들어 video 리소스는 다음과 같은 부분으로 구성됩니다.

  • snippet
  • contentDetails
  • fileDetails
  • player
  • processingDetails
  • recordingDetails
  • statistics
  • status
  • suggestions
  • topicDetails

이러한 부분은 모두 중첩된 속성을 포함하는 객체이며, 이러한 객체는 API 서버가 검색하거나 검색하지 않을 수 있는 메타데이터 필드의 그룹으로 생각할 수 있습니다. 따라서 part 매개변수를 사용하려면 애플리케이션에서 실제로 사용하는 리소스 구성요소를 선택해야 합니다. 이 요구사항은 두 가지 주요 용도로 사용됩니다.

  • API가 애플리케이션에서 사용하지 않는 메타데이터 필드를 검색하는 데 시간을 소비하지 않도록 함으로써 지연 시간을 줄여줍니다.
  • 애플리케이션에서 검색할 수 있는 불필요한 데이터양을 줄이거나 없앰으로써 대역폭 사용량을 감소시킵니다.

리소스가 점점 더 많은 부분을 추가하게 되면 애플리케이션에서 지원하지 않는 새로 정의된 속성을 요청하지 않게 되므로 이와 같은 장점은 더 커질 것입니다.

fields 매개변수 사용 방법

fields 매개변수는 part 매개변수 값에서 식별된 리소스 부분만 포함하는 API 응답을 필터링하여 응답에 특정 필드 집합만 포함합니다. fields 매개변수를 사용하면 API 응답에서 중첩된 속성을 삭제하여 대역폭 사용량을 더욱 줄일 수 있습니다. part 매개변수는 응답의 중첩된 속성을 필터링하는 데 사용할 수 없습니다.

다음 규칙은 대략적으로 XPath 문법을 기반으로 하는 fields 매개변수 값에 지원되는 문법을 설명합니다.

  • 여러 필드를 선택하려면 쉼표로 구분된 목록 (fields=a,b)을 사용합니다.
  • 별표 (fields=*)를 와일드 카드로 사용하여 모든 필드를 식별합니다.
  • API 응답에 포함될 중첩된 속성 그룹을 지정하려면 괄호 (fields=a(b,c))를 사용합니다.
  • 중첩된 속성을 식별하려면 슬래시 (fields=a/b)를 사용합니다.

실제로 이러한 규칙을 사용하면 여러 개의 다른 fields 매개변수 값을 사용하여 동일한 API 응답을 검색할 수 있는 경우가 많습니다. 예를 들어 재생목록 항목 ID, 제목, 재생목록에 있는 모든 항목의 위치를 검색하려는 경우 다음 값 중 하나를 사용할 수 있습니다.

  • fields=items/id,playlistItems/snippet/title,playlistItems/snippet/position
  • fields=items(id,snippet/title,snippet/position)
  • fields=items(id,snippet(title,position))

참고: 모든 쿼리 매개변수 값과 마찬가지로 fields 매개변수 값도 URL로 인코딩되어야 합니다. 이 문서의 예시에는 보기 쉽도록 인코딩이 생략되어 있습니다.

부분 요청 샘플

아래 예는 part 및 fields 매개변수를 사용하여 API 응답이 애플리케이션에서 사용하는 데이터만 포함하도록 하는 방법을 보여줍니다.

  1. 예 1은 4개 부분과 kind 및 etag 속성을 포함하는 동영상 리소스를 반환합니다.
  2. 예 2는 kind 및 etag 속성과 두 부분을 포함하는 동영상 리소스를 반환합니다.
  3. 예 3은 두 부분을 포함하지만 kind 및 etag 속성을 제외하는 동영상 리소스를 반환합니다.
  4. 예 4는 2개의 부분을 포함하지만 kind 및 etag는 물론 리소스의 snippet 객체에 있는 일부 중첩된 속성은 제외하는 동영상 리소스를 반환합니다.
를 통해 개인정보처리방침을 정의할 수 있습니다. <ph type="x-smartling-placeholder">
</ph> <ph type="x-smartling-placeholder">
</ph>
예 1
URL: https://www.googleapis.com/youtube/v3/videos?id=7lCDEYXw3mM&key=YOUR_API_KEY
     &part=snippet,contentDetails,statistics,status

Description: This example retrieves a video resource and identifies several
             resource parts that should be included in the API response.

API response:


{ 
 "kind": "youtube#videoListResponse",
 "etag": "\"UCBpFjp2h75_b92t44sqraUcyu0/sDAlsG9NGKfr6v5AlPZKSEZdtqA\"",
 "videos": [
  {
   "id": "7lCDEYXw3mM",
   "kind": "youtube#video",
   "etag": "\"UCBpFjp2h75_b92t44sqraUcyu0/iYynQR8AtacsFUwWmrVaw4Smb_Q\"",
   "snippet": { 
    "publishedAt": "2012-06-20T22:45:24.000Z",
    "channelId": "UC_x5XG1OV2P6uZZ5FSM9Ttw",
    "title": "Google I/O 101: Q&A On Using Google APIs",
    "description": "Antonio Fuentes speaks to us and takes questions on working with Google APIs and OAuth 2.0.",
    "thumbnails": {
     "default": {
      "url": "https://i.ytimg.com/vi/7lCDEYXw3mM/default.jpg"
     },
     "medium": {
      "url": "https://i.ytimg.com/vi/7lCDEYXw3mM/mqdefault.jpg"
     },
     "high": {
      "url": "https://i.ytimg.com/vi/7lCDEYXw3mM/hqdefault.jpg"
     }
    },
    "categoryId": "28"
   },
   "contentDetails": {
    "duration": "PT15M51S",
    "aspectRatio": "RATIO_16_9"
   },
   "statistics": {
    "viewCount": "3057",
    "likeCount": "25",
    "dislikeCount": "0",
    "favoriteCount": "17",
    "commentCount": "12"
   },
   "status": {
    "uploadStatus": "STATUS_PROCESSED",
    "privacyStatus": "PRIVACY_PUBLIC"
   }
  }
 ]
}
 드림
<ph type="x-smartling-placeholder">
</ph>
예 2
URL: https://www.googleapis.com/youtube/v3/videos?id=7lCDEYXw3mM&key=YOUR_API_KEY
     &part=snippet,statistics

Description: This example modifies the part parameter value so that the
             contentDetails and status properties are not included
             in the response.

API response:


{ 
 "kind": "youtube#videoListResponse",
 "etag": "\"UCBpFjp2h75_b92t44sqraUcyu0/sDAlsG9NGKfr6v5AlPZKSEZdtqA\"",
 "videos": [
  {
   "id": "7lCDEYXw3mM",
   "kind": "youtube#video",
   "etag": "\"UCBpFjp2h75_b92t44sqraUcyu0/iYynQR8AtacsFUwWmrVaw4Smb_Q\"",
   "snippet": { 
    "publishedAt": "2012-06-20T22:45:24.000Z",
    "channelId": "UC_x5XG1OV2P6uZZ5FSM9Ttw",
    "title": "Google I/O 101: Q&A On Using Google APIs",
    "description": "Antonio Fuentes speaks to us and takes questions on working with Google APIs and OAuth 2.0.",
    "thumbnails": {
     "default": {
      "url": "https://i.ytimg.com/vi/7lCDEYXw3mM/default.jpg"
     },
     "medium": {
      "url": "https://i.ytimg.com/vi/7lCDEYXw3mM/mqdefault.jpg"
     },
     "high": {
      "url": "https://i.ytimg.com/vi/7lCDEYXw3mM/hqdefault.jpg"
     }
    },
    "categoryId": "28"
   },
   "statistics": {
    "viewCount": "3057",
    "likeCount": "25",
    "dislikeCount": "0",
    "favoriteCount": "17",
    "commentCount": "12"
   }
  }
 ]
}
 드림
<ph type="x-smartling-placeholder">
</ph>
예 3
URL: https://www.googleapis.com/youtube/v3/videos?id=7lCDEYXw3mM&key=YOUR_API_KEY
     &part=snippet,statistics&fields=items(id,snippet,statistics)

Description: This example adds the fields parameter to remove all
             kind and etag properties from the API response.

API response:


{ 
 "videos": [
  {
   "id": "7lCDEYXw3mM",
   "snippet": { 
    "publishedAt": "2012-06-20T22:45:24.000Z",
    "channelId": "UC_x5XG1OV2P6uZZ5FSM9Ttw",
    "title": "Google I/O 101: Q&A On Using Google APIs",
    "description": "Antonio Fuentes speaks to us and takes questions on working with Google APIs and OAuth 2.0.",
    "thumbnails": {
     "default": {
      "url": "https://i.ytimg.com/vi/7lCDEYXw3mM/default.jpg"
     },
     "medium": {
      "url": "https://i.ytimg.com/vi/7lCDEYXw3mM/mqdefault.jpg"
     },
     "high": {
      "url": "https://i.ytimg.com/vi/7lCDEYXw3mM/hqdefault.jpg"
     }
    },
    "categoryId": "28"
   },
   "statistics": {
    "viewCount": "3057",
    "likeCount": "25",
    "dislikeCount": "0",
    "favoriteCount": "17",
    "commentCount": "12"
   }
  }
 ]
}
 드림
<ph type="x-smartling-placeholder">
</ph>
예 4
URL: https://www.googleapis.com/youtube/v3/videos?id=7lCDEYXw3mM&key=YOUR_API_KEY
     &fields=items(id,snippet(channelId,title,categoryId),statistics)&part=snippet,statistics

Description: This example modifies the fields parameter from example 3
             so that in the API response, each video resource's snippet
             object only includes the channelId, title,
             and categoryId properties.

API response:


{ 
 "videos": [
  {
   "id": "7lCDEYXw3mM",
   "snippet": { 
    "channelId": "UC_x5XG1OV2P6uZZ5FSM9Ttw",
    "title": "Google I/O 101: Q&A On Using Google APIs",
    "categoryId": "28"
   },
   "statistics": {
    "viewCount": "3057",
    "likeCount": "25",
    "dislikeCount": "0",
    "favoriteCount": "17",
    "commentCount": "12"
   }
  }
 ]
}

성능 최적화

ETags 사용

HTTP 프로토콜의 표준 부분인 ETags를 사용하면 애플리케이션이 특정 API 리소스의 특정 버전을 참조할 수 있습니다. 리소스는 전체 피드일 수도 있고 해당 피드의 항목일 수도 있습니다. 이 기능은 다음과 같은 경우에 사용할 수 있습니다.

  • 캐싱 및 조건부 검색 – 애플리케이션에서 API 리소스 및 infoType을 캐시할 수 있습니다. 그런 다음, 애플리케이션이 저장된 리소스를 다시 요청할 때 해당 리소스와 연결된 ETag를 지정합니다. 리소스가 변경된 경우 API는 수정된 리소스 및 해당 리소스 버전과 연결된 ETag를 반환합니다. 리소스가 변경되지 않은 경우 API는 리소스가 변경되지 않았음을 나타내는 HTTP 304 응답 (Not Modified)을 반환합니다. 애플리케이션에서 이와 같은 방법으로 캐시된 리소스를 제공함으로써 지연 시간 ㅁㅣㅊ 대역폭 사용량을 줄일 수 있습니다.

    Google API용 클라이언트 라이브러리는 서로 다른 infoType을 지원합니다. 예를 들어 JavaScript 클라이언트 라이브러리는 If-Match 및 If-None-Match를 포함하는 허용된 요청 헤더에 대한 허용 목록을 통해 ETag를 지원합니다. 화이트리스트를 사용하면 정상적인 브라우저 캐싱이 발생할 수 있으므로, 리소스의 이그레스가 변경되지 않은 경우 브라우저 캐시에서 리소스를 제공할 수 있습니다. 반면 Obj-C 클라이언트는 ETags를 지원하지 않습니다.

  • 의도하지 않은 변경사항 덮어쓰기로부터 보호 – infoType은 여러 API 클라이언트가 실수로 서로의 변경사항을 덮어쓰지 않도록 합니다. 리소스를 업데이트하거나 삭제할 때 애플리케이션에서 리소스의 ETag를 지정할 수 있습니다. ETag가 리소스의 가장 최신 버전과 일치하지 않는 경우 API 요청은 실패합니다.

애플리케이션에 ETags를 사용함으로써 얻을 수 있는 장점은 다음과 같습니다.

  • API가 캐시되었지만 변경되지 않은 리소스 요청에 더 빨리 응답하기 때문에 지연 시간이 줄어들고 대역폭 사용량이 감소합니다.
  • 애플리케이션에서 실수로 다른 API 클라이언트에서 만들어진 리소스에 변경사항을 덮어쓰는 일이 발생하지 않습니다.

Google APIs Client Library for JavaScript는 If-Match 및 If-None-Match HTTP 요청 헤더를 지원하므로 일반적인 브라우저 캐싱의 컨텍스트 내에서 eEtrebes가 작동할 수 있습니다.

gzip 사용

gzip 압축을 사용하여 각 API 응답에 필요한 대역폭을 줄일 수도 있습니다. 애플리케이션에서 API 응답의 압축을 풀기 위해 추가 CPU 시간이 필요하지만 일반적으로 보다 적은 네트워크 리소스를 사용함으로써 얻는 장점이 CPU 시간 추가로 인한 비용을 능가합니다.

gzip으로 인코딩된 응답을 받으려면 다음 두 작업을 수행해야 합니다.

  • Accept-Encoding HTTP 요청 헤더를 gzip로 설정합니다.
  • gzip 문자열을 포함하도록 사용자 에이전트를 수정합니다.

아래 샘플 HTTP 헤더에서 gzip 압축 사용 설정에 필요한 이러한 요구사항을 확인할 수 있습니다.

Accept-Encoding: gzip
User-Agent: my program (gzip)