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 (자바스크립트 객체 표기법) 데이터 형식의 핵심 개념을 숙지합니다. 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 단위 비용이 발생합니다.
  • 검색 요청 비용은 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 매개변수는 응답에서 중첩된 속성을 필터링하는 데 사용할 수 없습니다.

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

  • 쉼표로 구분된 목록 (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는 2개의 부분과 kind 및 etag 속성을 포함하는 동영상 리소스를 반환합니다.
  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)