Sources de données

01Ce qu'est une source de données

en bref Une commande, une adresse web, une valeur que le bot annonce.

Une source de données est une adresse web enregistrée une seule fois. Quand un spectateur lance une commande qui la cite, le bot appelle cette adresse, extrait une valeur de la réponse et la dit dans le chat. La météo, une statistique de jeu, la longueur de la file sur votre propre serveur: si ça répond en https et renvoie du JSON ou du texte, une commande peut le lire.

Derrière cette ligne se cache une commande personnalisée ordinaire. Sa réponse, telle qu'elle est tapée dans l'éditeur:

Il fait {urlfetch:weather}°C à Montréal en ce moment.

Le jeton nomme la source, pas la valeur. L'endroit où le bot va chercher cette valeur est enregistré sur la source elle-même, sous forme de chemin: une adresse à l'intérieur de la réponse. La réponse est l'immeuble, current est l'étage, temperature_2m est la porte. Écrivez le tout avec des points et vous obtenez current.temperature_2m. La section trois fait ces clics pour vous, et l'analogie peut rentrer chez elle.

Note Les sources de données sont gratuites sur toutes les formules. Une chaîne premium passe par une voie interne différente, et chaque limite de cette page est la même pour les deux.

02Ajouter une source depuis l'éditeur de commande

en bref Six clics, sans quitter la commande en cours.

Tout se passe dans Commandes, dans l'éditeur qui s'amarre à côté de votre liste de commandes.

1. Placez le curseur là où va la valeur

   Ouvrez une commande, cliquez dans Réponse, et laissez le curseur à l'endroit exact où la valeur doit apparaître dans la phrase.

2. Ouvrez la palette

   Sous la réponse, à côté des pastilles {user} et {args}, se trouve une puce Source de données. Son infobulle indique «Insère une valeur récupérée depuis une définition d'API enregistrée».

3. Créez-en une

   + Nouvelle source ouvre la fenêtre Ajouter une source de données: «Indiquez une API web, récupérez une vraie réponse, puis cliquez sur la valeur à afficher dans le chat.»

4. Nommez-la et collez l'adresse

   Nom affiché est pour vous. Il devient automatiquement le Nom de la définition, le mot qui entre dans le jeton: «Lettres minuscules, chiffres et underscores. Utilisé dans {urlfetch:name}.» Puis Adresse web, en https, jusqu'à 512 caractères.

5. Récupérez une vraie réponse

   Récupérer un exemple appelle votre API pour de vrai, environ une fois toutes les 10 secondes. Si la réponse arrive dans une forme que la fenêtre ne sait pas lire, prenez le lien ou collez une réponse et collez-en une à la main.

6. Cliquez la valeur, puis ajoutez la source

   La réponse devient une arborescence sous «Cliquez sur la valeur à afficher dans le chat.» Cliquez temperature_2m et la fenêtre affiche Affiche current.temperature_2m. Ajouter la source enregistre le tout, et la ligne de la palette insère {urlfetch:weather} à votre curseur.

Une fois la source créée, la même puce la répertorie. Chaque source enregistrée affiche son chemin, ce qui permet de distinguer deux flux météo d'un coup d'œil, et cliquer une ligne dépose le jeton là où était votre curseur.

Astuce Une chaîne peut garder 20 définitions. Au-delà, l'éditeur affiche «Vous avez atteint la limite de 20 définitions pour votre chaîne. Supprimez-en une pour faire de la place.» La suppression demande deux clics, et le serveur nomme les commandes qui citent la source avant de la lâcher: «Ces commandes la citent. Elles perdront ces données si vous supprimez :».

03Choisir la valeur

en bref Un chemin, ce sont des points entre les étapes. Cliquez une valeur et regardez le jeton s’écrire.

Voici la même arborescence que dans le tableau de bord, avec les mêmes règles. Seules les valeurs sont cliquables; une branche comme current contient d'autres choses, elle ne peut donc pas terminer un chemin. Modifiez la réponse à gauche et l'arborescence suit, ce qui reste la façon la plus rapide de répéter avec votre propre API avant d'enregistrer quoi que ce soit.

