YouTube Data API 개요

소개

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

시작하기 전에

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

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

  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 콘솔의 할당량 페이지에서 할당량 사용량을 확인할 수 있습니다.

참고: 할당량 한도에 도달하면 YouTube API 서비스의 할당량 확장 요청 양식을 작성하여 추가 할당량을 요청할 수 있습니다.

할당량 사용량 계산

Google은 각 요청에 비용을 할당하여 할당량 사용량을 계산합니다. 작업 유형에 따라 할당량 비용이 다릅니다. 예를 들면 다음과 같습니다.

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

API 요청의 할당량 비용 표에는 각 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 매개변수는 응답의 중첩된 속성을 필터링하는 데 사용할 수 없습니다.

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

  • 여러 필드를 선택하려면 쉼표로 구분된 목록 (fields=a,b)을 사용합니다.
  • 별표 (fields=*)를 와일드 카드로 사용하여 모든 필드를 식별합니다.
  • 괄호 (fields=a(b,c))를 사용하여 API 응답에 포함될 중첩된 속성 그룹을 지정합니다.
  • 중첩된 속성을 식별하려면 슬래시 (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 속성과 2개의 부분을 포함하는 동영상 리소스를 반환합니다.
  3. 예 3은 2개의 부분을 포함하지만 kind 및 etag 속성을 제외한 동영상 리소스를 반환합니다.
  4. 예 4는 2개의 부분을 포함하지만 kind 및 etag과 리소스의 snippet 객체에 있는 일부 중첩된 속성을 제외하는 동영상 리소스를 반환합니다.
예 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"
   }
  }
 ]
}
예 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"
   }
  }
 ]
}
예 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"
   }
  }
 ]
}
예 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 리소스 및 ETag를 캐시할 수 있습니다. 그런 다음 애플리케이션이 저장된 리소스를 다시 요청할 때 해당 리소스와 연결된 ETag를 지정합니다. 리소스가 변경된 경우 API는 수정된 리소스 및 해당 리소스 버전과 연결된 ETag를 반환합니다. 리소스가 변경되지 않은 경우 API는 리소스가 변경되지 않았음을 나타내는 HTTP 304 응답 (Not Modified)을 반환합니다. 애플리케이션에서 이와 같은 방법으로 캐시된 리소스를 제공함으로써 지연 시간 ㅁㅣㅊ 대역폭 사용량을 줄일 수 있습니다.

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

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

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

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

Google APIs Client Library for JavaScript는 If-Match 및 If-None-Match HTTP 요청 헤더를 지원하므로 ETag가 일반 브라우저 캐싱 컨텍스트 내에서 작동하도록 사용 설정합니다.

gzip 사용

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

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

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

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

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