Introducción
Este documento está dirigido a programadores que deseen crear aplicaciones que puedan interactuar con YouTube. Aquí se explican conceptos básicos de YouTube y de la API. También proporciona una visión general de las diferentes funciones que la API admite.
Antes de comenzar
-
Necesitas una cuenta de Google para acceder a la Consola de la API de Google, solicitar una clave de API y registrar tu aplicación.
-
Registra tu aplicación en Google para que pueda enviar solicitudes de API.
-
Después de registrar tu aplicación, selecciona la API de datos de YouTube como uno de los servicios que utiliza tu aplicación:
- Ve a la consola de la API y selecciona el proyecto que acabas de registrar.
- Haz clic en el panel Servicios.
- En la lista de las API, busca la API de datos de YouTube y cambia el estado a
ON
.
-
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.
Recursos | |
---|---|
activity |
Contiene información sobre una acción que un usuario en particular realizó en el sitio de YouTube. Entre las acciones de los usuarios que se informan en los feeds de actividad se incluyen: calificar videos, compartir videos, marcar un video como favorito, publicar el boletín de un canal, etc. |
channel |
Contiene información sobre un solo canal de YouTube. |
channelBanner |
Identifica la dirección URL que se va a usar para configurar una imagen recién cargada como la imagen de banner de un canal. |
guideCategory |
Identifica una categoría que YouTube asocia con los canales según su contenido u otros indicadores, como la popularidad. El objetivo de las categorías de guía es organizar los canales de una manera que facilite a los usuarios de YouTube encontrar el contenido que buscan. Si bien los canales podrían estar asociados con una o varias categorías de guía, no se garantiza que vayan a estar en alguna de estas categorías. |
playlist |
Representa una lista de reproducción de YouTube. Una lista de reproducción es una colección de videos que se pueden ver de manera sucesiva y compartir con otros usuarios. |
playlistItem |
Identifica un recurso, como por ejemplo un video, que forma parte de una lista de reproducción. El recurso playlistItem también contiene detalles que explican cómo se utiliza el recurso incluido en la lista de reproducción. |
search result |
Un resultado de búsqueda contiene información acerca de un video, canal o lista de reproducción de YouTube que coincide con los parámetros de búsqueda especificados en una solicitud de la API. Si bien un resultado de búsqueda apunta a un recurso único de identificación, como un video, no tiene sus propios datos persistentes. |
subscription |
Contiene información sobre la suscripción de un usuario de YouTube. Una suscripción notifica al usuario cuando se agregan nuevos videos a un canal o cuando otro usuario realiza una de varias acciones en YouTube, como subir un video, calificar un video o comentar un video. |
thumbnail |
Identifica imágenes en miniatura asociadas a un recurso. |
video |
Representa un video de YouTube. |
videoCategory |
Identifica una categoría que se asoció o podría asociarse a videos subidos. |
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 toda la información del video. En otro ejemplo, un resultado de búsqueda contiene una propiedad videoId
, playlistId
o channelId
, que identifica un video, una lista de reproducción o recursos 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 a un video.
Operaciónes | |
---|---|
list |
Recupera (GET ) una lista de cero o más recursos. |
insert |
Crea (POST ) un nuevo recurso. |
update |
Modifica (PUT ) un recurso existente para reflejar los datos de tu solicitud. |
delete |
Elimina un (DELETE ) recurso específico. |
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 de list
admiten solicitudes tanto autorizadas como no autorizadas. Entonces, las solicitudes no autorizadas solo recuperan datos públicos, mientras que las solicitudes autorizadas pueden obtener información pública o privada del usuario autenticado actualmente.
Operaciones admitidas | ||||
---|---|---|---|---|
list | insert | update | delete | |
activity |
||||
caption |
||||
channel |
channelBanner |
|||
channelSection |
||||
comment |
||||
commentThread |
||||
guideCategory |
||||
i18nLanguage |
||||
i18nRegion |
||||
playlist |
||||
playlistItem |
search result |
|||
subscription |
||||
thumbnail |
||||
video |
||||
videoCategory |
||||
watermark |
Uso de cuota
La YouTube Data API utiliza una cuota para garantizar que los programadores usen el servicio según lo previsto y no creen aplicaciones que reduzcan injustamente la calidad del servicio o limiten el acceso de las demás personas. Puedes encontrar la cuota disponible para tu aplicación en el panel de API console's Cuotas.
Google calcula el uso de tu cuota mediante la asignación de un costo a cada solicitud, pero el costo no es el mismo para cada solicitud. Hay dos factores principales que influyen en el costo de la cuota de una solicitud:
-
Diferentes tipos de operaciones tienen diferentes costos de cuotas.
- Una operación de lectura simple que solo recupera el ID de cada recurso devuelto tiene un costo de aproximadamente
1
unidad. - Una operación de escritura tiene un costo de aproximadamente
50
unidades. - Subir un video tiene un costo de aproximadamente
1600
unidades.
- Una operación de lectura simple que solo recupera el ID de cada recurso devuelto tiene un costo de aproximadamente
-
Las operaciones de lectura y escritura utilizan diferentes cantidades de cuota, según el número de partes de los recursos que recupera cada solicitud. Ten en cuenta que las operaciones
insert
yupdate
escriben datos y también muestran un recurso. Entonces, por ejemplo, la inserción de una lista de reproducción tiene un costo de cuota de 50 unidades por la operación de escritura más el costo del recurso mostrado de lista de reproducción.Como se explica en la sección siguiente, cada recurso de API se divide en partes. Por ejemplo, un recurso de
playlist
tiene dos partes,snippet
ystatus
, mientras que un recurso dechannel
tiene seis partes y un recurso devideo
tiene 10. Cada parte contiene un grupo de propiedades relacionadas, y los grupos están diseñados de manera que tu aplicación solo necesita recuperar los tipos de datos que realmente utiliza.Una solicitud de API que muestra datos de recursos debe especificar las partes de los recursos que la solicitud recupera. Cada parte agrega aproximadamente
2
unidades al costo de la cuota de la solicitud. Como tal, una solicitud devideos.list
que solo recupera la partesnippet
de cada video podría tener un costo de3
unidades. Sin embargo, una solicitud devideos.list
que recupera todas las partes de cada recurso podría tener un costo aproximado de21
unidades de cuota.
Con estas reglas en mente, se puede estimar el número de solicitudes de lectura, escritura o subida que tu aplicación podría enviar al día sin exceder la cuota. Por ejemplo, si tienes una cuota diaria de 5.000.000 de unidades, tu aplicación podría tener cualquiera de los siguientes límites aproximados:
- 1.000.000 de operaciones de lectura, donde cada una recupera dos partes de recursos.
- 50.000 operaciones de escritura y 450.000 operaciones de lectura adicionales, donde cada una recupera dos partes de recursos.
- 2.000 subidas de video, 7.000 operaciones de escritura y 200.000 operaciones de lectura, donde cada una recupera tres partes de recursos.
Importante: La recuperación de solamente las partes de recursos que necesita tu aplicación permite conservar tu cuota diaria y hace que todo el sistema sea más eficiente.
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 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 devuelva solo las propiedades específicas dentro de las partes de los recursos solicitados.
Qué es el parámetro part
El parámetro part
es obligatorio para cualquier solicitud de 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 de video
tiene las siguientes partes:
snippet
contentDetails
fileDetails
player
processingDetails
recordingDetails
statistics
status
suggestions
topicDetails
Todas estas partes son objetos que contienen propiedades anidadas, y puedes considerar estos objetos como grupos de campos de metadatos que el servidor de la API podría (o no) recuperar. Como tal, el parámetro part
requiere que selecciones los componentes de recursos que tu aplicación realmente usa. Este requisito tiene varios propósitos:
- Te permite administrar el uso de tu cuota de API. Cuando aumenta el número de partes que se recuperan en las respuestas de la API, tu uso de la API aumenta en consecuencia, y tu cuota disponible disminuye.
- Se reduce la latencia al impedir que el servidor de la API se dedique a recuperar campos de metadatos que tu aplicación no utiliza.
- Se reduce el uso de ancho de banda al reducir (o eliminar) la cantidad de datos innecesarios que la aplicación puede recuperar.
Con el tiempo, a medida que los recursos agregan más partes, estos beneficios solo aumentan dado que tu aplicación no va a solicitar propiedades recién introducidas que no admite.
Qué es el parámetro fields
El parámetro fields
filtra la respuesta de la API, que solo contiene las part
es de los recursos identificados en el valor del parámetro part
, de modo que la respuesta solo incluye un conjunto específico de campos. El parámetro fields
permite eliminar propiedades anidadas de una respuesta de la API para reducir aún más el uso de ancho de banda. (El parámetro part
no se puede utilizar para filtrar propiedades anidadas de una respuesta).
Las siguientes reglas explican la sintaxis admitida para el valor del parámetro fields
, que se basa libremente en la sintaxis de 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, a menudo estas normas permiten que diferentes valores del parámetro fields
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 consulta, el valor del parámetro fields
debe estar codificado como dirección URL. Para facilitar la lectura, los ejemplos de este documento omiten la codificación.
Solicitudes parciales de ejemplo
En los ejemplos siguientes se muestra cómo se pueden utilizar los parámetros part
y fields
para garantizar que las respuestas de la API incluyan solo los datos que utiliza la aplicación:
- En el ejemplo 1, se muestra un recurso de video que incluye cuatro partes, además de las propiedades
kind
yetag
. - En el ejemplo 2, se muestra un recurso de video que incluye dos partes, además de las propiedades
kind
yetag
. - En el ejemplo 3, se muestra un recurso de video que incluye dos partes, pero excluye las propiedades
kind
yetag
. - En el ejemplo 4, se muestra un recurso de video que incluye dos partes, pero excluye las propiedades
kind
yetag
, además de algunas propiedades anidadas en el objetosnippet
del recurso.
URL: https://www.googleapis.com/youtube/v3/videos?id=7lCDEYXw3mM&key=YOUR_API_KEY
&part=snippet,contentDetails,statistics,status Descripción: en este ejemplo se recupera un recurso devideo
y se identifican varias partes de los recursos que se deben incluir en la respuesta de la API. Respuesta de la API:{ "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 Descripción: En este ejemplo se modifica el valor del parámetropart
para que las propiedadescontentDetails
ystatus
no se incluyan en la respuesta. Respuesta de la API:{ "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) Descripción: En este ejemplo se agrega el parámetrofields
para eliminar todas las propiedadeskind
yetag
de la respuesta de la API. Respuesta de la API:{ "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 Descripción: En este ejemplo se modifica el parámetrofields
del ejemplo 3 para que en la respuesta de la API cada objetosnippet
del recurso de video incluya solo las propiedadeschannelId
,title
ycategoryId
. Respuesta de la API:{ "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
Uso de ETags
Las ETags, parte estándar del protocolo HTTP, permiten que las aplicaciones se refieran a una versión determinada de un recurso de API en particular. El recurso puede ser un feed completo o un elemento de dicho feed. Esta funcionalidad admite los siguientes casos de uso:
-
Almacenamiento en la memoria caché y recuperación condicional: la aplicación puede almacenar en la memoria caché los recursos de la API y sus ETags. Luego, cuando tu aplicación vuelve a solicitar un recurso almacenado, especifica la ETag asociada con ese recurso. Si el recurso cambió, la API muestra el recurso modificado y la ETag asociada con esa versión del recurso. Si el recurso no cambió, la API muestra una respuesta HTTP 304 (
Not Modified
), lo que indica que el recurso no cambió. Tu aplicación puede reducir la latencia y el uso de ancho de banda al servir recursos almacenados en la memoria caché de esta manera.Las bibliotecas cliente para las API de Google admiten ETags de maneras distintas. Por ejemplo, la biblioteca cliente JavaScript admite ETags a través de una lista blanca de encabezados de solicitudes permitidas que incluye
If-Match
eIf-None-Match
. La lista blanca permite el almacenamiento en la memoria caché del navegador normal, de modo que si la ETag del recurso no cambió, el recurso se puede publicar desde la caché del navegador. Por otro lado, el cliente Obj-C no admite ETags. -
Protección contra sobrescritura accidental de cambios: las ETags garantizan que los múltiples clientes de la API no sobrescriban accidentalmente los cambios del otro. Al actualizar o eliminar un recurso, tu aplicación puede especificar la ETag del recurso. Si la ETag no coincide con la versión más reciente de ese recurso, se produce un error en la solicitud de la API.
El uso de ETags en tu aplicación aporta varios beneficios:
- La API responde más rápidamente a las solicitudes de recursos en caché, pero sin cambios, lo que genera una menor latencia y un menor uso de ancho de banda.
- Tu aplicación no sobrescribirá accidentalmente los cambios en un recurso que se realizaron desde otro cliente de la API.
La Google APIs Client Library for JavaScript admite encabezados de solicitudes HTTP If-Match
e If-None-Match
, lo que permite que las ETags funcionen en el contexto de almacenamiento en la memoria caché del navegador normal.
Uso de gzip
También puedes reducir el ancho de banda necesario para cada respuesta de la API al habilitar la compresión gzip. Aunque tu aplicación va a necesitar tiempo adicional de CPU para descomprimir las respuestas de la API, el beneficio de consumir menos recursos de red suele ser mayor que el costo.
Para recibir una respuesta codificada como gzip debes hacer dos cosas:
- Establecer el encabezado de solicitud HTTP
Accept-Encoding
engzip
. - Modificar tu agente de usuario para que contenga la unidad
gzip
.
Los siguientes encabezados HTTP de ejemplo demuestran estos requisitos para habilitar la compresión gzip:
Accept-Encoding: gzip User-Agent: my program (gzip)