Astuce Une seule adresse enregistrée peut nourrir plusieurs commandes. Enregistrez {urlfetch:weather} sur current.temperature_2m pour !weather, puis écrivez {urlfetch:weather.current.wind_speed_10m} dans !wind. Même source, même budget de 20 définitions, deux réponses différentes.

04Les API qui demandent une clé

en bref Les clés vivent sur votre compte, scellées, et voyagent dans un en-tête Authorization.

Certaines API exigent une clé avant de répondre. Ajoutez-la une fois dans Paramètres, sur le panneau Clés API: un libellé jusqu'à 32 caractères pour la reconnaître plus tard, et le secret lui-même, jusqu'à 512 caractères. L'indication du panneau le dit mieux que nous: «Secrets au niveau du compte pour les sources de données. Les délégués peuvent les utiliser, jamais les lire.»

Le secret est scellé avant d'être écrit et il n'est plus jamais réaffiché. Il vous reste le libellé et les 4 derniers caractères, ce qui suffit à distinguer deux clés quand vous en changez une. Quand une source de données porte une clé, le bot l'envoie dans un en-tête Authorization: Bearer à chaque récupération, et l'adresse reste propre.

Dans la fenêtre «Ajouter une source de données», le champ Clé API n'apparaît qu'une fois qu'au moins une clé est enregistrée. Avant cela, il indique «Aucune clé requise», ce qui est aussi la bonne réponse pour la plupart des API publiques.

Attention Gardez la clé hors de l'Adresse web et hors de la réponse de la commande. Une adresse est stockée en texte et toute personne ayant accès au tableau de bord peut la lire, et une réponse part dans le chat où tout le monde la voit. Si votre API n'accepte la clé qu'en paramètre d'URL, considérez cette clé comme publique et changez-la régulièrement.

05Limites et délais

en bref Tout est plafonné, et le cache fait le gros du travail.

Les chiffres ci-dessous sont ceux qui tournent en production. Le cache est celui que vous rencontrerez en premier: une réponse acceptée est réutilisée pendant 30 secondes, donc une commande lancée 40 fois en une minute n'appelle votre API que deux fois.

Note Deux secondes de patience, c'est long dans un chat. Si votre API est lente, attendez-vous à [source timed out] pendant un direct chargé et écrivez la phrase pour qu'elle se lise encore sans la valeur.

06Ce que le chat affiche en cas d’échec

en bref Quatre replis, tous courts, tous en anglais où que soit votre chat.

Une commande ne devient jamais muette à cause d'une source de données. Le reste de la phrase part quand même et la valeur est remplacée par l'une de ces quatre chaînes, ce qui vous permet de lire le chat et de savoir ce qui a cassé.

Note Ces quatre chaînes ne sont pas traduites. Une chaîne francophone voit elle aussi [source unavailable], ce qui les garde faciles à rechercher et garde cette page honnête sur ce que vos spectateurs liront.

07Ce qu’une source ne fera pas

en bref Les bords, en un écran, avant de concevoir une commande autour.

• L'adresse est figée à l'enregistrement. {args} et {user} restent intacts dans une adresse web, donc un spectateur ne peut pas diriger la requête envoyée à votre API.
• Les requêtes sont en GET, et les en-têtes ne sont pas les vôtres à régler. Le seul que le bot ajoute est Authorization: Bearer, et seulement quand la source porte une clé.
• Les jetons ne se développent que dans les réponses de commandes personnalisées, après les vérifications de permission, de direct et de délai. Un minuteur publie son texte brut, et les compteurs laissent le jeton tranquille.
• Un message de chat rejoué ne récupère jamais deux fois. Si le bot relit un évènement ancien, le chat reçoit [source unavailable] plutôt qu'un second appel à votre API.
• Les adresses privées et locales sont écartées aux deux bouts: à l'enregistrement, puis de nouveau au moment de la récupération.

Astuce Citez deux fois la même source dans une réponse et le bot ne récupère qu'une fois. Écrivez {urlfetch:weather} dans la phrase et {urlfetch:weather.current.wind_speed_10m} juste après: deux valeurs, une requête, une ligne de votre quota.