Incrustar API

Este tema le ayudará a decidir cuándo y cómo utilizar las API de incrustar. La decisión de elegir entre usar las API de configuración del jugador frente a las API de incrustación es importante y el contenido de este documento le guiará en estas decisiones.

¿Por qué usar las API de inserción?

Las API de incrustación le permiten crear varias instancias de un reproductor en particular. Una buena manera de pensar en esta relación jugador/instancia es como una relación padre/hijo. El jugador individual es el padre, y los jugadores creados con las API de incrustación son hijos del jugador principal. El reproductor principal tiene la mayor parte de las propiedades que desea que tenga su reproductor y, a continuación, puede usar las API de incrustación para personalizar subconjuntos de propiedades en diferentes jugadores secundarios. Por ejemplo, puede cargar diferentes medios o usar diferentes plugins y estilos con diferentes reproductores secundarios.

Los siguientes diagramas ayudan a aclarar la funcionalidad. Debajo del padre se muestra a la izquierda, y dos niños jugadores a la derecha. Observe que:

El cartel es heredado por ambos niños
La forma del botón de reproducción es heredada por el niño superior, mientras que se anula en el secundario inferior
El elemento secundario superior agrega una propiedad, en este caso una superposición, que el padre no tiene

Otra característica poderosa de esta relación padre-hijo es que la herencia está en curso. El siguiente diagrama muestra un nuevo póster asignado al padre y ambos hijos heredarán ese cambio de configuración.

Cuándo NO utilizar las API de incrustación

Si bien hay algunas buenas razones para usar las API de inserción si tu caso de uso lo necesita, también hay algunas buenas razones para seguir con jugadores regulares. Aquí hay algunos:

Los reproductores secundarios no se pueden editar con Video Cloud Studio. Solo puede editar jugadores secundarios a través de la API de administración de jugadores. Puede editar el reproductor principal de un reproductor secundario en Video Cloud Studio, sin embargo, un cambio realizado en el reproductor principal afecta a todos los reproductores secundarios.
La publicación de un reproductor principal puede tardar mucho tiempo si tiene muchos jugadores secundarios asociados a ese reproductor principal. Cada jugador infantil se publica por separado, y si tiene más de 30 jugadores infantiles, puede esperar algunos retrasos en la publicación de su reproductor infantil. Este sería exactamente el mismo caso que publicar 30 jugadores regulares al mismo tiempo.

Dadas las razones anteriores, puede tener sentido comenzar con el uso de jugadores regulares, y luego probar incrustaciones cuando vea la necesidad de jugadores infantiles.

vídeo etiqueta de data-embed

Hay diferencias noacionales en los jugadores padres e hijos. El código estándar del reproductor incrustado en la página aparece en este formato:

    <video-js
      data-account="1507807800001"
      data-player="HiAdwRZ7kK"
      data-embed="default"
      controls=""
      data-application-id=""
      class="vjs-fluid"></video-js>

El atributo determina si el jugador es padre o hijo.data-embed Si el valor es default, el jugador es un padre. Si el jugador es un hijo, el data-embed atributo contendrá el ID del jugador principal. A continuación se muestra un ejemplo de ello:

    <video-js
      data-account="1507807800001"
      data-player="HiAdwRZ7kK"
      data-embed="NURK56ZSV"
      data-application-id=""
      class="video-js" controls></video-js>

Tenga en cuenta que el data-player, es decir, el ID del jugador, es el mismo, pero el data-embed ha cambiado de default al ID del jugador secundario.

URL de jugador infantil

¿Cómo se diferencia entre el jugador padre y el jugador infantil? Las URL serán diferentes. Por ejemplo, la URL de un jugador principal es:

    //players.brightcove.net/1507807800001/HiAdwRZ7kK_default/index.min.js

Después de usar las API de incrustación para crear un reproductor secundario, el ID del jugador secundario se agregó a la URL del padre, como se muestra a continuación:

    //players.brightcove.net/1507807800001/HiAdwRZ7kK_NURK56ZSV/index.min.js

Caso de uso padre/hijo

