Enviar traces pela API

A API v1 foi feita para o app Android: é por ela que o app entra, envia os traces e lê os relatórios. Não há chave de API à parte: um script entra como o app, com usuário, senha e o código da segunda etapa, e usa o token que o login devolve. Esta página mostra o caminho do envio com curl; o contrato completo, com todos os campos e códigos de erro, está em API v1.

Antes de começar

• Uma conta com a verificação em duas etapas pelo app autenticador e os termos aceitos no navegador. Antes do aceite, as chamadas respondem 403 termos_pendentes.
• O login pela API conta no limite de sessões simultâneas da conta, junto com o navegador e o app. Com o limite de uma sessão, entrar pelo script encerra a sessão mais antiga, como a do navegador.
• curl, jq e bash num Linux. Os exemplos usam o stat e o dd do GNU.

Entrar e pegar o token

1. Envie usuário e senha para receber o desafio da segunda etapa:

   BASE=https://app.waitscope.com/api/v1
   DESAFIO=$(curl -sS "$BASE/sessao" \
     -H 'Content-Type: application/json' \
     -d '{"username": "zz-exemplo", "password": "<senha>", "method": "app", "device_name": "script"}' |
     jq -r .desafio)

2. Troque o desafio e o código de 6 dígitos do app autenticador pelo token:

   TOKEN=$(curl -sS "$BASE/sessao/codigo" \
     -H 'Content-Type: application/json' \
     -d "{\"desafio\": \"$DESAFIO\", \"codigo\": \"123456\"}" |
     jq -r .token)

Resultado: TOKEN tem 43 caracteres. Ele vale até 90 dias, cai com 30 dias sem uso e aparece em Minha conta como App Android · script. O desafio vale 10 minutos.

Para encerrar a sessão no fim:

curl -sS -X DELETE "$BASE/sessao" -H "Authorization: Bearer $TOKEN"

Enviar o arquivo

1. Abra o envio com o nome e o tamanho de cada arquivo. Com "juntar": true, os arquivos viram uma análise só (analisar juntos):

   ARQ=exemplo-10046.trc
   TAM=$(stat -c %s "$ARQ")
   ENVIO=$(curl -sS "$BASE/envios" \
     -H "Authorization: Bearer $TOKEN" \
     -H 'Content-Type: application/json' \
     -d "{\"juntar\": false, \"arquivos\": [{\"nome\": \"$ARQ\", \"tamanho\": $TAM}]}" |
     jq -r .id)

   Resultado: a resposta 201 traz o id do envio, cada arquivo com a posição n e o que já chegou em recebido, e pedaco_max, de 8388608 bytes (8 MiB).

2. Mande o arquivo em pedaços de até 8 MiB, em ordem, cada um com o Content-Range do trecho e o tamanho total:

   PEDACO=8388608
   INI=0
   while [ "$INI" -lt "$TAM" ]; do
     FIM=$(( INI + PEDACO - 1 ))
     [ "$FIM" -ge "$TAM" ] && FIM=$(( TAM - 1 ))
     dd if="$ARQ" bs="$PEDACO" skip=$(( INI / PEDACO )) count=1 status=none |
       curl -fsS -X PUT "$BASE/envios/$ENVIO/arquivos/0" \
         -H "Authorization: Bearer $TOKEN" \
         -H 'Content-Type: application/octet-stream' \
         -H "Content-Range: bytes $INI-$FIM/$TAM" \
         --data-binary @- || break
     INI=$(( FIM + 1 ))
   done

   Resultado: cada pedaço aceito responde 200 com o novo total em recebido.

3. Conclua o envio e guarde o id da análise:

   ANALISE=$(curl -sS -X POST "$BASE/envios/$ENVIO/concluir" \
     -H "Authorization: Bearer $TOKEN" |
     jq -r '.analises[0].id // .repetidas[0]')

   Resultado: a resposta 201 traz em analises as análises novas e em repetidas os ids das que já existiam com o mesmo conteúdo (envio repetido).

Se um pedaço falhar, o laço para. Pergunte ao servidor quanto já chegou e rode de novo só o while, que continua desse ponto:

INI=$(curl -sS "$BASE/envios/$ENVIO" -H "Authorization: Bearer $TOKEN" | jq '.arquivos[0].recebido')

Acompanhar a análise

1. Pergunte a situação a cada alguns segundos:

   curl -sS "$BASE/analises/$ANALISE" -H "Authorization: Bearer $TOKEN" | jq '{status, progress, error}'

   Resultado: status passa de queued a running, com o andamento em progress, e termina em done ou em error, com o motivo em error.

2. Com done, baixe o relatório:

   curl -sS -o relatorio.html "$BASE/analises/$ANALISE/relatorio.html" -H "Authorization: Bearer $TOKEN"

relatorio.html é o mesmo arquivo do Baixar HTML da console. A rota /relatorio, sem extensão, devolve o relatório em JSON, seção por seção. Antes do fim da análise, ou se ela terminou com erro, as duas respondem 409 conflito.

Cancelar e retomar

• DELETE $BASE/envios/$ENVIO cancela o envio e apaga o que chegou.
• O envio pertence ao token que o criou e some depois de 24 horas sem pedaço novo, ou quando a sessão do token termina.
• Repetir o concluir devolve o mesmo resultado, sem criar análise de novo: pode repetir depois de perder a resposta.

Problemas comuns

Próximos passos

• Todos os campos, rotas e códigos de erro: API v1.
• Os limites de cada conta: limites e envio repetido.
• O mesmo envio com tela: enviar pelo navegador.