Fuentes de datos

01Qué es una fuente de datos

Una fuente de datos es una dirección web que guardas una sola vez. Cuando un espectador ejecuta un comando que la cita, el bot llama a esa dirección, extrae un valor de la respuesta y lo dice en el chat. El tiempo, una estadística de juego, la longitud de la cola en tu propio servidor: si responde por https y devuelve JSON o texto plano, un comando puede leerla.

Detrás de esa línea hay un comando personalizado normal. Su respuesta, tal como se escribe en el editor:

Hace {urlfetch:weather}°C en Montréal en este momento.

La variable nombra la fuente, no el valor. Qué valor extrae el bot se guarda en la propia fuente, como una ruta: una dirección dentro de la respuesta. La respuesta es el edificio, current es el piso y temperature_2m es la puerta. Escríbelo con puntos y obtienes current.temperature_2m. La sección tres hace esos clics por ti, y la analogía ya puede irse a casa.

02Añadir una fuente desde el editor de comandos

Todo se hace en Comandos, en el editor que se acopla junto a tu lista de comandos.

1. Coloca el cursor donde va el valor

   Abre un comando, haz clic en Respuesta y deja el cursor justo donde debe aparecer el valor dentro de la frase.

2. Abre el panel

   Debajo de la respuesta, junto a las píldoras {user} y {args}, hay un chip llamado Fuente de datos.

3. Crea una

   + Nueva fuente de datos abre la ventana Añadir una fuente de datos: «Conéctala a cualquier API web, obtén una respuesta real y haz clic en el valor que quieres mostrar en el chat.»

4. Ponle un nombre y pega la dirección

   Nombre visible es para ti. Se convierte automáticamente en el Nombre de la fuente de datos, la palabra que va dentro de la variable: «Letras minúsculas, dígitos y guiones bajos. Se usa dentro de {urlfetch:name}.» Luego, la Dirección web, en https, de hasta 512 caracteres.

5. Obtén una respuesta real

   Obtener una muestra llama a tu API de verdad, aproximadamente una vez cada 10 segundos. Si la respuesta llega en un formato que la ventana no sabe leer, usa el enlace o pega una respuesta y pega una a mano.

6. Haz clic en el valor y añade la fuente

   La respuesta se convierte en un árbol bajo «Haz clic en el valor que quieres mostrar en el chat.» Haz clic en temperature_2m y la ventana muestra Mostrando current.temperature_2m. Añadir fuente guarda todo, y la fila del panel inserta {urlfetch:weather} en tu cursor.

Una vez creada la fuente, el mismo chip la muestra en la lista. Cada fuente guardada muestra su ruta, así distingues dos fuentes del tiempo de un vistazo, y al hacer clic en una fila se coloca la variable donde estaba tu cursor.

03Elegir el valor

Este es el mismo árbol que muestra el panel, con las mismas reglas. Solo los valores son clicables; una rama como current contiene otras cosas, así que no puede ser el final de una ruta. Edita la respuesta a la izquierda y el árbol la sigue, que es la forma más rápida de ensayar con tu propia API antes de guardar nada.

04Las API que piden una clave

Algunas API exigen una clave antes de responder. Añádela una vez en Ajustes, en el panel Claves de API: una etiqueta de hasta 32 caracteres para reconocerla después, y el secreto en sí, de hasta 512 caracteres, y luego Añadir clave. El propio texto del panel lo dice mejor que nosotros: «Claves de API que tus fuentes de datos envían con cada solicitud. Las personas con acceso compartido pueden usarlas, pero nunca verlas.»

El secreto se cifra antes de guardarse y nunca vuelve a mostrarse. Te quedan la etiqueta y los últimos 4 caracteres, lo justo para distinguir dos claves cuando cambias una. Cuando una fuente de datos tiene una clave, el bot la envía en un encabezado Authorization: Bearer en cada consulta, y la dirección se mantiene limpia.

En la ventana «Añadir una fuente de datos», elige la clave en el campo Clave de API. «No necesita clave» es la respuesta correcta para la mayoría de las API públicas. Si todavía no tienes ninguna clave guardada, el campo dice «Aún no hay claves de API. Añade una en Ajustes y luego selecciónala aquí.» y un enlace Abrir claves de API te lleva a Ajustes.

05Límites y tiempos

Las cifras de abajo son las que están activas en producción. La caché es con lo primero que te encontrarás: una respuesta aceptada se reutiliza durante 30 segundos, así que un comando que se ejecuta 40 veces en un minuto solo llama a tu API dos veces.

06Lo que muestra el chat cuando falla

Un comando nunca se queda mudo por culpa de una fuente de datos. El resto de la frase se envía igualmente y el valor queda vacío, salvo que hayas escrito un respaldo después de una barra vertical: {urlfetch:weather|no disponible} dice «no disponible» cuando la consulta falla. Una fuente en pausa, inexistente o incapaz de producir un valor funciona igual: el chat y los temporizadores muestran el valor |default de la variable. Sin |default, el chat muestra la variable tal como se escribió, y por eso un {urlfetch:weather} sin procesar en el chat significa «revisa esta fuente de datos».

Si algo sale mal

07Lo que una fuente no hará

• La dirección se fija al guardarla. {args} y {user} no se tocan dentro de una dirección web, así que un espectador no puede dirigir la petición hacia tu API.
• Las peticiones son GET, y los encabezados no los configuras tú. El único que añade el bot es Authorization: Bearer, y solo cuando la fuente tiene una clave.
• Las variables se expanden en las respuestas de comandos personalizados, después de pasar las comprobaciones de permisos, de directo y de enfriamiento, y en los mensajes de temporizador, cada vez que se dispara. Un mensaje de temporizador puede citar hasta 3 fuentes de datos distintas. Los contadores no tocan la variable.
• Un mensaje de chat repetido nunca hace una segunda consulta. Si el bot vuelve a leer un evento antiguo, el chat recibe un hueco (o tu respaldo) en lugar de una segunda llamada a tu API.
• Las direcciones privadas y locales se rechazan en ambos extremos: al guardar, y de nuevo al consultar.