Guía de aprendizaje: uso de las API REST

En este tema, primero obtendrá una descripción general de alto nivel sobre el uso de las API REST. Entonces, más adelante en el documento, una inmersión más profunda discutirá el código de ejemplo. El primer ejemplo emplea el Analytics API para recuperar y mostrar en la barra de control del reproductor la cantidad de vistas que el video que el jugador tiene hoy día tiene. El segundo ejemplo, un tanto más complejo, usa el Analytics API en conjunción con la Brightcove Player Catálogo para recobrar los vídeos más populares de una cuenta y mostrarlos en una lista de reproducción. La discusión del código en este documento se centrará en recobrar los datos deseados de la API REST adecuada.

Vista de alto nivel

Para emplear las API REST necesita tener algunas piezas en su lugar. Resumiendo, son:

• Codigo del cliente: El código del cliente del servicio solicita datos específicos y luego los muestra según los requisitos de la aplicación. El código del cliente del servicio se tratará con determinada extensión en este documento, puesto que es lo que necesitará redactar con más frecuencia.

• Los servidores proxy: Por razones de seguridad, las API REST no aceptarán peticiones de datos de manera directa del cliente del servicio, en tanto que eso alentaría el envío de información reservado, como credenciales del usuario, desde el cliente. Esto significa que un proxy actuará como intermediario entre el cliente del servicio y la API REST. El proxy utilizado en los ejemplos está escrito en PHP y se examina más adelante en este documento. El proxy debe configurarse en un servidor bajo su control, y puede escribirse en el idioma de su elección. La configuración sugerida del proxy le permite ser escrita una vez y utilizada por cualquiera de las API.

• API REST: Brightcove suministra un conjunto completo de API para personalizar, ampliar y también integrar con el Brightcove plataforma. Ver eldocumento para más información.

El siguiente diagrama muestra la interacción entre las 3 entidades centrales del proceso para recuperar datos de una de BrightcoveAPIs de REST:

Descripción de la funcionalidad del cliente

El código del lado del usuario cambia significativamente en dependencia de la API a la que pide los datos. Como se mencionó anteriormente, el proxy es una escritura una vez y no altera una parte del código, y las API se mantienen por Brightcove. Esta es la razón por la que el énfasis en el documento se centrará en aprender a modificar el código del usuario para recuperar los datos deseados de una de las API.

El siguiente diagrama se centra en las partes clave del código del cliente, que son:

• La función que hace que HTTPRequestal proxy. Para evitar la ambigüedad, la función se llama makeRequest(). Está representado en el lado derecho del diagrama a continuación.

• El código que reúne la información requerida para la petición. Está representado en el rincón superior izquierda del diagrama. Este código suele ser bastante sencillo y emplea conceptos muy conocidos incluso para los programadores principiantes.

• La llamada que ejecuta el citado previamente makeRequest()función. Está representado en la esquina inferior izquierda del diagrama. La llamada pasa una función a makeRequest()como un parámetro. Entonces en makeRequest()Esa función tiene por nombre. Este es un caso de un anónimo definido. llamar de vueltafunción.

Ves las dos secciones en el diagrama etiquetado Actividad asíncrona. Aunque se representa en el diagrama en 2 lugares diferentes, esta es realmente la misma actividad asincrónica, y representa el tiempo desconocido que requiere:

• El cliente para enviar la solicitud al proxy.

• El proxy para solicitar datos de la API.

• La API para construir el conjunto de resultados y devolverlo al proxy.

• El proxy para devolver los datos al usuario.

Tenga en cuenta que las flechas de flujo lógico del cuadro que llama makeRequest()(cuadro inferior izquierdo) parece indicar que el código se ejecuta en dos instantes diferentes, que es exactamente el caso. La llamada a la función se efectúa, pero la función de devolución de llamada no se ejecuta hasta makeRequest()ha hecho su trabajo y se ejecuta la función de devolución de llamada, que devuelve los datos solicitados al código de llamada a la función.

Ejemplo de código paso a paso

En sitio de mirar el código como una sola pieza, será presentado y discutido en secciones. Ciertas secciones se relacionarán con el diagrama de arriba.

Código de jugador estándar

Esta sección de código contiene el código básico. Brightcove Player código de inserción en la página.

