El API de datos de YouTube permite a las aplicaciones realizar funciones que normalmente se ejecutan en el sitio web de YouTube. El API permite que tu aplicación busque vídeos de YouTube y recupere respuestas en vídeo, comentarios y feeds de vídeos estándar. Además, el API permite que tu aplicación suba vídeos a YouTube o actualice vídeos existentes. También puedes recuperar listas de reproducción, suscripciones, perfiles de usuario y mucho más. Finalmente, tu aplicación puede enviar solicitudes autenticadas que permitirán a los usuarios crear listas de reproducción, suscripciones, contactos y otras entidades específicas de cuentas.
Este documento está orientado a programadores que estén desarrollando aplicaciones cliente que interactúen con YouTube. En el documento se proporcionan ejemplos de operaciones básicas de API utilizando código XML y HTTP sin formato. Es posible que los desarrolladores Java y PHP prefieran consultar guías para desarrolladores específicas de un lenguaje determinado que expliquen cómo utilizar bibliotecas cliente Java o PHP para realizar funciones similares.
En este documento se supone que comprendes los principios generales del protocolo de API de datos de Google. Las API de datos de Google proporcionan un sencillo protocolo estándar para la lectura y escritura de datos en Internet. Las API de datos de Google están basadas en los formatos de sindicación Atom 1.0 y RSS 2.0, y en el Atom Publishing Protocol (APP).
Este documento consta de las siguientes secciones:
En la sección Autenticación se describen los dos métodos de autenticación disponibles para asociar operaciones de API a la cuenta de un usuario específico. En esta sección también se describen las diferencias entre el sistema de autenticación del API de datos de YouTube y otras API de datos de Google. A lo largo de este documento, las explicaciones de funciones de API específicas indicarán claramente si la función requiere la autenticación del usuario.
En la sección Entradas y feeds de vídeos se proporciona un ejemplo de respuesta de API y se explica cómo extraer información sobre un vídeo de una lista de vídeos o un conjunto de resultados de búsqueda. En esta sección también se explica cómo los elementos XML de una respuesta del API de datos de YouTube se corresponden con la información de vídeo que aparece normalmente en el sitio web de YouTube. En esta sección también se explica el formato de solicitud del API para actualizar una entrada de vídeo.
En la sección Recuperación y búsqueda de vídeos se explica cómo extraer una lista de vídeos. El API de datos de YouTube define varios tipos de feeds estándar, como los vídeos más valorados o los más vistos. En esta sección también se explica cómo recuperar una lista de vídeos subidos por un usuario específico o una lista de vídeos relacionados, que son vídeos que YouTube ha clasificado como similares a un vídeo en particular. Finalmente, en esta sección también se explica cómo utilizar el API para que los usuarios puedan realizar búsquedas en la biblioteca de vídeos de YouTube de vídeos que coincidan con categorías o términos de búsqueda específicos.
En la sección Subida de vídeos se explican brevemente dos formas de permitir que los usuarios suban vídeos a YouTube desde tu aplicación. En esta sección también se presentan diagramas de flujo de procesos de cada método de subida y se explica cómo funcionan estos métodos en combinación con el esquema de autenticación que estés utilizando.
Es posible que debas dejar a los usuarios subir vídeos para utilizar otras funciones del API. Por ejemplo, el API proporciona una función para añadir una respuesta en vídeo al vídeo. Sin embargo, si el usuario está subiendo un nuevo vídeo como una respuesta en vídeo, la aplicación cliente deberá seguir las instrucciones de subida de vídeos para añadir el vídeo a YouTube antes de identificar el nuevo vídeo como una respuesta a un vídeo existente.
En la sección Actualización y subida de vídeos se explica cómo permitir a un usuario actualizar o eliminar sus vídeos.
En la sección Uso de las funciones de la comunidad se describen funciones del API que permiten la interacción de los usuarios con los vídeos de YouTube. Estas funciones definen solicitudes de publicación de puntuaciones, comentarios, respuestas en vídeo o reclamaciones contra vídeos subidos al sitio. También puedes utilizar el API para recuperar listas de comentarios sobre vídeos o para recuperar o eliminar respuestas en vídeo.
En la sección Almacenamiento y recopilación de vídeos se explica cómo utilizar el API para crear, actualizar y acceder a vídeos favoritos, listas de reproducción de vídeos y suscripciones a canales de YouTube.
En la sección Habilitación de la interacción del usuario se explica cómo utilizar el API para la recuperación y actualización de perfiles de usuario. En esta sección también se explica cómo recuperar, añadir, actualizar y eliminar contactos de usuarios.
La autenticación permite a un usuario acceder a funciones de YouTube que vinculen contenido o información a una cuenta determinada de YouTube. Estas funciones requieren que el usuario o la aplicación proporcionen el nombre de usuario y la contraseña de YouTube para dicha cuenta. Por ejemplo, un usuario desea acceder a YouTube para subir un vídeo o añadir un comentario a un vídeo existente.
En este documento se describen varias funciones del API que requieren la autenticación del usuario, incluidas todas las funciones del API para crear, actualizar o eliminar cuentas.
Ten en cuenta que si implementas cualquier función que no requiera autenticación, te recomendamos que incluyas los encabezados de autenticación adecuados en todas las solicitudes, aunque dichas solicitudes no requieran la autenticación explícitamente.
Para realizar la autenticación correctamente, una solicitud debe incluir los encabezados X-GData-Key y Authorization. El encabezado X-GData-Key especifica tu clave de desarrollador, un valor que identifica de forma exclusiva a tus aplicaciones. El encabezado Authorization especifica el token que obtendrás por cada usuario mediante uno de los dos esquemas de autenticación, AuthSub o ClientLogin, que permiten a los usuarios acceder a funciones de YouTube específicas de cada cuenta. La siguiente lista te ayudará a seleccionar el esquema de autenticación más adecuado para tu aplicación.
La autenticación de proxy AuthSub permite a las aplicaciones web autenticar a los usuarios en sus cuentas de YouTube sin tener que acceder al nombre de usuario y la contraseña de YouTube. Debes utilizar la autenticación Authsub si deseas crear una aplicación web que permita a los usuarios vincular vídeos, comentarios, puntuaciones, contactos u otra información con sus propias cuentas de YouTube.
La autenticación ClientLogin te permitirá asociar todas las acciones del API con una única cuenta de YouTube. Si tu cliente es una aplicación instalada, independiente y para un solo usuario, como una aplicación de escritorio, utiliza la autenticación ClientLogin. En este caso, tu aplicación pedirá al usuario que introduzca su nombre de usuario y contraseña de YouTube y, a continuación, utilizará dichos valores para solicitar el token de autenticación de ClientLogin.
Nota: no debes crear nunca una aplicación web que implemente la autenticación ClientLogin y requiera que los usuarios introduzcan sus nombres de usuario y sus contraseñas. Si vas a crear una aplicación web que permita a los usuarios asociar acciones a sus cuentas de YouTube, utiliza la autenticación AuthSub.
Una clave de desarrollador identifica al desarrollador de YouTube que envía una solicitud del API. Una ID de cliente identifica tu aplicación con fines de depuración y registro. Consulta http://code.google.com/apis/youtube/dashboard/ para obtener una clave de desarrollador y una ID de cliente.
Al realizar una solicitud del API, utiliza el encabezado de solicitud X-GData-Key para especificar tu clave de desarrollador y el encabezado X-GData-Client para especificar tu ID de cliente, tal como se muestra en el siguiente ejemplo:
X-GData-Client: <client_id> X-GData-Key: key=<developer_key>
El proceso AuthSub se explica de forma más detallada en http://code.google.com/apis/accounts/AuthForWebApps.html. Además, debes tener en cuenta que la URL base y el valor de scope del servicio de autenticación AuthSub de YouTube – http://gdata.youtube.com – son diferentes de la URL y del valor de scope especificados en la documentación de AuthSub disponible online.
Para obtener un token de autenticación, envía una solicitud POST de HTTP a la siguiente URL:
|
https://www.google.com/accounts/AuthSubRequest?
next=http%3A%2F%2Fwww.example.com%2Fupload.html
&scope=http%3A%2F%2Fgdata.youtube.com
&session=0
&secure=0
La solicitud POST contiene los siguientes parámetros:
El parámetro next contiene la URL a la que se redirigirá al usuario después de iniciar sesión en YouTube.
El parámetro scope identifica el servicio al que el usuario te permitirá acceder en su nombre. El valor de este parámetro debe ser http://gdata.youtube.com.
El parámetro secure contiene un valor booleano (0 ó 1) que indica si el servicio de autenticación devolverá un token seguro o no seguro. Los tokens seguros se emiten sólo para sitios web registrados en Google, y las solicitudes del API de subida que utilicen un token seguro deben estar firmadas digitalmente. Consulta la documentación sobre AuthSub de Google para obtener información detallada sobre los tokens seguros.
El parámetro session contiene un valor booleano (0 ó 1) que indica si el token de autenticación de un solo uso que devuelve el servicio de autenticación se puede intercambiar por un token de sesión, que puede ser utilizado múltiples veces. Establece esta variable en 1 para indicar que el token de un solo uso se puede intercambiar por un token de sesión. Consulta la documentación sobre AuthSub de Google para obtener una explicación sobre cómo solicitar un token de sesión.
Después de que el usuario inicie sesión a través del servicio de autenticación de YouTube, YouTube redirigirá al usuario de nuevo a la URL identificada en el parámetro next de la solicitud de AuthSub. El redireccionamiento contiene un token de autenticación de un solo uso identificado por el parámetro token de la URL, tal como se muestra en el siguiente ejemplo. Si el valor del parámetro session de tu solicitud de AuthSub es 1, podrás intercambiar el token de uso único con un token de sesión mediante el envío de una solicitud AuthSubSessionToken.
La siguiente URL muestra cómo el parámetro token aparecerá en el redireccionamiento a tu sitio. Ten en cuenta que la URL del redireccionamiento se debería haber proporcionado como el valor del parámetro next en la solicitud de AuthSub.
http://www.example.com/upload.html?token=CKF50YzIHxCT85KMAg
Al realizar una solicitud del API autenticada mediante un token de autenticación de AuthSub, tu solicitud deberá especificar el encabezado de solicitud HTTP Authorization tal como se muestra en el ejemplo siguiente. Nota: En este documento, las solicitudes de ejemplo utilizan la sintaxis de AuthSub, a menos que se especifique lo contrario.
Authorization: AuthSub token=<authentication_token> X-GData-Key: key=<developer_key>
Para realizar una solicitud del API autenticada mediante ClientLogin, deberás identificar la cuenta del usuario de YouTube asociada a la solicitud. También debes utilizar el sistema ClientLogin de YouTube para la autenticación de un solo usuario. Deberás proporcionar el nombre de usuario y la contraseña de la cuenta del usuario de YouTube, comprobando que el usuario disponga de la autorización necesaria para realizar operaciones asociadas a dicha cuenta. Las acciones de autenticación pasarán a estar asociadas a dicha cuenta. Ten en cuenta que las siguientes instrucciones son ligeramente diferentes de las instrucciones estándar de ClientLogin.
Para obtener un token de autenticación, envía una solicitud POST de HTTP a la siguiente URL:
https://www.google.com/youtube/accounts/ClientLogin
Las siguientes directrices se aplican a la solicitud:
La solicitud POST debe especificar el valor application/x-www-form-urlencoded para el encabezado Content-Type.
El cuerpo de POST debe incluir una cadena en el siguiente formato:
Email=<youtube_username>&Passwd=<youtube_password>&service=youtube&source=<source>
Debes realizar los siguientes cambios en esta cadena:
Sustituye la cadena <youtube_username> por el nombre de usuario de la cuenta de YouTube del usuario.
Sustituye la cadena <youtube_password> por la contraseña de la cuenta de YouTube del usuario.
Sustituye la cadena <source> por una cadena breve que identifique tu aplicación para fines de registro.
Los valores <youtube_username>, <youtube_password> y <source> deben tener una codificación URL.
Google devolverá una respuesta con el token de autenticación que necesitarás para ejecutar operaciones del API asociadas a la cuenta de YouTube del usuario especificado. El token de autenticación será el valor Auth de dicha página. Además, el valor YouTubeUser de la página será el nombre de usuario de la cuenta de YouTube del usuario. Deberás extraer el token de autenticación y el nombre de usuario de la página y, a continuación, enviar estos valores en solicitudes del API. Ten en cuenta que los tokens de autenticación caducan periódicamente. Por tanto, es posible que tu aplicación deba repetir este proceso de autenticación y actualizar el valor del token de autenticación cuando éste caduque y sea rechazado.
Nota: En la documentación sobre ClientLogin de Google se explica cómo incorporar un desafío CAPTCHA a la aplicación mediante la autenticación ClientLogin.
Ejemplo de autenticación
Por ejemplo, supongamos que deseas autenticar una cuenta de YouTube cuyo nombre de usuario y contraseña son testuser y testpassword, respectivamente. Puede simular la solicitud POST de HTTP mediante el comando 'curl' de Linux, como se muestra en el siguiente ejemplo:
curl --location https://www.google.com/youtube/accounts/ClientLogin \
--data 'Email=testuser&Passwd=testpassword&service=youtube&source=TestLogin' \
--header 'Content-Type:application/x-www-form-urlencoded'
Si tu solicitud de autenticación tiene éxito, la respuesta para tu solicitud tendrá el siguiente formato. (Ten en cuenta que el valor del token Auth se ha acortado en el ejemplo).
Auth=AIwbFARksypDdUSGGYRI_5v7Z9TaijoPQqpIfCEjTFPAikn_---OC-I1VJtQ YouTubeUser=testuser
Al realizar una solicitud del API autenticada mediante un token de autenticación de ClientLogin, tu solicitud deberá especificar el encabezado de solicitud HTTP Authorization tal como se muestra en el ejemplo siguiente:
Authorization: GoogleLogin auth=<authentication_token> X-GData-Key: key=<developer_key>
Al recuperar un feed de vídeo o una lista de resultados de búsqueda, YouTube devuelve un feed Atom con una etiqueta <entry> por cada vídeo del conjunto de resultados. La etiqueta XML raíz de la respuesta será la etiqueta <feed>. Además de la información sobre los vídeos individuales del conjunto de resultados, el feed también contendrá el número total de resultados de la lista, el índice del primer elemento de la lista, el número de elementos de la lista y otros metadatos sobre el feed.
El siguiente código XML muestra el formato de una respuesta del API de datos de YouTube con un feed de vídeo:
<?xml version='1.0' encoding='UTF-8'?> <feed xmlns='http://www.w3.org/2005/Atom' xmlns:openSearch='http://a9.com/-/spec/opensearchrss/1.0/' xmlns:gml='http://www.opengis.net/gml' xmlns:georss='http://www.georss.org/georss' xmlns:media='http://search.yahoo.com/mrss/' xmlns:yt='http://gdata.youtube.com/schemas/2007' xmlns:gd='http://schemas.google.com/g/2005'> <id>http://gdata.youtube.com/feeds/api/standardfeeds/top_rated</id> <updated>2008-02-21T18:57:10.801Z</updated> <category scheme='http://schemas.google.com/g/2005#kind' term='http://gdata.youtube.com/schemas/2007#video'/> <title type='text'>Top Rated</title> <logo>http://www.youtube.com/img/pic_youtubelogo_123x63.gif</logo> <link rel='alternate' type='text/html' href='http://www.youtube.com/browser?s=tr'/> <link rel='http://schemas.google.com/g/2005#feed' type='application/atom+xml' href='http://gdata.youtube.com/feeds/api/standardfeeds/top_rated'/> <link rel='self' type='application/atom+xml' href='http://gdata.youtube.com/feeds/api/standardfeeds/top_rated?start_index=1&max-results=25'/> <link rel='self' type='application/atom+xml' href='http://gdata.youtube.com/feeds/api/standardfeeds/top_rated?start_index=26&max-results=25'/> <author> <name>YouTube</name> <uri>http://www.youtube.com/</uri> </author> <generator version='beta' uri='http://gdata.youtube.com/'>YouTube data API</generator> <openSearch:totalResults>99</openSearch:totalResults> <openSearch:startIndex>1</openSearch:startIndex> <openSearch:itemsPerPage>25</openSearch:itemsPerPage> <entry> <id>http://gdata.youtube.com/feeds/api/videos/ZTUVgYoeN_b</id> <published>2007-02-16T20:22:57.000Z</published> <updated>2007-02-16T20:22:57.000Z</updated> <category scheme="http://schemas.google.com/g/2005#kind" term="http://gdata.youtube.com/schemas/2007#video"/> <category scheme="http://gdata.youtube.com/schemas/2007/keywords.cat" term="Steventon"/> <category scheme="http://gdata.youtube.com/schemas/2007/keywords.cat" term="walk"/> <category scheme="http://gdata.youtube.com/schemas/2007/keywords.cat" term="Darcy"/> <category scheme="http://gdata.youtube.com/schemas/2007/categories.cat" term="Entertainment" label="Entertainment"/> <title type="text">My walk with Mr. Darcy</title> <content type="html"><div ... html content trimmed ...></content> <link rel="self" type="application/atom+xml" href="http://gdata.youtube.com/feeds/api/videos/ZTUVgYoeN_b"/> <link rel="alternate" type="text/html" href="http://www.youtube.com/watch?v=ZTUVgYoeN_b"/> <link rel="http://gdata.youtube.com/schemas/2007#video.responses" type="application/atom+xml" href="http://gdata.youtube.com/feeds/api/videos/ZTUVgYoeN_b/responses"/> <link rel="http://gdata.youtube.com/schemas/2007#video.ratings" type="application/atom+xml" href="http://gdata.youtube.com/feeds/api/videos/ZTUVgYoeN_b/ratings"/> <link rel="http://gdata.youtube.com/schemas/2007#video.complaints" type="application/atom+xml" href="http://gdata.youtube.com/feeds/api/videos/ZTUVgYoeN_b/complaints"/> <link rel="http://gdata.youtube.com/schemas/2007#video.related" type="application/atom+xml" href="http://gdata.youtube.com/feeds/api/videos/ZTUVgYoeN_b/related"/> <author> <name>Andy Samplo</name> <uri>http://gdata.youtube.com/feeds/api/users/andyland74</uri> </author> <media:group> <media:title type="plain">Shopping for Coats</media:title> <media:description type="plain"> What could make for more exciting video? </media:description> <media:keywords>Shopping, parkas</media:keywords> <yt:duration seconds="79"/> <media:category label="People" scheme="http://gdata.youtube.com/schemas/2007/categories.cat">People </media:category> <media:content url='http://www.youtube.com/v/ZTUVgYoeN_b' type='application/x-shockwave-flash' medium='video' isDefault='true' expression="full" duration='215' yt:format="5"/> <media:content url='rtsp://rtsp2.youtube.com/ChoLENy73bIAEQ1k30OPEgGDA==/0/0/0/video.3gp' type='video/3gpp' medium='video' expression="full" duration='215' yt:format="1"/> <media:content url='rtsp://rtsp2.youtube.com/ChoLENy73bIAEQ1k30OPEgGDA==/0/0/0/video.3gp' type='video/3gpp' medium='video' expression="full" duration='215' yt:format="6"/> <media:player url="http://www.youtube.com/watch?v=ZTUVgYoeN_b"/> <media:thumbnail url="http://img.youtube.com/vi/ZTUVgYoeN_b/2.jpg" height="97" width="130" time="00:00:03.500"/> <media:thumbnail url="http://img.youtube.com/vi/ZTUVgYoeN_b/1.jpg" height="97" width="130" time="00:00:01.750"/> <media:thumbnail url="http://img.youtube.com/vi/ZTUVgYoeN_b/3.jpg" height="97" width="130" time="00:00:05.250"/> <media:thumbnail url="http://img.youtube.com/vi/ZTUVgYoeN_b/0.jpg" height="240" width="320" time="00:00:03.500"/> </media:group> <yt:statistics viewCount="93"/> <gd:rating min='1' max='5' numRaters='435' average='4.94'/> <gd:comments> <gd:feedLink href="http://gdata.youtube.com/feeds/api/videos/ZTUVgYoeN_b/comments" countHint='2197'/> </gd:comments> </entry>
En la siguiente captura de pantalla se muestra cómo aparece la información en una lista de vídeos de YouTube. La lista que aparece a continuación indica cómo se corresponden las anotaciones de la captura de pantalla con la información incluida en la respuesta del API.
La captura de pantalla muestra la siguiente información:
Este elemento muestra un título para el conjunto de resultados. En tu aplicación, este valor puede ser el valor de la etiqueta <title> o también puedes seleccionar otro texto adecuado al feed solicitado o al conjunto de resultados de búsqueda.
En la imagen, el texto 1-20 de aprox. 13.800 utiliza los siguientes elementos de la respuesta del API:
Los menús desplegables permiten al usuario seleccionar valores para los parámetros orderby y time. En la Guía de referencia se incluye una lista completa de los parámetros de consulta que admite el API de datos de YouTube y se explican los tipos de consulta en los que se aplica cada parámetro.
Este elemento muestra una imagen en miniatura del vídeo. Las respuestas del API de YouTube pueden contener varias imágenes en miniatura de un vídeo, cada una de las cuales identificada por una etiqueta <media:thumbnail>. En el sitio web de YouTube, los enlaces en forma de imagen en miniatura permiten acceder a una página con más información sobre el vídeo, incluidos comentarios y respuestas en vídeo, y donde el usuario también puede reproducir el vídeo. En una entrada de vídeo, la etiqueta <link> cuyo atributo rel tiene el valor alternate, identifica la URL de la página de YouTube donde el usuario puede reproducir el vídeo. En las páginas de resultados de búsqueda de YouTube, las imágenes en miniatura están vinculadas a dicha URL.
Para obtener información sobre cómo visualizar la página de destino en tu aplicación, envía una solicitud HTTP a la URL de edición con la entrada de vídeo. En la sección siguiente, Identificación de feeds relacionados con una entrada de vídeo, se explica cómo identificar la URL de edición en una entrada.
El título situado junto al vídeo corresponde al valor de la etiqueta <media:title> de dicho vídeo. El texto situado bajo el título corresponde al valor de la etiqueta <media:description>.
La columna derecha muestra los siguientes valores:
La primera línea muestra el texto correspondiente al valor de la etiqueta <published> de dicho vídeo. Ten en cuenta que la etiqueta <published> contiene una marca de tiempo que se puede convertir en texto para mostrar la antigüedad de este vídeo, como se muestra en la captura de pantalla. Por ejemplo: añadido hace 5 meses. Sin embargo, también puedes mostrar una fecha. Por ejemplo, 22/10/07 o 22 oct. 2007.
La segunda línea identifica el nombre de usuario de YouTube del propietario del vídeo. Este valor viene especificado en la etiqueta <name> incluido en la etiqueta <author> de la entrada de vídeo. En el sitio web de YouTube, este enlace permite acceder al usuario a una página con la información del perfil del propietario del vídeo. Para recuperar esta información en tu sitio, debes enviar con posterioridad una solicitud al valor de la etiqueta <uri> incluido en la etiqueta <author> de la entrada de vídeo.
La tercera línea especifica el número de veces que se ha reproducido el vídeo. El atributo viewCount de la etiqueta <yt:statistics> especifica este valor.
La cuarta línea proporciona la puntuación media de los usuarios para el vídeo. El atributo average de la etiqueta <gd:rating> muestra esta puntuación. Ten en cuenta que en YouTube la puntuación se ajusta para determinar qué imagen de estrellas mostrar. Por ejemplo, una puntuación entre 2,75 y 3,2499 muestra una puntuación de tres estrellas, mientras que una puntuación entre 3,25 y 3,7499 muestra una puntuación de 3,5.
La quinta línea muestra la duración del vídeo. La etiqueta <yt:duration> indica la duración del vídeo en segundos. En la captura de pantalla, el valor se ha ajustado para mostrar un valor en minutos y segundos (292 segundos = 04:52).
La sexta línea muestra el nombre de la categoría que describe el vídeo. Este valor está contenido en el atributo label de la etiqueta <media:category>. En el sitio web de YouTube, el nombre de la categoría también conduce a una página con más vídeos de dicha categoría. En la sección Navegación con categorías y palabras clave se explica cómo solicitar vídeos pertenecientes a una categoría determinada.
Para recuperar un feed sobre un vídeo de un conjunto de resultados, debes enviar una solicitud GET HTTP a la URL de edición de dicha entrada, como se explica en la sección siguiente. Por ejemplo, puedes enviar esta solicitud cuando un usuario acceda desde un conjunto de resultados de búsqueda para ver un vídeo en particular de dicho conjunto de resultados de búsqueda.
Cada entrada de una respuesta del API de datos de YouTube identifica varias URL del API relacionadas con el vídeo. Por ejemplo, la entrada identifica URL que permiten solicitar comentarios del vídeo, respuestas en vídeo del vídeo o el perfil de usuario público de YouTube correspondiente al propietario del vídeo. Algunas URL permiten no sólo recuperar información, sino crearla, actualizarla o eliminarla. Por ejemplo, si envías una solicitud GET HTTP a una URL para recuperar comentarios de dicho vídeo y una solicitud POST HTTP a la misma URL para añadir un comentario a dicho vídeo.
Varias funciones del API de este documento hacen referencia a la URL de edición de un vídeo o a otro tipo de entrada. (En un feed de listas de reproducción, por ejemplo, una entrada se corresponde con una lista de reproducción en lugar de con un vídeo). En un feed <entry>, la URL de edición es el valor del atributo href en la etiqueta <link> cuyo atributo rel tiene el valor edit.
En el siguiente código XML de ejemplo se muestra cómo aparecen las etiquetas <link> en una respuesta del API de datos de YouTube. La URL de edición del ejemplo aparece en negrita.
<entry> <id>http://gdata.youtube.com/feeds/api/videos/dMH0bHeiRN</id> <link rel='http://gdata.youtube.com/schemas/2007#video.responses' type='application/atom+xml' href='http://gdata.youtube.com/feeds/api/videos/dmH0bHeiRN/responses'/> <link rel='http://gdata.youtube.com/schemas/2007#video.ratings' type='application/atom+xml' href='http://gdata.youtube.com/feeds/api/videos/dmH0bHeiRN/ratings'/> <link rel='http://gdata.youtube.com/schemas/2007#video.complaints' type='application/atom+xml' href='http://gdata.youtube.com/feeds/api/videos/dmH0bHeiRN/complaints'/> <link rel='self' type='application/atom+xml' href='http://gdata.youtube.com/feeds/api/users/andyland74/dmH0bHeiRN/uploads'/> <link rel='edit' type='application/atom+xml' href='http://gdata.youtube.com/feeds/api/users/andyland74/dmH0bHeiRN/uploads'/> ... </entry>
En las secciones Uso de las funciones de la comunidad, Almacenamiento y recopilación de vídeos y Habilitación de la interacción del usuario de este documento se incluyen casos de uso que describen situaciones en las que se puede utilizar una función determinada para solicitar, crear, actualizar o eliminar recursos con el API de YouTube. En cada caso práctico se explican las solicitudes del API que se deben enviar, así como los valores necesarios para recibir las respuestas del API que permitirán al usuario avanzar en el caso práctico. Con frecuencia, estos pasos requieren el envío de una solicitud del API a una URL identificada en una etiqueta <link> de la respuesta del API. Los casos de uso identifican las URL de las solicitudes del API que utilizan el valor del atributo rel de la etiqueta <link>.
Por ejemplo, para recuperar una lista de respuestas en vídeo de un vídeo, debes enviar una solicitud GET HTTP a la URL asociada a la etiqueta <link> cuyo valor de atributo rel es http://gdata.youtube.com/schemas/2007#video.responses. Para añadir una puntuación a un vídeo, debes enviar una solicitud POST HTTP a la URL asociada a la etiqueta <link> cuyo valor de atributo rel es http://gdata.youtube.com/schemas/2007#video.ratings.
En la siguiente captura de pantalla se muestra cómo aparece la información sobre un único vídeo en YouTube. Aunque la captura de pantalla que muestra la lista de vídeos sólo muestra información de una única solicitud del API, esta página sintetiza varias respuestas del API en una única página.
La lista que aparece a continuación indica la correspondencia entre las anotaciones de la captura de pantalla y las respuestas del API con el contenido.
Ten en cuenta que para ver esta página, antes debes recuperar el feed de la entrada de vídeo. El código XML del feed de una entrada de vídeo es idéntico al contenido correspondiente a dicho vídeo que aparece en un conjunto de resultados de búsqueda o un feed.
La captura de pantalla muestra la siguiente información:
La sección 1 muestra el título del vídeo. En una respuesta del API, la etiqueta <media:title> contiene el título del vídeo.
La sección 2 muestra el vídeo en sí mismo. Puedes utilizar el siguiente fragmento de código para reproducir un vídeo de YouTube en tu propia página. Ten en cuenta que debes sustituir las variables MEDIA_CONTENT_URL y MEDIA_CONTENT_TYPE con los valores adecuados del feed XML:
Para reproducir un vídeo en una página web, sustituye la variable MEDIA_CONTENT_URL por el valor de atributo url de la etiqueta <media:content> cuyo atributo yt:format es 5. Además, sustituye la variable MEDIA_CONTENT_TYPE por el valor de atributo type de la misma etiqueta <media:content>.
Para reproducir un vídeo en un dispositivo móvil, selecciona los valores adecuados de la etiqueta <media:content> en función del valor del atributo yt:format. Sustituye la variable MEDIA_CONTENT_URL por el valor de atributo url de dicha etiqueta. Además, sustituye la variable MEDIA_CONTENT_URL por el valor de atributo url de la etiqueta.
<object width="425" height="350"> <param name="movie" value="MEDIA_CONTENT_URL"></param> <embed src="MEDIA_CONTENT_URL" type="MEDIA_CONTENT_TYPE" width="425" height="350"> </embed> </object>
En la sección 3 se muestran varios botones de acción, además de datos estadísticos sobre el vídeo:
Botones de acción
El botón Compartir del sitio web de YouTube muestra un formulario en línea que permite al usuario enviar un mensaje a un contacto o a otra dirección de correo electrónico. Para duplicar esta implementación del botón Compartir, deberás proporcionar un formulario que recupere y muestre los contactos del usuario conectado y, a continuación, permita al usuario seleccionar contactos a quien enviar un mensaje. Cuando el usuario envíe el mensaje, tu aplicación necesitará enviar una solicitud del API por cada destinatario del mensaje.
El botón Favoritos añade el vídeo a la lista de vídeos favoritos del usuario conectado. Más información sobre cómo añadir un vídeo favorito
El botón Añadir a listas alterna entre un formulario en línea que muestra un menú desplegable con las listas de reproducción del usuario conectado y una opción para crear una nueva lista de reproducción. Si el usuario selecciona una lista de reproducción existente, el vídeo se añadirá a la lista de reproducción. Si el usuario elige añadir una nueva lista de reproducción, el formulario dirigirá al usuario a otro formulario para añadir una lista de reproducción. Después de enviar la información sobre la nueva lista de reproducción, YouTube también añadirá el vídeo a la lista de reproducción.
Para duplicar esta función, tu aplicación necesitará enviar una solicitud adicional del API para recuperar una lista de las listas de reproducción del usuario. Si el usuario selecciona una lista de reproducción existente, tu aplicación añadirá el vídeo a dicha lista de reproducción. Si el usuario optó por crear una nueva lista de reproducción, tu aplicación recopilará la información sobre la nueva lista de reproducción, añadirá la lista de reproducción y, a continuación, añadirá el vídeo a la lista de reproducción.
El botón Marcar muestra un formulario en línea que permite al usuario añadir una reclamación sobre un vídeo. En el sitio de YouTube, el formulario muestra menús de selección que permiten generar el valor de la etiqueta <yt:description> en la solicitud del API para añadir la reclamación. Tu aplicación puede mostrar menús desplegables similares o puede mostrar un cuadro de texto que permita al usuario introducir una reclamación.
Datos estadísticos
En la sección 4 se muestra una lista de comentarios y respuestas en vídeo del vídeo. (El ejemplo no incluye respuestas en vídeo del vídeo). En esta sección se muestran los siguientes elementos:
El enlace para enviar una respuesta en vídeo situado sobre la lista de comentarios dirige al usuario a un formulario que le permitirá seleccionar un vídeo subido anteriormente o subir un nuevo vídeo como una respuesta en vídeo.
Para permitir al usuario seleccionar un vídeo subido anteriormente, la aplicación recuperará un feed de los vídeos subidos por el usuario. Una vez que el usuario haya seleccionado un vídeo, tu aplicación añadirá el vídeo como una respuesta en vídeo.
Si el usuario opta por subir un nuevo vídeo, tu aplicación deberá ser compatible con el método de subida basada de navegador o el método de subida directa para añadir nuevos vídeos a YouTube. Una vez que el usuario haya subido el nuevo vídeo mediante uno de estos dos métodos, tu aplicación recuperará la ID del nuevo vídeo y posteriormente añadirá el vídeo como una respuesta en vídeo.
El segundo enlace situado sobre la lista de comentarios permite al usuario enviar un comentario de texto. El enlace alterna un formulario en línea donde el usuario puede introducir el comentario. Para ofrecer esta función, tu aplicación necesita enviar una solicitud del API para añadir el comentario después de que el usuario envíe el formulario.
Para ver la lista de comentarios, tu aplicación necesita enviar una solicitud adicional del API para recuperar el feed de comentarios del vídeo.
En la sección 5 se muestra información adicional sobre el vídeo y la persona que subió el vídeo:
Para recuperar información adicional sobre el propietario del vídeo, como el número de vídeos que ha subido dicha persona, deberás enviar una solicitud adicional del API para recuperar el perfil del propietario. Un feed de perfil contiene varias etiquetas <gd:feedLink> que se corresponden con un dato sobre el usuario, como sus vídeos favoritos, sus suscripciones o los vídeos que ha subido. El atributo countHint de la etiqueta <gd:feedLink> indica cuántos vídeos favoritos, suscripciones o vídeos subidos tiene el usuario.
El botón Subscribir situado junto al nombre del propietario del vídeo permite al usuario suscribirse al canal del propietario del vídeo, que contiene todos los vídeos subidos por el propietario del vídeo. Para duplicar la función del botón Subscribir de tu aplicación, deberás enviar una solicitud del API para añadir una suscripción cuando un usuario haga clic en el botón.
La parte Acerca de este vídeo del cuadro contiene información adicional sobre el vídeo. Puedes utilizar el contenido de las etiquetas <media:description>, <media:keywords>, <yt:duration>, entre otras, para ofrecer más información sobre un vídeo.
En la sección 6 se muestran más vídeos subidos por el propietario del vídeo. <a href="#User_Uploaded_Videos">Aprende a recuperar vídeos subidos por un usuario específico.
En la sección 7 se muestra una lista de vídeos que YouTube considera similares al vídeo incluido en la página. El feed de vídeos relacionados te permitirá recuperar esta lista mediante el API.
En esta sección se explica cómo recuperar feeds de YouTube estándar. Los feeds estándar contienen listas de vídeos que reflejan el comportamiento del usuario de YouTube, como feeds de los vídeos más vistos o más valorados, o que han sido seleccionados por el personal de YouTube, como feeds de vídeos móviles y los últimos vídeos destacados. Muchos de estos feeds aparecen en la ficha Vídeos del sitio web de YouTube.
Para recuperar un feed estándar, envía una solicitud GET HTTP a la URL asociada a ese feed. En la tabla siguiente se identifica la URL asociada a cada feed estándar:
| Nombre | ID del feed | Ejemplo |
|---|---|---|
| Más valorados | top_rated | http://gdata.youtube.com/feeds/api/standardfeeds/top_rated |
| Superfavoritos | top_favorites | http://gdata.youtube.com/feeds/api/standardfeeds/top_favorites |
| Más vistos | most_viewed | http://gdata.youtube.com/feeds/api/standardfeeds/most_viewed |
| Más recientes | most_recent | http://gdata.youtube.com/feeds/api/standardfeeds/most_recent |
| Más comentados | most_discussed | http://gdata.youtube.com/feeds/api/standardfeeds/most_discussed |
| Más enlazados | most_linked | http://gdata.youtube.com/feeds/api/standardfeeds/most_linked |
| Con más respuestas | most_responded | http://gdata.youtube.com/feeds/api/standardfeeds/most_responded |
| Últimos destacados | recently_featured | http://gdata.youtube.com/feeds/api/standardfeeds/recently_featured |
| Vídeos para teléfonos móviles | watch_on_mobile | http://gdata.youtube.com/feeds/api/standardfeeds/watch_on_mobile |
Además, ten en cuenta que muchos de estos feeds admiten el parámetro de consulta time, que permite restringir el feed para que sólo contenga resultados relevantes del día, la semana o el mes anterior. Por ejemplo, para recuperar los vídeos más valorados del día anterior, debes enviar una solicitud GET HTTP a la siguiente URL:
http://gdata.youtube.com/feeds/api/standardfeeds/top_rated?time=today
Nota: los feeds estándar top_rated, top_favorites, most_viewed, most_discussed, most_linked y most_responded admiten el parámetro time.
En esta sección se explica cómo recuperar un feed con todos los vídeos subidos por un usuario específico:
Para solicitar un feed de todos los vídeos subidos por el usuario conectado actualmente, envía una solicitud GET HTTP a la siguiente URL. Nota: para esta solicitud, debes enviar un token de autenticación en el encabezado de la solicitud HTTP Authorization. El token de autenticación permite que YouTube identifique al usuario.
http://gdata.youtube.com/feeds/api/users/default/uploads
Para solicitar un feed de todos los vídeos subidos por otro usuario, envía una solicitud GET HTTP a la siguiente URL. Ten en cuenta que esta solicitud no requiere autenticación.
http://gdata.youtube.com/feeds/api/users/username/uploads
En la URL anterior, debes sustituir el texto username por el nombre de usuario de YouTube. Puedes extraer el nombre de usuario de la etiqueta <name> en una respuesta del API, como se muestra en el ejemplo siguiente.
<author> <name>andyland74</name> <uri>http://gdata.youtube.com/feeds/api/users/andyland74</uri> </author>
La respuesta del API de esta consulta tiene exactamente el mismo formato que la respuesta de ejemplo de la sección Entradas y feeds de vídeos de este documento.
En esta sección se explica cómo recuperar un feed con una lista de los vídeos relacionados con otro vídeo. YouTube selecciona de forma algorítmica el conjunto de vídeos relacionados.
Cada entrada de vídeo de una respuesta del API contiene una serie de etiquetas <link>. La etiqueta <link> cuyo valor de atributo rel es http://gdata.youtube.com/schemas/2007/#video.related identifica la URL para recuperar otros vídeos relacionados con dicha entrada de vídeo. (El atributo href de la etiqueta <link> identifica la URL).
<link rel="http://gdata.youtube.com/schemas/2007#video.related"
type="application/atom+xml"
href="http://gdata.youtube.com/feeds/api/videos/ZTUVgYoeN_b/related"/>
La respuesta del API de esta consulta tiene exactamente el mismo formato que la respuesta de ejemplo de la sección Entradas y feeds de vídeos de este documento.
En esta sección se explica cómo recuperar un feed de todos los vídeos pertenecientes a una categoría en particular o que están asociados a una palabra clave en particular. (YouTube utiliza el término "etiqueta" para identificar una palabra clave relevante para un vídeo). En los ejemplos también se muestra cómo recuperar vídeos asociados a una categoría y a una o varias palabras clave, así como a vídeos que no están asociados a una categoría o palabra clave en particular.
Cada entrada de vídeo de una respuesta del API contiene una serie de elementos <category>. Cada elemento <category> identifica una categoría o palabra clave con la que está asociado el vídeo correspondiente. El atributo scheme del elemento indica si el elemento identifica una categoría o una palabra clave. El atributo term del elemento especifica la categoría o la palabra clave que puedes utilizar para localizar vídeos descritos en esta sección.
Para solicitar un feed de todos los vídeos pertenecientes a una categoría en particular o que estén asociados a una determinada palabra clave, envía una solicitud GET HTTP a la siguiente URL:
http://gdata.youtube.com/feeds/api/videos/-/categories_or_keywords
En la URL anterior, debes sustituir el texto categories_or_keywords por las categorías o palabras clave específicas para las que quieres recuperar los vídeos. En los ejemplos siguientes se muestra la URL que deberías utilizar para solicitar vídeos de la categoría "Comedy":
http://gdata.youtube.com/feeds/api/videos/-/Comedy
Ten en cuenta que se deben aplicar las siguientes convenciones a las categorías y palabras clave de tu consulta:
Si en tu solicitud se especifica una categoría y una o varias palabras clave o no se especifica una categoría pero sí varias palabras clave, separa el nombre de cada categoría y cada palabra clave con una barra inclinada. Por ejemplo, la siguiente URL permite solicitar vídeos relacionados con las palabras clave "bass" y "fishing":
http://gdata.youtube.com/feeds/api/videos/-/bass/fishing
Tu solicitud puede utilizar los operadores booleanos NOT (-) y OR (|) para excluir vídeos o buscar vídeos asociados a una de las distintas categorías o palabras clave. Por ejemplo, si quieres ver vídeos relacionados con "bass" y "music", el método más eficaz puede ser buscar vídeos asociados a la palabra clave "bass", pero no asociados a las palabras clave "fish" o "fishing", como se muestra en el ejemplo siguiente. (Buscar vídeos asociados a la categoría "Music" y la palabra clave "bass" (bajo) puede excluir vídeos instructivos sobre cómo tocar el bajo).
http://gdata.youtube.com/feeds/api/videos/-/bass/-fish/-fishing
En el ejemplo siguiente se muestra cómo buscar vídeos de béisbol pertenecientes a la categoría "Sports" o "Howto". Los nombres de las categorías están separados por el valor "%7C", que representa un carácter de barra vertical de codificación URL (|) que especifica que el vídeo debe estar asociado a una de las dos categorías:
http://gdata.youtube.com/feeds/api/videos/-/Sports%7CHowto/baseball
Escribe los nombres de las categorías en mayúsculas y los de las palabras clave en minúsculas. Por ejemplo, la siguiente consulta identifica vídeos asociados a la palabra clave "comedy" que no pertenecen a la categoría "Comedy":
http://gdata.youtube.com/feeds/api/videos/-/comedy/-Comedy
Si quieres realizar búsquedas de categorías o palabras clave automáticamente en función de la información de una respuesta del API, especifica el esquema como parte del nombre de categoría para diferenciar claramente las categorías de YouTube de las etiquetas de palabras clave o las etiquetas del desarrollador. En las siguientes URL se indica cómo especificar el esquema en el nombre de la categoría:
http://gdata.youtube.com/feeds/api/videos/-/%7Bhttp%3A%2F%2Fgdata.youtube.com%2Fschemas%2F2007%2Fcategories.cat%7DNews http://gdata.youtube.com/feeds/api/videos/-/%7Bhttp%3A%2F%2Fgdata.youtube.com%2Fschemas%2F2007%2Fkeywords.cat%7Ddog http://gdata.youtube.com/feeds/api/videos/-/%7Bhttp%3A%2F%2Fgdata.youtube.com%2Fschemas%2F2007%2Fdevelopertags.cat%7Dexample.com
Especifica el esquema, tal como se explica en el elemento anterior, si quieres solicitar vídeos asociados a una etiqueta de desarrollador en particular.
En esta sección se explica cómo utilizar el API para recuperar una lista de vídeos que coincida con un término de búsqueda especificado por el usuario. Para buscar vídeos, envía una solicitud GET HTTP a la siguiente URL, añadiendo los parámetros de consulta apropiados a tu solicitud:
http://gdata.youtube.com/feeds/api/videos
El ejemplo siguiente permite buscar el segundo conjunto de 10 vídeos subidos recientemente que coinciden con el término de consulta "football", pero que no coinciden con el término "soccer".
http://gdata.youtube.com/feeds/api/videos?
vq=football+-soccer
&orderby=published
&start-index=11
&max-results=10
Las solicitudes de búsqueda pueden incluir cualquiera de los parámetros siguientes. En primer lugar se muestran los parámetros utilizados con mayor frecuencia.
| Nombre | Definición | ||||||||
|---|---|---|---|---|---|---|---|---|---|
| vq | El parámetro vq permite especificar un término de consulta para una búsqueda. YouTube buscará todos los metadatos de los vídeos que coincidan con el término. Los metadatos de los vídeos incluyen títulos, palabras clave, descripciones, nombres de usuario de los autores y categorías. Ten en cuenta que a todos los espacios, las comillas y otros signos de puntuación del valor del parámetro se les debe aplicar un formato de escape URL. Para buscar una frase exacta, escribe la frase entre comillas dobles. Por ejemplo, para buscar vídeos que coincidan con la frase "spy plane", establece el parámetro vq en %22spy+plane%22. Tu solicitud puede utilizar los operadores booleanos NOT (-) y OR (|) para excluir vídeos o buscar vídeos asociados a uno de los distintos términos de búsqueda. Por ejemplo, para buscar vídeos que coincidan con "boating" o "sailing", establece el parámetro vq en boating%7Csailing. (Ten en cuenta que al carácter de barra vertical se le debe aplicar un formato de escape URL). De forma similar, para buscar vídeos que coincidan con "boating" o "sailing" pero no con "fishing", establece el parámetro vq en "boating&7Csailing+-fishing". |
||||||||
| orderby | El parámetro orderby permite especificar el valor que se utilizará para ordenar vídeos en el conjunto de resultados de la búsqueda. Los valores válidos de este parámetro son relevance, published, viewCount y rating. Además, puedes solicitar los resultados más relevantes para un idioma en particular estableciendo el valor de parámetro en relevance_lang_languageCode, donde languageCode es un código de idioma de dos letras ISO 639-1. (Utiliza los valores zh-Hans para chino simplificado y zh-Hant para chino tradicional). Además, ten en cuenta que los resultados en otros idiomas se obtendrán si presentan un alto nivel de relevancia con respecto al término de consulta de la búsqueda. El valor predeterminado es relevance. | ||||||||
| start-index | El parámetro start-index permite especificar el índice del primer resultado coincidente que se deberá incluir en el conjunto de resultados. Este parámetro utiliza un índice de base 1, lo que significa que el primer resultado es 1, el segundo es 2 y así sucesivamente. Este parámetro funciona en combinación con el parámetro max-results para determinar qué resultados se ofrecerán. Por ejemplo, para solicitar el segundo conjunto de 25 resultados, es decir, los resultados del 26 al 50, establece el parámetro start-index en 26 y el parámetro max-results en 25. | ||||||||
| max-results | El parámetro max-results especifica el número máximo de resultados que se deben incluir en el conjunto de resultados. Este parámetro funciona en combinación con el parámetro start-index para determinar qué resultados se ofrecerán. Por ejemplo, para solicitar el segundo conjunto de 25 resultados, es decir, los resultados del 26 al 50, establece el parámetro max-results en 26 y el parámetro start-index en 26. El valor predeterminado de este parámetro es 25 y el valor máximo es 50. | ||||||||
| author | El parámetro author restringe la búsqueda a vídeos subidos por un usuario de YouTube en particular. En la sección Vídeos subidos por un usuario específico se explica este parámetro de forma más detallada. | ||||||||
| alt | El parámetro alt permite especificar el formato del feed que se devolverá. Los valores válidos de este parámetro son atom, rss, json y json-in-script. El valor predeterminado es atom y en este documento sólo se explica el formato de las respuestas Atom. Para obtener más información sobre el uso de las respuestas del API en JavaScript, consulta Uso de JSON con las API de datos de Google. | ||||||||
| format | El parámetro format permite especificar en qué formato deben estar disponibles los vídeos. Tu solicitud podrá especificar cualquiera de los formatos siguientes:
| lr | El parámetro lr permite restringir la búsqueda de vídeos que tengan el título, la descripción o las palabras clave en un idioma específico. Los valores válidos del parámetro lr son códigos de idioma de dos letras ISO 639-1. Puedes utilizar los valores zh-Hans para chino simplificado y zh-Hant para chino tradicional. Este parámetro también se puede utilizar para solicitar cualquier feed de vídeos que no sea un feed estándar. | ||||||
| racy | El parámetro racy permite incluir contenido restringido y contenido estándar en el conjunto de resultados de una búsqueda. Los valores válidos de este parámetro son include y exclude. De forma predeterminada, se excluirá el contenido restringido. Las entradas de feeds de los vídeos que incluyen contenido restringido presentan un elemento <yt:racy> adicional. | ||||||||
| restriction | El parámetro restriction identifica la dirección IP que se debe utilizar para filtrar vídeos que sólo se pueden reproducir en países específicos. De forma predeterminada, el API excluye los vídeos que no se pueden reproducir en el país desde el que se envían las solicitudes del API. Esta restricción se basa en la dirección IP de la aplicación del cliente. Para solicitar vídeos reproducibles desde un equipo específico, incluye el parámetro “restriction” en tu solicitud y establece como valor del parámetro la dirección IP del equipo en el que se reproducirán los vídeos, por ejemplo, restriction=255.255.255.255.Para solicitar vídeos reproducibles desde un país específico, incluye el parámetro “restriction” en tu solicitud y establece como valor del parámetro el código de dos letras ISO 3166 del país en el que se reproducirán los vídeos, por ejemplo, restriction=DE. |
||||||||
| time | El parámetro time, que sólo está disponible para los feeds estándar top_rated y most_viewed, restringe la búsqueda para vídeos subidos dentro del período de tiempo especificado. Los valores válidos de este parámetro son today (1 día), this_week (7 días), this_month (1 mes) y all_time. El valor predeterminado de este parámetro es all_time. |
Ten en cuenta que los parámetros de consulta de las búsquedas también se pueden añadir a otros tipos de solicitudes de feed. Por ejemplo, puedes recuperar vídeos subidos por un usuario específico que también coincidan con una palabra clave en particular.
El API de datos de YouTube proporciona dos métodos para subir vídeos a YouTube.
La subida directa permite añadir vídeos de tu biblioteca de vídeos a YouTube. Debes elegir una implementación de subida directa si quieres alojar o almacenar vídeos subidos a través de tu sitio y además añadir dichos vídeos a YouTube. En un caso de subida directa, cuando un usuario sube un vídeo a través de tu sitio, el vídeo será enviado a tus servidores. Tu aplicación enviará posteriormente una solicitud del API para subir el vídeo desde tu servidor a YouTube.
La subida basada en navegador te permite aceptar las subidas de vídeos de tus usuarios sin tener que gestionar, alojar ni almacenar los archivos de vídeo en un servidor proxy. Debes elegir un proceso de subida basado en navegador si no quieres alojar ni almacenar los archivos de vídeo subidos.
Además de elegir un método de subida, debes elegir el esquema de autenticación adecuado para tu aplicación. En las secciones siguientes se incluye información adicional sobre el proceso de subida de vídeos:
En esta sección se muestran diagramas de flujo de procesos correspondientes a los dos esquemas de autenticación de los dos métodos de subida. En función de tu aplicación, podrás combinar cualquiera de los esquemas de autenticación con cualquiera de los métodos de subida.
En el siguiente diagrama se muestran los pasos necesarios para autenticar a un usuario mediante el esquema de autenticación AuthSub. La autenticación AuthSub se puede utilizar para las subidas directas o las subidas basadas en navegador.
En la imagen se indican los siguientes pasos:
El usuario hace clic en un enlace de tu sitio para subir un vídeo.
Tu sitio redirecciona al usuario al servicio proxy de autenticación de YouTube.
El navegador del usuario envía una solicitud al servicio de autenticación.
YouTube muestra una página de consentimiento de acceso, donde el usuario deberá acceder a su cuenta de YouTube.
El usuario inicia sesión en su cuenta y, a continuación, YouTube le pide que permita o no que tu sitio pueda subir los detalles de su vídeo.
Si el usuario permite el acceso, YouTube redirigirá al usuario de nuevo a tu sitio. La URL de redireccionamiento contiene el token de autenticación de tu solicitud del API de subida.
El navegador del usuario envía una solicitud, incluido el token de autenticación, a tu sitio. En la documentación sobre AuthSub de Google se explica el paso opcional para intercambiar el token de autenticación de uso único por un token de sesión que no caduca.
En el siguiente diagrama se muestran los pasos necesarios para autenticar a un usuario mediante el esquema de autenticación ClientLogin. Al igual que la autenticación AuthSub, la autenticación ClientLogin se puede utilizar para las subidas directas o las subidas basadas en navegador.
En la imagen se indican los siguientes pasos:
El usuario hace clic en un enlace de tu sitio para subir un vídeo.
Tu aplicación presenta un formulario donde el usuario podrá introducir su nombre de usuario y su contraseña de YouTube.
El usuario envía su nombre de usuario y su contraseña de YouTube a tu aplicación instalada.
Tu aplicación envía la solicitud de autenticación ClientLogin a YouTube con el fin de obtener un token de autenticación para subir el vídeo. La solicitud especifica el nombre de usuario y la contraseña de la cuenta de usuario de YouTube del usuario, que será la cuenta asociada al vídeo.
YouTube verifica el nombre de usuario y la contraseña del usuario y devuelve el token de autenticación a tu aplicación. Si estás utilizando la subida basada en navegador, el token te permitirá subir los metadatos del vídeo. Si estás utilizando la subida directa, el token te permitirá subir los metadatos y el archivo de vídeo.
En el siguiente diagrama se muestra el proceso de subida basado en navegador. Es posible que tu aplicación haya completado ya el proceso de autenticación antes de que se produzcan estos pasos. Sin embargo, también puedes hacer que el usuario te proporcione los metadatos del vídeo antes de completar el proceso de autenticación.
En la imagen se indican los siguientes pasos:
Tu sitio muestra un formulario en el que el usuario deberá introducir los detalles del vídeo que desea subir.
El usuario introduce los detalles del vídeo, como el título, la descripción y la categoría del vídeo.
Tu sitio envía una solicitud POST HTTP a YouTube con el token de autenticación y los detalles del vídeo que el usuario ha enviado en el paso anterior. En la sección Subida de metadatos de vídeos se explica cómo enviar los detalles de un vídeo a YouTube.
YouTube devuelve un token de subida de un solo uso, un valor cifrado con la información de autenticación y los detalles del vídeo que se va a subir. En la sección Extracción de valores de la respuesta del API se identifica el token y la URL de subida de la respuesta del API.
Tu sitio muestra un formulario donde el usuario podrá seleccionar su archivo de vídeo y subirlo a YouTube. El formulario se enviará directamente a YouTube y deberá contener un campo de introducción oculto que especifique el token de subida obtenido en el paso anterior. En la sección Subida del archivo de vídeo se definen las directrices de este formulario.
El usuario selecciona su vídeo y envía el formulario, enviando su vídeo y el token de subida directamente a YouTube. YouTube comprueba que el token es válido y añade el vídeo al canal de YouTube del usuario. Durante este proceso, YouTube asigna al vídeo un ID único que lo identificará en YouTube.
YouTube redirecciona al usuario de nuevo a tu sitio.
En el siguiente diagrama se muestra el proceso de subida directa. Es posible que tu aplicación haya completado ya el proceso de autenticación antes de que se produzcan estos pasos. Sin embargo, también puedes hacer que el usuario te proporcione los metadatos del vídeo antes de completar el proceso de autenticación.
En la imagen se indican los siguientes pasos:
Tu sitio muestra un formulario en el que el usuario deberá seleccionar el archivo de vídeo que desea subir e introducir los detalles del vídeo.
El usuario selecciona el archivo de vídeo e introduce los detalles del vídeo, como el título, la descripción y la categoría del vídeo.
Tu sitio envía una solicitud POST HTTP a YouTube con el token de autenticación, así como el archivo de vídeo y los detalles del vídeo que el usuario ha enviado en el paso anterior. En la sección Subida de metadatos de vídeos se explica cómo enviar el archivo de vídeo y los detalles del vídeo a YouTube.
YouTube devuelve una respuesta del API con la descripción del nuevo vídeo.
Deberás mostrar una confirmación al usuario indicando que el vídeo se ha subido correctamente.
Debes ser el titular de los derechos de autor o el representante autorizado del propietario de los derechos de autor de todos los archivos de vídeo que subas a YouTube. De forma similar, los usuarios que suban vídeos a YouTube desde tu sitio deberán ser los titulares de los derechos de autor o representantes autorizados del propietario de los derechos de autor de los vídeos que se suban. Te animamos a que tanto tú como tus usuarios subáis vídeos de la mayor calidad posible. Puedes consultar las especificaciones de vídeo recomendadas por YouTube online en el Centro de asistencia de YouTube y te recomendamos que transmitas estas directrices a tus usuarios.
Además de estas directrices, ten en cuenta que los archivos de vídeo deben tener un tamaño máximo de 100 MB y que YouTube no limitará la duración de los vídeos subidos. Puedes comprimir los archivos de vídeos utilizando el formato .zip. Sin embargo, ten en cuenta que la restricción de tamaño de 100 MB se aplicará al tamaño del archivo descomprimido.
Al subir un vídeo, puedes asociarlo a una de las categorías de vídeo de YouTube. También puedes asociar el video a palabras clave o etiquetas de desarrollador que podrás utilizar para identificarlo. Las etiquetas de desarrollador te permiten identificar todos los vídeos subidos a través de tu sitio web o incluso a través de áreas específicas de tu sitio web. YouTube no mostrará las etiquetas de desarrollador a los usuarios de YouTube; sin embargo, puedes recuperar o actualizar vídeos que coincidan con una etiqueta de desarrollador específica.
Para asociar etiquetas de desarrollador a un vídeo, incluye una etiqueta <media:category> en una solicitud del API de subida por cada etiqueta de desarrollador. Establece en el atributo scheme el valor http://gdata.youtube.com/schemas/2007/developertags.cat y en la etiqueta la palabra clave que quieras asociar al vídeo. En el siguiente XML se muestra una etiqueta de desarrollador tal como aparecería en una solicitud del API de subida. (Necesitas sustituir la cadena TagName con la etiqueta o la palabra clave que quieres asociar al vídeo).
<media:category scheme="http://gdata.youtube.com/schemas/2007/developertags.cat">TagName</media:category>
En una respuesta del API, las etiquetas de desarrollador se especifican en las etiquetas <category> y <media:category>.
Nota: cada etiqueta de desarrollador que asignes estará asociada a la clave de desarrollador de tu solicitud. Para buscar vídeos que coincidan con la etiqueta de desarrollador, tu aplicación deberá especificar la misma clave de desarrollador en la solicitud de búsqueda.
Para buscar vídeos asociados a una etiqueta de desarrollador específica, envía una solicitud de búsqueda del API que especifique el esquema de categoría developertags.cat y la etiqueta de desarrollador con la que deben estar asociados los vídeos. En las siguientes URL se indica cómo modificar la URL estándar del API para que coincida con una etiqueta de desarrollador. (Deberás sustituir la cadena TagName al final de la URL por el nombre de tu etiqueta de desarrollador).
Standard URL:
http://gdata.youtube.com/feeds/api/videos/
Retrieving videos associated with a developer tag:
http://gdata.youtube.com/feeds/api/videos/-/
%7Bhttp%3A%2F%2Fgdata.youtube.com%2Fschemas%2F2007%2Fdevelopertags.cat%7DTagName
Nota: cuando busques vídeos asociados a una etiqueta de desarrollador, tu solicitud deberá especificar la misma clave de desarrollador que utilizaste para asignar dicha etiqueta de desarrollador.
En el siguiente ejemplo se muestra el formato de una solicitud del API que utiliza el esquema de autenticación AuthSub para la subida basada en navegador:
POST /action/GetUploadToken HTTP/1.1 Host: gdata.youtube.com Authorization: AuthSub token=<authentication_token> X-GData-Client: <client_id> X-GData-Key: key=<developer_key> Content-Length: <content_length> Content-Type: application/atom+xml; charset=UTF-8 API_XML_request
Debes proporcionar varios valores en la solicitud POST HTTP. Estos valores aparecen resaltados en negrita en el ejemplo anterior. En la lista siguiente se explica cómo especificar cada uno de estos valores:
authentication_token: este valor contiene el token de autenticación de tu solicitud. El token debe ser un token ClientLogin, un token AuthSub de un solo uso o un token Authsub de sesión.
client_id (opcional): este valor identifica la aplicación que realiza la solicitud del API. Este valor se utiliza para depuración y registro. Visita http://code.google.com/apis/youtube/dashboard/ para obtener una ID de cliente.
developer_key: este valor identifica al desarrollador de YouTube que envía la solicitud de subida del vídeo. Visita http://code.google.com/apis/youtube/dashboard/ para obtener una clave de desarrollador.
content_length: este valor contiene el tamaño, en bytes, de todo el cuerpo de la solicitud POST HTTP.
API_XML_Request: este valor contiene información sobre el archivo de vídeo subido en el formulario de una entrada XML Atom. En el ejemplo siguiente se muestra una solicitud XML de ejemplo. Las etiquetas XML utilizadas en la entrada están definidas en la Guía de referencia.
En el ejemplo siguiente se muestra una solicitud POST HTTP con todos estos valores especificados con la excepción de los datos binarios del archivo.
POST /action/GetUploadToken HTTP/1.1 Host: gdata.youtube.com Authorization: AuthSub token=DXAA...sdb8 X-GData-Client: b1c4t9sl2159 X-GData-Key: key=adf15ee97731bca89da876c...a8dc Content-Length: 1941255 Content-Type: application/atom+xml; charset=UTF-8 <?xml version="1.0"?> <entry xmlns="http://www.w3.org/2005/Atom" xmlns:media="http://search.yahoo.com/mrss/" xmlns:yt="http://gdata.youtube.com/schemas/2007"> <media:group> <media:title type="plain">Bad Wedding Toast</media:title> <media:description type="plain">I gave a bad toast at my friend's wedding.</media:description> <media:category scheme="http://gdata.youtube.com/schemas/2007/categories.cat">People</media:category> <media:keywords>toast, wedding</media:keywords> </media:group> </entry>
Al enviar una solicitud del API de subida, el API devuelve una respuesta XML con una URL de subida y un token de subida que permiten que el usuario suba el archivo de vídeo. Deberás extraer la URL y el token de la respuesta e incluir estos valores en el formulario de tu página web desde donde el usuario subirá los archivos de vídeos.
En el ejemplo siguiente se muestra una respuesta del API de ejemplo a una solicitud de subida basada en navegador:
En el siguiente código XML se muestra un ejemplo de una respuesta API de subida.
<?xml version='1.0' encoding='UTF-8'?> <response> <url>http://uploads.gdata.youtube.com/action/FormUpload/AEF3087AUD<url> <token>AEwbFAQEvf3xox...</token> </response>
Después de extraer la URL de subida y el token de subida de la respuesta del API, deberás mostrar un formulario para que el usuario pueda subir el archivo de vídeo. El formulario debe utilizar la URL de subida como el valor del atributo action de la etiqueta <form> y contener un campo de introducción oculto con el token de subida.
El siguiente código HTML muestra un formulario de ejemplo tal como aparecería en tu sitio:
<form action="URL?nexturl=http%3A%2F%2Fwww.example.com method="post" enctype="multipart/form-data"> <input type="file" name="file"/> <input type="hidden" name="token" value="TOKEN/> <input type="submit" value="go" /> </form>
Ten en cuenta que el formulario debe seguir estas directrices:
Debes añadir el parámetro nexturl a la URL de destino del formulario. Este parámetro especifica la URL a la que YouTube redirigirá al navegador del usuario cuando éste suba su archivo de vídeo. Una vez subido el vídeo al navegador, el usuario será redirigido a la URL nexturl. Consulta la guía de referencia para obtener más información sobre los demás parámetros que se añadirán a la URL.
Debes establecer en el atributo enctype de la etiqueta <form> el valor multipart/form-data.
La etiqueta <input> que identifica el archivo debe llamarse file.
La etiqueta <input> que contiene el token debe llamarse token.
Para subir un vídeo, envía una solicitud POST HTTP con el vídeo y los metadatos asociados a http://uploads.gdata.youtube.com/feeds/api/users/<youtube_username>/uploads. Debes sustituir la cadena <youtube_username> por el nombre de usuario de la cuenta de YouTube del creador del contenido.
La solicitud del API de subida debe tener el siguiente formato:
POST /feeds/api/users/default/uploads HTTP/1.1 Host: uploads.gdata.youtube.com Authorization: AuthSub token=<authentication_token> X-GData-Client: <client_id> X-GData-Key: key=<developer_key> Slug: <video_filename> Content-Type: multipart/related; boundary=<boundary_string> Content-Length: <content_length> Connection: close --<boundary_string> Content-Type: application/atom+xml; charset=UTF-8 API_XML_request --<boundary_string> Content-Type: <video_content_type> Content-Transfer-Encoding: binary <Binary File Data> --<boundary_string>--
Una solicitud de subida de un vídeo con el esquema de autenticación ClientLogin presenta una diferencia sintáctica con el ejemplo anterior. El encabezado Authorization presenta un formato diferente para un token de autenticación ClientLogin. En el ejemplo siguiente se muestra el formato que debe tener un encabezado de la solicitud Authorization para un token de autenticación ClientLogin.
Authorization: GoogleLogin auth=<authentication_token>
Nota: el nombre de host para subir un vídeo a través del API, uploads.gdata.youtube.com, es diferente del nombre de host utilizado para el resto de las funciones del API. Sin embargo, puedes utilizar el mismo token de autenticación tanto para subir vídeos como para otras funciones del API.
Debes proporcionar varios valores en la solicitud POST HTTP. Estos valores aparecen resaltados en negrita en el ejemplo anterior. En la lista siguiente se explica cómo especificar cada uno de estos valores:
youtube_username: ten en cuenta que esta variable sólo es relevante para solicitudes que utilicen la autenticación ClientLogin. Este valor contiene el nombre de usuario de la cuenta de YouTube del usuario. El vídeo subido se asociará a esta cuenta.
authentication_token: este valor contiene el token de autenticación de tu solicitud. El token debe ser un token ClientLogin, un token AuthSub de un solo uso o un token Authsub de sesión.
client_id (opcional): este valor identifica a la aplicación que realiza la solicitud del API. Este valor se utiliza para depuración y registro. Visita http://code.google.com/apis/youtube/dashboard/ para obtener una ID de cliente.
developer_key: este valor identifica al desarrollador de YouTube que envía la solicitud de subida del vídeo. Visita http://code.google.com/apis/youtube/dashboard/ para obtener una clave de desarrollador.
video_filename: este valor contiene el nombre del archivo de vídeo que el creador de contenido va a subir.
boundary_string: este valor contiene una cadena de caracteres sin espacios. Normalmente, la cadena está formada por una serie de guiones seguidos por un conjunto aleatorio de caracteres alfanuméricos. Nota: Este valor aparece varias veces en la solicitud POST HTTP.
content_length: este valor contiene el tamaño, en bytes, de todo el cuerpo de la solicitud POST HTTP.
API_XML_Request: este valor contiene información sobre el archivo de vídeo subido en forma de entrada XML Atom. En el ejemplo siguiente se muestra una solicitud XML de ejemplo. Las etiquetas XML utilizadas en la entrada están definidas en la Guía de referencia.
video_content_type: este valor contiene el tipo MIME del archivo de vídeo subido. El tipo MIME debe ser video/* (video/mpeg, video/mp4, etc). o application/octet-stream.
Datos binarios del archivo - Este valor contiene el código binario del archivo de vídeo que se va a subir.
En el ejemplo siguiente se muestra una solicitud POST HTTP con todos estos valores especificados con la excepción de los datos binarios del archivo.
POST /feeds/api/users/default/uploads HTTP/1.1 Host: uploads.gdata.youtube.com Authorization: AuthSub token=DXAA...sdb8 X-GData-Client: b1c4t9sl2159 X-GData-Key: key=adf15ee97731bca89da876c...a8dc Slug: video-test.mp4 Content-Type: multipart/related; boundary=--f93dcbA3 Content-Length: 1941255 Connection: close --f93dcbA3 Content-Type: application/atom+xml; charset=UTF-8 <?xml version="1.0"?> <entry xmlns="http://www.w3.org/2005/Atom" xmlns:media="http://search.yahoo.com/mrss/" xmlns:yt="http://gdata.youtube.com/schemas/2007"> <media:group> <media:title type="plain">Bad Wedding Toast</media:title> <media:description type="plain">I gave a bad toast at my friend's wedding.</media:description> <media:category scheme="http://gdata.youtube.com/schemas/2007/categories.cat">People</media:category> <media:keywords>toast, wedding</media:keywords> </media:group> </entry> --f93dcbA3 Content-Type: video/mp4 Content-Transfer-Encoding: binary <Binary File Data> --f93dcbA3--
Al enviar una solicitud del API de subida, el API devuelve una respuesta XML que especifica todos los vídeos subidos por el usuario que generó la solicitud. (Si utilizas la autenticación ClientLogin, la respuesta incluirá todos los vídeos subidos a tu cuenta). La respuesta será una entrada Atom y tendrá el mismo formato que la respuesta estándar del API de datos de YouTube a una solicitud de recuperación de todos los vídeos subidos por un usuario. Ten en cuenta que la respuesta contiene etiquetas HTML con el formato de escape adecuado.
Un vídeo subido estará visible inmediatamente en el feed de vídeos subidos de un usuario autenticado. Sin embargo, el vídeo no estará visible en YouTube hasta que se haya procesado e indexado. El período de tiempo que transcurre desde que se sube el vídeo hasta que todos los usuarios de YouTube pueden ver el vídeo varía. Sin embargo, los vídeos se suelen indexar en menos de un día, a veces en varias horas o incluso en menos de una hora.
Para comprobar el estado de los vídeos no publicados de un usuario, recupera el feed de vídeos subidos del usuario. Las entradas de dicho feed que no se hayan publicado contendrán la etiqueta <app:control>. Ten en cuenta que los vídeos no publicados incluyen los vídeos que aún no se han procesado, los que no se han podido subir y los que han sido rechazados una vez subidos.
En el siguiente fragmento XML se muestra cómo la etiqueta <app:control> y sus subetiquetas <app:draft> y <yt:state> aparecen en un feed de vídeos subidos.
<entry> <id>http://gdata.youtube.com/feeds/user/username/b5bbb2beb5a7d9ca</id> <app:control> <app:draft>yes</app:draft> <yt:state name='rejected' reasonCode='tooLong' helpUrl='http://www.youtube.com/t/community_guidelines'> Video is too long. </yt:state> </app:control> <yt:private/> </entry>
Nota: te recomendamos que compruebes el valor de la etiqueta <yt:state> y le comuniques a los propietarios del vídeo si aún se está procesando un vídeo no publicado o si un error provocó que la subida fallara o se rechazara. Las guías de desarrolladores de Java y PHP proporcionan algunos códigos de ejemplo para comprobar los valores de estas etiquetas.
Para actualizar un vídeo, envía una solicitud PUT HTTP a la URL identificada en la etiqueta <link> de la entrada de vídeo donde el valor del atributo rel es edit:
<link rel='edit' type='application/atom+xml' href='http://gdata.youtube.com/feeds/apis/users/andyland74/uploads/914IMX9RSTE'>
El cuerpo de la solicitud PUT es una entrada XML Atom que contiene la información del vídeo. Puedes incluir cualquiera de los siguientes elementos y sus subetiquetas en tu solicitud. Los elementos necesarios están marcados con un asterisco (*).
Ten en cuenta que excluir un elemento eliminará la información que ya existe para dicho vídeo. Por ejemplo, si un vídeo está marcado como privado y tu solicitud no incluye la etiqueta <yt:private>, el vídeo pasará a ser público.
El siguiente código XML muestra una solicitud de ejemplo para actualizar un vídeo:
PUT /feeds/api/users/USER_ID/uploads/VIDEO_ID HTTP/1.1 Host: gdata.youtube.com Content-Type: application/atom+xml Content-Length: CONTENT_LENGTH Authorization: AuthSub token=AUTHORIZATION_TOKEN X-GData-Client: CLIENT_ID X-GData-Key: key=DEVELOPER_KEY <?xml version="1.0"?> <entry xmlns="http://www.w3.org/2005/Atom" xmlns:media="http://search.yahoo.com/mrss/" xmlns:yt="http://gdata.youtube.com/schemas/2007"> <media:group> <media:title type="plain">Yippee Skippy</media:title> <media:description type="plain">I am updating this video.</media:description> <media:category scheme="http://gdata.youtube.com/schemas/2007/categories.cat">People</media:category> <media:keywords>blastoff,rodeo,whiteboards</media:keywords> </media:group> </entry>
Para eliminar un vídeo, envía una solicitud DELETE HTTP a la URL de edición de dicho vídeo, tal como se muestra en el siguiente ejemplo:
DELETE /feeds/api/users/USER_ID/uploads/VIDEO_ID HTTP/1.1 Host: gdata.youtube.com Content-Type: application/atom+xml Authorization: AuthSub token=AUTHORIZATION_TOKEN X-GData-Client: CLIENT_ID X-GData-Key: key=DEVELOPER_KEY
Un usuario puede añadir una puntuación a un vídeo. YouTube utiliza un sistema de puntuación de 1 a 5 en el que 1 es la puntuación más baja que se puede asignar. Los usuarios no pueden actualizar ni eliminar puntuaciones. Normalmente, un usuario puntúa un vídeo después de verlo.
En una respuesta del API, cada entrada incluye dos etiquetas que contienen información relevante para las puntuaciones de los usuarios:
La etiqueta <gd:rating> identifica la escala de puntuaciones, el número de puntuaciones del vídeo y la puntuación media del vídeo. Esta etiqueta sólo se devuelve si el vídeo ha sido puntuado. En el siguiente fragmento XML se muestra cómo aparece esta URL en una respuesta del API:
<feed>
<entry>
...
<gd:rating min='1' max='5' numRaters='1914' average='4.24'/>
</entry>
</feed>
Una etiqueta <link> identifica la URL en la que se debe publicar una solicitud del API para añadir una puntuación a un vídeo. Como cada entrada incluye varias etiquetas de enlace, debes utilizar la URL de la etiqueta cuyo atributo rel tenga el valor http://gdata.youtube.com/schemas/2007#video.ratings. En el siguiente fragmento XML se muestra cómo aparece esta URL en una respuesta del API:
<feed>
<entry>
<link rel='http://gdata.youtube.com/schemas/2007#video.responses'
type='application/atom+xml'
href='http://gdata.youtube.com/feeds/api/videos/VIDEO_ID/responses'/>
<link rel='http://gdata.youtube.com/schemas/2007#video.ratings'
type='application/atom+xml'
href='http://gdata.youtube.com/feeds/api/videos/VIDEO_ID/ratings'/>
...
<media:group>
</entry>
</feed>
Para añadir una puntuación, envía una solicitud POST HTTP que identifique el vídeo que se va a puntuar y la puntuación en sí. (El usuario que va a puntuar el vídeo se identificará mediante el token de autenticación).
En el siguiente código XML se muestra cómo añadir una puntuación a un vídeo. Ten en cuenta que el atributo value de la etiqueta <gd:rating> debe ser un valor entero entre 1 y 5 que identifique la puntuación que se va a dar.
POST /feeds/api/videos/VIDEO_ID/ratings Host: gdata.youtube.com Content-Type: application/atom+xml Content-Length: CONTENT_LENGTH Authorization: AuthSub token=AUTHORIZATION_TOKEN X-GData-Client: CLIENT_ID X-GData-Key: key=DEVELOPER_KEY <?xml version="1.0" encoding="UTF-8"?> <entry xmlns="http://www.w3.org/2005/Atom" xmlns:gd="http://schemas.google.com/g/2005"> <gd:rating value="4" min="1" max="5"/> </entry>
Si YouTube ejecuta correctamente la solicitud, el API devolverá un código de respuesta HTTP 201.
YouTube devolverá un error si tu solicitud HTTP especifica un valor no válido para el atributo value de la etiqueta <gd:rating>, un valor distinto a 1 para el atributo min o un valor distinto a 5 para el atributo max.
Un comentario es una respuesta de texto a un vídeo. Los usuarios conectados pueden añadir comentarios a un vídeo pero no pueden modificar ni eliminar dichos comentarios. Además, ten en cuenta que YouTube convertirá cualquier marca HTML que aparezca en un comentario en texto sin formato. Normalmente, un usuario añadirá comentarios a un vídeo después de verlo.
Cada entrada de vídeo contiene una etiqueta <gd:comments>, que incluye la URL a la que se enviarán las solicitudes del API que se deberán recuperar o añadir a la lista de comentarios del vídeo. En el código XML de ejemplo se muestra cómo aparece esta URL en una respuesta del API:
<feed>
<entry>
...
<media:group>
...
</media:group>
<gd:comments>
<gd:feedLink href='http://gdata.youtube.com/feeds/api/videos/VIDEO_ID/comments'/>
</gd:comments>
</entry>
</feed>
Cada comentario tiene un autor, un título y un contenido. En el siguiente código XML aparece una respuesta del API de ejemplo con un feed de comentarios:
<?xml version='1.0' encoding='UTF-8'?> <feed xmlns='http://www.w3.org/2005/Atom' xmlns:openSearch='http://a9.com/-/spec/opensearchrss/1.0/'> <id>http://gdata.youtube.com/feeds/api/videos/ZTUVgYoeN_b/comments?start-index=1&max-results=25</id> <updated>2008-02-25T23:14:03.148Z</updated> <category scheme='http://schemas.google.com/g/2005#kind' term='http://gdata.youtube.com/schemas/2007#comment'/> <title type='text'>Comments on 'My walk with Mr. Darcy'</title> <logo>http://www.youtube.com/img/pic_youtubelogo_123x63.gif</logo> <link rel='related' type='application/atom+xml' href='http://gdata.youtube.com/feeds/api/videos/ZTUVgYoeN_b'/> <link rel='alternate' type='text/html' href='http://www.youtube.com/watch?v=ZTUVgYoeN_b'/> <link rel='http://schemas.google.com/g/2005#feed' type='application/atom+xml' href='http://gdata.youtube.com/feeds/api/videos/ZTUVgYoeN_b/comments'/> <link rel='self' type='application/atom+xml' href='http://gdata.youtube.com/feeds/api/videos/ZTUVgYoeN_b/comments?start-index=1&max-results=25'/> <link rel='next' type='application/atom+xml' href='http://gdata.youtube.com/feeds/api/videos/ZTUVgYoeN_b/comments?start-index=26&max-results=25'/> <author> <name>YouTube</name> <uri>http://www.youtube.com/</uri> </author> <generator version='beta' uri='http://gdata.youtube.com/'>YouTube data API</generator> <openSearch:totalResults>100</openSearch:totalResults> <openSearch:startIndex>1</openSearch:startIndex> <openSearch:itemsPerPage>25</openSearch:itemsPerPage> <entry> <id>http://gdata.youtube.com/feeds/api/videos/ZTUVgYoeN_b/comments/7F2BAAD03653A691</id> <published>2007-05-23T00:21:59.000-07:00</published> <updated>2007-05-23T00:21:59.000-07:00</updated> <category scheme='http://schemas.google.com/g/2005#kind' term='http://gdata.youtube.com/schemas/2007#comment'/> <title type='text'>Walking is fun.</title> <content type='text'>Walking is fun.</content> <link rel='related' type='application/atom+xml' href='http://gdata.youtube.com/feeds/api/videos/ZTUVgYoeN_b'/> <link rel='alternate' type='text/html' href='http://www.youtube.com/watch?v=ZTUVgYoeN_b'/> <link rel='self' type='application/atom+xml' href='http://gdata.youtube.com/feeds/api/videos/ZTUVgYoeN_b/comments/7F2BAAD03653A691'/> <author> <name>andyland744</name> <uri>http://gdata.youtube.com/feeds/api/users/andyland744</uri> </author> </entry> <entry> ... </entry> ... </feed>
Los usuarios de YouTube pueden responder a un comentario con otro comentario. En una respuesta XML, un comentario publicado en respuesta a otro comentario contendrá un enlace in-reply-to, tal como se muestra en la siguiente etiqueta <link>:
<link rel="http://gdata.youtube.com/schemas/2007#in-reply-to" type="application/atom+xml" href="http://gdata.youtube.com/feeds/api/videos/2cdgTWitj_o/comments/978A9E10911314AC"/>
Para añadir un comentario a un vídeo, envía una solicitud POST HTTP a la URL identificada en la etiqueta <gd:feedLink> que aparece dentro de la etiqueta <gd:comments>. El comentario que vas a enviar aparecerá como el valor de la etiqueta <content> en el código XML que constituye el cuerpo de la solicitud POST.
La siguiente solicitud del API en XML de ejemplo muestra cómo añadir un comentario a un vídeo.
POST /feeds/api/videos/VIDEO_ID/comments HTTP/1.1 Host: gdata.youtube.com Content-Type: application/atom+xml Content-Length: CONTENT_LENGTH Authorization: AuthSub token=AUTHORIZATION_TOKEN X-GData-Client: CLIENT_ID X-GData-Key: key=DEVELOPER_KEY <?xml version="1.0" encoding="UTF-8"?> <entry xmlns="http://www.w3.org/2005/Atom" xmlns:yt="http://gdata.youtube.com/schemas/2007"> <content>This is a crazy video.</content> </entry>
Una respuesta en vídeo es un vídeo asociado, como respuesta, a un segundo vídeo. Un vídeo se puede designar como respuesta en vídeo a otro vídeo concreto. Los usuarios conectados pueden añadir o eliminar respuestas en vídeo, pero el usuario debe haber subido el vídeo que se va a añadir o eliminar.
En esta sección se explica cómo recuperar un feed de respuestas en vídeo de un vídeo. Ten en cuenta que es posible que algunos vídeos no tengan ninguna respuesta en vídeo.
Cada entrada de vídeo de una respuesta del API contiene una serie de etiquetas <link>. La etiqueta <link> cuyo atributo rel tiene el valor http://gdata.youtube.com/schemas/2007/#video.responses identifica la URL que permitirá recuperar las respuestas en vídeo para dicha entrada en vídeo. (El atributo href de la etiqueta <link> identifica la URL).
<link rel="http://gdata.youtube.com/schemas/2007#video.responses"
type="application/atom+xml"
href="http://gdata.youtube.com/feeds/api/videos/ZTUVgYoeN_b/responses"/>
La respuesta del API de esta consulta tiene exactamente el mismo formato que la respuesta de ejemplo de la sección Entradas y feeds de vídeos de este documento.
Para añadir una respuesta en vídeo, envía una solicitud POST HTTP que identifique dos vídeos: el vídeo al que quieres añadir la respuesta en vídeo y el vídeo que se añadirá como respuesta.
En el siguiente código XML se muestra el formato de una solicitud de ejemplo de adición de una respuesta en vídeo. En la solicitud, la cadena ORIGINAL_VIDEO_ID identifica el vídeo al que quieres añadir la respuesta en vídeo y la cadena RESPONSE_VIDEO_ID identifica el vídeo que quieres añadir como respuesta.
POST /feeds/api/videos/ORIGINAL_VIDEO_ID/responses HTTP/1.1 Host: gdata.youtube.com Content-Type: application/atom+xml Content-Length: CONTENT_LENGTH Authorization: AuthSub token=AUTHORIZATION_TOKEN X-GData-Client: CLIENT_ID X-GData-Key: key=DEVELOPER_KEY <?xml version="1.0" encoding="UTF-8"?> <entry xmlns="http://www/w3.org/2005/Atom"> <id>RESPONSE_VIDEO_ID</id> </entry>
Si YouTube ejecuta correctamente la solicitud, el API devolverá un código de respuesta HTTP 201. Sin embargo, la respuesta en vídeo no se mostrará en el feed de respuestas en vídeo hasta que el propietario del vídeo original haya aprobado la respuesta.
Normalmente, un usuario añadirá una respuesta en vídeo a un vídeo después de verlo. En algunos casos, el usuario puede seleccionar como respuesta un vídeo que ya ha subido. En otros casos, el usuario subirá un nuevo vídeo que le servirá como respuesta en vídeo. La lista siguiente identifica las llamadas del API asociadas a cada tipo de solicitud del API:
El usuario selecciona un vídeo existente para hacer la función de respuesta en vídeo.
Puedes recuperar información sobre un vídeo mediante el envío de una solicitud del API a la URL propia del vídeo.
El usuario hace clic en un enlace para añadir una repuesta en vídeo al vídeo y elige responder con un vídeo subido anteriormente. Extraes la URL de la respuesta en vídeo correspondiente al vídeo al que el usuario desea añadir la respuesta.
Envías una solicitud del API para recuperar la lista de vídeos subidos por el usuario. Muestras la lista de vídeos de forma que el usuario pueda seleccionar uno de los vídeos.
Cuando el usuario selecciona un vídeo, envías una solicitud POST HTTP a la URL de la respuesta en vídeo correspondiente al vídeo original que especifica la <id> del vídeo seleccionado. En la sección Recuperación de una lista de respuestas en vídeo se explica cómo identificar la URL de la respuesta en vídeo correspondiente a la entrada de un feed.
El usuario sube un nuevo vídeo, que servirá como la respuesta en vídeo.
Este caso práctico también comienza con una solicitud del API para recuperar información sobre un vídeo.
El usuario hace clic en un enlace para añadir una repuesta en vídeo al vídeo y elige subir (o capturar) un nuevo vídeo. Extraes la URL de la respuesta en vídeo correspondiente al vídeo al que el usuario desea añadir la respuesta.
Envías una solicitud del API para subir el vídeo nuevo a la biblioteca de vídeos de YouTube. Si el usuario necesita capturar antes el vídeo, también deberás presentar un formulario que permita al usuario introducir el título y otros datos sobre el vídeo.
Puedes extraer la ID de vídeo del vídeo que se acaba de añadir de la respuesta del API a tu solicitud de YouTube.
Envías una solicitud POST HTTP a la URL de la respuesta en vídeo correspondiente al vídeo original para añadir el vídeo que se acaba de subir como una respuesta en vídeo.
Para eliminar una respuesta en vídeo, envía una solicitud DELETE HTTP que identifique los dos vídeos, tal como se muestra en el siguiente ejemplo.
DELETE /feeds/api/videos/VIDEO_ID/responses/VIDEO_RESPONSE_ID HTTP/1.1 Host: gdata.youtube.com Content-Type: application/atom+xml Authorization: AuthSub token=AUTHORIZATION_TOKEN X-GData-Client: CLIENT_ID X-GData-Key: key=DEVELOPER_KEY
Un usuario puede añadir una reclamación sobre un vídeo y marcarlo por incluir contenido inadecuado. Las reclamaciones se pueden insertar pero no se pueden actualizar ni eliminar. Normalmente, un usuario añadirá una reclamación a un vídeo después de verlo.
En una respuesta del API, cada entrada incluye una etiqueta <link> que identifica la URL en la que se publicará una solicitud del API para añadir una reclamación sobre el vídeo. Como cada entrada incluye varias etiquetas de enlace, debes utilizar la URL de la etiqueta cuyo atributo rel tenga el valor http://gdata.youtube.com/schemas/2007#video.complaints.
Para añadir una reclamación, debes enviar una solicitud POST HTTP que identifique al destinatario de la reclamación, al usuario que realiza la reclamación y el texto de la propia reclamación. (El usuario se identificará mediante el token de autenticación en los encabezados de la solicitud HTTP). La solicitud también puede especificar la razón de la reclamación mediante el uso de una etiqueta <category> cuyo atributo scheme tenga el valor http://gdata.youtube.com/schemas/2007/complaint-reasons.cat. El atributo term de la etiqueta debe ser uno de los siguientes términos:
En el siguiente código XML se muestra cómo añadir una reclamación a un vídeo.
POST /feeds/api/videos/VIDEO_ID/complaints HTTP/1.1 Host: gdata.youtube.com Content-Type: application/atom+xml Content-Length: CONTENT_LENGTH Authorization: AuthSub token=AUTHORIZATION_TOKEN X-GData-Client: CLIENT_ID X-GData-Key: key=DEVELOPER_KEY <?xml version="1.0" encoding="UTF-8"?> <entry xmlns="http://www.w3.org/2005/Atom" xmlns:yt="http://gdata.youtube.com/schemas/2007"> <yt:content type="text"> Please ignore this complaint. I'm testing a YouTube API and needed to issue a complaint to test the add complaint function. Per the value of the category tag, pretend I am complaining about a video that contains violent or repulsive acts. </yt:content> <category scheme="http://gdata.youtube.com/schemas/2007/complaint-reasons.cat" term="VIOLENCE"/> </entry>
Si YouTube ejecuta correctamente la solicitud, el API devolverá un código de respuesta HTTP 201.
En esta sección se explica cómo permitir a un usuario enviar vídeos a otros usuarios de su lista de contactos de YouTube. (En la sección Visualización de información sobre un vídeo de este documento se muestra cómo acceden los usuarios a esta función en el sitio web de YouTube).
Para enviar un vídeo de un usuario a los mensajes recibidos de YouTube de otro usuario, envía una solicitud POST HTTP a la siguiente URL. En la URL, debes sustituir el texto CONTACT_ID por el nombre de usuario de YouTube de la persona a la que se va a enviar el vídeo.
http://gdata.youtube.com/feeds/users/CONTACT_ID/inbox
En la solicitud POST, la etiqueta <id> identifica el vídeo que se va a enviar y la etiqueta <yt:description> incluye el contenido del mensaje que se enviará. En el ejemplo siguiente se muestra una solicitud de ejemplo para enviar un vídeo a otro usuario.
POST /feeds/api/users/CONTACT_ID/inbox HTTP/1.1 Host: gdata.youtube.com Content-Type: application/atom+xml Content-Length: CONTENT_LENGTH Authorization: AuthSub token=AUTHORIZATION_TOKEN X-GData-Client: CLIENT_ID X-GData-Key: key=DEVELOPER_KEY
Nota: un usuario sólo puede enviar vídeos a los usuarios incluidos en su lista de contactos.
En el siguiente caso práctico se describe cómo compartir un vídeo:
Este caso práctico comienza con una solicitud del API para recuperar información sobre un vídeo.
Después de ver el vídeo, el usuario hace clic en un enlace para enviar el vídeo a uno o varios contactos.
Tu aplicación envía una solicitud de recuperación de la lista de contactos del usuario autenticado actualmente.
Tu aplicación muestra un formulario que permite al usuario seleccionar uno o varios contactos a los que enviar el vídeo. El formulario también puede dejar que el usuario escriba un mensaje a estos contactos.
Después de que el usuario envíe el formulario, envías una solicitud PUT HTTP a cada uno de los contactos seleccionados.
Un vídeo favorito es un vídeo que un usuario ha marcado explícitamente como favorito. Un usuario puede ver y editar sus vídeos favoritos en la página de su cuenta. Los vídeos favoritos de un usuario también podrán verlos todos los usuarios de YouTube.
El API de datos de YouTube permite a los usuarios añadir o eliminar vídeos favoritos. Para añadir o eliminar un vídeo favorito, debes proporcionar el nombre de usuario de YouTube del usuario autenticado y la ID de YouTube del vídeo que se va a añadir o eliminar.
En esta sección se explica cómo recuperar un feed de los vídeos favoritos de un usuario. Ten en cuenta que es posible que algunos usuarios no hayan designado ningún vídeo favorito.
Para solicitar un feed de los vídeos favoritos del usuario conectado actualmente, envía una solicitud GET HTTP a la URL que aparece a continuación. Nota: para esta solicitud, debes enviar un token de autenticación en el encabezado de la solicitud HTTP Authorization. El token de autenticación permite que YouTube identifique al usuario.
http://gdata.youtube.com/feeds/api/users/default/favorites
Para solicitar un feed de los vídeos favoritos de otro usuario, envía una solicitud GET HTTP a la URL que aparece a continuación. Ten en cuenta que esta solicitud no requiere autenticación.
http://gdata.youtube.com/feeds/api/users/username/favorites
En la URL anterior, debes sustituir el texto username por el nombre de usuario de YouTube.
La respuesta del API de esta consulta tiene exactamente el mismo formato que la respuesta de ejemplo de la sección Entradas y feeds de vídeos de este documento.
La siguiente solicitud proporciona la URL y muestra el formato XML para añadir un vídeo a la lista de vídeos favoritos del usuario conectado:
POST /feeds/api/users/default/favorites HTTP/1.1 Host: gdata.youtube.com Content-Type: application/atom+xml Content-Length: CONTENT_LENGTH Authorization: AuthSub token=AUTHORIZATION_TOKEN X-GData-Client: CLIENT_ID X-GData-Key: key=DEVELOPER_KEY <?xml version="1.0" encoding="UTF-8"?> <entry xmlns="http://www.w3.org/2005/Atom"> <id>VIDEO_ID</id> </entry>
En la siguiente lista se identifican dos casos de uso habituales para añadir vídeos favoritos y se describen las llamadas al API asociadas a cada caso práctico:
Un usuario reproduce un vídeo y lo marca como favorito.
Este caso práctico comienza con una solicitud del API para obtener información sobre un vídeo específico.
Después de ver el vídeo, el usuario decide marcar el vídeo como favorito.
Tu aplicación envía una solicitud POST del API a http://gdata.youtube.com/feeds/api/users/default/favorites para añadir el vídeo a la lista de los favoritos del usuario.
Un usuario consulta una lista de vídeos y marca uno o varios como favoritos.
Este caso práctico comienza con una solicitud de búsqueda de vídeos o recuperación de un feed de vídeos concreto.
El usuario selecciona uno o varios vídeos de la lista; por ejemplo, el usuario podría activar la casilla de verificación situada junto a cada vídeo.
Tu aplicación repite la secuencia en los vídeos seleccionados y envía una solicitud del API para añadir cada vídeo seleccionado como favorito. Tu aplicación envía cada una de las solicitudes a http://gdata.youtube.com/feeds/api/users/default/favorites. La etiqueta <id> de cada solicitud especifica el valor de la etiqueta <id> del vídeo correspondiente en el feed de vídeos del paso anterior.
Para eliminar un vídeo favorito, envía una solicitud DELETE HTTP a la URL edit de la entrada de vídeo:
<link rel='edit' type='application/atom+xml' href='http://gdata.youtube.com/feeds/api/users/USER_ID/favorites/VIDEO_ID'>
En la siguiente solicitud del API de ejemplo se explica cómo eliminar un vídeo favorito:
DELETE /feeds/api/users/USER_ID/favorites/VIDEO_ID HTTP/1.1 Host: gdata.youtube.com Content-Type: application/atom+xml Authorization: AuthSub token=AUTHORIZATION_TOKEN X-GData-Client: CLIENT_ID X-GData-Key: key=DEVELOPER_KEY
En la siguiente lista se identifica un caso práctico habitual para eliminar vídeos favoritos y se describen las llamadas a API asociadas a dicho caso práctico:
Este caso práctico comienza con una solicitud de recuperación de un feed de los vídeos favoritos del usuario.
El usuario selecciona uno o varios vídeos de la lista; por ejemplo, el usuario podría activar la casilla de verificación situada junto a cada vídeo.
Tu aplicación repite la secuencia en los vídeos seleccionados y envía una solicitud DELETE HTTP para eliminar cada vídeo seleccionado de la lista de favoritos del usuario. Tu aplicación envía cada solicitud a la URL de edición del vídeo favorito correspondiente.
Una lista de reproducción es un grupo de vídeos que un usuario puede almacenar y ver uno tras otro, o bien compartir con otros usuarios. Un usuario puede ver y editar su lista de listas de reproducción en la página de su cuenta. Las listas de reproducción de un usuario también podrán verlas todos los usuarios de YouTube.
El API de datos de YouTube permite a los usuarios recuperar, crear, modificar y eliminar listas de reproducción.
En esta sección se explica cómo recuperar un feed que muestre las listas de reproducción de un usuario. Ten en cuenta que es posible que algunos usuarios no hayan creado ninguna lista de reproducción.
Para solicitar un feed de las listas de reproducción del usuario conectado actualmente, envía una solicitud GET HTTP a la URL que aparece a continuación. Nota: para esta solicitud, debes enviar un token de autenticación en el encabezado de la solicitud HTTP Authorization. El token de autenticación permite que YouTube identifique al usuario.
http://gdata.youtube.com/feeds/api/users/default/playlists
Para solicitar un feed de las listas de reproducción de otro usuario, envía una solicitud GET HTTP a la URL que aparece a continuación. Ten en cuenta que esta solicitud no requiere autenticación.
http://gdata.youtube.com/feeds/api/users/username/playlists
En la URL anterior, debes sustituir el texto username por el nombre de usuario de YouTube.
En el siguiente XML aparece una respuesta del API de ejemplo con un feed de listas de reproducción. La respuesta contiene una serie de etiquetas <entry>. En cada una de ellas aparece la descripción de una lista de reproducción. Cada entrada contiene el título, la descripción, el autor y la fecha de modificación de una lista de reproducción, así como una etiqueta <gd:feedLink> que especifica la URL para recuperar la lista de vídeos de la lista de reproducción.
<?xml version='1.0' encoding='UTF-8'?> <feed xmlns='http://www.w3.org/2005/Atom' xmlns:openSearch='http://a9.com/-/spec/opensearchrss/1.0/' xmlns:media='http://search.yahoo.com/mrss/' xmlns:yt='http://gdata.youtube.com/schemas/2007' xmlns:gd='http://schemas.google.com/g/2005'> <id>http://gdata.youtube.com/feeds/api/users/andyland74/playlists?start-index=1&max-results=25</id> <updated>2008-02-26T00:26:15.635Z</updated> <category scheme='http://schemas.google.com/g/2005#kind' term='http://gdata.youtube.com/schemas/2007#playlistLink'/> <title type='text'>andyland74's Playlists</title> <logo>http://www.youtube.com/img/pic_youtubelogo_123x63.gif</logo> <link rel='related' type='application/atom+xml' href='http://gdata.youtube.com/feeds/api/users/andyland74'/> <link rel='alternate' type='text/html' href='http://www.youtube.com/profile_play_list?user=andyland74'/> <link rel='http://schemas.google.com/g/2005#feed' type='application/atom+xml' href='http://gdata.youtube.com/feeds/api/users/andyland74/playlists'/> <link rel='self' type='application/atom+xml' href='http://gdata.youtube.com/feeds/api/users/andyland74/playlists?start-index=1&max-results=25'/> <author> <name>andyland74</name> <uri>http://gdata.youtube.com/feeds/api/users/andyland74</uri> </author> <generator version='beta' uri='http://gdata.youtube.com/'>YouTube data API</generator> <openSearch:totalResults>1</openSearch:totalResults> <openSearch:startIndex>1</openSearch:startIndex> <openSearch:itemsPerPage>25</openSearch:itemsPerPage> <entry> <id>http://gdata.youtube.com/feeds/api/users/andyland74/playlists/8BCDD04DE8F771B2</id> <published>2007-11-04T17:30:27.000-08:00</published> <updated>2008-02-22T09:55:14.000-08:00</updated> <category scheme='http://schemas.google.com/g/2005#kind' term='http://gdata.youtube.com/schemas/2007#playlistLink'/> <title type='text'>My New Playlist Title</title> <content type='text'>My new playlist Description</content> <link rel='related' type='application/atom+xml' href='http://gdata.youtube.com/feeds/api/users/andyland74'/> <link rel='alternate' type='text/html' href='http://www.youtube.com/view_play_list?p=8BCDD04DE8F771B2'/> <link rel='self' type='application/atom+xml' href='http://gdata.youtube.com/feeds/api/users/andyland74/playlists/8BCDD04DE8F771B2'/> <author> <name>andyland74</name> <uri>http://gdata.youtube.com/feeds/api/users/andyland74</uri> </author> <yt:description>My new playlist Description</yt:description> <gd:feedLink rel='http://gdata.youtube.com/schemas/2007#playlist' href='http://gdata.youtube.com/feeds/api/playlists/8BCDD04DE8F771B2'/> </entry> </feed>
Tal como se ha mencionado en la sección anterior, cada entrada de un feed de listas de reproducción contiene una etiqueta <gd:feedLink> que especifica la URL para recuperar la lista de vídeos de la lista de reproducción. En el siguiente ejemplo se muestra la URL para recuperar una lista de reproducción, tal como aparece en una entrada de feed de listas de reproducción:
<gd:feedLink rel='http://gdata.youtube.com/schemas/2007#playlist'
href='http://gdata.youtube.com/feeds/api/playlists/8BCDD04DE8F771B2'/>
La respuesta del API de un feed de lista de reproducción es casi idéntica a un típico feed de vídeos o conjunto de resultados de búsqueda. No obstante, dado que los propietarios de las listas de reproducción pueden optar por definir sus propios títulos y descripciones para cada vídeo de sus listas de reproducción, las entradas de feeds deben incluir estos valores personalizados. Así pues, una entrada de vídeo de un feed de lista de reproducción se diferencia de una entrada de vídeo típica en lo siguiente:
El título definido por el usuario para el vídeo aparece en la etiqueta <atom:title>, y el título original del vídeo aparece en la etiqueta <media:title>.
Si el propietario de la lista de reproducción ha definido una descripción personalizada, dicha descripción aparecerá en una etiqueta <yt:description>. La etiqueta <yt:description> es una subetiqueta de la etiqueta <entry>.
Cada entrada de la lista de reproducción contiene la etiqueta <yt:position>, que especifica el lugar en el que aparece el vídeo según el orden de la lista de reproducción. La etiqueta <yt:position> es una subetiqueta de la etiqueta <entry>.
Para crear una lista de reproducción, debes proporcionar un título y una descripción para la lista de reproducción. La etiqueta <yt:private>, que es opcional, indica si cualquier usuario podrá ver la lista de reproducción. (De forma predeterminada, las listas de reproducción están visibles para el resto de usuarios).
La siguiente solicitud proporciona la URL y muestra el formato XML para crear una nueva lista de reproducción:
POST /feeds/api/users/default/playlists HTTP/1.1 Host: gdata.youtube.com Content-Type: application/atom+xml Content-Length: CONTENT_LENGTH Authorization: AuthSub token=AUTHORIZATION_TOKEN X-GData-Client: CLIENT_ID X-GData-Key: key=DEVELOPER_KEY <?xml version="1.0" encoding="UTF-8"?> <entry xmlns="http://www.w3.org/2005/Atom" xmlns:yt="http://gdata.youtube.com/schemas/2007"> <title type="text">Sports Highlights Playlist</title> <yt:description>A selection of sports highlights</yt:description> </entry>
En la siguiente lista se identifican dos casos de uso habituales para crear una lista de reproducción y se describen las llamadas a API asociadas a cada caso práctico:
Un usuario ve un vídeo y crea una nueva lista de reproducción que incluye el vídeo.
Este caso práctico comienza con una solicitud del API para obtener información sobre un vídeo específico.
Después de ver el vídeo, el usuario hace clic en un enlace para añadir el vídeo a una nueva lista de reproducción. Tu aplicación muestra un formulario que permite al usuario introducir un título y una descripción para la lista de reproducción.
Tu aplicación envía una solicitud POST HTTP a http://gdata.youtube.com/feeds/api/users/default/playlists para crear la lista de reproducción. La solicitud del API especifica el título y la descripción de la lista de reproducción que el usuario ha introducido.
Tu aplicación envía una solicitud del API adicional para añadir el vídeo seleccionado a la lista de reproducción.
Un usuario echa un vistazo a los vídeos y selecciona uno o varios vídeos para añadirlos a una nueva lista de reproducción.
Este caso práctico comienza con una solicitud del API para buscar vídeos o recuperar un feed de vídeos concreto.
El usuario selecciona uno o varios vídeos de la lista para añadirlos a una nueva lista de reproducción; por ejemplo, el usuario podría activar la casilla de verificación situada junto a cada vídeo.
Tu aplicación muestra un formulario que permite al usuario introducir un título y una descripción para la lista de reproducción.
Tu aplicación envía una solicitud POST HTTP a http://gdata.youtube.com/feeds/api/users/default/playlists para crear la lista de reproducción utilizando el título y la descripción que ha introducido el usuario.
A continuación, tu aplicación repite la secuencia en los vídeos seleccionados y envía una solicitud del API adicional para añadir cada vídeo seleccionado a la lista de reproducción.
La solicitud del API para actualizar una lista de reproducción permite al usuario actualizar el título, la descripción y el estado público/privado de dicha lista de reproducción. El API define solicitudes adicionales para añadir un vídeo a una lista de reproducción, actualizar un vídeo de una lista de reproducción o eliminar un vídeo de una lista de reproducción.
La siguiente solicitud de ejemplo proporciona la URL y describe el formato XML para modificar una lista de reproducción. Ten en cuenta que el XML enviado en la solicitud tiene el mismo formato que una solicitud de creación de una lista de reproducción. No obstante, esta solicitud es una solicitud PUT HTTP y la URL del API debe especificar la ID de la lista de reproducción que se va a actualizar.
PUT /feeds/api/users/USER_ID/playlists/PLAYLIST_ID HTTP/1.1 Host: gdata.youtube.com Content-Type: application/atom+xml Content-Length: CONTENT_LENGTH Authorization: AuthSub token=AUTHORIZATION_TOKEN X-GData-Client: CLIENT_ID X-GData-Key: key=DEVELOPER_KEY <?xml version="1.0" encoding="UTF-8"?> <entry xmlns="http://www.w3.org/2005/Atom" xmlns:yt="http://gdata.youtube.com/schemas/2007"> <title type="text">Sports Highlights Playlist</title> <yt:description>A selection of sports highlights</yt:description> </entry>
El siguiente caso práctico describe un ejemplo en el que un usuario va a modificar una lista de reproducción:
Este caso práctico comienza con una solicitud de recuperación de un feed de las listas de reproducción del usuario.
El usuario selecciona una lista de reproducción de la lista y hace clic en un enlace para actualizarla.
Tu aplicación muestra un formulario que permite al usuario actualizar el título y la descripción de la lista de reproducción.
A continuación, tu aplicación envía una solicitud PUT HTTP a la URL de edición de la lista de reproducción para actualizar la lista de reproducción.
Para añadir un vídeo a una lista de reproducción, deberás enviar una solicitud del API que identifique la ID única que YouTube ha asignado a la lista de reproducción, así como la ID única que YouTube ha asignado al vídeo. El usuario también puede especificar un título y una descripción para el vídeo. Además, la etiqueta <yt:position>, que es opcional, identifica la posición en la que aparecerá la entrada en la lista de reproducción. De forma predeterminada, la entrada recién creada se añadirá al final de la lista de reproducción.
La siguiente solicitud proporciona la URL y muestra el formato XML para añadir un vídeo a una lista de reproducción:
POST /feeds/api/playlists/PLAYLIST_ID HTTP/1.1 Host: gdata.youtube.com Content-Type: application/atom+xml Content-Length: CONTENT_LENGTH Authorization: AuthSub token=AUTHORIZATION_TOKEN X-GData-Client: CLIENT_ID X-GData-Key: key=DEVELOPER_KEY <?xml version="1.0" encoding="UTF-8"?> <entry xmlns="http://www.w3.org/2005/Atom" xmlns:yt="http://gdata.youtube.com/schemas/2007"> <id>PLAYLIST_ENTRY_ID</id> <title type="text">Optional custom video title</title> <yt:description>Optional custom video description</yt:description> <yt:position>4</yt:position> </entry>
En la siguiente lista se identifican dos casos de uso habituales en los que se añade un vídeo a una lista de reproducción y se describen las llamadas a API asociadas a cada caso práctico:
Un usuario ve un vídeo y añade el vídeo a una lista de reproducción.
Este caso práctico comienza con una solicitud del API para obtener información sobre un vídeo específico.
Después de ver el vídeo, el usuario hace clic en un enlace para añadir el vídeo a una lista de reproducción.
Tu aplicación envía una solicitud del API para recuperar una lista con las listas de reproducción del usuario. En la respuesta del API, la etiqueta <gd:feedLink> de cada entrada identifica la URL que se deberá utilizar para añadir un vídeo a la lista de reproducción correspondiente.
El usuario selecciona una lista de reproducción existente y la aplicación envía una solicitud del API para añadir el vídeo seleccionado a dicha lista de reproducción.
Un usuario consulta los vídeos y selecciona uno o varios vídeos para añadirlos a una lista de reproducción.
Este caso práctico comienza con una solicitud del API para buscar vídeos o recuperar un feed de vídeos concreto.
El usuario selecciona uno o varios vídeos de la lista para añadirlos a una lista de reproducción; por ejemplo, el usuario podría activar la casilla de verificación situada junto a cada vídeo.
Tu aplicación envía una solicitud del API para recuperar una lista con las listas de reproducción del usuario. En la respuesta del API, la etiqueta <gd:feedLink> identifica la URL que se deberá utilizar para añadir una entrada a cada lista de reproducción.
El usuario selecciona una lista de reproducción y la aplicación repite la secuencia en los vídeos seleccionados y envía una solicitud del API para cada vídeo seleccionado a la lista de reproducción. En cada solicitud del API, el código XML especifica el identificador <id> del vídeo que se va a añadir.
Cuando un usuario actualiza una entrada de una lista de reproducción, puede modificar el título o la descripción personalizados asociados a dicha entrada de la lista de reproducción. El usuario también puede modificar el orden en el que aparecerá la entrada en la lista de reproducción.
En la siguiente solicitud de ejemplo se muestra el formato XML que permite modificar una entrada de una lista de reproducción. Ten en cuenta que el XML enviado en la solicitud tiene el mismo formato que una solicitud de creación de una entrada en una lista de reproducción. No obstante, esta solicitud es una solicitud PUT HTTP y la URL del API, que especifica la ID de la lista de reproducción que se va a actualizar, es distinta.
PUT /feeds/api/playlists/PLAYLIST_ID/PLAYLIST_ENTRY_ID HTTP/1.1 Host: gdata.youtube.com Content-Type: application/atom+xml Content-Length: CONTENT_LENGTH Authorization: AuthSub token=AUTHORIZATION_TOKEN X-GData-Client: CLIENT_ID X-GData-Key: key=DEVELOPER_KEY <?xml version="1.0" encoding="UTF-8"?> <entry xmlns="http://www.w3.org/2005/Atom" xmlns:yt="http://gdata.youtube.com/schemas/2007"> <title type="text">Sports Highlights Playlist</title> <yt:description>A selection of sports highlights</yt:description> <yt:position>2</yt:position> </entry>
El siguiente caso práctico describe un ejemplo en el que un usuario va a modificar una entrada de una lista de reproducción:
Este caso práctico comienza con una solicitud de recuperación de una lista de reproducción específica. Ten en cuenta que al recuperar una lista de vídeos de una lista de reproducción, cada etiqueta <entry> incluye la información de un único vídeo de la lista de reproducción. La URL que se debe utilizar para actualizar o eliminar una lista de reproducción se especifica en la etiqueta <gd:feedLink> dentro de la etiqueta <entry>.
Tu aplicación muestra la lista de entradas de la lista de reproducción y presenta una opción para que el usuario reorganice el orden en el que YouTube reproducirá los vídeos de la lista de reproducción.
El usuario reordena las entradas de la lista de reproducción y hace clic en un enlace para actualizar la lista de reproducción.
Tu aplicación repite la secuencia en todas las entradas de la lista de reproducción para actualizar el valor de la etiqueta <yt:position> de cada entrada. Tu aplicación deberá enviar una solicitud del API por cada entrada que se vaya a actualizar. Cada solicitud del API se debe enviar a la URL de edición de la entrada de la lista de reproducción.
En la siguiente solicitud del API de ejemplo se explica cómo eliminar una entrada de una lista de reproducción: Ten en cuenta que al recuperar una lista de vídeos de una lista de reproducción, cada etiqueta <entry> incluye la información de un único vídeo de la lista de reproducción. La URL que se debe utilizar para actualizar o eliminar una lista de reproducción se especifica en la etiqueta <gd:feedLink> dentro de la etiqueta <entry>.
DELETE /feeds/api/playlists/PLAYLIST_ID/PLAYLIST_ENTRY_ID HTTP/1.1 Host: gdata.youtube.com Content-Type: application/atom+xml Authorization: AuthSub token=AUTHORIZATION_TOKEN X-GData-Client: CLIENT_ID X-GData-Key: key=DEVELOPER_KEY
La siguiente lista describe un caso práctico común para eliminar una entrada de una lista de reproducción:
Este caso práctico comienza con una solicitud de recuperación de una lista de reproducción específica.
Tu aplicación muestra la lista de entradas de la lista de reproducción con una casilla de verificación junto a cada entrada, de modo que el usuario puede activar las entradas que se van a eliminar.
Tu aplicación repite la secuencia en las entradas seleccionadas y envía una solicitud DELETE HTTP para cada entrada que se va a eliminar de la lista de reproducción. Tu aplicación envía cada solicitud del API a la URL de edición de la entrada de la lista de reproducción que se va a eliminar.
Si eliminas una lista de reproducción, eliminarás todo el contenido de dicha lista de reproducción. En la siguiente solicitud del API de ejemplo se explica cómo eliminar una lista de reproducción:
DELETE /feeds/api/users/USER_ID/playlists/PLAYLIST_ID HTTP/1.1 Host: gdata.youtube.com Content-Type: application/atom+xml Authorization: AuthSub token=AUTHORIZATION_TOKEN X-GData-Client: CLIENT_ID X-GData-Key: key=DEVELOPER_KEY
La siguiente lista describe un caso práctico común para eliminar una lista de reproducción:
Este caso práctico comienza con una solicitud de recuperación de un feed de las listas de reproducción del usuario.
El usuario selecciona una lista de reproducción de la lista para eliminarla y tú envías una solicitud del API para eliminar la lista de reproducción.
El término suscripción hace referencia a una entidad que notifica a un usuario la subida de nuevos vídeos. Los usuarios se pueden suscribir al canal de otro usuario, a la lista de favoritos de otro usuario o a una etiqueta de palabra clave. Un usuario puede ver y editar su lista de suscripciones en la página de su cuenta. Las listas de suscripciones de un usuario también podrán verlas todos los usuarios de YouTube.
El API de datos de YouTube permite a un usuario crear o eliminar suscripciones.
En esta sección se explica cómo recuperar un feed que muestre las suscripciones de un usuario. Ten en cuenta que es posible que algunos usuarios no hayan creado ninguna lista de suscripciones.
Para solicitar un feed de las suscripciones del usuario conectado actualmente, envía una solicitud GET HTTP a la URL que aparece a continuación. Nota: para esta solicitud, debes enviar un token de autenticación en el encabezado de la solicitud HTTP Authorization. El token de autenticación permite que YouTube identifique al usuario.
http://gdata.youtube.com/feeds/api/users/default/subscriptions
Para solicitar un feed de las suscripciones de otro usuario, envía una solicitud GET HTTP a la URL que aparece a continuación. Ten en cuenta que esta solicitud no requiere autenticación.
http://gdata.youtube.com/feeds/api/users/username/subscriptions
En la URL anterior, debes sustituir el texto username por el nombre de usuario de YouTube.
En el siguiente XML aparece una respuesta del API de ejemplo con un feed de suscripciones. La respuesta contiene una serie de etiquetas <entry>. En cada una de ellas aparece la descripción de una suscripción. Los usuarios pueden suscribirse a canales de YouTube, a las listas de videos favoritos de otros usuarios y a etiquetas de palabras clave. Cada entrada del feed de suscripciones contiene una etiqueta <category> para la que el valor del atributo scheme es http://gdata.youtube.com/schemas/2007/subscriptiontypes.cat. El valor del atributo term de dicha etiqueta <category> indica si la suscripción es a un canal, a una lista de vídeos favoritos o a una etiqueta de palabra clave.
Si la entrada del feed describe una suscripción a un canal, el atributo term de la etiqueta <category> tendrá un valor de channel. La entrada también contendrá el elemento <yt:username>, que especificará el propietario del canal.
Si la entrada del feed describe una suscripción a la lista de vídeos favoritos de otro usuario, el atributo term de la etiqueta <category> tendrá un valor de favorites. La entrada también contendrá el elemento <yt:username>, que especifica al usuario a cuyos vídeos favoritos se realiza la suscripción.
Si la entrada del feed describe una suscripción a una palabra clave, el atributo term de la etiqueta <category> tendrá un valor de query. La entrada también contendrá el elemento <yt:queryString>, que especifica la palabra clave a la que se realiza la suscripción.
En el siguiente XML aparece una respuesta del API de ejemplo con un feed de suscripciones. La respuesta contiene una serie de tres etiquetas <entry>. En las etiquetas aparece una suscripción a un canal, a una palabra clave y a vídeos favoritos. La etiqueta <gd:feedLink> de cada entrada especifica la URL para recuperar los vídeos de dicha suscripción. En la segunda y la tercera entrada sólo aparecen las etiquetas que contienen valores distintos a los de las etiquetas de la primera entrada.
<?xml version='1.0' encoding='UTF-8'?> <feed xmlns='http://www.w3.org/2005/Atom' xmlns:openSearch='http://a9.com/-/spec/opensearchrss/1.0/' xmlns:media='http://search.yahoo.com/mrss/' xmlns:yt='http://gdata.youtube.com/schemas/2007' xmlns:gd='http://schemas.google.com/g/2005'> <id>http://gdata.youtube.com/feeds/api/users/andyland74/subscriptions?start-index=1&max-results=25</id> <updated>2008-02-26T00:26:15.635Z</updated> <category scheme='http://schemas.google.com/g/2005#kind' term='http://gdata.youtube.com/schemas/2007#subscription'/> <title type='text'>andyland74's Subscriptions</title> <logo>http://www.youtube.com/img/pic_youtubelogo_123x63.gif</logo> <link rel='related' type='application/atom+xml' href='http://gdata.youtube.com/feeds/api/users/andyland74'/> <link rel='alternate' type='text/html' href='http://www.youtube.com/profile_subscriptions?user=andyland74'/> <link rel='http://schemas.google.com/g/2005#feed' type='application/atom+xml' href='http://gdata.youtube.com/feeds/api/users/andyland74/subscriptions'/> <link rel='self' type='application/atom+xml' href='http://gdata.youtube.com/feeds/api/users/andyland74/subscriptions?start-index=1&max-results=25'/> <author> <name>andyland74</name> <uri>http://gdata.youtube.com/feeds/api/users/andyland74</uri> </author> <generator version='beta' uri='http://gdata.youtube.com/'>YouTube data API</generator> <openSearch:totalResults>1</openSearch:totalResults> <openSearch:startIndex>1</openSearch:startIndex> <openSearch:itemsPerPage>25</openSearch:itemsPerPage> <entry> <id>http://gdata.youtube.com/feeds/api/users/andyland74/subscriptions/d411759045e2ad8c</id> <published>2007-11-04T17:30:27.000-08:00</published> <updated>2008-02-22T09:55:14.000-08:00</updated> <category scheme='http://gdata.youtube.com/schemas/2007/subscriptiontypes.cat' term='channel'/> <category scheme='http://schemas.google.com/g/2005#kind' term='http://gdata.youtube.com/schemas/2007#subscription'/> <title type='text'>Videos published by : NBC</title> <link rel='related' type='application/atom+xml' href='http://gdata.youtube.com/feeds/api/users/andyland74'/> <link rel='alternate' type='text/html' href='http://www.youtube.com/profile_videos?user=NBC'/> <link rel='self' type='application/atom+xml' href='http://gdata.youtube.com/feeds/api/users/andyland74/subscriptions/d411759045e2ad8c'/> <author> <name>andyland74</name> <uri>http://gdata.youtube.com/feeds/api/users/andyland74</uri> </author> <yt:username>NBC</yt:username> <gd:feedLink rel='http://gdata.youtube.com/schemas/2007#user.uploads' href='http://gdata.youtube.com/feeds/api/users/nbc/uploads'/> </entry> <entry> ... <category scheme='http://gdata.youtube.com/schemas/2007/subscriptiontypes.cat' term='query'/> <title type='text'>Videos matching : surfing</title> <link rel='alternate' type='text/html' href='http://www.youtube.com/results?search_query=surfing'/> ... <yt:queryString>surfing</yt:queryString> <gd:feedLink rel='http://gdata.youtube.com/schemas/2007#video.query' href='http://gdata.youtube.com/feeds/api/videos?vq=surfing'/> </entry> <entry> ... <category scheme='http://gdata.youtube.com/schemas/2007/subscriptiontypes.cat' term='favorites'/> <title type='text'>Favorites of : kemlye</title> <link rel='alternate' type='text/html' href='http://www.youtube.com/profile_favorites?user=kemlye'/> ... <yt:username>kemlye</yt:username> <gd:feedLink rel='http://gdata.youtube.com/schemas/2007#user.uploads' href='http://gdata.youtube.com/feeds/api/users/kemlye/favorites'/> </entry> </feed>
Para crear una suscripción, deberás identificar el nombre de usuario de YouTube del usuario autenticado que va a crear la suscripción. También deberás utilizar la etiqueta <category> para indicar si el usuario se va a suscribir a un canal, una lista de favoritos o una palabra clave. Si el usuario autenticado se va a suscribir a un canal o una lista de favoritos, la etiqueta <yt:username> identifica el nombre de usuario asociado al canal o la lista de favoritos a los que se va a suscribir el usuario autenticado. Si el usuario autenticado se va a suscribir a una búsqueda de palabra clave, la etiqueta <yt:queryString> identifica la palabra clave asociada a la nueva suscripción.
Las siguientes solicitudes muestran el formato XML que permite crear suscripciones:
POST /feeds/api/users/default/subscriptions HTTP/1.1 Host: gdata.youtube.com Content-Type: application/atom+xml Content-Length: CONTENT_LENGTH Authorization: AuthSub token=AUTHORIZATION_TOKEN X-GData-Client: CLIENT_ID X-GData-Key: key=DEVELOPER_KEY <?xml version="1.0" encoding="UTF-8"?> <entry xmlns="http://www.w3.org/2005/Atom" xmlns:yt="http://gdata.youtube.com/schemas/2007"> <category scheme="http://gdata.youtube.com/schemas/2007/subscriptiontypes.cat" term="channel"/> <yt:username>andyland74</yt:username> </entry>
POST /feeds/api/users/default/subscriptions HTTP/1.1 Host: gdata.youtube.com Content-Type: application/atom+xml Content-Length: CONTENT_LENGTH Authorization: AuthSub token=AUTHORIZATION_TOKEN X-GData-Client: CLIENT_ID X-GData-Key: key=DEVELOPER_KEY <?xml version="1.0" encoding="UTF-8"?> <entry xmlns="http://www.w3.org/2005/Atom" xmlns:yt="http://gdata.youtube.com/schemas/2007"> <category scheme="http://gdata.youtube.com/schemas/2007/subscriptiontypes.cat" term="favorites"/> <yt:username>andyland74</yt:username> </entry>
POST /feeds/api/users/default/subscriptions HTTP/1.1 Host: gdata.youtube.com Content-Type: application/atom+xml Content-Length: CONTENT_LENGTH Authorization: AuthSub token=AUTHORIZATION_TOKEN X-GData-Client: CLIENT_ID X-GData-Key: key=DEVELOPER_KEY <?xml version="1.0" encoding="UTF-8"?> <entry xmlns="http://www.w3.org/2005/Atom" xmlns:yt="http://gdata.youtube.com/schemas/2007"> <category scheme="http://gdata.youtube.com/schemas/2007/subscriptiontypes.cat" term="query"/> <yt:queryString>Dog Skateboarding</yt:queryString> </entry>
En la siguiente lista se identifican casos de uso habituales para crear suscripciones y se describen las llamadas a API asociadas a cada caso práctico:
Un usuario ve un vídeo y se suscribe al canal del propietario del vídeo.
Este caso práctico comienza con una solicitud del API para recuperar información sobre un vídeo específico.
Después de ver el vídeo, el usuario hace clic en un enlace para suscribirse al canal del propietario del vídeo.
Tu aplicación envía una solicitud del API a http://gdata.youtube.com/feeds/api/users/default/subscriptions para crear la suscripción. En la entrada XML de la solicitud, el valor de la etiqueta <yt:username> especifica al nombre de usuario de YouTube del propietario del vídeo y el atributo term de la etiqueta <category> tiene el valor channel.
Un usuario ve un vídeo y, a continuación, se suscribe a todos los vídeos que coinciden con una palabra clave asociada a dicho vídeo.
Este caso práctico comienza con una solicitud del API para buscar vídeos o recuperar un feed de vídeos concreto.
El usuario hace clic en un vídeo del conjunto de resultados del paso 1, lo que genera una segunda solicitud del API para recuperar información sobre dicho vídeo específico. En este paso, el usuario accede a una página para ver el vídeo seleccionado.
En la página donde el usuario ve el vídeo aparece una lista de palabras clave asociadas al vídeo y permite al usuario suscribirse a palabras clave individuales. El usuario hace clic en un enlace para suscribirse a una palabra clave.
Tu aplicación envía una solicitud del API a http://gdata.youtube.com/feeds/api/users/default/subscriptions para crear la suscripción. En la entrada XML de la solicitud, el valor de la etiqueta <yt:queryString> es la palabra clave. El atributo term de la etiqueta <category> tiene el valor query.
En la siguiente solicitud del API de ejemplo se explica cómo eliminar una suscripción:
DELETE /feeds/api/users/USER_ID/subscriptions/SUBSCRIPTION_ID HTTP/1.1 Host: gdata.youtube.com Content-Type: application/atom+xml Authorization: AuthSub token=AUTHORIZATION_TOKEN X-GData-Client: CLIENT_ID X-GData-Key: key=DEVELOPER_KEY
En la siguiente lista se identifica un caso práctico común para eliminar una suscripción:
Un usuario consulta su lista de suscripciones y elimina una o varias suscripciones de la lista.
Este caso práctico comienza con una solicitud de recuperación de un feed de las suscripciones del usuario.
Tu aplicación muestra una lista de las suscripciones del usuario y el usuario selecciona una o varias suscripciones para eliminarla.
Tu aplicación repite la secuencia en las suscripciones seleccionadas y envía una solicitud DELETE HTTP para eliminar cada suscripción seleccionada de la lista de suscripciones del usuario. Cada solicitud del API se envía a la URL de edición de la suscripción.
Un perfil de usuario contiene información sobre un usuario como, por ejemplo, sus aficiones, su empleo o sus canciones, películas o libros favoritos. Cualquier información personal que aparezca en un feed de perfil de usuario la habrá introducido el propio usuario para su publicación en YouTube. El API de datos de YouTube permite recuperar perfiles de usuario.
En esta sección se explica cómo recuperar una entrada con información sobre el perfil de un usuario específico.
Para solicitar el perfil del usuario conectado actualmente, envía una solicitud GET HTTP a la URL que aparece a continuación. Nota: para esta solicitud, debes enviar un token de autenticación en el encabezado de la solicitud HTTP Authorization. El token de autenticación permite que YouTube identifique al usuario.
http://gdata.youtube.com/feeds/api/users/default
Para solicitar el perfil de otro usuario, envía una solicitud GET HTTP a la URL que aparece a continuación. Ten en cuenta que esta solicitud no requiere autenticación.
http://gdata.youtube.com/feeds/api/users/username
En la URL anterior, debes sustituir el texto username por el nombre de usuario de YouTube.
Una respuesta del API a una solicitud de un perfil de usuario contiene una única etiqueta <entry>. La entrada de perfil contiene la siguiente información:
Varias de las etiquetas del espacio de nombre yt identifican la información personal que el usuario ha añadido a su perfil de YouTube como, por ejemplo, su edad, sus libros favoritos, su empleo o su centro de estudios.
La etiqueta <media:thumbnail> contiene una fotografía subida por el usuario a su perfil o, en caso de que no exista ninguna, una imagen predeterminada.
La etiqueta <yt:statistics> contiene los datos estadísticos del usuario, incluido el número de personas que han visto el perfil del usuario, el número de vídeos que el usuario ha visto y el número de personas que se han suscrito a los vídeos subidos por el usuario.
Una serie de etiquetas <gd:feedLink> proporcionan las URL para recuperar los vídeos subidos por el usuario, los contactos, las suscripciones, las listas de reproducción y los vídeos favoritos del usuario.
En el siguiente código XML aparece una respuesta del API de ejemplo con un perfil de usuario.
<?xml version='1.0' encoding='UTF-8'?> <entry xmlns='http://www.w3.org/2005/Atom' xmlns:media='http://search.yahoo.com/mrss/' xmlns:yt='http://gdata.youtube.com/schemas/2007' xmlns:gd='http://schemas.google.com/g/2005'> <id>http://gdata.youtube.com/feeds/api/users/andyland74</id> <published>2006-10-16T00:09:45.000-07:00</published> <updated>2008-02-26T11:48:21.000-08:00</updated> <category scheme='http://gdata.youtube.com/schemas/2007/channeltypes.cat' term='Standard'/> <category scheme='http://schemas.google.com/g/2005#kind' term='http://gdata.youtube.com/schemas/2007#userProfile'/> <title type='text'>andyland74 Channel</title> <link rel='alternate' type='text/html' href='http://www.youtube.com/profile?user=andyland74'/> <link rel='self' type='application/atom+xml' href='http://gdata.youtube.com/feeds/api/users/andyland74'/> <author> <name>andyland74</name> <uri>http://gdata.youtube.com/feeds/api/users/andyland74</uri> </author> <yt:age>33</yt:age> <yt:username>andyland74</yt:username> <yt:books>Catch-22</yt:books> <yt:gender>m</yt:gender> <yt:company>Google</yt:company> <yt:hobbies>Testing YouTube APIs</yt:hobbies> <yt:location>US</yt:location> <yt:movies>Aqua Teen Hungerforce</yt:movies> <yt:music>Elliott Smith</yt:music> <yt:occupation>Technical Writer</yt:occupation> <yt:school>University of North Carolina</yt:school> <media:thumbnail url='http://i.ytimg.com/vi/YFbSxcdOL-w/default.jpg'/> <yt:statistics viewCount='9' videoWatchCount='21' subscriberCount='1' lastWebAccess='2008-02-25T16:03:38.000-08:00'/> <gd:feedLink rel='http://gdata.youtube.com/schemas/2007#user.favorites' href='http://gdata.youtube.com/feeds/api/users/andyland74/favorites' countHint='4'/> <gd:feedLink rel='http://gdata.youtube.com/schemas/2007#user.contacts' href='http://gdata.youtube.com/feeds/api/users/andyland74/contacts' countHint='1'/> <gd:feedLink rel='http://gdata.youtube.com/schemas/2007#user.inbox' href='http://gdata.youtube.com/feeds/api/users/andyland74/inbox' countHint='0'/> <gd:feedLink rel='http://gdata.youtube.com/schemas/2007#user.playlists' href='http://gdata.youtube.com/feeds/api/users/andyland74/playlists'/> <gd:feedLink rel='http://gdata.youtube.com/schemas/2007#user.subscriptions' href='http://gdata.youtube.com/feeds/api/users/andyland74/subscriptions' countHint='4'/> <gd:feedLink rel='http://gdata.youtube.com/schemas/2007#user.uploads' href='http://gdata.youtube.com/feeds/api/users/andyland74/uploads' countHint='1'/> </entry>
El API de datos de YouTube permite a los usuarios añadir, actualizar o eliminar contactos.
En esta sección se explica cómo recuperar un feed con una lista de los contactos de un usuario específico.
Para solicitar la lista de contactos del usuario conectado actualmente, envía una solicitud GET HTTP a la URL que aparece a continuación. Nota: para esta solicitud, debes enviar un token de autenticación en el encabezado de la solicitud HTTP Authorization. El token de autenticación permite que YouTube identifique al usuario.
http://gdata.youtube.com/feeds/api/users/default/contacts
Para solicitar la lista de contactos de otro usuario, envía una solicitud GET HTTP a la URL que aparece a continuación. Ten en cuenta que esta solicitud no requiere autenticación.
http://gdata.youtube.com/feeds/api/users/username/contacts
En la URL anterior, debes sustituir el texto username por el nombre de usuario de YouTube.
Una respuesta del API a una solicitud de una lista de contactos contiene una serie de etiquetas <entry>. Cada etiqueta contiene la siguiente información sobre cada contacto individual:
La URL edit, que se utilizará para actualizar o eliminar el contacto. En la sección Identificación de feeds relacionados con una entrada de feed se explica cómo identificar la URL de edición de una entrada de feed.
La etiqueta <category> indica si el contacto es un amigo o un familiar.
La etiqueta <yt:username> especifica el nombre de usuario de YouTube del contacto.
La etiqueta <yt:status> indica el estado del contacto. Esta etiqueta sólo aparece si se van a recuperar los contactos del usuario autenticado actualmente. Esta etiqueta tendrá uno de los siguientes valores:
En el siguiente código XML aparece una respuesta del API de ejemplo con un contacto:
<?xml version='1.0' encoding='UTF-8'?> <feed xmlns='http://www.w3.org/2005/Atom' xmlns:openSearch='http://a9.com/-/spec/opensearchrss/1.0/' xmlns:yt='http://gdata.youtube.com/schemas/2007'> <id>http://gdata.youtube.com/feeds/api/users/andyland74/contacts?start-index=1&max-results=25</id> <updated>2008-02-28T18:43:32.084Z</updated> <category scheme='http://schemas.google.com/g/2005#kind' term='http://gdata.youtube.com/schemas/2007#friend'/> <title type='text'>andyland74's Contacts</title> <logo>http://www.youtube.com/img/pic_youtubelogo_123x63.gif</logo> <link rel='alternate' type='text/html' href='http://www.youtube.com/profile_friends?user=andyland74'/> <link rel='http://schemas.google.com/g/2005#feed' type='application/atom+xml' href='http://gdata.youtube.com/feeds/api/users/andyland74/contacts'/> <link rel='self' type='application/atom+xml' href='http://gdata.youtube.com/feeds/api/users/andyland74/contacts?start-index=1&max-results=25'/> <link rel='next' type='application/atom+xml' href='http://gdata.youtube.com/feeds/api/users/andyland74/contacts?start-index=26&max-results=25'/> <author> <name>andyland74</name> <uri>http://gdata.youtube.com/feeds/api/users/andyland74</uri> </author> <generator version='beta' uri='http://gdata.youtube.com/'>YouTube data API</generator> <openSearch:totalResults>100</openSearch:totalResults> <openSearch:startIndex>1</openSearch:startIndex> <openSearch:itemsPerPage>25</openSearch:itemsPerPage> <entry> <id>http://gdata.youtube.com/feeds/api/users/andyland74/contacts/danidanciu</id> <published>2007-01-06T09:38:08.000-08:00</published> <updated>2008-02-28T18:43:32.082Z</updated> <category scheme='http://schemas.google.com/g/2005#kind' term='http://gdata.youtube.com/schemas/2007#friend'/> <title type='text'>danidanciu</title> <link rel='related' type='application/atom+xml' href='http://gdata.youtube.com/feeds/api/users/danidanciu'/> <link rel='alternate' type='text/html' href='http://www.youtube.com/profile?user=danidanciu'/> <link rel='self' type='application/atom+xml' href='http://gdata.youtube.com/feeds/api/users/andyland74/contacts/danidanciu'/> <author> <name>andyland74</name> <uri>http://gdata.youtube.com/feeds/api/users/andyland74</uri> </author> <yt:username>danidanciu</yt:username> <yt:status>accepted</yt:status> </entry> </feed>
Para añadir un contacto, deberás enviar una solicitud del API que identifique a los dos usuarios: el usuario que va a añadir al contacto y el contacto que se va a añadir. La solicitud también puede utilizar la etiqueta <category> para especificar si el contacto se va a añadir a la lista de familiares o amigos del usuario. Si la solicitud no especifica una categoría para el contacto, el contacto aparecerá en la lista de contactos del usuario, pero no se colocará en la categoría de familiares o amigos.
La siguiente solicitud proporciona la URL y describe el formato XML para añadir un contacto:
POST /feeds/api/users/default/contacts HTTP/1.1 Host: gdata.youtube.com Content-Type: application/atom+xml Content-Length: CONTENT_LENGTH Authorization: AuthSub token=AUTHORIZATION_TOKEN X-GData-Client: CLIENT_ID X-GData-Key: key=DEVELOPER_KEY <?xml version="1.0" encoding="UTF-8"?> <entry xmlns="http://www.w3.org/2005/Atom" xmlns:yt="http://gdata.youtube.com/schemas/2007"> <category scheme="http://gdata.youtube.com/schemas/2007/contact.cat" term="Friends"/> <yt:username>CONTACT_ID</yt:username> </entry>
En la siguiente lista se identifica un caso práctico común para añadir un contacto:
Un usuario ve un vídeo y, a continuación, añade al propietario del vídeo como amigo.
Este caso práctico comienza con una solicitud de recuperación de información sobre un vídeo específico.
Después de ver el vídeo, el usuario hace clic en un enlace para ver el perfil del propietario del vídeo.
Tu aplicación envía una solicitud del API para recuperar el perfil del propietario del vídeo.
En la página del sitio en la que se muestra la información sobre el propietario del vídeo aparecerá un enlace para añadir al propietario del vídeo como amigo. Si el usuario hace clic en este enlace, la aplicación enviará una solicitud del API a http://gdata.youtube.com/feeds/api/users/default/contacts para crear el contacto. En la solicitud, la etiqueta <yt:username> identifica el usuario de YouTube que se va a añadir como contacto. Además, el atributo term de la etiqueta <category> indica si el contacto es un amigo (term="Friends") o un familiar (term="Family").
Para actualizar un contacto, envía una solicitud PUT HTTP a la URL de edición para dicho contacto. El fragmento XML que aparece a continuación muestra cómo aparecerá la URL de edición en la entrada de un contacto:
<entry> <id>http://gdata.youtube.com/feeds/api/users/USER_ID/contacts/CONTACT_ID</id> ... <link rel='edit' type='application/atom+xml' href='http://gdata.youtube.com/feeds/api/users/USER_ID/contacts/CONTACT_ID'/> ... </entry>
El API permite a un usuario actualizar un contacto de dos formas:
Un usuario puede aceptar a un contacto con el estado requested. Para actualizar un contacto de este modo, en la solicitud del API, define el valor de la etiqueta <yt:status> en accepted, tal como aparece en la solicitud de ejemplo a continuación. (Del mismo modo, para rechazar un contacto, define el valor de la etiqueta <yt:status> en rejected).
Los contactos se pueden clasificar como amigos o familiares. Puedes utilizar el API para volver a clasificar los contactos en uno de estos dos grupos. Si clasificas un contacto como amigo, el valor de la etiqueta <category> debe ser Friends. Si clasificas un contacto como familiar, el valor de la etiqueta <category> debe ser Family.
En la siguiente solicitud de ejemplo se explica cómo actualizar un contacto. En el ejemplo, el contacto se va a aceptar y a clasificar como familiar. Ten en cuenta que en el ejemplo, la variable USER_ID hace referencia al usuario que va a añadir al contacto, y la variable CONTACT_ID hace referencia al contacto que se va a añadir.
PUT /feeds/api/users/USER_ID/contacts/CONTACT_ID HTTP/1.1 Host: gdata.youtube.com Content-Type: application/atom+xml Content-Length: CONTENT_LENGTH Authorization: AuthSub token=AUTHORIZATION_TOKEN X-GData-Client: CLIENT_ID X-GData-Key: key=DEVELOPER_KEY <?xml version="1.0" encoding="UTF-8"?> <entry xmlns="http://www.w3.org/2005/Atom" xmlns:yt="http://gdata.youtube.com/schemas/2007"> <category scheme="http://gdata.youtube.com/schemas/2007/contact.cat" term="Family"/> <status>accepted</status> </entry>
El siguiente caso práctico describe un ejemplo en el que un usuario va a modificar un contacto:
Este caso práctico comienza con una solicitud de recuperación de la lista de contactos de un usuario. Cada etiqueta <entry> de la respuesta del API incluye información sobre un contacto individual. La URL que se debe utilizar para actualizar o eliminar dicho contacto se especifica en la etiqueta <id> dentro de la etiqueta <entry>.
Tu aplicación mostrará la lista de contactos, así como un menú de selección situado junto a cada contacto que permitirá al usuario volver a clasificar el contacto como familiar o amigo. Tu aplicación también permite al usuario aceptar o rechazar los contactos con un estado pending o requested.
El usuario modifica uno o varios contactos y envía sus cambios.
Tu aplicación repite la secuencia en todos los contactos y envía una solicitud PUT HTTP para actualizar cada contacto modificado. Tu aplicación envía cada solicitud del API a la URL de edición del contacto que se va a actualizar.
En la siguiente solicitud del API de ejemplo se explica cómo eliminar un contacto:
DELETE /feeds/api/playlists/USER_ID/contacts/CONTACT_ID HTTP/1.1 Host: gdata.youtube.com Content-Type: application/atom+xml Authorization: AuthSub token=AUTHORIZATION_TOKEN X-GData-Client: CLIENT_ID X-GData-Key: key=DEVELOPER_KEY
La siguiente lista describe un caso práctico común para eliminar un contacto:
Como en el caso práctico de modificación de un contacto, este caso práctico comienza con una solicitud de recuperación de la lista de contactos de un usuario.
Tu aplicación muestra la lista de contactos, así como una casilla de verificación junto a cada contacto que permite al usuario eliminar dicho contacto.
El usuario selecciona uno o varios contactos y envía sus cambios.
Tu aplicación repite la secuencia en todos los contactos y envía una solicitud DELETE HTTP para eliminar cada contacto seleccionado. Tu aplicación envía cada solicitud del API a la URL de edición del contacto correspondiente.
En esta sección se explica la respuesta XML que puede acompañar a una solicitud del API errónea. Consulta la guía de referencia para obtener más información sobre los códigos de respuesta HTTP que devuelve el API.
Cuando se produce un error en una solicitud del API, YouTube devuelve un código de respuesta HTTP 4xx o 5xx que identifica el error de forma general, así como una respuesta XML que proporciona información más específica sobre la causa del error. Para cada error, la respuesta XML incluye un elemento <domain>, un elemento <code> y probablemente un elemento <location>. En las siguientes subsecciones aparecen los posibles valores para estos elementos y se proporciona una respuesta de error de ejemplo para cada error. Ten en cuenta que las respuestas de error pueden contener más de un error.
Un error de validación, identificado con una etiqueta <domain> con el valor yt:validation, informa de un problema relacionado con el valor de un elemento XML en una solicitud de introducción o actualización de una entrada. Las funciones del API que introducen o actualizan vídeos u otros datos pueden informar de errores yt:validation. Los errores de validación se suelen notificar a través del código de respuesta HTTP 400.
En todos los errores de validación, la etiqueta <location> define la ubicación del error como una ruta Xpath que indica la etiqueta XML que ha causado el error en la solicitud. La ubicación de la ruta Xpath se especifica en relación con la etiqueta <entry> de la solicitud.
En los errores de validación, la etiqueta <code> contiene más de uno de los siguientes valores:
required: este código indica que falta un campo obligatorio o tiene un valor vacío.
<?xml version='1.0' encoding='UTF-8'?> <errors> <error> <domain>yt:validation</domain> <code>required</code> <location type='xpath'>media:group/media:title/text()</location> </error> </errors>
deprecated - Este código indica que el valor de un elemento se ha desaprobado y ya no es válido. Por ejemplo, el nombre de una categoría de vídeo que se haya retirado no se podrá asociar a vídeos recién añadidos o actualizados.
<?xml version='1.0' encoding='UTF-8'?> <errors> <error> <domain>yt:validation</domain> <code>deprecated</code> <location type='xpath'> media:group/media:category[@scheme='http://gdata/youtube.com/schemas/2007/categories.cat']/text() </location> </error> </errors>
invalid_format: este código indica que el valor de un elemento XML no coincide con el formato esperado. Por ejemplo, puedes recibir este error si especificas unas coordenadas no válidas en la etiqueta <gml:pos>.
<?xml version='1.0' encoding='UTF-8'?> <errors> <error> <domain>yt:validation</domain> <code>invalid_format</code> <location type='xpath'>georss:where/gml:point/gml:pos/text()</location> </error> </errors>
invalid_character: este código indica que el valor de un campo XML contiene un carácter que no es válido. Por ejemplo, los títulos de vídeos no pueden contener el carácter menor que (<).
<?xml version='1.0' encoding='UTF-8'?> <errors> <error> <domain>yt:validation</domain> <code>invalid_character</code> <location type='xpath'>media:group/media:title/text()</location> </error> </errors>
too_long: este código indica que el valor del elemento XML supera la longitud máxima permitida. Por ejemplo, los títulos de vídeos deben tener 60 caracteres como máximo.
<?xml version='1.0' encoding='UTF-8'?> <errors> <error> <domain>yt:validation</domain> <code>too_long</code> <location type='xpath'>media:group/media:title/text()</location> </error> </errors>
Un error de cupo, identificado por una etiqueta <domain> con el valor yt:quota, identifica un problema relacionado con un uso irregular del API.
En los errores de cupo, la etiqueta <code> contiene más de uno de los siguientes valores:
too_many_recent_calls: este código indica que los servidores del API han recibido demasiadas llamadas desde el mismo origen en un breve espacio de tiempo. Este error no especifica ninguna ubicación. La respuesta del API no incluye una etiqueta <location> para este tipo de error.
<?xml version='1.0' encoding='UTF-8'?> <errors> <error> <domain>yt:quota</domain> <code>too_many_recent_calls</code> </error> </errors>
too_many_entries: este código indica que el usuario está intentando superar un límite de almacenamiento en su cuenta y debe eliminar entradas existentes antes de introducir nuevas. En este tipo de error, la etiqueta <location> identifica el feed que ha causado el error.
<?xml version='1.0' encoding='UTF-8'?> <errors> <error> <domain>yt:quota</domain> <code>too_many_entries</code> <location type='other'>http://gdata.youtube.com/feeds/users/username/uploads</location> </error> </errors>
Un error de autenticación, definido por una etiqueta <domain> con el valor yt:authentication, identifica un problema relacionado con una solicitud autenticada inadecuadamente para ejecutar una función del API para la que es necesaria información de usuario. Los errores de autenticación se pueden identificar con los códigos de respuesta HTTP 401 ó 403.
Los errores de autenticación pueden incluir un elemento <location>. Si fuese así, el valor del elemento identificará el encabezado que ha causado el error de autenticación.
En los errores de autenticación, la etiqueta <code> contiene uno de los siguientes valores:
InvalidToken - Este código indica que el token de autenticación especificado en el encabezado Authorization no es válido.
<?xml version='1.0' encoding='UTF-8'?> <errors> <error> <domain>yt:authentication</domain> <code>InvalidToken</code> <location type='header'>Authorization: GoogleLogin</location> </error> </errors>
TokenExpired - Este código indica que el token de autenticación especificado en el encabezado Authorization ha caducado.
<?xml version='1.0' encoding='UTF-8'?> <errors> <error> <domain>yt:authentication</domain> <code>TokenExpired</code> <location type='header'>Authorization: GoogleLogin</location> </error> </errors>