Documentação da API HTTP
Através da documentação da API HTTP, você aprenderá como controlar seu placar de vídeo remotamente, seja através de um dispositivo do tipo Stream Deck, uma chamada de comando curl via linha de comando ou através de um software desenvolvido por você.
O que é uma API e uma API HTTP?
Uma API (Application Programming Interface) é um elemento que fornece uma maneira de outros sistemas interagirem com ele. Existem muitos tipos de API, e é por isso que me referi a ela como um “elemento”, e ela pode fornecer muitos tipos de interações: você pode enviar dados para ela, coletar dados desse sistema ou controlá-lo remotamente.
No nosso caso, implementamos uma API HTTP, o que significa que temos uma espécie de servidor web que fica aguardando para receber suas solicitações como se você estivesse solicitando um site, e realiza ações com base no endereço que você digitou.
Portanto, a parte importante aqui é que se trata de um servidor web, então você pode enviar solicitações de API HTTP usando qualquer programa que possa solicitar páginas da web (seu navegador favorito, o aplicativo curl no Linux e OSX, etc.) e, mais importante, você pode fazer isso de qualquer computador, tablet ou celular que esteja na mesma rede, permitindo que você tenha vários LDSscoreboards (ou LDSperimetral) controlados a partir de um ponto centralizado, sua central de controle.
Para chamar esta API HTTP, você deve consultar uma url (URL é o nome dado ao endereço composto pelo protocolo, computador, porta e solicitação) como se fosse uma “página da web”. Mas onde está essa página da web? Estou me confundindo!. A maneira mais fácil é abrir a solicitação que você deseja com seu navegador preferido. O endereço a ser inserido terá a seguinte forma: https://IP_DO_COMPUTADOR:PORTA_CONFIGURADA/SOLICITAÇÃO
Portanto, e em resumo:
- O IP do computador depende da configuração de rede do equipamento. Recomendamos que você o torne fixo para evitar que ele mude e que as solicitações vão para outro computador sem que você perceba.
- A porta é indicada na configuração do terminal, marcada com uma seta vermelha.
- A solicitação dependerá do comando que você deseja dar ao LDSscoreboard (veremos isso em breve).
Através desta documentação da API HTTP, você aprenderá como controlar o placar de vídeo remotamente de maneira simples.
No caso mostrado, o IP do nosso computador é 192.168.1.35 e a porta configurada é 8086.
Descrição da API
O objetivo é ter uma API para todos os comandos de controle do LDSscoreboard, exceto edição de conteúdo. Dessa forma, você pode controlar centralmente todas as telas que desejar, publicar conteúdo promocional ou marcar elementos.
Controle de slides
| Comando | Parâmetros |
|---|---|
| /pcontrol/list_slides | Recupera a lista de slides disponíveis no placar carregado |
| /pcontrol/show_slide/ | Faz com que o slide indicado seja exibido na tela. name_slide = Nome do slide que você deseja mostrar |
Controle de contadores
| Comando | Parâmetros |
|---|---|
| /pcontrol/list_counters | Recupera a lista de contadores definidos no placar ativo |
| /pcontrol/increment_counter/COUNTER_NAME | Incrementa o contador passado como parâmetro. counter_name = Nome do contador a ser operado |
| /pcontrol/decrement_counter/COUNTER_NAME | Decrementa o contador passado como parâmetro. counter_name = Nome do contador a ser operado |
| /pcontrol/set_counter/COUNTER_NAME/VALUE | Atribui um valor a um determinado contador. counter_name = Nome do contador a ser operado, value = valor numérico a ser atribuído |
| /pcontrol/get_counter_value/COUNTER_NAME | Recupera o valor de um contador. counter_name = Nome do contador a ser operado |
Escala de jogadores
| Comando | Parâmetros |
|---|---|
| /roster/get_local_team_name | Verifica o nome da equipe local |
| /roster/get_guest_team_name | Verifica o nome da equipe visitante |
| /roster/get_team_players_count/[local|guest] | Retorna o número de jogadores na equipe da casa ou visitante |
| /roster/get_player_information/PLAYER_INDEX[local|guest] | Retorna as informações do jogador indicado (nome, número, etc.) |
| /roster/increment_player_score/[local|guest] /PLAYER_INDEX | Aumenta a pontuação associada ao jogador com o índice indicado |
| /roster/decrement_player_score/[local|guest] /PLAYER_INDEX | Diminui a pontuação associada ao jogador com o índice indicado |
| /roster/get_player_score/[local|guest] /PLAYER_INDEX | Recupera a pontuação associada ao jogador com o índice indicado |
| /roster/increment_player_fauls/[local|guest] /PLAYER_INDEX | Aumenta as faltas associadas ao jogador com o índice indicado |
| /roster/decrement_player_fauls/[local|guest] /PLAYER_INDEX | Diminui as faltas associadas ao jogador com o índice indicado |
| /roster/get_player_faults/[local|guest] /PLAYER_INDEX | Recupera as faltas associadas ao jogador com o índice indicado |
| /roster/increment_player_cautions/[local|guest] /PLAYER_INDEX | Aumenta as advertências associadas ao jogador com o índice indicado |
| /roster/decrement_player_cautions/[local|guest] /PLAYER_INDEX | Diminui as advertências associadas ao jogador com o índice indicado |
| /roster/get_player_cautions/[local|guest] /PLAYER_INDEX | Recupera as advertências associadas ao jogador com o índice indicado |
Controle de cronômetro
| Comando | Parâmetros |
|---|---|
| /pcontrol/list_timers | Recupera a lista de cronômetros disponíveis no placar ativo |
| /pcontrol/start_timer/TIMER_NAME | Inicia o cronômetro na direção em que foi definido. name_timer = Nome do cronômetro a ser operado |
| /pcontrol/stop_timer/TIMER_NAME | Para o cronômetro. Seu valor não é alterado. name_timer = Nome do cronômetro a ser operado |
| /pcontrol/reset_timer/TIMER_NAME | Redefine o cronômetro para o valor inicial definido em sua configuração. name_timer = Nome do cronômetro a ser operado |
| /pcontrol/get_timer_time/TIMER_NAME | Recupera o valor de um cronômetro. name_timer = Nome do cronômetro a ser operado |
Rótulos dinâmicos e contadores automáticos
| Comando | Parâmetros |
|---|---|
| /gc/list_dynamic_labels | Recupera a lista de rótulos dinâmicos disponíveis no placar carregado |
| /gc/get_dynamic_label/VAR | Recupera o valor atribuído à variável dinâmica. VAR = Identificador da variável a ser consultada |
| /gc/set_dynamic_label/VAR/ARG1 | Altera o valor atribuído à variável dinâmica. VAR = Identificador da variável a ser atribuída, ARG1 = Novo valor a ser atribuído |
| /gc/get_automatic_variable/VAR | Obtém o valor de uma variável automática. Estas variáveis são calculadas ao usar a escalação de jogadores. VAR = Nome da variável. Variáveis existentes: local_team_score (pontuação da equipe local), local_team_fauls (faltas cometidas pela equipe local), local_team_fauls_resetable (faltas cometidas pela equipe local, mas redefiníveis), guest_team_score (pontuação da equipe visitante), guest_team_fauls (faltas da equipe visitante), guest_team_fauls_resettable (faltas da equipe visitante, mas redefiníveis). |
| /gc/reset_automatic_variable/VAR | Redefine o contador para zero para variáveis automáticas que podem ser redefinidas. VAR: Nome da variável redefinível (local_team_fauls_resetable ou guest_team_fauls_resetable) |
Gerenciamento de vetores
| Comando | Parâmetros |
|---|---|
| /pcontrol/list_vectors | Recupera a lista de vetores disponíveis no placar ativo atual |
| /pcontrol/increment_vector_element/VECTOR_ID/INDEX/INCREMENT_VALUE | Incrementa o valor do elemento na posição INDEX do vetor VECTOR_ID. O incremento é determinado por INCREMENT_VALUE |
| /pcontrol/set_vector_element_value/VECTOR_ID/INDEX/VALUE | Define o valor do elemento na posição INDEX do vetor VECTOR_ID. O novo valor é determinado por VALUE |
| /pcontrol/get_vector_element_value/VECTOR_ID/INDEX | Obtém o valor do elemento na posição INDEX do vetor VECTOR_ID. |
| /pcontrol/get_vector_length/VECTOR_ID | Recupera o número de elementos do vetor. Ou seja, o tamanho definido. |
Exemplo de uso da API HTTP do LDSscoreboard
Vamos ver um exemplo para compreender claramente a operação descrita nesta documentação sobre a API HTTP. Suponha que tenhamos definido um marcador que contém um slide chamado “slide1”. Para solicitar ao sistema que abra o slide1, devemos saber o IP do computador e a porta, uma vez que já conhecemos o nome.
Se observarmos a imagem no topo da página, veremos que temos o IP 192.168.1.35 e a porta 8080. Portanto, devemos fazer uma solicitação HTTP (abrir a página) para o endereço http://192.168.1.35:8080/pcontrol/show_slide/slide1
Para fazer isso, podemos abrir um navegador e colocar o endereço na barra de endereços:
Em seguida, se tivermos o LDSscoreboard em execução, deveremos ver o slide chamado slide1 tornar-se ativo.
IMPORTANTE
Se o nome do slide contiver um espaço, por ser um caractere especial, devemos substituí-lo por %20, ou seja, “meu slide” será traduzido como “meu%20slide”.
Ferramentas para realizar chamadas de API HTTP
É claro que você não está restrito a ter que realizar chamadas HTTP a partir de um navegador; fizemos dessa maneira porque é uma ferramenta que você certamente tem à mão e conhece, mas existem muitas outras formas de fazê-lo.
curl
O curl é uma ferramenta de solicitação HTTP de código aberto. Está disponível em Linux, OSX e também nas versões mais recentes do Windows 10. Seu uso é muito simples, como visto na imagem a seguir:
JavaScript
Você pode criar um programa em Javascript, usando jquery, onde uma chamada HTTP é realizada, por exemplo com este código:
timer_identifier="my timer";
$.getJSON(`/pcontrol/start_
.done(function (data) )
.fail(function (err) );
e qualquer linguagem de programação permitirá que você faça esse tipo de chamada.