• Líneas 11-21: Estándar Brightcove Player código con la adición de una idatributo agregado.

Preparándose para hacer una llamada

Esta sección de código inicializa las variables y se prepara para efectuar la llamada a makeRequest(). En términos generales, para una petición de lectura deberá suministrar la próxima información:

1. La URL del proxy que va a utilizar, por ejemplo (naturalmente, debe ser un proxy bajo su control): /bcls/bcls-proxy/doc-samples-proxy-v2.php

1. La URL precisa para la solicitud real, generalmente construida dinámicamente: /v1/alltime/accounts/ /videos/

1. El método HTTP, por poner un ejemplo GET.

Un ejemplo a continuación:

• Línea 1: código estándar para esperar hasta el momento en que el jugador esté listo para interactuar.

• Líneas dos-4: crea / establece valores para las variables precisas más adelante en el código.

• Líneas 7-12: aguarde el loadstartevento por lo que el mediainfoobjeto se rellena. Asignar variables para sostener los valores necesarios para el Analytics API punto final

• Línea 13: establece el método HTTP para la llamada.

Llamada makeRequest()

Esta sección de código hace que la llamada a makeRequest()función. Tenga en cuenta que se pasan 2 parámetros. El primero es el objeto de opciones que contiene información para el punto y final, y el segundo es la función de devolución de llamada. Recuerde, esta es una llamada asíncrona, por lo que la función de devolución de llamada definida anónimamente no se ejecutará hasta el momento en que la API REST haya devuelto los datos a la makeRequest()función.

• Línea 1: llamar al makeRequest()función, pasando los valores requeridos para la llamada en el optionsobjeto. En un caso así, el objeto contiene lo siguiente:

• Líneas 3-13: la función de devolución de llamada se define como una función anónima (resaltada en amarillo). Recuerde que esta función es un parámetro y NO lleva por nombre aquí, sino más bien más adelante en el código.

• Líneas seis, 8, 10: console.log()declaraciones que muestran:

• La cadena JSON sin procesar que devuelve la llamada API.

• El objeto JSON generado por el JSON.parse()método que hace la conversión de cadena a objeto.

• Las vistas reales cuentan, extraídas del objeto mediante el empleo de simples object.propertynotación.

• Línea 12: llama a la función que muestra el número de vistas en la barra de control.

• La cadena JSON sin procesar que devuelve la llamada API.

• El objeto JSON generado por el JSON.parse()método que hace la conversión de cadena a objeto.

• Las vistas reales cuentan, extraídas del objeto mediante el uso de simples object.propertynotación.

La siguiente captura de pantalla de la consola muestra datos reales console.logdeclaraciones:

Real makeRequest()función

Esta sección del documento examina el código que verdaderamente define el makeRequest()función. El código que define la función está escrito de tal modo que NO precisa ser modificado, sino se utiliza reiteradamente tal como está. Usted puede encontrar casos extremos que esto no es true, pero para la enorme mayoría de los usos, este código NO precisa modificarse.

Sigue una discusión línea por línea del código:

• Líneas 1-6: Definición de funciones y creación de variables. Un punto clave es que un nuevo XMLHttpRequestel objeto es creado

• Líneas ocho, 26: define la función del supervisor de acontecimientos para readyStatecambios.

• Líneas nueve, 23, 25: Use una try-catchen caso de que la solicitud falle en un nivel alto.

• Líneas diez, 11: uso ifdeclaraciones para cerciorarse de que la petición haya finalizado ( readyStatees 4) y se completó con éxito, el estado está en el rango 200. A continuación, se muestra el registro de la consola del readyStatey statusvalores en la definición del controlador de eventos:

• Línea 18: la función de devolución de llamada se ejecuta. Esto pasa los datos devueltos de la API a la función de devolución de llamada como se especifica en el Llamar a makeRequest ()la sección de arriba.

• Line 33: establece el controlador de eventos para el XMLHttpRequest.onreadystatechangeevento.

• Línea 35: Inicia la solicitud al proxy.

• Línea 38: envía la solicitud, que es asincrónica.

Mostrar los datos devueltos

Este código muestra cómo colocar los datos devueltos en la barra de control. Esta función se llama al final de la función de devolución de llamada, que se muestra en Llamar a makeRequest ()la sección de arriba.