Supongamos que usa varios reproductores de vídeo. A menudo, las características comunes de los jugadores son casi las mismas, pero en algunos casos se desea ajustar el jugador para casos especiales. Puede crear varios jugadores utilizando las API de configuración del reproductor con POST y PATCH los métodos, pero esto podría ocasionar importantes problemas de mantenimiento. Por ejemplo, digamos que querías cambiar el póster para todos los jugadores. Esto significaría usar PATCH en todos los diferentes jugadores. Mientras que si crearas jugadores infantiles, solo lo harías con PATCH el jugador padre, y todos los jugadores secundarios tendrían automáticamente el nuevo póster.

Proceso de creación

Si ha hecho el paso a paso: Administración de reproductores ha visto el proceso de utilizar instrucciones curl para comunicar métodos HTTP a la API de administración de Player. El mismo enfoque se usará aquí.

Para crear un reproductor, es muy probable que haya utilizado algunos métodos HTTP con las API de configuración del reproductor, como:

Crea el reproductor usando un POST to https://players.api.brightcove.com/v2/accounts/$ACCOUNT_ID/players
Actualice el reproductor con un PATCH a https://players.api.brightcove.com/v2/accounts/$ACCOUNT_ID/players/$PLAYER_ID/configuration
Publicar el reproductor actualizado con una POST a https://players.api.brightcove.com/v2/accounts/$ACCOUNT_ID/players/$PLAYER_ID/publish

Se usará un enfoque similar para los jugadores secundarios que utilicen las API de inserción. En un nivel muy alto:

Crear un jugador infantil utilizando un POST a https://players.api.brightcove.com/v2/accounts/$ACCOUNT_ID/players/$PLAYER_ID/incrustaciones. Nota: Los jugadores secundarios creados con las API de incrustación se publican automáticamente en la creación, por lo que no hay necesidad de publicar en la creación de un jugador secundario, solo en la actualización del jugador secundario.
Actualice el reproductor secundario mediante PATCH a https://players.api.brightcove.com/v2/accounts/$ACCOUNT_ID/players/$PLAYER_ID/embeds/$embed_id/configuration
Publicar el reproductor secundario mediante POST a https://players.api.brightcove.com/v2/accounts/$ACCOUNT_ID/players/$PLAYER_ID/embeds/$embed_id/Publish

El siguiente contenido describe el proceso en detalle.

Crear jugador infantil

Para crear un reproductor secundario, utilice un POST método HTTP, como se muestra aquí:

    curl /
    --header "Content-Type: application/json" /
    --user $EMAIL /
    --request POST /
    --data '{
    "media": {
    "sources": [
      {
        "src":"http://solutions.brightcove.com/bcls/assets/videos/BirdsOfAFeather.mp4",
        "type":"video/mp4"
      }
    ],
    "poster": {
      "highres":"http://solutions.brightcove.com/bcls/assets/images/BirdsOfAFeather.jpg"
    }
    }
      }' /
    https://players.api.brightcove.com/v2/accounts/$ACCOUNT_ID/players/$PLAYER_ID/embeds

Una respuesta de ejemplo a la creación del jugador secundario es la siguiente:

    {
        "id": "be864624-8d85-4dfc-8fe6-4e9dd4c70417",
        "url": "http://players.brightcove.net/1507807800001/668c5107-a80c-4940-8c17-279c01ce101c_be864624-8d85-4dfc-8fe6-4e9dd4c70417/index.html",
        "embed_code": "<iframe src='//players.brightcove.net/1507807800001/668c5107-a80c-4940-8c17-279c01ce101c_be864624-8d85-4dfc-8fe6-4e9dd4c70417/index.html' allowfullscreen webkitallowfullscreen mozallowfullscreen></iframe>",
        "embed_in_page": "http://players.brightcove.net/1507807800001/668c5107-a80c-4940-8c17-279c01ce101c_be864624-8d85-4dfc-8fe6-4e9dd4c70417/in_page.embed",
        "preview_url": "http://preview-players.brightcove.net/1507807800001/668c5107-a80c-4940-8c17-279c01ce101c/be864624-8d85-4dfc-8fe6-4e9dd4c70417/index.html",
        "preview_embed_code": "<iframe src='//preview-players.brightcove.net/1507807800001/668c5107-a80c-4940-8c17-279c01ce101c/be864624-8d85-4dfc-8fe6-4e9dd4c70417/index.html' allowfullscreen webkitallowfullscreen mozallowfullscreen></iframe>"
    }

