Java
Instale o SDK Java da Piloterr e faça sua primeira chamada à API.
O SDK Java oficial da Piloterr, com um método tipado por endpoint e um request() genérico para o resto.
Requisitos
- Java 17+
Instalação
O SDK Java não está no Maven Central. Compile-o a partir do código-fonte para instalá-lo no seu repositório Maven local e depois adicione-o ao seu projeto.
git clone https://github.com/piloterr/piloterr-java.git
cd piloterr-java
mvn -q install -DskipTests<dependency>
<groupId>com.piloterr</groupId>
<artifactId>piloterr</artifactId>
<version>0.1.0</version>
</dependency>implementation("com.piloterr:piloterr:0.1.0")Obtenha sua chave de API
Copie sua chave de API no painel da Piloterr e coloque-a na variável de ambiente PILOTERR_API_KEY, que o SDK lê por padrão. Não a inclua no controle de versão.
Início rápido
import com.piloterr.ApiResponse;
import com.piloterr.PiloterrClient;
import com.piloterr.params.AmazonProductParams;
PiloterrClient client = PiloterrClient.fromEnv();
ApiResponse response = client.amazonProduct(AmazonProductParams.builder().query("B09DFCB66S").build());
System.out.println(response.json().toPrettyString());Jobs assíncronos
Qualquer chamada aceita is_async, útil além do limite de 60 segundos do servidor. A resposta é então um job_id, e o SDK pode aguardar o fim do job.
ApiResponse submitted = client.amazonProduct(AmazonProductParams.builder().query("B09DFCB66S").isAsync(true).build());
ApiResponse job = client.waitForJob(
submitted.json().get("job_id").asText(),
Duration.ofSeconds(3),
Duration.ofHours(12),
progress -> System.out.println(progress.path("status").asText() + " " + progress.path("progress").asInt()));Erros
Uma resposta fora de 2xx gera um erro de API com status e mensagem. Veja os códigos de status para a lista completa.
try {
client.amazonProduct(AmazonProductParams.builder().query("B09DFCB66S").build());
} catch (PiloterrApiException e) {
System.err.println(e.status() + ": " + e.getMessage());
}Novas tentativas
As requisições são repetidas até 3 vezes após um erro de rede, um 408, 500, 502, 503 ou 504, ou um limite de taxa do plano. Erros de cota por chave e timeouts do cliente não são repetidos. A espera começa em 1 segundo e cresce 1,5× a cada tentativa, e um cabeçalho Retry-After tem prioridade.
PiloterrClient client = PiloterrClient.builder().maxRetries(5).retryDelay(Duration.ofMillis(500)).build();
client.amazonProduct(AmazonProductParams.builder().query("B09DFCB66S").build(), RequestOptions.builder().maxRetries(0).build()); // one request without retriesRequisições em lote
Execute muitas chamadas de uma vez, 10 por padrão. Uma falha não interrompe as outras.
List<String> inputs = List.of("B09DFCB66S", "B0BSHF7WHW", "B08N5WRWNW");
List<BatchResult<ApiResponse>> results = client.batch(inputs, 5, value ->
client.amazonProduct(AmazonProductParams.builder().query(value).build()));
for (BatchResult<ApiResponse> result : results) {
if (result.ok()) {
System.out.println(result.value().json());
} else {
System.err.println(inputs.get(result.index()) + ": " + result.error().getMessage());
}
}Qualquer endpoint
request() alcança qualquer caminho, inclusive endpoints lançados depois da sua versão do SDK.
ApiResponse response = client.request("GET", "/v1/usage", Map.of());Erros comuns
- Colocar a chave de API no código front-end. Qualquer pessoa poderia lê-la. Chame a API a partir do seu servidor.
- Tratar todo
401como chave incorreta. Um401também pode ser um limite de taxa: leia a mensagem. O SDK repete automaticamente os limites do plano. - Repetir um
402. Não há mais créditos nem cota, então uma nova tentativa não pode funcionar. Veja Créditos. - Esperar requisições longas. Acima de 60 segundos, use o modo assíncrono como mostrado acima em vez de aumentar o timeout. Veja Timeout.
Links
- Pacote:
piloterr-java - Código-fonte: github.com/piloterr/piloterr-java
- Referência da API