• Líneas cinco, 16: define la función.

• Línea 6: crea una variable para spacerelemento en la barra de control.

• Line 7: crea dinámicamente un divelemento.

• Línea 9: Ponga una etiqueta y el valor de las vistas en el recién creado divelemento.

• Línea 11: use JavaScript document.getElementsByClassName()método para conseguir la barra de control spacerelemento.

• Línea 13: estilo el spacerpara mostrar el total de vistas justificadas a la derecha y hacia abajo 10px desde la parte superior de la spacer.

• Línea 15: añada el factor recién creado, poblado y estilo al spacer.

Completar el listado de códigos

El código completo y funcional se encuentra en este repositorio de GitHub:.

Depuración simple

Como puede ver, hay múltiples piezas involucradas al usar las API REST. Esto puede presentar desafíos en el momento en que una aplicación no funciona correctamente. ¿Dónde comienzas a depurar?

En esta sección se hacen un par de sugerencias simples y son un genial lugar para iniciar su aventura de depuración. Las próximas dos secciones le brindan una forma de ver la información más básica que precisa, qué se transmite para realizar la llamada y qué se devuelve.

Comprobando las opciones de llamada

El código del lado del cliente que se analiza en este documento tiene que ver básicamente con suministrar las opciones adecuadas que se utilizarán con el proxy y, a su vez, la API real. Por lo tanto, saber que las opciones son correctas es esencial para el correcto funcionamiento de su código. Una forma fácil de hacer esto es registrar en la consola el optionsobjeto justo antes que pasen a la makeRequestFunción donde se utilizan:

Lo que contiene el objeto de opciones variará según lo que intente hacer, pero siempre y en toda circunstancia habrá algunos conceptos básicos, que son:

• El ID de la cuenta. Esto puede ser una propiedad separada o bien una parte de la URL del punto y final de la API.

• La URL del proxy, que dependerá de dónde almacene su proxy.

• El género de método HTTP, por servirnos de un ejemplo GET, POSTor PATCH.

• La URL de punto y final de API empleada por el proxy para efectuar la petición real desde la API. tienda web ejemplo: /v2/accounts/ /players/playback/v1/accounts/ /videos/ /v1/alltime/accounts/ /videos/

Es posible que se requieran otras propiedades en el objeto de opciones dependiendo de la solicitud de API. Este es un caso de lo que vería en la consola al registrar el objeto de opciones para realizar una solicitud para todos y cada uno de los jugadores en una cuenta específica:

Aquí hay un objeto de opciones registradas un tanto más complejo que se utiliza al actualizar jugadores:

Viendo los datos devueltos

Lo que se devuelve variará según los datos que haya pedido, y si se devuelve un error. Pero con independencia de lo que se devuelva, lo más probable es que desee ver qué datos se devuelven. Una forma fácil de hacer esto es registrar en la consola el raw responsedatos justo después de la llamada a la makeRequestfunción:

Lo que se devolverá tiene posibilidades prácticamente infinitas, pero a continuación hay algunos ejemplos. El primero muestra el comienzo de una respuesta cuando se solicita a todos los jugadores en una cuenta:

Aquí está la respuesta después de actualizar los jugadores, utilizando el PATCHMétodo HTTP:

Aquí hay una vista con un formato más agradable de los datos en la primera respuesta:

Y por último, aquí hay una respuesta muy valiosa de cuando ocurrió un error. En un caso así, se estaba usando una cuenta sin las credenciales adecuadas:

Otros consejos para solventar problemas

Si tiene inconvenientes, aquí hay otras cosas que debe buscar.

• Verifique la referencia de la API para asegurarse de que la solicitud devuelva una contestación. Ciertos solo devuelven una contestación doscientos uno o bien doscientos cuatro sin contenido (en especial, pero no solo, las solicitudes DELETE). Tendrá que ajustar su código para manejar este caso.

• Verifique la sección Red de las Herramientas de desarrollo en su navegador para asegurarse de que ve una llamada triunfante al proxy (ese servidor podría no estar disponible provisionalmente): Sección de red de herramientas para desarrolladores

• Vea el factor anterior: procurar analizar una cadena vacía generará una excepción JSON

