Java

El SDK oficial de Java de Piloterr, con un método tipado por endpoint y un request() genérico para lo demás.

RequisitosCopiar enlace del ancla

• Java 17+

InstalaciónCopiar enlace del ancla

El SDK de Java no está en Maven Central. Compílalo desde el código fuente para instalarlo en tu repositorio Maven local y luego añádelo a tu proyecto.

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")

Obtén tu clave de APICopiar enlace del ancla

Copia tu clave de API desde el panel de Piloterr y guárdala en la variable de entorno PILOTERR_API_KEY, que el SDK lee por defecto. No la incluyas en el control de versiones.

Inicio rápidoCopiar enlace del ancla

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());

Trabajos asíncronosCopiar enlace del ancla

Cualquier llamada acepta is_async, útil más allá del límite de 60 segundos del servidor. La respuesta es entonces un job_id, y el SDK puede esperar a que termine el trabajo.

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()));

ErroresCopiar enlace del ancla

Una respuesta fuera de 2xx lanza un error de API con su estado y su mensaje. Consulta los códigos de estado para ver la lista completa.

try {
  client.amazonProduct(AmazonProductParams.builder().query("B09DFCB66S").build());
} catch (PiloterrApiException e) {
  System.err.println(e.status() + ": " + e.getMessage());
}

ReintentosCopiar enlace del ancla

Las solicitudes se reintentan hasta 3 veces tras un error de red, un 408, 500, 502, 503 o 504, o un límite de frecuencia del plan. Los errores de cuota por clave y los tiempos de espera del cliente no se reintentan. La espera empieza en 1 segundo y crece 1,5× en cada reintento, y una cabecera Retry-After tiene prioridad.

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 retries

Solicitudes por lotesCopiar enlace del ancla

Ejecuta muchas llamadas a la vez, 10 por defecto. Un fallo no detiene las demás.

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());
  }
}

Cualquier endpointCopiar enlace del ancla

request() llega a cualquier ruta, incluidos los endpoints publicados después de tu versión del SDK.

ApiResponse response = client.request("GET", "/v1/usage", Map.of());

Errores frecuentesCopiar enlace del ancla

• Poner la clave de API en el código front-end. Cualquiera podría leerla. Llama a la API desde tu servidor.
• Tratar todo 401 como una clave incorrecta. Un 401 también puede ser un límite de frecuencia: lee el mensaje. El SDK reintenta por ti los límites del plan.
• Reintentar un 402. Significa que no quedan créditos ni cuota, así que un reintento no puede funcionar. Consulta Créditos.
• Esperar solicitudes largas. Más allá de 60 segundos, usa el modo asíncrono como se muestra arriba en lugar de aumentar el tiempo de espera. Consulta Timeout.

EnlacesCopiar enlace del ancla

• Paquete: piloterr-java
• Código fuente: github.com/piloterr/piloterr-java
• Referencia de la API