Nota: El jugador infantil se publica en la creación, por lo que no hay necesidad de publicar el jugador secundario después de la creación. Todavía debe publicar jugador secundario si se altera con un PATCH método. En este punto, la información de vista previa no es útil, ya que puede usar el reproductor secundario publicado inmediatamente después de su creación.

Ahora puede utilizar la url propiedad del jugador secundario para ver los resultados. En el ejemplo siguiente, el jugador secundario se agregó al jugador padre creado en el paso a paso: Gestión de Jugadores. Usted ve el nuevo póster y video, pero el plugin de superposición del reproductor padre todavía está presente.

Jugador infantil con superposición de padres

Actualizar jugador infantil

Para actualizar el reproductor secundario, utilice un PATCH método HTTP. La siguiente instrucción curl actualiza la poster propiedad. Se supone que ha establecido la variable de $EMBED_ID entorno apropiadamente:

    curl
    --header "Content-Type: application/json"
    --user $EMAIL
    --request PATCH
    --data '{
    "media": {
    "poster": {
      "highres":"http://solutions.brightcove.com/bcls/assets/images/Water-Splashing.jpg"
    }
    }
      }'
    https://players.api.brightcove.com/v2/accounts/$ACCOUNT_ID/players/$PLAYER_ID/embeds/$EMBED_ID/configuration

La respuesta proporciona información de vista previa tanto para un preview_url y preview_embed_code código:

    {
        "preview_url": "http://preview-players.brightcove.net/1507807800001/668c5107-a80c-4940-8c17-279c01ce101c/be864624-8d85-4dfc-8fe6-4e9dd4c70417/index.html",
        "preview_embed_code": "<iframe src='//preview-players.brightcove.net/1507807800001/668c5107-a80c-4940-8c17-279c01ce101c/be864624-8d85-4dfc-8fe6-4e9dd4c70417/index.html' allowfullscreen webkitallowfullscreen mozallowfullscreen></iframe>"
    }

Publicar reproductor secundario

Una vez que el jugador infantil sea alterado, tendrá que publicarlo. Asegúrese de que la variable de $EMBED_ID entorno está configurada y luego puede publicar el reproductor secundario recién alterado:

    curl
    --header "Content-Type: application/json"
    --user $EMAIL
    --request POST
    https://players.api.brightcove.com/v2/accounts/$ACCOUNT_ID/players/$PLAYER_ID/embeds/$EMBED_ID/publish

La respuesta proporciona la información vital necesaria para usar el reproductor secundario, de manera muy similar a la publicación de un reproductor:

    {
        "id": "be864624-8d85-4dfc-8fe6-4e9dd4c70417",
        "url": "http://players.brightcove.net/1507807800001/668c5107-a80c-4940-8c17-279c01ce101c_be864624-8d85-4dfc-8fe6-4e9dd4c70417/index.html",
        "embed_code": "<iframe src='//players.brightcove.net/1507807800001/668c5107-a80c-4940-8c17-279c01ce101c_be864624-8d85-4dfc-8fe6-4e9dd4c70417/index.html' allowfullscreen webkitallowfullscreen mozallowfullscreen></iframe>",
        "embed_in_page": "http://players.brightcove.net/1507807800001/668c5107-a80c-4940-8c17-279c01ce101c_be864624-8d85-4dfc-8fe6-4e9dd4c70417/in_page.embed"
    }

Mostrar información de hijo

Puede utilizar el GET método HTTP para recuperar la información sobre un reproductor secundario. Un ejemplo de instrucción curl es:

    curl
      --header "Content-Type: application/json"
      --user $EMAIL
      --request GET
      https://players.api.brightcove.com/v2/accounts/$ACCOUNT_ID/players/$PLAYER_ID/embeds

Se devuelve una cantidad bastante grande de datos JSON.

Eliminar jugadores secundarios

También puede eliminar un jugador secundario mediante el DELETE método. Aquí hay un ejemplo de instrucción curl para eliminar un jugador secundario:

    curl
    --header "Content-Type: application/json"
    --user $EMAIL
    --request DELETE
    https://players.api.brightcove.com/v2/accounts/$ACCOUNT_ID/players/$PLAYER_ID/embeds/$EMBED_ID

Por supuesto, esto afectará solo al jugador niño y no al jugador padre.