이 페이지는 Cloud Translation API를 통해 번역되었습니다.

샘플 API 요청

이 페이지에서는 YouTube Data API에 대한 샘플 요청을 보여줍니다. YouTube Data API를 사용하면 동영상, 채널, 재생목록과 같은 YouTube 리소스를 검색하고 조작할 수 있습니다. 각 샘플은 Google API 탐색기에 연결하고 이를 채우므로 샘플을 실행하고 응답을 확인할 수 있습니다.

YouTube Data API를 사용한 콘텐츠 업로드에 대한 자세한 내용은 재개 가능한 업로드를 참조하세요.

개요

명확성을 위해 이 페이지의 샘플에서는 각 요청의 고유한 요소를 표시하고 Data API 요청을 처리하는 호스트 (https://www.googleapis.com/youtube/v3)의 기본 URL을 약어로 사용합니다. 샘플의 컨텍스트 외부에서 요청하려면 전체 URL을 포함해야 합니다.

예를 들어 다음은 이 페이지에 나타나는 요청의 예입니다.

GET {base-URL}/channels?part=contentDetails
                       &mine=true

이 요청의 전체 URL은 다음과 같습니다.

GET https://www.googleapis.com/youtube/v3/channels?part=contentDetails
                                                  &mine=true

일부 요청은 구독자 목록 등 YouTube 채널의 소유자만 액세스할 수 있는 데이터를 검색합니다. 채널 소유자가 Google API 탐색기를 대신하여 YouTube Data API 요청을 수행할 수 있는 권한을 부여해야 합니다. 비공개 채널 데이터에 대한 액세스 승인에 대한 자세한 내용은 OAuth 2.0 인증 구현을 참조하세요. API 탐색기에 연결한 후 OAuth 2.0을 사용하여 요청 승인 버튼을 클릭합니다. 이 단계에서는 API 탐색기가 소유자를 대신하여 요청할 수 있도록 승인합니다. 또한 API 탐색기에서 수행할 수 있는 요청 유형을 지정하는 승인 범위도 선택합니다.

각 요청에 대한 응답은 YouTube 리소스의 JSON 표현입니다. 요청의 part 매개변수는 응답의 어느 부분을 응답에 포함할지 지정합니다. 매개변수는 응답에 포함되어야 하는 하나 이상의 최상위 (비중첩) 리소스 속성을 식별합니다. 예를 들어 video 리소스 중 일부는 다음과 같습니다.

snippet
콘텐츠 세부정보
플레이어
statistics
status

이러한 모든 부분은 중첩된 속성이 포함된 객체이며, 이러한 객체를 API 서버가 검색하거나 가져올 수 없는 메타데이터 필드 그룹으로 생각할 수 있습니다. 따라서 part 매개변수를 사용하려면 애플리케이션이 실제로 사용하는 리소스 구성요소를 선택해야 합니다.자세한 내용은 YouTube Data API 시작하기를 참고하세요.

채널 정보 검색

이 요청은 channels.list 메서드를 사용하여 인증된 사용자에게 속한 채널의 세부정보를 검색합니다.

GET {base_URL}/channels?part=contentDetails
                       &mine=true

이 요청에 대한 응답에는 인증된 사용자의 채널에 대한 채널 ID와 contentDetails이 포함됩니다. contentDetails에는 채널과 관련된 시스템 생성 재생목록 여러 개가 포함됩니다. 대부분의 후속 요청에는 채널 ID 또는 재생목록 ID 중 하나가 필요하므로 이를 기록하는 것이 중요합니다.

{
  "id": {CHANNEL_ID},
  "kind": "youtube#channel",
  "etag": etag,
  "contentDetails": {
    "relatedPlaylists": {
      "likes": {LIKES_PLAYLIST_ID},
      "favorites": {FAVORITES_PLAYLIST_ID},
      "uploads": {UPLOADS_PLAYLIST_ID},
      "watchHistory": {WATCHHISTORY_PLAYLIST_ID},
      "watchLater": {WATCHLATER_PLAYLIST_ID}
    },
    "googlePlusUserId": string
  },
}

업로드된 동영상 및 시스템 생성 재생목록

YouTube는 업로드된 모든 동영상을 채널과 연결된 재생목록에 추가합니다. 업로드된 동영상 목록을 가져오려면 playlistItems.list 메서드를 사용하여 위에 표시된 채널 정보 응답에서 반환된 '업로드' 재생목록을 쿼리하여 해당 재생목록의 동영상을 검색합니다.

Google API 탐색기에서 다음 샘플 요청을 실행하기 전에 {UPLOADS_PLAYLIST_ID}를 이전 요청의 재생목록 ID로 바꿉니다.

GET {base_URL}/playlistItems?part=contentDetails
                            &playlistId={UPLOADS_PLAYLIST_ID}

반환된 각 항목의 "id" 값은 재생목록 항목 ID입니다. 재생목록 항목의 동영상 ID는 contentDetails 부분의 videoId입니다.

채널 정보 응답에서 해당 재생목록 ID를 대체하여 위 요청을 통해 사용자의 즐겨찾기, 좋아요, 시청 기록 또는 나중에 볼 동영상 목록을 검색할 수 있습니다.

사용자 제작 재생목록

이 요청은 playlists.list 메서드를 사용하여 인증된 채널과 연결된 재생목록을 검색합니다. 이 요청은 채널 정보 (업로드, 시청 기록 등)에 포함된 시스템 생성 재생목록을 검색하지 않습니다. 사용자가 만든 재생목록만 가져옵니다.

GET {base_URL}/playlists?part=snippet
                        &mine=true

재생목록 ID가 있으면 이전 섹션에 표시된 요청을 사용하여 재생목록에서 항목을 검색할 수 있습니다.

인증 없이 채널의 공개 재생목록에 대한 정보를 요청할 수 있습니다. 인증되지 않은 요청을 제출할 때는 애플리케이션의 고유 API 키를 지정하는 key 인수를 포함해야 합니다. 예를 들어 이 요청은 GoogleDevelopers 채널과 관련된 재생목록을 검색합니다.

GET {base_URL}/playlists?part=snippet
                        &channelId=UC_x5XG1OV2P6uZZ5FSM9Ttw
                        &key={YOUR_API_KEY}

구독 가져오기

subscription 리소스는 YouTube 사용자 (구독자)와 채널 간의 관계를 정의합니다. subscriptions.list 메서드는 요청에 포함된 매개변수에 따라 특정 채널의 구독자 또는 특정 사용자의 구독을 검색합니다.

채널 구독자

이 요청은 인증된 채널의 구독자 목록을 검색합니다.

GET {base_URL}/subscriptions?part=snippet
                            &mySubscribers=true

사용자 구독

구독자를 나열하는 동일한 메서드(subscriptions.list)를 사용하여 사용자가 구독하는 채널을 나열할 수 있습니다. 이 요청은 mine 매개변수를 사용하여 인증된 사용자가 구독하는 YouTube 채널 목록을 검색합니다.

GET {base_URL}/subscriptions?part=snippet
                            &mine=true

사용자 활동 가져오기

activity 리소스에는 동영상 업로드, 채널 구독 등 특정 채널 또는 사용자가 YouTube에서 취한 조치에 관한 정보가 포함되어 있습니다. activities.list 메서드는 요청 기준과 일치하는 채널 또는 사용자와 연결된 작업을 검색합니다. 예를 들어 특정 채널, 사용자의 구독 또는 사용자의 맞춤 YouTube 홈페이지와 관련된 작업을 검색할 수 있습니다.

특정 기간의 활동

이 요청은 인증된 사용자가 2013년 4월 동안 수행한 모든 작업을 검색합니다.

GET {base_URL}/activities?part=snippet,contentDetails
                         &mine=true
                         &publishedAfter=2013-04-01T00%3A00%3A00Z
                         &publishedBefore=2013-05-01T00%3A00%3A00Z

홈페이지 활동

이 요청은 인증된 사용자의 YouTube 홈페이지에 표시되는 맞춤 활동 피드를 검색합니다.

GET {base_URL}/activities?part=snippet,contentDetails
                         &home=true

YouTube 동영상 및 채널의 시청 통계, 인기도 측정항목, 인구통계 정보를 검색하려면 YouTube Analytics API를 사용합니다. 샘플 API 요청 페이지에는 YouTube 분석에서 일반적인 보고서를 가져오는 방법이 나와 있습니다.

검색

search.list 메서드를 사용하면 지정된 기준과 일치하는 YouTube 동영상, 채널 또는 재생목록을 검색할 수 있습니다. 동영상 속성, 키워드, 주제 (또는 조합)를 기준으로 검색할 수 있으며 생성일, 조회수, 평점 등의 요소를 토대로 검색결과를 정렬할 수도 있습니다.

다른 YouTube Data API 요청과 마찬가지로 search.list 메서드는 YouTube 리소스의 JSON 표현을 반환합니다. 하지만 다른 YouTube 리소스와 달리 검색결과는 고유 ID를 가진 영구 객체가 아닙니다.

대부분의 요청은 공개 콘텐츠를 검색하므로 인증이 필요하지 않습니다. 아래 샘플 중에서 특히 첫 번째는 '내' 동영상을 요청하므로 인증이 필요합니다. 인증되지 않은 요청을 제출할 때 애플리케이션의 고유한 API 키를 지정하는 key 인수를 포함해야 합니다.

많이 본 동영상

이 요청은 인증된 모든 사용자의 동영상을 검색하여 조회수를 기준으로 내림차순으로 나열합니다.

GET {base_URL}/search?part=snippet
                     &forMine=true
                     &order=viewCount
                     &type=video

퍼갈 수 있는 고화질 동영상

이 요청은 특정 속성을 가진 동영상, 즉 다른 사이트에 퍼갈 수 있는 고화질 동영상을 검색합니다. 결과는 내림차순으로 정렬됩니다.

GET {base_URL}/search?part=snippet
                     &order=rating
                     &type=video
                     &videoDefinition=high
                     &videoEmbeddable=true
                     &key={YOUR_API_KEY}

특정 주제에 관한 동영상

이 요청은 자막이 포함된 YouTube Data API에 대한 동영상에 대한 키워드 검색을 수행합니다.

GET {base_URL}/search?part=snippet
                     &q=YouTube+Data+API
                     &type=video
                     &videoCaption=closedCaption
                     &key={YOUR_API_KEY}

주제 기반 검색

특정 주제의 동영상을 검색하는 좀 더 정교한 방법은 키워드 대신 Freebase 주제를 사용하는 것입니다. YouTube 채널 및 동영상 리소스에는 모두 리소스와 연결된 Freebase 주제 ID의 목록이 포함된 topicDetails 객체가 포함되어 있습니다. Freebase 주제는 실제 컨셉 또는 사물의 모든 측면을 나타내기 때문에 주제 기반 검색은 키워드 검색보다 더 지능적입니다.

Freebase 주제를 사용하여 검색하려면 먼저 Freebase API를 사용하여 주제 ID를 가져와야 합니다. 이 요청은 주제 ID가 /m/05z1_인 Python용 Freebase 주제와 연결된 동영상을 반환합니다.

GET {base_URL}/search?part=snippet
                     &topicId=/m/05z1_
                     &type=video
                     &key={YOUR_API_KEY}

재생목록 또는 채널 검색

검색은 동영상에 국한되지 않습니다. 재생목록이나 채널을 검색할 수도 있습니다. 이 요청은 키워드 'soccer'와 일치하는 재생목록을 검색합니다.

GET {base_URL}/search?part=snippet
                     &q=soccer
                     &type=playlist
                     &key={YOUR_API_KEY}

축구 채널을 찾으려면 type 매개변수를 변경하면 됩니다.

GET {base_URL}/search?part=snippet
                     &q=soccer
                     &type=channel
                     &key={YOUR_API_KEY}

모든 축구 관련 콘텐츠 (채널, 재생목록, 동영상)를 보려면 범용 검색을 사용하세요. type 매개변수를 생략하면 요청이 모든 유형의 콘텐츠를 검색합니다.

GET {base_URL}/search?part=snippet
                     &q=soccer
                     &key={YOUR_API_KEY}

리소스 만들기 및 업데이트

지금까지 살펴본 요청은 모두 HTTP GET 메서드를 사용하여 YouTube 데이터를 검색합니다. YouTube Data API는 HTTP POST를 사용하여 동영상, 재생목록, 채널 등의 YouTube 리소스를 만들거나 업데이트하는 방법도 제공합니다. 다음 요청은 예를 보여줍니다.

POST 메서드에는 생성 또는 업데이트 중인 리소스의 JSON 표현인 Request body가 포함됩니다. 대화형 도구를 사용하여 Google API 탐색기에서 JSON 표현을 만들 수 있습니다.

구독 만들기

이 요청은 인증된 사용자를 GoogleDevelopers 채널을 구독합니다. 즉, 구독 리소스를 만듭니다.

POST {base_URL}/subscriptions?part=snippet
 Request body:
  {
    'snippet': {
      'resourceId': {
        'kind': 'youtube#channel',
        'channelId': 'UC_x5XG1OV2P6uZZ5FSM9Ttw' 
       }
     }
  }

재생목록 만들기

이 요청은 새 공개 재생목록을 만듭니다.

POST {base_URL}/playlists?part=snippet
 Request body:
  {
    'snippet': {
      'title': 'New playlist', 
      'description': 'Sample playlist for Data API',
     }
  }

재생목록에 동영상 추가하기

이제 재생목록을 만들었으므로 동영상을 추가해 보겠습니다. 이 요청은 재생목록('position': 0)의 시작 부분에 동영상을 추가합니다.

POST {base_URL}/playlistItems?part=snippet
  Request body:
  {
    'snippet': {
      'playlistId': '{PLAYLIST_ID}', 
      'resourceId': {
          'kind': 'youtube#video',
          'videoId': '{VIDEO_ID}'
        }
     'position': 0
      }
   }