• Mire la contestación y asegúrese de que sea una cadena JSON (que empieza con una o una [). Hay algunos casos en los que una petición podría no devolver JSON: un Analytics API llame, por servirnos de un ejemplo, si configura el formatparámetro para csvor xlxs. De nuevo, si realiza ese género de solicitudes, deberá ajustar su código para manejar contestaciones que no sean JSON.

• En la mayoría de los casos, los errores devueltos por las API también están en formato JSON, mas hay algunas salvedades donde el fallo se devuelve como texto sin formato o bien HTML.

Mire la respuesta y asegúrese de que sea una cadena JSON (que empieza con una o una [). Hay algunos casos en los que una petición podría no devolver JSON: un Analytics API llame, por poner un ejemplo, si configura el formatparámetro para csvor xlxs. Nuevamente, si efectúa ese tipo de solicitudes, deberá ajustar su código para manejar respuestas que no sean JSON.

Código proxy

Como se mencionó previamente, el proxy se puede redactar en el idioma de su elección. los Brightcove Los ejemplos de documentación de la API usan un proxy escrito en PHP. Dado que la implementación del proxy es tan dependiente del idioma, el código PHP a continuación no se analizará en detalle en este documento.

La funcionalidad básica proporcionada por un proxy debe incluir:

1. Aceptar la petición del cliente

1. conseguir una token de autenticacióndel OAuth API.

1. Envíe el token de autenticación y la petición de datos (punto y final) a la API deseada.

1. Reciba datos de API.

1. Enviar datos de vuelta al usuario.

Aunque el código completo para el servidor proxy se muestra arriba, también se halla en el repositorio de GitHub:en el objeto phpcarpeta.

ejemplo 2

Este segundo ejemplo es más complejo que el detallado previamente. Este caso de ejemplo muestra los vídeos 10 más populares de una cuenta en una lista de reproducción. Los principales pasos del código son:

1. Solicitud del Analytics API Los videos 10 con la mayor cantidad de vistas en una cuenta. Este paso implica una llamada asíncrona a través de una función de devolución de llamada.

1. De la vuelta Analytics API datos, extraiga solo las ID de vídeo y colóquelas en una matriz. Se escribe una función auxiliar para efectuar la extracción de ID de los datos devueltos.

1. Solicite los objetos de vídeo completos para cada uno de ellos de los videos en la lista de ID de la matriz. Este paso implica recorrer el conjunto y pedir que los objetos de video usen player.catalog.getVideo(). Lógicamente, esto implica múltiples llamadas asincrónicas utilizando el catalog. Se escribe una función ayudar para recuperar los objetos de vídeo basados ​​en ID y poner los objetos en una matriz.

1. Coloque la matriz de objetos de video en la lista de reproducción para un reproductor habilitado para lista de reproducción.

Como ahora está familiarizado con muchos de los conceptos y códigos específicos sobre cómo llamar a las API, solo el código que llama al makeRequest()la función es detallada.

• Línea 2: llamar al makeRequest()función que pasa como razonamientos las opciones precisas para una triunfante llamada a la API REST, así como una función de devolución de llamada definida anónimamente (destacada en amarillo). Esto debería sonarle familiar desde arriba. Fundamental, el makeRequest()función que lleva por nombre ES LA MISMA FUNCIÓN EXACTA UTILIZADA EN EL EJEMPLO ANTERIOR. Puedes hacer lo mismo en tu código. los makeRequest()La función fue escrita para ser vuelta a utilizar con cualquier llamada a un Brightcove API REST.

• Línea 3: crea una variable para contener los datos devueltos analizados por JSON.

• Línea 5: analiza los datos devueltos para transformar si de una cadena a un objeto.

• Línea 7: use la función de ayuda para extraer las ID de vídeo de los datos devueltos. Desafortunadamente, el Analytics API no devuelve los objetos de video completos, con lo que se necesitan ID para acceder a los objetos completos.

• Líneas nueve-12: llame al getVideoDatafunción de ayuda que usa una función de devolución de llamada para poblar el videoObjectsmatriz basada en ID pasados.

• Línea 11: llena la lista de reproducción con la matriz de aparecer el primero en google de video.

Completar el listado de códigos

El ejemplo completo de funcionamiento se halla en este CodePen:.