Aller au contenu
Guide 03

Sources de données

Enregistrez une adresse web une fois, cliquez sur la valeur voulue, et une commande la lit en direct.

Dans ce guide
8 min de lecture

01Ce qu'est une source de données

en brefUne 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.

Une commande, une valeur en direct.

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 brefSix 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.

  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 source de données, 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.

  • Le nom affiché est celui que vous lisez dans les listes. Il devient automatiquement le nom de la source de données en dessous.
  • Le nom de la source de données est le mot placé dans le jeton: lettres minuscules, chiffres et underscores, jusqu’à 32 caractères.
  • Adresse web: https, absolue, jusqu’à 512 caractères. Le bot l’envoie telle quelle, à chaque fois.
  • Récupérer un exemple lance une vraie requête vers votre API. Environ un test toutes les 10 secondes.
  • Cliquer une valeur enregistre son chemin sur la source. «Utiliser toute la réponse» bascule en texte brut.
La fenêtre «Ajouter une source de données» avec une valeur déjà choisie.

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.

  • La puce Source de données se trouve avec les pastilles de jetons sous Réponse, à côté de Compteur.
  • Chaque ligne montre le chemin enregistré sur la source, ou «Texte brut» quand elle affiche toute la réponse.
  • + Nouvelle source ouvre la fenêtre sans perdre la commande en cours d’écriture.
La puce «Source de données» ouverte à côté des pastilles de jetons.
Astuce Une chaîne peut garder 20 sources de données. Au-delà, l'éditeur affiche «Vous avez atteint la limite de 20 sources de données 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 brefUn 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.

Cliquez une valeur
L'arborescence apparaît une fois le JSON analysé.
La grammaire des chemins, celle-là même que l'éditeur vérifie à l'enregistrement.
RègleCe que ça veut dire
Des points entre les étapescurrent.temperature_2m ouvre current, puis en sort temperature_2m.
Les listes utilisent des chiffres nusitems.0.name est la première entrée. Les crochets ne font pas partie de la grammaire.
ProfondeurJusqu’à 8 étapes. Au-delà, l’arborescence refuse la valeur: «Plus profond que 8 niveaux. Choisissez quelque chose de plus proche du sommet.»
Chaque étapeLettres, chiffres, underscore et trait d’union, jusqu’à 64 caractères chacune.
La fin du cheminSe pose sur une valeur: du texte, un nombre, true ou false. S'arrêter sur un objet, une liste ou un champ vide compte comme une source de données cassée, et le chat affiche votre |default, ou le jeton brut s'il n'y en a pas.
Un chemin dans le jetonL'emporte sur celui enregistré sur la source. {urlfetch:weather.current.wind_speed_10m} lit une autre valeur à la même adresse.
Le nomInsensible à la casse. {URLFETCH:Weather} et {urlfetch:weather} désignent la même source.
La valeurNettoyée, rognée, puis coupée à 100 octets avant d’arriver dans le chat.
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 sources de données, deux réponses différentes.

04Les API qui demandent une clé

en brefLes 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, puis Ajouter une clé. L'indication du panneau le dit mieux que nous: «Clés API que vos sources de données envoient avec chaque requête. Les personnes disposant d’un accès partagé peuvent les utiliser, mais jamais les voir.»

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», choisissez la clé dans le champ Clé API. «Aucune clé requise» est la bonne réponse pour la plupart des API publiques. Si aucune clé n’est enregistrée, le champ indique «Aucune clé API pour l’instant. Ajoutez-en une dans Paramètres, puis sélectionnez-la ici.» et un lien Ouvrir les clés API mène aux Paramètres.

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 brefTout 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.

