Java

Das offizielle Java-SDK von Piloterr mit einer typisierten Methode pro Endpunkt und einem generischen request() für alles andere.

VoraussetzungenAnkerlink kopieren

• Java 17+

InstallationAnkerlink kopieren

Das Java-SDK ist nicht auf Maven Central verfügbar. Bauen Sie es aus dem Quellcode, um es in Ihrem lokalen Maven-Repository zu installieren, und fügen Sie es dann Ihrem Projekt hinzu.

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

API-Schlüssel erhaltenAnkerlink kopieren

Kopieren Sie Ihren API-Schlüssel aus dem Piloterr-Dashboard und legen Sie ihn in der Umgebungsvariable PILOTERR_API_KEY ab, die das SDK standardmäßig liest. Checken Sie ihn nicht in die Versionsverwaltung ein.

SchnellstartAnkerlink kopieren

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

Asynchrone JobsAnkerlink kopieren

Jeder Aufruf akzeptiert is_async, nützlich jenseits des Serverlimits von 60 Sekunden. Die Antwort ist dann eine job_id, und das SDK kann auf das Ende des Jobs warten.

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

FehlerAnkerlink kopieren

Eine Antwort außerhalb von 2xx löst einen API-Fehler mit Status und Meldung aus. Die vollständige Liste finden Sie unter Statuscodes.

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

WiederholungenAnkerlink kopieren

Anfragen werden bis zu 3-mal wiederholt nach einem Netzwerkfehler, einem 408, 500, 502, 503 oder 504 oder einem Ratenlimit des Tarifs. Kontingentfehler pro Schlüssel und clientseitige Timeouts werden nicht wiederholt. Die Wartezeit beginnt bei 1 Sekunde und wächst pro Wiederholung um das 1,5-Fache; ein Retry-After-Header hat Vorrang.

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

Batch-AnfragenAnkerlink kopieren

Führen Sie viele Aufrufe gleichzeitig aus, standardmäßig 10. Ein Fehler stoppt die anderen nicht.

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

Beliebiger EndpunktAnkerlink kopieren

request() erreicht jeden Pfad, auch Endpunkte, die nach Ihrer SDK-Version erschienen sind.

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

Häufige FehlerAnkerlink kopieren

• Den API-Schlüssel in Frontend-Code einbauen. Jeder könnte ihn lesen. Rufen Sie die API von Ihrem Server auf.
• Jeden 401 als falschen Schlüssel behandeln. Ein 401 kann auch ein Ratenlimit sein: Lesen Sie die Meldung. Das SDK wiederholt Tarif-Ratenlimits automatisch.
• Einen 402 wiederholen. Es sind keine Credits oder Kontingente mehr übrig, eine Wiederholung kann also nicht gelingen. Siehe Credits.
• Auf lange Anfragen warten. Nutzen Sie ab 60 Sekunden den asynchronen Modus wie oben gezeigt, statt das Timeout zu erhöhen. Siehe Timeout.

LinksAnkerlink kopieren

• Paket: piloterr-java
• Quellcode: github.com/piloterr/piloterr-java
• API-Referenz