Fontes de dados

01O que é uma fonte de dados

Uma fonte de dados é um endereço da web salvo uma única vez. Quando um espectador executa um comando que o cita, o bot chama esse endereço, extrai um valor da resposta e o diz no chat. O clima, uma estatística de jogo, o tamanho da fila no seu próprio servidor: se responde em https e devolve JSON ou texto, um comando pode lê-lo.

Por trás desta linha existe um comando personalizado comum. A resposta dele, como digitada no editor:

Está fazendo {urlfetch:weather}°C em Montreal agora.

O marcador nomeia a fonte, não o valor. O lugar de onde o bot tira esse valor fica salvo na própria fonte, na forma de um caminho: um endereço dentro da resposta. A resposta é o prédio, current é o andar, temperature_2m é a porta. Escreva tudo com pontos e você obtém current.temperature_2m. A seção três faz esses cliques por você, e a analogia já pode ir para casa.

02Adicionar uma fonte pelo editor de comandos

Tudo acontece em Comandos, no editor que se encaixa ao lado da sua lista de comandos.

1. Coloque o cursor onde vai o valor

   Abra um comando, clique em Resposta, e deixe o cursor exatamente onde o valor deve aparecer na frase.

2. Abra a paleta

   Abaixo da resposta, ao lado dos marcadores {user} e {args}, há um botão Fonte de dados.

3. Crie uma

   + Nova fonte abre a janela Adicionar uma fonte de dados: “Aponte para qualquer API da web, consulte uma resposta real e clique no valor que quer mostrar no chat.”

4. Dê um nome e cole o endereço

   Nome de exibição é para você. Ele vira automaticamente o Nome da fonte de dados, a palavra que entra no marcador: “Letras minúsculas, números e sublinhados. Usado em {urlfetch:name}.” Depois, Endereço da web, em https, até 512 caracteres.

5. Consulte uma resposta real

   Consultar uma amostra chama sua API de verdade, cerca de uma vez a cada 10 segundos. Se a resposta chegar em um formato que a janela não consegue ler, use o link ou cole uma resposta e cole uma à mão.

6. Clique no valor e adicione a fonte

   A resposta vira uma árvore sob “Clique no valor que quer mostrar no chat.” Clique em temperature_2m e a janela mostra Exibindo current.temperature_2m. Adicionar fonte salva tudo, e a linha da paleta insere {urlfetch:weather} no seu cursor.

Depois que a fonte é criada, o mesmo botão a lista. Cada fonte salva mostra o seu caminho, o que permite distinguir dois feeds de clima de relance, e clicar em uma linha coloca o marcador onde estava o seu cursor.

03Escolher o valor

Esta é a mesma árvore do painel, com as mesmas regras. Só os valores são clicáveis; um ramo como current contém outras coisas, então não pode terminar um caminho. Edite a resposta à esquerda e a árvore acompanha, o que continua sendo a forma mais rápida de testar com a sua própria API antes de salvar qualquer coisa.

04As APIs que exigem uma chave

Algumas APIs exigem uma chave antes de responder. Adicione-a uma vez em Configurações, no painel Chaves de API: um rótulo de até 32 caracteres para reconhecê-la depois, e o segredo em si, de até 512 caracteres, depois Adicionar chave. A indicação do painel diz melhor do que nós: “Chaves de API que suas fontes de dados enviam em cada requisição. Pessoas com acesso compartilhado podem usá-las, mas nunca vê-las.”

O segredo é selado antes de ser gravado e nunca mais é exibido. Você mantém o rótulo e os últimos 4 caracteres, o suficiente para diferenciar duas chaves quando trocar uma delas. Quando uma fonte de dados tem uma chave, o bot a envia em um cabeçalho Authorization: Bearer a cada consulta, e o endereço continua limpo.

Na janela “Adicionar uma fonte de dados”, escolha a chave no campo Chave da API. “Nenhuma chave necessária” é a resposta certa para a maioria das APIs públicas. Se nenhuma chave estiver salva, o campo indica “Ainda não há chaves de API. Adicione uma em Configurações, depois selecione-a aqui.” e um link Abrir chaves de API leva às Configurações.

05Limites e tempos limite

Os números abaixo são os que rodam em produção. O cache é o que você vai encontrar primeiro: uma resposta aceita é reutilizada por 30 segundos, então um comando executado 40 vezes em um minuto chama a sua API só duas vezes.

06O que o chat mostra quando algo falha

Um comando nunca fica mudo por causa de uma fonte de dados. O resto da frase sai mesmo assim e o valor fica vazio, a menos que você tenha escrito uma alternativa depois de uma barra vertical: {urlfetch:weather|indisponível} diz “indisponível” quando a consulta falha. Uma fonte pausada, ausente ou incapaz de produzir um valor funciona do mesmo jeito: o chat e os temporizadores mostram o valor |default do marcador. Sem |default, o chat mostra o marcador bruto, como digitado, e é por isso que um {urlfetch:weather} cru no chat significa “verifique esta fonte de dados”.

Se algo der errado

07O que uma fonte não faz

• O endereço fica fixo ao ser salvo. {args} e {user} permanecem intactos em um endereço da web, então um espectador não consegue direcionar a requisição enviada à sua API.
• As requisições são GET, e os cabeçalhos não são seus para configurar. O único que o bot adiciona é Authorization: Bearer, e só quando a fonte tem uma chave.
• Os marcadores se expandem nas respostas de comandos personalizados, depois das verificações de permissão, de live e de tempo de espera, e nas mensagens de temporizador, a cada disparo. Uma mensagem de temporizador pode citar até 3 fontes de dados diferentes. Os contadores deixam o marcador em paz.
• Uma mensagem de chat reproduzida nunca consulta duas vezes. Se o bot reprocessar um evento antigo, o chat recebe um espaço vazio (ou a sua alternativa) em vez de uma segunda chamada à sua API.
• Endereços privados e locais são descartados nas duas pontas: ao salvar, e de novo no momento da consulta.