Descripción general de la API de datos de YouTube

Introducción

Este documento está dirigido a programadores que deseen crear aplicaciones que puedan interactuar con YouTube. En él se explican conceptos básicos de YouTube y de la API. También proporciona una visión general de las diferentes funciones que admite la API.

Antes de comenzar

1. Necesitas una Cuenta de Google para acceder a la Consola de APIs de Google, solicitar una clave de API y registrar tu aplicación.

2. Crea un proyecto en Google Developers Console y obtén credenciales de autorización para que tu aplicación pueda enviar solicitudes a la API.

3. Después de crear tu proyecto, asegúrate de que la API de YouTube Data sea uno de los servicios para los que tu aplicación está registrada para utilizar:

   1. Ve a la Consola de API y selecciona el proyecto que acabas de registrar.
   2. Visita la página de APIs habilitadas. En la lista de las APIs, asegúrate de que el estado esté ACTIVADO para la versión 3 de la API de datos de YouTube.

4. Si tu aplicación va a utilizar cualquier método de API que requiera la autorización del usuario, lee la guía de autenticación para obtener información sobre cómo implementar la autorización OAuth 2.0.

5. Selecciona una biblioteca cliente para simplificar la implementación de la API.

6. Aprende los conceptos básicos del formato de datos JSON (JavaScript Object Notation). JSON es un formato de datos común e independiente del lenguaje que proporciona una representación de texto simple de estructuras de datos arbitrarias. Para obtener más información, visita la página json.org.

Recursos y tipos de recursos

Un recurso es una entidad de datos individual con un identificador exclusivo. En la tabla a continuación se describen los distintos tipos de recursos con los que puedes interactuar mediante la API.

Ten en cuenta que, en muchos casos, un recurso contiene referencias a otros recursos. Por ejemplo, la propiedad snippet.resourceId.videoId de un recurso playlistItem identifica un recurso de video que, a su vez, contiene información completa sobre el video. Otro ejemplo es el que un resultado de búsqueda contiene una propiedad videoId, playlistId o channelId que identifica un video, una playlist o un recurso de canal en particular.

Operaciones admitidas

En la siguiente tabla se muestran los métodos más comunes que la API admite. Algunos recursos también admiten otros métodos que realizan funciones más específicas para esos recursos. Por ejemplo, el método videos.rate asocia la calificación de un usuario con un video, y el método thumbnails.set sube una imagen en miniatura de un video a YouTube y la asocia con un video.

Actualmente, la API admite métodos para enumerar cada uno de los tipos de recursos admitidos y, del mismo modo, admite operaciones de escritura para muchos recursos.

En la siguiente tabla se identifican las operaciones admitidas para diferentes tipos de recursos. Las operaciones para insertar, actualizar o eliminar recursos siempre requieren la autorización del usuario. En algunos casos, los métodos list admiten solicitudes tanto autorizadas como no autorizadas, en las que las solicitudes no autorizadas solo recuperan datos públicos, mientras que las solicitudes autorizadas también pueden recuperar información o información privada del usuario autenticado actualmente.

Uso de cuota

El YouTube Data API usa una cuota para garantizar que los desarrolladores usen el servicio según lo previsto y no creen aplicaciones que reduzcan de manera injusta la calidad del servicio o limiten el acceso de otras personas. Todas las solicitudes a la API, incluidas las solicitudes no válidas, incurren en un costo de cuota de al menos un punto. Puedes encontrar la cuota disponible para tu aplicación en API Console.

Los proyectos que habilitan la API de datos de YouTube tienen una asignación de cuota predeterminada de 10,000 unidades por día, una cantidad suficiente para la inmensa mayoría de los usuarios de nuestra API. La cuota predeterminada, que está sujeta a cambios, nos ayuda a optimizar las asignaciones de cuotas y escalar nuestra infraestructura de una manera que sea más significativa para los usuarios de la API. Puedes ver tu uso de la cuota en la página Cuotas de la Consola de API.

Nota: Si alcanzas el límite de la cuota, puedes solicitar más cuota. finalizando el curso Extensión de cuota formulario de solicitud para los servicios de la API de YouTube.

Cómo calcular el uso de la cuota

Google calcula el uso de tu cuota asignando un costo a cada solicitud. Los diferentes tipos de las operaciones tienen diferentes costos de cuota. Por ejemplo:

• Operación de lectura que recupera una lista de recursos (canales, videos, playlists) y, por lo general, cuesta 1 unidad.
• Una operación de escritura que crea, actualiza o borra un recurso suele tener costos 50 unidades.
• Una solicitud de búsqueda cuesta 100 unidades.
• Subir un video cuesta 1600 unidades.