Identique sur toutes les formules.
LimiteLe chiffre
Sources de données par chaîne20.
Sources de données dans une réponse3. L'éditeur refuse d'en enregistrer une quatrième.
Adresse webhttps uniquement, absolue, jusqu’à 512 caractères.
Adresses refuséesLes adresses IP littérales, localhost, et tout ce qui finit par .local ou .internal. Vérifié à l’enregistrement puis à chaque récupération.
Taille de la réponseLe bot lit jusqu'à 1 Mio d'une réponse, mesuré après décompression.
Taille de l'exempleL'éditeur n'affiche une arborescence que pour un exemple de texte lisible d'au plus 128 Ko. Une réponse plus grosse ou illisible donne «L’API a répondu mais sa réponse n’a pas pu être lue automatiquement. Collez-en une ci-dessous.» Un exemple collé de plus de 128 Ko donne «Cet exemple dépasse 128 Ko. Collez-en un plus court.»
Type de contenuapplication/json ou text/*.
DélaisL'API a 2,5 secondes, le service de récupération 3 secondes, et le bot cesse d'attendre à 3,5 secondes.
CacheUne bonne réponse est gardée 30 secondes. Un refus, comme un 404 ou un chemin qui ne trouve rien, est gardé 15 secondes. Une panne n'est pas mise en cache.
Requêtes par chaîne6 par minute, toutes sources de données confondues.
Requêtes par source de données30 par minute.
Requêtes par hôte d'API120 par minute, comptées sur toutes les chaînes pointant vers cet hôte.
RedirectionsJusqu’à 3 sauts, chacun restant en https.
Un hôte qui échoue en sérieCinq échecs de transport d’affilée et cet hôte est mis au repos 60 secondes.
«Récupérer un exemple»Environ un test toutes les 10 secondes : «Trop de tests. Chacun appelle la véritable API. Attendez environ 10 secondes et réessayez.»
Sources de données citées par vos commandes
Requêtes réellement reçues par votre API
2 par minute
Servies par le cache de 30 secondes
10 par minute
Refusées par le plafond de 6 par minute
0 par minute

Le cache existe pour votre quota d'API. Sans lui, un seul raid dépenserait un mois d'appels en une soirée, et toutes les autres chaînes pointant vers le même hôte le sentiraient aussi.

Note Deux secondes de patience, c'est long dans un chat. Si votre API est lente, attendez-vous à un blanc à la place de la valeur pendant un direct chargé: écrivez la phrase pour qu'elle se lise encore sans la valeur, ou ajoutez un repli après une barre verticale.

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

en brefUn échec laisse un blanc ou votre repli. Une source qui ne peut pas répondre affiche votre |default, ou le jeton brut s'il n'y en a pas.

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 reste vide, sauf si vous avez écrit un repli après une barre verticale: {urlfetch:weather|indisponible} dit «indisponible» quand la récupération échoue. Une source en pause, manquante ou incapable de produire une valeur fonctionne de la même façon: le chat et les minuteurs affichent la valeur |default du token. Sans |default, le chat affiche le jeton brut, tel que tapé, et c'est pourquoi un {urlfetch:weather} brut dans le chat veut dire «vérifiez cette source de données».

Ce qui s'est passéCe que le chat affiche
L'API a refusé, elle vous a limité, elle a renvoyé une erreur, elle a mis plus de temps que le bot n'attend, le chemin n'a rien trouvé, ou le message est la relecture d'un ancienRien à la place de la valeur, ou le texte de votre |repli.
La source est en pause, manquante, jamais enregistrée, ou n'a pas pu produire de valeurLe texte de votre |repli. Sans |repli, le jeton affiché tel quel: {urlfetch:weather}.
#your_channel

PrincessBarney!weather

ItsBagelBotIl fait °C à Montréal en ce moment.

Votre clé a été rejetée, ou le point d'accès a écarté la requête. Testez depuis le tableau de bord et vous obtenez le même verdict: «L’API a refusé la requête. Vérifiez l’URL et choisissez la bonne clé dans Clé API si cette API en a besoin.»

Astuce Écrivez un repli pour tout ce qui peut échouer pendant un direct: {urlfetch:weather|indisponible}. Une API lente se lit alors «indisponible» plutôt qu'un trou dans la phrase.

En cas de problème

Ce que vous voyezCe que ça veut direQuoi faire
L’API a refusé la requête. Vérifiez l’URL et choisissez la bonne clé dans Clé API si cette API en a besoin.L'API a écarté le test: clé erronée ou absente, ou mauvaise adresse.Vérifiez l'adresse web. Si l'API exige une clé, ajoutez-la dans Paramètres sous Clés API, choisissez-la dans le champ Clé API et testez à nouveau.
Limite de débit atteinte. Patientez un instant et retestez.Un plafond de requêtes a été atteint.Patientez une minute et retestez.
L'API a renvoyé une erreur. Le chat n'affiche rien, sauf si le token a un |default : {urlfetch:nom|default}.L'API a répondu par une erreur.Vérifiez l'état de l'API, ou ajoutez un repli après une barre verticale.
L'API a expiré. Le chat n'affiche rien, sauf si le token a un |default : {urlfetch:nom|default}.L'API a mis plus de temps que le bot n'attend.Réessayez, et ajoutez un repli après une barre verticale.
Cette source de données n’a pas pu produire de valeur. En attendant, le chat affiche la valeur |default du token s’il en a une, sinon {urlfetch:name} tel que saisi. Vérifiez l’adresse web et la clé API, puis cliquez à nouveau sur Récupérer un exemple.La source est en pause, ou son chemin ou son adresse ne donne aucune valeur.Réactivez la source si elle est en pause. Sinon corrigez l'adresse ou la clé, récupérez un exemple et recliquez la valeur.
Le service de récupération n'a pas répondu. Réessayez dans un instant.Le service qui appelle votre API n'a pas répondu à temps.Patientez un instant et retestez.
L’API a répondu mais sa réponse n’a pas pu être lue automatiquement. Collez-en une ci-dessous.La réponse n'est pas du texte lisible, ou elle dépasse 128 Ko.Cliquez «ou collez une réponse» et collez une vraie réponse à la main.
Ce n'est pas du JSON valide. Corrigez-le et l'arborescence apparaîtra ici.L'exemple collé n'est pas du JSON.Collez de nouveau la réponse, de la première accolade à la dernière.
Cet exemple dépasse 128 Ko. Collez-en un plus court.L'exemple collé est trop gros pour l'arborescence.Collez un extrait plus petit de la réponse.
Trop de tests. Chacun appelle la véritable API. Attendez environ 10 secondes et réessayez.Récupérer un exemple autorise environ un test toutes les 10 secondes.Attendez 10 secondes.
Vous avez atteint la limite de 20 sources de données pour votre chaîne. Supprimez-en une pour faire de la place.Une chaîne garde 20 sources de données.Supprimez une source que vous n'utilisez plus.
Une source de données nommée « name » existe déjà.Une autre source porte déjà ce nom.Choisissez un autre nom, ou modifiez la source existante.
Un message de minuteur peut référencer au maximum 3 valeurs récupérées différentes ({urlfetch:…}).Les messages de minuteur sont limités à 3 sources de données.Citez moins de sources dans le message du minuteur.
Un {urlfetch:name} brut dans le chatLa source est en pause, manquante, ou ne peut pas produire de valeur, et le token n'a pas de |default. Les tokens au-delà du plafond par message restent aussi bruts.Ouvrez la commande, vérifiez que le nom correspond à une source enregistrée, et réactivez-la si elle est en pause. Ajoutez un |default pour que le chat affiche un repli.

07Ce qu’une source ne fera pas

en brefLes 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 se développent dans les réponses de commandes personnalisées, après les vérifications de permission, de direct et de délai, et dans les messages de minuteur, à chaque déclenchement. Un message de minuteur peut citer jusqu'à 3 sources de données différentes. 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 un blanc (ou votre repli) 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.
Note Vérifié le 12 octobre 2026.