En la tabla Costos de cuota para solicitudes a la API, se muestra la el costo de cuota de cada método de la API. Con estas reglas en mente, puedes estimar la cantidad de solicitudes que tu aplicación podría enviar al día sin exceder tu cuota.

Recursos parciales

La API permite, y requiere, la recuperación de recursos parciales para que las aplicaciones eviten la transferencia, el análisis y el almacenamiento de datos que no son necesarios. Este enfoque también garantiza que la API utilice los recursos de red, CPU y memoria de manera más eficiente.

La API admite dos parámetros de solicitud, que se explican en las siguientes secciones, que te permiten identificar las propiedades de los recursos que se deben incluir en las respuestas de la API.

• El parámetro part identifica grupos de propiedades que se deben mostrar para un recurso.
• El parámetro fields filtra la respuesta de la API para que solo muestre propiedades específicas dentro de las partes de recursos solicitadas.

Cómo usar el parámetro part

El parámetro part es obligatorio para cualquier solicitud a la API que recupera o muestra un recurso. El parámetro identifica una o más propiedades de recursos de nivel superior (no anidada) que se deben incluir en una respuesta de la API. Por ejemplo, un recurso video tiene las siguientes partes:

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

Todas estas partes son objetos que contienen propiedades anidadas. Puedes considerar estos objetos como grupos de campos de metadatos que el servidor de la API podría (o no) recuperar. Por lo tanto, el parámetro part requiere que selecciones los componentes de recursos que tu aplicación usa realmente. Este requisito tiene dos propósitos clave:

• Reducir la latencia evitando que el servidor de la API se dedique a recuperar campos de metadatos que tu aplicación no utiliza.
• Reducir el uso de ancho de banda al reducir (o eliminar) la cantidad de datos innecesarios que la aplicación podría recuperar.

Con el tiempo, a medida que los recursos agregan más partes, estos beneficios irán en aumento debido a que tu aplicación no solicitará las propiedades nuevas que no admita.

Cómo usar el parámetro fields

El parámetro fields filtra la respuesta de la API, que solo contiene las partes de los recursos identificadas en el valor del parámetro part, de modo que la respuesta solo incluya un conjunto específico de campos. El parámetro fields te permite quitar propiedades anidadas de una respuesta de la API y, por lo tanto, reducir aún más el uso de ancho de banda. (El parámetro part no se puede usar para filtrar propiedades anidadas de una respuesta).

Las siguientes reglas explican la sintaxis admitida para el valor del parámetro fields, que se basa de manera general en la sintaxis XPath:

• Usa una lista separada por comas (fields=a,b) para seleccionar varios campos.
• Usa un asterisco (fields=*) como comodín para identificar todos los campos.
• Usa paréntesis (fields=a(b,c)) para especificar un grupo de propiedades anidadas que se incluirá en la respuesta de la API.
• Usa una barra diagonal (fields=a/b) para identificar una propiedad anidada.

En la práctica, estas reglas a menudo permiten que varios valores de parámetro fields diferentes recuperen la misma respuesta de la API. Por ejemplo, si deseas recuperar la ID de elemento de lista de reproducción, el título y la posición de todos los elementos de una lista de reproducción, puedes utilizar cualquiera de los siguientes valores:

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

Nota: Al igual que con todos los valores de los parámetros de búsqueda, el valor del parámetro de fields debe estar codificado como URL. Para facilitar la lectura, en los ejemplos de este documento se omite la codificación.

Solicitudes parciales de ejemplo

En los siguientes ejemplos, se muestra cómo puedes usar los parámetros part y fields para garantizar que las respuestas de la API solo incluyan los datos que usa tu aplicación:

1. En el ejemplo 1, se muestra un recurso de video que incluye cuatro partes, además de las propiedades kind y etag.
2. En el ejemplo 2, se muestra un recurso de video que incluye dos partes, además de las propiedades kind y etag.
3. En el ejemplo 3, se muestra un recurso de video que incluye dos partes, pero excluye las propiedades kind y etag.
4. En el ejemplo 4, se muestra un recurso de video que incluye dos partes, pero excluye kind y etag, además de algunas propiedades anidadas en el objeto snippet del recurso.

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"
   }
  }
 ]
}

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"
   }
  }
 ]
}

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"
   }
  }
 ]
}

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"
   }
  }
 ]
}

Optimización del rendimiento

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